@truecarry/mcp 0.1.7 → 0.1.8

package/README.md

@@ -4,23 +4,26 @@ A Model Context Protocol (MCP) server for TON blockchain wallet operations. Buil
 
 ## Features
 
-- **Wallet Management**: Create, import, list, and remove TON wallets
-- **Balance Queries**: Check TON and Jetton balances
-- **Transfers**: Send TON and Jettons to any address
-- **Swaps**: Get quotes and execute token swaps
+- **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.
 
 ## Quick Start
 
 ```bash
-# Run as stdio MCP server
-npx @ton/mcp
+# Run with mnemonic (full control)
+MNEMONIC="word1 word2 ... word24" npx @ton/mcp
 
-# Run as HTTP server (port 3000)
-npx @ton/mcp --http
+# Run as HTTP server
+MNEMONIC="word1 word2 ... word24" npx @ton/mcp --http
 
-# Run as HTTP server on custom port
-npx @ton/mcp --http 8080
+# Run on custom port and host
+MNEMONIC="word1 word2 ... word24" npx @ton/mcp --http 8080 --host 127.0.0.1
 ```
 
 ## Usage with MCP Clients
@@ -34,79 +37,75 @@ Add to your MCP configuration:
   "mcpServers": {
     "ton": {
       "command": "npx",
-      "args": ["@ton/mcp"]
+      "args": ["@ton/mcp"],
+      "env": {
+        "MNEMONIC": "word1 word2 ... word24",
+        "NETWORK": "mainnet"
+      }
     }
   }
 }
 ```
 
-### HTTP mode
+### HTTP Mode
 
 Start the server and point your MCP client to the endpoint:
 
 ```bash
-npx @ton/mcp --http 3000
+MNEMONIC="..." npx @ton/mcp --http 3000
 # MCP endpoint: http://localhost:3000/mcp
 ```
 
 ## Environment Variables
 
-| Variable  | Default   | Description                  |
-|-----------|-----------|------------------------------|
+| 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 |
 
-## Available Tools
-
-### Wallet Management
-
-#### `create_wallet`
-Create a new TON wallet with a generated 24-word mnemonic.
-
-**Parameters:**
-- `name` (required): Unique name for the wallet
-- `version` (optional): Wallet version - `v5r1` (default, recommended) or `v4r2`
-
-**Returns:** Wallet address and mnemonic (save securely!)
-
-#### `import_wallet`
-Import an existing wallet using a mnemonic phrase.
+## Wallet Modes
 
-**Parameters:**
-- `name` (required): Unique name for the wallet
-- `mnemonic` (required): 24-word mnemonic phrase (space-separated)
-- `version` (optional): Wallet version - `v5r1` (default) or `v4r2`
-
-#### `list_wallets`
-List all stored wallets with their addresses and metadata.
+### Mnemonic Mode (Default)
+Provide a `MNEMONIC` environment variable to use traditional wallet control with full signing capabilities.
 
-#### `remove_wallet`
-Remove a wallet from storage.
+### 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)
 
-**Parameters:**
-- `name` (required): Name of the wallet to remove
+## Available Tools
 
-### Balance Queries
+### Balance & Info
 
 #### `get_balance`
-Get the TON balance for a wallet.
+Get the TON balance of the wallet.
 
-**Parameters:**
-- `wallet` (required): Name of the wallet
-
-**Returns:** Balance in nanoTON and TON
+**Returns:** Balance in TON and nanoTON
 
 #### `get_jetton_balance`
 Get the balance of a specific Jetton.
 
 **Parameters:**
-- `wallet` (required): Name of the wallet
 - `jettonAddress` (required): Jetton master contract address
 
 #### `get_jettons`
-List all Jettons held by a wallet.
+List all Jettons in the wallet with balances and metadata.
+
+#### `get_transactions`
+Get recent transaction history.
 
 **Parameters:**
-- `wallet` (required): Name of the wallet
+- `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.
 
 ### Transfers
 
@@ -114,28 +113,101 @@ List all Jettons held by a wallet.
 Send TON to an address.
 
 **Parameters:**
-- `wallet` (required): Name of the wallet to send from
 - `toAddress` (required): Recipient TON address
