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 許可證。