Subgraph MCP Server

Permite que los LLMs interactúen con Subgraphs disponibles en The Graph Network.

GitHub
8
Prueba este MCPPatrocinado

Documentación

Subgraph MCP Server

Un servidor de Model Context Protocol (MCP) que permite a los LLM interactuar con Subgraphs disponibles en The Graph Network.

Características

  • Obtener el esquema GraphQL de cualquier subgraph/deployment
  • Ejecutar consultas GraphQL contra cualquier subgraph/deployment
  • Encontrar los deployments de subgraph más importantes para una dirección de contrato en una cadena específica
  • Buscar subgraphs por palabra clave
  • Obtener el volumen de consultas de 30 días para deployments de subgraph
  • Soporta recursos, herramientas y prompts de MCP
  • Puede ejecutarse en modo STDIO o como servidor SSE (Server-Sent Events)

Uso

El servidor subgraph-mcp ofrece dos formas principales de interactuar con The Graph Network:

  1. Conexión al Servicio MCP Remoto Alojado (Recomendado para la mayoría de usuarios)
  2. Compilación y Ejecución del Servidor Localmente

Conexión al Servicio MCP Remoto Alojado

Esta es la forma más rápida de comenzar. Puedes configurar tu cliente MCP (por ejemplo, Claude Desktop) para conectarte a nuestro servicio subgraph-mcp alojado.

Requisitos

  • Una clave de API Gateway para The Graph Network.

Configuración

Añade lo siguiente al archivo de configuración de tu cliente (por ejemplo, claude_desktop_config.json):

{
  "mcpServers": {
    "subgraph-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "https://subgraphs.mcp.thegraph.com/sse"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_GATEWAY_API_KEY" // <-- Replace with your actual key
      }
    }
  }
}

Reemplaza YOUR_GATEWAY_API_KEY con tu clave de API Gateway real. Después de añadir la configuración, reinicia tu cliente MCP.

Una vez configurado, puedes ir directamente a las secciones "Herramientas Disponibles" o "Consultas en Lenguaje Natural" para aprender a interactuar con el servicio.

Compilación y Ejecución del Servidor Localmente

Esta opción es para usuarios que prefieren compilar, ejecutar y potencialmente modificar el servidor en su propia máquina.

Requisitos (para Ejecución Local)

  • Rust (se recomienda la última versión estable: 1.75+).
    Puedes instalarlo usando el siguiente comando en macOS, Linux u otros sistemas similares a Unix: \ 
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    Sigue las instrucciones en pantalla. Para otras plataformas, consulta la guía oficial de instalación de Rust.
  • Una clave de API Gateway para The Graph Network.

Instalación (para Ejecución Local)

# Clone the repository
git clone git@github.com:graphops/subgraph-mcp.git
cd subgraph-mcp

# Build the project
cargo build --release

Configuración (para Ejecución Local)

Añade lo siguiente al archivo de configuración de tu cliente (por ejemplo, claude_desktop_config.json):

{
  "mcpServers": {
    "subgraph-mcp": {
      "command": "/path/to/your/subgraph-mcp/target/release/subgraph-mcp", // <-- Replace this with the actual path!
      "env": {
        "GATEWAY_API_KEY": "YOUR_GATEWAY_API_KEY" // <-- Replace with your actual key
      }
    }
  }
}

Debes reemplazar /path/to/subgraph-mcp con la ruta absoluta al binario compilado que construiste en el paso de Instalación.

Encontrar la ruta del comando:

Después de ejecutar cargo build --release, el ejecutable normalmente estará ubicado en target/release/subgraph-mcp dentro de tu directorio de proyecto (subgraph-mcp).

  1. Navega a tu directorio subgraph-mcp en la terminal.
  2. Ejecuta pwd (imprimir directorio de trabajo) para obtener la ruta completa al directorio subgraph-mcp.
  3. Combina la salida de pwd con /target/release/subgraph-mcp.

