dsmr-mcp is an Model Context Protocol (MCP)
server that lets an AI agent work inside your live Common Lisp image. It
connects an MCP client to a running Lisp over Slynk, so an agent can evaluate
code, inspect live objects and threads, edit source structurally, run tests,
navigate a codebase, and look up documentation — in the same image you are
developing in.
Prerequisites: SBCL, Quicklisp, and the source on your ASDF source path (e.g.
under ~/SourceCode/lisp/).
# 1. Load and smoke-test the server (stdio transport, the default)
sbcl --non-interactive \
--eval '(ql:quickload :dsmr-mcp)' \
--eval '(dsmr-mcp:run)'To attach to a Lisp image you are already running, start a Slynk listener in that image and point dsmr-mcp at it:
DSMR_MODE=attached DSMR_SLYNK_ATTACH=127.0.0.1:4005 \
sbcl --non-interactive \
--eval '(ql:quickload :dsmr-mcp)' \
--eval '(dsmr-mcp:run)'No image to attach to? Use DSMR_MODE=hermetic (a forked, crash-isolated SBCL
worker pool) or DSMR_MODE=auto (attach if a listener is reachable, else
hermetic). Then wire it into your MCP client (Claude Code and others) — see
Configuration for the client setup and the full
environment-variable reference.
Driving more than one Lisp project from a single agent install? dsmr-mcp
ships a per-project direnv .envrc so each project can
point at its own image and port while the global MCP entry stays env-free —
see direnv per-project setup.
Verify with a trivial repl-eval round trip: evaluating (+ 1 2) should
return 3.
Lisp development is image-based: a developer builds up a running world of definitions, packages, threads, CLOS instances, and application state over a session. Conventional AI coding tools ignore that — they operate on files and a freshly spawned process, discarding the live context that makes Lisp productive.
dsmr-mcp takes the opposite stance, the attached-image-first thesis: the
agent should work in the same running world the developer already inhabits, where
a redefined function takes effect immediately, a live CLOS instance can be
inspected, and a restart can be invoked. It is the Common Lisp analogue of a
language server for an AI — a structured set of verbs over a live image.
The name is a backronym, expanding (at your convenience) To: DeepSky Systems Model-context-Reagent for Common Lisp.
The intended use is a developer pair-programming with an AI agent in their own running Lisp. The developer starts their project image with a Slynk listener; dsmr-mcp attaches to it; the agent then has the same live, image-resident tools the developer has at the REPL. It is explicitly a single-operator, localhost developer tool — not a multi-tenant or hosted service.
Who uses it:
- A Common Lisp developer who wants an AI agent to work in their live image.
- An AI agent (Claude and others) acting as that developer’s pair, via an MCP client.
The operator is the trust root: they already trust the agent to evaluate code in
their image. See the threat model for the full
posture — in short, dsmr-mcp is a trust-amplifier for an agent the operator
already trusts, not a containment layer against a hostile one.
- 31 verbs across REPL evaluation and build (
repl-eval,load-system,run-tests), filesystem access (fs-*), structural Lisp editing (lisp-*), code intelligence (code-find,code-describe,clgrep-search,clhs-lookup, …), live-image inspection (inspect-*), an LSP bridge (lsp-*), hermetic operations (pool-status,pool-kill-worker), project scaffolding (project-scaffold), and an agent coordination bus (bus-publish,bus-receive,bus-status). - A single-host coordination bus so several agents — one per Lisp project, plus subagents — can pass messages to each other through a durable, broker-mediated log, with per-agent cursors that resume across restarts. See Agent coordination bus.
- Three transports: stdio (default), TCP, and Streamable HTTP (with a bundled bridge). Loopback-only by default.
- Three execution modes: attached, hermetic, and auto.
- A filesystem sandbox as the one enforced agent-facing control, structured logging, a reviewable threat model, and an operations runbook.
The full manual lives in =docs/=:
- Introduction — overview and the attached-image-first thesis.
- Installation & Build — prerequisites, loading, running, testing.
- Configuration — environment variables, modes, transports, MCP-client wiring.
- Architecture — how a request flows from client to image.
- Modes & Transports — when to use each mode and transport.
- Agent coordination bus — how sibling agents and subagents coordinate on one host.
- Tool reference — every verb, generated from the live registry.
- Operations & Runbook — health checks and field recipes.
- Threat model — trust boundaries and the STRIDE register.
- Release notes.
v0.1.0 — first tagged release. See the release notes.
AGPL-3.0-or-later
© Brian O’Reilly / DeepSky Systems