Kunobi MCP 服务器

关键词

桌面应用集成多变体管理LLM 集成资源与工具发现JSON-RPC

使用说明

项目简介

本仓库提供一个完整的 MCP 服务器实现，用于将 Kunobi 桌面应用的多个变体（如 legacy、stable、dev 等）通过 MCP 协议对外暴露。服务器负责：与 Kunobi 实例建立连接、把变体的工具、资源与提示以变体命名空间动态注册到 MCP 客户端、提供内置工具以查询状态、启动 Kunobi、刷新连接以及通过通用入口 kunobi_call 调用下游工具。服务器采用标准的 JSON-RPC 形式处理 MCP 请求，并通过 Stdio 传输与 AI 客户端通信（也具备对 Kunobi 变体的 HTTP 连接能力以整合工具/资源元数据）。同时支持资源订阅、工具列表变更通知等能力，确保 LLM 客户端能获取到最新的上下文信息。

主要功能点

  • MCP 核心协议实现
    • 处理 MCP 请求/响应（初始化、工具列表、资源与提示订阅等）以及相关通知。
  • 资源、工具、提示的注册与动态更新
    • 为每一个已连接的 Kunobi 变体自动注册前缀为 variant__ 的工具、资源与提示。
    • 变体进出时自动注册/注销，工具列表可随变体状态动态更新。
  • 多变体管理
    • 支持配置多组变体及端口，服务器会持续尝试连接并维护持久会话。
    • 针对不同变体，资源 URI 与工具名称会以 variant 前缀进行命名，避免命名冲突。
  • 内置工具集合
    • kunobi_status、kunobi_launch、kunobi_refresh、kunobi_call，提供变体状态查询、启动 Kunobi、强制重连和稳定调用下游工具的能力。
  • 资源与提示的跨变体暴露
    • kunobi://status、kunobi://tools 等内置资源，以及根据变体动态生成的资源、工具、提示元数据。
  • 安全与扩展性
    • 服务器对日志、通知等能力进行声明，并提供可扩展的日志回调，便于集成到当前 AI 助手工作流中。
  • 传输模式
    • 初始通过 Stdio 进行 MCP 会话与客户端通信，未来可扩展到 HTTP/SSE/WebSocket 等传输方案以接入 Kunobi 变体的工具/资源元数据。

安装步骤

  • 安装依赖与构建
    • 需要 Node.js 环境与合适的包管理工具（如 npm/yarn/pnpm）。
    • 安装依赖并构建服务器：
      • 安装依赖
      • 构建服务器
  • 启动与使用
    • 通过标准输入输出（stdio）与 MCP 客户端建立会话。MCP 客户端通常通过将服务器进程的 stdout/stdin 作为通信管道连接到 AI 客户端。
    • 服务器会在启动后自动根据配置的变体端口建立对 Kunobi 实例的连接，并动态注册其工具、资源及提示。
    • 如果需要让 AI 客户端自动注册该服务器到已安装的 AI 客户端，请在 Kunobi 的 MCP 设置中执行自动注册命令。

服务器配置

MCP 客户端用于与 MCP 服务器建立连接，配置以 JSON 的形式描述服务器信息与启动命令。示例文本描述如下（请勿直接粘贴代码块给终端用户；以下为文本格式的示例）：

json { "mcpServers": { "kunobi": { "command": "npx", "args": ["-y", "@kunobi/mcp"] } // 该配置用于告诉 MCP 客户端如何启动服务器进程， // 具体名称为 Kunobi，命名空间与端口等由服务器端配置来管理 } } 说明：

  • server name 对应服务器在 MCP 客户端中的标识（如 "kunobi"）。
  • command 与 args 是启动服务器的命令及参数，在客户端需要启动 MCP 服务器时使用。
  • 服务器端会从 ~/.config/kunobi/mcp.json 读取变体端口等配置信息，初次运行时会自动创建默认配置。

运行时的可配置项（节选）：

  • 变体与端口（variants）：{ legacy: 3030, stable: 3200, unstable: 3300, dev: 3400, local: 3500, e2e: 3600 }
  • 自动重连间隔（MCP_KUNOBI_RECONNECT_INTERVAL_MS，默认 5000 毫秒）
  • 自动连接开关（MCP_KUNOBI_AUTO_CONNECT，默认 true；设置为 false 将禁用后台自动连接）

基本使用方法

  • 第一次运行后，服务器会自动发现 Kunobi 的不同变体并注册相应的工具与资源。
  • 使用 kunobi_status、kunobi_launch、kunobi_refresh、kunobi_call 等内置工具来管理变体并调用下游工具。
  • 当 Kunobi 变体启动、停止或出现网络状况变化时，MCP 服务器会自动更新工具与资源的可用性列表并向客户端发送变更通知。

基本使用示例

  • 通过 MCP 客户端初始连接后，先查询状态以了解有哪些变体已连接以及各自的工具数量。
  • 使用 kunobi_call 将一个变体的具体工具暴露出来进行执行。

运行与开发注意

  • 该实现包含一组完整的单元测试，覆盖变体管理生命周期、工具注册/调用、资源与提示的暴露等关键场景。
  • 开发者可在本地通过 pnpm install、pnpm build、pnpm test 进行安装、构建与测试。
  • 如果需要本地调试 Bundler/Adapter 的行为，可以将 bundler 与服务器的行为在测试环境中模拟。

服务器信息

访问项目