Lisp MCP Server

🚀 lisp-mcp-server

このプロジェクトは、Common Lisp用の最小限のModel Context Protocol (MCP)サーバーです。標準入出力またはTCPを介した改行区切りのJSON‑RPC 2.0トランスポート、小規模なプロトコル層（初期化、ピング、ツールのリスト、ツールの呼び出し）、およびフォームを評価して最後の値を返すREPLツールを提供します。このリポジトリは意図的に小規模で、テスト駆動開発で設計されており、エディタやエージェントクライアントがMCPを介してCommon Lispの開発を推進するために設計されています。

✨ 主な機能

• JSON‑RPC 2.0のリクエスト/レスポンスのフレーミング（1行に1メッセージ）
• 機能発見を伴うMCP初期化ハンドシェイク
• 1つの組み込みツール repl-eval を持つツールAPI
• トランスポート: :stdio と :tcp
• 環境変数によるレベル制御付きの構造化JSONログ
• ASDFの test-op を通して接続されたRoveテストスイート

📚 詳細ドキュメント

プロトコルサポート

• 認識されるプロトコルバージョン: 2025-06-18, 2025-03-26, 2024-11-05
  • initialize 時に、クライアントの protocolVersion がサポートされている場合はそれがエコーバックされます。それ以外の場合はサーバーの推奨バージョンが選択されます。

要件

• SBCL 2.x（SBCL 2.5.xで開発）
• Quicklisp（依存関係管理）
• 依存関係（ASDF/Quicklisp経由）: alexandria, yason, usocket, bordeaux-threads, rove（テスト用）

注: このリポジトリは現在、JSON処理に yason を使用しています。

🚀 クイックスタート

既存の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)))

または、最小限の標準入出力ループを実行することもできます（1リクエストにつき1行の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

このブリッジは接続タイムアウトを制限していますが、接続後は読み取りタイムアウトを無効にするため、標準入力が閉じられるまで無期限にアイドル状態を維持できます。

💻 使用例

基本的な使用法

repl-eval ツール

1つまたは複数のフォームを評価し、最後の値をテキスト項目として返します。

入力スキーマ（JSON）:

• code（文字列、必須）: 1つまたは複数の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"}]}}

🔧 技術詳細

ロギング

• 構造化JSONの行ログを *error-output* に出力します。
• 環境変数 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ブリッジのアイドル時の生存と標準入力が閉じられたときのクリーンな終了

注: テストを実行すると、FASLが ~/.cache/... にコンパイルされます。環境がそこに書き込みを許可していることを確認するか、SBCLのキャッシュディレクトリを適切に設定してください。

プロジェクト構成

• 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のキャッシュパスを再構成してください。
• 標準入出力に出力がない: プロトコルは1行に1つのJSON‑RPCメッセージであることを忘れないでください。各リクエストは改行で終わる必要があり、サーバーは正確に1行で応答します（通知の場合は何も返さないこともあります）。

ロードマップ

• 条件タイプとしてのエラー分類をJSON‑RPCエラーにマッピングする
• 追加のツール（読み取り専用ファイルアクセス、シンボル検索など）
• SBCL/macOS/LinuxのためのCI（GitHub Actions）マトリックス

📄 ライセンス

MIT