Model Context Protocol server for Common Lisp code evaluation

CL-MCP-Server is the BEEZ KNEEZ. Gives Claude SUPERPOWERS.

AI agents evaluate Common Lisp code in a persistent, stateful REPL session over the Model Context Protocol (MCP).

Our focus is simple: Empower Claude with a REPL.

Claude is already good with file system access. Claude is smart. Claude decides how to use the REPL. Point your instructions at Claude.

CL-MCP-Server is an MCP server implementation that provides Claude with the ability to:

• Evaluate Common Lisp expressions in a live REPL environment
• Maintain persistent state across evaluations (functions, variables, loaded systems)
• Capture rich output (return values, stdout, stderr, warnings, backtraces)
• Handle errors gracefully using Common Lisp's condition system
• Support incremental development with stateful session management

Unlike one-shot code execution, CL-MCP-Server provides a full REPL experience where definitions accumulate and state persists, enabling interactive exploratory programming through Claude.

• NEW: Paren matching tools -- the agents struggle with lots of parens
• Persistent REPL: Define functions once, use them repeatedly in the same session
• 36 tools: full-on REPL power for evaluation, introspection, profiling, and more
• Rich Error Reporting: Get detailed backtraces and condition information when things go wrong
• Stream Separation: Clearly distinguish between return values, printed output, and warnings
• Safe Execution: Server never crashes—all user code errors are caught and reported

• Standard Protocol: Uses MCP and JSON-RPC 2.0 for interoperability
• Formally Specified: Complete Canon specification in canon/ directory
• Well-Tested: Comprehensive test suite covering protocol, evaluation, and error handling
• Extensible: Clean architecture supports adding new tools and capabilities

• Formal Contracts: Machine-readable specifications in canon/features/
• Predictable Behavior: Documented invariants and properties
• JSON Schema: Structured request/response formats
• Standard Transport: stdio-based communication

• SBCL (Steel Bank Common Lisp)
• Quicklisp for dependency management
• Claude Code or compatible MCP client

1. Clone the following repositories to your quicklisp local-projects:

git clone https://github.com/quasi/opsis
git clone https://github.com/quasi/telos
git clone https://github.com/quasi/cl-mcp.git
git clone https://github.com/quasi/cl-mcp-server.git

2. Load dependencies (Quicklisp will install them automatically):

cd cl-mcp-server

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

3. Configure Claude Code:

claude mcp add --scope user --transport stdio lisp -- sbcl --script /path/to/cl-mcp-server/run-server.lisp

4. Configure Claude Desktop to use the server (optionally):

{
  "mcpServers": {
    "lisp": {
      "command": "sbcl",
      "args": [
        "--load", "/path/to/cl-mcp-server/run-server.lisp"
      ]
    }
  }
}

5. Configure Gemini

{
  "mcpServers": {
   "lisp": {
     "command": "/path-to/cl-mcp-server/run-server.lisp",
     "args": [],
     "description": "REPL power"
   }
 }
}

6. Configure Opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cl-mcp-server": {
        "type": "local",
        "enabled": true,
        "command": ["sbcl", "--script", "/path-to/cl-mcp-server/run-server.lisp"],
    },
  },
}

User: Please evaluate (+ 1 2 3)
Claude: => 6

User: Define a function to calculate factorial
Claude: (evaluating)
        (defun factorial (n)
          (if (<= n 1) 1 (* n (factorial (- n 1)))))
        => FACTORIAL

User: What is 10 factorial?
Claude: (evaluating) (factorial 10)
        => 3628800

See the Quickstart Guide for a complete walkthrough.

• Quickstart - Get running in 5 minutes
• Tutorial: First REPL Session - Learn by building a temperature converter
• Full Documentation - Complete user guide

• Dev Skill - Contributor guidelines, build commands, code conventions
• canon/INDEX.md - Navigate formal specifications
• Architecture - System design and rationale

• canon/features/ - Formal API specifications
• canon/core/foundation/vocabulary.md - Domain model
• MCP Protocol Contracts - Protocol details

• ✓ MCP Protocol: Standards-compliant JSON-RPC 2.0 over stdio
• ✓ Persistent Session: State persists across all evaluations
• ✓ Rich Output: Separates return values, stdout, stderr, and warnings
• ✓ Error Handling: Captures and reports conditions with backtraces
• ✓ Multiple Values: Full support for Common Lisp's multiple return values
• ✓ Safety: Server isolation mitigates against user code from crashing the server
• ✓ Stream Capture: All output streams are captured during evaluation

CL-MCP-Server provides 36 tools organized into categories:

• evaluate-lisp - Execute Common Lisp code in persistent REPL session
• compile-form - Compile code without executing to check for warnings/errors
• time-execution - Execute code with detailed timing and memory statistics

• validate-syntax - Check code syntax without evaluation (use before saving files)

• describe-symbol - Get comprehensive information about symbols (functions, variables, classes)
• apropos-search - Search for symbols by pattern with type filtering
• macroexpand-form - Expand macros to understand their transformations

• class-info - Inspect classes, slots, superclasses, and inheritance hierarchies
• find-methods - Find all methods specialized on a given class

• describe-last-error - Get detailed information about the most recent error
• get-backtrace - Retrieve stack trace from the last error

• describe-system - Get information about ASDF system structure
• system-dependencies - View dependency graph for a system
• list-local-systems - Find all locally available ASDF systems
• load-file - Load a single Lisp file into the session

