grid402-mcp 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Servidor oficial do **Model Context Protocol (MCP)** para o **Grid402** — Hub de Utilitários de Rede e Dados Públicos Abertos com liquidação de micropagamentos x402 em USDC na rede Base.
4
4
 
5
- Compatível nativamente com **Claude Desktop**, **Cursor**, **Smithery.ai** e qualquer orquestrador compatível com a especificação MCP da Anthropic.
5
+ Compatível nativamente com **Claude Desktop**, **Cursor**, **Smithery.ai**, **Coinbase AgentKit** e qualquer orquestrador compatível com a especificação MCP da Anthropic.
6
6
 
7
7
  ---
8
8
 
@@ -10,19 +10,37 @@ Compatível nativamente com **Claude Desktop**, **Cursor**, **Smithery.ai** e qu
10
10
 
11
11
  | Ferramenta | Descrição | Modalidade | Custo |
12
12
  |---|---|---|---|
13
- | `grid402_summary` | Resumo consolidado de saúde dos 6 micro-serviços | Direto | Gratuito |
13
+ | `grid402_summary` | Resumo consolidado de saúde dos serviços | Direto | Gratuito |
14
14
  | `grid402_forex` | Cotações em tempo real de USD, EUR e GBP para BRL | On-Demand | 0.0005 USDC |
15
15
  | `grid402_crypto` | Preços spot de BTC, ETH, SOL, USDC e BASE | On-Demand | 0.0005 USDC |
16
16
  | `grid402_dns` | Resolução autoritativa de DNS (A, AAAA, MX, TXT, NS, CNAME) | On-Demand | 0.0005 USDC |
17
17
  | `grid402_ssl` | Inspeção de validade, emissor e dias restantes de certificados TLS/SSL | On-Demand | 0.0005 USDC |
18
18
  | `grid402_asn` | Inteligência BGP, número ASN, organização e país de bloco IP | On-Demand | 0.0005 USDC |
19
19
  | `grid402_cep` | Consulta de endereço postal brasileiro e código IBGE oficial | On-Demand | 0.0005 USDC |
20
+ | `grid402_cnpj` | Consulta cadastral de CNPJ da Receita Federal com status e CNAE | On-Demand | 0.0020 USDC |
20
21
 
21
22
  ---
22
23
 
23
- ## 🚀 Como Configurar
24
+ ## 🚀 Como Configurar e Instalar
25
+
26
+ ### 1. Instalação em 1 Clique via Smithery.ai
27
+
28
+ Se você utiliza a CLI do Smithery, instale diretamente no cliente desejado:
29
+
30
+ ```bash
31
+ # Para Claude Desktop
32
+ npx -y @smithery/cli install grid402-mcp --client claude
33
+
34
+ # Para Cursor
35
+ npx -y @smithery/cli install grid402-mcp --client cursor
36
+ ```
37
+
38
+ O Smithery criará e injetará as configurações automaticamente no seu ambiente.
39
+
40
+ ---
41
+
42
+ ### 2. Configuração Manual no Claude Desktop
24
43
 
25
- ### 1. Claude Desktop
26
44
  Adicione ao seu arquivo de configuração (`claude_desktop_config.json`):
27
45
  - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
28
46
  - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
@@ -35,6 +53,7 @@ Adicione ao seu arquivo de configuração (`claude_desktop_config.json`):
35
53
  "args": ["-y", "grid402-mcp"],
36
54
  "env": {
37
55
  "GRID402_ENDPOINT": "https://orangered-jackal-900744.hostingersite.com",
56
+ "GRID402_SANDBOX": "false",
38
57
  "GRID402_PRIVATE_KEY": "0xsua_chave_privada_base_aqui"
39
58
  }
40
59
  }
@@ -42,18 +61,24 @@ Adicione ao seu arquivo de configuração (`claude_desktop_config.json`):
42
61
  }
