| name | cl-mcp-server-dev |
| description | For contributors working ON cl-mcp-server. Build/test commands, architecture, coding conventions, rules. |
| version | 0.3.1 |
| author | quasi |
| type | dev |
cl-mcp-server — Dev Skill
MCP server providing 36 Common Lisp REPL tools to Claude. Thin application layer over the cl-mcp protocol library.
Quick Reference
sbcl --load cl-mcp-server.asd --eval "(ql:quickload :cl-mcp-server)"
sbcl --load cl-mcp-server.asd \
--eval "(ql:quickload :cl-mcp-server)" \
--eval "(cl-mcp-server:start)"
sbcl --load cl-mcp-server.asd \
--eval "(ql:quickload :cl-mcp-server/tests)" \
--eval "(asdf:test-system :cl-mcp-server)"
Architecture
Dependency graph:
digraph {
rankdir=LR
"cl-mcp-server" -> "cl-mcp" [label="protocol"]
"cl-mcp-server" -> "alexandria"
"cl-mcp-server" -> "trivial-backtrace"
"cl-mcp" -> "yason"
"cl-mcp" -> "opsis/conditions"
}
What cl-mcp owns: JSON-RPC 2.0 framing, stdio transport, MCP handshake, per-server tool registry, error recovery.
What cl-mcp-server owns: Session state, code evaluation, 36 REPL tool handlers.
start reduces to 3 calls:
(cl-mcp:make-server :name "cl-mcp-server" :version "0.3.0")
(cl-mcp-server.tools:define-builtin-tools server session)
(cl-mcp:run-server server)
Package Structure
| Package | File | Purpose |
|---|
cl-mcp-server.conditions | src/conditions.lisp | REPL conditions + re-exports from cl-mcp.conditions |
cl-mcp-server.error-format | src/error-format.lisp | Condition/backtrace formatting |
cl-mcp-server.session | src/session.lisp | Persistent *package* context and state |
cl-mcp-server.evaluator | src/evaluator.lisp | Safe evaluation with stream capture |
cl-mcp-server.introspection | src/introspection.lisp | Symbol/class/method inspection |
cl-mcp-server.asdf-tools | src/asdf-tools.lisp | ASDF/Quicklisp operations |
cl-mcp-server.profiling-tools | src/profiling-tools.lisp | Statistical and deterministic profiling |
cl-mcp-server.telos-tools | src/telos-tools.lisp | Telos intent introspection (graceful degradation) |
cl-mcp-server.tools | src/tools.lisp | Registers all 36 tools via cl-mcp:register-tool |
cl-mcp-server | src/server.lisp | Entry point: start |
File Layout
| Path | Purpose |
|---|
cl-mcp-server.asd | ASDF system (depends on cl-mcp) |
src/ | Implementation |
tests/ | FiveAM test suites |
canon/ | Formal Canon specifications |
docs/ | User and contributor docs |
run-server.lisp | Script entry point |
../cl-mcp/ | External protocol library |
Critical Rules
RULE-001: Request-Response Guarantee
Every valid JSON-RPC request MUST receive exactly one response. Handled by cl-mcp; tool handlers MUST NOT raise uncaught conditions.
RULE-002: Server Stability
Server MUST NOT terminate due to evaluation errors. cl-mcp catches handler errors. Do not add sb-ext:exit or error to the server loop.
RULE-003: Session State Persistence
Definitions made in one evaluation MUST be available in subsequent evaluations. Always use with-session to bind *session*.
RULE-004: Output Stream Separation
Return values, stdout, stderr, and warnings MUST be distinguishable in results. Use format-result from cl-mcp-server.evaluator.
RULE-005: Condition Type Preservation
Error responses MUST include condition type, not just message:
(format nil "[ERROR] ~A~%~A" (type-of condition) condition)
RULE-006: Tool Registration via cl-mcp
New tools MUST be registered via cl-mcp:register-tool in src/tools.lisp. Do NOT add MCP protocol methods directly.
Coding Conventions
- Every file begins with
;;; ABOUTME: ... comment
- Naming:
*earmuffs* for specials, +plus+ for constants, -p predicates, make- constructors
- Package names: lowercase hyphenated (
cl-mcp-server.evaluator)
- Error handling:
handler-case for expected errors, handler-bind for warnings (muffle)
Testing
Test helpers in tests/packages.lisp:
;; Create a test server with all tools
(multiple-value-bind (server session) (make-test-server)
;; Call a tool
(call-test-tool server "evaluate-lisp" '(("code" . "(+ 1 2)"))))
Test suites: error-format-tests, session-tests, evaluator-tests, tools-tests,
introspection-tests, asdf-tools-tests, profiling-tools-tests, integration-tests.
Key Invariants
- INV-001: Every valid JSON-RPC request → exactly one response
- INV-002: Server never terminates due to evaluation errors
- INV-003: Session state persists across evaluations
- INV-004: Output streams (stdout/stderr/values) are distinguishable
- INV-005: All messages conform to JSON-RPC 2.0
- INV-006: Condition types are preserved in error reports
Interactive Development
When Lisp MCP tools are available (mcp__lisp__evaluate-lisp):
- Load system once:
(ql:quickload :cl-mcp-server)
- Redefine functions interactively, test, then write to file
- Reload system after package/export changes
References
- Protocol specs:
canon/INDEX.md → feature contracts and invariants
- Architecture:
docs/explanation/architecture.md
- cl-mcp API:
../cl-mcp/CLAUDE.md
- Tool catalog:
.claude/skills/integration/references/tools-reference.md
