@tongateway/mcp 0.14.0 → 0.19.2

package/README.md

@@ -52,7 +52,7 @@ openclaw config set --strict-json plugins.entries.acpx.config.mcpServers '{
 }'
 ```
 
-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.
+No token needed upfront — the agent authenticates via `auth.request` (generates a one-time link, user connects wallet). Token persists in `~/.tongateway/token` across restarts.
 
 ## Tools
 
@@ -60,48 +60,55 @@ No token needed upfront — the agent authenticates via `request_auth` (generate
 
 | Tool | Description |
 |------|-------------|
-| `request_auth` | Generate a one-time link for wallet connection |
-| `get_auth_token` | Retrieve token after user connects wallet |
+| `auth.request` | Generate a one-time link for wallet connection |
+| `auth.get_token` | Retrieve token after user connects wallet |
 
 ### Wallet
 
 | Tool | Description |
 |------|-------------|
-| `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 |
+| `wallet.info` | Wallet address, TON balance, account status |
+| `wallet.jettons` | All token balances (USDT, NOT, DOGS, etc.) |
+| `wallet.transactions` | Recent transaction history |
+| `wallet.nfts` | 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 |
+| `transfer.request` | Request a TON transfer (to, amountNano, payload?, stateInit?) |
+| `transfer.status` | Check transfer status by ID |
+| `transfer.pending` | List all pending requests |
 
 ### Lookup
 
 | Tool | Description |
 |------|-------------|
-| `resolve_name` | Resolve .ton domain to address |
-| `get_ton_price` | Current TON price in USD/EUR |
+| `lookup.resolve_name` | Resolve .ton domain to address |
+| `lookup.price` | Current TON price in USD/EUR |
+
+### DEX (open4dev order book)
+
+| Tool | Description |
+|------|-------------|
+| `dex.create_order` | Place a limit order (fromToken, toToken, amount, price) |
+| `dex.pairs` | List available trading pairs |
 
 ### 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 |
+| `agent_wallet.deploy` | Deploy a dedicated wallet contract for the agent |
+| `agent_wallet.transfer` | Send TON directly from agent wallet |
+| `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")
+Agent: lookup.resolve_name("alice.ton") → 0:83df...
+       transfer.request(to="0:83df...", amountNano="1000000000")
        → Transfer request created. Approve in your wallet app.
 ```
 
@@ -110,10 +117,39 @@ 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)
+Agent: agent_wallet.transfer(wallet, to, amount)
        → Transfer executed. No approval needed.
 ```
 
+## Build from Source
+
+If you prefer not to use `npx`, you can build and run locally:
+
+```bash
+git clone https://github.com/tongateway/mcp
+cd mcp
+npm install
+npm run build
+```
+
+Then configure your MCP client to use the local build:
+
+```json
+{
+  "mcpServers": {
+    "tongateway": {
+      "command": "node",
+      "args": ["/path/to/mcp/dist/index.js"],
+      "env": {
+        "AGENT_GATEWAY_API_URL": "https://api.tongateway.ai"
+      }
+    }
+  }
+}
+```
+
+See [SECURITY.md](SECURITY.md) for the full security model.
+
 ## Links
 
 - [tongateway.ai](https://tongateway.ai) — landing page + install guides
@@ -121,6 +157,8 @@ Agent: execute_agent_wallet_transfer(wallet, to, amount)
 - [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
+- [Smithery](https://smithery.ai/servers/tongateway/agent) — MCP marketplace listing
+- [MCP HTTP Endpoint](https://tongateway.run.tools) — remote MCP transport
 
 ## License
 

package/dist/index.js

@@ -1,4 +1,33 @@
 #!/usr/bin/env node
+// Handle --help and --version before importing anything
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    console.log(`@tongateway/mcp — TON blockchain gateway for AI agents
+
+Usage:
+  npx @tongateway/mcp              Start MCP server (stdio transport)
+  npx @tongateway/mcp --http       Start HTTP server (port 3100)
+
+Environment variables:
+  AGENT_GATEWAY_API_URL   API base URL (default: https://api.tongateway.ai)
+  AGENT_GATEWAY_TOKEN     Pre-configured auth token (optional)
+  MCP_HTTP_PORT           HTTP server port (default: 3100 with --http)
+
+Tools (16):
+  auth.request, auth.get_token
+  wallet.info, wallet.jettons, wallet.transactions, wallet.nfts
+  transfer.request, transfer.status, transfer.pending
+  lookup.resolve_name, lookup.price
+  dex.create_order, dex.pairs
+  agent_wallet.deploy, agent_wallet.transfer, agent_wallet.info
+
+Docs: https://tongateway.ai/docs
+GitHub: https://github.com/tongateway/mcp`);
+    process.exit(0);
+}
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    console.log('0.15.0');
+    process.exit(0);
+}
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -69,7 +98,7 @@ const server = new McpServer({
     name: 'agent-gateway',
     version: '0.1.0',
 });
