@ton/mcp 0.1.15-alpha.0 → 0.1.15-alpha.2

package/README.md

@@ -4,60 +4,73 @@ A Model Context Protocol (MCP) server for TON blockchain wallet operations. Buil
 
 ## Features
 
-- **Balance Queries**: Check TON and Jetton balances, view transaction history
-- **Transfers**: Send TON, Jettons, and NFTs to any address
-- **Agentic Sub-wallet Deploy**: Deploy additional Agentic wallets from a root Agentic wallet
-- **Swaps**: Get quotes for token swaps via DEX aggregators
-- **NFTs**: List, inspect, and transfer NFTs
-- **DNS**: Resolve TON DNS-compatible domains and reverse-lookup addresses
-- **Known Jettons**: Built-in directory of popular tokens
-- **Wallet Registry Mode**: Work with multiple stored wallets, active wallet selection, and local config-backed management tools
-- **Agentic Onboarding**: Start and complete first root-agent wallet setup from MCP
-- **Multiple Transports**: Stdio (default), multi-session HTTP server, and serverless modes
+- **Balance Queries**: Check TON and Jetton balances, view transaction history.
+- **Transfers**: Send TON, Jettons, and NFTs to any address.
+- **Swaps**: Get quotes for token swaps via DEX aggregators.
+- **NFTs**: List, inspect, and transfer NFTs.
+- **DNS**: Resolve TON DNS-compatible domains and reverse-lookup addresses.
+- **Known Jettons**: Built-in directory of popular tokens.
+- **Agentic Wallets**: Manage agentic wallets. Create, import, or manage your agentic wallets.
+- **Multiple Transports**: Stdio (default), multi-session HTTP server, and serverless modes.
 
 ## Quick Start
 
 `@ton/mcp` supports two runtime modes.
 
-- **Registry mode**: if `MNEMONIC` and `PRIVATE_KEY` are not set, the server starts from local config registry at `~/.config/ton/config.json` or `TON_CONFIG_PATH`
+- **Agentic Wallets mode**: Server starts from local config registry at `~/.config/ton/config.json` or `TON_CONFIG_PATH`
 - **Single-wallet mode**: if `MNEMONIC` or `PRIVATE_KEY` is set, the server starts with one in-memory wallet
 
