flow-control-mcp

极简、稳定的业务控制原语 MCP Server。

flow-control-mcp 只做一件事：把 Agent/Skill 调用的 flow.* 业务控制工具，写成 .runs/state.json.businessControl 中可验证、可审计、可调度消费的结构化事实。

1. Install

npm install -g flow-control-mcp

本地开发：

npm install
npm run build

Node.js 要求 >=20。

2. Generate Claude Code Config

flow-control-mcp config claude --json

输出可作为跨用户共享模板：

{
  "mcpServers": {
    "flow-control-mcp": {
      "command": "flow-control-mcp",
      "args": [],
      "env": {
        "FLOW_MCP_REQ_PATH": "${FLOW_MCP_REQ_PATH}"
      }
    }
  }
}

FLOW_MCP_REQ_PATH 应由 Agent Runtime 按会话注入；不同会话可以注入不同 request path。

前提：目标环境已通过 npm install -g flow-control-mcp 安装，并且 flow-control-mcp 在 Runtime PATH 中可用。Server 启动时仍会校验 Node.js >=20。

3. Verify

flow-control-mcp doctor --req-path /absolute/request/path --json

doctor 会检查实际 Node 路径、Node 版本、.runs、control-context.json、state.json、写权限和锁。

开发门禁：

npm run typecheck
npm run build
npm test
npm run test:integration
npm pack --dry-run

打包：

# 默认：不包含 runtime dependencies，安装时由 npm 拉取依赖
npm run pack:default

# 离线部署：包含 runtime dependencies
npm run pack:bundled

Contract

• Server 名称：flow-control-mcp
• Tools：flow.finish、flow.pause、flow.resume、flow.rewind、flow.abort
• Context：FLOW_MCP_REQ_PATH/.runs/control-context.json
• State：FLOW_MCP_REQ_PATH/.runs/state.json.businessControl
• Logs：运行日志只写 stderr；stdout 只用于 MCP 协议或 CLI 输出

最小 control-context.json：

{
  "runId": "run-123",
  "stage": "design",
  "actionIndex": 1
}

更多 Claude Code、Linux、Windows 和故障定位说明见 docs/claude-code.md。

Skill 中如何调用 5 个业务控制原语见 docs/skill-usage.md。