longhorn-mcp

longhorn-mcp

一个用于 Longhorn 分布式存储管理器 API 的 MCP 服务。完整支持 Longhorn REST API 的读写操作（卷、快照、备份、后备映像、节点、设置、引擎映像、定期任务等），支持 --read-only 模式、stdio 和 Streamable HTTP 两种传输方式，并提供官方 Helm chart。

AI 辅助开发。 本代码库的大部分内容——实现、测试和本文档——均由 AI（Claude）协助编写。请仔细审查，尤其是在生产环境 Longhorn 集群上运行写入模式工具之前。

快速开始

npx -y longhorn-mcp --longhorn-url=http://<longhorn-manager-host>:9500

Longhorn 的 manager API 不需要身份验证——可访问性是唯一的访问控制。如果你不是在集群内运行此服务（参见连接常用 MCP 客户端 → 远程/HTTP），则需要 VPN、SSH 隧道或 kubectl port-forward svc/longhorn-backend 9500:9500 才能安全访问。切勿将 Longhorn 的 manager API 直接暴露给不受信任的网络。

CLI 参考

标志	默认值	说明
--http	关闭（stdio）	使用 Streamable HTTP 而非 stdio 提供服务。
--port	3000	HTTP 监听端口（搭配 --http 使用）。
--host	0.0.0.0	HTTP 监听地址（搭配 --http 使用）。
--read-only	关闭	仅注册读取工具；客户端也会拒绝任何非 GET 请求。
--longhorn-url	http://longhorn-backend.longhorn-system.svc.cluster.local:9500	Longhorn manager API 的基础 URL。默认使用标准 Kubernetes 集群内部 DNS——如果集群使用自定义集群域名，应在其 Deployment 中通过 --longhorn-url 覆盖，而非更改此软件包的默认值。
--allowed-hosts	localhost,127.0.0.1	--http 模式下以逗号分隔的 Host/Origin 允许列表。必须包含实际访问此服务时使用的所有主机名/IP:端口——参见 MCP 规范中的 DNS 重绑定指南。

使用 Helm 部署

每次发布都会同时发布官方 chart：

helm install longhorn-mcp oci://ghcr.io/rafaelgaspar/longhorn-mcp/charts/longhorn-mcp --version 0.1.0 \
  --set args[0]=--http \
  --set args[1]=--longhorn-url=http://longhorn-backend.longhorn-system.svc.cluster.local:9500

关键配置项：

配置项	默认值	备注
image.repository / image.tag	ghcr.io/rafaelgaspar/longhorn-mcp / chart appVersion
args	["--http"]	可追加 --read-only、--longhorn-url、--allowed-hosts 等——参见 CLI 参考。
service.enabled / .type / .port	true / ClusterIP / 3000
route.enabled	false	可选的、厂商中立的核心 Gateway API HTTPRoute（gateway.networking.k8s.io/v1）——不使用 Envoy Gateway 专属资源。请自行提供 Gateway 并设置 route.parentRefs/route.hostnames。
serviceAccount.create	true

完整配置：chart/values.yaml / chart/values.schema.json。

对于通过 OCI Referrers API 发现 chart、而非拉取单独标记的制品的工具，chart 也会作为 OCI 引用直接附加到映像清单：

oras discover ghcr.io/rafaelgaspar/longhorn-mcp:0.1.0

连接常用 MCP 客户端

各客户端的具体配置文件路径/键名可能会随版本变化——如果以下配置不起作用，请查阅客户端自己的文档。它们都接受相同的底层 command/args 结构，用于配置本地 stdio 服务。

Claude Code

claude mcp add longhorn -- npx -y longhorn-mcp --longhorn-url=http://localhost:9500

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "longhorn": {
      "command": "npx",
      "args": ["-y", "longhorn-mcp", "--longhorn-url=http://localhost:9500"]
    }
  }
}

Cursor

编辑 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

{
  "mcpServers": {
    "longhorn": {
      "command": "npx",
      "args": ["-y", "longhorn-mcp", "--longhorn-url=http://localhost:9500"]
    }
  }
}

VS Code（Copilot Chat）

.vscode/mcp.json 使用 servers 键（而非 mcpServers）：

{
  "servers": {
    "longhorn": {
      "command": "npx",
      "args": ["-y", "longhorn-mcp", "--longhorn-url=http://localhost:9500"]
    }
  }
}

远程/HTTP

若要让客户端连接到已运行的 Streamable HTTP 实例（例如，此服务已部署在集群内部，参见使用 Helm 部署），而不是启动本地 npx 进程，请使用该客户端的远程 MCP 配置，并填写服务的 /mcp URL。不支持原生远程 HTTP MCP 的客户端可以通过 mcp-remote 桥接。

在网关后运行

Longhorn 的管理器 API 本身没有身份验证，此服务也因此没有；是否可以访问就是访问控制（参见快速入门）。对于多租户或可从外部访问的部署，建议在 --http 模式前设置支持 MCP 的网关（例如 Envoy AI Gateway 或类似网关），用于身份验证、速率限制和路由。不过这并非必需——使用私有网络边界（VPN、SSH 隧道、仅限集群内部访问）也是完全合理的独立部署方式，而 Helm chart 默认正是如此（route.enabled: false，不对外暴露）。

破坏性操作的防护措施

