Lisp MCP Server

🚀 lisp-mcp-server

lisp-mcp-server 是一个为 Common Lisp 设计的最小化模型上下文协议（MCP）服务器。它通过标准输入输出或 TCP 提供以换行符分隔的 JSON-RPC 2.0 传输，包含一个小型协议层（初始化、ping、工具/列表、工具/调用），以及一个 REPL 工具，用于计算表达式并返回最后一个值。该项目专为编辑器/代理客户端通过 MCP 驱动 Common Lisp 开发而设计。

🚀 快速开始

可以从现有的 REPL 中加载并运行该服务器：

(ql:quickload :lisp-mcp-server)
(asdf:load-system :lisp-mcp-server)

;; 在临时端口上启动 TCP 传输，并打印所选端口
(lisp-mcp-server:run :transport :tcp
                     :port 12345
                     :accept-once nil
                     :on-listening (lambda (p)
                                     (format t "~&port=~A~%" p)))

或者运行一个最小化的标准输入输出循环（每个请求一行 JSON-RPC）：

(lisp-mcp-server:run :transport :stdio)

使用附带的客户端进行测试

• Python TCP 一次性客户端（初始化）：

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

• 标准输入输出与 TCP 桥接（将编辑器的标准输入输出连接到 TCP 服务器）：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | \
  python3 scripts/stdio_tcp_bridge.py --host 127.0.0.1 --port 12345

该桥接器使用有限的连接超时时间，但在连接后会禁用读取超时，因此它可以无限期保持空闲状态（直到标准输入关闭）。

✨ 主要特性

• JSON-RPC 2.0 请求/响应框架（每行一条消息）
• 支持能力发现的 MCP 初始化握手
• 工具 API，包含一个内置工具：repl-eval
• 传输方式：:stdio 和 :tcp
• 通过环境变量进行日志级别控制的结构化 JSON 日志
• 通过 ASDF test-op 连接的 Rove 测试套件

📚 详细文档

协议支持

• 支持的协议版本：2025-06-18、2025-03-26、2024-11-05
  • 在 initialize 时，如果客户端的 protocolVersion 受支持，则会原样返回；否则，将选择服务器首选的版本。

工具

repl-eval

计算一个或多个表达式，并将最后一个值作为文本项返回。

输入模式（JSON）：

• code（字符串，必需）：一个或多个 s 表达式
• package（字符串，可选）：要在其中计算的包（默认为 CL-USER）
• printLevel（整数或 null）：绑定 *print-level*
• printLength（整数或 null）：绑定 *print-length*

示例 JSON-RPC 请求：

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

响应（节选）：

{"result":{"content":[{"type":"text","text":"3"}]}}

日志记录

• 向 *error-output* 输出结构化的 JSON 行日志。
• 通过环境变量 MCP_LOG_LEVEL 控制日志级别，可选值为：debug、info、warn、error。

示例：

MCP_LOG_LEVEL=debug sbcl --eval '(ql:quickload :lisp-mcp-server)' ...

运行测试

本项目使用 Rove 和 ASDF 的 test-op。

在带有 Quicklisp 的 REPL 中执行以下操作：

(asdf:load-asd #P"lisp-mcp-server.asd")
(asdf:test-system "lisp-mcp-server")

测试覆盖范围：

• 版本/API 表面合理性
• REPL 计算语义（启用读取器计算）
• 协议握手（initialize、ping、工具列表/调用）
• RPC 调度/结果的日志记录
• TCP 服务器接受/响应（以换行符分隔的 JSON）
• 标准输入输出与 TCP 桥接器在空闲时保持活动状态，并在标准输入关闭时正常退出

项目布局

• src/ — 包含包、日志记录、REPL、协议、TCP 和运行入口点
• tests/ — 由 ASDF test-op 调用的 Rove 测试套件
• scripts/ — 辅助客户端和标准输入输出与 TCP 桥接器
• lisp-mcp-server.asd — 主系统和测试系统（将 test-op 委托给 Rove）

安全注意事项

• 读取器和运行时计算均已启用。请将其视为受信任的本地开发工具；不可信的输入可能会在主机 Lisp 映像中执行任意代码。
• 如果计划在受信任的使用场景之外使用，请添加允许列表、资源/时间限制和输出上限。

故障排除

• 桥接器在闲置几秒钟后退出：确保使用的是附带的 scripts/stdio_tcp_bridge.py（它在连接后禁用读取超时），并且标准输入保持打开状态。
• 测试期间编译 FASL 时出现权限错误：允许在 ~/.cache 下写入，或者重新配置 SBCL 的缓存路径。
• 标准输入输出无输出：请记住协议是每行一条 JSON-RPC 消息。每个请求必须以换行符结尾，服务器将精确地以一行进行响应（通知则无响应）。

路线图

• 将错误分类作为条件类型映射到 JSON-RPC 错误
• 添加额外的工具（只读文件访问、符号查找等）
• 为 SBCL/macOS/Linux 设置 CI（GitHub Actions）矩阵

📦 安装指南

要求

• SBCL 2.x（使用 SBCL 2.5.x 开发）
• Quicklisp（用于依赖管理）
• 依赖项（通过 ASDF/Quicklisp）：alexandria、yason、usocket、bordeaux-threads、rove（测试用）

注意：该仓库目前使用 yason 处理 JSON。

📄 许可证

本项目采用 MIT 许可证。