43
62
  ```
44
63
 
45
- > 💡 **Nota de Segurança:** A variável `GRID402_PRIVATE_KEY` é opcional. Se informada, o servidor MCP realiza a transferência automática de 0.0005 USDC on-chain na Base a cada consulta paga. Se não for informada, o servidor retorna o desafio x402 em formato amigável. A chave é processada estritamente na sua máquina local e nunca é enviada ao servidor do Grid402.
64
+ > 💡 **Modo Sandbox Gratuito:** Você pode definir `"GRID402_SANDBOX": "true"` para testar todas as ferramentas sem gastar USDC nem configurar chave privada (limite de 20 consultas por hora por IP).
65
+ >
66
+ > 💡 **Nota de Segurança:** A variável `GRID402_PRIVATE_KEY` é opcional. Se informada, o servidor MCP realiza a transferência automática de USDC on-chain na Base a cada consulta paga. Se não informada ou sem saldo, o servidor retorna o desafio x402 com amostra de dados. A chave é processada estritamente na sua máquina local e nunca é enviada ao servidor do Grid402.
46
67
 
47
68
  ---
48
69
 
49
- ### 2. Cursor IDE
70
+ ### 3. Configuração Manual no Cursor IDE
71
+
50
72
  No seu projeto ou globalmente em `~/.cursor/mcp.json`:
51
73
  ```json
52
74
  {
53
75
  "mcpServers": {
54
76
  "grid402": {
55
77
  "command": "npx",
56
- "args": ["-y", "grid402-mcp"]
78
+ "args": ["-y", "grid402-mcp"],
79
+ "env": {
80
+ "GRID402_SANDBOX": "true"
81
+ }
57
82
  }
58
83
  }
59
84
  }
@@ -61,19 +86,23 @@ No seu projeto ou globalmente em `~/.cursor/mcp.json`:
61
86
 
62
87
  ---
63
88
 
64
- ### 3. Smithery.ai
65
- Para instalar via Smithery CLI:
66
- ```bash
67
- smithery install grid402-mcp --client claude
68
- ```
89
+ ### 4. Agentes Autônomos com Coinbase AgentKit (CDP)
90
+
91
+ Para robôs que operam nativamente na Base utilizando o Coinbase AgentKit, utilize o provedor de ações pronto em TypeScript ou Python:
92
+
93
+ - **TypeScript:** `integrations/agentkit/grid402_action_provider.ts`
94
+ - **Python:** `integrations/agentkit/grid402_action_provider.py`
95
+ - **Guia Completo:** Veja `integrations/agentkit/README.md`
96
+
97
+ O provedor gerencia automaticamente o ciclo de vida HTTP 402, transferindo os micropagamentos em USDC pela carteira CDP do agente e reenviando a requisição de forma transparente.
69
98
 
70
99
  ---
71
100
 
72
101
  ## 🧪 Testando Localmente
102
+
73
103
  ```bash
74
104
  cd mcp
75
105
  node test_mcp.mjs
76
106
  ```
77
107
 
78
108
  Licença MIT • Grid402 Team
79
-
package/package.json CHANGED
@@ -1,12 +1,18 @@
1
1
  {
2
2
  "name": "grid402-mcp",
3
- "version": "1.1.0",
4
- "description": "Official Model Context Protocol (MCP) Server for Grid402 - Public Open Data e Network Utilities Hub (Forex, Crypto, DNS, SSL, ASN, CEP) with Base x402 micropayments.",
3
+ "version": "1.2.0",
4
+ "description": "Official Model Context Protocol (MCP) Server for Grid402 - Public Open Data e Network Utilities Hub (Forex, Crypto, DNS, SSL, ASN, CEP, CNPJ) with Base x402 micropayments e Sandbox.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "grid402-mcp": "index.mjs"
8
8
  },
9
9
  "main": "./index.mjs",
