@ton/mcp 0.1.10 → 0.1.12

package/README.md

@@ -4,26 +4,27 @@ A Model Context Protocol (MCP) server for TON blockchain wallet operations. Buil
 
 ## Features
 
-- **Balance Queries**: Check TON and Jetton balances, list all tokens
-- **Transaction History**: View recent transactions with detailed info
-- **Transfers**: Send TON, Jettons, and NFTs
-- **Swaps**: Get quotes and execute token swaps via DEX
-- **NFT Support**: List, view details, and transfer NFTs
-- **DNS Resolution**: Resolve .ton domains and reverse lookup addresses
-- **Dual Transport**: Stdio (default) and HTTP server modes
-- **Serverless Support**: Deploy to AWS Lambda, Vercel, etc.
+- **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` domains and reverse-lookup addresses
+- **Known Jettons**: Built-in directory of popular tokens
+- **Multiple Transports**: Stdio (default), HTTP server, and serverless modes
 
 ## Quick Start
 
+> **Note:** We currently do not support launch without a mnemonic or private key.
+
 ```bash
-# Run with mnemonic (full control)
-MNEMONIC="word1 word2 ... word24" npx @ton/mcp
+# Run as stdio MCP server
+MNEMONIC="word1 word2 ..." npx @ton/mcp
 
-# Run as HTTP server
-MNEMONIC="word1 word2 ... word24" npx @ton/mcp --http
+# Run as HTTP server (port 3000)
+MNEMONIC="word1 word2 ..." npx @ton/mcp --http
 
-# Run on custom port and host
-MNEMONIC="word1 word2 ... word24" npx @ton/mcp --http 8080 --host 127.0.0.1
+# Run as HTTP server on custom port
+MNEMONIC="word1 word2 ..." npx @ton/mcp --http 8080
 ```
 
 ## Usage with MCP Clients
@@ -37,50 +38,45 @@ Add to your MCP configuration:
   "mcpServers": {
     "ton": {
       "command": "npx",
-      "args": ["@ton/mcp"],
+      "args": ["-y", "@ton/mcp"],
       "env": {
-        "MNEMONIC": "word1 word2 ... word24",
-        "NETWORK": "mainnet"
+        "MNEMONIC": "word1 word2 word3 ...",
+        "PRIVATE_KEY": "0xyour_private_key_here (optional, alternative to MNEMONIC)"
       }
     }
   }
 }
 ```
 
-### HTTP Mode
+### HTTP mode
 
 Start the server and point your MCP client to the endpoint:
 
 ```bash
-MNEMONIC="..." npx @ton/mcp --http 3000
+MNEMONIC="word1 word2 ..." npx @ton/mcp --http 3000
 # MCP endpoint: http://localhost:3000/mcp
 ```
 
 ## Environment Variables
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `MNEMONIC` | - | 24-word mnemonic phrase (required for mnemonic mode) |
-| `NETWORK` | `mainnet` | TON network (`mainnet` / `testnet`) |
-| `WALLET_VERSION` | `v5r1` | Wallet version (`v5r1` / `v4r2`) |
-| `WALLET_ADDRESS` | - | User's wallet address (for controlled wallet mode) |
-| `TONCENTER_API_KEY` | - | Optional TonCenter API key for higher rate limits |
+| Variable          | Default   | Description                                           |
+|-------------------|-----------|-------------------------------------------------------|
+| `NETWORK`         | `mainnet` | TON network (`mainnet` / `testnet`)                   |
+| `MNEMONIC`        |           | Space-separated 24-word mnemonic phrase for wallet    |
+| `PRIVATE_KEY`     |           | Hex-encoded private key (alternative to mnemonic)     |
+| `WALLET_VERSION`  | `v5r1`    | Wallet version to use (`v5r1` or `v4r2`)              |
+| `TONCENTER_API_KEY`|          | API key for Toncenter (optional, for higher rate limits)|
 
-## Wallet Modes
+## Available Tools
 
-### Mnemonic Mode (Default)
-Provide a `MNEMONIC` environment variable to use traditional wallet control with full signing capabilities.
+### Wallet Info
 
-### Controlled Wallet Mode
-When `MNEMONIC` is not provided, the MCP operates in controlled wallet mode:
-1. Checks for existing keypair in `~/.ton/key.json`
-2. If not found, requires `WALLET_ADDRESS` and generates a new keypair
-3. Stores the keypair for future use
-4. Uses this keypair to sign transactions (requires wallet to authorize the public key)
+#### `get_wallet`
+Get the current wallet address and network information.
 
-## Available Tools
+**Returns:** Wallet address and network (`mainnet` or `testnet`)
 
-### Balance & Info
+### Balance & History
 
 #### `get_balance`
 Get the TON balance of the wallet.
