@ton/mcp 0.1.15-alpha.13 → 0.1.15-alpha.15

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.
@@ -26,6 +27,8 @@ Choose one control path per task: either run `@ton/mcp` as an MCP server (stdio
 
 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.
 
+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.
@@ -48,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
@@ -194,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.).
@@ -241,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`
@@ -297,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`

package/USAGE_EXAMPLES.md

@@ -164,6 +164,24 @@ npx @ton/mcp@alpha get_known_jettons
 
 > `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