10
+ "files": [
11
+ "index.mjs",
12
+ "tools.mjs",
13
+ "README.md",
14
+ "package.json"
15
+ ],
10
16
  "scripts": {
11
17
  "start": "node index.mjs",
12
18
  "test": "node test_mcp.mjs"
@@ -17,6 +23,7 @@
17
23
  "claude",
18
24
  "cursor",
19
25
  "smithery",
26
+ "agentkit",
20
27
  "ai-agents",
21
28
  "x402",
22
29
  "base",
@@ -26,7 +33,9 @@
26
33
  "dns",
27
34
  "ssl",
28
35
  "asn",
29
- "cep"
36
+ "cep",
37
+ "cnpj",
38
+ "sandbox"
30
39
  ],
31
40
  "author": "Grid402 Team <contato@grid402.com.br>",
32
41
  "license": "MIT",
package/tools.mjs CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  import { settleX402Payment } from './x402_payer.mjs';
6
6
 
7
- export const DEFAULT_ENDPOINT = process.env.GRID402_ENDPOINT || 'https://orangered-jackal-900744.hostingersite.com';
7
+ export const DEFAULT_ENDPOINT = process.env.GRID402_ENDPOINT || process.env.GRID402_API_URL || 'https://orangered-jackal-900744.hostingersite.com';
8
8
 
