Z-tolk-mcp
Tolk智能合约编译器的MCP服务器——从任何AI助手编译、检查和部署TON区块链智能合约
🇷🇺 俄语 | 🇬🇧 英语
*MCP服务器，带来 托尔金 智能合约编译器直接集成到像Claude这样的人工智能助手中——编写、编译、检查和部署TON合约，而无需离开对话。*
______________________________________________________________________
📖 概述
Z-tolk-mcp 是一个 模型上下文协议 （MCP）服务器，将Tolk智能合约编译器集成到AI助手中，为TON区块链开发提供无缝的写-编译-部署工作流。
- 托尔金 是TON区块链的下一代智能合约语言，被设计为FunC的现代继承者，具有熟悉的语法（类似于C/TypeScript）、类型安全和更清晰的语义。
- 主控程序 （模型上下文协议）是一个开放标准，允许AI助手使用外部工具、访问数据源并遵循指导的工作流程，将其转化为功能强大的开发环境。
______________________________________________________________________
✨ 特性
| 特性 | 描述 |
|---|---|
| 🔨 4个MCP工具 | compile_tolk, check_tolk_syntax, get_compiler_version, generate_deploy_link |
| 📄 6 MCP资源 | 语言指南、stdlib参考、变更日志、FunC迁移指南、示例合约 |
| 💬 3个MCP提示 | 编写、审查和调试智能合约的指导工作流程 |
| ⚙️ 完整编译器选项 | 优化级别（0-2）、堆栈注释、路径映射、多文件编译 |
| 📦 多文件支持 | 编译多个项目 .tolk 源文件， @stdlib/* 和 @fiftlib/* 进口 |
| 🔗 部署链接 | 生成 ton:// 用于钱包部署的深度链接和Tonkeeper URL |
| 🚀 零配置 | 运行通过 npx 除了Node.js之外没有外部依赖 |
______________________________________________________________________
🚀 快速开始
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客户端配置
Claude Desktop
添加 claude_desktop_config.json:
{
"mcpServers": {
"tolk": {
"command": "npx",
"args": ["-y", "iz-tolk-mcp"]
}
}
}Claude Code
claude mcp add tolk -- npx -y iz-tolk-mcpCursor
添加 .cursor/mcp.json:
{
"mcpServers": {
"tolk": {
"command": "npx",
"args": ["-y", "iz-tolk-mcp"]
}
}
}Windsurf
添加 ~/.windsurf/mcp.json:
{
"mcpServers": {
"tolk": {
"command": "npx",
"args": ["-y", "iz-tolk-mcp"]
}
}
}VS Code (Copilot)
添加 .vscode/mcp.json:
{
"servers": {
"tolk": {
"command": "npx",
"args": ["-y", "iz-tolk-mcp"]
}
}
}Local build (any client)
{
"mcpServers": {
"tolk": {
"command": "node",
"args": ["/absolute/path/to/izTolkMcp/dist/cli.js"]
}
}
}______________________________________________________________________
🛠️ MCP工具
🔍 get_compiler_version
返回捆绑在中的Tolk编译器的版本 @ton/tolk-js （WASM）。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| *（无）* | -- | -- | 无参数 |
🔨 compile_tolk
编译Tolk智能合约源代码。返回Fift输出、base64格式的BoC（Bag of Cells）、代码哈希和编译器版本。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
entrypointFileName | string | ✅ | 主要 .tolk 要编译的文件（例如。， "main.tolk") |
sources | object | ✅ | 地图 filename -> source code。必须包含入口点文件。 |
optimizationLevel | number | -- | 优化级别0-2（默认值：2） |
withStackComments | boolean | -- | 在Fift输出中包含堆栈布局注释 |
pathMappings | object | -- | 地图 @alias 用于导入解析的文件夹路径前缀 |
✅ check_tolk_syntax
检查Tolk源代码的语法和类型错误，但不返回完整的编译输出。迭代开发的更快反馈循环。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
entrypointFileName | string | ✅ | 主要 .tolk 要检查的文件 |
sources | object | ✅ | 地图 filename -> source code |
pathMappings | object | -- | 地图 @alias 用于导入解析的文件夹路径前缀 |
🔗 generate_deploy_link
为已编译的合约生成TON部署深度链接。计算确定性合约地址并返回 ton:// Tonkeeper链接已准备好进行钱包部署。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
codeBoc64 | string | ✅ | Base64编码的已编译合同代码的BoC（来自 compile_tolk) |
initialDataBoc64 | string | -- | 初始数据单元格使用Base64编码的BoC（默认值：空单元格） |
workchain | number | -- | 目标工作链ID（默认值：0） |
amount | string | -- | 部署数量单位为nanoTON（默认值： "50000000" =0.05吨） |
______________________________________________________________________
📄 MCP资源
| 资源 | URI | 描述 |
|---|---|---|
📘 language-guide | tolk://docs/language-guide | 完整的托尔克语言语法参考 |
📗 stdlib-reference | tolk://docs/stdlib-reference | 标准库模块和函数参考 |
📋 changelog | tolk://docs/changelog | Tolk编译器从v0.6到最新版本的版本历史记录 |
🔄 tolk-vs-func | tolk://docs/tolk-vs-func | FunC到Tolk迁移指南——主要差异和比较 |
📝 example-counter | tolk://examples/counter | Tolk中简单的计数器智能合约示例 |
💎 example-jetton | tolk://examples/jetton | 托尔克的Jetton（可替代代币）铸币合同示例 |
______________________________________________________________________
💬 MCP提示
write_smart_contract
指导在TON上编写新的Tolk智能合约的工作流程。将语言参考和相关的示例合同注入到对话上下文中。
| 参数 | 类型 | 必填 | 描述 | ||||
|---|---|---|---|---|---|---|---|
description | string | ✅ | 智能合约应该做什么的描述 | ||||
contractType | string | — | "counter" | "jetton" | "nft" | "wallet" | "custom" （默认值： "custom") |
review_smart_contract
对Tolk智能合约的安全审查。检查访问控制、消息处理、整数溢出、气体管理、存储完整性和TON特定漏洞。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
code | string | ✅ | 托尔克智能合约源代码审查 |
debug_compilation_error
诊断并修复Tolk编译错误。根据语言参考分析错误并提供更正的代码。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
errorMessage | string | ✅ | 来自Tolk编译器的编译错误消息 |
code | string | ✅ | 编译失败的Tolk源代码 |
______________________________________________________________________
💡 使用示例
配置后，通过AI助手中的自然语言与Tolk MCP服务器进行交互：
编写合同：
“编译此Tolk智能合约：” ``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预提交钩子会自动强制执行代码质量：
- 生物群系 --TypeScript的快速linter和格式化程序
- 哈士奇 --Git挂钩管理器
- 皮棉上演 --仅对暂存文件运行检查