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

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:

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:

{
  "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

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.