@tongateway/mcp 0.7.0 → 0.8.0

package/README.md

@@ -1,24 +1,34 @@
 # @tongateway/mcp
 
-MCP server for [Agent Gateway](https://github.com/pewpewgogo/ton-agent-gateway) — lets AI agents request TON blockchain transfers via Model Context Protocol.
+MCP server for [Agent Gateway](https://tongateway.ai) — gives AI agents full access to the TON blockchain via Model Context Protocol.
 
-## Install
+**14 tools:** wallet info, jettons, NFTs, transactions, transfers, .ton DNS, prices, agent wallets, and more.
+
+## Quick Start
+
+### Claude Code
 
 ```bash
-npm install -g @tongateway/mcp
+claude mcp add-json tongateway '{
+  "command": "npx",
+  "args": ["-y", "@tongateway/mcp"],
+  "env": {
+    "AGENT_GATEWAY_API_URL": "https://api.tongateway.ai"
+  }
+}' --scope user
 ```
 
-## Configure
+### Cursor
 
-Add to your MCP client config (Claude Code, Cursor, etc.):
+Add to Cursor Settings → MCP Servers:
 
 ```json
 {
   "mcpServers": {
     "tongateway": {
-      "command": "tongateway-mcp",
+      "command": "npx",
+      "args": ["-y", "@tongateway/mcp"],
       "env": {
-        "AGENT_GATEWAY_TOKEN": "YOUR_TOKEN_HERE",
         "AGENT_GATEWAY_API_URL": "https://api.tongateway.ai"
       }
     }
@@ -26,18 +36,90 @@ Add to your MCP client config (Claude Code, Cursor, etc.):
 }
 ```
 
-Get your token at [tongateway.ai/app.html](https://tongateway.ai/app.html).
+### OpenClaw
+
+```bash
+openclaw config set --strict-json plugins.entries.acpx.config.mcpServers '{
+  "tongateway": {
+    "command": "npx",
+    "args": ["-y", "@tongateway/mcp"],
+    "env": {
+      "AGENT_GATEWAY_API_URL": "https://api.tongateway.ai"
+    }
+  }
+}'
+```
+
+No token needed upfront — the agent authenticates via `request_auth` (generates a one-time link, user connects wallet). Token persists in `~/.tongateway/token` across restarts.
 
 ## Tools
 
+### Auth
+
+| Tool | Description |
+|------|-------------|
+| `request_auth` | Generate a one-time link for wallet connection |
+| `get_auth_token` | Retrieve token after user connects wallet |
+
+### Wallet
+
 | Tool | Description |
-|---|---|
-| `request_transfer` | Request a TON transfer (to, amountNano, payloadBoc?) |
-| `get_request_status` | Check status of a request by ID |
+|------|-------------|
+| `get_wallet_info` | Wallet address, TON balance, account status |
+| `get_jetton_balances` | All token balances (USDT, NOT, DOGS, etc.) |
+| `get_transactions` | Recent transaction history |
+| `get_nft_items` | NFTs owned by the wallet |
+
+### Transfers (Safe — requires wallet approval)
+
+| Tool | Description |
+|------|-------------|
+| `request_transfer` | Request a TON transfer (to, amountNano, payload?, stateInit?) |
+| `get_request_status` | Check transfer status by ID |
 | `list_pending_requests` | List all pending requests |
 
+### Lookup
+
+| Tool | Description |
+|------|-------------|
+| `resolve_name` | Resolve .ton domain to address |
+| `get_ton_price` | Current TON price in USD/EUR |
+
+### Agent Wallet (Autonomous — no approval needed)
+
+| Tool | Description |
+|------|-------------|
+| `deploy_agent_wallet` | Deploy a dedicated wallet contract for the agent |
+| `execute_agent_wallet_transfer` | Send TON directly from agent wallet |
+| `get_agent_wallet_info` | Balance, seqno, agent key status |
+
+## How it works
+
+```
+You: "Send 1 TON to alice.ton"
+
+Agent: resolve_name("alice.ton") → 0:83df...
+       request_transfer(to="0:83df...", amountNano="1000000000")
+       → Transfer request created. Approve in your wallet app.
+```
+
+For agent wallets (autonomous mode):
+
+```
+You: "Send 0.5 TON from my agent wallet to 0:abc..."
+
+Agent: execute_agent_wallet_transfer(wallet, to, amount)
+       → Transfer executed. No approval needed.
+```
+
 ## Links
 
-- [Agent Gateway](https://github.com/pewpewgogo/ton-agent-gateway) — main repo with all links
-- [Dashboard](https://tongateway.ai) — connect wallet & manage tokens
+- [tongateway.ai](https://tongateway.ai) — landing page + install guides
+- [Dashboard](https://tongateway.ai/app.html) — connect wallet & manage tokens
 - [API Docs](https://api.tongateway.ai/docs) — Swagger UI
+- [Agent Wallet Contract](https://github.com/tongateway/ton-agent-gateway-contract) — FunC smart contract
+- [Skill File](https://tongateway.ai/agent-gateway.md) — context file for AI agents
+
+## License
+
+MIT

package/dist/index.js

@@ -67,7 +67,7 @@ const server = new McpServer({
     name: 'agent-gateway',
     version: '0.1.0',
 });
-server.tool('request_auth', 'Request wallet authentication. Generates a one-time link for the user to connect their TON wallet. After the user connects, use get_auth_token to retrieve the token. Use this when no token is configured.', {
+server.tool('request_auth', 'Authenticate with TON blockchain. Call this FIRST if you get "No token configured" errors. Generates a one-time link — ask the user to open it and connect their wallet. Then call get_auth_token to complete. Token persists across restarts.', {
     label: z.string().optional().describe('Label for this agent session (e.g. "claude-agent")'),
 }, async ({ label }) => {
     try {
@@ -105,7 +105,7 @@ server.tool('request_auth', 'Request wallet authentication. Generates a one-time
         };
     }
 });
-server.tool('get_auth_token', 'Check if the user has completed wallet authentication and retrieve the token. Call this after request_auth once the user has opened the link and connected their wallet.', {
+server.tool('get_auth_token', 'Complete authentication after the user opened the link from request_auth. Pass the authId you received. Once successful, all other tools become available. You only need to authenticate once — the token is saved automatically.', {
     authId: z.string().describe('The authId returned by request_auth'),
 }, async ({ authId }) => {
     try {
@@ -155,7 +155,7 @@ server.tool('get_auth_token', 'Check if the user has completed wallet authentica
         };
     }
 });
-server.tool('request_transfer', 'Request a TON transfer from the wallet owner. The request will be queued and the owner must approve it via TON Connect.', {
+server.tool('request_transfer', 'Request a TON transfer. The user must approve it in their wallet app. Amount is in nanoTON (1 TON = 1000000000). Supports optional payload (BOC) and stateInit (for contract deployment). The transfer is queued — use get_request_status to check if approved.', {
     to: z.string().describe('Destination TON address'),
     amountNano: z.string().describe('Amount in nanoTON (1 TON = 1000000000)'),
     payload: z.string().optional().describe('Optional BOC-encoded payload for the transaction'),
@@ -202,7 +202,7 @@ server.tool('request_transfer', 'Request a TON transfer from the wallet owner. T
         };
     }
 });
-server.tool('get_request_status', 'Check the status of a previously submitted transfer request.', {
+server.tool('get_request_status', 'Check the status of a transfer request. Statuses: pending (waiting for approval), confirmed (signed and broadcast), rejected (user declined), expired (5 min timeout). Also shows broadcast result if available.', {
     id: z.string().describe('The request ID returned by request_transfer'),
 }, async ({ id }) => {
     if (!TOKEN) {
@@ -241,7 +241,7 @@ server.tool('get_request_status', 'Check the status of a previously submitted tr
         };
     }
 });
-server.tool('list_pending_requests', 'List all pending transfer requests waiting for wallet owner approval.', {}, async () => {
+server.tool('list_pending_requests', 'List all transfer requests waiting for wallet owner approval. Use to check if there are unfinished transfers.', {}, async () => {
     if (!TOKEN) {
         return {
             content: [{ type: 'text', text: 'No token configured. Use request_auth first to authenticate.' }],
@@ -273,7 +273,7 @@ server.tool('list_pending_requests', 'List all pending transfer requests waiting
         };
     }
 });
-server.tool('get_wallet_info', 'Get the connected wallet address, TON balance, and account status.', {}, async () => {
+server.tool('get_wallet_info', 'Get the connected wallet address, TON balance (in nanoTON and TON), and account status. Use this to check how much TON the user has before sending transfers.', {}, async () => {
     if (!TOKEN) {
         return { content: [{ type: 'text', text: 'No token configured. Use request_auth first.' }], isError: true };
     }
@@ -296,7 +296,7 @@ server.tool('get_wallet_info', 'Get the connected wallet address, TON balance, a
         return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
     }
 });
-server.tool('get_jetton_balances', 'Get all jetton (token) balances in the connected wallet. Shows USDT, NOT, DOGS, and other tokens.', {}, async () => {
+server.tool('get_jetton_balances', 'List all tokens (jettons) in the wallet — USDT, NOT, DOGS, and others. Shows symbol, name, balance, and decimals for each. Use this when the user asks about their tokens or wants to know what they hold.', {}, async () => {
     if (!TOKEN) {
         return { content: [{ type: 'text', text: 'No token configured. Use request_auth first.' }], isError: true };
     }
@@ -321,7 +321,7 @@ server.tool('get_jetton_balances', 'Get all jetton (token) balances in the conne
         return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
     }
 });
-server.tool('get_transactions', 'Get recent transaction history for the connected wallet.', {
+server.tool('get_transactions', 'Get recent transaction history. Shows timestamps, action types, and whether transactions were flagged as scam. Use when the user asks "what happened" or wants to review recent activity.', {
     limit: z.number().optional().describe('Number of transactions to return (default 10)'),
 }, async ({ limit }) => {
     if (!TOKEN) {
@@ -346,7 +346,7 @@ server.tool('get_transactions', 'Get recent transaction history for the connecte
         return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
     }
 });
-server.tool('get_nft_items', 'List NFTs owned by the connected wallet.', {}, async () => {
+server.tool('get_nft_items', 'List all NFTs owned by the wallet — name, collection, and address for each. Use when the user asks about their NFTs or collectibles.', {}, async () => {
     if (!TOKEN) {
         return { content: [{ type: 'text', text: 'No token configured. Use request_auth first.' }], isError: true };
     }
@@ -365,7 +365,7 @@ server.tool('get_nft_items', 'List NFTs owned by the connected wallet.', {}, asy
         return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
     }
 });
-server.tool('resolve_name', 'Resolve a .ton domain name to a wallet address. Use this when the user says "send to alice.ton" instead of a raw address.', {
+server.tool('resolve_name', 'Resolve a .ton domain name (like "alice.ton") to a raw wallet address. ALWAYS use this before request_transfer when the user gives a .ton name instead of a raw address.', {
     domain: z.string().describe('The .ton domain name to resolve (e.g. "alice.ton")'),
 }, async ({ domain }) => {
     try {
@@ -384,7 +384,7 @@ server.tool('resolve_name', 'Resolve a .ton domain name to a wallet address. Use
         return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
     }
 });
-server.tool('get_ton_price', 'Get the current price of TON in USD and other currencies.', {
+server.tool('get_ton_price', 'Get the current TON price in USD, EUR, or other currencies. Use when the user asks "how much is my TON worth" or before transfers to show USD equivalents.', {
     currencies: z.string().optional().describe('Comma-separated currencies (default "USD")'),
 }, async ({ currencies }) => {
     try {
@@ -403,7 +403,7 @@ server.tool('get_ton_price', 'Get the current price of TON in USD and other curr
         return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
     }
 });
-server.tool('deploy_agent_wallet', 'Deploy a new Agent Wallet smart contract. This creates an autonomous wallet that the agent can use to send TON without requiring approval for each transaction. DANGER: funds in this wallet can be spent by the agent without approval.', {}, async () => {
+server.tool('deploy_agent_wallet', 'Deploy an Agent Wallet smart contract — a dedicated sub-wallet for autonomous operations. WARNING: The agent can spend funds from this wallet WITHOUT user approval. Only deploy if the user explicitly wants autonomous transfers. After deployment, top up the wallet with funds.', {}, async () => {
     if (!TOKEN) {
         return { content: [{ type: 'text', text: 'No token configured. Use request_auth first.' }], isError: true };
     }
@@ -486,7 +486,7 @@ server.tool('deploy_agent_wallet', 'Deploy a new Agent Wallet smart contract. Th
         return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
     }
 });
-server.tool('execute_agent_wallet_transfer', 'Send TON directly from an Agent Wallet. No approval needed — the agent signs and broadcasts immediately. Only works with deployed agent wallets where the agent key is set.', {
+server.tool('execute_agent_wallet_transfer', 'Send TON directly from an Agent Wallet — NO approval needed. The agent signs and broadcasts immediately. Only works with deployed agent wallets. Use for automated/autonomous transfers where speed matters and the user has opted in.', {
     walletAddress: z.string().describe('The agent wallet contract address'),
     to: z.string().describe('Destination TON address'),
     amountNano: z.string().describe('Amount in nanoTON'),
@@ -583,7 +583,7 @@ server.tool('execute_agent_wallet_transfer', 'Send TON directly from an Agent Wa
         return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
     }
 });
-server.tool('get_agent_wallet_info', 'Get info about an Agent Wallet — balance, seqno, agent key status.', {
+server.tool('get_agent_wallet_info', 'Get info about Agent Wallets — balance, seqno, agent key status. Pass a wallet address for details, or omit to list all agent wallets.', {
     walletAddress: z.string().optional().describe('Agent wallet address. If omitted, lists all your agent wallets.'),
 }, async ({ walletAddress }) => {
     if (!TOKEN) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tongateway/mcp",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "MCP server for Agent Gateway — lets AI agents request TON blockchain transfers",
   "license": "MIT",
   "repository": {