gtxagent-mcp 0.1.1 → 0.3.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
@@ -1,27 +1,22 @@
1
1
  # gtxagent-mcp
2
2
 
3
- MCP bridge for the GTXAgent x402 tools. One process, one prepaid key, seven 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-wallet` 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
13
- npx -y gtxagent-mcp
16
+ export GTX_X402_BUYER_KEY=0x...
17
+ npx -y gtxagent-mcp-wallet
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
@@ -32,9 +27,9 @@ Requires Node 20 or newer. The process exits with a clear error when `GTX_MCP_KE
32
27
  "mcpServers": {
33
28
  "gtxagent": {
34
29
  "command": "npx",
35
- "args": ["-y", "gtxagent-mcp"],
30
+ "args": ["-y", "gtxagent-mcp-wallet"],
36
31
  "env": {
37
- "GTX_MCP_KEY": "gtx_mcp_…"
32
+ "GTX_X402_BUYER_KEY": "0x..."
38
33
  }
39
34
  }
40
35
  }
@@ -50,42 +45,50 @@ Requires Node 20 or newer. The process exits with a clear error when `GTX_MCP_KE
50
45
  "mcpServers": {
51
46
  "gtxagent": {
52
47
  "command": "npx",
53
- "args": ["-y", "gtxagent-mcp"],
48
+ "args": ["-y", "gtxagent-mcp-wallet"],
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
- | `token_safety` | $0.03 | Ownership powers, holder concentration, honeypot and liquidity flags |
67
- | `x_search` | $0.015 | Recent X/Twitter posts with author and minimum-like filters |
68
- | `token_price` | $0.04 | Live price and market data for coin ids or tickers |
69
- | `market_open` | $0.015 | Whether a named exchange is open, with local time and holidays |
70
- | `agent_recommend` | $0.02 | Agent recommendations for a stated need |
71
- | `trending_coins` | $0.04 | Trending coins with market data |
72
- | `whale_coverage` | $0.02 | Whale activity coverage for a token |
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 |
73
66
 
74
- Every call is charged to the tenant's prepaid `credits_available` balance. The per-key daily cap is
75
- $5 by default and is checked before the call. An insufficient balance or cap returns a tool error,
76
- not a partial result.
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.
77
69
 
78
- ## Keys
70
+ ## Hosted mode
79
71
 
80
- Keys are issued per tenant and are not self-service yet. Ask through https://gtxagent.com/agents.html
81
- or the GTXAgent Telegram bot. The raw key is shown **once**; only a SHA-256 hash is stored. Revoke a
82
- key immediately if it leaks.
72
+ The hosted path needs no wallet but a tenant key:
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 |
83
82
 
84
- ## Zero-account alternative
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.
85
88
 
86
- The repository also ships a local stdio bridge that pays the public x402 routes from your own Base
87
- wallet (`GTX_X402_BUYER_KEY=0x… npm run --silent mcp`). That path needs a funded wallet but no tenant
88
- key. This package deliberately uses the hosted path so MCP hosts need no wallet.
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.
89
92
 
90
93
  ## Links
91
94