Skip to content
Back to search

cl-mcp

A Model Context Protocol (MCP) server for Common Lisp, providing JSON-RPC 2.0 over stdio, TCP, and HTTP (Streamable HTTP). It enables AI agents to interact with Common Lisp environments through…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cl-ai-project--cl-mcp/badge.svg)](/listings/cl-ai-project--cl-mcp)

HTML

<a href="/listings/cl-ai-project--cl-mcp"><img src="/api/listings/cl-ai-project--cl-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install

# Install from Roswell
ros install cl-ai-project/cl-mcp

# or fetch from GitHub
cd ~/common-lisp
git clone https://github.com/cl-ai-project/cl-mcp.git

Load and run from an existing REPL:

(asdf:load-system :cl-mcp)  ; or (ql:quickload :cl-mcp) if using Quicklisp

;; Start the HTTP server on port 3000 (the default)
(cl-mcp:start-http-server :port 3000)

;; Or start the TCP transport on port 12345, accepting clients until stopped
(cl-mcp:ensure-tcp-server-thread :port 12345)

Or run a minimal stdio loop (one JSON-RPC line per request):

# With Roswell
ros run -s cl-mcp -e "(cl-mcp:run :transport :stdio)"

# With a plain sbcl command
sbcl --eval '(require :asdf)' \
     --eval '(asdf:load-system :cl-mcp)' \
     --eval '(cl-mcp:run :transport :stdio)'

**Project root**: File operations require a project root to be set. The root belongs to the session that sets it, with `fs-set-project-root` or with `initialize`'s `rootPath`/`rootUri`: several agents can share one server and work on different projects, and none of them moves another's root. `MCP_PROJECT_ROOT`, when set, is the default for a session that sets none. If it is not set, a session's first file access returns an error prompting it to call `fs-set-project-root`; AI agents handle this by setting it to their working directory. A session's own root lasts as long as the session, so a reconnect -- a new HTTP session or TCP connection -- starts from `MCP_PROJECT_ROOT` when it is set, and otherwise without a root, and has to set its own again.

System Prompts

The `prompts/` directory contains system prompts that teach AI agents how to use cl-mcp tools effectively:

- **`repl-driven-development.md`** — Tool selection guide, REPL-driven workflow (explore → experiment → persist → verify), editing patterns, and troubleshooting recipes - **`common-lisp-expert.md`** — Production-quality Common Lisp coding standards, CLOS/conditions/restarts conventions, and TDD with Rove - **`cl-spec-driven-development.md`** — Contract-driven workflow for the optional `cl-spec` tool group: finding and writing Function Specs and Properties, baselines, seed replay, and reading `spec-check` verdicts. Supplements the two prompts above rather than replacing them

