iz-tolk-mcp — Tolk Compiler for TON

📖 概述

iz-tolk-mcp 是一个 Model Context Protocol（MCP）服务，可将 Tolk 智能合约编译器集成到 AI 助手中，为 TON 区块链开发提供顺畅的编写、编译和部署工作流。

• Tolk 是面向 TON 区块链的新一代智能合约语言，旨在作为 FunC 的现代继任者，具有熟悉的语法（类似 C/TypeScript）、类型安全性和更清晰的语义。
• MCP（Model Context Protocol）是一项开放标准，可让 AI 助手使用外部工具、访问数据源并遵循引导式工作流，从而将它们转变为功能强大的开发环境。

✨ 功能特性

🚀 快速开始

npx iz-tolk-mcp

服务通过标准输入/输出（stdio）通信，设计为由 MCP 客户端启动。

📦 安装

使用 npx（无需安装）

MCP 客户端会自动启动服务——只需将其添加到配置中（见下文）。

全局安装

npm install -g iz-tolk-mcp

从源代码安装

git clone https://github.com/izzzzzi/izTolkMcp.git
cd izTolkMcp
npm install
npm run build

要求： Node.js >= 18

🔧 MCP 客户端配置

{
  "mcpServers": {
    "tolk": {
      "command": "npx",
      "args": ["-y", "iz-tolk-mcp"]
    }
  }
}

claude mcp add tolk -- npx -y iz-tolk-mcp

{
  "mcpServers": {
    "tolk": {
      "command": "npx",
      "args": ["-y", "iz-tolk-mcp"]
    }
  }
}

{
  "mcpServers": {
    "tolk": {
      "command": "npx",
      "args": ["-y", "iz-tolk-mcp"]
    }
  }
}

{
  "servers": {
    "tolk": {
      "command": "npx",
      "args": ["-y", "iz-tolk-mcp"]
    }
  }
}

{
  "mcpServers": {
    "tolk": {
      "command": "node",
      "args": ["/absolute/path/to/izTolkMcp/dist/cli.js"]
    }
  }
}

🛠️ MCP 工具

🔍 get_compiler_version

返回 @ton/tolk-js（WASM）中捆绑的 Tolk 编译器版本。

🔨 compile_tolk

编译 Tolk 智能合约源代码。返回 Fift 输出、Base64 格式的 BoC（单元格包）、代码哈希和编译器版本。

✅ check_tolk_syntax

检查 Tolk 源代码中的语法和类型错误，不返回完整的编译输出。可在迭代开发中更快地获得反馈。

🔗 generate_deploy_link

为已编译的合约生成 TON 部署深度链接。计算确定性合约地址，并返回可用于通过钱包部署的 ton:// 和 Tonkeeper 链接。

📄 MCP 资源

💬 MCP 提示词

write_smart_contract

在 TON 上编写新 Tolk 智能合约的引导式工作流。将语言参考和相关合约示例注入对话上下文。

review_smart_contract

以安全性为重点审查 Tolk 智能合约。检查访问控制、消息处理、整数溢出、Gas 管理、存储完整性以及 TON 特有的漏洞。

debug_compilation_error

诊断并修复 Tolk 编译错误。根据语言参考分析错误，并提供修正后的代码。

💡 使用示例

配置完成后，可以在 AI 助手中使用自然语言与 Tolk MCP 服务交互：

编译合约：

“编译这个 Tolk 智能合约：”

import "@stdlib/tvm-dicts";

fun onInternalMessage(myBalance: int, msgValue: int, msgFull: cell, msgBody: slice) {
    // handle messages
}

从头编写新合约：

“为 TON 编写一个简单的计数器合约，用于存储一个数字，并允许任何人递增该数字。添加一个 getter 以读取当前值。”

审查现有合约：

“检查这个合约是否存在安全问题” （粘贴代码）

调试编译错误：

“编译时出现此错误：unexpected token 'fun'——这是我的代码：” （粘贴代码）

生成部署链接：

“为我们刚刚编译的合约生成部署链接。”

📁 项目结构

src/
├── index.ts        — Server initialization and stdio transport
├── tools.ts        — 4 MCP tools (compile, check, version, deploy)
├── resources.ts    — 6 MCP resources (docs, examples)
├── prompts.ts      — 3 MCP prompts (write, review, debug)
└── content/        — Bundled documentation and example contracts
    ├── language-guide.md
    ├── stdlib-reference.md
    ├── changelog.md
    ├── tolk-vs-func.md
    ├── example-counter.tolk
    └── example-jetton.tolk

主要依赖：

• @modelcontextprotocol/sdk — MCP 服务框架
• @ton/tolk-js — Tolk 编译器（WASM，在本地运行）
• @ton/core — 用于地址计算和单元序列化的 TON 原语
• zod — 工具参数的模式验证

🧑‍💻 开发

npm install          # Install dependencies
npm run build        # Compile TypeScript + copy content files
npm run dev          # Run with tsx (hot reload for development)
npm test             # Run test suite (vitest)
npm run lint         # Check for lint errors
npm run lint:fix     # Fix lint errors automatically
npm run format       # Format code with Biome

提交前钩子会自动执行代码质量检查：

• Biome — 快速的 TypeScript 代码检查与格式化工具
• Husky — Git 钩子管理器
• lint-staged — 仅对已暂存的文件运行检查