{
  "markdown": "<div align=\"center\">\n\n# iz-tolk-mcp\n\n**MCP server for the Tolk smart contract compiler — compile, check, and deploy TON blockchain smart contracts from any AI assistant**\n\n[![CI](https://github.com/izzzzzi/izTolkMcp/actions/workflows/ci.yml/badge.svg)](https://github.com/izzzzzi/izTolkMcp/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/iz-tolk-mcp.svg?style=flat&colorA=18181B&colorB=28CF8D)](https://www.npmjs.com/package/iz-tolk-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/iz-tolk-mcp.svg?style=flat&colorA=18181B&colorB=28CF8D)](https://www.npmjs.com/package/iz-tolk-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat&colorA=18181B&colorB=28CF8D)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat&colorA=18181B&colorB=3178C6)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-ESM-green?style=flat&colorA=18181B&colorB=339933)](https://nodejs.org/)\n\n[🇷🇺 Русский](README.ru.md) | **🇬🇧 English**\n\n<br />\n\n*MCP server that brings the [Tolk](https://docs.ton.org/v3/documentation/smart-contracts/tolk/overview) smart contract compiler directly into AI assistants like Claude — write, compile, check, and deploy TON contracts without leaving the conversation.*\n\n</div>\n\n---\n\n## 📖 Overview\n\n**iz-tolk-mcp** is a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that integrates the Tolk smart contract compiler into AI assistants, enabling a seamless write-compile-deploy workflow for TON blockchain development.\n\n- **Tolk** is the next-generation smart contract language for the TON blockchain, designed as a modern successor to FunC with familiar syntax (C/TypeScript-like), type safety, and cleaner semantics.\n- **MCP** (Model Context Protocol) is an open standard that lets AI assistants use external tools, access data sources, and follow guided workflows — turning them into capable development environments.\n\n---\n\n## ✨ Features\n\n| Feature | Description |\n|---------|-------------|\n| 🔨 **4 MCP Tools** | `compile_tolk`, `check_tolk_syntax`, `get_compiler_version`, `generate_deploy_link` |\n| 📄 **6 MCP Resources** | Language guide, stdlib reference, changelog, FunC migration guide, example contracts |\n| 💬 **3 MCP Prompts** | Guided workflows for writing, reviewing, and debugging smart contracts |\n| ⚙️ **Full Compiler Options** | Optimization levels (0-2), stack comments, path mappings, multi-file compilation |\n| 📦 **Multi-file Support** | Compile projects with multiple `.tolk` source files, `@stdlib/*` and `@fiftlib/*` imports |\n| 🔗 **Deployment Links** | Generate `ton://` deeplinks and Tonkeeper URLs for wallet deployment |\n| 🚀 **Zero Configuration** | Runs via `npx` with no external dependencies beyond Node.js |\n\n---\n\n## 🚀 Quick Start\n\n```bash\nnpx iz-tolk-mcp\n```\n\nThe server communicates over stdio and is designed to be launched by an MCP client.\n\n---\n\n## 📦 Installation\n\n### Using npx (no install needed)\n\nMCP clients launch the server automatically — just add it to your configuration (see below).\n\n### Global install\n\n```bash\nnpm install -g iz-tolk-mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/izzzzzi/izTolkMcp.git\ncd izTolkMcp\nnpm install\nnpm run build\n```\n\n> **Requirement:** Node.js >= 18\n\n---\n\n## 🔧 MCP Client Configuration\n\n<details>\n<summary><b>Claude Desktop</b></summary>\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"tolk\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"iz-tolk-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Claude Code</b></summary>\n\n```bash\nclaude mcp add tolk -- npx -y iz-tolk-mcp\n```\n\n</details>\n\n<details>\n<summary><b>Cursor</b></summary>\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"tolk\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"iz-tolk-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Windsurf</b></summary>\n\nAdd to `~/.windsurf/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"tolk\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"iz-tolk-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>VS Code (Copilot)</b></summary>\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"tolk\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"iz-tolk-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Local build (any client)</b></summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"tolk\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/izTolkMcp/dist/cli.js\"]\n    }\n  }\n}\n```\n\n</details>\n\n---\n\n## 🛠️ MCP Tools\n\n### 🔍 `get_compiler_version`\n\nReturns the version of the Tolk compiler bundled in `@ton/tolk-js` (WASM).\n\n| Parameter | Type | Required | Description |\n|-----------|------|:--------:|-------------|\n| *(none)* | — | — | No parameters |\n\n### 🔨 `compile_tolk`\n\nCompiles Tolk smart contract source code. Returns Fift output, BoC (Bag of Cells) in base64, code hash, and compiler version.\n\n| Parameter | Type | Required | Description |\n|-----------|------|:--------:|-------------|\n| `entrypointFileName` | `string` | ✅ | The main `.tolk` file to compile (e.g., `\"main.tolk\"`) |\n| `sources` | `object` | ✅ | Map of `filename -> source code`. Must include the entrypoint file. |\n| `optimizationLevel` | `number` | — | Optimization level 0-2 (default: 2) |\n| `withStackComments` | `boolean` | — | Include stack layout comments in Fift output |\n| `pathMappings` | `object` | — | Maps `@alias` prefixes to folder paths for import resolution |\n\n### ✅ `check_tolk_syntax`\n\nChecks Tolk source code for syntax and type errors without returning full compilation output. Faster feedback loop for iterative development.\n\n| Parameter | Type | Required | Description |\n|-----------|------|:--------:|-------------|\n| `entrypointFileName` | `string` | ✅ | The main `.tolk` file to check |\n| `sources` | `object` | ✅ | Map of `filename -> source code` |\n| `pathMappings` | `object` | — | Maps `@alias` prefixes to folder paths for import resolution |\n\n### 🔗 `generate_deploy_link`\n\nGenerates TON deployment deeplinks for a compiled contract. Computes the deterministic contract address and returns `ton://` and Tonkeeper links ready for wallet deployment.\n\n| Parameter | Type | Required | Description |\n|-----------|------|:--------:|-------------|\n| `codeBoc64` | `string` | ✅ | Base64-encoded BoC of compiled contract code (from `compile_tolk`) |\n| `initialDataBoc64` | `string` | — | Base64-encoded BoC for initial data cell (default: empty cell) |\n| `workchain` | `number` | — | Target workchain ID (default: 0) |\n| `amount` | `string` | — | Deploy amount in nanoTON (default: `\"50000000\"` = 0.05 TON) |\n\n---\n\n## 📄 MCP Resources\n\n| Resource | URI | Description |\n|----------|-----|-------------|\n| 📘 `language-guide` | `tolk://docs/language-guide` | Complete Tolk language syntax reference |\n| 📗 `stdlib-reference` | `tolk://docs/stdlib-reference` | Standard library modules and functions reference |\n| 📋 `changelog` | `tolk://docs/changelog` | Tolk compiler version history from v0.6 to latest |\n| 🔄 `tolk-vs-func` | `tolk://docs/tolk-vs-func` | FunC to Tolk migration guide — key differences and comparison |\n| 📝 `example-counter` | `tolk://examples/counter` | Simple counter smart contract example in Tolk |\n| 💎 `example-jetton` | `tolk://examples/jetton` | Jetton (fungible token) minter contract example in Tolk |\n\n---\n\n## 💬 MCP Prompts\n\n### `write_smart_contract`\n\nGuided workflow for writing a new Tolk smart contract on TON. Injects the language reference and a relevant example contract into the conversation context.\n\n| Argument | Type | Required | Description |\n|----------|------|:--------:|-------------|\n| `description` | `string` | ✅ | Description of what the smart contract should do |\n| `contractType` | `string` | — | `\"counter\"` \\| `\"jetton\"` \\| `\"nft\"` \\| `\"wallet\"` \\| `\"custom\"` (default: `\"custom\"`) |\n\n### `review_smart_contract`\n\nSecurity-focused review of a Tolk smart contract. Checks for access control, message handling, integer overflow, gas management, storage integrity, and TON-specific vulnerabilities.\n\n| Argument | Type | Required | Description |\n|----------|------|:--------:|-------------|\n| `code` | `string` | ✅ | The Tolk smart contract source code to review |\n\n### `debug_compilation_error`\n\nDiagnose and fix a Tolk compilation error. Analyzes the error against the language reference and provides corrected code.\n\n| Argument | Type | Required | Description |\n|----------|------|:--------:|-------------|\n| `errorMessage` | `string` | ✅ | The compilation error message from the Tolk compiler |\n| `code` | `string` | ✅ | The Tolk source code that failed to compile |\n\n---\n\n## 💡 Usage Examples\n\nOnce configured, interact with the Tolk MCP server through natural language in your AI assistant:\n\n**Compile a contract:**\n\n> \"Compile this Tolk smart contract:\"\n> ```tolk\n> import \"@stdlib/tvm-dicts\";\n>\n> fun onInternalMessage(myBalance: int, msgValue: int, msgFull: cell, msgBody: slice) {\n>     // handle messages\n> }\n> ```\n\n**Write a new contract from scratch:**\n\n> \"Write a simple counter contract for TON that stores a number and lets anyone increment it. Include a getter to read the current value.\"\n\n**Review an existing contract:**\n\n> \"Review this contract for security issues\" *(paste code)*\n\n**Debug a compilation error:**\n\n> \"I'm getting this error when compiling: `unexpected token 'fun'` — here's my code:\" *(paste code)*\n\n**Generate a deploy link:**\n\n> \"Generate a deployment link for the contract we just compiled.\"\n\n---\n\n## 📁 Project Structure\n\n```\nsrc/\n├── index.ts        — Server initialization and stdio transport\n├── tools.ts        — 4 MCP tools (compile, check, version, deploy)\n├── resources.ts    — 6 MCP resources (docs, examples)\n├── prompts.ts      — 3 MCP prompts (write, review, debug)\n└── content/        — Bundled documentation and example contracts\n    ├── language-guide.md\n    ├── stdlib-reference.md\n    ├── changelog.md\n    ├── tolk-vs-func.md\n    ├── example-counter.tolk\n    └── example-jetton.tolk\n```\n\nKey dependencies:\n\n- `@modelcontextprotocol/sdk` — MCP server framework\n- `@ton/tolk-js` — Tolk compiler (WASM, runs locally)\n- `@ton/core` — TON primitives for address computation and cell serialization\n- `zod` — Schema validation for tool parameters\n\n---\n\n## 🧑‍💻 Development\n\n```bash\nnpm install          # Install dependencies\nnpm run build        # Compile TypeScript + copy content files\nnpm run dev          # Run with tsx (hot reload for development)\nnpm test             # Run test suite (vitest)\nnpm run lint         # Check for lint errors\nnpm run lint:fix     # Fix lint errors automatically\nnpm run format       # Format code with Biome\n```\n\nPre-commit hooks enforce code quality automatically:\n\n- **Biome** — fast linter and formatter for TypeScript\n- **Husky** — Git hooks manager\n- **lint-staged** — runs checks only on staged files\n\n",
  "bytes": 10865,
  "sha": "055606cacf5e28411dc0fdc131c3057e508840c4219ad107eef2b4ecc45ab4e9",
  "repo_slug": "izzzzzi/iztolkmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_izzzzzi_iz_tolk_mcp_1be42424/readme"
}