• quickload - Load systems via Quicklisp with automatic dependency resolution
• quicklisp-search - Search Quicklisp for available systems

• profile-code - Statistical profiling for CPU, wall-clock time, or memory allocation
• profile-functions - Deterministic profiling of specific functions
• memory-report - Get detailed memory usage and GC statistics
• allocation-profile - Profile memory allocation patterns

• list-definitions - List all definitions (functions, variables, macros) in current session
• reset-session - Clear session state and start fresh

• telos-list-features - List all features defined in loaded systems
• telos-feature-intent - Get full intent definition for a feature
• telos-get-intent - Get intent attached to functions, classes, or conditions
• telos-intent-chain - Trace intent hierarchy from code to root feature
• telos-feature-members - List all functions and classes in a feature

See Tools Reference for detailed documentation.

┌──────────────────────────────────────┐
│         MCP Client (Claude)          │
└──────────────┬───────────────────────┘
               │ JSON-RPC over stdio
               │
┌──────────────▼───────────────────────┐
│  cl-mcp  (external library)          │
│  • JSON-RPC 2.0 framing              │
│  • stdio transport                   │
│  • MCP handshake + dispatch          │
│  • Per-server tool registry          │
└──────────────┬───────────────────────┘
               │ register-tool / run-server
               │
┌──────────────▼───────────────────────┐
│         CL-MCP-Server                │
│  ┌────────────────────────────────┐  │
│  │  Tool Layer (28+ REPL tools)   │  │
│  └──────────────┬─────────────────┘  │
│                 │                    │
│  ┌──────────────▼─────────────────┐  │
│  │  Evaluator (with error capture) │  │
│  └──────────────┬──────────────────┘  │
│                 │                    │
│  ┌──────────────▼─────────────────┐  │
│  │  Session (persistent state)     │  │
│  └─────────────────────────────────┘  │
└───────────────────────────────────────┘

See Architecture Explanation for details.

Run the full test suite:

sbcl --load cl-mcp-server.asd \
     --eval "(ql:quickload :cl-mcp-server/tests)" \
     --eval "(asdf:test-system :cl-mcp-server)"

Version: 0.3.0

Status: Alpha (human testing required). The core functionality is working and tested with 36 tools available. The API may change as we gather user feedback.

Contributions are welcome! Please:

Contribute design documents and not code. A good design document example is the artifact generated by the obra superpowers writing-plans skill.

The real value is in ideas and solutions. If we fix that, claude can write the code.

MIT License

• Abhijit Rao -> quasi (quasi@quasilabs.in)

Protocol Layer Extraction

• Extracted JSON-RPC, stdio transport, and tool registry into standalone cl-mcp library
• server.lisp is now a thin 12-line glue: cl-mcp:make-server → define-builtin-tools → cl-mcp:run-server
• cl-mcp-server.conditions re-exports from cl-mcp.conditions for backward compatibility
• No functional changes to tools or REPL behavior

Telos Intent Introspection

New Tool Category:

• Telos Integration (5 tools): Intent-driven development support
  • telos-list-features - List all features defined in loaded systems
  • telos-feature-intent - Get full intent definition for a feature
  • telos-get-intent - Get intent attached to functions, classes, or conditions
  • telos-intent-chain - Trace intent hierarchy from code to root feature
  • telos-feature-members - List all functions and classes in a feature

Total: 28 tools (up from 23 in v0.2.0 — note: actual count is 36 including configure-limits, who-calls, who-references, find-system-file, telos-feature-decisions, telos-list-decisions, load-system, get-usage-guide)

Features:

• Graceful degradation when telos is not loaded
• Enhanced formatting for structs, conditions, and methods
• Full integration with telos intent system for purpose-driven code exploration

Major Feature Expansion

New Tool Categories:

• Code Evaluation & Execution (3 tools): evaluate-lisp, compile-form, time-execution
• Syntax & Validation (1 tool): validate-syntax for pre-save verification
• Code Introspection (3 tools): describe-symbol, apropos-search, macroexpand-form
• CLOS Intelligence (2 tools): class-info, find-methods for object-oriented code
• Error Intelligence (2 tools): describe-last-error, get-backtrace for debugging
• ASDF System Management (4 tools): describe-system, system-dependencies, list-local-systems, load-file
• Quicklisp Integration (2 tools): quickload, quicklisp-search for library management
• Performance Profiling (4 tools): profile-code, profile-functions, memory-report, allocation-profile
• Session Management (2 tools): list-definitions, reset-session

Total: 23 tools (up from 1 in v0.1.0)

Documentation:

• Complete reference documentation for all tool categories
• New how-to guides for code exploration and introspection
• Expanded user documentation with examples
• Canon specifications updated for all features

Infrastructure:

• Comprehensive test coverage for all new tools
• Formal Canon specifications for verification
• Enhanced error reporting and diagnostics

Initial Release

• MCP protocol implementation (JSON-RPC 2.0 over stdio)
• evaluate-lisp tool with persistent session
• Error handling with condition capture and backtraces
• Output stream separation (values, stdout, stderr, warnings)
• Multiple return values support
• Comprehensive test suite (95%+ coverage)
• Canon specification for formal verification
• User documentation and tutorials

Ready to get started? → Quickstart Guide

Questions? → Documentation

Want to contribute? → Dev Skill