CL-TRON-MCP

AI-Powered Debugging for Common Lisp

A Model Context Protocol (MCP) server that gives AI assistants deep access to running SBCL Common Lisp applications—debugger, inspector, profiler, and hot code reload.

How It Works

See It In Action

Basic Debugging Demo:

Basic Demo

The AI connects to your running Lisp, triggers an error, inspects the backtrace, hot-reloads a fix, and verifies it works—all without restarting.

Kilocode CLI Demo:

Kilocode Demo

Shows what you'd see when using Kilocode with Tron MCP: the terminal interface, commands, and output.

Raw MCP Protocol:

MCP Protocol

Shows the actual JSON-RPC messages that AI clients send to Tron internally. This is what Kilocode, Cursor, and Claude Code do under the hood.

Architecture

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  SBCL + Swank   │◄───────►│   Tron (MCP)    │◄───────►│   AI Client     │
│  (Port 4005)    │         │   (stdio)       │         │ (Kilocode, etc) │
│                 │         │                 │         │                 │
│  Your code      │         │  86 tools:      │         │  Sends prompts  │
│  Debugger       │         │   - swank_eval  │         │  Receives       │
│  Threads        │         │   - inspect     │         │  results        │
│  State lives    │         │   - profile     │         │                 │
└─────────────────┘         └─────────────────┘         └─────────────────┘
        ▲
        │
        └──────────────────────────────────────────────────────┘
                      Same session, no restart

Key insight: All state lives in the SBCL process. Tron connects as a client. The session persists across debugging, hot-reloads, and errors.

📖 Full architecture documentation →

Features

| Category | Description | Documentation | |----------|-------------|---------------| | Debugger | Backtrace, restarts, stepping, breakpoints | docs/tools/debugger.md | | Inspector | Objects, slots, classes, functions, packages | docs/tools/inspector.md | | Hot Reload | Compile strings, reload systems | docs/tools/hot-reload.md | | Profiler | Start/stop profiling, generate reports | docs/tools/profiler.md | | Threads | List, inspect, get backtraces | docs/tools/threads.md | | Monitor | Health checks, runtime stats, GC | docs/tools/monitor.md | | Swank | Slime/Portacle integration (21 tools) | docs/swank-integration.md |

86 tools total across 14 categories.

Quick Tool Examples

Debug an error:

(swank-eval :code "(my-buggy-function 7)")  ; triggers error
(swank-backtrace)                            ; see stack frames
(swank-invoke-restart :restart_index 2)      ; abort
(swank-eval :code "(defun my-buggy-function ...)")  ; hot-reload fix

Profile performance:

(profile-start)
(swank-eval :code "(process-data)")
(profile-stop)
(profile-report :format "flat")

Find callers:

(who-calls :symbol_name "my-package:process")

📖 More workflow examples →

Discoverable by AI Agents

The MCP is fully discoverable: an AI agent can learn how to use it without any user explanation.

Short path: The agent calls prompts/get with name discover-mcp. That returns the exact steps: resources/list → resources/read AGENTS.md → prompts/list → prompts/get getting-started → tools/list. After that, the agent has everything needed to connect, evaluate, debug, inspect, profile, and hot-reload.
Read path: The agent calls resources/list, then resources/read with uri AGENTS.md. That document (and the other listed resources) explains the one long-running Lisp session, connection, tools, workflows, and conventions.

No manual “how to use Tron” instructions are required. Standard MCP methods (resources/list, resources/read, prompts/list, prompts/get, tools/list) are enough.

📖 MCP resources and prompts →

Quick Start

1. Start a Swank Server

;; In SBCL
(ql:quickload :swank)
(swank:create-server :port 4005 :dont-close t)

2. Configure Your AI Client

You can run the MCP from a local copy or from a clone of the GitHub repo. In both cases the client runs a command that starts start-mcp.sh (or equivalent) inside the project directory.

Getting the server

| Option | What to do | |--------|------------| | Local copy | You already have the repo on disk (e.g. in ~/quicklisp/local-projects/cl-tron-mcp). Use that path in the config below. | | From GitHub | Clone the repo, then use the path to the cloned directory: git clone https://github.com/Alba-Intelligence/cl-tron-mcp.git and cd cl-tron-mcp. In config, set the path to where you cloned it (e.g. $HOME/cl-tron-mcp or ~/cl-tron-mcp). |

Replace /path/to/cl-tron-mcp in the examples below with your actual path (e.g. ~/cl-tron-mcp or $HOME/quicklisp/local-projects/cl-tron-mcp). Copy the example for your client from examples/ if you prefer. See docs/starting-the-mcp.md if the MCP won't start.

Kilocode

Config file: ~/.kilocode/cli/config.json (or your Kilocode MCP config location).

{
  "mcpServers": {
    "cl-tron-mcp": {
      "command": ["/path/to/cl-tron-mcp/start-mcp.sh"],
      "disabled": false,
      "env": {},
      "alwaysAllow": []
    }
  }
}

Or run from the project directory:

"command": ["bash", "-c", "cd /path/to/cl-tron-mcp && ./start-mcp.sh"]

OpenCode

Config file: ~/.config/opencode/opencode.json.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cl-tron-mcp": {
      "type": "local",
      "command": ["bash", "-c", "cd /path/to/cl-tron-mcp && ./start-mcp.sh"],
      "enabled": true
    }
  }
}

