Substrate MCP Server

Un servidor del Protocolo de Contexto de Modelo (MCP) para cadenas de bloques de Substrate, escrito en Rust.

GitHub
12
Prueba este MCPPatrocinado

Documentación

Substrate MCP Server

MIT License Rust

Trust Score

Un servidor de Model Context Protocol (MCP) para blockchains Substrate, escrito en Rust. Este proyecto expone operaciones dinámicas de blockchain Substrate (consulta de saldos, bloques, pallets, almacenamiento, eventos y más) a través del protocolo MCP, y es totalmente configurable mediante variables de entorno.

Diseñado para interactuar con la crate subxt.

✨ Características

  • Consultar saldos de cuentas y almacenamiento dinámicamente
  • Listar pallets y sus entradas
  • Obtener y filtrar eventos y extrínsecos
  • Enviar y observar transacciones firmadas dinámicas
  • Acceder a información del sistema y de bloques
  • Llamadas RPC personalizadas a nodos Substrate

🚀 Casos de Uso Potenciales

  1. Operaciones de Blockchain Impulsadas por IA

    • Integrar con LLMs (como Cursor o Claude) para permitir a los usuarios hacer preguntas en lenguaje natural (por ejemplo, "¿Cuál fue la última transferencia de Alice?"), que se traducen en llamadas a herramientas MCP.
    • Construir un chatbot que pueda responder preguntas, consultar saldos o explicar actividad en cadena usando tu servidor MCP como backend.
    • Usar el servidor MCP para proporcionar actualizaciones en vivo de la actividad en cadena, como cambios de saldo o estados de transacciones, a herramientas de desarrollo como VSCode, Cursor, Claude Code, etc.

  2. Paneles Personalizados y Monitoreo

    • Crear paneles personalizados y sistemas de monitoreo para tu blockchain Substrate
    • Mostrar datos y análisis en tiempo real de tus operaciones de blockchain
    • Configurar alertas y notificaciones para eventos críticos
    • Usar agentes de IA para detectar actividad sospechosa analizando eventos y extrínsecos en tiempo real.

🛠️ Requisitos

  • Rust
  • Acceso a un endpoint de nodo Substrate (WebSocket)
  • Un par de claves de firma válido (en hexadecimal)
  • Archivo de metadatos de runtime para tu cadena objetivo (ver abajo para nombres y ubicación)

📦 Instalación

Clona el repositorio y compila:

git clone https://github.com/ThomasMarches/substrate-mcp-rs.git
cd substrate-mcp-rs
cargo build --release

⚙️ Configuración

Crea un archivo .env en la raíz del proyecto con las siguientes variables:

# WebSocket endpoint for the Substrate node
RPC_URL=wss://your-node-url.example.com

# Signing keypair as hex (32 bytes, e.g. output of subkey inspect-key --scheme Sr25519)
SIGNING_KEYPAIR_HEX=your_signing_keypair_hex_here

Generando un Par de Claves de Firma

Puedes generar un par de claves y obtener la semilla secreta en hexadecimal usando subkey:

subkey generate --scheme Sr25519 --output-type Json

Usa el campo secretSeed (elimina el prefijo 0x si está presente) para SIGNING_KEYPAIR_HEX.

Obteniendo y Colocando los Metadatos del Runtime

Exporta los metadatos del runtime desde tu nodo y colócalos en artifacts/metadata.scale:

subxt metadata -f bytes > artifacts/metadata.scale

Importante: El archivo debe llamarse metadata.scale y estar ubicado en el directorio artifacts/ antes de compilar. La compilación fallará si este archivo falta o tiene un nombre incorrecto.

▶️ Uso

Para iniciar el servidor MCP:

cargo run --release

El servidor se iniciará y escuchará solicitudes MCP a través de stdio.

🖇️ Integración con Cursor

Para usar este servidor MCP con Cursor, debes agregarlo a tu configuración MCP de Cursor. Esto permite que Cursor descubra e interactúe con tu servidor MCP de Substrate.

  1. Compila tu servidor en modo release:

    cargo build --release

  2. Localiza la ruta al binario compilado (típicamente target/release/substrate-mcp-rs).

  3. En tu archivo .cursor/mcp.json del proyecto (o global), agrega una entrada para tu servidor. Por ejemplo:

    {
  "mcpServers": {
    "substrate-mcp-rs": {
      "command": "$PROJECT_ROOT_ABSOLUTE_PATH/target/release/substrate-mcp-rs",
      "args": []
    }
  }
}
    • Reemplaza la ruta command con la ruta absoluta a tu binario compilado si difiere.

  4. Reinicia Cursor. Ahora debería detectar y conectarse a tu servidor MCP de Substrate, haciendo que sus herramientas estén disponibles para su uso.

Para más detalles, consulta la documentación de Cursor o la introducción al Model Context Protocol.

🧰 Herramientas Disponibles

El servidor expone un conjunto de herramientas para interactuar con una blockchain Substrate, incluyendo:

  • query_balance: Obtener el saldo de una cuenta
  • list_pallets: Listar todos los pallets en el runtime
  • list_pallet_entries: Listar todas las entradas de almacenamiento de un pallet
  • dynamic_runtime_call: Ejecutar una llamada de API del runtime
  • send_dynamic_signed_transaction: Construir, firmar y enviar una transacción
  • query_storage: Consultar almacenamiento por pallet y entrada
  • get_latest_events: Obtener todos los eventos del último bloque
  • find_events: Encontrar eventos específicos por pallet y variante
  • get_latest_block: Obtener detalles sobre el último bloque
  • get_block_by_hash: Obtener detalles de un bloque por hash
  • find_extrinsics: Encontrar extrínsecos en el último bloque
  • get_system_info: Obtener información del sistema vía RPC
  • custom_rpc: Hacer una llamada RPC personalizada

Consulta src/tooling/substrate.rs para detalles completos y parámetros.

🗂️ Estructura del Proyecto

  • src/main.rs: Punto de entrada, configura el registro y inicia el servidor MCP
  • src/tooling/: Contiene la implementación de las herramientas de Substrate
  • artifacts/: Coloca tu archivo de metadatos del runtime aquí como metadata.scale (requerido antes de compilar)

📈 Próximos Pasos y Objetivos

  • Agregar pruebas E2E
  • Agregar pruebas unitarias
  • Agregar más herramientas

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor, abre issues o pull requests. Para cambios más grandes, abre un issue primero para discutir tu propuesta.

  • Sigue las mejores prácticas de Rust y asegúrate de que el código esté documentado
  • Ejecuta cargo fmt y cargo clippy antes de enviar
  • Agrega pruebas cuando sea posible

📄 Licencia

MIT