📖 Overview

iz-tolk-mcp is a Model Context Protocol (MCP) server that integrates the Tolk smart contract compiler into AI assistants, enabling a seamless write-compile-deploy workflow for TON blockchain development.

• 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.
• 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.

✨ Features

🚀 Quick Start

npx iz-tolk-mcp

The server communicates over stdio and is designed to be launched by an MCP client.

📦 Installation

Using npx (no install needed)

MCP clients launch the server automatically — just add it to your configuration (see below).

Global install

npm install -g iz-tolk-mcp

From source

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

Requirement: Node.js >= 18

🔧 MCP Client Configuration

{
  "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/index.js"]
    }
  }
}

🛠️ MCP Tools

🔍 get_compiler_version

Returns the version of the Tolk compiler bundled in @ton/tolk-js (WASM).

🔨 compile_tolk

Compiles Tolk smart contract source code. Returns Fift output, BoC (Bag of Cells) in base64, and the code hash.

✅ check_tolk_syntax

Checks Tolk source code for syntax and type errors without returning full compilation output. Faster feedback loop for iterative development.

🔗 generate_deploy_link

Generates TON deployment deeplinks for a compiled contract. Computes the deterministic contract address and returns ton:// and Tonkeeper links ready for wallet deployment.

📄 MCP Resources

💬 MCP Prompts

write_smart_contract

Guided workflow for writing a new Tolk smart contract on TON. Injects the language reference and a relevant example contract into the conversation context.

review_smart_contract

Security-focused review of a Tolk smart contract. Checks for access control, message handling, integer overflow, gas management, storage integrity, and TON-specific vulnerabilities.

debug_compilation_error

Diagnose and fix a Tolk compilation error. Analyzes the error against the language reference and provides corrected code.

💡 Usage Examples

Once configured, interact with the Tolk MCP server through natural language in your AI assistant:

Compile a contract:

"Compile this Tolk smart contract:"

import "@stdlib/tvm-dicts";

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

Write a new contract from scratch:

"Write a simple counter contract for TON that stores a number and lets anyone increment it. Include a getter to read the current value."

Review an existing contract:

"Review this contract for security issues" (paste code)

Debug a compilation error:

"I'm getting this error when compiling: unexpected token 'fun' — here's my code:" (paste code)

Generate a deploy link:

"Generate a deployment link for the contract we just compiled."

📁 Project Structure

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

Key dependencies:

• @modelcontextprotocol/sdk — MCP server framework
• @ton/tolk-js — Tolk compiler (WASM, runs locally)
• @ton/core — TON primitives for address computation and cell serialization
• zod — Schema validation for tool parameters

🧑‍💻 Development

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

Pre-commit hooks enforce code quality automatically:

• Biome — fast linter and formatter for TypeScript
• Husky — Git hooks manager
• lint-staged — runs checks only on staged files

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Use Conventional Commits for commit messages
4. Run npm run lint && npm test before submitting
5. Open a Pull Request

📄 License

MIT © iz-tolk-mcp contributors