Nimiq MCP Server

Nimiq MCP Server

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con la blockchain de Nimiq.

📖 Protocolo de Contexto de Modelo

Características

• 🚀 Dos opciones de despliegue: Acceso remoto sin configuración O instalación local
• 🔗 18 herramientas integrales para cuentas, transacciones, bloques, validadores y más
• 🤖 Protocolo MCP 2025-06-18: Especificación más reciente con funciones mejoradas
• 💬 Herramientas interactivas: Soporte de elicitación para experiencias de usuario guiadas
• ⚡ Opción remota: Sin necesidad de instalación - solo añade la URL a tu cliente MCP
• 🔧 Opción local: Control total con npx nimiq-mcp
• 🔍 Búsqueda avanzada: Búsqueda de texto completo en la documentación integral de Nimiq
• 📊 Cálculos mejorados: Calculadora interactiva de recompensas de staking con valores predeterminados inteligentes
• 🔒 Operaciones de solo lectura (el envío de transacciones no es compatible por seguridad)
• ✅ Validación de entrada: Validación integral de esquemas para todas las entradas de herramientas

Inicio Rápido

Elige una de dos opciones:

Opción 1: Acceso Remoto

Añade esto a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "nimiq": {
      "url": "https://nimiq-mcp.je-cf9.workers.dev/sse",
      "transport": "sse"
    }
  }
}

Opción 2: Instalación Local

Añade esto a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "nimiq": {
      "command": "npx",
      "args": ["nimiq-mcp"]
    }
  }
}

Comparación

Con Endpoint RPC Personalizado y Autenticación

{
  "mcpServers": {
    "nimiq": {
      "url": "https://nimiq-mcp.je-cf9.workers.dev/sse?rpc-url=https://your-rpc-endpoint.com&rpc-username=your-username&rpc-password=your-password",
      "transport": "sse"
    }
  }
}

{
  "mcpServers": {
    "nimiq": {
      "command": "npx",
      "args": [
        "nimiq-mcp",
        "--rpc-url",
        "https://your-rpc-endpoint.com",
        "--rpc-username",
        "your-username",
        "--rpc-password",
        "your-password"
      ]
    }
  }
}

Argumentos Disponibles

Herramientas y Recursos Disponibles

El servidor MCP proporciona herramientas y recursos integrales para interactuar con la blockchain de Nimiq:

Herramientas (18 disponibles)

Recursos (3 disponibles)

Parámetros de Herramientas

Cada herramienta acepta parámetros específicos:

• Herramientas de bloque: includeBody (booleano) para incluir detalles de transacciones
• Herramientas de dirección: address (cadena) para direcciones de Nimiq
• Herramientas de transacción: hash (cadena) para hashes de transacciones, max (número) para límites
• Herramientas de documentación: includeSchemas (booleano) para getRpcMethods para incluir esquemas detallados de parámetros/resultados
• Herramientas de búsqueda: query (cadena) para términos de búsqueda, limit (número) para controlar el recuento de resultados

Acceso a Recursos

Los recursos se acceden a través de su URI y no requieren parámetros:

• Recursos de documentación: Acceso a través de nimiq://docs/web-client, nimiq://docs/protocol o nimiq://docs/validators
• El contenido se devuelve como texto plano para un consumo óptimo por parte de LLMs
• Los clientes MCP pueden almacenar en caché el contenido de los recursos para mejorar el rendimiento

Respuestas de Ejemplo

Respuesta de Datos de Suministro

{
  "total": 210000000000000,
  "vested": 0,
  "burned": 0,
  "max": 210000000000000,
  "initial": 25200000000000,
  "staking": 100000000000,
  "minted": 1000000000,
  "circulating": 25200000000000,
  "mined": 0,
  "updatedAt": "2025-01-20T12:00:00.000Z"
}

Respuesta de Datos de Bloque

{
  "blockNumber": 21076071,
  "block": {
    "hash": "90e2ba0a831eec477bca1a26ba8c5e2b3162b5d042667828c4db0f735247d41e",
    "number": 21076071,
    "timestamp": 1749486768481,
    "parentHash": "b4fae3fc846ac13bfc62aa502c8683e25e92616d987f3f642b9cb57da73b6392",
    "type": "micro",
    "producer": {
      "slotNumber": 305,
      "validator": "NQ51 LM8E Q8LS 53TX GGDG 26M4 VX4Y XRE2 8JDT"
    }
  },
  "timestamp": "2025-06-09T16:32:49.055Z",
  "network": "mainnet"
}

Respuesta de Búsqueda en Documentación

{
  "query": "validator staking",
  "totalResults": 3,
  "results": [
    {
      "title": "Validator Setup",
      "content": "To become a validator in Nimiq, you need to stake NIM tokens...",
      "section": "Validators",
      "score": 0.95,
      "snippet": "...validator in Nimiq, you need to stake NIM tokens and run validator software..."
    },
    {
      "title": "Staking Rewards",
      "content": "Validators earn rewards for producing blocks and validating transactions...",
      "section": "Economics",
      "score": 0.87,
      "snippet": "...earn rewards for producing blocks and validating transactions. Staking rewards..."
    }
  ],
  "searchedAt": "2025-01-20T12:00:00.000Z"
}

Ejemplos de Uso

Configuración de Claude Desktop

Opción 1: Remoto (Configuración Cero)

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "nimiq": {
      "url": "https://nimiq-mcp.je-cf9.workers.dev/sse",
      "transport": "sse"
    }
  }
}

Opción 2: Instalación Local

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "nimiq": {
      "command": "npx",
      "args": ["nimiq-mcp"]
    }
  }
}

Con Configuración Local Personalizada