Por ejemplo, si pwd genera /Users/user/subgraph-mcp, la ruta completa del comando sería /Users/user/subgraph-mcp/target/release/subgraph-mcp.

Después de añadir la configuración, reinicia Claude Desktop.

Configuración de Tiempo de Espera de Solicitudes (para Ejecución Local)

El servidor incluye ajustes de tiempo de espera configurables para solicitudes HTTP al Gateway de The Graph. Esto ayuda a manejar consultas GraphQL complejas que pueden tardar más en ejecutarse.

Comportamiento Predeterminado

Por defecto, el servidor utiliza un tiempo de espera de 120 segundos para todas las solicitudes HTTP al Gateway de The Graph. Esto proporciona un buen equilibrio entre permitir que las consultas complejas se completen y evitar bloqueos indefinidos.

Configuración de Tiempo de Espera Personalizado

Puedes personalizar el tiempo de espera de varias formas:

Opción 1: Variable de Entorno (Recomendado)

Establece la variable de entorno SUBGRAPH_REQUEST_TIMEOUT_SECONDS:

export SUBGRAPH_REQUEST_TIMEOUT_SECONDS=300  # 5 minutes

Para la configuración de Claude Desktop:

{
  "mcpServers": {
    "subgraph-mcp": {
      "command": "/path/to/subgraph-mcp",
      "env": {
        "GATEWAY_API_KEY": "YOUR_GATEWAY_API_KEY",
        "SUBGRAPH_REQUEST_TIMEOUT_SECONDS": "300"
      }
    }
  }
}

Opción 2: Configuración Programática (para desarrolladores)

Al crear aplicaciones con la biblioteca del servidor:

use std::time::Duration;
use subgraph_mcp::SubgraphServer;

// Use default timeout (120 seconds)
let server = SubgraphServer::new();

// Use custom timeout
let server = SubgraphServer::with_timeout(Duration::from_secs(300));

Nota: Los tiempos de espera muy largos (>5 minutos) deben usarse con precaución, ya que pueden afectar la capacidad de respuesta general de la aplicación.

Importante: Claude Desktop puede no utilizar automáticamente los recursos del servidor. Para garantizar un funcionamiento adecuado, añade manualmente el recurso Subgraph Server Instructions a tu contexto de chat haciendo clic en el menú de contexto y añadiendo el recurso.

Herramientas Disponibles

El servidor expone las siguientes herramientas:

  • search_subgraphs_by_keyword: Busca subgraphs por palabra clave en sus nombres mostrados. Ordenados por señal. Devuelve los 10 mejores resultados si el total de resultados es ≤ 100, o la raíz cuadrada del total en caso contrario.
  • get_deployment_30day_query_counts: Obtiene el recuento agregado de consultas de los últimos 30 días para múltiples deployments de subgraph (usando sus hashes IPFS), ordenados por recuento de consultas.
  • get_schema_by_deployment_id: Obtiene el esquema GraphQL para un deployment de subgraph específico usando su ID de deployment (por ejemplo, 0x...).
  • get_schema_by_subgraph_id: Obtiene el esquema GraphQL para el deployment actual asociado con un ID de subgraph (por ejemplo, 5zvR82...).
  • get_schema_by_ipfs_hash: Obtiene el esquema GraphQL para un deployment de subgraph específico usando el hash IPFS de su manifiesto (por ejemplo, Qm...).
  • execute_query_by_deployment_id: Ejecuta una consulta GraphQL contra un deployment de subgraph específico e inmutable usando su ID de deployment (por ejemplo, 0x...).
  • execute_query_by_subgraph_id: Ejecuta una consulta GraphQL contra el deployment más reciente asociado con un ID de subgraph (por ejemplo, 5zvR82...).
  • execute_query_by_ipfs_hash: Ejecuta una consulta GraphQL contra un deployment de subgraph específico e inmutable usando su hash IPFS (por ejemplo, Qm...).
  • get_top_subgraph_deployments: Obtiene los 3 mejores deployments de subgraph que indexan una dirección de contrato dada en una cadena específica, ordenados por tarifas de consulta.

