Flux MCP 伺服端实现

使用说明（Markdown格式）

• 项目简介 Flux MCP 服务器是 Flux 项目的一部分，旨在以 MCP 协议为标准向 LLM 客户端提供上下文信息和能力：对资源进行托管与访问、注册与执行工具、以及定义/渲染提示模板。服务器通过 JSON-RPC 风格的请求/响应与客户端进行通信，内部数据源来自 Flux 的存储层（本地存储或远程服务），并支持多种传输方式（包括标准输入/输出和基于 HTTP 的流式传输）。

• 主要功能点

  • 资源托管与查询（Resources）：向 MCP 客户端暴露 Flux 中的项目、任务、史诗等资源及其元信息，客户端可通过 MCP 查询、读取。
  • 工具注册与执行（Tools）：暴露一组可调用的操作，例如列出/创建/更新/删除项目、史诗、任务、Webhook、Blob 等，LLM 可以通过调用工具来对 Flux 数据进行操控。
  • Prompt/模板渲染（Prompts）：为 LLM 提供可渲染的提示和上下文模板，便于交互式对话和任务执行。
  • JSON-RPC 语义与结构化响应：采用 MCP 规定的请求模式，返回标准化的 JSON-RPC 响应或通知。
  • 支持多传输协议：默认通过标准输入输出（stdio）传输，HTTP 模式通过 Web 标准的流式传输（WebStandardStreamableHTTPServerTransport）实现 SSE/流式交互，便于与远程 LLM 客户端对接。
  • 会话管理与能力声明：服务器端维护能力清单、会话状态，确保多客户端并发访问的一致性。
  • 与 Flux 存储的紧密集成：通过 Flux 的共享数据模型和适配器，读取/修改 Flux 的 Projects、Epics、Tasks、Blobs、Webhooks 等数据。

• 安装与运行步骤

  1. 确保仓库依赖已安装（含 TypeScript、Node/Bun 等运行环境以及 Flux 相关依赖）。
  2. 将 MCP 服务启动为一个独立进程：在项目根目录下执行可执行入口，或通过包管理工具直接运行相应脚本。
  3. 服务器启动参数示例（可选）：支持两种传输模式
     • 标准输入/输出（stdio）模式：默认启动，适合与本地工具链或管道式调用集成。
     • HTTP 模式：通过 --http 启用，通过 --port 指定端口（默认 3001），以流式传输提供 MCP 服务。
  4. 客户端配置与连接：MCP 客户端需要提供服务器信息（名称、启动命令和参数等），以建立与 MCP 服务器的连接并按 MCP 协议进行资源/工具/提示的交互。

• 服务器配置（MCP 客户端需要的配置信息，JSON 表示，包含 server name、command、args 等） { "server": "flux-mcp", "command": "node /path/to/flux/packages/mcp/src/index.ts", "args": ["--http", "--port=3001"], "description": "Flux MCP 服务器，提供资源和工具接口，采用 JSON-RPC 交互。HTTP 模式可通过端口 3001 访问，默认使用 stdio 传输。" } 注释说明：以上为客户端连接该 MCP 服务器所需的配置信息示例，包含服务器名称、启动命令及参数。MCP 客户端并不需要该代码实现的细节，仅依赖该配置来建立连接。本仓库的 MCP 服务器实现会根据运行时参数选择传输模式。

• 基本使用方法

  1. 启动服务器
     • 以 stdio 传输启动：将 MCP 客户端置于同一进程或管道场景，直接通过标准输入输出进行 JSON-RPC 通信。
     • 以 HTTP/SSE 启动：使用 --http 模式，端口号通过 --port 指定，客户端通过 HTTP 请求向 MCP 服务发起 JSON-RPC 交互。
  2. 客户端接入与交互
     • 客户端通过 MCP 提供的资源查询、工具执行等接口获取 Flux 数据、执行操作。
     • 客户端需要遵循 MCP 的请求/响应格式，传输 JSON-RPC 风格的数据。
  3. 典型用例
     • 列出 Flux 项目、epic、task 等资源；通过工具执行创建/更新等操作；读取资源详情并将结果呈现给用户或自动化流程。
  4. 运行环境与调试
     • 关注服务器启动日志，确认传输模式是否正确（stdio / HTTP）。
     • 通过接口调用验证资源和工具的返回数据结构是否符合 MCP 约定。

• 关键词 flux, MCP, JSON-RPC, 资源管理, 工具执行, 流式传输

• 分类 5