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

These demos show the real MCP JSON-RPC protocol that AI agents send to Tron
— not internal function calls.

Protocol Discovery — tools, resources, and guided prompts:

Protocol discovery

Live Health Monitoring — health check and runtime statistics:

Health and runtime stats

In-Debugger Function Hot-Reload — compile a function while the debugger is
active, invoke CONTINUE to retry the failing call:

A unique capability of Common Lisp is the ability to modify running code without
unwinding the call stack.

In this example, we define a function f1 with 2 arguments that immediately
calls an undefined function f2 with the same 2 arguments. Calling (f1 1 2)
immediately throws the execution into the debugger. The MCP can then, while in
the debugger, inject a definition of f2 (a simple (defun f2 (x y) (+ x y)))
and restart the execution where it was interrupted.

The recording shows the sequence of calls and responses between the MCP and the
Common Lisp Swank server.

f1/f2 in-debugger fix

See demo/README.md for the setup phase (Swank launch + REPL connect).

Factorial: Debug, Fix, Verify — DIVISION-BY-ZERO, inspect restarts, hot-reload the fix:

Factorial debug

See demo/README.md for all 6 demo phases.

Architecture

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

Key: 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

92 tools total across 14 categories.

Quick Tool Examples

Debug an error (using MCP tool names):

repl_eval        code: "(my-buggy-function 7)"   ; triggers error
debugger_frames                                   ; see stack frames
repl_invoke_restart  restart_index: 5             ; abort to top level
repl_compile     code: "(defun my-buggy-function ...)"  ; hot-reload fix

Profile performance:

profile_start
repl_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

Recommended: Start Tron once as a long-running HTTP server, then configure
MCP clients to connect via streamable HTTP. This keeps Tron running across IDE
sessions without repeated startup.

./start-mcp.sh                    # Start long-running HTTP server (port 4006)
./start-mcp.sh --status           # Check if server is running
./start-mcp.sh --stop             # Stop the server

For MCP clients that require stdio (e.g., older configurations), use --stdio-only. This creates a short-lived process that exits when the client disconnects.

Mode	Command	Lifecycle	Use Case
combined	(default)	Long-running HTTP	Recommended for IDE sessions
stdio-only	`--stdio-only`	Exits when client disconnects	MCP client starts the server
http-only	`--http-only`	Long-running HTTP	Same as combined

Run ./start-mcp.sh --help for all options. See docs/starting-the-mcp.md for details.

1. Start a Swank Server

;; In SBCL
(ql:quickload :swank)
(swank:create-server :port 4006 :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. `~/cl-tron-mcp`).

The config examples below use tilde expansion (~) for the standard Quicklisp path. MCP clients support ~ but do not support $HOME or other environment variables. Adjust the path if your Quicklisp is in a different location.

Quick Setup: Use the config generator script to create all MCP client configurations with absolute paths:

# Interactive menu - select which clients to configure
./create_configs.sh

# Or generate all configs at once
./create_configs.sh --all

# Or generate a specific client config
./create_configs.sh --client cursor
./create_configs.sh --client kilocode
./create_configs.sh --client vscode
./create_configs.sh --client copilot
./create_configs.sh --client copilot-cli
./create_configs.sh --client opencode
./create_configs.sh --client claude

# Or use start-mcp.sh --config (same as create_configs.sh)
./start-mcp.sh --config

The script generates configuration files with absolute paths (no ~ or $HOME), which is required for JSON config files.

Kilocode

Config file: .kilocode/mcp.json (project) or global MCP settings. The repo provides both Tron variants under different server names so you can choose one:

Server name	Transport	Choose this if…
cl-tron-mcp-stdio	STDIO	You want Kilocode to start Tron (default)
cl-tron-mcp-http	Streamable HTTP	You run `./start-mcp.sh --http` yourself

Enable the one you want (disabled: false); leave the other disabled or remove it. See examples/kilocode-mcp.json.example for a template with both entries.

STDIO (cl-tron-mcp-stdio, recommended):

{
  "mcpServers": {
    "cl-tron-mcp": {
      "command": "~/quicklisp/local-projects/cl-tron-mcp/start-mcp.sh",
      "args": ["--stdio-only"],
      "disabled": false
    }
  }
}

Streamable HTTP (cl-tron-mcp-http): Start Tron with ./start-mcp.sh (combined) or ./start-mcp.sh --http-only [--port 4006], then set "type": "streamable-http" and "url": "http://127.0.0.1:4006/mcp".

OpenCode

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

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cl-tron-mcp": {
      "type": "local",
      "command": "~/quicklisp/local-projects/cl-tron-mcp/start-mcp.sh",
      "enabled": true
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "cl-tron-mcp": {
      "command": "~/quicklisp/local-projects/cl-tron-mcp/start-mcp.sh",
      "args": ["--stdio-only"],
      "disabled": false,
      "env": {}
    }
  }
}

GitHub Copilot (VS Code)

GitHub Copilot uses VS Code's built-in MCP support (VS Code 1.99+). Add Tron to your workspace config at .vscode/mcp.json:

{
    "servers": {
        "cl-tron-mcp": {
            "type": "stdio",
            "command": "bash",
            "args": ["-c", "cd ~/quicklisp/local-projects/cl-tron-mcp && ./start-mcp.sh --stdio-only"]
        }
    }
}

Or add to your user settings (settings.json):

{
    "mcp": {
        "servers": {
            "cl-tron-mcp": {
                "type": "stdio",
                "command": "bash",
                "args": ["-c", "cd ~/quicklisp/local-projects/cl-tron-mcp && ./start-mcp.sh --stdio-only"]
            }
        }
    }
}