@@ -88,126 +84,150 @@ Get the TON balance of the wallet.
 **Returns:** Balance in TON and nanoTON
 
 #### `get_jetton_balance`
-Get the balance of a specific Jetton.
+Get the balance of a specific Jetton in the wallet.
 
 **Parameters:**
 - `jettonAddress` (required): Jetton master contract address
 
 #### `get_jettons`
-List all Jettons in the wallet with balances and metadata.
+List all Jettons held by the wallet with balances and metadata.
 
 #### `get_transactions`
-Get recent transaction history.
+Get recent transaction history for the wallet (TON transfers, Jetton transfers, swaps, etc.).
 
 **Parameters:**
-- `limit` (optional): Max transactions to return (default: 20, max: 100)
-
-**Returns:** Transaction events including TON transfers, Jetton transfers, swaps
-
-#### `get_known_jettons`
-Get a list of known/popular Jettons on TON with their addresses and metadata.
+- `limit` (optional): Maximum number of transactions to return (default: 20, max: 100)
 
 ### Transfers
 
 #### `send_ton`
-Send TON to an address.
+Send TON to an address. Amount is in human-readable format (e.g., `"1.5"` means 1.5 TON).
 
 **Parameters:**
 - `toAddress` (required): Recipient TON address
-- `amount` (required): Amount in TON (e.g., "1.5" for 1.5 TON)
+- `amount` (required): Amount in TON (e.g., `"1.5"`)
 - `comment` (optional): Transaction comment/memo
 
 #### `send_jetton`
-Send Jettons to an address.
+Send Jettons to an address. Amount is in human-readable format.
 
 **Parameters:**
 - `toAddress` (required): Recipient TON address
 - `jettonAddress` (required): Jetton master contract address
-- `amount` (required): Amount in human-readable format
+- `amount` (required): Amount in human-readable format (e.g., `"100"`)
 - `comment` (optional): Transaction comment/memo
 
 #### `send_raw_transaction`
-Send a raw transaction with full control over messages.
+Send a raw transaction with full control over messages. Supports multiple messages in a single transaction.
 
 **Parameters:**
-- `messages` (required): Array of messages with `address`, `amount` (nanoTON), optional `stateInit` and `payload` (Base64)
-- `validUntil` (optional): Unix timestamp for transaction expiry
+- `messages` (required): Array of messages, each with:
+  - `address` (required): Recipient wallet address
+  - `amount` (required): Amount in nanotons
+  - `stateInit` (optional): Initial state for deploying a contract (Base64)
+  - `payload` (optional): Message payload data (Base64)
+- `validUntil` (optional): Unix timestamp after which the transaction becomes invalid
 - `fromAddress` (optional): Sender wallet address
 
 ### Swaps
 
 #### `get_swap_quote`
-Get a quote for swapping tokens.
+Get a quote for swapping tokens. Returns quote details and transaction params that can be executed via `send_raw_transaction`.
 
 **Parameters:**
-- `fromToken` (required): Token to swap from ("TON" or jetton address)
-- `toToken` (required): Token to swap to ("TON" or jetton address)
-- `amount` (required): Amount to swap in raw units
+- `fromToken` (required): Token to swap from (`"TON"` or jetton address)
+- `toToken` (required): Token to swap to (`"TON"` or jetton address)
+- `amount` (required): Amount in human-readable format (e.g., `"1.5"` for 1.5 TON)
 - `slippageBps` (optional): Slippage tolerance in basis points (default: 100 = 1%)
 
-**Returns:** Quote details and transaction params for `send_raw_transaction`
-
 ### NFTs
 
 #### `get_nfts`
-List all NFTs in the wallet.
+List all NFTs in the wallet with metadata, collection info, and attributes.
 
 **Parameters:**
-- `limit` (optional): Max NFTs to return (default: 20, max: 100)
-- `offset` (optional): Pagination offset (default: 0)
+- `limit` (optional): Maximum number of NFTs to return (default: 20, max: 100)
+- `offset` (optional): Offset for pagination (default: 0)
 
 #### `get_nft`
-Get detailed information about a specific NFT.
+Get detailed information about a specific NFT by its address.
 
 **Parameters:**
 - `nftAddress` (required): NFT item contract address
 
 #### `send_nft`
-Transfer an NFT to another address.
+Transfer an NFT from the wallet to another address.
 
 **Parameters:**
-- `nftAddress` (required): NFT item contract address
+- `nftAddress` (required): NFT item contract address to transfer
 - `toAddress` (required): Recipient TON address
 - `comment` (optional): Transaction comment/memo
 
 ### DNS
 
 #### `resolve_dns`
-Resolve a TON DNS domain to a wallet address.
+Resolve a TON DNS domain (e.g., `"foundation.ton"`) to a wallet address.
 
 **Parameters:**
