Nimiq MCP Server

Nimiq MCP Server

Um servidor Model Context Protocol (MCP) para interagir com a blockchain Nimiq.

📖 Model Context Protocol

Recursos

• 🚀 Duas opções de implantação: Acesso remoto sem configuração OU instalação local
• 🔗 18 ferramentas abrangentes para contas, transações, blocos, validadores e mais
• 🤖 Protocolo MCP 2025-06-18: Especificação mais recente com recursos aprimorados
• 💬 Ferramentas Interativas: Suporte a elicitação para experiências de usuário guiadas
• ⚡ Opção remota: Sem necessidade de instalação - basta adicionar a URL ao seu cliente MCP
• 🔧 Opção local: Controle total com npx nimiq-mcp
• 🔍 Busca avançada: Pesquisa de texto completo na documentação abrangente da Nimiq
• 📊 Cálculos aprimorados: Calculadora interativa de recompensas de staking com padrões inteligentes
• 🔒 Operações somente leitura (envio de transações não suportado por segurança)
• ✅ Validação de entrada: Validação abrangente de esquema para todas as entradas de ferramentas

Início Rápido

Escolha uma das duas opções:

Opção 1: Acesso Remoto

Adicione isto à configuração do seu cliente MCP:

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

Opção 2: Instalação Local

Adicione isto à configuração do seu cliente MCP:

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

Comparação

Com Endpoint RPC Personalizado e Autenticação

{
  "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 Disponíveis

Ferramentas e Recursos Disponíveis

O servidor MCP fornece ferramentas e recursos abrangentes para interagir com a blockchain Nimiq:

Ferramentas (18 disponíveis)

Recursos (3 disponíveis)

Parâmetros das Ferramentas

Cada ferramenta aceita parâmetros específicos:

• Ferramentas de bloco: includeBody (booleano) para incluir detalhes de transações
• Ferramentas de endereço: address (string) para endereços Nimiq
• Ferramentas de transação: hash (string) para hashes de transação, max (número) para limites
• Ferramentas de documentação: includeSchemas (booleano) para getRpcMethods incluir esquemas detalhados de parâmetros/resultados
• Ferramentas de busca: query (string) para termos de busca, limit (número) para controlar a quantidade de resultados

Acesso aos Recursos

Os recursos são acessados via sua URI e não requerem parâmetros:

• Recursos de documentação: Acesse via nimiq://docs/web-client, nimiq://docs/protocol ou nimiq://docs/validators
• O conteúdo é retornado como texto simples para consumo ideal por LLMs
• Clientes MCP podem armazenar em cache o conteúdo dos recursos para melhor desempenho

Exemplos de Respostas

Resposta de Dados de Fornecimento

{
  "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"
}

Resposta de Dados de Bloco

{
  "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"
}

Resposta de Busca na Documentação

{
  "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"
}

Exemplos de Uso

Configuração do Claude Desktop

Opção 1: Remoto (Sem Configuração)

Adicione ao seu claude_desktop_config.json:

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

Opção 2: Instalação Local

Adicione ao seu claude_desktop_config.json:

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

Com Configuração Local Personalizada

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

Em Aplicações Web

Acesse o servidor remoto diretamente via HTTP:

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

Em Outros Clientes MCP

O servidor segue a especificação MCP e pode ser usado com qualquer cliente compatível com MCP:

Instalação local:

npx nimiq-mcp

Acesso remoto:

• Endpoint de Ferramentas: https://nimiq-mcp.je-cf9.workers.dev/tools
• Endpoint de Informações: https://nimiq-mcp.je-cf9.workers.dev/info
• Verificação de Saúde: https://nimiq-mcp.je-cf9.workers.dev/health
• Interface Web: https://nimiq-mcp.je-cf9.workers.dev/

Desenvolvimento

Desenvolvimento 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

Desenvolvimento com 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

Implantação no Cloudflare Workers

Consulte o Guia de Implantação completo para instruções detalhadas.

Etapas rápidas de implantação:

1. Configure a conta Cloudflare e obtenha o token da API
2. Configure os segredos do GitHub (para implantação automática):
   • CLOUDFLARE_API_TOKEN
   • CLOUDFLARE_ACCOUNT_ID
3. Envie para o branch main - implantação automática via GitHub Actions
4. Configure os segredos de produção (opcional):

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

O worker estará disponível em: https://nimiq-mcp.je-cf9.workers.dev

Arquitetura

O servidor MCP é construído usando:

• @modelcontextprotocol/sdk: SDK MCP oficial para TypeScript
• nimiq-rpc-client-ts: Cliente RPC Nimiq totalmente tipado
• rpc.nimiqwatch.com: Serviço RPC público gratuito da Nimiq
• Valibot: Validação de esquema em tempo de execução e segurança de tipos para todas as entradas de ferramentas
• Cloudflare Workers: Plataforma de computação de borda para implantação remota
• TypeScript: Para segurança de tipos e melhor experiência de desenvolvimento

Recursos do Protocolo MCP 2025-06-18

Este servidor implementa a especificação mais recente do Model Context Protocol (2025-06-18) com recursos aprimorados:

• Suporte a Elicitação: Ferramentas interativas podem solicitar informações adicionais dos usuários durante a execução
• Validação de Entrada Aprimorada: Validação abrangente de esquema com mensagens de erro detalhadas
• Respostas Estruturadas de Ferramentas: Definições de JSON Schema para melhor compreensão por LLMs
• Tratamento de Erros Aprimorado: Respostas de erro padronizadas com códigos de erro MCP adequados
• Conformidade com a Versão do Protocolo: Suporte completo aos requisitos mais recentes da especificação MCP

Opções de Implantação

Implantação Local (Transporte STDIO)

• Executa como um processo local comunicando-se via stdin/stdout
• Ideal para aplicações desktop e desenvolvimento local
• Nenhuma configuração de rede necessária
• Inerentemente seguro (sem exposição à rede)

Implantação Remota (Transporte SSE)

• Implantado na rede de borda do Cloudflare Workers
• Acessível de qualquer lugar via HTTPS
• Suporta múltiplos clientes simultâneos
• Segurança integrada, limitação de taxa e CDN global
• Escalonamento automático e alta disponibilidade

Validação de Entrada

O servidor usa Valibot para validação abrangente de entrada em todas as ferramentas, fornecendo:

• Segurança de Tipos em Tempo de Execução: Todas as entradas de ferramentas são validadas contra esquemas estritos
• Mensagens de Erro Descritivas: Erros de validação claros com detalhes em nível de campo
• Inferência de Tipos: Inferência automática de tipos TypeScript a partir de esquemas Valibot
• Valores Padrão: Aplicação automática de valores padrão para parâmetros opcionais
• Validação de Enum: Validação estrita de valores permitidos para parâmetros como tipos de rede

Exemplo de validação:

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'),
})

Tratamento de Erros

O servidor inclui tratamento abrangente de erros:

• Erros de conexão RPC
• Tratamento de limite de taxa
• Parâmetros inválidos
• Timeouts de rede
• Desligamento gracioso no SIGINT

Contribuindo

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Faça suas alterações
4. Execute testes e linting
5. Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.