Tolk MCP Server

A Model Context Protocol (MCP) server for the Tolk compiler, enabling Large Language Models (LLMs) to compile and verify Tolk smart contract code for the TON blockchain.

中文文档 | English Documentation

Overview

This MCP server exposes the Tolk compiler functionality to AI assistants, allowing them to:

• ✅ Compile Tolk source code in real-time

• ✅ Verify code correctness before deployment

• ✅ Get compiled bytecode (BOC) and code hash

• ✅ Debug compilation errors with detailed messages

• ✅ Support multi-file projects

Related MCP server: iz-tolk-mcp

Supported Platforms

Quick Start

Installation

# Install globally
npm install -g tolk-mcp-server

# Or install as project dependency
npm install tolk-mcp-server

# Or run directly with npx
npx tolk-mcp-server

For Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tolk-compiler": {
      "command": "npx",
      "args": ["tolk-mcp-server"]
    }
  }
}

For ChatGPT

1. Start the HTTP server:

npx tolk-mcp-server-http

2. Expose via ngrok (for testing):

ngrok http 3000

3. Add in ChatGPT: Settings → Connectors → Advanced → Developer Mode → Add your URL

Available Tools

getTolkCompilerVersion

Returns the current Tolk compiler version.

Example: "0.7.0"

runTolkCompiler

Compiles Tolk source code and returns the result.

Parameters:

Success Response:

{
  "status": "ok",
  "fiftCode": "...",
  "codeBoc64": "...",
  "codeHashHex": "...",
  "stderr": ""
}

Error Response:

{
  "status": "error",
  "message": "Error description"
}

Usage Examples

Ask Claude or ChatGPT:

Compile this Tolk contract:

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

The AI will use the Tolk compiler to verify and compile your code.

Development

Build from Source

# Clone repository
git clone https://github.com/robustfengbin/tolk-mcp-server.git
cd tolk-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Available Scripts

Project Structure

tolk-mcp-server/
├── src/
│   ├── index.ts           # stdio transport server
│   └── server-http.ts     # HTTP/SSE transport server
├── test/
│   └── test.ts            # Test suite
├── docs/
│   ├── USAGE.md           # English documentation
│   └── USAGE_CN.md        # Chinese documentation
├── Dockerfile             # Docker deployment
├── package.json
└── README.md

Deployment

Docker

# Build image
docker build -t tolk-mcp-server .

# Run container
docker run -p 3000:3000 tolk-mcp-server

Environment Variables

API Endpoints (HTTP Server)

Requirements

• Node.js >= 18.0.0

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

References

• Tolk Language Documentation

• tolk-js Library

• Model Context Protocol

• ChatGPT MCP Support

• TON Society Grants & Bounties #1200

Acknowledgments

This project was created as part of the TON Society Grants & Bounties program.