@ton/mcp 0.1.15-alpha.10 → 0.1.15-alpha.12

package/README.md

@@ -26,7 +26,7 @@ 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.
 
-**Learn more about [Agentic Wallets](https://agentic-wallets-dashboard.vercel.app/).**
+**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.
 

package/dist/cli.js

@@ -133560,7 +133560,7 @@ async function createMcpWalletServiceFromStoredWallet(input) {
 * LICENSE file in the root directory of this source tree.
 *
 */
-const AGENTIC_DASHBOARD_BASE_URL = "https://agentic-wallets-dashboard.vercel.app/";
+const AGENTIC_DASHBOARD_BASE_URL = "https://agents.ton.org/";
 const AGENTIC_LOOKUP_RETRY_ATTEMPTS = 5;
 const AGENTIC_LOOKUP_RETRY_DELAY_MS = 1500;
 const AGENTIC_WALLET_CODE_HASH = AgenticWalletCodeCell.hash().toString("hex");
@@ -135164,7 +135164,7 @@ const getNftsByAddressSchema = objectType({
 	limit: numberType().min(1).max(100).optional().describe("Maximum number of NFTs to return (default: 20, max: 100)"),
 	offset: numberType().min(0).optional().describe("Offset for pagination (default: 0)")
 });
-const getJettonInfoSchema = objectType({ address: stringType().min(1).describe("Jetton master contract address") });
+const getJettonInfoSchema = objectType({ jettonAddress: stringType().min(1).describe("Jetton master contract address") });
 objectType({
 	jettonAddress: stringType().min(1).describe("Jetton master contract address"),
 	ownerAddress: stringType().min(1).describe("Owner wallet address")
@@ -135287,7 +135287,7 @@ function createMcpAddressTools(service) {
 			inputSchema: getJettonInfoSchema,
 			handler: async (args) => {
 				try {
-					const jettonInfo = await service.getJettonInfo(args.address);
+					const jettonInfo = await service.getJettonInfo(args.jettonAddress);
 					if (!jettonInfo) return {
 						content: [{
 							type: "text",
@@ -137211,8 +137211,43 @@ if (WALLET_VERSION !== "agentic" && WALLET_VERSION !== "v4r2" && WALLET_VERSION
 function log(message) {
 	console.error(`[${SERVER_NAME}] ${message}`);
 }
+function printHelp() {
+	const help = `
+@ton/mcp – TON wallet MCP server & CLI
+
+Usage:
+  npx @ton/mcp@alpha                              stdio MCP server (default)
+  npx @ton/mcp@alpha --http [port]                HTTP MCP server (default: 0.0.0.0:3000)
+  npx @ton/mcp@alpha --http --host 127.0.0.1      HTTP server on custom host
+  npx @ton/mcp@alpha <tool_name> [--arg value]    call one tool and exit
+
+Options:
+  --help, -h      Show this help message
+  --http [port]   Start HTTP server instead of stdio
+  --host <addr>   Bind HTTP server to address (default: 0.0.0.0)
+
+Examples:
+  npx @ton/mcp@alpha get_balance
+  npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQAbc...
+  npx @ton/mcp@alpha get_swap_quote --fromToken TON --toToken EQAbc... --amount 1
+  npx @ton/mcp@alpha send_ton --toAddress UQA... --amount 0.5
+
+Environment variables:
+  NETWORK              mainnet (default) or testnet
+  MNEMONIC             24-word mnemonic phrase
+  PRIVATE_KEY          Hex-encoded private key (alternative to MNEMONIC)
+  WALLET_VERSION       v5r1 (default), v4r2, or agentic
+  TONCENTER_API_KEY    Optional Toncenter API key
+  TON_CONFIG_PATH      Config file path (default: ~/.config/ton/config.json)
+`.trimStart();
+	process.stdout.write(help);
+}
 function parseArgs() {
 	const args = process.argv.slice(2);
+	if (args.includes("--help") || args.includes("-h")) {
+		printHelp();
+		process.exit(0);
+	}
 	const httpIndex = args.indexOf("--http");
 	if (httpIndex !== -1) {
 		const nextArg = args[httpIndex + 1];

package/dist/index.cjs

@@ -132755,7 +132755,7 @@ async function createMcpWalletServiceFromStoredWallet(input) {
 * LICENSE file in the root directory of this source tree.
 *
 */
-const AGENTIC_DASHBOARD_BASE_URL = "https://agentic-wallets-dashboard.vercel.app/";
+const AGENTIC_DASHBOARD_BASE_URL = "https://agents.ton.org/";
 const AGENTIC_LOOKUP_RETRY_ATTEMPTS = 5;
 const AGENTIC_LOOKUP_RETRY_DELAY_MS = 1500;
 const AGENTIC_WALLET_CODE_HASH = AgenticWalletCodeCell.hash().toString("hex");
@@ -134359,7 +134359,7 @@ const getNftsByAddressSchema = objectType({
 	limit: numberType().min(1).max(100).optional().describe("Maximum number of NFTs to return (default: 20, max: 100)"),
 	offset: numberType().min(0).optional().describe("Offset for pagination (default: 0)")
 });
-const getJettonInfoSchema = objectType({ address: stringType().min(1).describe("Jetton master contract address") });
+const getJettonInfoSchema = objectType({ jettonAddress: stringType().min(1).describe("Jetton master contract address") });
 objectType({
 	jettonAddress: stringType().min(1).describe("Jetton master contract address"),
 	ownerAddress: stringType().min(1).describe("Owner wallet address")
@@ -134482,7 +134482,7 @@ function createMcpAddressTools(service) {
 			inputSchema: getJettonInfoSchema,
 			handler: async (args) => {
 				try {
-					const jettonInfo = await service.getJettonInfo(args.address);
+					const jettonInfo = await service.getJettonInfo(args.jettonAddress);
 					if (!jettonInfo) return {
 						content: [{
 							type: "text",

package/dist/index.js

@@ -132755,7 +132755,7 @@ async function createMcpWalletServiceFromStoredWallet(input) {
 * LICENSE file in the root directory of this source tree.
 *
 */
-const AGENTIC_DASHBOARD_BASE_URL = "https://agentic-wallets-dashboard.vercel.app/";
+const AGENTIC_DASHBOARD_BASE_URL = "https://agents.ton.org/";
 const AGENTIC_LOOKUP_RETRY_ATTEMPTS = 5;
 const AGENTIC_LOOKUP_RETRY_DELAY_MS = 1500;
 const AGENTIC_WALLET_CODE_HASH = AgenticWalletCodeCell.hash().toString("hex");
@@ -134359,7 +134359,7 @@ const getNftsByAddressSchema = objectType({
 	limit: numberType().min(1).max(100).optional().describe("Maximum number of NFTs to return (default: 20, max: 100)"),
 	offset: numberType().min(0).optional().describe("Offset for pagination (default: 0)")
 });
-const getJettonInfoSchema = objectType({ address: stringType().min(1).describe("Jetton master contract address") });
+const getJettonInfoSchema = objectType({ jettonAddress: stringType().min(1).describe("Jetton master contract address") });
 objectType({
 	jettonAddress: stringType().min(1).describe("Jetton master contract address"),
 	ownerAddress: stringType().min(1).describe("Owner wallet address")
@@ -134482,7 +134482,7 @@ function createMcpAddressTools(service) {
 			inputSchema: getJettonInfoSchema,
 			handler: async (args) => {
 				try {
-					const jettonInfo = await service.getJettonInfo(args.address);
+					const jettonInfo = await service.getJettonInfo(args.jettonAddress);
 					if (!jettonInfo) return {
 						content: [{
 							type: "text",

package/dist/serverless.cjs

@@ -133824,7 +133824,7 @@ async function createMcpWalletServiceFromStoredWallet(input) {
 * LICENSE file in the root directory of this source tree.
 *
 */
-const AGENTIC_DASHBOARD_BASE_URL = "https://agentic-wallets-dashboard.vercel.app/";
+const AGENTIC_DASHBOARD_BASE_URL = "https://agents.ton.org/";
 const AGENTIC_LOOKUP_RETRY_ATTEMPTS = 5;
 const AGENTIC_LOOKUP_RETRY_DELAY_MS = 1500;
 const AGENTIC_WALLET_CODE_HASH = AgenticWalletCodeCell.hash().toString("hex");
@@ -135428,7 +135428,7 @@ const getNftsByAddressSchema = objectType({
 	limit: numberType().min(1).max(100).optional().describe("Maximum number of NFTs to return (default: 20, max: 100)"),
 	offset: numberType().min(0).optional().describe("Offset for pagination (default: 0)")
 });
-const getJettonInfoSchema = objectType({ address: stringType().min(1).describe("Jetton master contract address") });
+const getJettonInfoSchema = objectType({ jettonAddress: stringType().min(1).describe("Jetton master contract address") });
 objectType({
 	jettonAddress: stringType().min(1).describe("Jetton master contract address"),
 	ownerAddress: stringType().min(1).describe("Owner wallet address")
@@ -135551,7 +135551,7 @@ function createMcpAddressTools(service) {
 			inputSchema: getJettonInfoSchema,
 			handler: async (args) => {
 				try {
-					const jettonInfo = await service.getJettonInfo(args.address);
+					const jettonInfo = await service.getJettonInfo(args.jettonAddress);
 					if (!jettonInfo) return {
 						content: [{
 							type: "text",

package/dist/serverless.js

@@ -133824,7 +133824,7 @@ async function createMcpWalletServiceFromStoredWallet(input) {
 * LICENSE file in the root directory of this source tree.
 *
 */
-const AGENTIC_DASHBOARD_BASE_URL = "https://agentic-wallets-dashboard.vercel.app/";
+const AGENTIC_DASHBOARD_BASE_URL = "https://agents.ton.org/";
 const AGENTIC_LOOKUP_RETRY_ATTEMPTS = 5;
 const AGENTIC_LOOKUP_RETRY_DELAY_MS = 1500;
 const AGENTIC_WALLET_CODE_HASH = AgenticWalletCodeCell.hash().toString("hex");
@@ -135428,7 +135428,7 @@ const getNftsByAddressSchema = objectType({
 	limit: numberType().min(1).max(100).optional().describe("Maximum number of NFTs to return (default: 20, max: 100)"),
 	offset: numberType().min(0).optional().describe("Offset for pagination (default: 0)")
 });
-const getJettonInfoSchema = objectType({ address: stringType().min(1).describe("Jetton master contract address") });
+const getJettonInfoSchema = objectType({ jettonAddress: stringType().min(1).describe("Jetton master contract address") });
 objectType({
 	jettonAddress: stringType().min(1).describe("Jetton master contract address"),
 	ownerAddress: stringType().min(1).describe("Owner wallet address")
@@ -135551,7 +135551,7 @@ function createMcpAddressTools(service) {
 			inputSchema: getJettonInfoSchema,
 			handler: async (args) => {
 				try {
-					const jettonInfo = await service.getJettonInfo(args.address);
+					const jettonInfo = await service.getJettonInfo(args.jettonAddress);
 					if (!jettonInfo) return {
 						content: [{
 							type: "text",

package/dist/tools/address-tools.d.ts

@@ -42,11 +42,11 @@ export declare const getNftsByAddressSchema: z.ZodObject<{
     offset?: number | undefined;
 }>;
 export declare const getJettonInfoSchema: z.ZodObject<{
-    address: z.ZodString;
+    jettonAddress: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    address: string;
+    jettonAddress: string;
 }, {
-    address: string;
+    jettonAddress: string;
 }>;
 export declare const getJettonWalletAddressSchema: z.ZodObject<{
     jettonAddress: z.ZodString;
@@ -107,11 +107,11 @@ export declare function createMcpAddressTools(service: McpWalletService): {
     get_jetton_info: {
         description: string;
         inputSchema: z.ZodObject<{
-            address: z.ZodString;
+            jettonAddress: z.ZodString;
         }, "strip", z.ZodTypeAny, {
-            address: string;
+            jettonAddress: string;
         }, {
-            address: string;
+            jettonAddress: string;
         }>;
         handler: (args: z.infer<typeof getJettonInfoSchema>) => Promise<ToolResponse>;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ton/mcp",
-  "version": "0.1.15-alpha.10",
+  "version": "0.1.15-alpha.12",
   "description": "TON MCP Server - Model Context Protocol server for TON blockchain wallet operations",
   "license": "MIT",
   "type": "module",

package/skills/ton-balance/SKILL.md

@@ -15,11 +15,11 @@ Read-only queries for wallet balances, token holdings, and transaction history o
 | ---- | -------- | -------- |
 | `get_wallet` | — | `walletSelector` |
 | `get_balance` | — | `walletSelector` |
-| `get_balance_by_address` | `address` | — |
+| `get_balance_by_address` | `address` | `walletSelector` |
 | `get_jetton_balance` | `jettonAddress` | `walletSelector` |
 | `get_jettons` | — | `walletSelector` |
-| `get_jettons_by_address` | `address` | — |
-| `get_jetton_info` | `address` | — |
+| `get_jettons_by_address` | `address` | `limit`, `offset`, `walletSelector` |
+| `get_jetton_info` | `jettonAddress` | `walletSelector` |
 | `get_known_jettons` | — | — |
 | `get_transactions` | — | `limit`, `walletSelector` |
 | `get_transaction_status` | `normalizedHash` | `walletSelector` |

package/skills/ton-cli/SKILL.md

@@ -70,11 +70,11 @@ Without `MNEMONIC` or `PRIVATE_KEY`, the CLI uses the local config registry at `
 | ---- | ------------- | ------------- |
 | `get_wallet` | — | `--walletSelector` |
 | `get_balance` | — | `--walletSelector` |
-| `get_balance_by_address` | `--address` | — |
+| `get_balance_by_address` | `--address` | `--walletSelector` |
 | `get_jetton_balance` | `--jettonAddress` | `--walletSelector` |
 | `get_jettons` | — | `--walletSelector` |
-| `get_jettons_by_address` | `--address` | — |
-| `get_jetton_info` | `--jettonAddress` | — |
+| `get_jettons_by_address` | `--address` | `--limit`, `--offset`, `--walletSelector` |
+| `get_jetton_info` | `--jettonAddress` | `--walletSelector` |
 | `get_transactions` | — | `--limit`, `--walletSelector` |
 | `get_transaction_status` | `--normalizedHash` | `--walletSelector` |
 | `get_known_jettons` | — | — |
@@ -95,29 +95,29 @@ Without `MNEMONIC` or `PRIVATE_KEY`, the CLI uses the local config registry at `
 | `send_ton` | `--toAddress`, `--amount` | `--comment`, `--walletSelector` |
 | `send_jetton` | `--toAddress`, `--jettonAddress`, `--amount` | `--comment`, `--walletSelector` |
 | `send_nft` | `--nftAddress`, `--toAddress` | `--comment`, `--walletSelector` |
-| `send_raw_transaction` | `--messages` | `--walletSelector` |
-| `emulate_transaction` | `--messages` | `--validUntil` |
+| `send_raw_transaction` | `--messages` | `--validUntil`, `--fromAddress`, `--walletSelector` |
+| `emulate_transaction` | `--messages` | `--validUntil`, `--walletSelector` |
 
 ### Swaps
 
 | Tool | Required args | Optional args |
 | ---- | ------------- | ------------- |
-| `get_swap_quote` | `--fromToken`, `--toToken`, `--amount` | `--walletSelector` |
+| `get_swap_quote` | `--fromToken`, `--toToken`, `--amount` | `--slippageBps`, `--walletSelector` |
 
 ### NFTs
 
 | Tool | Required args | Optional args |
 | ---- | ------------- | ------------- |
 | `get_nfts` | — | `--limit`, `--offset`, `--walletSelector` |
-| `get_nfts_by_address` | `--address` | `--limit`, `--offset` |
-| `get_nft` | `--nftAddress` | — |
+| `get_nfts_by_address` | `--address` | `--limit`, `--offset`, `--walletSelector` |
+| `get_nft` | `--nftAddress` | `--walletSelector` |
 
 ### DNS
 
-| Tool | Required args |
-| ---- | ------------- |
-| `resolve_dns` | `--domain` |
-| `back_resolve_dns` | `--address` |
+| Tool | Required args | Optional args |
+| ---- | ------------- | ------------- |
+| `resolve_dns` | `--domain` | `--walletSelector` |
+| `back_resolve_dns` | `--address` | `--walletSelector` |
 
 ## Example Session
 
@@ -135,7 +135,7 @@ npx @ton/mcp@alpha get_jettons
 npx @ton/mcp@alpha get_transactions --limit 10
 
 # Get balance of a specific jetton
-npx @ton/mcp@alpha get_jetton_balance --address EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
+npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
 
 # Resolve a .ton domain
 npx @ton/mcp@alpha resolve_dns --domain foundation.ton

package/skills/ton-create-wallet/SKILL.md

@@ -42,7 +42,7 @@ Deploy an on-chain agentic wallet on TON. The agent generates operator keys, ope
 - The agent keeps the **operator private key** — it can sign transactions autonomously
 - The user keeps the **owner key** — they can withdraw funds or revoke access at any time
 - The wallet is an on-chain smart contract (NFT-based), not a custodial service
-- The dashboard is at `agentic-wallets-dashboard.vercel.app`
+- The dashboard is at `agents.ton.org`
 
 ## Environment Variables
 

package/skills/ton-xstocks/SKILL.md

@@ -21,15 +21,17 @@ Backed **xStocks** are jettons on TON. Resolve the **jetton master** from the pu
 
 ## Resolve the TON jetton master for an xStock
 
-1. **By symbol** (e.g. `TSLAx`): fetch  
-   `GET https://api.xstocks.fi/api/v2/public/assets/{symbol}`  
+1. **By symbol** (e.g. `TSLAx`): fetch via **`curl`** (not WebFetch — the xStocks API returns 403 for non-standard user-agents):
+   ```bash
+   curl -s "https://api.xstocks.fi/api/v2/public/assets/{symbol}"
+   ```
    (production base: `https://api.xstocks.fi/api/v2` — see [xStocks API](https://docs.xstocks.fi/apis/openapi)).
 
 2. In the JSON, find `deployments[]` where **`network` is `"Ton"`**. Use that object's **`address`** as the jetton master for MCP (`fromToken` / `toToken`).
 
-3. Optional: `GET https://api.xstocks.fi/api/v2/public/assets` returns all assets with the same `deployments` shape.
+3. Optional: `curl -s "https://api.xstocks.fi/api/v2/public/assets"` returns all assets with the same `deployments` shape.
 
-4. Call `get_jetton_info` with that address to confirm **name / symbol / decimals** before swapping.
+4. Call `get_jetton_info` with `--jettonAddress <jetton_master>` to confirm **name / symbol / decimals** before swapping.
 
 ## MCP tools
 
@@ -42,6 +44,20 @@ Backed **xStocks** are jettons on TON. Resolve the **jetton master** from the pu
 
 Amounts for `get_swap_quote` are **human-readable** strings (respect jetton decimals from `get_jetton_info`).
 
+## CLI argument names (exact)
+
+| Tool | Arg | CLI flag |
+| ---- | --- | -------- |
+| `get_jetton_info` | jettonAddress | `--jettonAddress` |
+| `get_jetton_balance` | jettonAddress | `--jettonAddress` |
+| `get_swap_quote` | fromToken | `--fromToken` (use `"TON"` for native TON, jetton master address for tokens) |
+| `get_swap_quote` | toToken | `--toToken` |
+| `get_swap_quote` | amount | `--amount` (human-readable) |
+| `get_swap_quote` | slippageBps | `--slippageBps` (default 100 = 1%) |
+| `emulate_transaction` | messages | `--messages` (JSON array from quote's `transaction.messages`) |
+| `send_raw_transaction` | messages | `--messages` (same JSON array) |
+| `get_transaction_status` | normalizedHash | `--normalizedHash` |
+
 ## Pre-fund USDT (auto, when needed)
 
 Before any xStock trade, check the user's USDT balance:
@@ -49,7 +65,7 @@ Before any xStock trade, check the user's USDT balance:
 1. `get_jetton_balance` for the USDT master address — use the `amount` field for comparison.
 2. If `amount` **< required amount** for the planned buy:
    a. Calculate the shortfall (include a small buffer for price movement).
-   b. `get_swap_quote` with `fromToken` = native TON, `toToken` = USDT master, `amount` = shortfall.
+   b. `get_swap_quote` with `fromToken` = `"TON"` (the literal string, not an address), `toToken` = USDT master, `amount` = shortfall.
    c. Confirm with the user: *"You need ~X USDT but only have Y. Swap Z TON → X USDT first?"*
    d. On approval, `send_raw_transaction` → poll `get_transaction_status` until `completed`.
    e. Re-check USDT balance before proceeding to the xStock buy.
@@ -62,7 +78,7 @@ Before any xStock trade, check the user's USDT balance:
 4. `emulate_transaction` with the quote's `transaction.messages` — verify expected balance changes before sending.
 5. Show the user: **fromAmount**, **toAmount**, **minReceived**, **expiresAt**, emulation results, and note the forward **TON** on router messages (gas).
 6. Confirm once, then `send_raw_transaction` with the returned `transaction.messages`.
-6. Poll `get_transaction_status` on `normalizedHash` until `completed` or `failed`.
+7. Poll `get_transaction_status` on `normalizedHash` until `completed` or `failed`.
 
 > **Do not attempt TON → xStock directly.** It will return no quote. Always route through USDT.