-- `amount` (required): Amount in nanoTON (1 TON = 1,000,000,000 nanoTON)
+- `amount` (required): Amount in TON (e.g., "1.5" for 1.5 TON)
 - `comment` (optional): Transaction comment/memo
 
 #### `send_jetton`
 Send Jettons to an address.
 
 **Parameters:**
-- `wallet` (required): Name of the wallet to send from
 - `toAddress` (required): Recipient TON address
 - `jettonAddress` (required): Jetton master contract address
-- `amount` (required): Amount in raw units (apply decimals yourself)
+- `amount` (required): Amount in human-readable format
 - `comment` (optional): Transaction comment/memo
 
+#### `send_raw_transaction`
+Send a raw transaction with full control over messages.
+
+**Parameters:**
+- `messages` (required): Array of messages with `address`, `amount` (nanoTON), optional `stateInit` and `payload` (Base64)
+- `validUntil` (optional): Unix timestamp for transaction expiry
+- `fromAddress` (optional): Sender wallet address
+
 ### Swaps
 
 #### `get_swap_quote`
-Get a quote for a token swap.
+Get a quote for swapping tokens.
+
+**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
+- `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.
+
+**Parameters:**
+- `limit` (optional): Max NFTs to return (default: 20, max: 100)
+- `offset` (optional): Pagination offset (default: 0)
+
+#### `get_nft`
+Get detailed information about a specific NFT.
 
-#### `execute_swap`
-Execute a token swap.
+**Parameters:**
+- `nftAddress` (required): NFT item contract address
+
+#### `send_nft`
+Transfer an NFT to another address.
+
+**Parameters:**
+- `nftAddress` (required): NFT item contract address
+- `toAddress` (required): Recipient TON address
+- `comment` (optional): Transaction comment/memo
+
+### DNS
+
+#### `resolve_dns`
+Resolve a TON DNS domain to a wallet address.
+
+**Parameters:**
+- `domain` (required): TON DNS domain (e.g., "foundation.ton")
+
+#### `back_resolve_dns`
+Reverse resolve a wallet address to its DNS domain.
+
+**Parameters:**
+- `address` (required): TON wallet address
+
+## Serverless Deployment
+
+The package exports a serverless handler for deployment to AWS Lambda, Vercel, etc.
+
+```typescript
+// AWS Lambda
+import { createServerlessHandler } from '@ton/mcp/serverless';
+export const handler = createServerlessHandler();
+
+// Vercel
+import { createServerlessHandler } from '@ton/mcp/serverless';
+export default createServerlessHandler();
+```
+
+### Serverless Headers
+
+Pass credentials via request headers:
+
+| 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 |
 
 ## Development
 
@@ -156,18 +228,33 @@ node packages/mcp/dist/cli.js --http 8080
 
 ## Library Usage
 
-The package also exports a programmatic API for building custom MCP servers:
+The package exports a programmatic API for building custom MCP servers:
 
 ```typescript
-import { createTonWalletMCP, InMemoryStorageAdapter, LocalSignerAdapter, StaticUserContextProvider } from '@ton/mcp';
-
-const server = createTonWalletMCP({
-  storage: new InMemoryStorageAdapter(),
-  signer: new LocalSignerAdapter(),
-  userContext: new StaticUserContextProvider('my-user'),
-  network: 'mainnet',
-  requireConfirmation: false,
+import { createTonWalletMCP } from '@ton/mcp';
+import { Signer, WalletV5R1Adapter, TonWalletKit, Network, MemoryStorageAdapter } from '@ton/walletkit';
+
+// Initialize kit
+const kit = new TonWalletKit({
+  networks: { [Network.mainnet().chainId]: {} },
+  storage: new MemoryStorageAdapter(),
+});
+await kit.waitForReady();
+
+// Create wallet adapter
+const signer = await Signer.fromMnemonic(mnemonic, { type: 'ton' });
+const walletAdapter = await WalletV5R1Adapter.create(signer, {
+  client: kit.getApiClient(Network.mainnet()),
+  network: Network.mainnet(),
 });
+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);
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truecarry/mcp",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "TON MCP Server - Model Context Protocol server for TON blockchain wallet operations",
   "license": "MIT",
   "type": "module",