### Starting the Server

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Instructions for starting the cl-mcp server via HTTP, TCP, or stdio.

```APIDOC
## Starting the Server

### Description
Starts the cl-mcp server using different transport protocols: HTTP (recommended for Claude Code), TCP (for development), or stdio.

### Method
Lisp REPL commands or shell command

### Endpoint
N/A

### Parameters
None

### Request Example
```lisp
;; HTTP server (recommended for Claude Code integration)
(cl-mcp:start-http-server :port 3000)
;; Server runs at http://127.0.0.1:3000/mcp

;; TCP server (development)
(cl-mcp:start-tcp-server-thread :port 12345)

;; Stdio transport
ros run -s cl-mcp -e "(cl-mcp:run :transport :stdio)"
```

### Response
N/A

### Success Response (200)
N/A

### Response Example
N/A
```

--------------------------------

### Starting CL-MCP HTTP Server

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Start the CL-MCP HTTP server from your REPL using `ql:quickload` and `cl-mcp:start-http-server`. This makes the MCP service available over HTTP.

```common-lisp
(ql:quickload :cl-mcp)
(cl-mcp:start-http-server :port 3000)
```

--------------------------------

### Test from REPL (via MCP tools)

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Example of running a specific test case from the REPL using MCP tools and capturing its output.

