Subgraph Explorer

Overview

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.

Quick Start

Starting the MCP Server

Before using subgraph exploration features, ensure the MCP server is running:

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

Note: The scripts default to ~/Workspace/subgraph-mcp as the project path. Set SUBGRAPH_MCP_PATH environment variable to override.

MCP Server Connection

The MCP server runs in SSE mode and exposes the following tools via HTTP:

Registry-based tools:

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

Ad-hoc tools:

• get_schema_by_url - Get schema from any GraphQL endpoint (no registry needed)
• execute_query_by_url - Execute query against any GraphQL endpoint (no registry needed)

To interact with the MCP server, use the WebFetch tool to make HTTP requests to the SSE endpoint at http://localhost:8000.

Core Workflows

1. Exploring Configured Subgraphs

When exploring subgraphs in the registry (subgraphs.json):

Step 1: List or Search

• Use list_subgraphs to see all available subgraphs
• Use search_subgraphs_by_keyword to find specific subgraphs by name/description

Step 2: Understand the Schema

• Use get_schema_by_id to retrieve the GraphQL schema
• Examine entity types, fields, and relationships
• Check get_query_examples_by_id for pre-built query templates
• Review get_subgraph_guidance_by_id for subgraph-specific tips

Step 3: Execute Queries

• Use execute_query_by_id to run GraphQL queries
• Start with simple queries and iterate
• Apply pagination for large result sets
• Reference references/graphql_patterns.md for common patterns

Step 4: Export Useful Queries

• Use scripts/export_query.py to save queries for project use
• Choose format: JavaScript, Python, GraphQL, or JSON

2. Ad-hoc Subgraph Exploration

For exploring subgraphs not in the registry:

Direct URL Access:

• Use get_schema_by_url with the GraphQL endpoint URL
• Optionally provide auth_header if authentication is required
• Use execute_query_by_url to run queries directly

Example workflow:

1. Get schema: get_schema_by_url(url="https://example.com/graphql")
2. Analyze available entities and fields
3. Build query based on schema
4. Execute: execute_query_by_url(url="https://example.com/graphql", query="...", variables={...})

3. Query Development Process

Iterative Query Building:

1. Start Simple: Query a single entity to understand data structure

   query SimpleQuery {
     entity(id: "0x123") {
       id
       name
     }
   }
   

2. Add Fields: Gradually add more fields as needed

   query ExpandedQuery {
     entity(id: "0x123") {
       id
       name
       timestamp
       relatedData {
         field1
         field2
       }
     }
   }
   

3. Apply Filters: Use where clauses for specific criteria

   query FilteredQuery($minValue: String!) {
     entities(where: { value_gte: $minValue }, first: 100) {
       id
       value
       timestamp
     }
   }
   

4. Optimize: Use aggregated fields instead of large arrays

   • Prefer: contract.holders (pre-calculated count)
   • Avoid: Counting all tokens manually

Reference: See references/graphql_patterns.md for comprehensive query patterns including pagination, filtering, aggregation, and performance optimization.

Exporting Queries

Use the export utility to save discovered queries for project integration:

JavaScript/TypeScript Export

python3 scripts/export_query.py queries/getLatestSwaps.js --format js --name GetLatestSwaps --description "Fetch latest DEX swaps"

Then paste your GraphQL query when prompted.

Output:

/**
 * Fetch latest DEX swaps
 */
export const GetLatestSwaps = `
  query GetLatestSwaps($first: Int!) {
    swaps(first: $first, orderBy: timestamp, orderDirection: desc) {
      id
      timestamp
      amountUSD
      pair {
        token0 { symbol }
        token1 { symbol }
      }
    }
  }
`;

Python Export

python3 scripts/export_query.py queries/get_latest_swaps.py --format py --name get_latest_swaps

GraphQL File Export

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

JSON Export (with metadata)

python3 scripts/export_query.py queries/latest_swaps.json --format json --name GetLatestSwaps --variables '{"first": 100}'

Understanding Subgraph Data

Common Entity Types

DEX/Trading Subgraphs:

• Swap - Individual trade transactions
• Pair - Trading pairs with liquidity and volume
• Token - Token information and metadata
• DayData / PairDayData - Aggregated daily metrics

NFT Subgraphs:

• ERC721Transfer / ERC1155Transfer - NFT transfer events
• Account - User accounts with balances
• ERC721Token / ERC1155Token - Individual NFT tokens
• ERC721Contract - NFT collection contracts

Common Patterns:

• Most entities have id, timestamp, and blockNumber fields
• Use relationship fields (e.g., pair { token0 { symbol } }) to navigate connections
• Aggregated fields (e.g., totalSupply, holders) provide pre-calculated stats

Data Considerations

Time-based Data:

• Daily aggregates typically reset at midnight UTC
• For "today's" data, consider querying both current day and previous day
• Calculate partial day metrics: (yesterday_value * hours_passed / 24) + today_value

Pagination:

• Maximum first parameter is typically 1000, recommended 100
• Use skip for offset-based pagination
• Use cursor-based pagination (id_gt) for large datasets

Performance:

• Avoid deep nesting of relationships
• Use aggregated fields when available
• Apply specific filters to reduce result sets
• Request only needed fields, not entire objects

Troubleshooting

MCP Server Issues

Container won't start:

• Check if ports 8000 or 9091 are already in use
• Verify subgraphs.json exists in the subgraph-mcp directory
• View logs: docker logs subgraph-mcp-server

Server not responding:

• Run: bash scripts/check_mcp_status.sh
• Verify Docker is running
• Check firewall settings for localhost access

Configuration errors:

• Verify SUBGRAPH_MCP_PATH points to correct directory
• Ensure subgraphs.json is valid JSON
• Check subgraph URLs are accessible

Query Issues

Schema introspection fails:

• Verify the subgraph endpoint is accessible
• Check authentication headers if required
• Ensure the endpoint is a valid GraphQL API

Query timeout:

• Simplify the query (reduce nesting, fewer fields)
• Add more specific filters
• Reduce first parameter value
• Use pagination for large datasets

Type errors:

• Check field types in schema (String vs Int vs BigInt)
• Ensure variable types match schema requirements
• Use quotes for String types in variables: {"id": "0x123"}

Empty results:

• Verify entity IDs are correct (case-sensitive)
• Check filter conditions aren't too restrictive
• For time-based queries, verify timestamp format (usually Unix seconds)
• Confirm data exists in the subgraph (check subgraph sync status)

Resources

scripts/

Docker Management:

• start_mcp_server.sh - Start the MCP server in Docker
• stop_mcp_server.sh - Stop the MCP server
• check_mcp_status.sh - Check server status and health

Query Export:

• export_query.py - Export GraphQL queries to various formats (JS, Python, GraphQL, JSON)

references/

• graphql_patterns.md - Comprehensive guide to GraphQL query patterns for subgraphs
  • Pagination strategies
  • Filtering patterns
  • Aggregation techniques
  • Performance optimization
  • Common query scenarios

Tips

• Always start with schema exploration - Use get_schema_by_id or get_schema_by_url first
• Check for query examples - Use get_query_examples_by_id for configured subgraphs
• Read subgraph guidance - Use get_subgraph_guidance_by_id for subgraph-specific tips
• Test queries incrementally - Build complex queries step by step
• Export working queries - Save successful queries for reuse in projects
• Monitor performance - Check metrics endpoint (http://localhost:9091/metrics) for server health
• Use aggregated data - Prefer pre-calculated fields over manual aggregation
• Consider UTC timezone - Daily data typically resets at midnight UTC