Model Context Protocol (MCP) Wrapper for Lisply Backends

Model Context Protocol (MCP) Wrapper for Lisply Backends

用于管理符合规范的、使用 "Lisply" Lisp 语言的后端服务并与之通信的“模型上下文协议 (MCP)”服务器

gornskew

研究与数据
访问服务器

README

Lisply 后端的模型上下文协议 (MCP) 包装器

这是一个 MCP 包装器脚本，用于将 Claude Desktop 和类似的“代理 AI 客户端”连接到某些“Lisply”服务。它提供了 Claude 和任何兼容的 Lisp 后端服务（例如 Gendl）之间的强大接口，从而实现直接的 AI 辅助符号编程。

注意： 此实现目前适用于 Gendl 系统，如果需要，会自动启动和停止 Gendl 容器。正在努力推广该实现以支持 Gnu Emacs 后端，随后我们欢迎更多兼容的 Lispy 系统。

目录

概述

Lisply MCP 包装器使用 Nodejs 实现，并在 Claude AI 和任何兼容的 Lisply 后端系统之间提供桥梁。此包装器使 Claude 能够：

  1. 在 Lisply 环境 (LE) 中评估 Lisp 代码。
  2. 向 LE 中实现的任何端点发出 HTTP 请求。
  3. 访问 LE 中的任何内省和文档查找工具。
  4. 通过 Lisp 评估创建、操作、编译、加载、分析文件。
  5. 与 Lisp 调试器交互（对于本地生成的容器）。

架构

MCP 包装器实现了模型上下文协议 (MCP)，以将 Claude 与 Gendl 的功能连接起来。以下是组件如何交互：

flowchart TB
    User("User") <--> Claude("Claude AI Assistant")
    User <-.-> Emacs("Emacs Text Editor (Optional)")

    Claude <--> MCP("MCP Protocol")
    MCP <--> Wrapper("NodeJS MCP Wrapper")

    Wrapper --> LispyHttp("Lispy HTTP Server")
    
    subgraph Docker ["Docker Container"]
    subgraph LispyExec["Lispy Executable"]
    LispyHttp
    LispySwank("Lispy SWANK Server")
    end
    end
	
    Wrapper <-- "Manages" --> Docker

    Emacs <-.-> LispySwank
    
    KB[("Lispy Knowledge Base")] <--> Wrapper
    
    LispyHttp --> Endpoints("RESTful Endpoints")
    LispyHttp --> LispEval("Lisp Evaluation")
    
    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 LispyExec fill:#8f8,stroke:#333,stroke-width:2px
    style LispyHttp fill:#bfb,stroke:#333,stroke-width:1px
    style LispySwank 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

包装器脚本处理：

  1. 如果需要，启动和管理 Lispy Docker 容器
  2. 在 Claude 和 Lispy 后端之间路由请求
  3. 在 MCP 协议和后端 Lispy API 之间进行转换
  4. 错误处理和日志记录

特性

  • 可配置的 Lispy 主机和端口：通过命令行参数或环境变量进行配置
  • Docker 容器管理：在需要时自动启动 Lispy 容器
  • 卷挂载：将主机目录挂载到 Lispy 容器中
  • 在 Docker 中自行运行：直接在主机上或在带有 Docker 套接字的容器内运行此包装器
  • 错误处理：检测和报告错误
  • 详细日志记录：带有时间戳的详细日志，以及可选的调试模式以获得更多详细信息
  • 自动 Docker 镜像选择：基于克隆的分支和选择的后端类型的合理默认值
  • DockerHub 身份验证：自动拉取最新的容器镜像，并处理身份验证
  • 现有服务检测：依赖于现有的实时服务（如果可用），从而避免了启动和停止专用容器的需要

安装

  1. 安装所需的依赖项：
cd /path/to/lispy-mcp/scripts
npm install
chmod +x mcp-wrapper.js

  1. 确保您的系统上已安装 Docker。

  2. 测试脚本：

node mcp-wrapper.js --help

配置

您可以使用命令行参数或环境变量来配置 MCP 包装器。

命令行参数