```APIDOC
## Test from REPL (via MCP tools)

### Description
Demonstrates how to execute a specific test case directly from the Common Lisp REPL using MCP tools, with the capability to capture the test's standard output.

### Method
Lisp REPL command

### Endpoint
N/A

### Parameters
None

### Request Example
```lisp
;; Run specific test with output capture
(with-output-to-string (*standard-output*)
  (rove:run-test 'cl-mcp/tests/integration-test::repl-eval-printlength))
```

### Response
N/A

### Success Response (200)
N/A

### Response Example
N/A
```

--------------------------------

### Load Quicklisp Systems with ql:quickload

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/prompts/repl-driven-development.md

Loads Common Lisp libraries and systems using Quicklisp. This is typically done once at the session start to make external functionalities available for use in the project.

```common-lisp
(ql:quickload :system-name)
```

--------------------------------

### Start HTTP Server for Claude Code Integration (Common Lisp)

Source: https://context7.com/cl-ai-project/cl-mcp/llms.txt

Initializes and starts an HTTP server for Claude Code integration on a specified port. Requires the 'cl-mcp' Quicklisp system to be loaded. The server runs at http://127.0.0.1:<port>/mcp. The REPL remains usable while the server is active. Use 'cl-mcp:stop-http-server' to shut it down.

```common-lisp
;; Load the system
(ql:quickload :cl-mcp)

;; Start HTTP server on port 3000
(cl-mcp:start-http-server :port 3000)
;; => #<MCP-ACCEPTOR (host 127.0.0.1) (port 3000)>
;; Server runs at http://127.0.0.1:3000/mcp

;; You can continue using your REPL normally while server runs
(+ 1 2)  ; => 3

;; Stop when done
(cl-mcp:stop-http-server)
```

--------------------------------

### Start cl-mcp HTTP Server

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Starts the cl-mcp server using the HTTP transport on port 3000. This is the recommended method for Claude Code integration. The server will be accessible at http://127.0.0.1:3000/mcp.

```lisp
;; HTTP server (recommended for Claude Code integration)
(cl-mcp:start-http-server :port 3000)
;; Server runs at http://127.0.0.1:3000/mcp
;; You can continue using your REPL while the server runs
```

--------------------------------

### Start HTTP Transport Server in Common Lisp

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/README.md

Loads the cl-mcp library and starts an HTTP transport server on a specified port. This server is accessible via HTTP and is recommended for use with Claude Code.

```common-lisp
(ql:quickload :cl-mcp)

;; Start HTTP server on port 3000 (default)
(cl-mcp:start-http-server :port 3000)

;; Server is now running at http://127.0.0.1:3000/mcp
;; You can continue using your REPL normally
(+ 1 2)  ; => 3

;; Stop the server when done
(cl-mcp:stop-http-server)
```

--------------------------------

### Server Initialization (HTTP)

Source: https://context7.com/cl-ai-project/cl-mcp/llms.txt

Starts an HTTP server for Claude Code integration on a specified port. The server runs at http://127.0.0.1:<port>/mcp.

```APIDOC
## Server Initialization (HTTP)

### Description
Starts an HTTP server for Claude Code integration on a specified port. The server runs at http://127.0.0.1:<port>/mcp.

### Method
Lisp Function Call

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```lisp
;; Load the system
(ql:quickload :cl-mcp)

;; Start HTTP server on port 3000
(cl-mcp:start-http-server :port 3000)
;; => #<MCP-ACCEPTOR (host 127.0.0.1) (port 3000)>
;; Server runs at http://127.0.0.1:3000/mcp

;; Stop when done
(cl-mcp:stop-http-server)
```

### Response
#### Success Response (200)
Returns the server acceptor object upon successful start, or indicates completion upon stop.

#### Response Example
```
#<MCP-ACCEPTOR (host 127.0.0.1) (port 3000)>
```
```

--------------------------------

### Server Initialization (TCP)

Source: https://context7.com/cl-ai-project/cl-mcp/llms.txt

Starts a TCP server in a separate thread for direct socket connections on a specified port.

```APIDOC
## Server Initialization (TCP)

### Description
Starts a TCP server in a separate thread for direct socket connections on a specified port.

### Method
Lisp Function Call

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```lisp
;; Start TCP server on port 12345
(cl-mcp:start-tcp-server-thread :port 12345)
;; => #<THREAD "mcp-tcp-server">, 12345

;; Check if server is running
(cl-mcp:tcp-server-running-p)
;; => T

;; Stop the server
(cl-mcp:stop-tcp-server-thread)
;; => :STOPPED
```

### Response
#### Success Response (200)
Returns the thread object upon successful start, T if running, or :STOPPED upon completion.

#### Response Example
```
#<THREAD "mcp-tcp-server">, 12345
```
```

--------------------------------

### Run cl-mcp with Stdio Transport

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Starts the cl-mcp server using the stdio transport. This command is executed via the 'ros' tool.

```bash
ros run -s cl-mcp -e "(cl-mcp:run :transport :stdio)"
```

--------------------------------

### MCP Client Configuration

Source: https://context7.com/cl-ai-project/cl-mcp/llms.txt

Provides configuration examples for MCP clients (like Claude Code) to connect to the cl-mcp server via HTTP or stdio.

```APIDOC
## MCP Client Configuration

### Description
Provides configuration examples for MCP clients (like Claude Code) to connect to the cl-mcp server via HTTP or stdio.

### Method
Configuration File Snippet

### Endpoint
N/A (Configuration)

### Parameters
None

### Request Example
```json
// HTTP Transport Configuration
{
  "mcpServers": {
    "cl-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

// Stdio Transport Configuration (Subprocess)
{
  "mcpServers": {
    "cl-mcp": {
      "command": "ros",
      "args": ["run", "-l", "cl-mcp", "-e", "(cl-mcp:run)"],
      "env": {
        "MCP_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}
```

### Response
N/A (Configuration Snippets)
```

--------------------------------

### Evaluate Common Lisp Code with repl-eval Tool (JSON-RPC)

Source: https://context7.com/cl-ai-project/cl-mcp/llms.txt

Demonstrates the usage of the 'repl-eval' tool via JSON-RPC to evaluate Common Lisp code. Examples show evaluating simple expressions, code with package context and print limits, and handling timeouts. The tool returns results as structured content, including text output and optional object IDs.

```json
// Request: Evaluate a simple expression
{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"repl-eval","arguments":{"code":"(+ 1 2 3)"}}}

// Response
{"result":{"content":[{"type":"text","text":"6"}],"stdout":"","stderr":""}}

// Request: Evaluate with package context and print limits
{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"repl-eval","arguments":{
   "code":"(loop for i from 1 to 100 collect i)",
   "package":"CL-USER",
   "print_length":5,
   "print_level":2
 }}}

// Response (truncated output)
{"result":{"content":[{"type":"text","text":"(1 2 3 4 5 ...)"}] ,
           "result_object_id":42}}

// Request: Evaluate with timeout
{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"repl-eval","arguments":{
   "code":"(loop)",
   "timeout_seconds":2
 }}}

// Response (timed out)
{"result":{"content":[{"type":"text","text":"Evaluation timed out after 2.00 seconds"}]}}
```

--------------------------------

### Get Project Root Path

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/prompts/repl-driven-development.md

Retrieve project information, including the project root, using `fs-get-project-info`. This is essential for constructing absolute paths and ensuring reliable file operations.

```json
{
  "command": "fs-get-project-info"
}
```

--------------------------------

### Set Project Root with fs-set-project-root

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/prompts/repl-driven-development.md

Configures the root directory for the current project. This is a fundamental step at the start of a session to ensure all subsequent file operations and tool interactions are relative to the correct project context.

```common-lisp
(fs-set-project-root ".")
```

--------------------------------

### Start cl-mcp TCP Server (Development)

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Starts the cl-mcp server using the TCP transport in a separate thread on port 12345. This is primarily for development purposes.

```lisp
;; TCP server (development)
(cl-mcp:start-tcp-server-thread :port 12345)
```

--------------------------------

### Loading the System

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Command to load the cl-mcp system using Quicklisp.

```APIDOC
## Loading the System

### Description
Loads the cl-mcp system using the Quicklisp package manager.

### Method
Lisp REPL command

### Endpoint
N/A

### Parameters
None

### Request Example
```lisp
(ql:quickload :cl-mcp)
```

### Response
N/A

### Success Response (200)
N/A

### Response Example
N/A
```

--------------------------------

### Key Design Patterns: Token-Efficient Reading

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Explains the token-efficient reading approach using `lisp-read-file` with options like `collapsed=true` and `name_pattern`.

```APIDOC
## Key Design Patterns: Token-Efficient Reading

### Description
Details the token-efficient reading strategy employed by `lisp-read-file`. When `collapsed=true`, only function signatures are displayed (e.g., `(defun foo (args) ...)`). The `name_pattern` regex can be used to expand specific definitions. A default line limit of 2000 is applied for raw reads to manage performance.

### Method
`lisp-read-file` tool parameters

### Endpoint
N/A

### Parameters
#### Request Body (lisp-read-file)
- **method** (string) - `tools/call`
- **params** (object) - 
  - **toolName** (string) - `lisp-read-file`
  - **args** (object) - 
    - **path** (string) - The path to the file to read.
    - **collapsed** (boolean, optional) - If `true`, only shows signatures.
    - **name_pattern** (string, optional) - A regex to filter definitions.
    - **limit** (integer, optional) - Maximum number of lines to read.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "toolName": "lisp-read-file",
    "args": {
      "path": "src/utils.lisp",
      "collapsed": true,
      "name_pattern": "^my-utility-"
    }
  }
}
```

### Response
#### Success Response (200)
- **result** (string) - The read content, potentially collapsed or filtered.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 12,
  "result": "(defun my-utility-a (x) ...)\n(defun my-utility-b (y) ...)"
}
```
```

--------------------------------

### Key Design Patterns: Project Root Synchronization

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

No description

--------------------------------

### Start TCP Transport Server in Common Lisp

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/README.md

Loads the cl-mcp library and starts a TCP transport server on a specified port in a new thread. This allows clients to connect via TCP to the MCP server.

```common-lisp
(ql:quickload :cl-mcp)

;; Start TCP transport on port 12345 in a new thread.
(cl-mcp:start-tcp-server-thread :port 12345)
```

--------------------------------

### Start TCP Server for Direct Socket Connections (Common Lisp)

Source: https://context7.com/cl-ai-project/cl-mcp/llms.txt

Starts a TCP server in a separate thread, allowing direct socket connections for MCP clients. The server listens on a specified port. You can check if the server is running using 'cl-mcp:tcp-server-running-p' and stop it with 'cl-mcp:stop-tcp-server-thread'.

```common-lisp
;; Start TCP server on port 12345
(cl-mcp:start-tcp-server-thread :port 12345)
;; => #<THREAD "mcp-tcp-server">, 12345

;; Check if server is running
(cl-mcp:tcp-server-running-p)
;; => T

;; Stop the server
(cl-mcp:stop-tcp-server-thread)
;; => :STOPPED
```

--------------------------------

### Load Common Lisp System with Quicklisp

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Loads the cl-mcp system using Quicklisp's quickload function. This is a prerequisite for running the server or other commands.

```lisp
(ql:quickload :cl-mcp)
```

--------------------------------

### Read and Write Files in Project Sandbox (fs-read-file, fs-write-file)

Source: https://context7.com/cl-ai-project/cl-mcp/llms.txt

The `fs-read-file` and `fs-write-file` tools allow reading from and writing to files within the project sandbox. `fs-read-file` supports specifying an offset and limit for reading partial content, while `fs-write-file` can create new files using relative paths.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fs-read-file",
    "arguments": {
      "path": "README.md",
      "offset": 0,
      "limit": 1000
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "fs-write-file",
    "arguments": {
      "path": "docs/notes.md",
      "content": "# Development Notes\n\nThis file contains notes..."
    }
  }
}
```

--------------------------------

### File System Write API

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/README.md

Write text content to a file located under the project root. Directories will be automatically created if they do not exist.

```APIDOC
## POST /tools/call

### Description
Writes specified text content to a file. The file path must be relative to the project root. If the necessary directories do not exist, they will be created automatically. Writes outside the project root are rejected.

### Method
POST

### Endpoint
/tools/call

### Parameters
#### Request Body
- **name** (string) - Required - The name of the tool to call, which is `fs-write-file` for this operation.
- **arguments** (object) - Required - An object containing the arguments for the `fs-write-file` tool:
  - **path** (string) - Required - The path to the file, relative to the project root.
  - **content** (string) - Required - The text content to write to the file.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "fs-write-file",
    "arguments": {
      "path": "output/log.txt",
      "content": "Log entry: operation successful."
    }
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the write operation (e.g., "ok").

#### Response Example
```json
{
  "result": {
    "status": "ok"
  }
}
```
```

--------------------------------

### Loading Common Lisp Systems

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Always load Common Lisp systems using `ql:quickload` before operating on their symbols. Use package-qualified symbols for clarity and to avoid ambiguity.

```common-lisp
(ql:quickload :system-name)
(symbol-function 'cl-mcp:run)
```

--------------------------------

### fs-set-project-root Tool

Source: https://context7.com/cl-ai-project/cl-mcp/llms.txt

Synchronizes the server's project root with the client's working directory. This is essential for correct file path resolution.

```APIDOC
## fs-set-project-root Tool

### Description
Synchronize the server's project root with the client's working directory. This ensures that file operations are performed relative to the correct project context.

### Method
POST

### Endpoint
/tools/call

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC version, must be "2.0".
- **id** (integer) - Required - Unique identifier for the request.
- **method** (string) - Required - Must be "tools/call".
- **params** (object) - Required - Parameters for the tool call.
  - **name** (string) - Required - Must be "fs-set-project-root".
  - **arguments** (object) - Required - Arguments for the fs-set-project-root tool.
    - **path** (string) - Required - The absolute path to the new project root directory.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fs-set-project-root",
    "arguments": {
      "path": "/home/user/my-project"
    }
  }
}
```

### Response
#### Success Response (200)
- **result** (object)
  - **info** (object) - Information about the project root change.
    - **project_root** (string) - The new project root path.
    - **cwd** (string) - The current working directory.
    - **previous_root** (string) - The previous project root path.
    - **status** (string) - A status message indicating the result of the operation.

#### Response Example
```json
{
  "result": {
    "info": {
      "project_root": "/home/user/my-project/",
      "cwd": "/home/user/my-project/",
      "previous_root": "(not set)",
      "status": "Project root set to /home/user/my-project/"
    }
  }
}
```
```

--------------------------------

### Describe Symbols with code-describe

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/prompts/repl-driven-development.md

Obtain detailed information about symbols, such as function signatures, using code-describe. This is useful for verifying function definitions and understanding their expected arguments and return values.

```json
{"symbol": "my-package:my-function"}
```

--------------------------------

### run-tests

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/README.md

Executes tests for a specified ASDF system and returns structured results.

```APIDOC
## POST /run-tests

### Description
Run tests for a system and return structured results with pass/fail counts and failure details.

### Method
POST

### Endpoint
/run-tests

### Parameters
#### Request Body
- **system** (string) - Required - The ASDF system name to test (e.g., `"my-project/tests"`).
- **framework** (string) - Optional - Force a specific test framework (`"rove"`, `"fiveam"`, or `"auto"` for auto-detection).
- **test** (string) - Optional - Run only a specific test by its fully qualified name (e.g., `"my-package::my-test-name"`).

### Request Example
```json
{
  "system": "cl-mcp/tests/clhs-test",
  "test": "cl-mcp/tests/clhs-test::clhs-lookup-symbol-returns-hash-table"
}
```

### Response
#### Success Response (200)
- **passed** (integer) - Number of tests that passed.
- **failed** (integer) - Number of tests that failed.
- **pending** (integer) - Number of tests that were pending or skipped (Rove only).
- **framework** (string) - The test framework used (`"rove"` or `"asdf"`).
- **duration_ms** (integer) - The execution time of the tests in milliseconds.
- **failed_tests** (array) - An array containing detailed information about each failing test, including `test_name`, `description`, `form`, `values`, `reason`, and `source`.

#### Response Example
```json
{
  "passed": 10,
  "failed": 0,
  "pending": 1,
  "framework": "rove",
  "duration_ms": 150,
  "failed_tests": []
}
```
```

--------------------------------

### Configuring Claude Code with MCP Server (HTTP)

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Configure Claude Code to connect to the CL-MCP HTTP server by specifying the `mcpServers` in `~/.claude/settings.json` or a project `.mcp.json`. This example uses the default port 3000.

```json
{
  "mcpServers": {
    "cl-mcp": {
      "type": "url",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```

--------------------------------

### Run a Single Test with run-tests Tool

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/prompts/repl-driven-development.md

Execute a specific test within a system using the run-tests tool. This requires the test package to be loaded first, either by running system-level tests or explicitly loading it.

```json
{"name": "run-tests", "arguments": {"system": "my-system/tests", "test": "my-system/tests::my-specific-test"}}
```

--------------------------------

### MCP Protocol Initialize Handshake

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Details the MCP initialize handshake, including supported protocol versions for negotiation.

```APIDOC
## MCP Protocol Initialize Handshake

### Description
Describes the initialization handshake process for the MCP protocol, which includes negotiating the protocol version between the client and server. Supported versions are 2025-06-18, 2025-03-26, and 2024-11-05.

### Method
JSON-RPC 2.0 message

### Endpoint
N/A

### Parameters
#### Request Body
- **method** (string) - `initialize`
- **params** (object) - 
  - **protocolVersion** (string) - The client's supported protocol version.
  - **rootPath** (string, optional) - The root path of the project.
  - **rootUri** (string, optional) - The root URI of the project.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "rootPath": "/path/to/project",
    "rootUri": "file:///path/to/project"
  }
}
```

### Response
#### Success Response (200)
- **result** (object) - 
  - **protocolVersion** (string) - The negotiated protocol version.
  - **capabilities** (object) - Server capabilities.
#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "completionProvider": {"resolveProvider": true},
      "hoverProvider": true,
      "definitionProvider": true,
      "referencesProvider": true,
      "documentSymbolProvider": true,
      "workspaceSymbolProvider": true,
      "codeActionProvider": true,
      "renameProvider": true,
      "documentFormattingProvider": true,
      "documentRangeFormattingProvider": true,
      "executeCommandProvider": {"commands": ["clmcp.eval.code", "clmcp.eval.file", "clmcp.eval.region"]}
    }
  }
}
```
```

--------------------------------

### Run Stdio Transport Loop in Common Lisp

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/README.md

Starts a minimal stdio loop for the cl-mcp server, processing JSON-RPC requests line by line. Requires the MCP_PROJECT_ROOT environment variable to be set.

```bash
# With environment variable
export MCP_PROJECT_ROOT=$(pwd)
ros run -s cl-mcp -e "(cl-mcp:run :transport :stdio)"
```

--------------------------------

### fs-read-file / fs-write-file Tools

Source: https://context7.com/cl-ai-project/cl-mcp/llms.txt

Tools for reading from and writing to files within the project sandbox. Supports specifying paths, offsets, limits, and content.

```APIDOC
## fs-read-file / fs-write-file Tools

### Description
Read and write files within the project sandbox. `fs-read-file` allows specifying offset and limit for partial reads, while `fs-write-file` can create new files or overwrite existing ones.

### Method
POST

### Endpoint
/tools/call

### Parameters
#### Request Body (for both tools)
- **jsonrpc** (string) - Required - JSON-RPC version, must be "2.0".
- **id** (integer) - Required - Unique identifier for the request.
- **method** (string) - Required - Must be "tools/call".
- **params** (object) - Required - Parameters for the tool call.
  - **name** (string) - Required - Must be "fs-read-file" or "fs-write-file".
  - **arguments** (object) - Required - Arguments for the file system tool.
    - **path** (string) - Required - Path to the file.
    - **offset** (integer) - Optional - For `fs-read-file`, the starting byte offset.
    - **limit** (integer) - Optional - For `fs-read-file`, the maximum number of bytes to read.
    - **content** (string) - Required for `fs-write-file` - The content to write to the file.

### Request Example (Read File)
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fs-read-file",
    "arguments": {
      "path": "README.md",
      "offset": 0,
      "limit": 1000
    }
  }
}
```

### Request Example (Write File)
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "fs-write-file",
    "arguments": {
      "path": "docs/notes.md",
      "content": "# Development Notes\n\nThis file contains notes..."
    }
  }
}
```

### Response
#### Success Response (200)
- **result** (object)
  - For `fs-read-file`:
    - **content** (array) - Array of text objects representing the file content.
    - **path** (string) - The path of the file read.
    - **offset** (integer) - The offset used for reading.
    - **limit** (integer) - The limit used for reading.
  - For `fs-write-file`:
    - **success** (boolean) - Indicates if the write operation was successful.
    - **path** (string) - The path of the file written.
    - **bytes** (integer) - The number of bytes written.

#### Response Example (Read File)
```json
{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# cl-mcp\n..."
      }
    ],
    "path": "README.md",
    "offset": 0,
    "limit": 1000
  }
}
```

#### Response Example (Write File)
```json
{
  "result": {
    "success": true,
    "path": "docs/notes.md",
    "bytes": 45
  }
}
```
```

