zhongwei/gh-nschwermann-claude-tools-subgraph-explorer

Fork 0

Files

Zhongwei Li acd2279239 Initial commit

2025-11-30 08:44:39 +08:00

4.5 KiB

Raw Blame History

Subgraph Explorer Skill

A Claude Code skill for exploring and querying blockchain subgraphs through a private MCP server running in Docker.

Description

This skill enables exploration and querying of blockchain subgraphs through a private MCP server. It provides tools for managing the Docker-based server, exploring GraphQL schemas, executing queries against configured subgraphs, and exporting discovered queries for project integration.

Features

Docker Management: Start, stop, and check status of the MCP server
Schema Exploration: Introspect GraphQL schemas from subgraphs
Query Execution: Execute GraphQL queries against configured or ad-hoc subgraph endpoints
Query Export: Save discovered queries in multiple formats (JS, Python, GraphQL, JSON)
Comprehensive Patterns: Reference guide with common GraphQL query patterns for blockchain data

Use Cases

Exploring NFT transfers and ownership data
Querying DEX swaps and trading volume
Analyzing DeFi protocol metrics
Examining subgraph schemas and entities
Exporting queries for project integration

Requirements

Docker and Docker Compose
Private Subgraph MCP Server (https://github.com/nschwermann/subgraph-mcp)
Python 3 (for query export utility)

Installation

As a Claude Code Skill

Download the subgraph-explorer.zip file
Install via Claude Code plugin system, or
Extract to your Claude skills directory

From Source

# Clone or download this repository
git clone <repository-url>

# The skill is ready to use
# Scripts are in scripts/
# Reference docs are in references/
# Main instructions are in SKILL.md

Quick Start

Starting the MCP Server

bash scripts/start_mcp_server.sh

This starts the Docker container with:

SSE endpoint: http://localhost:8000 (for MCP communication)
Metrics endpoint: http://localhost:9091/metrics (for monitoring)

Check Server Status

bash scripts/check_mcp_status.sh

Stop the Server

bash scripts/stop_mcp_server.sh

Exporting Queries

Export discovered GraphQL queries for project use:

JavaScript/TypeScript

python3 scripts/export_query.py queries/myQuery.js --format js --name MyQuery

Python

python3 scripts/export_query.py queries/myQuery.py --format py --name my_query

GraphQL

python3 scripts/export_query.py queries/myQuery.graphql --format graphql

JSON

python3 scripts/export_query.py queries/myQuery.json --format json --name MyQuery

Structure

subgraph-explorer/
├── SKILL.md                           # Main skill documentation
├── scripts/
│   ├── start_mcp_server.sh           # Start Docker MCP server
│   ├── stop_mcp_server.sh            # Stop Docker MCP server
│   ├── check_mcp_status.sh           # Check server status
│   └── export_query.py               # Export queries to various formats
└── references/
    └── graphql_patterns.md           # GraphQL query patterns reference

Configuration

The scripts default to ~/Workspace/subgraph-mcp as the MCP server project path. Override by setting the SUBGRAPH_MCP_PATH environment variable:

export SUBGRAPH_MCP_PATH=/path/to/your/subgraph-mcp
bash scripts/start_mcp_server.sh

MCP Server Tools

The skill works with the following MCP server tools:

Registry-based:

list_subgraphs - List all configured subgraphs
search_subgraphs_by_keyword - Search subgraphs by keyword
get_schema_by_id - Get GraphQL schema for a subgraph
execute_query_by_id - Execute query against a subgraph
get_query_examples_by_id - Get query examples
get_subgraph_guidance_by_id - Get subgraph-specific guidance

Ad-hoc:

get_schema_by_url - Get schema from any GraphQL endpoint
execute_query_by_url - Execute query against any GraphQL endpoint

Documentation

See SKILL.md for comprehensive documentation including:

Core workflows for subgraph exploration
Query development process
Data considerations and best practices
Troubleshooting guide
Tips and tricks

See references/graphql_patterns.md for:

Pagination strategies
Filtering and aggregation patterns
Performance optimization techniques
Common query scenarios

License

MIT

Private Subgraph MCP Server - The MCP server this skill interacts with
Claude Code - The AI coding assistant platform

4.5 KiB Raw Blame History