+### Agentic Wallets mode
+
+Self-custody wallets for autonomous agents. Your AI agent gets TON wallet capabilities — transfers, swaps, NFTs. User keeps the master key, agent keeps the operator key.
+
+**Learn more about [Agentic Wallets](https://agentic-wallets-dashboard.vercel.app/).**
+
+Agentic Wallets mode is the default mode that allows you to manage agentic wallets. To create your first agentic wallet, ask your agent to `create agentic wallet` and follow the instructions.
+
 ```bash
-# Run as stdio MCP server in registry mode
-npx @ton/mcp
+# Install skills (recommended)
+npx skills add ton-connect/kit/packages/mcp
+
+# Run as stdio MCP server in agentic mode
+npx @ton/mcp@alpha
+
+# Run as HTTP server in agentic mode
+npx @ton/mcp@alpha --http
 
 # Run in registry mode with a custom config path
-TON_CONFIG_PATH=/path/to/config.json npx @ton/mcp
+TON_CONFIG_PATH=/path/to/config.json npx @ton/mcp@alpha
+```
+
+### Single-wallet mode
 
+Single-wallet mode is a mode where the server starts with one in-memory wallet. This mode is useful when you want to manage a single wallet or when you want to use the server for a one-off task.
+
+```bash
 # Run as stdio MCP server with mnemonic
-MNEMONIC="word1 word2 ..." npx @ton/mcp
+MNEMONIC="word1 word2 ..." npx @ton/mcp@alpha
 
 # Run as HTTP server (port 3000)
-npx @ton/mcp --http
+MNEMONIC="word1 word2 ..." npx @ton/mcp@alpha --http
 
-# Run as HTTP server on custom port
-npx @ton/mcp --http 8080
-
-# Run with custom agentic wallet contract
-PRIVATE_KEY="0xyour_private_key" \
-WALLET_VERSION="agentic" \
-AGENTIC_WALLET_ADDRESS="EQ..." \
-npx @ton/mcp
+# Run as HTTP server on custom port and private key
+PRIVATE_KEY="0xyour_private_key" npx @ton/mcp@alpha --http 8080
 ```
 
 ## Usage with MCP Clients
 
 ### Claude Desktop / Cursor
 
-Registry mode:
+Agentic Wallets mode:
 
 ```json
 {
   "mcpServers": {
     "ton": {
       "command": "npx",
-      "args": ["-y", "@ton/mcp"],
+      "args": ["-y", "@ton/mcp@alpha"],
       "env": {
+        "// optional config path": "",
         "TON_CONFIG_PATH": "/absolute/path/to/config.json"
       }
     }
@@ -72,7 +85,7 @@ Single-wallet mode:
   "mcpServers": {
     "ton": {
       "command": "npx",
-      "args": ["-y", "@ton/mcp"],
+      "args": ["-y", "@ton/mcp@alpha"],
       "env": {
         "MNEMONIC": "word1 word2 word3 ...",
         "PRIVATE_KEY": "0xyour_private_key_here (optional, alternative to MNEMONIC)"
@@ -87,7 +100,7 @@ Single-wallet mode:
 Start the server and point your MCP client to the endpoint:
 
 ```bash
-npx @ton/mcp --http 3000
+npx @ton/mcp@alpha --http 3000
 # MCP endpoint: http://localhost:3000/mcp
 ```
 
@@ -99,10 +112,10 @@ HTTP mode keeps a separate MCP session/transport per client session id, so multi
 |-------------------|-----------|-------------------------------------------------------|
 | `NETWORK` | `mainnet` | TON network (`mainnet` / `testnet`) and default env override target for `TONCENTER_API_KEY` |
 | `MNEMONIC` |  | Space-separated 24-word mnemonic phrase for single-wallet mode |
-| `PRIVATE_KEY` |  | Hex-encoded private key: 32-byte seed or 64-byte `private||public` (alternative to mnemonic) |
+| `PRIVATE_KEY` |  | Hex-encoded private key: 32-byte or 64-byte (alternative to mnemonic) |
 | `WALLET_VERSION` | `v5r1` | Wallet version to use in single-wallet mode (`v5r1`, `v4r2`, or `agentic`) |
 | `AGENTIC_WALLET_ADDRESS` |  | Agentic wallet address (required for `WALLET_VERSION=agentic`, unless derived from init params) |
-| `AGENTIC_WALLET_NFT_INDEX` |  | Agentic wallet NFT index / subwallet id (`uint256`, optional) |
+| `AGENTIC_WALLET_NFT_INDEX` |  | Agentic wallet NFT index (`uint256`, optional) |
 | `AGENTIC_COLLECTION_ADDRESS` | `EQByQ19qvWxW7VibSbGEgZiYMqilHY5y1a_eeSL2VaXhfy07` | Agentic collection address override for single-wallet mode |
 | `TONCENTER_API_KEY` |  | API key for Toncenter (optional, for higher rate limits) |
 | `TON_CONFIG_PATH` | `~/.config/ton/config.json` | Config path for registry mode |
@@ -222,16 +235,6 @@ Send a raw transaction with full control over messages. Supports multiple messag
 - `validUntil` (optional): Unix timestamp after which the transaction becomes invalid
 - `fromAddress` (optional): Sender wallet address
 
-#### `agentic_deploy_subwallet`
-Deploy a new Agentic sub-wallet from the current wallet. Works only with an agentic root wallet that can sign and only when the current wallet is a user-root wallet (`deployedByUser=true`). Returns `normalizedHash`, deployed sub-wallet address, and computed sub-wallet NFT index. NFT metadata is written in onchain TEP-64 format.
-
-**Default flow:** Poll `get_transaction_status` with the returned `normalizedHash` until completion.
-
-**Parameters:**
-- `operatorPublicKey` (required): New sub-wallet operator public key (`uint256`, decimal or `0x`-prefixed hex)
-- `metadata` (required): Onchain TEP-64 metadata object. Must include at least `name` (non-empty string).
-- `amountTon` (optional): TON amount to attach for deployment in TON units (default: `"0.05"`)
-
 ### Swaps
 
 #### `get_swap_quote`

package/bin/mcp.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const binDir = path.dirname(fileURLToPath(import.meta.url));
+const cliEntrypoint = path.resolve(binDir, '../dist/cli.js');
+
+if (!existsSync(cliEntrypoint)) {
+    process.stderr.write(
+        'The @ton/mcp CLI has not been built yet. Run `pnpm --filter @ton/mcp build` from the workspace root and retry.\n',
+    );
+    process.exit(1);
+}
+
+await import(pathToFileURL(cliEntrypoint).href);