--------------------------------

### Lookup Symbols and Sections in Common Lisp HyperSpec (CLHS)

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/README.md

Queries the Common Lisp HyperSpec for a given symbol or section number. It can fetch the URL and optionally include extracted text content from a local installation. If not found locally, it attempts to use a remote URL.

```CommonLisp
;; Example usage (conceptual, actual function call would be via a tool interface)
;; (clhs-lookup :query "loop")
;; (clhs-lookup :query "22.3" :include_content false)
```

--------------------------------

### Linting

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Commands for linting Common Lisp files using `mallet` before committing changes.

```APIDOC
## Linting

### Description
Ensures code quality by linting Common Lisp files with `mallet` before committing. This command can be used to lint individual files or all source files in the project.

### Method
Shell commands

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
# Lint a single file
mallet src/http.lisp

# Lint all source files
mallet src/*.lisp
```

### Response
N/A

### Success Response (200)
N/A

### Response Example
N/A
```

--------------------------------

### Common Lisp Tool Selection Decision Tree (Text)

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/prompts/repl-driven-development.md

A decision tree to guide developers in selecting the appropriate Common Lisp tool based on the task at hand. It categorizes tasks into SEARCH/EXPLORE, READ, EXECUTE, EDIT, and REFERENCE, providing specific tool recommendations for each sub-task. This helps ensure the correct and most efficient tool is used for different development activities.

```text
What do you need to do?
│
├─ SEARCH/EXPLORE
│   ├─ Pattern search (project-wide) ──→ clgrep-search
│   ├─ Symbol lookup (system loaded) ──→ code-find, code-describe
│   └─ Find callers/references ────────→ code-find-references (loaded) or clgrep-search
│
├─ READ
│   ├─ .lisp/.asd file ────→ lisp-read-file (collapsed=true, then name_pattern)
│   └─ Other files ────────→ fs-read-file
│
├─ EXECUTE
│   ├─ Test expression ────→ repl-eval
│   └─ Inspect result ─────→ inspect-object (use result_object_id)
│
├─ EDIT
│   ├─ Existing .lisp ─────→ lisp-edit-form (ALWAYS)
│   └─ New file ───────────→ fs-write-file (minimal), then lisp-edit-form
│
└─ REFERENCE
    └─ CL language spec ───→ clhs-lookup (symbol or section number)
