gtxagent-mcp 0.2.0 → 0.3.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 +44 -45
- package/bin/gtxagent-mcp-dispatch.mjs +27 -0
- package/bin/gtxagent-mcp-hosted.mjs +67 -0
- package/bin/gtxagent-mcp-wallet.mjs +58007 -0
- package/package.json +5 -3
- package/server.json +3 -3
package/README.md
CHANGED
|
@@ -1,27 +1,22 @@
|
|
|
1
1
|
# gtxagent-mcp
|
|
2
2
|
|
|
3
|
-
MCP bridge for the GTXAgent x402 tools.
|
|
4
|
-
and no GTXAgent account in the client.
|
|
3
|
+
MCP bridge for the GTXAgent x402 tools. Two modes:
|
|
5
4
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
`
|
|
5
|
+
- **Wallet (zero account, default):** `gtxagent-mcp` runs locally and pays each call from your
|
|
6
|
+
own Base wallet. Five decision tools, no signup, no tenant key.
|
|
7
|
+
- **Hosted:** `gtxagent-mcp` forwards to `https://app.gtxagent.com/mcp` with a prepaid tenant key.
|
|
8
|
+
Eleven data tools, no wallet in the client.
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## Quick start (wallet)
|
|
11
|
+
|
|
12
|
+
Use a Base wallet funded with a little USDC — the calls cost $0.02–$0.05 each. The key stays in the
|
|
13
|
+
MCP process and never leaves it; the x402 payment is a signed EIP-3009 authorization.
|
|
11
14
|
|
|
12
15
|
```bash
|
|
16
|
+
export GTX_X402_BUYER_KEY=0x...
|
|
13
17
|
npx -y gtxagent-mcp
|
|
14
18
|
```
|
|
15
19
|
|
|
16
|
-
Requires Node 20 or newer. The process exits with a clear error when `GTX_MCP_KEY` is missing.
|
|
17
|
-
|
|
18
|
-
## Configure
|
|
19
|
-
|
|
20
|
-
| Variable | Required | Meaning |
|
|
21
|
-
|---|---|---|
|
|
22
|
-
| `GTX_MCP_KEY` | yes | `gtx_mcp_…` tenant key; shown once when issued |
|
|
23
|
-
| `GTX_MCP_URL` | no | defaults to `https://app.gtxagent.com/mcp`; `http://localhost` is allowed for development |
|
|
24
|
-
|
|
25
20
|
### Claude Desktop
|
|
26
21
|
|
|
27
22
|
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
|
|
@@ -34,7 +29,7 @@ Requires Node 20 or newer. The process exits with a clear error when `GTX_MCP_KE
|
|
|
34
29
|
"command": "npx",
|
|
35
30
|
"args": ["-y", "gtxagent-mcp"],
|
|
36
31
|
"env": {
|
|
37
|
-
"
|
|
32
|
+
"GTX_X402_BUYER_KEY": "0x..."
|
|
38
33
|
}
|
|
39
34
|
}
|
|
40
35
|
}
|
|
@@ -52,44 +47,48 @@ Requires Node 20 or newer. The process exits with a clear error when `GTX_MCP_KE
|
|
|
52
47
|
"command": "npx",
|
|
53
48
|
"args": ["-y", "gtxagent-mcp"],
|
|
54
49
|
"env": {
|
|
55
|
-
"
|
|
50
|
+
"GTX_X402_BUYER_KEY": "0x..."
|
|
56
51
|
}
|
|
57
52
|
}
|
|
58
53
|
}
|
|
59
54
|
}
|
|
60
55
|
```
|
|
61
56
|
|
|
62
|
-
## Tools
|
|
57
|
+
## Tools (wallet)
|
|
63
58
|
|
|
64
59
|
| Tool | Price | What it returns |
|
|
65
60
|
|---|---:|---|
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
61
|
+
| `verdict` | $0.02 | Token safety grade: liquidity, volume, trades, age, proxy/owner flags, reasons, `not_checked` |
|
|
62
|
+
| `preflight` | $0.02 | What a Base transaction will do: decoded call, checks, simulation, go / caution / no_go |
|
|
63
|
+
| `preflight_full` | $0.05 | The preflight plus decoded balance changes (transfers, allowances, swap path) |
|
|
64
|
+
| `position_risk` | $0.03 | Aave V3 / Morpho health factor now and after a borrow or withdrawal |
|
|
65
|
+
| `wallet_dossier` | $0.05 | Counterparty facts: kind, balances, contract facts, OFAC screen |
|
|
66
|
+
|
|
67
|
+
`preflight` and `preflight_full` accept `assume: "allowance"` to simulate a swap before the approval
|
|
68
|
+
transaction exists. Without `from`, a balance-dependent call is reported as skipped, never guessed.
|
|
69
|
+
|
|
70
|
+
## Hosted mode
|
|
71
|
+
|
|
72
|
+
The same command runs the hosted path when `GTX_MCP_KEY` is set (no wallet needed):
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
npx -y gtxagent-mcp
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
| Variable | Required | Meaning |
|
|
79
|
+
|---|---|---|
|
|
80
|
+
| `GTX_MCP_KEY` | yes | `gtx_mcp_…` tenant key, shown once when issued |
|
|
81
|
+
| `GTX_MCP_URL` | no | defaults to `https://app.gtxagent.com/mcp`; `http://localhost` is allowed for development |
|
|
82
|
+
|
|
83
|
+
The hosted server exposes eleven data tools: `market_pulse`, `token_registry`, `token_quote`,
|
|
84
|
+
`token_decision`, `token_safety`, `x_search`, `token_price`, `market_open`, `agent_recommend`,
|
|
85
|
+
`trending_coins`, `whale_coverage`. Every call is charged to the tenant's prepaid
|
|
86
|
+
`credits_available` balance; the per-key daily cap is $5 by default. An insufficient balance or cap
|
|
87
|
+
returns a tool error, not a partial result.
|
|
88
|
+
|
|
89
|
+
Keys are issued per tenant and are not self-service yet. Ask through
|
|
90
|
+
https://gtxagent.com/agents.html or the GTXAgent Telegram bot. The raw key is shown **once**; only a
|
|
91
|
+
SHA-256 hash is stored. Revoke a key immediately if it leaks.
|
|
93
92
|
|
|
94
93
|
## Links
|
|
95
94
|
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// gtxagent-mcp — one entry point, two modes.
|
|
3
|
+
//
|
|
4
|
+
// GTX_X402_BUYER_KEY set -> wallet bridge (zero account, pays per call from your Base wallet)
|
|
5
|
+
// GTX_MCP_KEY set -> hosted bridge (prepaid tenant key, eleven data tools)
|
|
6
|
+
//
|
|
7
|
+
// The mode is chosen by the environment so `npx -y gtxagent-mcp` is the only command a user needs.
|
|
8
|
+
import { spawn } from 'node:child_process';
|
|
9
|
+
|
|
10
|
+
const wallet = (process.env.GTX_X402_BUYER_KEY ?? '').trim();
|
|
11
|
+
const hosted = (process.env.GTX_MCP_KEY ?? '').trim();
|
|
12
|
+
|
|
13
|
+
if (wallet === '' && hosted === '') {
|
|
14
|
+
console.error([
|
|
15
|
+
'gtxagent-mcp: no credential.',
|
|
16
|
+
'Wallet mode (no signup): export GTX_X402_BUYER_KEY=0x... (a funded Base wallet).',
|
|
17
|
+
'Hosted mode: export GTX_MCP_KEY=gtx_mcp_... (a prepaid tenant key).',
|
|
18
|
+
].join('\n'));
|
|
19
|
+
process.exit(1);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const target = wallet !== '' ? './gtxagent-mcp-wallet.mjs' : './gtxagent-mcp.mjs';
|
|
23
|
+
const child = spawn(process.execPath, [new URL(target, import.meta.url).pathname], {
|
|
24
|
+
stdio: 'inherit',
|
|
25
|
+
env: process.env,
|
|
26
|
+
});
|
|
27
|
+
child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// gtxagent-mcp — stdio MCP bridge to the hosted GTXAgent x402 tools.
|
|
3
|
+
//
|
|
4
|
+
// The client (Claude Desktop, Cursor, any MCP host) speaks stdio to this process; this process
|
|
5
|
+
// speaks Streamable HTTP to https://app.gtxagent.com/mcp with the tenant's prepaid key. The key
|
|
6
|
+
// stays in the environment and is never printed. No wallet, no local GTX account.
|
|
7
|
+
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
|
8
|
+
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
|
|
9
|
+
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
|
10
|
+
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
11
|
+
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
|
|
12
|
+
|
|
13
|
+
const VERSION = '0.2.0';
|
|
14
|
+
const DEFAULT_URL = 'https://app.gtxagent.com/mcp';
|
|
15
|
+
|
|
16
|
+
function fail(message) {
|
|
17
|
+
console.error(`gtxagent-mcp: ${message}`);
|
|
18
|
+
process.exit(1);
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
function endpoint() {
|
|
22
|
+
const raw = process.env.GTX_MCP_URL?.trim() || DEFAULT_URL;
|
|
23
|
+
let url;
|
|
24
|
+
try {
|
|
25
|
+
url = new URL(raw);
|
|
26
|
+
} catch {
|
|
27
|
+
fail('GTX_MCP_URL is not a valid URL');
|
|
28
|
+
}
|
|
29
|
+
const local = url.protocol === 'http:' && (url.hostname === '127.0.0.1' || url.hostname === 'localhost');
|
|
30
|
+
if (url.protocol !== 'https:' && !local) fail('GTX_MCP_URL must be https (http is allowed only on localhost)');
|
|
31
|
+
return url;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
const key = process.env.GTX_MCP_KEY?.trim();
|
|
35
|
+
if (!key) fail('GTX_MCP_KEY is required — issue a gtx_mcp_… key for your tenant first');
|
|
36
|
+
if (!/^gtx_mcp_[0-9a-f]{64}$/.test(key)) fail('GTX_MCP_KEY is malformed (expected gtx_mcp_ followed by 64 hex characters)');
|
|
37
|
+
|
|
38
|
+
const remote = new Client({ name: 'gtxagent-mcp', version: VERSION }, { capabilities: {} });
|
|
39
|
+
const transport = new StreamableHTTPClientTransport(endpoint(), {
|
|
40
|
+
requestInit: { headers: { Authorization: ['Bearer', key].join(' ') } },
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
try {
|
|
44
|
+
await remote.connect(transport);
|
|
45
|
+
} catch (error) {
|
|
46
|
+
// The SDK error can include the URL, never the Authorization header; keep the message short.
|
|
47
|
+
fail(`cannot reach the hosted endpoint (${error instanceof Error ? error.message : 'unknown error'})`);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const server = new Server(
|
|
51
|
+
{ name: 'gtxagent', version: VERSION },
|
|
52
|
+
{ capabilities: { tools: {} } },
|
|
53
|
+
);
|
|
54
|
+
|
|
55
|
+
server.setRequestHandler(ListToolsRequestSchema, async (request) => remote.listTools(request.params));
|
|
56
|
+
server.setRequestHandler(CallToolRequestSchema, async (request) => remote.callTool(request.params));
|
|
57
|
+
|
|
58
|
+
const shutdown = async () => {
|
|
59
|
+
await remote.close().catch(() => undefined);
|
|
60
|
+
await server.close().catch(() => undefined);
|
|
61
|
+
process.exit(0);
|
|
62
|
+
};
|
|
63
|
+
process.on('SIGINT', shutdown);
|
|
64
|
+
process.on('SIGTERM', shutdown);
|
|
65
|
+
|
|
66
|
+
await server.connect(new StdioServerTransport());
|
|
67
|
+
console.error(`gtxagent-mcp ${VERSION}: connected to ${endpoint().href}`);
|