{
  "mcpServers": {
    "nimiq": {
      "command": "npx",
      "args": [
        "nimiq-mcp",
        "--rpc-url",
        "https://rpc.nimiqwatch.com"
      ]
    }
  }
}

En Aplicaciones Web

Accede al servidor remoto directamente a través de HTTP:

// Connect to the remote MCP server
const mcpClient = new SSEClientTransport(
  new URL('https://nimiq-mcp.je-cf9.workers.dev/sse')
)

En Otros Clientes MCP

El servidor sigue la especificación MCP y se puede usar con cualquier cliente compatible con MCP:

Instalación local:

npx nimiq-mcp

Acceso remoto:

• Endpoint de Herramientas: https://nimiq-mcp.je-cf9.workers.dev/tools
• Endpoint de Información: https://nimiq-mcp.je-cf9.workers.dev/info
• Verificación de Salud: https://nimiq-mcp.je-cf9.workers.dev/health
• Interfaz Web: https://nimiq-mcp.je-cf9.workers.dev/

Desarrollo

Desarrollo Local

# Install dependencies
pnpm install

# Run linting
pnpm run lint

# Fix linting issues
pnpm run lint:fix

# Build for production
pnpm run build

# Test the server manually
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

Desarrollo de Cloudflare Workers

# Install dependencies including Wrangler
pnpm install

# Start local development server
pnpm run dev:worker

# Build and test worker deployment
pnpm run build:worker

# Deploy to Cloudflare
pnpm run deploy

Despliegue en Cloudflare Workers

Consulta la Guía de Despliegue completa para obtener instrucciones detalladas.

Pasos rápidos de despliegue:

1. Configura una cuenta de Cloudflare y obtén un token de API
2. Configura los secretos de GitHub (para despliegue automático):
   • CLOUDFLARE_API_TOKEN
   • CLOUDFLARE_ACCOUNT_ID
3. Haz push a la rama principal - despliegue automático a través de GitHub Actions
4. Configura los secretos de producción (opcional):

   wrangler secret put NIMIQ_RPC_URL
   wrangler secret put NIMIQ_RPC_USERNAME
   wrangler secret put NIMIQ_RPC_PASSWORD
   

El worker estará disponible en: https://nimiq-mcp.je-cf9.workers.dev

Arquitectura

El servidor MCP está construido usando:

• @modelcontextprotocol/sdk: SDK MCP oficial para TypeScript
• nimiq-rpc-client-ts: Cliente RPC de Nimiq completamente tipado
• rpc.nimiqwatch.com: Servicio RPC público gratuito de Nimiq
• Valibot: Validación de esquemas en tiempo de ejecución y seguridad de tipos para todas las entradas de herramientas
• Cloudflare Workers: Plataforma de computación en el borde para despliegue remoto
• TypeScript: Para seguridad de tipos y una mejor experiencia de desarrollo

Características del Protocolo MCP 2025-06-18

Este servidor implementa la especificación más reciente del Protocolo de Contexto de Modelo (2025-06-18) con funciones mejoradas:

• Soporte de Elicitación: Las herramientas interactivas pueden solicitar información adicional a los usuarios durante la ejecución
• Validación de Entrada Mejorada: Validación integral de esquemas con mensajes de error detallados
• Respuestas de Herramientas Estructuradas: Definiciones de esquema JSON para una mejor comprensión por parte de LLMs
• Manejo de Errores Mejorado: Respuestas de error estandarizadas con códigos de error MCP adecuados
• Cumplimiento de la Versión del Protocolo: Soporte completo para los requisitos de la especificación MCP más reciente

Opciones de Despliegue

Despliegue Local (Transporte STDIO)

• Se ejecuta como un proceso local que se comunica a través de stdin/stdout
• Mejor para aplicaciones de escritorio y desarrollo local
• No se requiere configuración de red
• Inherentemente seguro (sin exposición a la red)

Despliegue Remoto (Transporte SSE)

• Desplegado en la red de borde de Cloudflare Workers
• Accesible desde cualquier lugar a través de HTTPS
• Soporta múltiples clientes concurrentes
• Seguridad integrada, limitación de velocidad y CDN global
• Escalado automático y alta disponibilidad

Validación de Entrada

El servidor usa Valibot para la validación integral de entradas en todas las herramientas, proporcionando:

• Seguridad de Tipos en Tiempo de Ejecución: Todas las entradas de herramientas se validan contra esquemas estrictos
• Mensajes de Error Descriptivos: Errores de validación claros con detalles a nivel de campo
• Inferencia de Tipos: Inferencia automática de tipos de TypeScript a partir de esquemas de Valibot
• Valores Predeterminados: Aplicación automática de valores predeterminados para parámetros opcionales
• Validación de Enumeraciones: Validación estricta de valores permitidos para parámetros como tipos de red

Ejemplo de validación:

const StakingRewardsSchema = v.object({
  amount: v.optional(v.pipe(v.number(), v.description('Initial amount staked in NIM')), 1),
  days: v.optional(v.pipe(v.number(), v.description('Number of days staked')), 365),
  network: v.optional(v.pipe(v.picklist(['main-albatross', 'test-albatross']), v.description('Network name')), 'main-albatross'),
})

Manejo de Errores

El servidor incluye un manejo integral de errores:

• Errores de conexión RPC
• Manejo de límites de velocidad
• Parámetros inválidos
• Tiempos de espera de red
• Apagado elegante en SIGINT

Contribuciones

1. Haz un fork del repositorio
2. Crea una rama de características
3. Realiza tus cambios
4. Ejecuta las pruebas y el linting
5. Envía una solicitud de extracción

Licencia

Licencia MIT - consulta el archivo LICENSE para obtener más detalles.