```

--------------------------------

### Tools API Dispatch

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Details the `tools/list` and `tools/call` methods for interacting with MCP tools.

```APIDOC
## Tools API Dispatch

### Description
Allows clients to discover available tools using `tools/list` and execute them using `tools/call`. This is the primary mechanism for AI agents to interact with the Common Lisp environment.

### Method
JSON-RPC 2.0 method calls

### Endpoint
N/A

### Parameters
#### Request Body (tools/list)
- **method** (string) - `tools/list`

#### Request Body (tools/call)
- **method** (string) - `tools/call`
- **params** (object) - 
  - **toolName** (string) - The name of the tool to call.
  - **args** (object) - Arguments for the tool.

### Request Example
```json
// List available tools
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

// Call a tool (e.g., REPL evaluation)
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "toolName": "repl/eval",
    "args": {
      "code": "(+ 1 2)",
      "package": "KEYWORD"
    }
  }
}
```

### Response
#### Success Response (200) for `tools/list`
- **result** (array) - A list of available tool names.

#### Success Response (200) for `tools/call`
- **result** (object) - The result of the tool execution.

#### Response Example (`tools/list`)
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": [
    "repl/eval",
    "fs/read-file",
    "fs/write-file",
    "code/find-definitions"
  ]
}
```

#### Response Example (`tools/call` - repl/eval)
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "value": 3,
    "print": "3"
  }
}
```
```

--------------------------------

### Verify Project Root with fs-get-project-info

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/prompts/repl-driven-development.md

Ensures the current project root is correctly set, which is crucial for file operations and resolving path-related errors. This function helps diagnose issues where file operations might fail due to an incorrect project context.

```common-lisp
(fs-get-project-info)
```

--------------------------------

### REPL Evaluation API

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/README.md

Evaluate Common Lisp code and retrieve results, standard output, and standard error.

```APIDOC
## POST /tools/call

