@ton/mcp 0.1.10

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

@@ -0,0 +1,159 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import { z } from 'zod';
+import type { McpWalletService } from '../services/McpWalletService.js';
+import type { ToolResponse } from './types.js';
+export declare const sendTonSchema: z.ZodObject<{
+    toAddress: z.ZodString;
+    amount: z.ZodString;
+    comment: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    toAddress: string;
+    amount: string;
+    comment?: string | undefined;
+}, {
+    toAddress: string;
+    amount: string;
+    comment?: string | undefined;
+}>;
+export declare const sendJettonSchema: z.ZodObject<{
+    toAddress: z.ZodString;
+    jettonAddress: z.ZodString;
+    amount: z.ZodString;
+    comment: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    jettonAddress: string;
+    toAddress: string;
+    amount: string;
+    comment?: string | undefined;
+}, {
+    jettonAddress: string;
+    toAddress: string;
+    amount: string;
+    comment?: string | undefined;
+}>;
+export declare const sendRawTransactionSchema: z.ZodObject<{
+    messages: z.ZodArray<z.ZodObject<{
+        address: z.ZodString;
+        amount: z.ZodString;
+        stateInit: z.ZodOptional<z.ZodString>;
+        payload: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        address: string;
+        amount: string;
+        stateInit?: string | undefined;
+        payload?: string | undefined;
+    }, {
+        address: string;
+        amount: string;
+        stateInit?: string | undefined;
+        payload?: string | undefined;
+    }>, "many">;
+    validUntil: z.ZodOptional<z.ZodNumber>;
+    fromAddress: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    messages: {
+        address: string;
+        amount: string;
+        stateInit?: string | undefined;
+        payload?: string | undefined;
+    }[];
+    validUntil?: number | undefined;
+    fromAddress?: string | undefined;
+}, {
+    messages: {
+        address: string;
+        amount: string;
+        stateInit?: string | undefined;
+        payload?: string | undefined;
+    }[];
+    validUntil?: number | undefined;
+    fromAddress?: string | undefined;
+}>;
+export declare function createMcpTransferTools(service: McpWalletService): {
+    send_ton: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            toAddress: z.ZodString;
+            amount: z.ZodString;
+            comment: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            toAddress: string;
+            amount: string;
+            comment?: string | undefined;
+        }, {
+            toAddress: string;
+            amount: string;
+            comment?: string | undefined;
+        }>;
+        handler: (args: z.infer<typeof sendTonSchema>) => Promise<ToolResponse>;
+    };
+    send_jetton: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            toAddress: z.ZodString;
+            jettonAddress: z.ZodString;
+            amount: z.ZodString;
+            comment: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            jettonAddress: string;
+            toAddress: string;
+            amount: string;
+            comment?: string | undefined;
+        }, {
+            jettonAddress: string;
+            toAddress: string;
+            amount: string;
+            comment?: string | undefined;
+        }>;
+        handler: (args: z.infer<typeof sendJettonSchema>) => Promise<ToolResponse>;
+    };
+    send_raw_transaction: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            messages: z.ZodArray<z.ZodObject<{
+                address: z.ZodString;
+                amount: z.ZodString;
+                stateInit: z.ZodOptional<z.ZodString>;
+                payload: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                address: string;
+                amount: string;
+                stateInit?: string | undefined;
+                payload?: string | undefined;
+            }, {
+                address: string;
+                amount: string;
+                stateInit?: string | undefined;
+                payload?: string | undefined;
+            }>, "many">;
+            validUntil: z.ZodOptional<z.ZodNumber>;
+            fromAddress: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            messages: {
+                address: string;
+                amount: string;
+                stateInit?: string | undefined;
+                payload?: string | undefined;
+            }[];
+            validUntil?: number | undefined;
+            fromAddress?: string | undefined;
+        }, {
+            messages: {
+                address: string;
+                amount: string;
+                stateInit?: string | undefined;
+                payload?: string | undefined;
+            }[];
+            validUntil?: number | undefined;
+            fromAddress?: string | undefined;
+        }>;
+        handler: (args: z.infer<typeof sendRawTransactionSchema>) => Promise<ToolResponse>;
+    };
+};
+//# sourceMappingURL=transfer-tools.d.ts.map

