cl-mcp-server-dev

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

# Load
sbcl --load cl-mcp-server.asd --eval "(ql:quickload :cl-mcp-server)"

# Run
sbcl --load cl-mcp-server.asd \
     --eval "(ql:quickload :cl-mcp-server)" \
     --eval "(cl-mcp-server:start)"

# Test
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

1. INV-001: Every valid JSON-RPC request → exactly one response
2. INV-002: Server never terminates due to evaluation errors
3. INV-003: Session state persists across evaluations
4. INV-004: Output streams (stdout/stderr/values) are distinguishable
5. INV-005: All messages conform to JSON-RPC 2.0
6. 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