### Description
Evaluates one or more s-expressions in a specified package and returns the last value, along with any standard output or error streams. It supports optional parameters for controlling evaluation depth, timeouts, and output truncation.

### Method
POST

### Endpoint
/tools/call

### Parameters
#### Request Body
- **name** (string) - Required - The name of the tool to call, which is `repl-eval` for this operation.
- **arguments** (object) - Required - An object containing the arguments for the `repl-eval` tool:
  - **code** (string) - Required - One or more s-expressions to evaluate.
  - **package** (string) - Optional - The package in which to evaluate the code. Defaults to `CL-USER`.
  - **print_level** (integer|null) - Optional - Binds `*print-level*` during evaluation.
  - **print_length** (integer|null) - Optional - Binds `*print-length*` during evaluation.
  - **timeout_seconds** (number|null) - Optional - The maximum number of seconds to allow for evaluation before aborting.
  - **max_output_length** (integer|null) - Optional - The maximum number of characters to truncate `content`, `stdout`, or `stderr` to.
  - **safe_read** (boolean|null) - Optional - If `true`, disables `*read-eval*` while reading forms.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "repl-eval",
    "arguments": {
      "code": "(+ 1 2)"
    }
  }
}
```

### Response
#### Success Response (200)
- **content** (array) - The last evaluated value as text items.
- **stdout** (string) - Concatenated standard output from the evaluation.
- **stderr** (string) - Concatenated standard error from the evaluation.
- **result_object_id** (integer|null) - An ID for non-primitive results, usable with `inspect-object`.
- **error_context** (object|null) - Structured error information if an error occurred.

#### Response Example
```json
{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "3"
      }
    ]
  }
}
```
```