Options:
  -H, --host <host>            Lispy server host (default: 127.0.0.1)
  --swank-host-port <port>     SWANK port on host system (default: 4201)
  --http-host-port <port>      HTTP port on host system (default: 9081)
  --https-host-port <port>     HTTPS port on host system (default: 9444)
  --telnet-host-port <port>    TELNET port on host system (default: 4024)
  --http-port <port>           HTTP port inside container (default: 9080)
  --https-port <port>          HTTPS port inside container (default: 9443)
  --swank-port <port>          SWANK port inside container (default: 4200)
  --telnet-port <port>         TELNET port inside container (default: 4023)
  --docker-image <image>       Docker image for Lispy services (default: `dcooper8/gendl:<branch>-<lisp-impl>`)
  --lisp-impl <impl>           Lisp implementation to use, e.g. ccl or sbcl for `dcooper8/gendl` (default: ccl)
  --no-auto-start              Do not auto-start Gendl docker container if live service not available (resulting in an error exit).
  --docker-socket <path>       Path to docker socket (needed if running this nodejs wrapper inside a docker container) (default: /var/run/docker.sock)
  --log-file <path>            Path to log file of this script (default: /tmp/mcp-wrapper.log)
  --debug                      Enable debug logging (more verbose)
  --mount <mounts...>          Mount volumes in format "src:dst" (can specify multiple times)
  --start-http                 Start HTTP service in Gendl container (required)(default: true)
  --start-https                Start HTTPS service in Gendl container (default: false)
  --start-swank                Start SWANK service in Gendl container (default: true)
  --start-telnet               Start TELNET service in Gendl container (default: false)
  -h, --help                   Display help for command

环境变量

该脚本还支持通过环境变量进行配置：

环境变量 描述 默认值
GENDL_HOST Gendl 服务器主机 127.0.0.1
SWANK_HOST_PORT 主机系统上的 SWANK 端口 5200
HTTP_HOST_PORT 主机系统上的 HTTP 端口 10080
HTTPS_HOST_PORT 主机系统上的 HTTPS 端口 10443
TELNET_HOST_PORT 主机系统上的 TELNET 端口 5023
HTTP_PORT 容器内的 HTTP 端口 9080
HTTPS_PORT 容器内的 HTTPS 端口 9443
SWANK_PORT 容器内的 SWANK 端口 4200
TELNET_PORT 容器内的 TELNET 端口 4023
START_HTTP 启用 HTTP 服务 true
START_HTTPS 启用 HTTPS 服务 false
START_SWANK 启用 SWANK 服务 true
START_TELNET 启用 TELNET 服务 false
GENDL_DOCKER_IMAGE Gendl 的 Docker 镜像 (自动检测)
GENDL_LISP_IMPL 要使用的 Lisp 实现 ccl
GENDL_AUTO_START 启用自动启动容器 true
DOCKER_SOCKET Docker 套接字的路径 /var/run/docker.sock
GENDL_LOG_FILE 日志文件的路径 /tmp/mcp-wrapper.log
DEBUG_GENDL 启用调试日志记录 false
GENDL_MOUNTS 逗号分隔的挂载点 (无)

Docker 集成

MCP 包装器与 Docker 紧密集成，以有效地管理 Gendl 容器。

Docker 镜像选择

包装器根据 lispy-mcp 存储库中的当前分支自动选择适当的 Docker 镜像：

  1. Docker 镜像遵循命名模式：dcooper8/gendl:${branch}-${impl}

    • ${branch} 是当前的 git 分支名称，任何斜杠 (/) 都转换为双连字符 (--)
      • 例如，release/1598 在镜像标签中变为 release--1598
      • devo 分支将使用镜像标签 devo
    • ${impl} 是 Lisp 实现（ccl 或 sbcl）

  2. 脚本将尝试拉取或使用与当前分支匹配的镜像：

    • 首先尝试从 Docker Hub 拉取与当前分支匹配的镜像
    • 如果拉取失败，则检查镜像是否在本地存在
    • 如果两者都不起作用，则回退到 master 分支镜像

  3. 您可以使用以下方式覆盖自动选择：

    • --docker-image 命令行参数
    • GENDL_DOCKER_IMAGE 环境变量

  4. 对于 Lisp 实现：

    • 使用 --lisp-impl (ccl 或 sbcl) 指定
    • 或使用 GENDL_LISP_IMPL 环境变量
    • 如果未指定，则默认为 ccl

Docker Hub 身份验证

包装器将尝试在启动容器之前拉取相应 Docker 镜像的最新版本。此行为包括：

  1. 检查 Docker Hub 身份验证
  2. 如果未通过身份验证，则尝试登录（使用存储的凭据或交互式登录）
  3. 拉取与您的配置匹配的最新镜像
  4. 如果拉取失败，则回退到使用本地镜像
  5. 如果需要，尝试拉取默认镜像 (master-ccl) 作为最后的手段

现有服务检测

