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 CHANGED
@@ -1,27 +1,22 @@
1
1
  # gtxagent-mcp
2
2
 
3
- MCP bridge for the GTXAgent x402 tools. One process, one prepaid key, eleven paid tools — no wallet
4
- and no GTXAgent account in the client.
3
+ MCP bridge for the GTXAgent x402 tools. Two modes:
5
4
 
6
- The package is a **stdio ⇄ Streamable HTTP** adapter. Your MCP host starts `gtxagent-mcp` as a local
7
- stdio server; it connects to `https://app.gtxagent.com/mcp` with your tenant key and forwards
8
- `tools/list` and `tools/call`. Billing, upstream payment and settlement stay on GTXAgent.
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
- ## Install
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
- "GTX_MCP_KEY": "gtx_mcp_…"
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
- "GTX_MCP_KEY": "gtx_mcp_…"
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
- | `market_pulse` | $0.01 | Live Base snapshot: every supported token quoted in USDC |
67
- | `token_registry` | $0.005 | Allowed Base tokens with address and decimals |
68
- | `token_quote` | $0.002 | One token: contract, decimals and the latest USDC quote |
69
- | `token_decision` | $0.01 | Deterministic yes/no for one token over 24h with reasons and sources |
70
- | `token_safety` | $0.03 | Ownership powers, holder concentration, honeypot and liquidity flags |
71
- | `x_search` | $0.015 | Recent X/Twitter posts with author and minimum-like filters |
72
- | `token_price` | $0.04 | Live price and market data for coin ids or tickers |
73
- | `market_open` | $0.015 | Whether a named exchange is open, with local time and holidays |
74
- | `agent_recommend` | $0.02 | Agent recommendations for a stated need |
75
- | `trending_coins` | $0.04 | Trending coins with market data |
76
- | `whale_coverage` | $0.02 | Whale activity coverage for a token |
77
-
78
- Every call is charged to the tenant's prepaid `credits_available` balance. The per-key daily cap is
79
- $5 by default and is checked before the call. An insufficient balance or cap returns a tool error,
80
- not a partial result.
81
-
82
- ## Keys
83
-
84
- Keys are issued per tenant and are not self-service yet. Ask through https://gtxagent.com/agents.html
85
- or the GTXAgent Telegram bot. The raw key is shown **once**; only a SHA-256 hash is stored. Revoke a
86
- key immediately if it leaks.
87
-
88
- ## Zero-account alternative
89
-
90
- The repository also ships a local stdio bridge that pays the public x402 routes from your own Base
91
- wallet (`GTX_X402_BUYER_KEY=0x… npm run --silent mcp`). That path needs a funded wallet but no tenant
92
- key. This package deliberately uses the hosted path so MCP hosts need no wallet.
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}`);