--------------------------------

### code-describe Tool

Source: https://context7.com/cl-ai-project/cl-mcp/llms.txt

Retrieves metadata for a given symbol, including its type, argument list, and documentation.

```APIDOC
## POST /tools/call (code-describe)

### Description
Get symbol metadata including type, arglist, and documentation.

### Method
POST

### Endpoint
/tools/call

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC protocol version.
- **id** (integer) - Required - Unique identifier for the request.
- **method** (string) - Required - The method to call, must be "tools/call".
- **params** (object) - Required - Parameters for the tools/call method.
  - **name** (string) - Required - The name of the tool to call, must be "code-describe".
  - **arguments** (object) - Required - Arguments for the code-describe tool.
    - **symbol** (string) - Required - The symbol to describe (e.g., "cl-mcp:repl-eval").

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "code-describe",
    "arguments": {
      "symbol": "cl-mcp:repl-eval"
    }
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - JSON-RPC protocol version.
- **id** (integer) - The ID of the request.
- **result** (object) - The result of the tool call.
  - **name** (string) - The name of the symbol.
  - **type** (string) - The type of the symbol (e.g., "function").
  - **arglist** (string) - The argument list of the symbol.
  - **documentation** (string) - The documentation string for the symbol.
  - **path** (string) - The file path where the symbol is defined.
  - **line** (integer) - The line number where the symbol is defined.

#### Response Example
```json
{
  "result": {
    "name": "CL-MCP:REPL-EVAL",
    "type": "function",
    "arglist": "(INPUT &KEY (PACKAGE *DEFAULT-EVAL-PACKAGE*) (PRINT-LEVEL NIL) (PRINT-LENGTH NIL) (TIMEOUT-SECONDS NIL) (MAX-OUTPUT-LENGTH NIL) (SAFE-READ NIL))",
    "documentation": "Evaluate INPUT (a string of one or more s-expressions) in PACKAGE...",
    "path": "src/repl.lisp",
    "line": 211
  }
}
```
```

