Cl MCP Server Integration

cl-mcp-server — Integration Skill

A running SBCL process with a persistent REPL exposed as 36 MCP tools. Definitions accumulate across calls — defun in call 1 is callable in call 2.

Quick Start

Always call first:

tool: get-usage-guide
args: {}

Returns workflow guide with current best practices.

Minimal evaluation:

tool: evaluate-lisp
args: {"code": "(+ 1 2)"}
→ "=> 3"

Core Concepts

Persistent Session

State is global within a server process:

• defun, defvar, defclass, ql:quickload → persist for all subsequent calls
• let, let* bindings → scoped to one evaluation
• reset-session clears everything

Output Format

evaluate-lisp returns a text string with labeled sections:

[stdout]
Hello

[stderr]
WARNING: something

[Backtrace]
0: ...

=> 42

Only non-empty sections appear. Return value is always last.

Error Behavior

Errors do NOT crash the server. They return a formatted error string:

[ERROR] DIVISION-BY-ZERO
arithmetic error DIVISION-BY-ZERO signalled
Operation was (/ 1 0).

[Backtrace]
0: (/ 1 0)
...

isError: false in the MCP response even on Lisp errors. Check for [ERROR] prefix to detect failures.

Tool Categories

Full reference: .claude/skills/integration/references/tools-reference.md

Common Patterns

PATTERN-001: Validate Before Evaluate

Use validate-syntax before saving code to files:

tool: validate-syntax
args: {"code": "(defun foo (x)\n  (* x x))"}
→ "Syntax OK"

Does not evaluate — safe for untrusted/large code.

PATTERN-002: Incremental Definition

Define, test, refine without file I/O:

# Step 1
tool: evaluate-lisp
args: {"code": "(defun square (x) (* x x))"}
→ "=> SQUARE"

# Step 2
tool: evaluate-lisp
args: {"code": "(square 7)"}
→ "=> 49"

# Step 3: only write to file when working

PATTERN-003: Debug Last Error

When evaluation returns [ERROR]:

tool: describe-last-error
args: {}
→ detailed error with restarts

tool: get-backtrace
args: {"max-frames": 10}
→ stack trace

PATTERN-004: Load External System

# Check if available
tool: quicklisp-search
args: {"pattern": "alexandria"}

# Load it
tool: quickload
args: {"system": "alexandria"}
→ "Successfully loaded: ALEXANDRIA"

# Verify
tool: evaluate-lisp
args: {"code": "(alexandria:flatten '(1 (2 3) (4 (5))))"}
→ "=> (1 2 3 4 5)"

PATTERN-005: Profile Hot Code

tool: time-execution
args: {"code": "(loop repeat 1000000 sum 1)"}
→ "Real time: 0.012s, GC time: 0.000s, Bytes: 0"

# For deeper profiling
tool: profile-code
args: {"code": "(loop repeat 1000000 sum 1)", "mode": "cpu"}

Key Tool Signatures

Pitfalls

Detailed Reference

• All 36 tools with full schemas: .claude/skills/integration/references/tools-reference.md
• Architecture: docs/explanation/architecture.md
• Canon specifications: canon/features/

Source: quasi/cl-mcp-server — distributed by TomeVault.