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

package/README.md

@@ -9,6 +9,7 @@ A Model Context Protocol (MCP) server for TON blockchain wallet operations. Buil
 - **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.
+- **TonProof Authentication**: Generate signed TonConnect proof-of-ownership payloads for third-party services.
 - **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.
@@ -20,11 +21,15 @@ A Model Context Protocol (MCP) server for TON blockchain wallet operations. Buil
 - **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
 
+Choose one control path per task: either run `@ton/mcp` as an MCP server (stdio or HTTP) or call tools through raw CLI. Agents must not mix MCP server mode and raw CLI against the same workflow/session, because that creates competing control paths over the same wallet/config state.
+
 ### 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/).**
+Key storage in this mode: wallet secrets are persisted inside the local config registry at `TON_CONFIG_PATH` or `~/.config/ton/config.json`. The config directory is created with `0700` permissions and the config file with `0600` permissions. The file is not stored as plain text, but the current protected-file format is only obfuscation-in-file, not real cryptographic protection with an external secret or password.
+
+**Learn more about [Agentic Wallets](https://agents.ton.org/).**
 
 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.
 
@@ -46,6 +51,8 @@ TON_CONFIG_PATH=/path/to/config.json npx @ton/mcp@alpha
 
 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.
 
+Key storage in this mode: `MNEMONIC` / `PRIVATE_KEY` are read from environment variables and used only in memory for the current process; `@ton/mcp` does not persist them to disk in this mode. The values come in as plain environment variables, so any non-plain-text storage or encryption is the responsibility of the caller or host environment, not `@ton/mcp`.
+
 ```bash
 # Run as stdio MCP server with mnemonic
 MNEMONIC="word1 word2 ..." npx @ton/mcp@alpha
@@ -106,6 +113,10 @@ npx @ton/mcp@alpha --http 3000
 
 HTTP mode keeps a separate MCP session/transport per client session id, so multiple clients can initialize and reconnect independently.
 
+## Usage Examples
+
+Examples of user requests, approximate corresponding raw CLI commands via `npx @ton/mcp@alpha`, and expected agent responses are collected in [USAGE_EXAMPLES.md](./USAGE_EXAMPLES.md).
+
 ## Environment Variables
 
 | Variable | Default | Description |
@@ -188,7 +199,7 @@ List Jettons held by any address with balances and metadata.
 Get metadata for a Jetton master contract.
 
 **Parameters:**
-- `address` (required): Jetton master contract address
+- `jettonAddress` (required): Jetton master contract address
 
 #### `get_transactions`
 Get recent transaction history for the wallet (TON transfers, Jetton transfers, swaps, etc.).
@@ -235,6 +246,13 @@ 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
 
+#### `emulate_transaction`
+Dry-run a raw transaction without broadcasting it. Accepts the same `messages` format as `send_raw_transaction` and returns the expected TON and Jetton balance changes, fees, and high-level actions so agents can verify a transaction before sending.
+
+**Parameters:**
+- `messages` (required): Array of messages, each with `address`, `amount` in nanotons, and optional `stateInit` / `payload`
+- `validUntil` (optional): Unix timestamp after which the transaction becomes invalid
+
 ### Swaps
 
 #### `get_swap_quote`
@@ -291,6 +309,19 @@ Reverse-resolve a TON wallet address to its associated DNS domain when available
 **Parameters:**
 - `address` (required): TON wallet address to reverse resolve
 
+### Authentication
+
+#### `generate_ton_proof`
+Generate a signed TonConnect proof-of-ownership payload for the active wallet. Use it to authenticate with third-party services that accept TonProof, such as APIs that ask for a domain and challenge payload.
+
+**Parameters:**
+- `domain` (required): Domain to generate the proof for (for example, `"getgems.io"`)
+- `payload` (required): Challenge or payload string provided by the verifying service
+
+**Returns:** Address, chain id, wallet state init, public key, timestamp, domain, payload, and base64 signature ready to submit to the verifying service.
+
+TonProof does not broadcast a transaction, but it does require signing access to the selected wallet. Imported read-only agentic wallets need operator key rotation completed before this tool can generate a proof.
+
 ### Utility
 
 #### `get_known_jettons`
@@ -321,7 +352,7 @@ Import an existing agentic wallet into the local TON config registry, recovering
 - `name` (optional): Wallet display name
 
 #### `agentic_start_root_wallet_setup` (registry mode only)
-Start first-root-agent setup: generate operator keys, persist a pending draft, and return a dashboard URL for the user to create the wallet from their main wallet.
+Start first-root-agent setup: generate operator keys, persist a pending draft, and return a dashboard URL for the user to create the wallet from their main wallet. Agents with local shell/browser access should open the dashboard URL for the user. Callback-based completion is for long-lived stdio/HTTP server sessions; raw CLI should use manual completion.
 
 **Parameters:**
 - `network` (optional): Network for the new root wallet

package/USAGE_EXAMPLES.md

@@ -0,0 +1,360 @@
+# Usage Examples
+
+These examples show how `@ton/mcp` can be used in raw CLI mode. They are illustrative rather than literal agent logs: each example includes a representative user request, the `npx @ton/mcp@alpha` commands an agent would typically run, and the kind of response it would usually return.
+
+## Agentic Wallets
+
+### Create an agentic wallet
+
+**User request**
+
+`Create an agentic wallet`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha agentic_start_root_wallet_setup --name "My Agent" --network mainnet
+open <DASHBOARD_URL>
+npx @ton/mcp@alpha agentic_complete_root_wallet_setup --setupId <SETUP_ID> --walletAddress <WALLET_ADDRESS>
+npx @ton/mcp@alpha get_current_wallet
+```
+
+**Approximate agent response**
+
+> A new agentic wallet setup was started, and the dashboard link was opened. After the dashboard step was completed, wallet `EQ...` was added and set as the active wallet.
+
+### Import an existing agentic wallet
+
+**User request**
+
+`Import my existing agentic wallet EQ...`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha agentic_validate_wallet --address EQ...
+npx @ton/mcp@alpha agentic_import_wallet --address EQ... --name "Imported wallet"
+npx @ton/mcp@alpha agentic_rotate_operator_key --walletSelector "Imported wallet"
+open <DASHBOARD_URL>
+npx @ton/mcp@alpha list_wallets
+```
+
+**Approximate agent response**
+
+> Wallet `EQ...` was validated and imported into the local registry under the name `Imported wallet`. The dashboard link for the `Public Key` update was opened. Until that on-chain confirmation is completed, the wallet is available in read-only mode.
+
+### Rotate the operator key
+
+**User request**
+
+`Rotate the operator key for the active agentic wallet`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha agentic_rotate_operator_key
+open <DASHBOARD_URL>
+npx @ton/mcp@alpha agentic_get_pending_operator_key_rotation --rotationId <ROTATION_ID>
+npx @ton/mcp@alpha agentic_complete_rotate_operator_key --rotationId <ROTATION_ID>
+```
+
+**Approximate agent response**
+
+> The dashboard link for the `Public Key` update was opened. After the main wallet confirms the change, write access is restored.
+
+### List agentic wallets by owner
+
+**User request**
+
+`Which agentic wallets belong to owner address EQ...?`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha agentic_list_wallets_by_owner --ownerAddress EQ...
+```
+
+**Approximate agent response**
+
+> Several agentic wallets were found for owner address `EQ...`. For each wallet, the agent typically shows the wallet address and basic metadata.
+
+## Wallet Registry and Balances
+
+### List wallets in the registry
+
+**User request**
+
+`Which wallets do I have?`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha list_wallets
+npx @ton/mcp@alpha get_current_wallet
+```
+
+**Approximate agent response**
+
+> Several wallets were found. The active wallet is `EQ...`. The others can be selected by `id`, name, or address via `set_active_wallet`.
+
+### Switch the active wallet
+
+**User request**
+
+`Make wallet "treasury" active`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha set_active_wallet --walletSelector treasury
+npx @ton/mcp@alpha get_current_wallet
+```
+
+**Approximate agent response**
+
+> The active wallet was switched to `treasury`. Current address: `UQ...`. Network: `mainnet`.
+
+### Show the active wallet balance
+
+**User request**
+
+`Show my balance in TON and jettons`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha get_balance
+npx @ton/mcp@alpha get_jettons
+```
+
+**Approximate agent response**
+
+> Active wallet balance: `12.84 TON`. Jetton balances include `USDT 53.2`, `NOT 1400`, and `STON 18.05`.
+
+### Show the balance of any address
+
+**User request**
+
+`Show the balance of address EQ...`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha get_balance_by_address --address EQ...
+npx @ton/mcp@alpha get_jettons_by_address --address EQ...
+```
+
+**Approximate agent response**
+
+> Address `EQ...` has a balance of `3.21 TON`. No jettons were found for that address.
+
+### Find a known jetton address
+
+**User request**
+
+`Show the address of USDT`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha get_known_jettons
+```
+
+**Approximate agent response**
+
+> `USDT` was found in the list of known jettons with master contract address `EQ...`. That address can be used with `send_jetton` or `get_swap_quote`.
+
+## TON Proof Authentication
+
+### Generate a TonProof for a service challenge
+
+**User request**
+
+`Generate a TonProof for getgems.io using payload getgems-llm`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha generate_ton_proof --domain getgems.io --payload getgems-llm
+```
+
+**Approximate agent response**
+
+> A signed TonProof was generated for `getgems.io`. The proof includes the wallet address, chain id, wallet state init, public key, timestamp, domain, payload, and signature needed by the verifying service.
+
+## Transfers and Swaps
+
+### Send TON to a TON DNS name
+
+**User request**
+
+`Send 1 TON to foundation.ton`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha resolve_dns --domain foundation.ton
+npx @ton/mcp@alpha send_ton --toAddress EQ... --amount 1
+npx @ton/mcp@alpha get_transaction_status --normalizedHash <NORMALIZED_HASH>
+```
+
+**Approximate agent response**
+
+> `foundation.ton` was resolved to TON address `EQ...`. The `1 TON` transfer was sent with `normalizedHash: <NORMALIZED_HASH>`. Transaction status: `completed`.
+
+### Send a jetton
+
+**User request**
+
+`Send 25 USDT to UQAbc...`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha get_jettons
+npx @ton/mcp@alpha send_jetton --jettonAddress EQ... --toAddress UQAbc... --amount 25
+npx @ton/mcp@alpha get_transaction_status --normalizedHash <NORMALIZED_HASH>
+```
+
+**Approximate agent response**
+
+> `USDT` was found in the wallet, and the `25 USDT` transfer to `UQAbc...` was sent. `normalizedHash: <NORMALIZED_HASH>`. Current status: `completed`.
+
+### Swap TON for a jetton
+
+**User request**
+
+`Swap 2 TON to USDT`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha get_known_jettons
+# quote
+npx @ton/mcp@alpha get_swap_quote --fromToken TON --toToken EQ... --amount 2 --slippageBps 100
+# pass messages from quote if user approved
+npx @ton/mcp@alpha send_raw_transaction --messages '<quote.transaction.messages>'
+# If the quote includes transaction.validUntil, add --validUntil to the send_raw_transaction invocation above
+npx @ton/mcp@alpha get_transaction_status --normalizedHash <NORMALIZED_HASH>
+```
+
+**Approximate agent response**
+
+> A quote was received for swapping `2 TON` to `USDT`. After confirmation, the swap was executed with an expected output of about `X USDT` after slippage. `normalizedHash: <NORMALIZED_HASH>`.
+
+### Show recent transactions
+
+**User request**
+
+`Show my last 5 transactions`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha get_transactions --limit 5
+```
+
+**Approximate agent response**
+
+> The last 5 operations were shown, including incoming and outgoing TON transfers, jetton transfers, and swaps. For each transaction, the agent typically shows the time, action type, amount, and final status.
+
+## TON DNS
+
+### Resolve a TON DNS name
+
+**User request**
+
+`What does foundation.ton resolve to?`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha resolve_dns --domain foundation.ton
+```
+
+**Approximate agent response**
+
+> Domain `foundation.ton` resolves to address `EQ...`.
+
+### Reverse-resolve an address
+
+**User request**
+
+`Does address EQ... have a TON DNS name?`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha back_resolve_dns --address EQ...
+```
+
+**Approximate agent response**
+
+> If reverse resolution succeeds, address `EQ...` maps to a DNS name such as `foundation.ton`. Otherwise, the agent reports that no DNS name was found.
+
+## NFTs
+
+### List NFTs in the active wallet
+
+**User request**
+
+`Show my NFTs`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha get_nfts --limit 20
+```
+
+**Approximate agent response**
+
+> A list of NFTs from the active wallet was shown, including addresses, collection names, preview metadata, and key attributes.
+
+### Show NFT details
+
+**User request**
+
+`Show details for NFT EQ...`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha get_nft --nftAddress EQ...
+```
+
+**Approximate agent response**
+
+> For NFT `EQ...`, the agent shows metadata, collection information, owner, content URI, and attributes.
+
+### Send an NFT
+
+**User request**
+
+`Send NFT EQ... to UQReceiver...`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha send_nft --nftAddress EQ... --toAddress UQReceiver...
+npx @ton/mcp@alpha get_transaction_status --normalizedHash <NORMALIZED_HASH>
+```
+
+**Approximate agent response**
+
+> NFT `EQ...` was sent to `UQReceiver...`. `normalizedHash: <NORMALIZED_HASH>`. Transaction status: `completed`.
+
+### Show NFTs owned by any address
+
+**User request**
+
+`Show NFTs owned by address EQ...`
+
+**Approximate command list**
+
+```bash
+npx @ton/mcp@alpha get_nfts_by_address --address EQ... --limit 10
+```
+
+**Approximate agent response**
+
+> NFTs owned by address `EQ...` were shown, even though that address is not one of the saved wallets.

package/dist/cli.d.ts

@@ -5,5 +5,33 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
-export {};
+/**
+ * TON MCP CLI - Command-line MCP server for TON wallet management
+ *
+ * This CLI runs a Model Context Protocol server that provides
+ * TON wallet management tools for use with Claude Desktop or other MCP clients.
+ *
+ * Usage:
+ *   npx @ton/mcp@alpha                          # stdio mode (default)
+ *   npx @ton/mcp@alpha --http                   # HTTP server on 0.0.0.0:3000
+ *   npx @ton/mcp@alpha --http 8080              # HTTP server on custom port
+ *   npx @ton/mcp@alpha --http --host 127.0.0.1  # HTTP server on custom host
+ *   npx @ton/mcp@alpha get_balance              # raw CLI: call tool and exit
+ *   npx @ton/mcp@alpha get_transactions --limit 5
+ *   npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQAbc...
+ *
+ * Environment variables:
+ *   NETWORK         - Network to use (mainnet or testnet, default: mainnet)
+ *   MNEMONIC        - 24-word mnemonic phrase for wallet
+ *   PRIVATE_KEY     - Hex-encoded private key (alternative to MNEMONIC)
+ *   WALLET_VERSION  - Wallet version (v5r1, v4r2, or agentic; default: v5r1)
+ *   AGENTIC_WALLET_ADDRESS - Agentic wallet address (required for WALLET_VERSION=agentic unless derived from init params)
+ *   AGENTIC_WALLET_NFT_INDEX - walletNftIndex / subwallet id for agentic wallet (uint256, optional)
+ *   AGENTIC_COLLECTION_ADDRESS - collection address for agentic wallet state init derivation (optional)
+ *   TONCENTER_API_KEY - API key for Toncenter (optional, for higher rate limits)
+ *   AGENTIC_CALLBACK_BASE_URL - optional public callback base URL for agentic onboarding
+ *   AGENTIC_CALLBACK_HOST - host for local callback server in stdio mode (default: 127.0.0.1)
+ *   AGENTIC_CALLBACK_PORT - port for local callback server in stdio mode (default: random free port)
+ */
+import './suppress-punycode-deprecation.js';
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,oCAAoC,CAAC"}