# flow-control-mcp

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

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

## 1. Install

```bash
npm install -g flow-control-mcp
```

本地开发：

```bash
npm install
npm run build
```

Node.js 要求 `>=20`。

## 2. Generate Claude Code Config

```bash
flow-control-mcp config claude --json
```

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

```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

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

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

开发门禁：

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

打包：

```bash
# 默认：不包含 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`：

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

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

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