--read-only 是强制执行的结构性保障（见下文）；以下措施则较为宽松，面向模型——它会影响行为良好的大模型应该做什么，而不是服务能够拒绝什么。

每个操作具有破坏性或难以撤销的工具（删除、强制分离、回滚、恢复集群范围的状态、驱逐节点、部署任意引擎映像、重定向备份目标等），其描述末尾都附有明确指示：除非用户在当前对话中明确授权执行该特定操作，否则不得调用；也绝不能主动调用、推测性调用，或将其作为无关任务的副作用。服务的 MCP instructions 字段（支持该字段的客户端会显示此内容，且每个工具自身的描述中也有相同指示）会在服务级别重复这项指引，为未仔细阅读工具完整描述就调用工具的情况提供额外保障。

这只是建议，并非强制措施——客户端或模型可以忽略。它能降低大模型未经提示便将 volume_delete 或 systemrestore_create 作为“好心”副作用调用的可能性；如果你需要可靠保障，就不能用它代替 --read-only。

Longhorn 文档链接

大多数工具描述末尾都有一个 Longhorn docs: <url> 链接，指向 Longhorn 官方文档中的相关页面。链接固定到此服务默认 --longhorn-url 目标所运行的 Longhorn 版本（当前为 1.13.0），而非“最新”版本，以确保链接内容与实际使用的 API 版本相符。少数没有明确对应文档页面的工具（instancemanager_*、volumeattachment_*、longhorn_events、volume_job_list，以及 longhorn_raw_request/longhorn_list_resource_types/longhorn_describe_resource_type 这些内省工具）没有此类链接。

操作链接

此服务返回的每个 Longhorn 资源（卷、节点、后备映像等）都会嵌入一个 actions 映射，其中包含当前对该资源有效的 RPC 操作，例如卷的 actions.attach。Longhorn 自身的 API 会将这些操作返回为指向管理器集群内地址的 URL——这对 MCP 客户端毫无用处，因为客户端只能调用工具，无法调用任意 HTTP 端点。此服务会将每个操作改写为执行它的 MCP 工具，并附上该工具的参数形状（名称 -> 紧凑类型，? 后缀表示可选），这样客户端无需单独查询架构即可调用，例如：

"actions": {
  "attach": {
    "tool": "volume_attach",
    "shape": { "name": "string", "hostId": "string", "disableFrontend": "boolean?", "attachedBy": "string?", "attacherType": "string?", "attachmentID": "string?" }
  },
  "updateReplicaCount": {
    "tool": "volume_update_setting",
    "shape": { "name": "string", "setting": "enum(19 values)", "value": "string|number|boolean" },
    "args": { "setting": "replicaCount" }
  }
}

当某个操作已确定工具的一个参数时，就会出现 args（如上面的 updateReplicaCount）。例如，Longhorn 的约 19 个单字段卷 update* 操作都会通过同一个 volume_update_setting 工具路由，区别仅在于要传入哪个 setting 值。shape 始终会列出工具接收的所有参数，包括已由 args 确定的参数，因此始终可以通过 shape 查询已确定的值，无需单独查找。

每种资源类型的架构当前声明的所有操作都会以这种方式映射到具名工具，包括卷的未公开文档的 jobList，它通过 volume_job_list 调用（Longhorn 未为它发布输入／输出架构，因此该工具接受开放式的 extra 对象；请参阅 longhorn_describe_resource_type('volume')，以查看部署版本的确切形状）。如果未来的 Longhorn 版本添加了此服务尚未支持的操作，则会改用 longhorn_raw_request，并根据原始 URL 预填充 args.method／args.path。由于 Longhorn 只会列出当前资源状态下有效的操作（例如，salvage 只会出现在故障卷上），因此这反映的是当前实际可调用的操作，而不只是工具架构允许的操作。

只读模式

--read-only 通过两种方式强制执行只读限制：

1. 注册时过滤 — 写入工具不会出现在 tools/list 中，因此只读实例的工具集严格属于读写实例工具集的子集。
2. 客户端层防护 — LonghornClient 会拒绝任何非 GET 请求，无论触发请求的是哪个工具。这可以保护 longhorn_raw_request；该工具是唯一的应急通道，在两种模式下都会保持注册（只有实际调用时才能确定它是否会执行写入操作）。

如果希望 LLM 会话默认只读，同时又能使用显式配置、名称不同且具备写入能力的工具集，可以在同一客户端配置中以不同名称运行读写实例和只读实例：

{
  "mcpServers": {
    "longhorn": { "command": "npx", "args": ["-y", "longhorn-mcp", "--longhorn-url=http://localhost:9500"] },
    "longhorn-readonly": { "command": "npx", "args": ["-y", "longhorn-mcp", "--read-only", "--longhorn-url=http://localhost:9500"] }
  }
}

开发

npm ci
npm run typecheck
npm test
npm run build

scripts/introspect-schema.ts 会转储运行中的 Longhorn 管理器自描述的 /v1/schemas，便于将此软件包手写的工具覆盖范围与您实际运行的 Longhorn 版本进行交叉核对：

npm run introspect-schema -- http://localhost:9500
npm run introspect-schema -- http://localhost:9500 volume   # one resource type in full

贡献

欢迎贡献 — 开发环境设置、编码规范和发布流程请参阅 CONTRIBUTING.md。

许可证

MIT — 请参阅 LICENSE。