grid402-mcp 1.1.0 → 1.2.1
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 +42 -13
- package/package.json +13 -3
- package/tools.mjs +4 -2
- package/smithery.yaml +0 -19
- package/test_mcp.mjs +0 -74
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
|
|
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
|
-
> 💡 **
|
|
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
|
-
###
|
|
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
|
-
###
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
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,19 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "grid402-mcp",
|
|
3
|
-
"version": "1.1
|
|
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.1",
|
|
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
|
+
"x402_payer.mjs",
|
|
14
|
+
"README.md",
|
|
15
|
+
"package.json"
|
|
16
|
+
],
|
|
10
17
|
"scripts": {
|
|
11
18
|
"start": "node index.mjs",
|
|
12
19
|
"test": "node test_mcp.mjs"
|
|
@@ -17,6 +24,7 @@
|
|
|
17
24
|
"claude",
|
|
18
25
|
"cursor",
|
|
19
26
|
"smithery",
|
|
27
|
+
"agentkit",
|
|
20
28
|
"ai-agents",
|
|
21
29
|
"x402",
|
|
22
30
|
"base",
|
|
@@ -26,7 +34,9 @@
|
|
|
26
34
|
"dns",
|
|
27
35
|
"ssl",
|
|
28
36
|
"asn",
|
|
29
|
-
"cep"
|
|
37
|
+
"cep",
|
|
38
|
+
"cnpj",
|
|
39
|
+
"sandbox"
|
|
30
40
|
],
|
|
31
41
|
"author": "Grid402 Team <contato@grid402.com.br>",
|
|
32
42
|
"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.
|
|
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
|
-
|