在尝试启动容器之前，包装器将检查 Gendl 服务是否已在指定的主机和端口上运行：

  1. 首先检查 HTTP 服务 (HTTP_HOST_PORT) 作为主要服务
  2. 检查 SWANK 服务 (SWANK_HOST_PORT) 作为后备

现有服务的参数行为

重要提示： 当在指定的主机和端口上检测到现有服务时：

  1. 所有 Docker 相关设置都将被忽略：

    • --docker-image 和 --lisp-impl
    • --mount 卷选项
    • --start-* 服务标志
    • --*-port 内部容器端口设置
    • --docker-socket 路径
    • --no-auto-start 标志

  2. 包装器将显示有关哪些设置被忽略的警告

这确保了包装器可以与外部 Gendl 服务正常工作，同时提供有关忽略的配置选项的清晰反馈。

卷挂载

您可以将主机目录挂载到 Gendl 容器中，以在主机系统和容器之间共享文件：

node mcp-wrapper.js --mount /home/user/projects:/projects

可以指定多个挂载点：

node mcp-wrapper.js --mount /home/user/projects:/projects --mount /home/user/data:/data

或者使用环境变量：

GENDL_MOUNTS=/home/user/projects:/projects,/home/user/data:/data node mcp-wrapper.js

使用示例

以下所有示例都可以在命令行上进行测试，并在 claude_desktop_config.json 配置中使用（请参阅 Claude Desktop 配置）。

基本用法

使用默认设置运行 (localhost:5200)：

node mcp-wrapper.js

自定义主机和端口

指定自定义 Gendl 服务器：

node mcp-wrapper.js --host 192.168.1.100 --swank-host-port 5200 --http-host-port 10080

自定义 Lisp 实现

指定不同的 Lisp 实现：

node mcp-wrapper.js --lisp-impl sbcl

启用服务

启用 HTTP 和 HTTPS 服务：

node mcp-wrapper.js --start-http --start-https

或者使用环境变量：

START_HTTP=true START_HTTPS=true node mcp-wrapper.js

配置内部容器端口

指定所有内部端口：

node mcp-wrapper.js --http-port 9080 --https-port 9443 --swank-port 4200 --telnet-port 4023

或者使用环境变量：

HTTP_PORT=9080 HTTPS_PORT=9443 SWANK_PORT=4200 TELNET_PORT=4023 node mcp-wrapper.js

在容器中运行

如果在容器内运行包装器，请确保挂载 Docker 套接字：

docker run -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/scripts:/app node:18 node /app/mcp-wrapper.js

Claude 集成

此包装器使 Claude 能够通过模型上下文协议 (MCP) 与 Gendl 交互。

Claude 工具

MCP 包装器公开了 Claude 可以用来与 Gendl 交互的几个工具：

Lisp 评估工具

lisp_eval 工具允许 Claude 直接在 Gendl 环境中评估 Lisp 代码。这使 Claude 能够：

  • 创建和操作 GDL 对象
  • 使用 Gendl 的几何图元执行复杂的计算
  • 访问和修改 Gendl 的状态

该工具接受以下参数：

  • code (必需)：要评估的 Lisp 代码
  • package (可选)：用于评估的包
  • mode (可选)：用于与 Gendl 通信的模式
    • http (默认)：使用 HTTP 通信进行结构化响应
    • stdio：使用标准输入/输出通信进行原始 REPL 体验

模式比较：

特性 HTTP 模式 STDIO 模式
响应格式 具有单独的 Result 和 Stdout 字段的结构化格式 原始 REPL 样式的输出
错误处理 捕获错误并将其作为字符串返回 可以进入交互式调试器
调试器支持 无交互式调试 支持交互式调试器
兼容性 适用于本地和远程服务器 仅适用于 MCP 启动的本地容器
用例 干净的集成，简单的查询 开发、调试、复杂的交互

使用默认 HTTP 模式的示例用法：

(in-package :gdl-user)
(defparameter *test-box* (make-box :width 10 :height 5 :depth 3))
(theo *test-box* width)

使用 STDIO 模式的示例用法（用于调试）：

;; 这将允许在发生错误时进行交互式调试
(in-package :gdl-user)
(defparameter *test-box* (make-box :width 10 :height 5 :depth 3))
(theo *test-box* width)

HTTP 请求工具

http_request 工具使 Claude 能够与 Gendl 公开的任何 HTTP 端点进行交互：

{
  "path": "/color-map",
  "method": "GET",
  "headers": {
    "Accept": "application/json"
  }
}

知识库集成

