# iz-tolk-mcp
**MCP server for the Tolk smart contract compiler β compile, check, and deploy TON blockchain smart contracts from any AI assistant**
[](https://github.com/izzzzzi/izTolkMcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/iz-tolk-mcp)
[](https://www.npmjs.com/package/iz-tolk-mcp)
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[π·πΊ Π ΡΡΡΠΊΠΈΠΉ](README.ru.md) | **π¬π§ English**
*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.*
---
## π Overview
**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.
- **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
| Feature | Description |
|---------|-------------|
| π¨ **4 MCP Tools** | `compile_tolk`, `check_tolk_syntax`, `get_compiler_version`, `generate_deploy_link` |
| π **6 MCP Resources** | Language guide, stdlib reference, changelog, FunC migration guide, example contracts |
| π¬ **3 MCP Prompts** | Guided workflows for writing, reviewing, and debugging smart contracts |
| βοΈ **Full Compiler Options** | Optimization levels (0-2), stack comments, path mappings, multi-file compilation |
| π¦ **Multi-file Support** | Compile projects with multiple `.tolk` source files, `@stdlib/*` and `@fiftlib/*` imports |
| π **Deployment Links** | Generate `ton://` deeplinks and Tonkeeper URLs for wallet deployment |
| π **Zero Configuration** | Runs via `npx` with no external dependencies beyond Node.js |
---
## π Quick Start
```bash
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
```bash
npm install -g iz-tolk-mcp
```
### From source
```bash
git clone https://github.com/izzzzzi/izTolkMcp.git
cd izTolkMcp
npm install
npm run build
```
> **Requirement:** Node.js >= 18
---
## π§ MCP Client Configuration
Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"tolk": {
"command": "npx",
"args": ["-y", "iz-tolk-mcp"]
}
}
}
```
Claude Code
```bash
claude mcp add tolk -- npx -y iz-tolk-mcp
```
Cursor
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"tolk": {
"command": "npx",
"args": ["-y", "iz-tolk-mcp"]
}
}
}
```
Windsurf
Add to `~/.windsurf/mcp.json`:
```json
{
"mcpServers": {
"tolk": {
"command": "npx",
"args": ["-y", "iz-tolk-mcp"]
}
}
}
```
VS Code (Copilot)
Add to `.vscode/mcp.json`:
```json
{
"servers": {
"tolk": {
"command": "npx",
"args": ["-y", "iz-tolk-mcp"]
}
}
}
```
Local build (any client)
```json
{
"mcpServers": {
"tolk": {
"command": "node",
"args": ["/absolute/path/to/izTolkMcp/dist/cli.js"]
}
}
}
```
---
## π οΈ MCP Tools
### π `get_compiler_version`
Returns the version of the Tolk compiler bundled in `@ton/tolk-js` (WASM).
| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| *(none)* | β | β | No parameters |
### π¨ `compile_tolk`
Compiles Tolk smart contract source code. Returns Fift output, BoC (Bag of Cells) in base64, code hash, and compiler version.
| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| `entrypointFileName` | `string` | β
| The main `.tolk` file to compile (e.g., `"main.tolk"`) |
| `sources` | `object` | β
| Map of `filename -> source code`. Must include the entrypoint file. |
| `optimizationLevel` | `number` | β | Optimization level 0-2 (default: 2) |
| `withStackComments` | `boolean` | β | Include stack layout comments in Fift output |
| `pathMappings` | `object` | β | Maps `@alias` prefixes to folder paths for import resolution |
### β
`check_tolk_syntax`
Checks Tolk source code for syntax and type errors without returning full compilation output. Faster feedback loop for iterative development.
| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| `entrypointFileName` | `string` | β
| The main `.tolk` file to check |
| `sources` | `object` | β
| Map of `filename -> source code` |
| `pathMappings` | `object` | β | Maps `@alias` prefixes to folder paths for import resolution |
### π `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.
| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| `codeBoc64` | `string` | β
| Base64-encoded BoC of compiled contract code (from `compile_tolk`) |
| `initialDataBoc64` | `string` | β | Base64-encoded BoC for initial data cell (default: empty cell) |
| `workchain` | `number` | β | Target workchain ID (default: 0) |
| `amount` | `string` | β | Deploy amount in nanoTON (default: `"50000000"` = 0.05 TON) |
---
## π MCP Resources
| Resource | URI | Description |
|----------|-----|-------------|
| π `language-guide` | `tolk://docs/language-guide` | Complete Tolk language syntax reference |
| π `stdlib-reference` | `tolk://docs/stdlib-reference` | Standard library modules and functions reference |
| π `changelog` | `tolk://docs/changelog` | Tolk compiler version history from v0.6 to latest |
| π `tolk-vs-func` | `tolk://docs/tolk-vs-func` | FunC to Tolk migration guide β key differences and comparison |
| π `example-counter` | `tolk://examples/counter` | Simple counter smart contract example in Tolk |
| π `example-jetton` | `tolk://examples/jetton` | Jetton (fungible token) minter contract example in Tolk |
---
## π¬ 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.
| Argument | Type | Required | Description |
|----------|------|:--------:|-------------|
| `description` | `string` | β
| Description of what the smart contract should do |
| `contractType` | `string` | β | `"counter"` \| `"jetton"` \| `"nft"` \| `"wallet"` \| `"custom"` (default: `"custom"`) |
### `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.
| Argument | Type | Required | Description |
|----------|------|:--------:|-------------|
| `code` | `string` | β
| The Tolk smart contract source code to review |
### `debug_compilation_error`
Diagnose and fix a Tolk compilation error. Analyzes the error against the language reference and provides corrected code.
| Argument | Type | Required | Description |
|----------|------|:--------:|-------------|
| `errorMessage` | `string` | β
| The compilation error message from the Tolk compiler |
| `code` | `string` | β
| The Tolk source code that failed to compile |
---
## π‘ 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:"
> ```tolk
> 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
```bash
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