package/dist/tools/transfer-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-tools.d.ts","sourceRoot":"","sources":["../../src/tools/transfer-tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,eAAO,MAAM,aAAa;;;;;;;;;;;;EAIxB,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;EAK3B,CAAC;AASH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAInC,CAAC;AAEH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB;;;;;;;;;;;;;;;;wBAK9B,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,KAAG,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;wBA8CrD,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,KAAG,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAyFxD,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,KAAG,OAAO,CAAC,YAAY,CAAC;;EA+CjG"}

package/dist/tools/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+export interface ToolResponse {
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Converts a human-readable amount to raw units.
+ */
+export declare function toRawAmount(amount: string, decimals: number): string;
+export declare const TON_DECIMALS = 9;
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,MAAM,WAAW,YAAY;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKpE;AAED,eAAO,MAAM,YAAY,IAAI,CAAC"}

package/dist/types/config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/**
+ * Configuration types for createTonWalletMCP factory
+ */
+import type { Wallet } from '@ton/walletkit';
+import type { IContactResolver } from './contacts.js';
+/**
+ * Network-specific configuration
+ */
+export interface NetworkConfig {
+    /** TonCenter API key for this network */
+    apiKey?: string;
+}
+/**
+ * Configuration for createTonWalletMCP factory
+ */
+export interface TonMcpConfig {
+    /**
+     * Wallet instance to use for operations.
+     * Required.
+     */
+    wallet: Wallet;
+    /**
+     * Optional contact resolver for name-to-address resolution.
+     */
+    contacts?: IContactResolver;
+    /**
+     * Network-specific configuration (API keys).
+     */
+    networks?: {
+        mainnet?: NetworkConfig;
+        testnet?: NetworkConfig;
+    };
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/types/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,aAAa,CAAC;QACxB,OAAO,CAAC,EAAE,aAAa,CAAC;KAC3B,CAAC;CACL"}

package/dist/types/contacts.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/**
+ * IContactResolver - Optional interface for resolving friend names to TON addresses
+ *
+ * Purpose: Allow users to send to "Alice" instead of raw addresses.
+ * Contacts are scoped to the user who created them.
+ */
+/**
+ * Contact information
+ */
+export interface Contact {
+    /** Human-readable name for the contact */
+    name: string;
+    /** TON address */
+    address: string;
+    /** Optional network specification (defaults to any) */
+    network?: 'mainnet' | 'testnet';
+}
+/**
+ * Interface for contact resolution.
+ * All operations are scoped to a specific user.
+ */
+export interface IContactResolver {
+    /**
+     * Resolve a contact name to an address.
+     *
+     * @param userId - The user's ID
+     * @param name - The contact name to resolve
+     * @returns The TON address or null if not found
+     */
+    resolve(userId: string, name: string): Promise<string | null>;
+    /**
+     * Add a new contact for a user.
+     *
+     * @param userId - The user's ID
+     * @param contact - The contact to add
+     */
+    addContact(userId: string, contact: Contact): Promise<void>;
+    /**
+     * List all contacts for a user.
+     *
+     * @param userId - The user's ID
+     * @returns Array of contacts
+     */
+    listContacts(userId: string): Promise<Contact[]>;
+    /**
+     * Remove a contact by name.
+     *
+     * @param userId - The user's ID
+     * @param name - The contact name to remove
+     * @returns true if removed, false if not found
+     */
+    removeContact(userId: string, name: string): Promise<boolean>;
+}
+//# sourceMappingURL=contacts.d.ts.map

package/dist/types/contacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contacts.d.ts","sourceRoot":"","sources":["../../src/types/contacts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,OAAO;IACpB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE9D;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjE"}

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/**
+ * Type exports for @ton/mcp package
+ */
+export type { IContactResolver, Contact } from './contacts.js';
+export type { TonMcpConfig, NetworkConfig } from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AAGH,YAAY,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG/D,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/llms.txt

@@ -0,0 +1,114 @@
+# TON MCP Server
+
+> TON blockchain wallet operations via Model Context Protocol
+
+## Overview
+
+This MCP server provides tools for managing TON blockchain wallets. It supports balance queries, transfers (TON, Jettons, NFTs), token swaps, transaction history, and DNS resolution.
+
+## Available Tools
+
+### get_balance
+Get TON balance of the wallet.
+Returns: address, balance in TON and nanoTON
+
+### get_jetton_balance
+Get balance of a specific Jetton token.
+Parameters:
+- jettonAddress (required): Jetton master contract address
+
+### get_jettons
+List all Jettons in the wallet with balances and metadata.
+Returns: array of tokens with address, symbol, name, balance, decimals
+
+### get_transactions
+Get recent transaction history.
+Parameters:
+- limit (optional): 1-100, default 20
+Returns: transactions with type (TonTransfer, JettonTransfer, JettonSwap), amounts, addresses
+
+### get_known_jettons
+Get list of known/popular Jettons on TON.
+Returns: array with symbol, name, address, decimals
+
+### send_ton
+Send TON to an address.
+Parameters:
+- toAddress (required): recipient address
+- amount (required): amount in TON (e.g., "1.5")
+- comment (optional): transaction memo
+
+### send_jetton
+Send Jettons to an address.
+Parameters:
+- toAddress (required): recipient address
+- jettonAddress (required): token contract address
+- amount (required): human-readable amount
+- comment (optional): transaction memo
+
+### send_raw_transaction
+Send raw transaction with full control.
+Parameters:
+- messages (required): array of {address, amount (nanoTON), stateInit?, payload?}
+- validUntil (optional): expiry timestamp
+- fromAddress (optional): sender address
+
+### get_swap_quote
+Get quote for token swap.
+Parameters:
+- fromToken (required): "TON" or jetton address
+- toToken (required): "TON" or jetton address
+- amount (required): amount in raw units
+- slippageBps (optional): slippage in basis points (100 = 1%)
+Returns: quote details + transaction params for send_raw_transaction
+
+### get_nfts
+List NFTs in the wallet.
+Parameters:
+- limit (optional): 1-100, default 20
+- offset (optional): pagination offset
+
+### get_nft
+Get NFT details.
+Parameters:
+- nftAddress (required): NFT item contract address
+
+### send_nft
+Transfer NFT to another address.
+Parameters:
+- nftAddress (required): NFT to transfer
+- toAddress (required): recipient address
+- comment (optional): transaction memo
+
+### resolve_dns
+Resolve .ton domain to wallet address.
+Parameters:
+- domain (required): e.g., "foundation.ton"
+
+### back_resolve_dns
+Find .ton domain for a wallet address.
+Parameters:
+- address (required): TON wallet address
+
+## Usage Patterns
+
+### Sending TON
+1. If recipient is .ton domain: resolve_dns first
+2. send_ton with resolved address
+
+### Sending Tokens
+1. get_jettons to find token address
+2. send_jetton with token details
+
+### Swapping Tokens
+1. get_known_jettons if needed for addresses
+2. get_swap_quote for quote
+3. Confirm with user
+4. send_raw_transaction with quote's transaction params
+
+## Important Notes
+
+- Always confirm transfers/swaps with user before executing
+- send_ton/send_jetton use human-readable amounts
+- get_swap_quote uses raw amounts (with decimals applied)
+- Check transaction success in response

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@ton/mcp",
+  "version": "0.1.10",
+  "description": "TON MCP Server - Model Context Protocol server for TON blockchain wallet operations",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": "./dist/cli.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./serverless": {
+      "import": {
+        "types": "./dist/serverless.d.ts",
+        "default": "./dist/serverless.js"
+      },
+      "require": {
+        "types": "./dist/serverless.d.ts",
+        "default": "./dist/serverless.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "llms.txt",
+    "README.md"
+  ],
+  "keywords": [
+    "ton",
+    "mcp",
+    "wallet",
+    "model-context-protocol",
+    "blockchain"
+  ],
+  "author": "TON Tech",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ton-connect/kit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "zod": "^3.25.76",
+    "@ton/walletkit": "0.0.6"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.29",
+    "@vitest/coverage-v8": "^4.0.17",
+    "rimraf": "^6.1.0",
+    "rolldown": "1.0.0-rc.2",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "pnpm build:clean && rolldown -c && pnpm build:types && pnpm build:chmod",
+    "build:clean": "rimraf dist",
+    "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
+    "build:chmod": "chmod +x dist/cli.js",
+    "dev": "rolldown -c --watch",
+    "dev:cli": "node --import tsx/esm src/cli.ts",
+    "dev:cli:http": "node --import tsx/esm src/cli.ts --http",
+    "lint": "eslint src --max-warnings 0",
+    "lint:fix": "eslint src --max-warnings 0 --fix",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,67 @@
+# TON Blockchain Wallet
+
+Manage TON blockchain wallet operations including balance queries, transfers, swaps, NFTs, and DNS resolution.
+
+## When to Use
+
+Use this skill when the user wants to:
+- Check TON or token balances
+- Send TON, Jettons (tokens), or NFTs
+- Swap tokens on DEX
+- View transaction history
+- Resolve .ton domains
+
+## Tools Available
+
+### Balance & Info
+- `get_balance` - Get TON balance
+- `get_jetton_balance` - Get specific token balance (needs `jettonAddress`)
+- `get_jettons` - List all tokens in wallet
+- `get_transactions` - View recent transactions (optional `limit`)
+- `get_known_jettons` - Get list of popular tokens with addresses
+
+### Transfers
+- `send_ton` - Send TON (`toAddress`, `amount` in TON like "1.5", optional `comment`)
+- `send_jetton` - Send tokens (`toAddress`, `jettonAddress`, `amount`, optional `comment`)
+- `send_nft` - Transfer NFT (`nftAddress`, `toAddress`, optional `comment`)
+- `send_raw_transaction` - Advanced: send raw transaction with multiple messages
+
+### Swaps
+- `get_swap_quote` - Get swap quote (`fromToken`, `toToken`, `amount` in raw units)
+  - Use "TON" or jetton address for tokens
+  - Returns transaction params for `send_raw_transaction`
+
+### NFTs
+- `get_nfts` - List wallet NFTs (optional `limit`, `offset`)
+- `get_nft` - Get NFT details (`nftAddress`)
+
+### DNS
+- `resolve_dns` - Resolve .ton domain to address (`domain` like "foundation.ton")
+- `back_resolve_dns` - Find domain for address (`address`)
+
+## Common Workflows
+
+### Check Balance
+1. Call `get_balance` for TON
+2. Call `get_jettons` for all tokens
+
+### Send TON
+1. If user provides .ton domain, call `resolve_dns` first
+2. Call `send_ton` with address and amount
+
+### Send Token
+1. Call `get_jettons` to find token address and verify balance
+2. Call `send_jetton` with token address and amount
+
+### Swap Tokens
+1. Call `get_known_jettons` if user mentions token by name
+2. Call `get_swap_quote` to get quote and transaction params
+3. Show quote to user and ask for confirmation
+4. Call `send_raw_transaction` with the transaction params
+
+## Notes
+
+- Amounts for `send_ton` and `send_jetton` are human-readable (e.g., "1.5" = 1.5 TON)
+- Amounts for `get_swap_quote` are in raw units (apply decimals)
+- Always confirm with user before executing transfers or swaps
+- Transaction results include success status and details