利斯普-mcp
项目介绍
【技术文档摘要】
**注意：当前分支尚未稳定支持自动启动容器。此问题将会得到修正，但目前更可靠的方法是通过 skewed-emacs README 中的“容器化运行”部分来启动容器化的 Lisply-MCP 环境。容器启动后，Claude Desktop 将根据下面的示例配置连接到它们。
基于Lisp及其类似环境的模型上下文协议（MCP）中间件
该项目是一个 模型上下文协议（MCP） 中间件，它使 大型语言模型（LLMs） 能够通过一种称为 Lisply 的轻量级协议与基于 Lisp 的开发和运行时环境进行交互。
这是为谁准备的？
- 对Lisp感兴趣的AI从业者
- 对AI感兴趣的Lisp从业者
- 对神经符号编程感兴趣的任何人
- 对CAD自动化和知识工程感兴趣的机械/土木工程师和设计师
- 来自各行各业的捣鼓者、干预者和篡改者
它的目的是什么？
Lisply-MCP 中间件连接了能够支持 MCP 的 AI Agent 程序或 MCP 客户端，例如 ClaudeDesktop，到支持 REPL（读取-求值-打印循环）的基于 Lisp 的系统。这种连接旨在促进AI辅助的符号编程，有时也被称为 神经符号编程。我们创造了术语“Lisply”，以指代一种轻量级协议，几乎任何Lisp类系统都可以实现该协议，使其与这个 Lisply-MCP 中间件兼容。
其理念是，LLM 将能够生成并评估任意的 Lisp 表达式，包括创建、编译、加载和测试整个文件和项目。
快速入门
遵循 skewed-emacs README 中的“容器化运行”部分。
这将为您提供一个 Docker Compose 设置，其中包括预配置的 Lisply-MCP 容器化版本。
快速开始
以下步骤将帮助您快速启动并运行具有最小默认配置和作为 Docker 容器运行的默认公共 Common Lisp 后端。请参阅下面的主要内容以获取更多背景信息和详细的配置选项。
1. 安装
- 安装 Node.js（推荐版本 18+）。如果在 Windows 上，可以直接在 Windows 或 WSL 中安装。
- 在安装 Node.js 的同一主机上安装 Docker（推荐版本 20+）。
- 将此
lisply-mcp仓库克隆到您的 MCP 能力的 AI Agent（如 Claude Desktop）可以访问的位置。
2. 配置您的 MCP 能力的 AI Agent
编辑或创建您的 AI Agent 的配置文件，如下所示。对于 Claude Desktop，配置文件通常位于：
/mnt/c/Users/<user>/AppData/Roaming/Claude/claude_desktop_config.json
或者
c:\Users\<user>\AppData\Roaming\Claude\claude_desktop_config.json
在下面的示例中，用正确的路径替换 /path/to/cloned/，指向从克隆的仓库中的 ./scripts/mcp-wrapper.js 文件：
{
"mcpServers": {
"gendl-ccl": {
"command": "node",
"args": [
"/path/to/cloned/lisply-mcp/scripts/mcp-wrapper.js",
"--server-name", "gendl-ccl",
"--http-port", "9080"
]
}
},
{
"gendl-sbcl": {
"command": "node",
"args": [
"/path/to/cloned/lisply-mcp/scripts/mcp-wrapper.js",
"--server-name", "gendl-sbcl",
"--http-port", "9090"
]
}
},
{
"skewed-emacs": {
"command": "node",
"args": [
"/path/to/cloned/lisply-mcp/scripts/mcp-wrapper.js",
"--server-name", "skewed-emacs",
"--http-port", "7080"
]
}
}
}
或者在 WSL 场景中（其中 Claude Desktop 在 Windows 主机上运行）：
{
"mcpServers": {
"gendl-ccl": {
"command": "wsl",
"args": [
"node /path/to/cloned/lisply-mcp/scripts/mcp-wrapper.js",
"--server-name", "gendl-ccl",
"--http-port", "9080"
]
}
},
{
"gendl-sbcl": {
"command": "wsl",
"args": [
"node /path/to/cloned/lisply-mcp/scripts/mcp-wrapper.js",
"--server-name", "gendl-sbcl",
"--http-port", "9090"
]
}
},
{
"skewed-emacs": {
"command": "wsl",
"args": [
"node /path/to/cloned/lisply-mcp/scripts/mcp-wrapper.js",
"--server-name", "skewed-emacs",
"--http-port", "7080"
]
}
}
}
请参阅下面的主要内容以获取进一步的配置选项，例如如何将您的 ~/projects/ 文件系统目录挂载（“挂接”）到默认的 Lisply 后端，或者如何指定替代的 Lisply 后端容器或服务主机/端口。
每个服务器独立运行，允许您同时使用多个 Lisp 环境而不会出现工具名称冲突。
3. 重启您的 AI Agent 并测试
按照上述配置，您重新启动的 AI Agent 将现在能够访问名为 lisply-gendl 的 MCP 服务器，并且具有 gendl__lisp_eval MCP 工具（以及其他一些在主要内容中讨论的工具）。请注意，工具名称会自动以前缀服务器名称，以避免运行多个 Lisply 服务器时发生冲突。
为了测试您的设置，您可以提示您的 LLM 如下：
使用 gendl__lisp_eval 工具评估
(+ 1 2 3)，并告诉我结果。
LLM 应该调用请求的评估并返回预期的 6。在继续之前，请随意尝试更复杂的表达式。
默认最小配置是如何工作的？
上面快速开始中描述的最小默认配置将拉取并运行一个包含标准 REPL（读取-求值-打印循环）的 Common Lisp 超集的 Gendl Docker 容器。请注意，还存在一个用于 Emacs Lisp 的第二 Lisply 后端实现，在 Skewed Emacs 项目中。
系统概述
Lisply MCP 中间件作为一个旨在在 Node.js 中运行的 JavaScript 程序实现，提供了一个桥梁，连接您的 AI Agent 和任何 符合 Lisply 后端系统的。此包装器使 AI Agent 能够：
- 在 Lisply 后端评估 Lisp 代码并接收结果。
- 向后端实现的任何 Web 终结点发出 HTTP 请求。
- 使用 Lisp 评估访问后端的内省和文档查找设施。
- 创建、操作、编译、加载和分析文件，再次使用 Lisp 评估。
- 与 Lisp 调试器交互（对于本地运行的后端）。
Lisply 是一种轻量级协议，规定了一组最小且灵活的 HTTP 和标准输入/输出接口，一组标准的环境变量，Docker 容器镜像命名约定以及几种可选功能，以方便 AI 代理控制正在运行的 Lisp 系统。
架构
下图大致捕捉了组件之间的交互方式：
flowchart TB
User("用户") <--> Claude("Claude Desktop")
User <-.-> Emacs("Emacs 文本编辑器 (可选)")
Claude <--> MCP("MCP 协议")
MCP <--> Wrapper("Node.js MCP 包装器")
Wrapper --> LisplyHttp("Lisply HTTP 服务器")
subgraph Docker ["Docker 容器"]
subgraph LisplyExec["Lisply 可执行程序"]
LisplyHttp
LisplySwank("Lisply SWANK 服务器 (用于 Emacs 连接)")
end
end
Wrapper <-- "管理" --> Docker
Emacs <-.-> LisplySwank
KB[("Lisply 知识库")] <--> Wrapper
LisplyHttp --> Endpoints("RESTful 终结点")
LisplyHttp --> LispEval("Lisp 评估")
style User fill:#ff9,stroke:#333,stroke-width:2px
style Claude fill:#f9f,stroke:#333,stroke-width:2px
style Emacs fill:#9ff,stroke:#333,stroke-width:2px,stroke-dasharray:5
style Wrapper fill:#bbf,stroke:#333,stroke-width:2px
style MCP fill:#bbf,stroke:#333,stroke-width:1px
style Docker fill:#bfb,stroke:#333,stroke-width:2px
style LisplyExec fill:#8f8,stroke:#333,stroke-width:2px
style LisplyHttp fill:#bfb,stroke:#333,stroke-width:1px
style LisplySwank fill:#bfb,stroke:#333,stroke-width:1px
style KB fill:#bfb,stroke:#333,stroke-width:1px
style Endpoints fill:#bfb,stroke:#333,stroke-width:1px
style LispEval fill:#bfb,stroke:#333,stroke-width:1px
中间件处理：
- 如果需要，启动和管理符合 Lisply 的 Docker 容器。
- 在 MCP 协议和后端 Lisply API 之间翻译 Lisp 评估请求。
- 错误处理、Lisp 调试器交互和日志记录。
安全注意事项
由于 Lisply-MCP 允许任意 Lisp 代码被评估到正在运行的基于 Lisp 的后端，因此如果 LLM 出现“故障”，则存在一定的风险。因此，最佳实践是：
- 允许包装器仅连接到 Lisply 后端的容器化版本。如果覆盖默认主机/端口，包装器将愉快地连接到任何正在运行的 Lisply 兼容的 HTTP 端口。避免让这种情况发生在由直接在主机上运行的程序提供的任何 HTTP 端口上。
- 确保不将任何不可替换的目录挂接到该容器（请参阅目录挂接配置说明）。
- 考虑采取措施 限制容器的 RAM 和 CPU 使用。
代码模块/文件
- lib/config.js: 配置加载和环境处理
- lib/logger.js: 日志功能
- lib/docker.js: Docker 容器管理
- lib/server.js: HTTP 服务器和 MCP 包装器实现
- lib/utils.js: 响应处理的实用函数
- handlers/: 工具特定请求处理器
- initialize.js: 初始化处理器
- toolsList.js: 工具列表处理器
- toolCall.js: 主工具调用调度器
- httpRequest.js: HTTP 请求处理器
- ping.js: Ping 处理器
- lispEval.js: Lisp 评估处理器
- mcp-wrapper.js: <--- 主入口点 <---
详细安装
- 克隆此仓库：
git clone https://github.com/gornskew/lisply-mcp.git
- 安装所需的依赖项（可选，因为包装器会自动安装依赖项）：
cd lisply-mcp/scripts
npm install # 可选 - 脚本也会尝试在需要时安装这些依赖项
chmod +x mcp-wrapper.js # 某些系统需要
-
确保您的系统已安装 Docker。
-
测试脚本：
node mcp-wrapper.js --help
高级配置
适用于高级用户的可选设置，默认情况下适合大多数情况：
命令行参数
选项:
-H, --backend-host <host> Lisply 服务器主机 (默认: 127.0.0.1)
--swank-host-port <port> 主机系统的 SWANK 端口 (外部) (默认: 4201)
--http-host-port <port> 主机系统的 HTTP 端口 (外部) (默认: 9081)
--https-host-port <port> 主机系统的 HTTPS 端口 (外部) (默认: 9444)
--telnet-host-port <port> 主机系统的 TELNET 端口 (外部) (默认: 4024)
--http-port <port> 容器内的 HTTP 端口 (内部) (默认: 9080)
--https-port <port> 容器内的 HTTPS 端口 (内部) (默认: 9443)
--swank-port <port> 容器内的 SWANK 端口 (内部) (默认: 4200)
--telnet-port <port> 容器内的 TELNET 端口 (内部) (默认: 4023)
--image-base-name <n> Docker 镜像的基本名称 (默认: dcooper8/gendl)
--image-branch <branch> Docker 镜像使用的分支 (默认: 自动检测)
--docker-image <image> 后端的完整 Docker 镜像 (覆盖基本名称和分支)
--lisp-impl <impl> 使用的 Lisp 实现，ccl 或 sbcl (默认: ccl)
--no-auto-start 如果未运行，则不自动启动后端 Docker 容器
--docker-socket <path> Docker 套接字的路径 (默认: /var/run/docker.sock)
--log-file <path> 日志文件的路径 (默认: /tmp/lisply-mcp-wrapper.log)
--debug 启用调试日志
--mount <mounts...> 挂接卷的格式 "src:dst" (可以多次指定)
--start-http 在后端容器中启动 HTTP 服务 (默认: true)
--start-https 在后端容器中启动 HTTPS 服务 (默认: false)
--start-swank 在后端容器中启动 SWANK 服务 (默认: true)
--start-telnet 在后端容器中启动 TELNET 服务 (默认: false)
--no-use-stdio 禁用本地容器的 stdio 功能 (默认: false)
--repl-prompt <pattern> 检测 Lisp 评估完成的 REPL 提示模式 (默认: ?)
--eval-timeout <ms> Lisp 评估的超时时间 (毫秒) (默认: 30000)
--endpoint-prefix <prefix> 所有终结点的前缀 (默认: lisply)
--lisp-eval-endpoint <n> Lisp 评估的终结点名称 (默认: lisp-eval)
--http-request-endpoint <n> HTTP 请求的终结点名称 (默认: http-request)
--ping-endpoint <n> Ping 的终结点名称 (默认: ping-lisp)
--server-name <name> 工具前缀的 MCP 服务器名称 (默认: lisply-mcp)
-h, --help 显示命令的帮助
环境变量
脚本还支持通过环境变量进行配置。您可以指定带有 "LISPLY_" 前缀或无前缀的变量：
注意： 重要的是要区分主机端口（在主机系统上监听并可从主机系统访问）和容器端口（容器内部可见，对 Lisply 后端服务进程可见）：
| 环境变量 | 描述 | 默认值 |
|---|---|---|
BACKEND_HOST 或 LISPLY_BACKEND_HOST | Lisply 服务器主机 | 127.0.0.1 |
SWANK_HOST_PORT 或 LISPLY_SWANK_HOST_PORT | 主机系统的 SWANK 端口 (外部) | 4201 |
HTTP_HOST_PORT 或 LISPLY_HTTP_HOST_PORT | 主机系统的 HTTP 端口 (外部) | 9081 |
HTTPS_HOST_PORT 或 LISPLY_HTTPS_HOST_PORT | 主机系统的 HTTPS 端口 (外部) | 9444 |
TELNET_HOST_PORT 或 LISPLY_TELNET_HOST_PORT | 主机系统的 TELNET 端口 (外部) | 4024 |
HTTP_PORT 或 LISPLY_HTTP_PORT | 容器内的 HTTP 端口 (内部) | 9080 |
HTTPS_PORT 或 LISPLY_HTTPS_PORT | 容器内的 HTTPS 端口 (内部) | 9443 |
SWANK_PORT 或 LISPLY_SWANK_PORT | 容器内的 SWANK 端口 (内部) | 4200 |
TELNET_PORT 或 LISPLY_TELNET_PORT | 容器内的 TELNET 端口 (内部) | 40 |