# Tolk MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)

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.

[中文文档](./docs/USAGE_CN.md) | [English Documentation](./docs/USAGE.md)

## 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

```bash
# 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`

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

### For ChatGPT

1. Start the HTTP server:
```bash
npx tolk-mcp-server-http
```

2. Expose via ngrok (for testing):
```bash
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:**
```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

```bash
# 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

```bash
# 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](CONTRIBUTING.md) 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](LICENSE) file for details.

## References

- [Tolk Language Documentation](https://docs.ton.org/develop/tolk)
- [tolk-js Library](https://github.com/ton-blockchain/tolk-js)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [ChatGPT MCP Support](https://platform.openai.com/docs/mcp)
- [TON Society Grants & Bounties #1200](https://github.com/ton-society/grants-and-bounties/issues/1200)

## Acknowledgments

This project was created as part of the [TON Society Grants & Bounties](https://github.com/ton-society/grants-and-bounties) program.