Consultas en Lenguaje Natural

Una vez conectado a un LLM con este servidor MCP, puedes hacer preguntas en lenguaje natural.

Importante: Claude Desktop puede no utilizar automáticamente los recursos del servidor. Para garantizar un funcionamiento adecuado, añade manualmente el recurso Subgraph Server Instructions a tu contexto de chat haciendo clic en el menú de contexto y añadiendo el recurso.

Ejemplo de uso en Claude (u otros clientes MCP), asumiendo que añadiste Subgraph Server Instructions a tu prompt:

User: List the 20 most recently registered .eth names.

Assistant (after `search_subgraphs_by_keyword`, `get_deployment_30day_query_counts` and other tool usage):
Perfect! I've successfully retrieved the 20 most recently registered .eth names using the ENS subgraph, which has 68.1 million queries in the last 30 days, making it the most active and reliable source for ENS data.
Here are the 20 most recently registered .eth names:

...

El LLM automáticamente:

  1. Seguirá las Instrucciones del Servidor de Subgraph.
  2. Usará search_subgraphs_by_keyword para encontrar subgraphs candidatos.
  3. Usará get_deployment_30day_query_counts para verificar la actividad y ayudar en la selección.
  4. Usará get_top_subgraph_deployments si se proporciona una dirección de contrato.
  5. Obtendrá y comprenderá el esquema del subgraph usando la herramienta get_schema_by_* apropiada.
  6. Convertirá tu pregunta en una consulta GraphQL apropiada.
  7. Ejecutará la consulta usando la herramienta execute_query_by_* correcta según el tipo de identificador y el deployment activo confirmado.
  8. Presentará los resultados en un formato legible.

Prompts

El servidor proporciona prompts predefinidos para la mayoría de las herramientas (como se puede descubrir a través de list_prompts de MCP):

  • get_schema_by_deployment_id: Obtener el esquema para un ID de deployment.
  • get_schema_by_subgraph_id: Obtener el esquema para un ID de subgraph.
  • get_schema_by_ipfs_hash: Obtener el esquema para un hash IPFS.
  • execute_query_by_deployment_id: Ejecutar una consulta GraphQL contra un ID de deployment.
  • execute_query_by_subgraph_id: Ejecutar una consulta GraphQL contra un ID de subgraph.
  • execute_query_by_ipfs_hash: Ejecutar una consulta GraphQL contra un hash IPFS.
  • get_top_subgraph_deployments: Obtener los mejores subgraphs para un contrato en una cadena específica.

Recursos

El servidor expone un recurso:

  • graphql://subgraph: Proporciona las Subgraph Server Instructions detalladas utilizadas por el LLM, incluyendo el flujo de trabajo para diferentes objetivos de usuario (búsqueda de direcciones, encontrar subgraphs para un contrato, consultar por ID, obtener esquema) y notas de uso importantes.

A continuación se muestra una referencia de las Subgraph Server Instructions:

**Interacting with The Graph Subgraphs**
**IMPORTANT: ALWAYS verify query volumes using `get_deployment_30day_query_counts` for any potential subgraph candidate *before* selecting or querying it. This step is NON-OPTIONAL. Failure to do so may result in using outdated or irrelevant data.**
**Follow this sequence strictly:**
1.  **Analyze User Request:**
    *   Identify the **protocol name** (e.g., "Uniswap", "Aave", "ENS").
    *   Note any specific **version** or **blockchain network** mentioned by the user.
    *   Determine the **goal**: Query data? Get schema?
2.  **Initial Search & Preliminary Analysis:**
    *   Use `search_subgraphs_by_keyword` with the most generic term for the protocol (e.g., if "Uniswap v3 on Ethereum", initially search only for "Uniswap").
    *   Examine `displayName` and other metadata in the search results for version and network information.