--------------------------------

### Key Design Patterns: Package-Inferred System

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Explanation of the package-inferred system design pattern used in cl-mcp, where each file defines its own package.

```APIDOC
## Key Design Patterns: Package-Inferred System

### Description
Describes the `package-inferred-system` approach used in cl-mcp, where each source file typically defines its own Common Lisp package. This pattern simplifies system management by associating packages directly with their respective files. New files should be added to `cl-mcp.asd` dependencies, and symbols intended for external use must be explicitly exported in `main.lisp`.

### Method
ASDF system definition

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
N/A

### Success Response (200)
N/A

### Response Example
N/A
```

--------------------------------

### fs-list-directory Tool

Source: https://context7.com/cl-ai-project/cl-mcp/llms.txt

Lists the contents of a directory within the project sandbox, with options to filter hidden files and build artifacts.

```APIDOC
## fs-list-directory Tool

### Description
List directory contents with filtering for hidden and build artifacts. Allows specifying a path to list.

### Method
POST

### Endpoint
/tools/call

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC version, must be "2.0".
- **id** (integer) - Required - Unique identifier for the request.
- **method** (string) - Required - Must be "tools/call".
- **params** (object) - Required - Parameters for the tool call.
  - **name** (string) - Required - Must be "fs-list-directory".
  - **arguments** (object) - Required - Arguments for the fs-list-directory tool.
    - **path** (string) - Required - The path of the directory to list. Use "." for the project root.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fs-list-directory",
    "arguments": {
      "path": "."
    }
  }
}
```

