lisp-mcp-server

A minimal Model Context Protocol (MCP) server for Common Lisp. It provides a newline‑delimited JSON‑RPC 2.0 transport over stdio or TCP, a small protocol layer (initialize, ping, tools/list, tools/call), and a REPL tool that evaluates forms and returns the last value.

This repo is intentionally small and test-first. It’s designed for editor/agent clients to drive Common Lisp development via MCP.

Features

JSON‑RPC 2.0 request/response framing (one message per line)
MCP initialize handshake with capability discovery
Tools API with one built-in tool: repl-eval
Transports: :stdio and :tcp
Structured JSON logs with level control via env var
Rove test suite wired through ASDF test-op

Protocol Support

Protocol versions recognized: 2025-06-18, 2025-03-26, 2024-11-05
- On initialize, if the client’s protocolVersion is supported it is echoed back; otherwise the server’s preferred version is selected.

Requirements

SBCL 2.x (developed with SBCL 2.5.x)
Quicklisp (for dependencies)
Dependencies (via ASDF/Quicklisp): alexandria, yason, usocket, bordeaux-threads, rove (tests)

Note: The repository currently uses yason for JSON.

Quick Start

Load and run from an existing REPL:

(ql:quickload :lisp-mcp-server)
(asdf:load-system :lisp-mcp-server)

;; Start TCP transport on an ephemeral port, print chosen port
(lisp-mcp-server:run :transport :tcp
                     :port 12345
                     :accept-once nil
                     :on-listening (lambda (p)
                                     (format t "~&port=~A~%" p)))

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

(lisp-mcp-server:run :transport :stdio)

Try it with the bundled clients

Python TCP one‑shot client (initialize):

python3 scripts/client_init.py --host 127.0.0.1 --port 12345 --method initialize --id 1

Stdio↔TCP bridge (connect editor’s stdio to the TCP server):

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | \
  python3 scripts/stdio_tcp_bridge.py --host 127.0.0.1 --port 12345

The bridge uses a bounded connect timeout but disables read timeouts after connecting, so it can stay idle indefinitely (until stdin closes).

Tools

`repl-eval`

Evaluate one or more forms and return the last value as a text item.

Input schema (JSON):

code (string, required): one or more s‑expressions
package (string, optional): package to evaluate in (default CL-USER)
printLevel (integer|null): binds *print-level*
printLength (integer|null): binds *print-length*

Example JSON‑RPC request:

{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"repl-eval","arguments":{"code":"(+ 1 2)"}}}

Response (excerpt):

{"result":{"content":[{"type":"text","text":"3"}]}}

Logging

Structured JSON line logs to *error-output*.
Control level via env var MCP_LOG_LEVEL with one of: debug, info, warn, error.

Example:

MCP_LOG_LEVEL=debug sbcl --eval '(ql:quickload :lisp-mcp-server)' ...

Running Tests

This project uses Rove and ASDF’s test-op.

From a REPL with Quicklisp:

(asdf:load-asd #P"lisp-mcp-server.asd")
(asdf:test-system "lisp-mcp-server")

What’s covered:

Version/API surface sanity
REPL evaluation semantics (reader eval enabled)
Protocol handshake (initialize, ping, tools listing/calls)
Logging of RPC dispatch/results
TCP server accept/respond (newline‑delimited JSON)
Stdio↔TCP bridge stays alive on idle and exits cleanly when stdin closes

Note: Running tests compiles FASLs into ~/.cache/.... Ensure your environment allows writing there or configure SBCL’s cache directory accordingly.

Project Layout

src/ — packages, logging, REPL, protocol, TCP, run entrypoint
tests/ — Rove test suites invoked by ASDF test-op
scripts/ — helper clients and a stdio↔TCP bridge
lisp-mcp-server.asd — main and test systems (delegates test-op to Rove)

Security Notes

Reader and runtime evaluation are both enabled. Treat this as a trusted, local-development tool; untrusted input can execute arbitrary code in the host Lisp image.
If exposure beyond trusted usage is planned, add allowlists, resource/time limits, and output caps.

Troubleshooting

Bridge exits after a few seconds of inactivity: ensure you’re using the bundled scripts/stdio_tcp_bridge.py (it disables read timeouts after connect) and that your stdin remains open.
Permission errors compiling FASLs during tests: allow writes under ~/.cache or reconfigure SBCL’s cache path.
No output on stdio: remember the protocol is one JSON‑RPC message per line. Each request must end with a newline and the server will answer with exactly one line (or nothing for notifications).

Roadmap

Error taxonomy as condition types mapped to JSON‑RPC errors
Additional tools (read‑only file access, symbol lookup, etc.)
CI (GitHub Actions) matrix for SBCL/macOS/Linux

License

MIT