9
9
  /**
10
10
  * Definições formais das 7 ferramentas no padrão MCP
@@ -189,11 +189,13 @@ export async function executeGrid402Request(service, params = {}, options = {})
189
189
 
190
190
  const headers = {
191
191
  'Accept': 'application/json',
192
- 'User-Agent': 'Grid402-MCP-Server/1.0',
192
+ 'User-Agent': 'Grid402-MCP-Server/1.1',
193
193
  };
194
194
 
195
195
  if (params.payment_tx_hash) {
196
196
  headers['X-Payment'] = params.payment_tx_hash;
197
+ } else if (process.env.GRID402_SANDBOX === 'true' || process.env.GRID402_SANDBOX === '1') {
198
+ headers['X-Payment'] = 'demo';
197
199
  }
198
200
 
199
201
  // 1. Primeira tentativa de requisição
package/smithery.yaml DELETED
@@ -1,19 +0,0 @@
1
- name: "grid402-mcp"
2
- version: 1.0.0
3
- description: "Official Model Context Protocol (MCP) Server for Grid402 - Public Open Data e Network Utilities Hub (Forex, Crypto, DNS, SSL, ASN, CEP) with Base x402 micropayments."
4
- startCommand:
5
- type: stdio
6
- config:
7
- command: npx
8
- args:
9
- - "-y"
10
- - "grid402-mcp"
11
- env:
12
- GRID402_ENDPOINT:
13
- type: string
14
- description: "Grid402 Hub API Endpoint"
15
- default: "https://orangered-jackal-900744.hostingersite.com"
16
- GRID402_PRIVATE_KEY:
17
- type: string
18
- description: "EVM private key on Base Mainnet for automated 0.0005 USDC x402 payment settlement (optional)"
19
-
package/test_mcp.mjs DELETED
@@ -1,74 +0,0 @@
1
- /**
2
- * Grid402 MCP Server - Bateria de Testes Automatizados
3
- */
4
-
5
- import assert from 'node:assert';
6
- import { MCP_TOOLS_DEFINITIONS, executeGrid402Request } from './tools.mjs';
7
- import { settleX402Payment, GRID402_RECIPIENT_WALLET } from './x402_payer.mjs';
8
-
9
- async function runTests() {
10
- console.log('=== Testando Servidor MCP Grid402 ===\n');
11
-
12
- // 1. Validação de Schemas das Ferramentas
13
- console.log('[1/4] Validando registro e schemas das 8 ferramentas MCP...');
14
- assert.strictEqual(MCP_TOOLS_DEFINITIONS.length, 8, 'Deve conter exatamente 8 ferramentas registradas');
15
-
16
- const toolNames = MCP_TOOLS_DEFINITIONS.map(t => t.name);
17
- const expectedTools = [
18
- 'grid402_summary',
19
- 'grid402_forex',
20
- 'grid402_crypto',
21
- 'grid402_dns',
22
- 'grid402_ssl',
23
- 'grid402_asn',
24
- 'grid402_cep',
25
- 'grid402_cnpj',
26
- ];
27
-
28
- for (const expected of expectedTools) {
29
- assert.ok(toolNames.includes(expected), `Ferramenta ${expected} deve estar presente`);
30
- }
31
- console.log(' ✓ Todas as 8 ferramentas MCP validadas com sucesso!');
32
-
33
- // 2. Teste de Consulta Gratuita (summary)
34
- console.log('\n[2/4] Testando consulta à ferramenta gratuita grid402_summary...');
35
- const summary = await executeGrid402Request('summary');
36
- assert.strictEqual(summary.protocol, 'x402', 'Protocolo deve ser x402');
37
- assert.strictEqual(summary.hub, 'Grid402', 'Hub deve ser Grid402');
38
- assert.ok(summary.services, 'Deve conter catálogo de serviços');
39
- console.log(' ✓ Resumo de saúde recebido com sucesso (Hub operacional)');
40
-
41
- // 3. Teste de Captura de Desafio x402 sem Chave Privada
42
- console.log('\n[3/4] Testando resposta de desafio 402 para consulta detalhada (grid402_dns e grid402_cnpj)...');
43
- const dnsChallenge = await executeGrid402Request('dns', { domain: 'github.com' });
44
- assert.strictEqual(dnsChallenge.payment_required, true, 'Deve indicar payment_required: true');
45
- assert.ok(dnsChallenge.challenge, 'Deve conter objeto challenge');
46
- assert.strictEqual(
47
- (dnsChallenge.challenge.recipient_wallet || '').toLowerCase(),
48
- GRID402_RECIPIENT_WALLET,
49
- 'Carteira recebedora deve coincidir com a oficial'
50
- );
51
-
52
- const cnpjChallenge = await executeGrid402Request('cnpj', { cnpj: '00000000000191' });
53
- assert.strictEqual(cnpjChallenge.payment_required, true, 'CNPJ deve indicar payment_required: true');
54
- assert.ok(cnpjChallenge.challenge, 'Deve conter desafio estruturado');
55
- console.log(' ✓ Desafio x402 capturado com instruções e carteira oficial para DNS e CNPJ!');
56
-
57
- // 4. Teste de Validação Defensiva de Chave Privada
58
- console.log('\n[4/4] Testando validação defensiva de formato de chave privada...');
59
- try {
60
- await settleX402Payment({}, 'chave_invalida');
61
- assert.fail('Deveria ter lançado erro para chave inválida');
62
- } catch (err) {
63
- assert.ok(err.message.includes('Chave privada inválida'), 'Deve rejeitar chave mal formatada');
64
- console.log(' ✓ Rejeição de chave privada inválida validada com sucesso!');
65
- }
66
-
67
- console.log('\n=== Todos os testes do MCP Server Grid402 foram APROVADOS com 100% de sucesso! ===');
68
- }
69
-
70
- runTests().catch(err => {
71
- console.error('\n❌ Falha no teste do MCP Server:', err);
72
- process.exit(1);
73
- });
74
-
package/x402_payer.mjs DELETED
@@ -1,90 +0,0 @@
1
- /**
2
- * Grid402 MCP Server - Módulo de Liquidação x402 On-Chain (Base Mainnet)
3
- *
4
- * Permite pagamentos automáticos de US$ 0.0005 USDC via transferência ERC-20
5
- * quando uma chave privada é fornecida no ambiente do agente.
6
- */
7
-
8
- import { ethers } from 'ethers';
9
-
10
- export const BASE_RPC_URLS = [
11
- 'https://mainnet.base.org',
12
- 'https://1rpc.io/base',
13
- 'https://base.llamarpc.com',
14
- ];
15
-
16
- export const USDC_CONTRACT_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'.toLowerCase();
17
- export const GRID402_RECIPIENT_WALLET = '0xa31c31069c43ac1c0075a93c325b0dcd7744356c'.toLowerCase();
18
- export const REQUIRED_RAW_UNITS = 500n; // 0.000500 USDC (6 casas decimais)
19
-
20
- const ERC20_ABI = [
21
- 'function transfer(address to, uint256 amount) returns (bool)',
22
- 'function balanceOf(address account) view returns (uint256)',
23
- ];
24
-
25
- /**
26
- * Cria um provider com fallback resiliente para a Base Mainnet
27
- */
28
- export async function getBaseProvider(preferredRpc = null) {
29
- const rpcs = preferredRpc ? [preferredRpc, ...BASE_RPC_URLS] : BASE_RPC_URLS;
30
- for (const rpc of rpcs) {
31
- try {
32
- const provider = new ethers.JsonRpcProvider(rpc, 8453, { staticNetwork: true });
33
- await provider.getBlockNumber();
34
- return provider;
35
- } catch {
36
- // Tenta próximo RPC
37
- }
38
- }
39
- throw new Error('Não foi possível conectar a nenhum nó RPC da Base Mainnet.');
40
- }
41
-
42
- /**
43
- * Executa a transferência de 0.0005 USDC na Base para liquidar o desafio x402
44
- *
45
- * @param {object} challenge Desafio retornado pelo Grid402 (HTTP 402)
46
- * @param {string} privateKey Chave privada hexadecimal da carteira pagadora
47
- * @param {string} [preferredRpc] URL opcional de RPC da Base
48
- * @returns {Promise<{ txHash: string, blockNumber: number }>}
49
- */
50
- export async function settleX402Payment(challenge, privateKey, preferredRpc = null) {
51
- if (!privateKey || typeof privateKey !== 'string' || !privateKey.startsWith('0x')) {
52
- throw new Error('Chave privada inválida. Deve iniciar com 0x e conter 64 caracteres hexadecimais.');
53
- }
54
-
55
- const recipient = (challenge?.recipient_wallet || GRID402_RECIPIENT_WALLET).toLowerCase();
56
- const tokenContract = (challenge?.token_contract || USDC_CONTRACT_BASE).toLowerCase();
57
- const rawUnits = BigInt(challenge?.price_raw_units || REQUIRED_RAW_UNITS);
58
-
59
- const provider = await getBaseProvider(preferredRpc);
60
- const wallet = new ethers.Wallet(privateKey, provider);
61
-
62
- // Instancia contrato ERC-20 do USDC na Base
63
- const usdc = new ethers.Contract(tokenContract, ERC20_ABI, wallet);
64
-
65
- // 1. Verifica saldo de USDC
66
- try {
67
- const balance = await usdc.balanceOf(wallet.address);
68
- if (balance < rawUnits) {
69
- throw new Error(`Saldo insuficiente de USDC na carteira ${wallet.address}. Requerido: 0.0005 USDC, Atual: ${ethers.formatUnits(balance, 6)} USDC.`);
70
- }
71
- } catch (err) {
72
- if (err.message.includes('Saldo insuficiente')) {
73
- throw err;
74
- }
75
- // Caso leitura falhe por RPC restrito, tenta envio direto
76
- }
77
-
78
- // 2. Envia transferência ERC-20
79
- const tx = await usdc.transfer(recipient, rawUnits);
80
- const receipt = await tx.wait(1);
81
-
82
- return {
83
- txHash: receipt.hash,
84
- blockNumber: receipt.blockNumber,
85
- from: wallet.address,
86
- to: recipient,
87
- amountUsdc: '0.0005',
88
- };
89
- }
90
-