iz-tolk-mcp
by izzzzzi
README.md
<div align="center">
# 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**
<br />
*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.*
</div>
---
## π 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
<details>
<summary><b>Claude Desktop</b></summary>
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"tolk": {
"command": "npx",
"args": ["-y", "iz-tolk-mcp"]
}
}
}
```
</details>
<details>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add tolk -- npx -y iz-tolk-mcp
```
</details>
<details>
<summary><b>Cursor</b></summary>
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"tolk": {
"command": "npx",
"args": ["-y", "iz-tolk-mcp"]
}
}
}
```
</details>
<details>
<summary><b>Windsurf</b></summary>
Add to `~/.windsurf/mcp.json`:
```json
{
"mcpServers": {
"tolk": {
"command": "npx",
"args": ["-y", "iz-tolk-mcp"]
}
}
}
```
</details>
<details>
<summary><b>VS Code (Copilot)</b></summary>
Add to `.vscode/mcp.json`:
```json
{
"servers": {
"tolk": {
"command": "npx",
"args": ["-y", "iz-tolk-mcp"]
}
}
}
```
</details>
<details>
<summary><b>Local build (any client)</b></summary>
```json
{
"mcpServers": {
"tolk": {
"command": "node",
"args": ["/absolute/path/to/izTolkMcp/dist/cli.js"]
}
}
}
```
</details>
---
## π οΈ 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
TDQS
A4.2/5.0
Scored across 4 tools
Disambiguation5/5
Each tool has a clearly distinct purpose: syntax checking, compilation, deploy link generation, and version retrieval. There is no overlap or ambiguity.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern in snake_case (e.g., check_tolk_syntax, get_compiler_version), making them predictable and easy to understand.
Tool Count5/5
With 4 tools, the server is well-scoped for Tolk smart contract development, covering essential operations without unnecessary bloat.
Completeness4/5
The tool set covers the main workflow: syntax check, compilation, and deploy link generation. However, it lacks tools for tasks like directly fetching contract addresses or deploying contracts, which are minor gaps.
Maintenance
ActivityInactive
ResponsivenessNo recent community issues