cl-mcp also sends a short summary of the first, and of the third when the `cl-spec` group is enabled, as its MCP server instructions (see [Server instructions](docs/tools.md#server-instructions)), so a client that honours them gets the essentials without any setup. Reference the full prompts from your project's `CLAUDE.md` (or equivalent) when you want the complete guide, or when your client ignores server instructions:

# CLAUDE.md
@prompts/repl-driven-development.md
@prompts/common-lisp-expert.md

If you enable the `cl-spec` tool group (see [Optional tool groups](docs/tools.md#optional-tool-groups)), add the third prompt as well. Leave it out otherwise: without the group, the tools it describes are not in the agent's tool list.

@prompts/cl-spec-driven-development.md

Claude Code

HTTP transport (recommended)

Start the HTTP server from your REPL and keep using it alongside Claude Code:

(asdf:load-system :cl-mcp)  ; or (ql:quickload :cl-mcp)

;; Start HTTP server on port 3000 (default)
(cl-mcp:start-http-server :port 3000)

;; Server is now running at http://127.0.0.1:3000/mcp
;; You can continue using your REPL normally
(+ 1 2)  ; => 3

;; Stop the server when done
(cl-mcp:stop-http-server)

Register it with Claude Code:

claude mcp add --transport http cl-mcp http://127.0.0.1:3000/mcp

or write the entry yourself, in the project's `.mcp.json` (or `~/.claude.json` for all projects):

{
  "mcpServers": {
    "cl-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

`start-http-server` also takes `:token :generate` (or a token string) to require an

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 448 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # cl-mcp
  2. [![CI](https://github.com/cl-ai-project/cl-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cl-ai-project/cl-mcp/actions/workflows/ci.yml)
  3. [![Lint](https://github.com/cl-ai-project/cl-mcp/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/cl-ai-project/cl-mcp/actions/workflows/lint.yml)
  4. A Model Context Protocol (MCP) server for Common Lisp, providing JSON-RPC 2.0
  5. over stdio, TCP, and HTTP (Streamable HTTP). It enables AI agents to interact
  6. with Common Lisp environments through structured tools for REPL evaluation,
  7. system loading, file operations, code introspection, and structure-aware editing.
  8. ## Features
  9. - **REPL evaluation with object inspection** — evaluate forms, drill down into complex results (CLOS instances, hash-tables, etc.), and capture structured error context with stack frames and local variables
  10. - **Sandboxed file operations** — read/write/list files restricted to the project root and ASDF system source directories, preventing accidental access outside the project
  11. - **Structure-aware Lisp editing** — replace, insert, and patch top-level forms using Eclector CST parsing with automatic parinfer repair, preserving formatting and comments
  12. - **Code intelligence** — symbol lookup and description; callers with their exact call sites and the tests that exercise them; CLOS class hierarchies, slots and generic-function methods; macroexpansion of a form straight from its file; Lisp-aware search and file viewing with collapsed signatures; CLHS lookup
  13. - **Structured test runner** — run Rove, FiveAM and prove tests with pass/fail counts, failure details, and source locations
  14. - **Worker pool isolation** — eval-dependent tools run in isolated child SBCL processes with automatic crash recovery, circuit breaker, and per-session affinity; an optional init hook can start your app inside the worker
  15. - **Three transports** — stdio, TCP (multi-client), and Streamable HTTP (for Claude Code)
  16. - **Project scaffolding** — generate a throwaway package-inferred project with Rove or FiveAM tests
  17. - **Optional contract checking** — the `cl-spec` tool group (off by default) lists, reads and checks [cl-spec](https://github.com/masatoi/cl-spec) contracts; see [Optional tool groups](docs/tools.md#optional-tool-groups)
  18. ### Tools at a glance
  19. | Category | Tool | Purpose | Runs in |
  20. |---|---|---|---|
  21. | Project & files | `fs-set-project-root` | Set this session's project root | parent (the worker follows) |
  22. | | `fs-get-project-info` | Show the root and working directory | parent |
  23. | | `fs-read-file` / `fs-write-file` / `fs-list-directory` | Text I/O inside the allowed roots | parent |
  24. | | `project-scaffold` | Generate a new project skeleton | parent |
  25. | Lisp source | `lisp-read-file` | Collapsed or pattern-expanded view of a file | parent |
  26. | | `lisp-edit-form` / `lisp-patch-form` | Replace, insert or delete a top-level form; scoped text patch | parent |
  27. | | `lisp-check-parens` | Diagnose unbalanced delimiters and suggest the fix | parent |
  28. | | `clgrep-search` | Lisp-aware grep that reports the enclosing form; no loading needed | parent |
  29. | | `lisp-macroexpand` | Expand a macro call from a file or a code string | parent locates, worker expands |
  30. | REPL | `repl-eval` | Evaluate forms, with backtraces and locals on error | worker |
  31. | | `inspect-object` | Drill into a result object | worker |
  32. | | `load-system` | Load or reload an ASDF system | worker |
  33. | | `run-tests` | Run Rove/FiveAM/prove tests with structured results | worker |
  34. | Introspection | `code-find` / `code-describe` | Definition location; signature and documentation | worker |
  35. | | `code-find-references` | Callers, call sites and affected tests | worker (xref) + parent (source scan) |
  36. | | `clos-describe` | Classes, slots and generic-function methods | worker, verified against source by the parent |
  37. | Reference | `clhs-lookup` | Common Lisp HyperSpec | parent |
  38. | Pool | `pool-status` / `pool-kill-worker` | Diagnose or replace the session's worker | parent |
  39. | `cl-spec` (opt-in) | `spec-list` / `spec-symbol` / `spec-describe` / `spec-check` | List, read and check contracts | worker |
  40. For every tool's input/output schema, see [docs/tools.md](docs/tools.md).
  41. ## Requirements
  42. - SBCL 2.x (developed with SBCL 2.5.x)
  43. - Quicklisp (optional; pure ASDF also works)
  44. - Dependencies (via ASDF/Quicklisp): runtime — `alexandria`, `cl-ppcre`, `yason`, `usocket`, `bordeaux-threads`, `eclector`, `hunchentoot`, `named-readtables`; tests — `rove`; optional — `fiveam` (for running FiveAM suites), `clhs` (loaded on-demand by `clhs-lookup` tool), `swank` (only for `MCP_WORKER_SWANK`), `cl-spec` (only for the `cl-spec` tool group).
  45. ## Quick Start
  46. ### Install
  47. ```bash
  48. # Install from Roswell
  49. ros install cl-ai-project/cl-mcp
  50. # or fetch from GitHub
  51. cd ~/common-lisp
  52. git clone https://github.com/cl-ai-project/cl-mcp.git
  53. ```
  54. Load and run from an existing REPL:
  55. ```lisp
  56. (asdf:load-system :cl-mcp) ; or (ql:quickload :cl-mcp) if using Quicklisp
  57. ;; Start the HTTP server on port 3000 (the default)
  58. (cl-mcp:start-http-server :port 3000)
  59. ;; Or start the TCP transport on port 12345, accepting clients until stopped
  60. (cl-mcp:ensure-tcp-server-thread :port 12345)
  61. ```
  62. Or run a minimal stdio loop (one JSON-RPC line per request):
  63. ```bash
  64. # With Roswell
  65. ros run -s cl-mcp -e "(cl-mcp:run :transport :stdio)"
  66. # With a plain sbcl command
  67. sbcl --eval '(require :asdf)' \
  68. --eval '(asdf:load-system :cl-mcp)' \
  69. --eval '(cl-mcp:run :transport :stdio)'
  70. ```
  71. **Project root**: File operations require a project root to be set. The root
  72. belongs to the session that sets it, with `fs-set-project-root` or with
  73. `initialize`'s `rootPath`/`rootUri`: several agents can share one server and
  74. work on different projects, and none of them moves another's root.
  75. `MCP_PROJECT_ROOT`, when set, is the default for a session that sets none. If it
  76. is not set, a session's first file access returns an error prompting it to call
  77. `fs-set-project-root`; AI agents handle this by setting it to their working
  78. directory. A session's own root lasts as long as the session, so a reconnect -- a
  79. new HTTP session or TCP connection -- starts from `MCP_PROJECT_ROOT` when it is set,
  80. and otherwise without a root, and has to set its own again.
  81. ### System Prompts
  82. The `prompts/` directory contains system prompts that teach AI agents how to
  83. use cl-mcp tools effectively:
  84. - **`repl-driven-development.md`** — Tool selection guide, REPL-driven workflow
  85. (explore → experiment → persist → verify), editing patterns, and
  86. troubleshooting recipes
  87. - **`common-lisp-expert.md`** — Production-quality Common Lisp coding standards,
  88. CLOS/conditions/restarts conventions, and TDD with Rove
  89. - **`cl-spec-driven-development.md`** — Contract-driven workflow for the
  90. optional `cl-spec` tool group: finding and writing Function Specs and
  91. Properties, baselines, seed replay, and reading `spec-check` verdicts.
  92. Supplements the two prompts above rather than replacing them
  93. cl-mcp also sends a short summary of the first, and of the third when the
  94. `cl-spec` group is enabled, as its MCP server instructions (see [Server
  95. instructions](docs/tools.md#server-instructions)), so a client that honours
  96. them gets the essentials without any setup. Reference
  97. the full prompts from your project's `CLAUDE.md` (or equivalent) when you want
  98. the complete guide, or when your client ignores server instructions:
  99. ```markdown
  100. # CLAUDE.md
  101. @prompts/repl-driven-development.md
  102. @prompts/common-lisp-expert.md
  103. ```
  104. If you enable the `cl-spec` tool group (see
  105. [Optional tool groups](docs/tools.md#optional-tool-groups)), add the third
  106. prompt as well. Leave it out otherwise: without the group, the tools it
  107. describes are not in the agent's tool list.
  108. ```markdown
  109. @prompts/cl-spec-driven-development.md
  110. ```
  111. ### Claude Code
  112. #### HTTP transport (recommended)
  113. Start the HTTP server from your REPL and keep using it alongside Claude Code:
  114. ```lisp
  115. (asdf:load-system :cl-mcp) ; or (ql:quickload :cl-mcp)
  116. ;; Start HTTP server on port 3000 (default)
  117. (cl-mcp:start-http-server :port 3000)
  118. ;; Server is now running at http://127.0.0.1:3000/mcp
  119. ;; You can continue using your REPL normally
  120. (+ 1 2) ; => 3
  121. ;; Stop the server when done
  122. (cl-mcp:stop-http-server)
  123. ```
  124. Register it with Claude Code:
  125. ```bash
  126. claude mcp add --transport http cl-mcp http://127.0.0.1:3000/mcp
  127. ```
  128. or write the entry yourself, in the project's `.mcp.json` (or `~/.claude.json` for all projects):
  129. ```json
  130. {
  131. "mcpServers": {
  132. "cl-mcp": {
  133. "type": "http",
  134. "url": "http://127.0.0.1:3000/mcp"
  135. }
  136. }
  137. }
  138. ```
  139. `start-http-server` also takes `:token :generate` (or a token string) to require an
  140. `Authorization: Bearer <token>` header on every request; the generated token is printed
  141. to `*error-output*`.
  142. This approach lets both you and Claude Code share the same Lisp runtime.
  143. You can inspect state from SLIME/Sly while Claude Code works through MCP.
  144. #### Stdio transport
  145. For a simpler setup where Claude Code manages the server process directly:
  146. ```json
  147. {
  148. "mcpServers": {
  149. "cl-mcp": {
  150. "type": "stdio",
  151. "command": "ros",
  152. "args": ["run", "-s", "cl-mcp", "-e", "(cl-mcp:run)"],
  153. "env": {
  154. "MCP_ENABLE_TOOL_GROUPS": "cl-spec"
  155. }
  156. }
  157. }
  158. }
  159. ```
  160. The `env` entry is optional; it turns on the `cl-spec` tool group (see
  161. [Optional tool groups](docs/tools.md#optional-tool-groups)). Any variable from
  162. [Environment Variables](#environment-variables) can be passed the same way.
  163. Stdio is easy to configure but the Lisp process is owned by Claude Code,
  164. making manual intervention from SLIME or another REPL difficult.
  165. ### Codex
  166. Configure in `~/.codex/config.toml`.
  167. #### Stdio transport
  168. The simplest setup — Codex spawns and manages the server process:
  169. ```toml
  170. [mcp_servers.cl-mcp]
  171. command = "ros"
  172. args = ["run", "-s", "cl-mcp", "-e", "(cl-mcp:run)"]
  173. ```
  174. As with Claude Code's stdio mode, the Lisp process is owned by Codex and
  175. not easily accessible from SLIME or another REPL.
  176. #### TCP transport with stdio bridge
  177. Start a TCP server from your REPL, then point Codex at it via the bundled
  178. Python bridge that translates stdio ↔ TCP:
  179. ```lisp
  180. ;; In your REPL: keep accepting clients, so Codex can reconnect after a restart
  181. (asdf:load-system :cl-mcp)
  182. (cl-mcp:ensure-tcp-server-thread :port 12345)
  183. ```
  184. ```toml
  185. [mcp_servers.cl-mcp]
  186. command = "python3"
  187. # Codex starts the bridge from your project, not from the cl-mcp checkout,
  188. # so give the script's absolute path.
  189. args = ["/path/to/cl-mcp/scripts/stdio_tcp_bridge.py", "--host", "127.0.0.1", "--port", "12345"]
  190. ```
  191. `--host` and `--port` default to `127.0.0.1` and `12345`; the bridge also reads
  192. `LISP_MCP_HOST` and `LISP_MCP_PORT`. (`cl-mcp:start-tcp-server-thread` serves a single
  193. client and then stops unless given `:accept-once nil`.)
  194. This gives you the same shared-REPL workflow as Claude Code's HTTP mode —
  195. you keep your SLIME/Sly session while Codex works through the bridge.
  196. A TCP request line that is not valid UTF-8 is answered with a parse error
  197. (-32700) and the connection goes on. Over stdio the same bytes are decoded with
  198. U+FFFD in place of each invalid sequence (SBCL reads stdin that way), and the
  199. request runs.
  200. ## Worker Pool Isolation
  201. Eval-dependent tools (`repl-eval`, `load-system`, `run-tests`, `code-*`,
  202. `clos-describe`, `lisp-macroexpand`, `inspect-object`, and the optional `spec-*` tools)
  203. run in isolated child SBCL processes. Each session gets
  204. a dedicated worker with automatic crash recovery and circuit breaker protection.
  205. File-system and editing tools run inline in the parent process, each request under
  206. its own session's project root.
  207. With the worker pool enabled, a worker crash loses all worker-local Lisp state
  208. (loaded systems, definitions, packages, and REPL state). Any in-flight call
  209. that observes the crash fails. The pool normally attempts recovery; if it
  210. supplies a replacement, that worker starts with fresh Lisp state. The circuit
  211. breaker can halt automatic recovery after repeated crashes. In diagnostic logs,
  212. `worker.crashed` can initially report `exit_status=running` after TCP EOF; that
  213. is a provisional snapshot. Use the later `worker.reaped` event for the final
  214. process exit status.
  215. For a pooled SBCL worker request, a condition that no existing handler resolves
  216. and that reaches the debugger path is observed and aborted as that request's
  217. structured failure. This preserves the worker for later requests, but it does
  218. not roll back side effects made before the failure. A process exit such as
  219. SB-EXT:EXIT remains a real worker crash and follows normal EOF/reaper recovery.
  220. Disable the worker pool with `MCP_NO_WORKER_POOL=1` or the `:worker-pool` keyword:
  221. ```lisp
  222. (cl-mcp:run :transport :stdio :worker-pool nil)
  223. ```
  224. ## Environment Variables
  225. | Variable | Purpose | Default |
  226. |----------|---------|---------|
  227. | `MCP_PROJECT_ROOT` | Default project root for sessions that set none of their own | (not set: each session sets its own) |
  228. | `MCP_LOG_LEVEL` | Log level: `debug`, `info`, `warn` (or `warning`), `error`; an unrecognized value is ignored | `debug` |
  229. | `MCP_LOG_FILE` | Also log to a file, named `<stem>-<timestamp>-<pid>.<ext>` beside the given path; workers do not inherit it | (stderr only) |
  230. | `MCP_NO_WORKER_POOL` | Any non-empty value (even `0`) disables worker pool isolation | (not set = pool enabled) |
  231. | `MCP_ENABLE_TOOL_GROUPS` | Optional tool groups to enable, separated by commas or spaces, case-insensitive (`cl-spec`); read when the system loads. The `:tool-groups` argument of `run`, `start-http-server`, `serve-tcp`, `start-tcp-server-thread` and `ensure-tcp-server-thread` overrides it | (empty: all groups off) |
  232. | `MCP_WORKER_SWANK` | Any non-empty value makes each worker `(ql:quickload :swank)` and start a Swank server on a free port, reported in the `worker.swank.started` log event (needs Quicklisp in the worker; without it the worker runs without Swank) | (off) |
  233. | `CL_MCP_WORKER_POOL_WARMUP` | Number of standby workers to maintain (non-negative integer) | `1` |
  234. | `CL_MCP_MAX_POOL_SIZE` | Maximum total workers, bound + standby (positive integer) | `16` |
  235. | `MCP_WORKER_INIT_SYSTEM` | ASDF system to load in the elected owner worker at bind (master gate for the init hook) | (unset = off) |
  236. | `MCP_WORKER_INIT_ENTRY` | `PKG:SYMBOL` nullary thunk run after the load (preferred activation) | (none) |
  237. | `MCP_WORKER_INIT_EVAL` | Lisp form run via repl-eval as an escape hatch | (none) |
  238. | `MCP_WORKER_INIT_PACKAGE` | Package used to read/eval `MCP_WORKER_INIT_EVAL` | `CL-USER` |
  239. | `MCP_WORKER_INIT_MAX_FAILURES` | Soft init failures before init auto-retry latches off | `1` |
  240. | `MCP_WORKER_INIT_MODE` | `singleton` (one owner binds a fixed port). v1 supports `singleton` only | `singleton` |
  241. ### Tuning warmup for cold-start handshakes
  242. The worker pool warms its standbys asynchronously once `cl-mcp:run`
  243. returns control to the MCP transport, so the stdio handshake is not
  244. blocked on subprocess launches. If you still see your MCP client
  245. report `Failed to connect` on a cold FASL cache — for example the
  246. first cl-mcp invocation after a system upgrade — set
  247. `CL_MCP_WORKER_POOL_WARMUP=0` to skip pre-spawning entirely. Workers
  248. are then created on demand the first time a session needs one,
  249. trading first-eval latency for the smallest possible startup
  250. footprint. Once your client establishes the session you can ignore
  251. the warmup; the pool will grow as sessions arrive.
  252. ### Running an app inside a worker (init hook)
  253. Set `MCP_WORKER_INIT_SYSTEM` (and optionally `MCP_WORKER_INIT_ENTRY`) to have
  254. the pool run a startup routine inside the single worker elected as the
  255. "runtime owner" when a session binds it. This lets an app (e.g. a web server)
  256. run in the same process that serves `repl-eval`/`load-system`, so hot-reload
  257. lands in the app's process, while the parent keeps the persistent `/mcp`
  258. endpoint. `pool-kill-worker` restarts the runtime without dropping `/mcp`.
  259. - The init runs on a background thread under a worker-global ASDF load lock,
  260. so it never races a `load-system` RPC.
  261. - `MCP_WORKER_INIT_SYSTEM` is loaded the way the `load-system` tool loads: a
  262. file that compiles with a full `WARNING` is refused, as `asdf:load-system`
  263. refuses it, and the init fails. `ql:quickload` muffles such warnings, so an
  264. app that has only ever been quickloaded can meet this the first time its
  265. files are compiled here; `load-system` on it names the warning and its place.
  266. - Init failures never trip the crash circuit breaker; a failed init leaves a
  267. plain, usable REPL worker. Check `pool-status` (`init_owner_session`,
  268. `init_disabled`, `init_failures`) to see runtime state.
  269. - Requires the pool enabled (do not set `MCP_NO_WORKER_POOL=1`); cl-mcp warns
  270. at startup if the init vars are set while the pool is disabled.
  271. - The init form must be bind-robust and idempotent, and should pass
  272. `:address "127.0.0.1"` for a localhost-only dev server. Do not embed
  273. secrets in `MCP_WORKER_INIT_EVAL`.
  274. - Reloading code with `load-system :force t` while the app is serving live
  275. requests can race in-flight request threads (class/method redefinition);
  276. reload between requests or quiesce the app's acceptor first.
  277. Example (recurya): add a nullary `recurya/dev:start-dev-runtime!` thunk that
  278. starts the DB and web server, then set `MCP_WORKER_INIT_SYSTEM=recurya/dev`
  279. and `MCP_WORKER_INIT_ENTRY=recurya/dev:start-dev-runtime!`.
  280. Known v1 limitations:
  281. - **Single dev runtime / single session.** `singleton` mode is designed for one
  282. developer session driving one fixed-port app. Ownership is bound to the owner
  283. session and never migrates to a different *live* session, so hot-reload stays
  284. in the app's process. A narrow multi-session race remains (if the owner's
  285. worker crashes during the same window that a second session binds), so two
  286. concurrent sessions against one init runtime is not supported in v1; a future
  287. per-worker/ephemeral-port mode is planned for that.
  288. - **Reset is not instantaneous.** `pool-kill-worker` re-arms the runtime, but the
  289. app is re-initialized lazily on the session's next tool call (not eagerly), so
  290. the app is briefly down after a reset until the next MCP request. The parent
  291. `/mcp` endpoint stays up throughout.
  292. - **Soft-failure retry is worker-scoped.** `MCP_WORKER_INIT_MAX_FAILURES` counts
  293. init failures across a session's worker (re)binds (e.g. successive hard-crash
  294. recoveries). A *soft* init failure (the app reports an error but the worker
  295. stays alive) keeps the runtime owned by that session (no migration) but is not
  296. auto-retried on the same worker — recover it with `pool-kill-worker`.
  297. ## Running in a Container
  298. When cl-mcp runs in a container and the project is bind-mounted into it, the
  299. files it writes belong to the user the server runs as. Editing an existing file
  300. keeps that file's read, write and execute bits and, when the server runs as
  301. root, its owner and group too. Run as another user, the server keeps the group
  302. when that user is in it, and the owner becomes the server's user either way. A
  303. **new** file or directory always
  304. belongs to the server's user, so a server running as root leaves root-owned
  305. files in your working tree that you cannot edit in place.
  306. Run the container as your own user, so that every file the server writes is
  307. yours:
  308. ```bash
  309. docker run --rm -it \
  310. --user "$(id -u):$(id -g)" \
  311. -e HOME=/tmp/cl-mcp-home \
  312. -v "$PWD":"$PWD" -w "$PWD" \
  313. your-cl-mcp-image
  314. ```
  315. With Docker Compose, set `user: "1000:1000"` (your `id -u` and `id -g`) on the
  316. service.
  317. - Your user has to be able to read the image's Lisp installation (Roswell,
  318. Quicklisp), and to write a home directory and the FASL caches
  319. (`~/.cache/common-lisp`, ASDF's, and `~/.cache/cl-mcp/worker-fasls`, where
  320. each worker compiles its project's files, under `$XDG_CACHE_HOME` when set).
  321. Point `HOME` at a writable directory as above, or mount a volume there, so
  322. the cache survives restarts. Roswell looks for its
  323. installation in `$ROSWELL_HOME`, or else `$HOME/.roswell`: when the image
  324. installed it under its own user's home, set `ROSWELL_HOME` to that directory
  325. as well, or the moved `HOME` hides it.
  326. - Mount the project directory, not single files. Every write replaces the file
  327. with `rename`, and the kernel refuses to rename onto a file that is itself a
  328. bind mount (`EBUSY`).
  329. - Mounting the project at the same path as on the host, as above, keeps the
  330. paths the server reports valid on the host.
  331. ## Security Model
  332. **cl-mcp is a trusted, localhost-only development tool.** `repl-eval` executes
  333. arbitrary Common Lisp code in the host image, so any client with MCP access has
  334. full system privileges. Do not expose the endpoint beyond localhost. File
  335. operation restrictions (project root enforcement) are convenience guardrails
  336. to prevent accidental mistakes, not security boundaries.
  337. Because a request that reaches it is code execution, the HTTP transport refuses
  338. what a web page could send it, as the MCP Streamable HTTP transport requires:
  339. a request whose `Origin` is not a loopback origin (403), a request whose `Host`
  340. does not name the loopback interface while the server listens only on it
  341. (403; this is what stops DNS rebinding), and a `POST` that is not
  342. `Content-Type: application/json` (415). Clients that are not browsers send no
  343. `Origin` and are unaffected. A server started on a non-loopback address was
  344. exposed on purpose, and its `Host` is not checked; its `Origin` still is, since
  345. a page rebound to its LAN address sends an `Origin` matching that `Host`.
  346. Input that would drive a recursive parser off the end of a thread's stack is
  347. refused before any parser sees it. SBCL cannot always recover from an exhausted
  348. stack, and when it cannot, the whole server stops. A JSON message nested more
  349. than 1000 levels deep is a parse error (-32700). A worker's answer that deep
  350. comes back as an error instead of being read: ask for a shallower `preview_max_depth` or `max_depth`. Lisp source
  351. that would make the reader recurse more than 500 levels is refused by the tools
  352. that read it, whether it is a file, tool content or `repl-eval` code. That
  353. covers nested lists and also chains of prefixes such as `'`, `#'` and `#+`.
  354. The HTTP transport has no authentication by default. `start-http-server`'s
  355. `:token` argument (`:generate` or a string) makes every request other than
  356. `OPTIONS` carry `Authorization: Bearer <token>`.
  357. Workers are child processes of the server and inherit its whole environment,
  358. API keys and other secrets included: code run through `repl-eval` can read them.
  359. Only the `MCP_WORKER_INIT_*` variables and `MCP_LOG_FILE` are withheld (the worker's own
  360. `MCP_*` control variables are set fresh). A worker
  361. listens on `127.0.0.1` and answers only the parent, which proves itself with a
  362. per-worker shared secret.
  363. ## License
  364. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.