Cursor

Config file: ~/.cursor/mcp.json (or Cursor MCP settings).

{
  "mcpServers": {
    "cl-tron-mcp": {
      "command": ["bash", "-c", "cd /path/to/cl-tron-mcp && ./start-mcp.sh"],
      "disabled": false,
      "env": {}
    }
  }
}

Other clients (Claude Code, VS Code, etc.)

Any MCP client that runs a local command can use Tron the same way:

Clone or copy the repo: git clone https://github.com/Alba-Intelligence/cl-tron-mcp.git (or use an existing local path).
In the client’s MCP config, add a server entry whose command runs the MCP over stdio, for example:
- Preferred: ["/path/to/cl-tron-mcp/start-mcp.sh"] or ["bash", "-c", "cd /path/to/cl-tron-mcp && ./start-mcp.sh"]
- Alternative (SBCL only): ["sbcl", "--non-interactive", "--noinform", "--eval", "(ql:quickload :cl-tron-mcp :silent t)", "--eval", "(cl-tron-mcp/core:start-server :transport :stdio)"]

Ensure SBCL (or ECL) and Quicklisp are on the PATH when the client starts the server. To force ECL, use ["/path/to/cl-tron-mcp/start-mcp.sh", "--use-ecl"].

Example config files: examples/cursor-mcp.json.example, examples/kilocode-mcp.json.example, examples/opencode-mcp.json.example.

3. Start Debugging

Ask your AI: "Connect to Swank on port 4005 and debug factorial-example.lisp"

Installation

Quicklisp

(ql:quickload :cl-tron-mcp)

From Source

git clone https://github.com/Alba-Intelligence/cl-tron-mcp.git
cd cl-tron-mcp
sbcl --eval '(load "cl-tron-mcp.asd")' --eval '(ql:quickload :cl-tron-mcp)'

Development

Running Tests

(asdf:test-system :cl-tron-mcp)

;; Or with Rove
(ql:quickload :rove)
(rove:run :cl-tron-mcp/tests)

Project Structure

cl-tron-mcp/
├── src/                    # Source code
│   ├── core/               # Core infrastructure
│   ├── swank/              # Swank client
│   ├── tools/              # Tool definitions
│   └── ...
├── tests/                  # Rove test suites
├── docs/                   # Documentation
│   ├── architecture.md     # How it works
│   ├── swank-integration.md
│   └── tools/              # Tool docs
├── prompts/                # Workflow guides
├── demo/                   # Demo generation
└── AGENTS.md              # AI agent guidelines

Documentation

| Document | Purpose | |----------|---------| | AGENTS.md | Quick start for AI agents using Tron | | docs/architecture.md | System architecture and design | | docs/swank-integration.md | Swank protocol details | | docs/mcp-resources-prompts.md | MCP discoverability features | | docs/starting-the-mcp.md | Starting the MCP and troubleshooting | | docs/demo-creation.md | How to create demo GIFs | | tutorial/e2e-mcp-workflow.md | End-to-end workflow (connect, eval, error, restart, hot-fix) | | prompts/workflow-examples.md | Step-by-step usage examples | | prompts/debugging-workflows.md | Debugging patterns |

Contributing

Fork the repository
Create a feature branch
Follow guidelines in AGENTS.md
Add tests
Submit a pull request

Requirements

SBCL 2.0.0 or later, or ECL (Embeddable Common Lisp). The MCP server runs with either. start-mcp.sh selects the Lisp by: --use-sbcl / --use-ecl (CLI) or auto-detect (sbcl, then ecl). Run ./start-mcp.sh --help for full usage.
Quicklisp
Swank (for Slime/Portacle/Sly)

Troubleshooting

| Problem | Solution | |---------|----------| | "Package not found" | (ql:quickload :cl-tron-mcp) first | | Client shows "failed" | Use start-mcp.sh which handles stdio correctly | | "Not connected to REPL" | Run swank_connect or repl_connect first | | Tests fail with stale FASL | (asdf:compile-system :cl-tron-mcp :force t) |

License

Apache License 2.0. See LICENSE file.

Resources

Repository: https://github.com/Alba-Intelligence/cl-tron-mcp
SBCL Documentation
Model Context Protocol
Swank/Slime

MCP Servers

CL-TRON-MCP

How It Works

See It In Action

Architecture

Features

Quick Tool Examples

Discoverable by AI Agents

Quick Start

1. Start a Swank Server

2. Configure Your AI Client

Getting the server

Kilocode

OpenCode

Cursor

Other clients (Claude Code, VS Code, etc.)

3. Start Debugging

Installation

Quicklisp

From Source

Development

Running Tests

Project Structure

Documentation

Contributing

Requirements

Troubleshooting

License

Resources

安装命令（包未发布）

Cursor 配置 (mcp.json)

CL-TRON-MCP

How It Works

See It In Action

Architecture

Features

Quick Tool Examples

Discoverable by AI Agents

Quick Start

1. Start a Swank Server

2. Configure Your AI Client

Getting the server

Kilocode

OpenCode

Cursor

Other clients (Claude Code, VS Code, etc.)

3. Start Debugging

Installation

Quicklisp

From Source

Development

Running Tests

Project Structure

Documentation

Contributing

Requirements

Troubleshooting

License

Resources

安装命令 （包未发布）

Cursor 配置 (mcp.json)

安装命令（包未发布）