QodFlow

qodflow-mcp

适用于 QodFlow 的模型上下文协议（MCP）服务。QodFlow 是一款支持 SLA 跟踪的看板，供人类和 AI Agent 共同使用。Claude Code、Claude Desktop、Cursor 和其他 MCP 客户端可通过此服务创建、移动、分配工作项并生成报告；访问权限由具备特定作用域且可撤销的个人访问令牌控制。

安装

# Claude Code
claude mcp add qodflow -- npx qodflow-mcp
export QODFLOW_API_TOKEN=qf_live_…

对于其他 MCP 客户端：将 npx qodflow-mcp 设为服务命令，并在其环境中设置 QODFLOW_API_TOKEN（见下文）。完整指南：https://www.qodflow.com/docs/mcp

如需从源代码构建，请在 mcp-server/ 中运行 npm install，然后运行 npm run build；生成的二进制文件为 qodflow-mcp。

配置 Agent

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）

{
  "mcpServers": {
    "qodflow": {
      "command": "npx",
      "args": ["qodflow-mcp"],
      "env": {
        "QODFLOW_API_TOKEN": "qf_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor / ChatGPT Desktop

使用相同的 command + env 格式；请查阅客户端文档，了解准确的配置路径。

获取令牌

1. 登录 QodFlow。
2. 前往 Settings → API Keys。
3. 点击 New token，为令牌命名，选择所需的最小作用域（当前工具集只需 jobs:read + stages:read），然后复制明文令牌——仅显示一次，之后将不再显示。
4. 在 Agent 配置中将其粘贴为 QODFLOW_API_TOKEN。

进行集成测试时，请在创建令牌时启用 Test mode；令牌前缀将变为 qf_test_，且令牌会绑定到测试模式的 Stripe 产品。

工具（v0.1）

工具	所需作用域	方案	描述
list_jobs	jobs:read	任意	分页列出最新工作项。
list_stages	stages:read	任意	列出流水线阶段及其顺序、颜色和 SLA。
list_tags	tags:read	任意	列出工作区中定义的标签。
list_members	members:read	任意	列出团队成员（ID、姓名、隐藏部分的邮箱提示、角色）。
create_job	jobs:write	任意*	在第一个阶段（或指定阶段）创建工作项。
update_job	jobs:write	任意*	更新标题、描述、优先级和 PO 编号。
move_job	jobs:write	任意	将工作项移至其他阶段。
assign_job	mcp:assign	任意	将工作项分配给成员（或设为 null 以取消分配）。
create_tag	tags:write	PREMIUM+	创建标签。
update_stage	stages:write	任意*	重命名阶段、更改 SLA 或颜色。
claim_job / release_job	mcp:claim	任意	以原子方式认领或释放工作项（基于租约）。
report_progress	mcp:claim	任意	向工作项时间线追加进度备注。
request_human_decision	mcp:decide	任意	请人类在多个选项中进行选择。
resolve_decision	mcp:resolve	任意	解决一项待处理的决策。
attach_evidence	mcp:evidence	任意	附加备注（可选附带 URL）作为证据。
get_timeline / list_decisions / list_evidence	jobs:read	任意	查看工作项的时间线 / 决策 / 证据。

* 受方案限制（进行中工作项数量上限、标签功能限制）。当调用超出方案限制或配额时，工具会返回错误，错误文本中包含 Upgrade: <url> 提示，可转告用户。

删除团队、批量移动等破坏性操作不会通过 MCP 提供。它们仅能通过 UI 中的确认文本保护机制执行。

安全模型

• 每次调用都会在服务端强制执行令牌作用域——此二进制文件无法授予自身未获授权的权限。
• 每个通过令牌验证的请求都会写入审计日志，团队所有者可查看日志。
• 紧急停用：前往 Settings → API Keys 撤销令牌，即可立即停止 Agent。
• 速率限制：每个令牌每分钟 120 个请求（由服务端强制执行）。
• 此二进制文件不会向磁盘持久化任何内容，也不会主动联系其他服务——它只会与 QODFLOW_API_BASE 通信（默认为 https://www.qodflow.com）。

共享工作站上的令牌处理

MCP 宿主（Claude Desktop、Cursor）会将此二进制文件作为子进程启动，并通过 QODFLOW_API_TOKEN 环境变量传递令牌。在 Linux 上，同一用户运行的任何其他进程都能通过 /proc/PID/environ 读取该环境变量；在某些配置下，macOS 上也会通过 ps -ewww 暴露类似信息。如果你在共享工作站或运行着其他不可信代码的机器上操作（CI 运行器、承包商的笔记本电脑等）：

1. 优先使用个人令牌，而非共享令牌 — 设置范围较窄的权限，并每 90 天轮换一次。
2. 使用操作系统钥匙串存储：security add-generic-password（macOS）、secret-tool（GNOME）、wincred（Windows）。让宿主配置在启动时从钥匙串读取令牌，而不是直接写入令牌。
3. 未来计划： v1.1 将支持在启动时通过 stdin 写入令牌，而不是通过 env 传递，从而消除令牌暴露在 /proc/PID/environ 中的风险。请关注问题 [token-via-stdin]，以便采用此功能。
4. 切勿将 claude_desktop_config.json 或同类文件提交到代码库，其中包含你的令牌。

环境变量

变量	必需	默认值	描述
QODFLOW_API_TOKEN	是	—	qf_live_… 或 qf_test_… PAT。
QODFLOW_API_BASE	否	https://www.qodflow.com	用于可自托管部署或本地开发的覆盖值。必须使用 www 主机名 — 根域名会重定向，Node 会在跨源跳转时移除身份验证标头。

开发

npm run dev   # tsx watch on src/index.ts

路线图：编写工具（创建任务、移动任务），然后读取审计日志，接着在 v1.1 中支持基于 HTTP 的托管传输和 OAuth。