3.  **Mandatory Query Volume Check & Clarification (If Needed):**
    *   **ALWAYS** extract the IPFS hashes (`ipfsHash`) for all potentially relevant subgraphs identified in Step 2.
    *   **ALWAYS** use `get_deployment_30day_query_counts` for these IPFS hashes.
    *   **If Ambiguous (Multiple Versions/Chains with significant volume):**
        *   Present a summary to the user, **including the 30-day query counts for each option**. For example: "I found several Uniswap subgraphs. Uniswap v3 on Ethereum is the most active (X queries last 30 days). I also see Uniswap v2 on Ethereum (Y queries) and Uniswap v3 on Arbitrum (Z queries). Which specific version and network are you interested in?"
    *   **If Still Unclear (Information Missing and Not Inferable even with query volumes):**
        *   If version/chain information is genuinely missing from search results and user input, and query volumes don't offer a clear path (e.g. all relevant subgraphs have very low or no volume), ask for clarification directly. Example: "I found several subgraphs for 'ExampleProtocol', but none have significant query activity. Could you please specify the version and blockchain network you're interested in?"
    *   **Do NOT proceed to Step 4 without completing this query volume verification.**
4.  **Select Final Subgraph (Post Query Volume Check & Clarification):**
    *   After the keyword search, mandatory query volume check, and any necessary clarification, you should have a clear target protocol, version, and network.
    *   Identify all candidate subgraphs from your Step 2 `search_subgraphs_by_keyword` results that match these clarified criteria.
    *   **If there is more than one such matching subgraph:**
        *   You should have already fetched their query counts in Step 3.
        *   **Select the subgraph with the highest `total_query_count`** among them.
    *   **If only one subgraph precisely matches the criteria**, that is your selected subgraph.
    *   When presenting your chosen subgraph or asking for final confirmation before querying, **ALWAYS state its 30-day query volume** to demonstrate this check has been performed. For example: "I've selected the 'Uniswap v3 Ethereum' subgraph, which has X queries in the last 30 days. Shall I proceed to get its schema?"
    *   If the selected subgraph's query count is very low (and this wasn't already discussed during clarification), briefly inform the user.
