CL-MCP-Server

Model Context Protocol server for Common Lisp code evaluation

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

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

Our focus is simple: Empower your AGENT with a REPL.

Agent is already good with file system access. Agent is smart. Agent decides how to use the REPL. Agent gets SuperPowers.

Lisp Is Super Power

---

What is This?

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, and on-demand backtraces)
• Handle errors gracefully using Common Lisp’s condition system
• Support incremental development with stateful session management
• Optimized for Token efficiency

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.

Value Proposition

For Claude Users

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

For Developers

• 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

For AI Agents

• 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

Quick Start

Prerequisites

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

Installation

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"],
    },
  },
}

Usage Example

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.

Documentation

For Users

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

For Contributors

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

For External Agents

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

Features

Core Capabilities

• ✓ 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 conditions with concise default reports and on-demand 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

Available Tools

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

Workflow & Configuration

• get-usage-guide - Get the recommended workflow for effective REPL-assisted development
• configure-limits - Configure evaluation timeout and maximum captured output

Code Evaluation & Execution

• 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

Syntax & Validation

• validate-syntax - Check code syntax without evaluation (use before saving files)
• match-paren - Find matching parentheses with line/column context

Code Introspection

• describe-symbol - Get comprehensive information about symbols (functions, variables, classes)
• apropos-search - Search for symbols by pattern with type filtering
• who-calls - Find functions that call a specified function
• who-references - Find code that references a specified variable
• macroexpand-form - Expand macros to understand their transformations

CLOS Intelligence

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

Error Intelligence

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

ASDF System Management

• 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
• find-system-file - Locate the ASDF definition file for a system
• load-system - Load an ASDF system by name
• load-file - Load a single Lisp file into the session

Quicklisp Integration

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

Performance Profiling

• 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

Session Management

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

Telos Integration

• 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
• telos-feature-decisions - Get recorded design decisions for a feature
• telos-list-decisions - List recorded decisions across all features

See Tools Reference for detailed documentation.

Token-Optimized Evaluation Output

evaluate-lisp is optimized for MCP token usage. The default response returns the information an agent usually needs immediately, and keeps verbose diagnostic detail available through dedicated follow-up tools.

• Warning responses show warnings only. Return values are suppressed when warnings are present, avoiding large => ... echoes from forms that returned a long value.
• Error and timeout responses are concise by default: condition type plus message, without an inline backtrace.
• Full error context is still captured in the session. Use describe-last-error for restarts and a backtrace overview, or get-backtrace for stack frames.
• If inline backtraces are needed for a special workflow, the evaluator exposes cl-mcp-server.evaluator:*include-backtrace-in-evaluate-response*.

Architecture

┌──────────────────────────────────────┐
│         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 (37 REPL tools)    │  │
│  └──────────────┬─────────────────┘  │
│                 │                    │
│  ┌──────────────▼─────────────────┐  │
│  │  Evaluator (with error capture) │  │
│  └──────────────┬──────────────────┘  │
│                 │                    │
│  ┌──────────────▼─────────────────┐  │
│  │  Session (persistent state)     │  │
│  └─────────────────────────────────┘  │
└───────────────────────────────────────┘

See Architecture Explanation for details.

Testing

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)"

Project Status

Version: 0.3.0

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

Contributing

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.

License

MIT License

Authors

• Abhijit Rao -> quasi ([email protected])

Changelog

Unreleased

Transport Robustness

• Evaluated code can no longer kill the server or corrupt the JSON-RPC stream. New src/stdio-guard.lisp installs process-global guards from start
• An unhandled error in any thread spawned by evaluated code previously quit the whole process: sbcl --script implies --disable-debugger, whose hook prints a backtrace and exits. sb-ext:*invoke-debugger-hook* now logs to stderr and aborts only the offending thread, resuming via CONTINUE so (break) in user code merely logs and carries on
• Stray output from spawned threads no longer reaches the protocol stream. Threads read the global value of *standard-output*, which --script leaves pointed at the pipe; the guards set the global cell via sb-ext:symbol-global-value, not a plain setf, which only mutates the script’s own binding
• start accepts :input / :output, capturing the real stdio before the redirection so the transport keeps the real pipe
• Known gap: code writing directly to sb-sys:*stdout* still reaches the protocol stream. No dynamic-variable rebinding can prevent that

Bug Fixes

• profile-functions report returned an empty string, silently and with no error. It captured *standard-output* while sb-profile:report writes to *trace-output*
• find-methods signalled UNBOUND-SLOT on any class that had never been instantiated, since an unfinalized class has no precedence list. The class is now finalized on demand

Introspection Usability

• find-methods with :include-inherited returned 1,205 lines for a two-slot class, exceeding the tool’s token budget, because the class precedence list always reaches standard-object and t. Language-level superclasses are now skipped and the omission is reported rather than silently truncated
• who-calls collapses duplicate entries by caller and location, reporting a call site count instead of repeating identical rows for recursive functions
• who-calls no longer attributes session-defined functions to run-server.lisp. SBCL records the file being loaded when eval ran, which for evaluate-lisp definitions is the launcher; such entries are marked “defined in this session”

MCP Token Usage Optimization

• evaluate-lisp suppresses return values when warnings are present, avoiding large value echoes in diagnostic responses
• Immediate error and timeout responses are concise by default; detailed backtraces remain available through describe-last-error and get-backtrace
• README tool catalog updated to list all 37 currently registered tools

Version 0.3.1 (2026-02-25)

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

Version 0.3.0 (2026-02-05)

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 at release: 28 tools (up from 23 in v0.2.0; current releases document 37 registered tools in the Available Tools section)

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

Version 0.2.0 (2026-01-27)

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

Version 0.1.0 (2026-01-22)

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