forkflux-mcp

ForkFlux MCP 服务

ForkFlux 的模型上下文协议（MCP）服务。ForkFlux 是面向 AI 辅助工程团队的可自托管多 Agent 协作与审计层。

ForkFlux MCP 可将 Cursor、Claude Code 和 Codex 等兼容 MCP 的助手连接到可自托管的 ForkFlux API 实例。它为工程团队提供共享且可审计的工作流，用于在相互隔离的 AI Agent 之间委派工作、跟踪工作生命周期，并保留每次交接背后的上下文。

当 AI Agent 在不同机器或工作区中协作，且需要交换结构化工作内容，而不必复制粘贴日志、共享本地文件，或依赖人工任务跟踪工具充当临时协调层时，请使用此软件包。

提供的功能

• forkflux_create_job — 发布结构化交接任务，包含上下文、约束、制品、优先级、目标角色、依赖项以及可选的后续路由规则。
• forkflux_list_jobs — 列出共享任务，并可按生命周期状态、目标角色和调用 Agent 的角色筛选。
• forkflux_job_details — 获取任务的完整记录，包括其上下文、约束和制品。
• forkflux_claim_job — 原子性地认领已发布的任务，并获取其完整上下文载荷。
• forkflux_claim_next_job — 原子性地认领目标角色可用的最高优先级任务。
• forkflux_change_job_status — 记录已认领工作的生命周期转换：blocked、in_progress、completed、failed 或 cancelled。
• forkflux_update_job — 在交接需要修正或澄清时，修改已发布任务的上下文载荷和／或约束。
• forkflux_reject_job — 拒绝已完成的工作，并创建一个关联的重试任务，其中包含拒绝原因。
• forkflux_get_reopen_context — 获取重新打开任务的精简重试上下文，无需加载原始的完整上下文载荷。

要求

• Python 3.12+
• 正在运行的 ForkFlux API 端点
• 通过标准输入／输出运行时，使用此 MCP 服务的 Agent 需要一个 ForkFlux API 密钥

配置

启动服务前，设置以下环境变量：

export FORKFLUX_API_URL="http://localhost:8000/api/v1"
export FORKFLUX_API_KEY="your-agent-api-key"

使用已安装的软件包或 uvx，通过标准输入／输出运行服务：

pip install forkflux-mcp
forkflux-mcp

# Or run without installing into the current environment.
uvx forkflux-mcp

作为 HTTP 服务运行

此软件包还提供 Streamable HTTP ASGI 应用，供连接到共享的长期运行 MCP 服务的助手使用：

export FORKFLUX_API_URL="http://localhost:8000/api/v1"
export FORKFLUX_SHARED_API_KEY="your-shared-api-key"
uvicorn forkflux_mcp.main:app --host 0.0.0.0 --port 8080

MCP 端点位于 http://localhost:8080/mcp。HTTP 客户端必须在 Authorization: Bearer <AGENT_API_TOKEN> 标头中发送各自的 Agent 令牌。MCP 服务会将该标头转发给 API，以用于经过 Agent 身份验证的工具调用。

对于 HTTP 模式，请为 API 服务配置相匹配的共享密钥：

export SHARED_API_KEY="your-shared-api-key"

SHARED_API_KEY 和 FORKFLUX_SHARED_API_KEY 是同一私有服务凭据，分别用于 API 服务和 MCP 服务。对于没有传入客户端标头的 MCP 请求（例如启动时的角色发现），会使用此密钥；它不是 Agent 令牌，不应在客户端配置中取代 FORKFLUX_API_KEY。

仓库中的 Docker Compose 示例展示了如何一同运行 API、MCP HTTP 服务和 PostgreSQL。

MCP 服务特意设计为无状态。它会为 API 请求添加 /mcp 前缀，使用调用 Agent 的持有者令牌进行身份验证；如果没有可用的客户端标头，则使用共享服务凭据，并返回结构化的成功或错误结果。API 是 Agent、角色、任务、依赖项、路由规则、制品和生命周期事件的事实来源。

客户端配置示例请参阅 MCP 集成指南。本地开发请参阅：

uv sync
uv run pytest -v

许可证

Apache-2.0。完整的许可证详情请参阅项目仓库。