tolk-mcp-server

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

Supported Platforms

| Platform | Transport | Status | |----------|-----------|--------| | Claude Desktop | stdio | ✅ Supported | | ChatGPT | HTTP/SSE | ✅ Supported | | Other MCP Clients | Both | ✅ Supported |

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

1. Expose via ngrok (for testing):

ngrok http 3000

1. 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:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | entrypointFileName | string | Yes | Main .tolk file name | | sources | Record<string, string> | Yes | Map of filename to source code | | optimizationLevel | number (0-2) | No | Optimization level (default: 2) | | withStackComments | boolean | No | Include stack comments in Fift output | | experimentalOptions | string | No | Experimental compiler flags |

Success Response: ``json { "status": "ok", "fiftCode": "...", "codeBoc64": "...", "codeHashHex": "...", "stderr": "" } ``

Error Response: ``json { "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

| Script | Description | |--------|-------------| | npm start | Run stdio server (for Claude Desktop) | | npm run start:http | Run HTTP server (for ChatGPT) | | npm run build | Build TypeScript | | npm test | Run tests | | npm run dev | Build and run stdio server | | npm run dev:http | Build and run HTTP server |

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

| Variable | Default | Description | |----------|---------|-------------| | MCP_PORT | 3000 | HTTP server port | | MCP_HOST | 0.0.0.0 | HTTP server host |

API Endpoints (HTTP Server)

| Endpoint | Method | Description | |----------|--------|-------------| | /mcp | POST | MCP JSON-RPC endpoint | | /mcp | GET | SSE stream for notifications | | /mcp | DELETE | Session termination | | /health | GET | Health check | | / | GET | Server info |

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.