# Cl Mcp Server > Common Lisp REPL Superpower for Agents - **Type:** MCP server - **Install:** `agentstack add mcp-quasi-cl-mcp-server` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [quasi](https://agentstack.voostack.com/s/quasi) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [quasi](https://github.com/quasi) - **Source:** https://github.com/quasi/cl-mcp-server ## Install ```sh agentstack add mcp-quasi-cl-mcp-server ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 [](LICENSE) --- ## 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](http://www.sbcl.org/) (Steel Bank Common Lisp) - [Quicklisp](https://www.quicklisp.org/) for dependency management - [Claude Code](https://claude.ai/code) or compatible MCP client ### Installation 1. Clone the following repositories to your quicklisp local-projects: ```bash 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): ```bash cd cl-mcp-server sbcl --load cl-mcp-server.asd \ --eval "(ql:quickload :cl-mcp-server)" \ --quit ``` 3. Configure Claude Code: ```bash 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): ```json { "mcpServers": { "lisp": { "command": "sbcl", "args": [ "--load", "/path/to/cl-mcp-server/run-server.lisp" ] } } } ``` 5. Configure Gemini ```json { "mcpServers": { "lisp": { "command": "/path-to/cl-mcp-server/run-server.lisp", "args": [], "description": "REPL power" } } } ``` 6. Configure Opencode ```json { "$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 ( FACTORIAL User: What is 10 factorial? Claude: (evaluating) (factorial 10) => 3628800 ``` See the [Quickstart Guide](docs/quickstart.md) for a complete walkthrough. ## Documentation ### For Users - **[Quickstart](docs/quickstart.md)** - Get running in 5 minutes - **[Tutorial: First REPL Session](docs/tutorials/01-first-session.md)** - Learn by building a temperature converter - **[Full Documentation](docs/README.md)** - Complete user guide ### For Contributors - **[Dev Skill](.claude/skills/dev/SKILL.md)** - Contributor guidelines, build commands, code conventions - **[canon/INDEX.md](canon/INDEX.md)** - Navigate formal specifications - **[Architecture](docs/explanation/architecture.md)** - System design and rationale ### For External Agents - **[canon/features/](canon/features/)** - Formal API specifications - **[canon/core/foundation/vocabulary.md](canon/core/foundation/vocabulary.md)** - Domain model - **[MCP Protocol Contracts](canon/features/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](docs/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](docs/explanation/architecture.md) for details. ## Testing Run the full test suite: ```bash 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 (quasi@quasilabs.in) ## Changelog ### Unreleased **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](https://github.com/quasi/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](docs/quickstart.md) **Questions?** → [Documentation](docs/README.md) **Want to contribute?** → [Dev Skill](.claude/skills/dev/SKILL.md) ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [quasi](https://github.com/quasi) - **Source:** [quasi/cl-mcp-server](https://github.com/quasi/cl-mcp-server) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-quasi-cl-mcp-server - Seller: https://agentstack.voostack.com/s/quasi - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.