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.

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:

Live Health Monitoring — health check and runtime statistics:

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.

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:

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

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  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 →

92 tools total across 14 categories.

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 →

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 →

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.

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

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

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.

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.

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:

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

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

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

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.

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.

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.

Two usage modes:

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.

MCP client config (using devenv): Instead of hardcoding ./start-mcp.sh, 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"
    }
  }
}

Run ./create_configs.sh --client devenv to see full instructions for your current path.

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.

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

1. Clone or copy the repo: git clone https://github.com/Alba-Intelligence/cl-tron-mcp.git (or use an existing local path).
2. 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.

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

(ql:quickload :cl-tron-mcp)

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)'

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

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

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

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

1. Fork the repository
2. Create a feature branch
3. Follow guidelines in AGENTS.md
4. Add tests
5. Submit a pull request

• 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)

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).

Apache License 2.0. See LICENSE file.

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