carlos-flow MCP Server
Provides Git-based repository change tracking and enforcement: comparing working-tree changes against a scope whitelist using git diff, analyzing diff hunks, snapshotting files before dispatch, and generating atomic revert plans.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Carlos Flow
AI 编码 Agent 的机械门禁(Mechanical Gate)
留痕 → 派发 → 验证 → 裁定 → 审计 → 还原
把「相信 Agent」变成「验证 Agent」——约束写在代码里,不写在提示词里。
📌 这是什么(TL;DR)
Carlos Flow 是一个 MCP Server,为 AI 编码 Agent 提供可执行、可审计、不可自欺的工作流门禁。
普通 Agent 工作流的问题在于:约束都是建议性的。
你说 | Agent 实际做的 |
"只改 | 客气地点头,然后把半个仓库重写了 |
"跑一下测试" | 汇报"测试通过",其实根本没跑 |
"记录一下过程" | 在普通文件里写几行日志 —— 可删可改 |
Carlos Flow 的做法是:约束全部落在代码里,用运行时事实校验,不信自述。
越界?→ 运行时
git diff对比卡片白名单,直接阻断派发说测试通过?→ 真实
spawn执行verify.cmd,记 PASS 前必须有通过的 exitCode审计日志?→ 链式哈希(
prevHash→hash),改一条全链断裂。 设了CARLOS_FLOW_AUDIT_KEY时用 HMAC-SHA256(带密钥)→ 攻击者重算不出,只能发现不能隐藏想跳过?→ 免检需显式
confirmed=true,且每次派发自动清零 审计文件按本地日期分片,prevHash一律联动前一天的 tail,跨天不断链。 未设密钥时(plain模式)走裸 SHA-256:只能防意外损坏, 不能防有意篡改;verifyAuditChain()的回传带了mode字段(plain/hmac), 调用方自行判断强度。审计记录(audit())和状态文件(saveState()) 写之前先脱敏——密钥片段不入盘。
一句话:它把「代码评审的门禁」搬到了 AI Agent 上,而且门禁本身是机器执行、不是人执行。
Related MCP server: MonoMCP Gateway
🎯 解决的 8 个真实问题
# | 问题 | 传统现状 | Carlos Flow 的机械化答案 |
1 | 越界改动 | "只改这些文件"是建议不是规则 |
|
2 | 验证表演 | Agent 自述"测试通过",无人能证明 |
|
3 | 可洗白审计 | 普通文件日志 —— 可删可改 | 链式哈希审计,改一条全链断裂;跨天链联动前一天 tail;审计记录与落盘状态均脱敏后写; |
配 | |||
4 | 失控免检 | 一句话关闭所有防护 | 需卡片显式 |
5 | 无限派发 | 领卡即重置计数,可无限重试 |
|
6 | 自证式复核 | 同一 Agent 既实现又审批 | 内置 |
7 | 改坏无法回退 | 只能手动 | 派发前自动快照 → |
8 | 每次手动喊话 | 不喊就不启动,忘了就裸奔 | 智能触发引擎自动识别意图,评分达标才触发并解释命中了什么 |
✨ 核心亮点
1. 零分叉的跨平台架构
一套核心 MCP Server,6 大平台开箱即用。平台差异只在初始化模板,核心逻辑零分叉。
carlos-flow (单一 npm 包)
├── src/index.js ← 核心 MCP Server(纯标准协议,零平台耦合)
├── client/carlos.js ← CLI + init --target <平台>
├── bridge/ ← Cindy 专属:后台常驻 Bridge
├── plugins/ ← OpenCode 专属:chat.message 钩子
└── templates/ ← Cursor / Cline / VS Code / Claude 模板2. 智能触发引擎 —— 工作流会自己认出该上场的时候
三层架构,每次决策都给出可解释的 breakdown(命中了哪些词、多少分、为什么)。
L1 动态上限:
5 + 会话时长×0.5 + 复杂度×2 − 窗口内已触发×0.3,封顶 15L2 三维评分:关键词 50 / 上下文 30 / 意图 20,加权满分 38
L3 四档决策:
trigger/review/ignore/throttled
中文流程词内置(工作流/门禁/派发/审计/任务卡/子代理…),普通开发需求不会误触发。
3. 反自欺的激活闸门
自动触发不等于直接放行。激活后进入 activation_pending 状态:
在 scope / acceptance / verify.cmd 补齐之前,flow_claim / flow_dispatch / flow_verdict 一律拒绝。
防的是「占位卡 → 直接派发 → 直接记 PASS」的假闭环。
4. Fail-closed 语义
空 scope 判定为全部越界(而不是"白名单为空=随便改")。这是安全默认值,不是业务默认值。
5. 变异测试守护
13 类变异体(注入退化)13/13 全部被测试抓住。锚点唯一性由 npm run check:anchors 守护,防止测试"静默失去守护作用"。
6. 跨进程并发安全
flow_submit_requirement 的读-改-写被包在跨进程排他锁里(mkdir 原子性)。
红队实测 40 轮并发复现 4 次的状态丢失,现在泄漏 0/453。
🏗️ 技术框架
整体架构
flowchart TB
subgraph Host["宿主 Agent 平台"]
Cindy[Cindy<br/>ghost.json]
OpenCode[OpenCode<br/>plugin + .mcprc]
Cursor[Cursor / Cline<br/>VS Code / Claude]
end
subgraph Client["客户端层"]
CLI["client/carlos.js<br/>CLI + init + 触发检查"]
Bridge["bridge/mcp-bridge.js<br/>常驻守护 + Token 认证"]
Plugin["plugins/carlos-flow-trigger.js<br/>chat.message 钩子"]
end
subgraph Core["核心 MCP Server (src/index.js) — 16 个工具"]
Protocol["flow_protocol"]
Submit["flow_submit_requirement"]
Dispatch["flow_claim / flow_dispatch"]
Verify["flow_run_verify / flow_falsify / flow_check_scope"]
Verdict["flow_verdict"]
Audit["flow_status / flow_audit"]
Trigger["flow_trigger_check"]
end
subgraph Engine["智能触发引擎 (src/trigger.js)"]
L1["L1 DynamicTriggerManager"]
L2["L2 TriggerScorer"]
L3["L3 TriggerDecisionEngine"]
end
subgraph Storage["持久化层 (CARLOS_FLOW_HOME)"]
State["gate-state/runs/<sid>/"]
AuditLog["gate-audit/YYYY-MM-DD.jsonl<br/>SHA-256 链式"]
Snap["snapshots/"]
TrigState["trigger-state/"]
end
Cindy --> CLI
OpenCode --> Plugin
Cursor --> CLI
Plugin --> Trigger
CLI --> Bridge
Bridge --> Core
Core --> Engine
Core --> Storage
Engine --> TrigState分层职责
层 | 位置 | 职责 | 平台耦合 |
宿主适配层 |
| 发现、启动、配置、生命周期 | ⚠️ 唯一有平台差异的层 |
客户端层 |
| CLI、触发检查、Bridge 守护 | 仅 Cindy 需要 Bridge |
协议层 |
| 16 个 MCP 工具 + 参数校验 + 门禁语义 | ✅ 零耦合,纯标准 MCP |
引擎层 |
| 触发评分、卡片校验、状态/审计 | ✅ 零耦合,纯 JS 无依赖 |
持久化层 |
| 状态、审计链、快照、触发历史 | ✅ 跨平台路径约定 |
核心设计原则:MCP 协议是被动的 —— 服务端不能主动推送。 因此「自动触发」必须由能拿到用户消息的那一侧发起(宿主插件钩子 或 Agent 主动调用
flow_trigger_check)。 两条路径共用src/trigger.js同一份实现,行为完全一致。
📊 能力矩阵
能力 | Carlos Flow | 原生 MCP Server | 提示词 / 手写脚本 |
越界拦截 | ✅ 自己跑 | ❌ | ❌ 靠自觉 |
真实验证 | ✅ spawn + 捕获,无证据不许 PASS | ❌ | ❌ Agent 自述 |
审计链完整性 | ✅ 链式哈希(+ 可选 HMAC),跨天串联,落盘脱敏 | ❌ | ❌ |
可控免检 | ✅ 显式开启 + 自动清零 | ❌ | ❌ 一句话全关 |
诚实派发配额 | ✅ 只计派发 | ❌ | ❌ |
独立复核 | ✅ 内置 | ❌ | ❌ 可选 |
快照 + 还原 | ✅ 自动、原子计划 | ❌ | ❌ 手动 |
守护进程生命周期 | ✅ 全自动(Cindy) | ❌ 手动 | ❌ 手动 |
智能触发 | ✅ 三层评分 + 可解释决策 | ❌ | ❌ |
跨平台 | ✅ 单一包 6 平台 | ⚠️ 需自己写配置 | ❌ |
信任边界说明:手工改
state.json里的 verdict 能伪造 PASS —— 状态文件不在审计哈希链内。 这是本地文件系统权限的信任边界,不是 MCP 工具面能被绕过的漏洞: 能写CARLOS_FLOW_HOME的人本来就能改自己的代码。 还要注意:(1)未设CARLOS_FLOW_AUDIT_KEY时是plain模式(裸 SHA-256),ok: true不是「没被篡改过」的证明,调用方看mode字段; (2)审计记录与状态(verify.cmd/token/password)脱敏后入盘,密钥片段不留明文。 完整说明见 QA 验收报告 §六。
📦 安装
npm install -g carlos-flow⚠️ 报
ETARGET: No matching version found?这是 npm 的 registry 元数据缓存没刷新:npm cache clean --force npm view carlos-flow versions # 验证版本存在
兼容性要求:Node.js ≥ 22.0.0 | MCP SDK ≥ 1.29.0 | 零运行时外部依赖
🖥️ 平台支持
一个包,六个平台。初始化命令会生成对应平台的配置文件。
平台 | 初始化命令 | 生成产物 | 平台专属能力 |
Cindy |
|
| Bridge 自动守护 + Settings UI |
OpenCode |
|
|
|
Cursor / Windsurf |
| 项目 | — |
Cline |
| 项目 | — |
VS Code (Copilot) |
| 项目 | — |
Claude Desktop |
| macOS: | — |
💡 所有平台共用同一套配置字段:
CARLOS_FLOW_HOME(状态目录)+node <root>/src/index.js(stdio 启动)。
🚀 快速开始
1. 安装并初始化
npm install -g carlos-flow
carlos-flow init --target <你的平台> # cindy | opencode | cursor | cline | vscode | claude2. 环境变量(可选,都有默认值)
CARLOS_FLOW_HOME=~/.carlos-flow # 状态/审计目录(跨平台统一)
CARLOS_FLOW_MCP_ROOT=/path/to/carlos-flow # 源码安装时指向仓库根目录
BRIDGE_PORT=19099 # Cindy Bridge 端口路径一律用正斜杠(
/home/you/apps/carlos-flow)或双反斜杠(D:\\apps\\carlos-flow)。 单反斜杠在配置里会被当成转义符,\c、\o会被吃掉,路径直接失效。
3. 验证服务正常
node client/carlos.js flow_status '{"sessionId":"probe"}'期望输出 "has_card": false 即表示服务正常。
4. 走一次完整门禁
# ① 留痕(记录用户原话,作为 quote 锚点数据源)
node client/carlos.js flow_add_user_msg '{"sessionId":"demo","text":"给登录接口加参数校验"}'
# ② 提交任务卡(scope 是白名单)
node client/carlos.js flow_submit_requirement '{"sessionId":"demo","goal":"加参数校验","quote":"给登录接口加参数校验","scope":["src/auth.py"],"acceptance":["非法参数返回 400"],"verify":{"cmd":"npm test"},"cwd":"/path/to/project"}'
# ③ 领取派发名额
node client/carlos.js flow_claim '{"sessionId":"demo","role":"executor"}'
# ④ 派发(自动快照 scope 内文件)
node client/carlos.js flow_dispatch '{"sessionId":"demo","role":"executor"}'
# ⑤ 真实执行验证命令
node client/carlos.js flow_run_verify '{"sessionId":"demo","cwd":"/path/to/project"}'
# ⑥ 记录裁定(没有验证通过证据不许记 PASS)
node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes":"测试通过"}'🔧 MCP 工具参考(16 个)
工具 | 作用 | 关键约束 |
| 读取完整门禁协议(档位、四段合同、错误分层) | — |
| 写入用户原话 | quote 锚点的唯一数据源 |
| 提交/替换任务卡 | 按风险档强制必填项;伪填充被拒 |
| 领取派发名额(executor / auditor) | 激活闸门未解时拒绝 |
| 按四段合同派发子 Agent | 派发前自动快照 scope 内文件 |
| 保存子 Agent 执行结果 | — |
| 真实执行 | 返回 exitCode / stdout / stderr + |
| 负对照:改动前跑 verify.cmd 必须失败、改动后必须通过 | 空测试(` |
| 检查文件是否越界 | 空 scope → fail-closed 全部越界 |
| 记录裁定 PASS / DIRECTION / LOCAL | 未派发不许 PASS;验证未过不许 PASS;负对照未过不许 PASS |
| 查询门禁状态 | 暴露 |
| 读取审计流水 | 含 6 类激活相关事件 |
| 解析 | — |
| 开关免检模式 | 需 |
| 生成原子还原计划 | 只返回计划,不自动执行 |
| 智能触发检查 | 达标即实际激活;未达标如实返回评分 |
⚙️ 配置
触发器配置
路径:$CARLOS_FLOW_HOME/trigger-config.json(首次 init 自动生成)
{
"keywordWeights": {
"评审": 5
},
"readOnlyIntentWords": ["讲一下"],
"mutatingActionWords": ["重构一下"]
}合并语义(重要):
keywordWeights→ 对象合并(自定义词覆盖同名默认词,其余默认词保留)词表数组 → 追加去重(扩展,不是替换)
其余标量 → 覆盖
早期实现是浅合并,用户写一个自定义词就把整个默认词表(含内置中文流程词)丢掉 —— 中文场景重新变回 0 分。已修复。
环境变量
变量 | 默认值 | 说明 |
|
| 状态 / 审计 / 快照目录。 |
| 自动推导 | 源码安装时指向仓库根目录 |
|
| Cindy Bridge 监听端口 |
| 随机生成落盘 | Bridge 本地认证 token(自动生成,存 0600) |
| — | 设置它(≥16 字符)启用 HMAC 审计链 —— 发现有意篡改必须配它 |
|
| Bridge 请求超时(需 > 服务端 120s 验证上限) |
|
| CLI 客户端 MCP 调用超时 |
| — | CLI 模式下注入触发检查用的用户原话 |
| 多路探测 | OpenCode 会话库路径(读用户原话用) |
🛡️ 门禁体系 —— 门禁自己也要被门禁
「项目说自己有门禁」是最容易说的一句话,也最容易被证伪。 所以本项目的门禁自己也有一套门禁,且分两类:
一、静态一致性(东西对不对得上)
脚本 | 查什么 |
| 旧引用 / 个人路径 / 版本号一致性 / 文档死链 / npm 发布集合 / 模板占位符 / package.json 字段 / 双仓残留 / ghost.json 工具清单 |
| 身份、版本、文档、产物、安全五类一致性 |
| 提交信息与源码注释是否中文(产物语言体检) |
| 中英双语 README 是否漂移 |
| 变异体的注入锚点是否仍能命中(防止测试静默失去守护作用) |
二、行为兑现(说了的做到了吗)—— 这一类才是关键
脚本 | 查什么 | 为什么需要 |
| README/工具描述里的每个能力声明,是否都有对应的代码路径 | 静态检查查不出「承诺 vs 实现」的落差 |
|
| 静默失效型 bug(如 |
| 同一 request schema 是否被重复注册 | 重复注册时后注册的覆盖先注册的 → 先注册的是永不执行的死代码,靠注册顺序维持的正确性会被一次重排静默破坏 |
三、变异测试 —— 用注入退化撞自己最自豪的代码
npm run test:mutation # 17 类变异体,必须 17/17 全部被抓住变异体不是随机造的,每一条都对应一个真实退化,且必须有测试能抓住它:
变异体 | 注入的退化 | 抓住它的测试 |
M1 | 激活只打印日志、不真的激活 | e2e |
M2 / M3 | claim / verdict 的闸门失效 | e2e |
M4 | 会话撞名(清洗后同形共用状态) | trigger |
M5 / M6 | scope 不算补齐项 / 半补齐绕过 | e2e |
M7 | 空 scope 退回 fail-open | e2e |
M8 | 未派发可记 PASS | e2e |
M9 | 闸门派生回退(用上一轮 pending 传递) | e2e 19d-3 |
M10 / M11 | 普通卡也上闸 / 占位卡硬编码三项 | e2e |
M12 | 跨进程锁失效( | concurrency |
M13 | 只读意图误判 | trigger |
M14 | 审计链断链(去掉 prevHash 链接) | audit-chain |
M15 | 审计链校验恒真 | audit-chain |
M16 | 越界检查退回 fail-open | scope-enforcement |
M17 | date 参数失效 | audit-chain |
四、专项真实验证(不靠 mock)
脚本 | 验什么 |
| 在真实 git 仓库里改文件 → scope 外改动真的被阻断;派发前就有的改动不误伤 |
| 真实篡改审计记录 → hmac 模式必须发现;plain 模式如实标注局限;legacy 记录不误报;date 参数真的生效 |
跨天链连通不留断点;脱敏检查确保密钥片段不留明文 | |
| 端口上是别人的 bridge 时不得复用(否则状态会写到别人的 HOME) |
|
|
| 语言体检脚本真的能抓到英文(防假绿) |
💡 给质疑者的可执行入口:上面每一条命令都可以自己跑一遍。 一个项目宣称「我的门禁是机械的」,最好的证明不是文档,是让对方自己跑一遍。
🧪 开发
git clone https://github.com/skyer-now/carlos-flow.git
cd carlos-flow
npm install
# 全套测试(129 个用例)
npm run test:all
# 单项
npm run test:e2e # 端到端 62 项
npm run test:p0 # P0 门禁 22 项
npm run test:trigger # 触发引擎 29 项
npm run test:concurrency # 跨进程并发 3 项
npm run test:acceptance # 验收 13 项
npm run test:mutation # 变异测试(13/13 变异体全抓住)
npm run check:anchors # 变异锚点唯一性守护
npm run check:readme # 双语 README 一致性
# 打包
npm pack测试覆盖矩阵
套件 | 数量 | 覆盖内容 |
| 4 | 卡片解析 / 校验 / 状态往返 |
| 62 | 全流程 + 激活闸门 + 假闭环防护 + 越界拦截 |
| 22 | P0 级门禁语义(伪填充、类型校验、fail-closed) |
| 29 | 三层引擎 + 会话隔离 + 配置合并 + |
| 3 | 跨进程并发零泄漏 / 零利用 |
| 13 | MCP 路径触发 + 中文词表 + 插件真实开卡 |
合计 | 129 | 全部通过 |
📚 文档
文档 | 说明 |
智能触发引擎深度指南(配置、评分、激活、反馈学习) | |
版本历史(Keep a Changelog + SemVer) | |
从 | |
变更前置索引:改哪类东西先读哪份权威契约 | |
第三方审查报告的逐条核实与决策记录 | |
第三方只读验收(13/13 变异体全抓住) | |
变异体注入细节与结果 |
❓ 常见问题
普通 MCP Server 暴露工具,但不施加约束 —— 它信任调用方会正确使用。
Carlos Flow 的约束在 服务端运行时强制执行:越界文件会被 enforceScope() 拦下,
没跑过验证就不许记 PASS,审计日志改一条就断链。
不需要。单一包对所有用户都是同一个安装体积(~106 KB), 不需要额外下载任何平台专属依赖 —— 只是模板文件不同。
不会。门禁状态是文件级持久化,无数据库、无网络、无常驻进程 (除 Cindy 版的 Bridge,它只在首次调用时拉起)。 触发引擎是纯 JS 计算,零依赖。
会。早期版本不会展开 —— path.normalize 只换分隔符,路径仍是字面量,
状态写到「当前目录下字面名为 ~ 的目录」里,位置诡异极易丢失。
现已统一展开(state.js / trigger.js 共用 expandHome()),并有回归用例守护。
免检需卡片上显式 confirmed=true,且 bypass_ts 必须晚于 card_ts(旧卡的免检不能作用于新卡)。
最关键的是:每次派发后自动清零 —— 免检只对当次派发生效,不会变成长期开关。
完全支持。中文流程词内置(工作流/门禁/派发/审计/复核/任务卡/子代理/流程/触发/执行/调度/留痕/裁定), 中文需求同样能触发;普通开发需求(「给接口加个参数校验」)不会误触发。
能,但已标记 Deprecated。迁移方式见 MIGRATION.md。
🔗 链接
仓库 | |
npm | |
问题反馈 | |
更新日志 |
🤝 贡献
欢迎 PR!提交前请确保:
npm run test:all # 129/0 全通过
npm run check:anchors # 变异锚点未失效
npm run check:readme # 双语 README 未漂移详见 CONTRIBUTING.md。
📄 License
MIT © Carlos Flow Contributors
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Governed MCP workflow automation for MSPs and agencies: approvals, durable state, signed evidence.
Remote MCP for Kiro release readiness, evidence binders, signoff, and CI approval receipts.
One MCP endpoint for your company's tools, with per-person sign-in, policy and audit.
Governed MCP gateway for business apps: roles, previews, approvals and one audit log.
1
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables users to define and run MCP tools using declarative YAML configs with built-in trust enforcement, credential brokering, and tamper-evident audit logging.14MIT

MonoMCP Gatewayofficial
FlicenseNot gradedqualityBmaintenanceA unified MCP layer that serves organization toolkits as MCP endpoints with per-tool permissions, an async approval queue, and full audit logging.-- AlicenseNot gradedqualityCmaintenanceEnables centralized proxy and orchestration of MCP servers, providing unified tool discovery, authentication, and secure request routing. It adds a human-in-the-loop approval gate for high-risk actions and audit logging.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables users to trace regulatory rule changes to affected parties and required actions through deterministic safety gates, returning dated action plans and hash-linked evidence records. Supports 12 MCP tools over stdio or streamable HTTP for source comparison, obligation decomposition, scope assessment, planning, and evidence validation across multiple domain packs.MIT