-server.tool('auth.request', '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 auth.get_token to complete. Token persists across restarts.', {
+server.tool('auth.request', 'Authenticate with TON blockchain. Call this tool FIRST if you get "No token configured" errors. It returns a URL that you MUST display to the user as a clickable link. The user opens it in their browser to connect their wallet. After they confirm, call auth.get_token with the authId. Do NOT use curl or fetch — use this MCP tool. Do NOT poll in a loop — just call auth.get_token once after the user says they connected.', {
     label: z.string().optional().describe('Label for this agent session (e.g. "claude-agent")'),
 }, { title: 'Request Authentication', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ label }) => {
     try {
@@ -86,15 +115,15 @@ server.tool('auth.request', 'Authenticate with TON blockchain. Call this FIRST i
                 {
                     type: 'text',
                     text: [
-                        `Authentication requested.`,
+                        `IMPORTANT: Show this link to the user NOW:`,
                         ``,
-                        `Ask the user to open this link:`,
-                        data.authUrl,
+                        `👉 ${data.authUrl}`,
+                        ``,
+                        `Tell the user: "Open this link and connect your wallet. Let me know when done."`,
                         ``,
                         `Auth ID: ${data.authId}`,
-                        `Expires: ${new Date(data.expiresAt).toISOString()}`,
                         ``,
-                        `After the user connects their wallet, call auth.get_token with this authId to get the token.`,
+                        `When the user confirms they connected, call auth.get_token with authId "${data.authId}"`,
                     ].join('\n'),
                 },
             ],
@@ -165,12 +194,13 @@ server.tool('auth.get_token', 'Complete authentication after the user opened the
         };
     }
 });
-server.tool('transfer.request', '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 transfer.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'),
-    stateInit: z.string().optional().describe('Optional stateInit BOC for deploying new contracts'),
-}, { title: 'Request Transfer', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ to, amountNano, payload, stateInit }) => {
+server.tool('transfer.request', 'Send a TON transfer. The user approves in their wallet app. Use human-readable amounts (e.g. amount="1.5"). Supports .ton domain names directly (e.g. to="alice.ton"). The API handles name resolution and decimal conversion automatically.', {
+    to: z.string().describe('Destination: TON address or .ton domain (e.g. "alice.ton" or "EQD...abc")'),
+    amount: z.string().describe('Human-readable amount (e.g. "1.5" for 1.5 TON, "100" for 100 TON)'),
+    comment: z.string().optional().describe('Text comment/message to attach (e.g. "Payment for services")'),
+    payload: z.string().optional().describe('Optional BOC-encoded payload (advanced — use comment for text)'),
+    stateInit: z.string().optional().describe('Optional stateInit BOC for contract deployment'),
+}, { title: 'Request Transfer', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ to, amount, comment, payload, stateInit }) => {
     if (!TOKEN) {
         return {
             content: [{ type: 'text', text: 'No token configured. Use auth.request first to authenticate.' }],
@@ -178,7 +208,9 @@ server.tool('transfer.request', 'Request a TON transfer. The user must approve i
         };
     }
     try {
-        const body = { to, amountNano };
+        const body = { to, amount };
+        if (comment)
+            body.comment = comment;
         if (payload)
             body.payload = payload;
         if (stateInit)
@@ -194,13 +226,13 @@ server.tool('transfer.request', 'Request a TON transfer. The user must approve i
                     text: [
                         `Transfer request created.`,
                         `ID: ${result.id}`,
-                        `To: ${result.to}`,
-                        `Amount: ${result.amountNano} nanoTON`,
+                        `To: ${result.resolved ? `${result.resolved.from} → ${result.resolved.to}` : result.to}`,
+                        `Amount: ${amount} TON (${result.amountNano} nanoTON)`,
                         `Status: ${result.status}`,
-                        `Expires: ${new Date(result.expiresAt).toISOString()}`,
+                        comment ? `Comment: ${comment}` : null,
                         ``,
-                        `The wallet owner must approve this in their TON Connect client.`,
-                    ].join('\n'),
+                        `Approve in your wallet app.`,
+                    ].filter(Boolean).join('\n'),
                 },
             ],
         };
@@ -283,6 +315,56 @@ server.tool('transfer.pending', 'List all transfer requests waiting for wallet o
         };
     }
 });