query_gendl_kb 工具允许 Claude 搜索有关 Gendl/GDL（通用声明式语言）的信息：

query_gendl_kb("How do I create a box in GDL?")

Ping 工具

ping_gendl 工具让 Claude 检查 Gendl 服务器是否可用：

ping_gendl()

Claude Desktop 配置

以下是如何配置 Claude Desktop 以使用此包装器的示例：

{
  "mcpServers": {
    "filesystem": {
      "command": "wsl",
      "args": [
        "docker",
        "run",
        "-i",
        "--rm",
        "-u",
        "1000:1000",
        "--mount",
        "type=bind,src=/home/user/projects,dst=/projects",
        "mcp/filesystem",
        "/projects"
      ]
    },
    "gendl": {
      "command": "wsl",
      "args": [
        "node",
        "/home/user/projects/lispy-mcp/scripts/mcp-wrapper.js",
        "--mount", "/home/user/projects:/projects"
      ],
      "env": {
        "NODE_ENV": "production",
        "DEBUG": "*"
      }
    }
  },
  "globalShortcut": ""
}

实际示例

示例 1：创建参数化框

在此示例中，Claude 在 Gendl 中创建一个参数化框，然后根据用户要求修改其属性。

用户：“您能在 Gendl 中创建一个宽度为 10、高度为 5、深度为 3 的框吗？然后告诉我如何将高度更改为 8。”

Claude：

我将使用 lisp_eval 工具在 Gendl 中创建一个参数化框，然后向您展示如何修改其高度。

首先，让我们创建具有指定尺寸的框：

(in-package :gdl-user)

;; 首先，创建具有指定尺寸的框
(defparameter *my-box* (make-object 'box 
                         :width 10 
                         :height 5 
                         :depth 3))

;; 让我们验证尺寸
(list (theo *my-box* width)
      (theo *my-box* height)
      (theo *my-box* depth))

现在，让我们将高度从 5 更改为 8：

;; 使用带有访问器的 setf 更改高度
(theo *my-box* (set-slot! :height 8))

;; 或者，我们可以创建一个新框
(defparameter *new-box* (make-object 'box 
                         :width 10 
                         :height 8  ;; 更新的高度
                         :depth 3))

;; 验证原始框的新尺寸
(list (theo *my-box* width)
      (theo *my-box* height)
      (theo *my-box* depth))

您可以通过创建 GWL Web 界面或使用 Gendl 的内置可视化工具来可视化此框。

您想让我向您展示如何创建更复杂的参数化对象或如何设置可视化吗？

示例 2：查询 GDL 信息的知识库

用户：“如何在 GDL 中创建一个圆柱体，它接受哪些参数？”

Claude：

我将使用 Gendl 知识库来查找有关在 GDL 中创建圆柱体的信息：

在 GDL 中创建圆柱体的基本语法是：