### Response
#### Success Response (200)
- **result** (object)
  - **entries** (array) - An array of objects, each representing a file or directory entry.
    - **name** (string) - The name of the entry.
    - **type** (string) - The type of the entry ("file" or "directory").
  - **path** (string) - The path of the directory that was listed.

#### Response Example
```json
{
  "result": {
    "entries": [
      {
        "name": "src",
        "type": "directory"
      },
      {
        "name": "tests",
        "type": "directory"
      },
      {
        "name": "README.md",
        "type": "file"
      },
      {
        "name": "cl-mcp.asd",
        "type": "file"
      }
    ],
    "path": "."
  }
}
```
```

--------------------------------

### Set Project Root Directory (fs-set-project-root)

Source: https://context7.com/cl-ai-project/cl-mcp/llms.txt

The `fs-set-project-root` tool synchronizes the server's project root with the client's current working directory. This ensures that file operations are performed relative to the correct project location, providing feedback on the status and previous root.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fs-set-project-root",
    "arguments": {
      "path": "/home/user/my-project"
    }
  }
}
```

--------------------------------

### Environment Variables

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/CLAUDE.md

Essential environment variables for configuring cl-mcp, including project root and logging level.

```APIDOC
## Environment Variables

### Description
Configures the cl-mcp server's behavior through environment variables. `MCP_PROJECT_ROOT` is critical for file operations, and `MCP_LOG_LEVEL` controls the verbosity of logs.

### Method
Environment variable export

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
# Project root (critical for file operations)
export MCP_PROJECT_ROOT=/path/to/project

# Logging level
export MCP_LOG_LEVEL=debug  # debug|info|warn|error
```

### Response
N/A

### Success Response (200)
N/A

### Response Example
N/A
```

--------------------------------

### Common Lisp Development Loop Diagram (Text)

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/prompts/repl-driven-development.md

A visual representation of the iterative Common Lisp development process. It illustrates the flow from exploring code and experimenting in the REPL, to refining and persisting changes, and finally verifying the results. The diagram highlights the cyclical nature of development, where issues found during verification can lead back to earlier stages for correction.

```text
    ┌─────────────────────────────────────┐
    │                                     │
    ▼                                     │
EXPLORE ──→ EXPERIMENT ──→ REFINE ────────┘
    │              │
    │              ▼ (when correct)
    │          PERSIST ──→ VERIFY
    │              │
    └──────────────┘ (if issues found)
```

--------------------------------

### Python TCP Client for MCP Initialization

Source: https://github.com/cl-ai-project/cl-mcp/blob/main/README.md

A Python script to send an 'initialize' request to an MCP server via TCP. It takes host, port, method, and ID as command-line arguments.

```bash
python3 scripts/client_init.py --host 127.0.0.1 --port 12345 --method initialize --id 1
```