5.  **Execute Action Using the Identified Subgraph:**
    *   **Identify the ID Type:** (Subgraph ID, Deployment ID, or IPFS Hash - note that `search_subgraphs_by_keyword` returns `id` for Subgraph ID and `ipfsHash` for current deployment's IPFS hash).
    *   **Determine the Correct Tool based on Goal & ID Type:**
        *   **Goal: Query Data**
            *   Subgraph ID (`id` from search) → `execute_query_by_subgraph_id`
            *   Deployment ID (0x...) → `execute_query_by_deployment_id`
            *   IPFS Hash (`ipfsHash` from search) → `execute_query_by_ipfs_hash`
        *   **Goal: Get Schema**
            *   Subgraph ID → `get_schema_by_subgraph_id`
            *   Deployment ID → `get_schema_by_deployment_id`
            *   IPFS Hash → `get_schema_by_ipfs_hash`
    *   **Write Clean GraphQL Queries:** Simple structure, omit 'variables' if unused, include only essential fields.
**Special Case: Contract Address Lookup**
*   ONLY when a user explicitly provides a **contract address** (0x...) AND asks for subgraphs related to it:
    *   Identify the blockchain network for the address (ask user if unclear).
    *   Use `get_top_subgraph_deployments` with the provided contract address and chain name.
    *   Process and use the resulting IPFS hashes as needed. **Crucially, before using any of these IPFS hashes for querying, first use `get_deployment_30day_query_counts` with their IPFS hashes to verify recent activity.**
**ID Type Reference:**
*   **Subgraph ID**: Typically starts with digits and letters (e.g., 5zvR82...)
*   **Contract Address**: A shorter hexadecimal string, typically 42 characters long including the "0x" prefix (e.g., 0x1a3c9b1d2f0529d97f2afc5136cc23e58f1fd35b).
*   **Deployment ID**: A longer hexadecimal string, typically 66 characters long including the "0x" prefix (e.g., 0xc5b4d246cf890b0b468e005224622d4c85a8b723cc0b8fa7db6d1a93ddd2e5de). Use length to distinguish from a Contract Address.
*   **IPFS Hash**: Typically starts with Qm... For the purpose of `get_deployment_30day_query_counts`, use the \'IPFS Hash\' (Qm...).
*   Note `search_subgraphs_by_keyword` and `get_top_subgraph_deployments` returns `ipfsHash`.

**Best Practices:**
*   When using GraphQL, if unsure about the structure, first get the schema to understand available entities and fields.
*   Create focused queries that only request necessary fields.
*   For paginated data, use appropriate limit parameters.
*   Use variables for dynamic values in queries.

Monitoreo

El servidor expone métricas de Prometheus para monitorear su rendimiento y comportamiento.

Endpoint de Métricas

Cuando se ejecuta en modo SSE, se inicia un servidor de métricas en un puerto separado.

  • Endpoint: /metrics
  • Puerto Predeterminado: 9091

Puedes configurar el puerto y el host del servidor de métricas usando las variables de entorno METRICS_PORT y METRICS_HOST.

Métricas Expuestas

Se exponen las siguientes métricas específicas de la aplicación:

  • mcp_tool_calls_total{tool_name, status}: Un contador para el número de llamadas a herramientas MCP.
    • tool_name: El nombre de la herramienta MCP que se está llamando (por ejemplo, get_schema_by_deployment_id).
    • status: El resultado de la llamada (success o error).
  • mcp_tool_call_duration_seconds{tool_name}: Un histograma de la duración de las llamadas a herramientas MCP.
  • gateway_requests_total{endpoint_type, status}: Un contador para solicitudes salientes al Gateway de The Graph.
    • endpoint_type: El tipo de consulta o endpoint al que se accede (por ejemplo, get_schema_by_deployment_id, subgraphs/id).
    • status: El resultado de la solicitud (success o error).
  • gateway_request_duration_seconds{endpoint_type}: Un histograma de la duración de las solicitudes al Gateway.

Adicionalmente, la biblioteca axum-prometheus proporciona métricas estándar de solicitudes HTTP para el propio servidor de métricas (con prefijo http_).

Solución de Problemas

Errores de Tiempo de Espera de Solicitudes

Si encuentras errores de "Request timed out" o "MCP error -32001", esto generalmente indica que las consultas GraphQL están tardando más que el tiempo de espera configurado en completarse.

Soluciones:

Si estás ejecutando tu propia instancia local del servidor:

  1. Aumenta el tiempo de espera usando la variable de entorno SUBGRAPH_REQUEST_TIMEOUT_SECONDS: 
    export SUBGRAPH_REQUEST_TIMEOUT_SECONDS=300  # 5 minutes

Si estás usando el servicio remoto alojado:

  1. Contacta con soporte - Los ajustes de tiempo de espera son gestionados por el servicio alojado y no pueden ser personalizados por los usuarios finales.

Para todos los usuarios:

  1. Comprueba la complejidad de la consulta - Las consultas muy complejas con grandes conjuntos de resultados pueden necesitar tiempos de espera más largos u optimización de la consulta.

  2. Verifica el estado del Gateway de The Graph - Los problemas ocasionales de tiempo de espera pueden deberse a problemas temporales de rendimiento del Gateway.

Tiempo de Espera Predeterminado: Las instancias locales del servidor utilizan un tiempo de espera de 120 segundos por defecto (aumentado desde 30 segundos en versiones anteriores). Los ajustes de tiempo de espera del servicio remoto alojado pueden diferir.

Problemas Comunes

  • "API key not found": Asegúrate de que la variable de entorno GATEWAY_API_KEY esté configurada correctamente
  • "Configuration error": Verifica que tu clave de API Gateway sea válida y tenga los permisos apropiados
  • Conexión rechazada: Verifica que el servidor esté ejecutándose y sea accesible en el puerto configurado

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

Licencia

Apache-2.0