(make-object 'cylinder :radius 5 :height 8)

圆柱体的主要参数是：

  • :radius - 圆柱体的半径（默认为 1）
  • :height - 圆柱体的高度（默认为 1）
  • :orientation - 通常使用 alignment 创建的方位矩阵
  • :center - 中心点（默认为 (make-point 0 0 0)）

这是一个完整的示例：

(in-package :gdl-user)

(defparameter *my-cylinder* (make-object 'cylinder 
                              :radius 2.5
                              :height 10
                              :orientation 
							  (alignment :rear (the (face-normal-vector :top)))))

;; 验证参数
(list (theo *my-cylinder* radius)
      (theo *my-cylinder* height)
      (theo *my-cylinder* center))

请注意，:display-controls 是显示属性的 plist，例如 :color 用于渲染

您想让我解释使用 GDL 中的圆柱体的任何其他方面吗？

故障排除

常见问题和解决方案

容器无法启动

如果 Gendl 容器无法启动：

  1. 检查 Docker 是否正在运行：
docker info
  1. 检查端口是否已被使用：
sudo lsof -i :5200
sudo lsof -i :10080
  1. 验证 Docker 镜像是否存在：
docker images | grep gendl
  1. 尝试手动拉取镜像：
docker pull dcooper8/gendl:master-ccl

连接错误

如果 Claude 无法连接到 Gendl：

  1. 检查 Gendl 服务器是否正在运行：
docker ps | grep gendl
  1. 启用调试日志记录：
node mcp-wrapper.js --debug
  1. 检查日志文件：
tail -f /tmp/mcp-wrapper.log
  1. 尝试 ping Gendl HTTP 服务器：
curl http://localhost:10080/mcp/ping-gendl
  1. 尝试连接到 Gendl SWANK 服务器：
telnet localhost 5200

权限问题

如果您遇到权限错误：

  1. 检查 Docker 套接字权限：
ls -l /var/run/docker.sock
  1. 确保您的用户有权访问 Docker：
sudo usermod -aG docker $USER
  1. 检查挂载目录权限：
ls -l /path/to/mounted/directory

诊断命令

使用以下命令来诊断问题：

  1. 检查包装器日志：
tail -f /tmp/mcp-wrapper.log
  1. 检查 Docker 容器日志：
docker logs $(docker ps --filter "name=lispy-mcp" --format "{{.ID}}")
  1. 检查 Gendl 服务状态：
curl http://localhost:10080/mcp/ping-gendl
  1. 验证 Docker 环境：
docker system info

许可证

本软件根据 GNU Affero 通用公共许可证 v3.0 (AGPL-3.0) 获得许可，该许可证与 Gendl 使用的许可证相同。

许可证含义

重要提示：仅使用此 MCP 服务器与 Gendl 交互并获取输出不会触发 AGPL 的要求。您可以使用此包装器与 Gendl 交互，而无需共享您的代码。

但是，如果您修改此包装器并托管基于修改后的软件的服务，则 AGPL 将要求您与该服务的用户共享您的修改。换句话说，如果您以网络服务的形式运行此软件的修改版本，则必须向该服务的用户提供修改后的源代码。

对于需要保持其源代码关闭的应用程序，Genworks 以 5% 的自我报告的季度特许权使用费的形式提供“AGPL 逃生条款”。更多信息和支付网关可在 payments.genworks.com 上找到。

许可证的完整文本可以在此目录中的 COPYING.txt 文件中找到。

推荐服务器

Crypto Price & Market Analysis MCP Server

Crypto Price & Market Analysis MCP Server

一个模型上下文协议 (MCP) 服务器，它使用 CoinCap API 提供全面的加密货币分析。该服务器通过一个易于使用的界面提供实时价格数据、市场分析和历史趋势。 (Alternative, slightly more formal and technical translation): 一个模型上下文协议 (MCP) 服务器，利用 CoinCap API 提供全面的加密货币分析服务。该服务器通过用户友好的界面，提供实时价格数据、市场分析以及历史趋势数据。

精选
TypeScript
MCP PubMed Search

MCP PubMed Search

用于搜索 PubMed 的服务器（PubMed 是一个免费的在线数据库，用户可以在其中搜索生物医学和生命科学文献）。 我是在 MCP 发布当天创建的，但当时正在度假。 我看到有人在您的数据库中发布了类似的服务器，但还是决定发布我的服务器。

精选
Python
mixpanel

mixpanel

连接到您的 Mixpanel 数据。 从 Mixpanel 分析查询事件、留存和漏斗数据。

精选
TypeScript
Sequential Thinking MCP Server

Sequential Thinking MCP Server

这个服务器通过将复杂问题分解为顺序步骤来促进结构化的问题解决，支持修订，并通过完整的 MCP 集成来实现多条解决方案路径。

精选
Python
Nefino MCP Server

Nefino MCP Server

为大型语言模型提供访问德国可再生能源项目新闻和信息的能力，允许按地点、主题（太阳能、风能、氢能）和日期范围进行筛选。

官方
Python
Vectorize

Vectorize

将 MCP 服务器向量化以实现高级检索、私有深度研究、Anything-to-Markdown 文件提取和文本分块。

官方
JavaScript
Mathematica Documentation MCP server

Mathematica Documentation MCP server

一个服务器，通过 FastMCP 提供对 Mathematica 文档的访问，使用户能够从 Wolfram Mathematica 检索函数文档和列出软件包符号。

本地
Python
kb-mcp-server

kb-mcp-server

一个 MCP 服务器，旨在实现便携性、本地化、简易性和便利性，以支持对 txtai “all in one” 嵌入数据库进行基于语义/图的检索。任何 tar.gz 格式的 txtai 嵌入数据库都可以被加载。

本地
Python
Research MCP Server

Research MCP Server

这个服务器用作 MCP 服务器，与 Notion 交互以检索和创建调查数据，并与 Claude Desktop Client 集成以进行和审查调查。

本地
Python
Cryo MCP Server

Cryo MCP Server

一个API服务器，实现了模型补全协议（MCP），用于Cryo区块链数据提取，允许用户通过任何兼容MCP的客户端查询以太坊区块链数据。

本地
Python