+server.tool('transfer.batch', 'Send multiple TON transfers in a SINGLE wallet approval. Up to 4 transfers per batch (v4 wallet). All transfers appear as one transaction to sign. Use for batch payments, multi-recipient sends, or multiple DEX orders at once.', {
+    transfers: z.string().describe('JSON array of transfers: [{"to":"addr","amountNano":"1000000000","comment":"optional text"},...]'),
+}, { title: 'Batch Transfer', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ transfers: transfersJson }) => {
+    if (!TOKEN) {
+        return { content: [{ type: 'text', text: 'No token configured. Use auth.request first.' }], isError: true };
+    }
+    try {
+        const transfers = JSON.parse(transfersJson);
+        if (!transfers.length)
+            throw new Error('No transfers provided');
+        if (transfers.length > 4)
+            throw new Error('Max 4 transfers per batch (v4 wallet). Use agent_wallet.batch_transfer for more.');
+        // Encode comments as payloads
+        const processed = [];
+        for (const t of transfers) {
+            const entry = { to: t.to, amountNano: t.amountNano };
+            if (t.comment) {
+                const { beginCell } = await import('@ton/core');
+                const commentCell = beginCell().storeUint(0, 32).storeStringTail(t.comment).endCell();
+                entry.payload = commentCell.toBoc().toString('base64');
+            }
+            processed.push(entry);
+        }
+        const result = await apiCall('/v1/safe/tx/batch', {
+            method: 'POST',
+            body: JSON.stringify({ transfers: processed }),
+        });
+        const totalNano = BigInt(result.batch?.totalNano ?? '0');
+        const totalTon = (totalNano / 1000000000n).toString() + '.' +
+            (totalNano % 1000000000n).toString().padStart(9, '0').replace(/0+$/, '') || '0';
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        `Batch transfer created! ${transfers.length} transfers in 1 approval.`,
+                        '',
+                        `Total: ${totalTon} TON`,
+                        `Request ID: ${result.id}`,
+                        '',
+                        ...transfers.map((t, i) => `  ${i + 1}. ${t.amountNano} nanoTON → ${t.to.slice(0, 16)}...${t.comment ? ` "${t.comment}"` : ''}`),
+                        '',
+                        'Approve in your wallet app — one signature for all transfers.',
+                    ].join('\n'),
+                }],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
+    }
+});
 server.tool('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.', {}, { title: 'Wallet Info', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async () => {
     if (!TOKEN) {
         return { content: [{ type: 'text', text: 'No token configured. Use auth.request first.' }], isError: true };
@@ -413,11 +495,11 @@ server.tool('lookup.price', 'Get the current TON price in USD, EUR, or other cur
         return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
     }
 });
-server.tool('dex.create_order', 'Place a limit order on the open4dev DEX order book. Provide the token pair, amount in smallest units, and price in human-readable format (e.g. price=20 means "1 fromToken = 20 toToken"). The API handles all decimal conversions and slippage automatically. The order requires wallet approval.', {
+server.tool('dex.create_order', 'Place a limit order on the open4dev DEX order book. Both amount and price are human-readable — the API converts to raw units automatically. The order requires wallet approval. Slippage (4% including fees) is applied automatically.', {
     fromToken: z.string().describe('Token to sell, e.g. "NOT", "TON", "USDT"'),
     toToken: z.string().describe('Token to buy, e.g. "TON", "NOT", "AGNT"'),
-    amount: z.string().describe('Amount to sell in smallest unit. TON/NOT/DOGS/BUILD/AGNT use 9 decimals (1 TON = 10^9). USDT/XAUT0 use 6 decimals (1 USDT = 10^6).'),
-    price: z.number().describe('Human-readable price: how many toToken per 1 fromToken. E.g. price=20 means "1 USDT = 20 AGNT". price=0.05 means "1 AGNT = 0.05 USDT".'),
+    amount: z.string().describe('Human-readable amount to sell, e.g. "10000" for 10,000 NOT or "5" for 5 USDT'),
+    price: z.number().describe('Human-readable price: how many toToken per 1 fromToken. E.g. price=20 means "1 USDT = 20 AGNT". price=0.000289 means "1 NOT = 0.000289 TON".'),
 }, { title: 'Create DEX Order', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ fromToken, toToken, amount, price }) => {
     if (!TOKEN) {
         return { content: [{ type: 'text', text: 'No token configured. Use auth.request first.' }], isError: true };
@@ -644,6 +726,107 @@ server.tool('agent_wallet.transfer', 'Send TON directly from an Agent Wallet —
         return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
     }
 });
+server.tool('agent_wallet.batch_transfer', 'Send multiple TON transfers in a SINGLE transaction from an Agent Wallet — NO approval needed. All transfers are executed atomically in one external message. Max 255 actions per transaction.', {
+    walletAddress: z.string().describe('The agent wallet contract address'),
+    transfers: z.string().describe('JSON array of transfers: [{"to":"addr","amountNano":"1000000000"},...]'),
+}, { title: 'Batch Transfer from Agent Wallet', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }, async ({ walletAddress, transfers: transfersJson }) => {
+    if (!TOKEN) {
+        return { content: [{ type: 'text', text: 'No token configured. Use auth.request first.' }], isError: true };
+    }
+    try {
+        const { Cell, beginCell, Address, SendMode, external, storeMessage } = await import('@ton/core');
+        const { sign, keyPairFromSeed } = await import('@ton/crypto');
+        const transfers = JSON.parse(transfersJson);
+        if (!transfers.length)
+            throw new Error('No transfers provided');
+        if (transfers.length > 255)
+            throw new Error('Max 255 transfers per batch');
+        const localWallets = loadLocalWallets();
+        const localConfig = localWallets[walletAddress];
+        if (!localConfig)
+            throw new Error('Agent wallet secret key not found locally.');
+        const infoResult = await apiCall(`/v1/agent-wallet/${encodeURIComponent(walletAddress)}/info`);
+        const seqno = infoResult.seqno;
+        const walletId = localConfig.walletId;
+        const secretKeyBuf = Buffer.from(localConfig.agentSecretKey, 'hex');
+        let secretKey;
+        if (secretKeyBuf.length === 64) {
+            secretKey = secretKeyBuf;
+        }
+        else {
+            const kp = keyPairFromSeed(secretKeyBuf);
+            secretKey = kp.secretKey;
+        }
+        // Build actions list with all transfers
+        const sendMode = SendMode.PAY_GAS_SEPARATELY + SendMode.IGNORE_ERRORS;
+        let actionsList = beginCell().endCell(); // empty tail
+        for (const t of transfers) {
+            const destAddr = Address.parse(t.to);
+            const transferMsg = beginCell()
+                .storeUint(0x18, 6)
+                .storeAddress(destAddr)
+                .storeCoins(BigInt(t.amountNano))
+                .storeUint(0, 1 + 4 + 4 + 64 + 32 + 1 + 1)
+                .endCell();
+            actionsList = beginCell()
+                .storeRef(actionsList)
+                .storeUint(0x0ec3c86d, 32)
+                .storeUint(sendMode, 8)
+                .storeRef(transferMsg)
+                .endCell();
+        }
+        // Build and sign external message
+        const validUntil = Math.floor(Date.now() / 1000) + 300;
+        const unsignedBody = beginCell()
+            .storeUint(0x7369676e, 32)
+            .storeUint(walletId, 32)
+            .storeUint(validUntil, 32)
+            .storeUint(seqno, 32)
+            .storeMaybeRef(actionsList)
+            .endCell();
+        const signature = sign(unsignedBody.hash(), secretKey);
+        const signedBody = beginCell()
+            .storeSlice(unsignedBody.beginParse())
+            .storeBuffer(signature)
+            .endCell();
+        const vaultAddr = Address.parse(walletAddress);
+        const extMsg = external({ to: vaultAddr, body: signedBody });
+        const boc = beginCell().store(storeMessage(extMsg)).endCell().toBoc().toString('base64');
+        // Broadcast
+        const broadcastRes = await fetch('https://toncenter.com/api/v2/sendBoc', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ boc }),
+        });
+        const broadcastData = await broadcastRes.json();
+        if (!broadcastData.ok) {
+            throw new Error(`Broadcast failed: ${broadcastData.error || JSON.stringify(broadcastData)}`);
+        }
+        const totalNano = transfers.reduce((sum, t) => sum + BigInt(t.amountNano), 0n);
+        const totalTon = (totalNano / 1000000000n).toString() + '.' +
+            (totalNano % 1000000000n).toString().padStart(9, '0').replace(/0+$/, '');
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        `Batch transfer executed! ${transfers.length} transfers in 1 transaction.`,
+                        '',
+                        `From: ${walletAddress}`,
+                        `Total: ${totalTon} TON`,
+                        `Transfers: ${transfers.length}`,
+                        `Seqno: ${seqno}`,
+                        '',
+                        ...transfers.map((t, i) => `  ${i + 1}. ${t.amountNano} nanoTON → ${t.to.slice(0, 12)}...`),
+                        '',
+                        'All broadcast successfully. No approval needed.',
+                    ].join('\n'),
+                }],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
+    }
+});
 server.tool('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.'),
 }, { title: 'Agent Wallet Info', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async ({ walletAddress }) => {

package/dist/worker.js

@@ -32,10 +32,10 @@ function createMcpServer() {
     server.tool('lookup.resolve_name', 'Resolve a .ton domain name (e.g. "alice.ton") to a raw wallet address. Always use this before transfer.request when the user provides a .ton name.', { domain: z.string().describe('The .ton domain name to resolve, e.g. "alice.ton" or "foundation.ton"') }, { title: 'Resolve .ton Name', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async () => ({ content: [{ type: 'text', text: 'Use stdio transport for full tool execution.' }] }));
     server.tool('lookup.price', 'Get the current price of TON in USD, EUR, or other fiat currencies. Use to show users the value of their holdings.', { currencies: z.string().optional().describe('Comma-separated currency codes, e.g. "USD,EUR". Default: "USD"') }, { title: 'TON Price', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async () => ({ content: [{ type: 'text', text: 'Use stdio transport for full tool execution.' }] }));
     // --- DEX ---
-    server.tool('dex.create_order', 'Place a limit order on the open4dev DEX order book. Provide token pair, amount in smallest units, and human-readable price. The API handles decimal conversion, slippage (4% including fees), and gas automatically.', {
+    server.tool('dex.create_order', 'Place a limit order on the open4dev DEX order book. Both amount and price are human-readable. The API converts to raw units, handles slippage (4% including fees), and gas automatically.', {
         fromToken: z.string().describe('Token to sell: TON, NOT, USDT, DOGS, BUILD, AGNT, CBBTC, PX, XAUT0'),
         toToken: z.string().describe('Token to buy: TON, NOT, USDT, DOGS, BUILD, AGNT, CBBTC, PX, XAUT0'),
-        amount: z.string().describe('Amount to sell in smallest unit. TON/NOT/DOGS/BUILD/AGNT use 9 decimals. USDT/XAUT0 use 6 decimals.'),
+        amount: z.string().describe('Human-readable amount to sell, e.g. "10000" for 10,000 NOT or "5" for 5 USDT'),
         price: z.number().describe('Human-readable price: how many toToken per 1 fromToken. E.g. price=20 means "1 USDT = 20 AGNT".'),
     }, { title: 'Create DEX Order', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async () => ({ content: [{ type: 'text', text: 'Use stdio transport for full tool execution.' }] }));
     server.tool('dex.pairs', 'List all available trading pairs and tokens on the open4dev DEX. Returns supported tokens: TON, NOT, USDT, DOGS, BUILD, AGNT, CBBTC, PX, XAUT0.', {}, { title: 'DEX Pairs', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async () => ({ content: [{ type: 'text', text: 'Use stdio transport for full tool execution.' }] }));
@@ -53,16 +53,138 @@ function createMcpServer() {
                 role: 'user',
                 content: {
                     type: 'text',
-                    text: 'Install: npx -y @tongateway/mcp\n\nClaude Code: claude mcp add-json tongateway \'{"command":"npx","args":["-y","@tongateway/mcp"],"env":{"AGENT_GATEWAY_API_URL":"https://api.tongateway.ai"}}\' --scope user\n\nThen say: "Send 1 TON to alice.ton"',
+                    text: `# Quick Start
+
+## Install
+\`\`\`bash
+claude mcp add-json tongateway '{"command":"npx","args":["-y","@tongateway/mcp"],"env":{"AGENT_GATEWAY_API_URL":"https://api.tongateway.ai"}}' --scope user
+\`\`\`
+
+## First use
+The agent authenticates automatically — it generates a link, you open it and connect your wallet once. Token persists across restarts.
+
+## Try these commands:
+- "What's my TON balance?"
+- "Show my tokens"
+- "Send 1 TON to alice.ton"
+- "What's the current TON price?"
+- "Show my NFTs"`,
                 },
             }],
     }));
-    server.prompt('token-reference', 'Amount conversion reference for TON blockchain', async () => ({
+    server.prompt('token-reference', 'Amount conversion and token decimals reference', async () => ({
         messages: [{
                 role: 'user',
                 content: {
                     type: 'text',
-                    text: 'TON amounts are in nanoTON (1 TON = 10^9 nanoTON):\n0.1 TON = 100000000\n0.5 TON = 500000000\n1 TON = 1000000000\n10 TON = 10000000000\n\nUSDT/XAUT0 use 6 decimals. All other jettons use 9 decimals.',
+                    text: `# Token Reference
+
+## Amount conversion (nanoTON)
+| TON   | nanoTON        |
+|-------|----------------|
+| 0.1   | 100000000      |
+| 0.5   | 500000000      |
+| 1     | 1000000000     |
+| 10    | 10000000000    |
+
+## Token decimals
+- 9 decimals: TON, NOT, DOGS, BUILD, AGNT, PX, CBBTC
+- 6 decimals: USDT, XAUT0
+
+## DEX price format
+Price is human-readable: price=20 means "1 fromToken = 20 toToken"
+Example: USDT→AGNT at price=20 means "1 USDT = 20 AGNT"`,
+                },
+            }],
+    }));
+    server.prompt('example-transfer', 'Example: Send TON to a .ton domain with price check', async () => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `# Example: Send TON to alice.ton
+
+## Step 1: Check balance
+wallet.info()
+→ Address: 0:9d43...0c02, Balance: 823.18 TON, Status: active
+
+## Step 2: Check price
+lookup.price({ currencies: "USD" })
+→ 1 TON = $2.45 USD
+
+## Step 3: Resolve .ton domain
+lookup.resolve_name({ domain: "alice.ton" })
+→ alice.ton → 0:83df...31a8
+
+## Step 4: Send transfer
+transfer.request({ to: "0:83df...31a8", amountNano: "500000000" })
+→ Transfer request created (ID: abc-123). Approve in your wallet app.
+
+## Step 5: Check status
+transfer.status({ id: "abc-123" })
+→ Status: confirmed, Broadcast: success`,
+                },
+            }],
+    }));
+    server.prompt('example-dex-order', 'Example: Place a DEX order to swap tokens', async () => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `# Example: Swap 10,000 NOT for TON
+
+## Step 1: Check available tokens
+dex.pairs()
+→ Available tokens: TON, NOT, USDT, DOGS, BUILD, AGNT, CBBTC, PX, XAUT0
+
+## Step 2: Check your NOT balance
+wallet.jettons()
+→ NOT: 3,186,370.60, USDT: 107.79, BUILD: 45,277.57
+
+## Step 3: Get current price
+lookup.price({ currencies: "USD" })
+→ 1 TON = $2.45 USD
+(NOT ≈ 0.000289 TON per NOT)
+
+## Step 4: Place order
+dex.create_order({
+  fromToken: "NOT",
+  toToken: "TON",
+  amount: "10000",  // human-readable, API converts to raw
+  price: 0.000289            // TON per NOT
+})
+→ Order placed! Approve in your wallet app.`,
+                },
+            }],
+    }));
+    server.prompt('example-agent-wallet', 'Example: Deploy and use an autonomous Agent Wallet', async () => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `# Example: Autonomous Agent Wallet
+
+⚠️ WARNING: Agent Wallet allows spending WITHOUT approval!
+
+## Step 1: Deploy
+agent_wallet.deploy()
+→ Agent Wallet deployed at EQCT1... Approve 0.1 TON deploy fee in wallet.
+
+## Step 2: Top up
+transfer.request({ to: "EQCT1...", amountNano: "1000000000" })
+→ Transfer 1 TON to agent wallet. Approve in wallet.
+
+## Step 3: Send from agent wallet (NO approval needed!)
+agent_wallet.transfer({
+  walletAddress: "0:93d4...",
+  to: "0:abc...",
+  amountNano: "500000000"
+})
+→ Transfer executed. No approval needed.
+
+## Check balance
+agent_wallet.info({ walletAddress: "0:93d4..." })
+→ Balance: 0.5 TON, Seqno: 1, Status: active`,
                 },
             }],
     }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tongateway/mcp",
-  "version": "0.14.0",
+  "version": "0.19.2",
   "description": "TON blockchain gateway for AI agents — 16 MCP tools: wallet info, transfers, jettons, NFTs, DNS, prices, DEX orders, agent wallets",
   "homepage": "https://tongateway.ai",
   "license": "MIT",
@@ -25,7 +25,8 @@
   ],
   "scripts": {
     "build": "tsc",
-    "dev": "tsx src/index.ts"
+    "dev": "tsx src/index.ts",
+    "test": "vitest run"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
@@ -38,6 +39,7 @@
     "@types/node": "^22.17.2",
     "tsx": "^4.20.5",
     "typescript": "^5.9.2",
+    "vitest": "^4.1.1",
     "wrangler": "^4.77.0"
   }
 }