-- `domain` (required): TON DNS domain (e.g., "foundation.ton")
+- `domain` (required): TON DNS domain to resolve
 
 #### `back_resolve_dns`
-Reverse resolve a wallet address to its DNS domain.
+Reverse-resolve a TON wallet address to its `.ton` domain.
 
 **Parameters:**
-- `address` (required): TON wallet address
+- `address` (required): TON wallet address to reverse resolve
+
+### Utility
+
+#### `get_known_jettons`
+Get a list of known/popular Jettons on TON with their addresses and metadata. Useful for looking up token addresses for swaps or transfers.
 
 ## Serverless Deployment
 
-The package exports a serverless handler for deployment to AWS Lambda, Vercel, etc.
+The package exports a `@ton/mcp/serverless` entry point for deploying as a serverless function (AWS Lambda, Vercel, Cloudflare Workers, etc.). Credentials are passed via request headers instead of environment variables.
+
+### Headers
+
+| Header          | Description                                              |
+|-----------------|----------------------------------------------------------|
+| `MNEMONIC`      | 24-word mnemonic phrase                                  |
+| `PRIVATE_KEY`   | Hex-encoded private key (takes priority over `MNEMONIC`) |
+| `NETWORK`       | `mainnet` (default) or `testnet`                         |
+| `TONCENTER_KEY` | Optional TonCenter API key for higher rate limits        |
+
+### AWS Lambda
 
 ```typescript
-// AWS Lambda
 import { createServerlessHandler } from '@ton/mcp/serverless';
+
 export const handler = createServerlessHandler();
+```
 
-// Vercel
+### Vercel
+
+```typescript
 import { createServerlessHandler } from '@ton/mcp/serverless';
+
 export default createServerlessHandler();
 ```
 
-### Serverless Headers
+### Custom Integration
 
-Pass credentials via request headers:
+```typescript
+import { createServerlessHandler } from '@ton/mcp/serverless';
 
-| Header | Description |
-|--------|-------------|
-| `MNEMONIC` or `mnemonic` | 24-word mnemonic phrase |
-| `PRIVATE_KEY` or `private-key` | Hex-encoded private key (priority over mnemonic) |
-| `NETWORK` or `network` | Network (`mainnet` / `testnet`) |
-| `TONCENTER_KEY` or `toncenter-key` | Optional TonCenter API key |
+const handle = createServerlessHandler();
+
+const response = await handle({
+  method: 'POST',
+  url: '/mcp',
+  headers: {
+    'MNEMONIC': 'word1 word2 word3 ...',
+    'NETWORK': 'mainnet',
+  },
+  body: mcpRequestBody,
+});
+```
 
 ## Development
 
@@ -228,55 +248,32 @@ node packages/mcp/dist/cli.js --http 8080
 
 ## Library Usage
 
-The package exports a programmatic API for building custom MCP servers:
+The package also exports a programmatic API for building custom MCP servers:
 
 ```typescript
 import { createTonWalletMCP } from '@ton/mcp';
-import { Signer, WalletV5R1Adapter, TonWalletKit, Network, MemoryStorageAdapter } from '@ton/walletkit';
+import { Signer, WalletV5R1Adapter, TonWalletKit, MemoryStorageAdapter, Network } from '@ton/walletkit';
 
-// Initialize kit
+// Initialize TonWalletKit
+const network = Network.mainnet();
 const kit = new TonWalletKit({
-  networks: { [Network.mainnet().chainId]: {} },
+  networks: { [network.chainId]: {} },
   storage: new MemoryStorageAdapter(),
 });
 await kit.waitForReady();
 
-// Create wallet adapter
+// Create wallet from mnemonic
 const signer = await Signer.fromMnemonic(mnemonic, { type: 'ton' });
 const walletAdapter = await WalletV5R1Adapter.create(signer, {
-  client: kit.getApiClient(Network.mainnet()),
-  network: Network.mainnet(),
+  client: kit.getApiClient(network),
+  network,
 });
 const wallet = await kit.addWallet(walletAdapter);
 
 // Create MCP server
 const server = await createTonWalletMCP({ wallet });
-
-// Connect to transport
-const transport = new StdioServerTransport();
-await server.connect(transport);
 ```
 
-## Agent Skills
-
-This package includes skill files for AI agent integration:
-
-- **`skills/SKILL.md`** - Concise skill description for Claude Code and compatible agents
-- **`llms.txt`** - Detailed tool documentation for LLM context
-
-### Using with Claude Code
-
-Copy the skill to your project:
-
-```bash
-mkdir -p .claude/skills/ton-wallet
-cp node_modules/@ton/mcp/skills/SKILL.md .claude/skills/ton-wallet/
-```
-
-### Using llms.txt
-
-The `llms.txt` file follows the [llms.txt standard](https://llmstxt.org/) and can be used to provide context to any LLM about the available tools.
-
 ## License
 
 MIT