The repo's .vscode/mcp.json is pre-configured for this workspace. Run ./create_configs.sh --client copilot to generate a user-level config.

GitHub Copilot CLI

The Copilot CLI uses ~/.copilot/mcp-config.json with mcpServers at the top level and "type": "local":

{
    "mcpServers": {
        "cl-tron-mcp": {
            "type": "local",
            "command": "bash",
            "args": ["-c", "cd ~/quicklisp/local-projects/cl-tron-mcp && ./start-mcp.sh --stdio-only"],
            "env": {},
            "tools": ["*"]
        }
    }
}

Run ./create_configs.sh --client copilot-cli to generate this file, or use /mcp add inside the CLI.

From Outside the devenv Environment (run-mcp.sh)

If you are not inside the devenv shell but want to use devenv-managed dependencies, use the bundled run-mcp.sh script. It auto-detects your host Quicklisp installation, enters the devenv environment, and starts the MCP:

./run-mcp.sh --stdio-only   # For MCP clients
./run-mcp.sh                # Long-running HTTP server (default)

This is the simplest way to run Tron from an coding assistant or IDE that spawns a shell outside the Nix environment. The script handles:

Finding Quicklisp on the host ($HOME/quicklisp or QUICKLISP_DIR)
Entering the devenv shell with the correct environment
Forwarding all arguments to start-mcp.sh

See docs/starting-the-mcp.md#quick-start-outside-devenv for details.

Claude Desktop

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

{
    "mcpServers": {
        "cl-tron-mcp": {
            "command": "bash",
            "args": ["-c", "cd ~/quicklisp/local-projects/cl-tron-mcp && ./start-mcp.sh --stdio-only"]
        }
    }
}

Run ./create_configs.sh --client claude to generate this file.

devenv (NixOS / Nix users)

If you manage your development environment with devenv, Tron integrates natively via devenv.nix. After cloning the repo, the devenv environment already includes SBCL and all required packages.

Quick start — recommended: Use the bundled run-mcp.sh script. It auto-detects your host Quicklisp, enters the devenv environment, and starts the MCP:

# Long-running HTTP server (combined mode)
./run-mcp.sh

# Stdio for MCP clients
./run-mcp.sh --stdio-only

# HTTP only
./run-mcp.sh --http-only

# Force SBCL
./run-mcp.sh --use-sbcl

Inside the devenv shell manually:

Mode	Command	Best for
HTTP server (persistent)	`devenv up`	Development — keeps Tron running on port 4006
Stdio (on-demand)	`devenv shell -- tron-mcp`	MCP clients that spawn the server per session

Fast startup: When you enter the devenv shell (devenv shell), the tron-mcp:precompile task automatically compiles Lisp sources to cached .fasl files. Subsequent MCP startups take ~2 seconds instead of ~8 seconds. If Quicklisp is not available in the sandbox, the task skips with a diagnostic rather than blocking shell entry.

MCP client config (using run-mcp.sh):

{
  "mcpServers": {
    "cl-tron-mcp": {
      "command": "/path/to/cl-tron-mcp/run-mcp.sh",
      "args": ["--stdio-only"],
      "disabled": false
    }
  }
}

MCP client config (using devenv directly): Point your client at devenv shell -- tron-mcp. This ensures SBCL and all env vars come from devenv, even from outside the shell:

{
  "mcpServers": {
    "cl-tron-mcp": {
      "command": "devenv",
      "args": ["shell", "--", "tron-mcp"],
      "cwd": "/path/to/cl-tron-mcp"
    }
  }
}

Note: devenv mcp is devenv's own built-in MCP server (for querying Nix packages/options). It is unrelated to Tron and cannot be used to run Tron.

Other clients (Claude 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: ["~/quicklisp/local-projects/cl-tron-mcp/start-mcp.sh", "--stdio-only"]
- Alternative (SBCL only): ["sbcl", "--non-interactive", "--noinform", "--eval", "(ql:quickload :cl-tron-mcp :silent t)", "--eval", "(cl-tron-mcp/core:start-server :transport :stdio-only)"]

Ensure SBCL (or ECL) and Quicklisp are on the PATH when the client starts the server. To force ECL, use ["~/quicklisp/local-projects/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 4006 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
├── scripts/                # run-http.sh, tutorial-run.lisp, debug-mcp-stdio.sh
├── examples/               # MCP config examples, mcp-kilocode.json, example Python clients
├── docs/                   # Documentation
│   ├── architecture.md     # How it works
│   ├── DEVELOPERS.md       # Developer guide (where to add features)
│   ├── swank-integration.md
│   └── tools/              # Tool docs
├── prompts/                # Workflow guides
├── demo/                   # Demo scripts, asciinema recordings (.cast), and GIFs (see [demo/README.md](demo/README.md))
└── 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/protocol-handlers.md	JSON-RPC protocol handler documentation
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

See CONTRIBUTING.md for setup, tests, and PR process, and docs/DEVELOPERS.md for where to add features and how the codebase is organized.

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)

Server Management

For HTTP and combined modes, start-mcp.sh includes server detection and session management:

./start-mcp.sh --status   # Check if server is running (shows PID, port, uptime)
./start-mcp.sh --stop     # Stop a running server gracefully
./start-mcp.sh --restart  # Stop existing and start new instance

The PID file (.tron-server.pid) contains JSON metadata: {"pid": 12345, "port": 4006, "transport": "combined", "started": 1709000000}. The script automatically detects if a server is already running (via PID file and health endpoint) and exits successfully without starting a duplicate instance.

Use --restart when you want to stop an old instance and start a fresh one (e.g., after updating code).

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