fr8 MCP 服务端实现

关键词

模型上下文协议工作区管理JSON-RPC 服务器远程执行与日志tmux 会话管理

使用说明

  • 项目简介

    • fr8 提供一个内置的 MCP (Model Context Protocol) 服务器，允许 AI 客户端（如 Claude Code、Cursor 等）通过 JSON-RPC 的方式对 FR8 的工作区进行创建、查询、启动、停止、归档等操作，以及获取工作区环境变量、日志、仓库信息等上下文数据。
    • MCP 服务端基于 go 语言实现，依赖 github.com/mark3labs/mcp-go 库，通过标准输入输出（stdio）进行通信，便于与 AI 代理的集成环境进行长期长驻的对话式交互。

  • 主要功能点

    • 提供 12 组工具（tools），涵盖对工作区的完整生命周期管理与查询：
      • workspace_list、workspace_status、workspace_create、workspace_archive、workspace_run、workspace_stop
      • workspace_env、workspace_logs、workspace_rename、repo_list、config_show、config_doctor
    • 支持对同一服务器内跨仓库的工作区管理（可通过 repo 参数过滤目标仓库）。
    • 通过 MCP 服务注册工具、接收请求、返回格式化的 MCP 内容，支持错误和结果的清晰区分。
    • 服务器端负责会话管理、能力声明、以及与本地 registry、git 仓库、tmux 会话、端口分配等模块的配合。
    • 与 fr8 CLI 的无缝配合，CLI 的 mcp serve 子命令即启动该 MCP 服务器，供 AI 客户端接入。

  • 安装步骤

    • 你需要先编译和安装 fr8 的命令行二进制，然后通过 fr8 mcp serve 启动 MCP 服务器。启动后服务器将以标准输入输出传输 JSON-RPC 请求与响应，供 MCP 客户端连接使用。
    • 典型安装步骤（简述，实际执行请参考项目的 README 与命令帮助）：
      • 安装 fr8 的命令行工具
      • 运行 fr8 mcp serve 启动 MCP 服务器
      • 配置你的 MCP 客户端以连接该服务器（通常通过给定的 server 名称、启动命令和参数来完成配置）

  • 服务器配置（MCP 客户端需要，fr8 提供的示例）

    • MCP 客户端需要配置服务器信息以建立连接，配置示例（JSON）如下所示，直接提供给 MCP 客户端即可：
    • 配置示例（JSON） { "mcpServers": { "fr8": { "command": "fr8", "args": ["mcp", "serve"] } // 说明：服务器名称为 "fr8"，启动 fr8 命令并向其传递参数 "mcp" 和 "serve" 来开启 MCP 服务端 } }
    • 注释说明
      • server: 名称标识，客户端用于区分不同的 MCP 服务端
      • command: 启动服务器的命令（此处为 fr8）
      • args: 服务器启动时的参数列表，确保包含 mcp serve 来开启 MCP 服务
    • 备注
      • MCP 客户端不需要 fr8 的内部实现细节，以上仅用于描述如何让客户端与 fr8 的 MCP 服务端建立连接。

  • 基本使用方法

    • 启动服务器
      • 在支持的环境中执行 fr8 mcp serve，服务器将监听并通过 stdio 进行 JSON-RPC 交互。
    • 通过 MCP 客户端调用工具
      • 客户端向服务器发送 JSON-RPC 请求，执行诸如 workspace_list、workspace_create 等操作；服务器返回对应的 JSON-RPC 响应对象或错误信息。
    • 运行时能力
      • 服务器通过全局 registro 及 git 工作树信息管理工作区、仓库、端口等资源，确保 AI 代理在执行工具时获得一致的上下文与结果。

  • 重要注意

    • 该实现具备完整的 MCP 服务端能力、注册工具、以及对 FR8 的工作区生命周期的管理能力，非示例代码。对于需要将 ACM（AI 客户端）接入 FR8 的场景，这个 MCP 服务端提供了核心后端能力。

服务器信息

访问项目