fluxgit-mcp-server

fluxgit-mcp-sidecar

mcp-name: io.github.fluxgit-hq/fluxgit-mcp-server

以安全为先的 Git 模型上下文协议（MCP）服务。

AI Agent 负责检查，FluxGit 掌控全局。

一个 Rust MCP 服务，包含面向 AI 编码 Agent 的 38 项契约：25 个只读工具和 13 个人工审核操作工具（12 项提案，以及取消待处理提案的工具）。Sidecar 绝不执行 Git 写入操作；它会将已批准的提案转交给 FluxGit 桌面应用。

有关上下文预算对比，请参阅公开的 Git 上下文 token 基准测试。其中发布了测试样本、原始输出、脚本和校验和，包括全面的 CLI 测试和规模较小、经人工调优的反例。

---

为什么要开发它

人们越来越多地要求 AI 编码 Agent 操作真实的代码仓库：解释分支状态、总结差异、查找丢失的提交、建议安全的后续步骤。要做好这些工作，Agent 需要比 git status 更丰富、且便于推理的结构化 Git 上下文。要确保安全，Agent 绝不能在未经人工批准后果的情况下，悄悄修改引用、强制推送、丢弃工作或应用补丁。

其他 MCP Git 服务只能二选一：严格保持只读（实用性有限），或直接开放写入工具（存在危险——Agent 会产生幻觉，提示词可能遭到投毒，失误会造成破坏）。此 Sidecar 两者都不选。检查操作经过架构验证并受到范围限制；操作则通过写入与 UI 握手完成：Agent 提出提案，FluxGit 显示预览，用户在应用中批准，然后 FluxGit 通过安全管线执行，并提供还原点和审计记录。

---

提供的功能

25 个只读工具

工具	用途
repo.brief	一次调用掌握情境——分支、领先/落后状态、正在进行的操作、工作树摘要、贮藏、汇总的子模块偏移、近期提交、检测到的惯例和后续步骤提示。推荐作为 Agent 会话的首次调用；取代 6-10 次原始 git 调用，并经过专门设计以控制 token 预算
repo.scope	单体仓库范围界定——一次调用即可查看某个子树的工作树变更、近期提交、变更频率（指定时间范围内的提交数和作者）以及 CODEOWNERS 所有者
repo.status	工作树、当前分支、脏路径
repo.refs	分支、标签、远程仓库、贮藏
repo.branchStack	当前分支与上游 / 基础 / 相关分支的关系
repo.history	分页提交历史
repo.reflog	变动时间线及恢复提示
repo.conflictPreflight	在运行合并/变基前预测其结果
conflict.read	以结构化数据呈现活动冲突——正在进行的操作、生成提交的 ours/theirs、逐文件阶段分类、基础/ours/theirs 内容（限制大小并标记二进制文件），以及冲突标记区域的行范围。不再需要解析 <<<<<<< 乱麻
commit.details	单个提交的元数据和变更文件
worktree.changes	逐路径工作树变更摘要
worktree.list	所有工作树（主工作树 + 已链接工作树），包含分支/分离状态、HEAD SHA 和锁定/可修剪标记——并行 Agent 工作树的只读基础
submodule.status	子模块列表及状态
diff.text	标准文本补丁（兼容 git diff）
diff.semantic	经能力协商的语义说明
diff.semanticFallbacks	从语义模式回退到文本模式的路径
fleet.radar	多仓库关注队列
fleet.digest	自某个时间点以来整个仓库群发生了哪些变化——多个仓库的 HEAD 和本地分支 reflog 变动，按时间从新到旧排列，并受 maxEvents 限制（默认值为 200，最大值为 1000）。若省略 repoPaths，则使用 FluxGit 在允许根目录内登记的仓库。identity 与 Git 记录的内容完全一致（即已配置的身份，并非某个人或 Agent 的证明）；rewrote 标记丢弃了先前末端的变动（reset、amend、rebase、强制移动）。仅读取 reflog 文件；不会获取或写入任何内容
agents.presence	当前有哪些其他编码 Agent 正在此仓库中工作——仅依据本地来源（正在运行的 Agent 进程及其子进程、Agent 自身的会话存储、它们保存在仓库中的文件、内置 Agent 的编辑器，以及 FluxGit MCP 在线状态记录）。对每个 Agent，提供已知的 state（working/open/recent）、sources、分支、最近使用的工具和相对于仓库的文件。名称取自各工具或 MCP 客户端对自身的声明。不包含你自己的 MCP 记录；可能属于你本人会话的发现会标记为 likelyCaller。绝不返回提示词、消息或文件内容
safety.timeline	根据还原点 + reflog 综合生成的安全事件
safety.eventDetails	深入查看某个时间线事件
flux.latestRestorePoint	最新的 FluxGit 还原点
flux.restorePoints	还原点列表
flux.restorePointDetails	某个还原点及其变更前/后的引用
operation.status	按 previewId 查询权威异步状态；预览返回 accepted: true 后进行轮询，且在状态变为终态前不要报告 Git 操作结果

13 个需通过 UI 握手的写入工具

所有 12 个 operation.preview.* 提案在配置完成后都会通过 FluxGit 网关分发。sidecar 会 POST 提案，执行一次有界状态读取，通常立即返回 accepted: true、规范的 previewId、当前状态和 nextAction.tool: "operation.status"。人工审核继续进行期间，FluxGit 应用会显示“Requested by AI agent”批准卡片。代码 10003 专用于桥接缺失、无效或无法访问的情况；它不表示人工审批超时。 全部 12 个预览架构都接受可选的、有长度限制的 idempotencyKey。只有在重试同一个逻辑意图时才复用它；sidecar 会按操作类型限定其作用范围，因此重试会解析到现有的网关提案。对于新意图，应省略此键——即使其他参数相同也是如此——此时 sidecar 会发送一个基于 UUID 的新键。因此，预览工具仍会标示 idempotentHint: false。

工具	用途	网关分发
operation.preview.merge	提议合并，供人工审核	POST /v1/mcp/operation/preview/merge → 在 FluxGit 中生成审批卡片
operation.preview.rebase	提议执行非交互式 rebase	interactive: true 会在 POST／创建卡片之前因架构验证失败；已接受的请求会 POST /v1/mcp/operation/preview/rebase，并打开一张警告卡片，提示此操作会改写历史记录
operation.preview.discard	提议丢弃工作树更改	POST /v1/mcp/operation/preview/discard → 显示针对特定路径的警告；FluxGit 在丢弃匹配的更改前要求先创建安全暂存
operation.preview.reset	提议执行 soft／mixed／hard reset	POST /v1/mcp/operation/preview/reset → 生成与模式对应的卡片（hard 模式会强制要求明确确认）
operation.preview.patch	提议应用 Agent 生成的补丁	POST /v1/mcp/operation/preview/patch → 以等宽字体预览补丁，并提供 applyToIndex 开关
operation.preview.plan	提议执行由 1-10 个步骤组成的序列，步骤可使用五种受支持的类型（merge、rebase、discard、reset、patch）	POST /v1/mcp/operation/preview/plan → 生成编号步骤卡片；破坏性步骤需要勾选明确的复选框。带有 interactive: true 的 rebase 步骤会在分发前因架构验证失败；执行会在首次失败时停止。计划执行前的检查点仅锚定分支提交：受保护的恢复会还原 HEAD／受跟踪文件，而原始索引、工作树和未跟踪文件则需要通过单独的步骤快照／Safety Timeline 恢复界面恢复
operation.preview.worktree	提议为并行任务创建隔离的工作树（非破坏性；绝不会触及历史记录）	POST /v1/mcp/operation/preview/worktree → 生成包含分支、目标路径和原因的审批卡片；通过与手动点击相同的工作树创建操作执行
operation.preview.commit	提议暂存并附带消息提交（非破坏性；不支持 amend）	POST /v1/mcp/operation/preview/commit → 审批卡片会列出将要暂存并提交的确切文件；通过常规提交流程执行（钩子、签名、策略）；完成后返回新的 SHA
operation.preview.push	提议将分支推送到远程（可选设置上游；force-with-lease 会显示高风险警告）	POST /v1/mcp/operation/preview/push → 生成包含远程、分支信息的审批卡片，并在适用时显示强制推送警告；通过受保护的推送流程执行
operation.preview.branch	提议从起点创建分支（并可选择切换到该分支）	POST /v1/mcp/operation/preview/branch → 生成包含名称、起点和是否切换分支选项的审批卡片
operation.preview.branchDelete	提议在一个或多个仓库中删除已合并的本地分支（targets，最多 20 个仓库 × 每个仓库 20 个分支，总计 100 个）。Agent 指定分支名称；由 FluxGit 决定哪些分支可删除。绝不会触及远程分支	POST /v1/mcp/operation/preview/branchDelete → 卡片会原生检查每个分支，并保留任何在 HEAD 或其上游中不存在其提交、在任何位置已检出或其尖端已移动的分支；每个已删除分支的尖端都会记录在 Fleet 分支删除历史记录中，可通过 Restore 重新创建。完成后会返回每个分支的 deleted／failed／skipped 结果
operation.preview.submodulePointer	提议记录（record，需要 message）或返回到（return）任意深度的一个子模块指针（parentPath + relativePath）。可选的 expectedRecordedOid／expectedCheckedOutOid 固定值取自 submodule.status	POST /v1/mcp/operation/preview/submodulePointer → record 会通过 Git 自身的提交操作，只在父仓库中提交 gitlink（钩子和签名照常生效；不会推送任何内容）；return 会以分离状态检出已记录的提交，并将此前的检出状态记录为恢复点。子模块必须已初始化、干净，且当前指针与已记录的指针不同
operation.cancel	按 previewId 取消 Agent 自己仍待处理的提议	POST cancel；该卡片会像已过期的提议一样从用户队列中消失
所有写入提案都必须提供自由文本 reason，以便用户在审批弹窗中看到 Agent 给出的理由。所有提案都使用相同的持久化网关生命周期（`pending → approved → executing → completed	failed，并包含拒绝／取消／过期分支），以及 UI 中相同的 Tauri 桥接层。六个垫片涵盖待处理、可恢复、批准、认领、拒绝和完成。重启后，只有在重新验证仓库／引用并认领后，已批准的提案才能继续执行；正在执行的提案会显示出来供用户明确协调，绝不会盲目重新执行。已批准操作捕获还原点时，完成结果中的 result` 会公开这些恢复元数据，以便 Agent 如实报告，而无需猜测。

审批环节会有意采用默认拒绝的策略。FluxGit 会将提案的 repoPath 解析为其对应的规范打开仓库 ID，并要求该 ID 与用户正在审核的仓库一致；路径无法解析、不匹配或仓库切换都会阻止执行。工具参数会在分派前以及由网关再次验证。可选的声明式 Agent 策略可以在提案卡片打开前拒绝提案。其规则会匹配 sidecar 转发的 agentId（经过清理、由客户端自行声明的 clientInfo.name，例如 claude-code），并可限制该 Agent 可执行的操作、引用，以及通过 pathConstraints 限制仓库和工作树路径前缀。如果已配置 FLUXGIT_MCP_AGENT_POLICY，但文件缺失、无法读取、格式错误或不受支持，网关将不会启动。未配置策略时，兼容性仍保持宽松，但每项操作仍必须经过人工审批。

同一仓库中的其他 Agent（冲突提示）

每个 operation.preview.* 结果都可能包含可选的 otherAgents 对象： agents.presence 在提案所在仓库中发现的其他 Agent；如果双方都列明了各自的文件（丢弃和提交操作的 paths、补丁标头、计划步骤、submodulePointer 的子模块目录），还会包含 overlappingPaths。此信息仅供参考：它是在网关作出决定后添加的，绝不会阻止提案，也不会改变审批方式。禁用 Agent 检测时不会提供此信息。

"otherAgents": {
  "informational": true,
  "agents": [{ "agent": "codex", "state": "working", "sources": ["process", "session"],
               "branch": "codex/fix-login", "lastTool": "apply_patch",
               "files": ["src/login.rs"], "overlappingPaths": ["src/login.rs"],
               "pid": 4242, "lastActivityMs": 1790000000000, "mcpClient": null,
               "sameAgentAsCaller": false }],
  "agentCount": 1, "overlappingAgentCount": 1, "proposalPathsKnown": true,
  "omittedLikelyCaller": 1, "note": "Informational only: ..."
}

检测在本地进行且只读：其他 Agent 的 SQLite 存储会以只读方式打开，检测器只会输出仓库相对路径、工具名称、分支和时间。设置 FLUXGIT_MCP_AGENT_DETECTION_DISABLED（任意值）即可关闭检测：此时 agents.presence 会返回 10011，预览中也不会包含提示。

每个 sidecar 还会记录其客户端使用过的仓库，以便桌面应用和其他 sidecar 查看：<run_dir>/presence/mcp/<pid>.json（0600），其中包含自行声明的 clientInfo 名称和版本，以及每个仓库的规范路径、时间和最近使用的工具名称。只会记录已接受的调用（Agent 策略拒绝的提案或因缺少 FluxGit 而被拒绝的提案不会记录）；正常退出时会删除该文件。设置 FLUXGIT_MCP_PRESENCE_DISABLED 即可关闭此功能。

编写协议详情

每个 operation.preview.* 调用都遵循相同的线缆协议。以 operation.preview.merge 为例：

1. Sidecar POST 提案：

POST /v1/mcp/operation/preview/merge HTTP/1.1
Host: 127.0.0.1:59647
Content-Type: application/json

{
  "previewId": "1f3c5b9a-...-uuid",
  "agentId": "external-mcp-sidecar",
  "operationType": "merge",
  "repoPath": "/Users/dev/projects/checkout",
  "sourceRef": "feature/cart-redesign",
  "targetRef": "main",
  "reason": "Cart redesign work is complete; tests pass on the feature branch.",
  "strategy": "merge",
  "requestedAt": "2026-05-28T11:42:09.512Z"
}

2. Gateway 响应 202 Accepted：

{ "previewId": "1f3c5b9a-...-uuid", "status": "pending", "expiresAt": "2026-05-28T11:47:09.512Z" }

3. Sidecar 执行一次有界状态读取：

GET /v1/mcp/operation/status/1f3c5b9a-...-uuid HTTP/1.1
Host: 127.0.0.1:59647

如果提案仍处于有效状态，预览工具会迅速返回：

{
  "tool": "operation.preview.merge",
  "readOnly": false,
  "accepted": true,
  "previewId": "1f3c5b9a-...-uuid",
  "status": "pending",
  "nextAction": {
    "tool": "operation.status",
    "data": { "previewId": "1f3c5b9a-...-uuid" }
  }
}

这表示提案已成功提交，并不表示 Git 操作已成功。

4. 客户端持续轮询 operation.status，直到 gateway 报告终止状态：

{
  "previewId": "1f3c5b9a-...-uuid",
  "operationType": "merge",
  "status": "completed",
  "result": {
    "commitSha": "9a8b7c6d...",
    "restorePointId": "rp_2026_05_28_1142",
    "conflicts": []
  }
}

completed 会返回 isError: false。处于有效状态的 pending 或 approved 提案也会作为成功接受的结果返回，但不会声称 Git 已发生变化。任何非 completed 的终止状态（rejected、failed、expired、cancelled）都会连同结构化负载一起返回 isError: true，以便 Agent 报告实际结果，而不是凭空编造。

所有 12 个 operation.preview.* 工具都采用相同模式。只有请求正文中的字段和结果结构不同；提案提交、一次即时读取、异步 operation.status 后续处理以及错误语义均相同。公开的契约摘要维护在 fluxgit.com/features/mcp-agent-git。

---

边界：自由 Shell 与 FluxGit 驱动功能

即使未安装 FluxGit，sidecar 也能通过 MCP 通信。标准 Git 检查功能均可用（status、refs、history、reflog、diff.text 等）。需要 FluxGit 的工具会返回 JSON-RPC 错误代码 10001，并附带 upgradeHint，引导 Agent 完成安装和配置。

层级分类：

• 自由 Shell — 仅使用本地 git：repo.brief、repo.scope、repo.status、repo.refs、repo.branchStack、repo.history、repo.reflog、commit.details、worktree.changes、worktree.list、submodule.status、diff.text、conflict.read、fleet.digest。agents.presence 也不需要 FluxGit：它会读取本地 Agent 状态（以及存在时的 FluxGit MCP 存在记录）。
• 混合模式 — 在本地运行，并提供有文档说明的回退方案，同时由 FluxGit 丰富结果：fleet.radar、diff.semantic、diff.semanticFallbacks、repo.conflictPreflight。
• 需要 FluxGit — 如果没有 FluxGit，则返回 gateway_not_configured，因为仅根据本地 refs 合成这些结果会误导 Agent：safety.timeline、safety.eventDetails、flux.latestRestorePoint、flux.restorePoints、flux.restorePointDetails。
• 写入握手 — 通过 gateway 握手服务器路由至 FluxGit UI 审批。12 个 operation.preview.* 工具会迅速返回已接受且仍处于有效状态的提案，并通过 operation.status 继续处理；operation.cancel 会撤回由同一 Agent 发起的待处理提案。仅当桥接无法接受或提供握手服务时，才会使用代码 10003。

---

快速开始

安装已发布的 crate（会将 fluxgit-mcp-sidecar 放到 PATH 中）：

cargo install fluxgit-mcp-sidecar --locked

若要改为安装当前源代码分支：

cargo install --git https://github.com/fluxgit-hq/fluxgit-mcp-server fluxgit-mcp-sidecar --locked

或者从克隆的仓库构建：

# Build
cargo build --release

# Run as MCP server (stdin/stdout transport)
./target/release/fluxgit-mcp-sidecar

连接任何兼容 MCP 的 Agent

将下面的通用代码块粘贴到任意 MCP 主机配置中。无需针对特定客户端进行安装。

{
  "mcpServers": {
    "fluxgit": {
      "type": "stdio",
      "command": "/absolute/path/to/fluxgit-mcp-sidecar",
      "env": {
        "FLUXGIT_MCP_HANDSHAKE_ADDR": "127.0.0.1:59647",
        "FLUXGIT_MCP_AUDIT_LOG": "/optional/path/to/audit.jsonl"
      }
    }
  }
}

FLUXGIT_MCP_HANDSHAKE_ADDR 是由 FluxGit Quick Connect 生成的规范桥接地址。FLUXGIT_GATEWAY_ADDR 和 FLUXGIT_GATEWAY_URL 仍可作为兼容性回退选项。sidecar 仅接受显式指定端口、主机为回环地址的纯 HTTP；远程主机、凭据、路径、查询、片段、HTTPS 或缺少端口均会被拒绝。没有有效的本地桥接时，自由 Shell 层仍可使用。

FLUXGIT_MCP_AUDIT_LOG 用于启用仅追加的 JSONL 审计日志，记录每次 tools/call。参数会进行哈希处理；原始路径和标识符绝不会以明文形式写入。

---

语义差异契约

diff.semantic 是 AI Agent 使用最多、也最容易误用的工具。规则很严格：

只有当 data.supported 严格等于 true 时，才能将结果称为语义差异。

当 FluxGit 语义引擎不可用时（FluxGit 应用未运行、未配置网关地址，或仓库未在 FluxGit 中注册），diff.semantic 会返回：

{
  "tool": "diff.semantic",
  "readOnly": true,
  "data": {
    "supported": false,
    "fallback": "diff.text",
    "reason": "Semantic diff is not available in local sidecar fallback mode.",
    "textDiffArguments": { "repoPath": "...", "base": "...", "head": "...", "path": "..." }
  }
}

运行 FluxGit 应用并在 FluxGit 中注册仓库后，同一调用会通过网关的只读桥接，由 FluxGit diff-engine 提供服务，并返回 supported: true 和每个文件的语义差异块：

{
  "tool": "diff.semantic",
  "readOnly": true,
  "source": "fluxgit-gateway",
  "data": {
    "supported": true,
    "engine": "fluxgit-diff-engine",
    "files": [
      {
        "path": "src/main.rs",
        "fallbackToText": false,
        "hunks": [{
          "header": "fn main",
          "lines": [{
            "type": "modified", "oldLine": 3, "newLine": 3,
            "content": "let x = 2;", "oldContent": "let x = 1;",
            "changedTokens": ["2"], "oldChangedTokens": ["1"]
          }]
        }]
      },
      {
        "path": "logo.bin",
        "fallbackToText": true,
        "hunks": [],
        "reason": "The semantic engine could not parse this file (unsupported language, binary or unreadable source); use a text diff for it.",
        "textDiffArguments": { "repoPath": "...", "base": "...", "head": "...", "path": "logo.bin" }
      }
    ],
    "changedFiles": 2,
    "filesTruncated": false
  }
}

结果的准确性需落实到每个文件，而不只是每次调用：引擎无法解析的文件会带有 fallbackToText: true、原因以及可直接使用的 textDiffArguments，绝不会被合成为语义差异块。diff.semanticFallbacks 遵循相同的区分；连接后会列出引擎实际产生的每个文件回退记录。

已连接的 Agent 必须：

1. 调用 diff.semantic。
2. 读取 data.supported。
3. 如果为 true，使用语义负载并将结果标记为语义差异；但 fallbackToText: true 的条目必须标记为文本回退。
4. 如果为 false，使用 data.textDiffArguments 调用 diff.text，并将结果标记为文本差异回退。
5. 绝不要仅凭文本补丁推断函数或类级别的移动。

允许的表述：“FluxGit 报告此文件回退为文本差异”。 禁止的表述：当 supported=false 时说*“这是语义差异”*。

---

Presence 文件（哪个 Agent 在哪里工作）

除非设置了 FLUXGIT_MCP_PRESENCE_DISABLED，每个边车进程都会在本地保留一个文件 <FluxGit run dir>/presence/mcp/<pid>.json，以便 FluxGit 桌面应用显示已连接的编码 Agent 及其正在处理的仓库。文件仅包含 Agent 在 initialize 中声明的客户端名称和版本，以及每个仓库（最多 16 个）的已检查 repoPath、最近一次调用的时间和工具名称。不包含其他参数或结果。与审计日志不同，仓库路径会原样存储，以便桌面应用进行匹配；文件权限为私有（0700 目录中的 0600 文件），以原子方式重写，在正常退出时删除，24 小时后清理，且写入操作绝不会影响工具调用。客户端名称由其自行声明，并非经过身份验证的身份。

---

审计日志

除非设置了 FLUXGIT_MCP_AUDIT_DISABLED，边车会尝试将每个 tools/call 追加到共享的 JSONL 账本。网关会尝试通过同一个写入器追加人工决策。FLUXGIT_MCP_AUDIT_LOG 可覆盖路径；否则两个进程都会使用 <FluxGit run dir>/audit/mcp.jsonl（包括 FLUXGIT_RUN_DIR）：

{
  "id": "bdeca765-488c-4e2a-b86b-25cd734f2988",
  "timestamp": 1712345678901,
  "auditSchemaVersion": 1,
  "auditChainVersion": 1,
  "sequence": 42,
  "segmentId": "7ab6fa7a-c5bf-4d82-86a8-26b4728b5acd",
  "previousHash": "sha256:...",
  "entryHash": "sha256:...",
  "tool": "repo.status",
  "event_type": "tool_call",
  "repo_scope": "repoPath:sha256:...",
  "args_fingerprint": "sha256:...",
  "risk": "read",
  "approval": "none",
  "result": "success",
  "session_id": "my-agent",
  "duration_ms": 12,
  "summary": "...",
  "readOnly": true,
  "sidecarReadOnly": true,
  "signature": "base64url-ed25519",
  "signatureKeyId": "1a2b3c4d5e6f7a8b",
  "signatureVersion": 3
}

敏感路径和标识符会被哈希处理，绝不会以原文存储。一个稳定的跨进程锁会保护验证、轮换以及完整的追加和同步操作。每行最大为 256 KiB。活动日志段达到 4 MiB 时会轮换，最多保留四个已轮换的日志段；配置签名后还会生成已签名的检查点。

单条记录 Ed25519 签名（于 2026-05-28 发布）

审计签名为可选功能。当 FLUXGIT_MCP_AUDIT_SIGN_KEY 指向 PEM PKCS8 Ed25519 私钥时，每条追加的记录都会使用该密钥签名。签名记录会添加：

• signature — 对不含签名字段的记录规范 JSON进行签名后生成的 base64url（无填充）Ed25519 签名。
• signatureKeyId — 匹配的公钥的 16 位十六进制前缀，因此轮换的密钥可以共存于同一个 JSONL 文件中。
• signatureVersion: 3 — 当前的链式签名域；密钥 ID、序列号、 上一个哈希和记录哈希均包含在签名字节中。

规范 JSON 规则（验证器必须完全匹配）：递归地按 UTF-8 字节顺序对每个对象的键进行字典序排序；数组保留原有顺序；移除 signature；以紧凑格式序列化。对于版本 2 和 3，签名对象中保留 signatureKeyId 和 signatureVersion。对于没有版本号的旧版签名记录，验证器还会移除 signatureKeyId。

如果未设置环境变量，新记录会加入哈希链，但不会签名，以保持向后兼容。如果显式设置了环境变量，密钥为空、缺失、不安全、过大或无效时，审计启动会失败关闭；绝不会降级为输出未签名记录。

验证审计日志

sidecar 二进制文件也可用作验证器：

fluxgit-mcp-sidecar verify-audit /path/to/mcp.jsonl --pubkey /path/to/install.pub.pem

CLI 会以有界内存流式读取活动文件及保留的轮替文件。它会验证序列号、哈希、分段名称、检查点和签名，然后仅报告有界计数器（entries、chained、legacy、signed、 unsigned、segments 及保留的序列范围）。旧版逐条记录仍可读取和验证，但会报告为 legacy，绝不会作为防篡改链的一部分。若要进行严格的证据校验，请运行：

fluxgit-mcp-sidecar verify-audit /path/to/mcp.jsonl --pubkey /path/to/install.pub.pem --require-signed

成功时退出代码为 0；数据格式错误、哈希链或轮替损坏、签名错误，以及严格模式下存在任何未签名记录时，退出代码为 3；用法错误返回 2。

程序化验证完整账本时，请使用 verify_audit_ledger；较旧的 verify_audit_event_signature 仍可用于兼容的逐条记录检查。如果没有独立可信的外部锚点，本地哈希链无法证明整个保留历史（或其本地检查点）是否遭到删除或替换。经过签名的保留记录确实可以阻止没有私钥的攻击者重新计算被修改后的哈希链。

审计配置（包括显式指定的签名密钥）在启动时失败关闭。之后发生的文件系统或磁盘空间耗尽导致的追加失败，会记录为降级状态，但不会撤销工具响应或已持久化的网关生命周期转换；恢复时仍以网关生命周期日志为准。

---

协议详情

服务器支持两个协议时期：

• **2026-07-28（首选，无状态）：**调用 server/discover，然后在每个请求中包含 params._meta.io.modelcontextprotocol/protocolVersion 和 params._meta.io.modelcontextprotocol/clientCapabilities。 现代结果包含 resultType: "complete" 和服务器元数据；列表 结果还包含 ttlMs 和 cacheScope。tools/list 包含 title、inputSchema、outputSchema 和注解。tools/call 同时包含用于展示的 content，以及相同的 structuredContent 载荷。 只有提案工具和 operation.status 会在其 outputSchema 中声明 previewId、status、accepted 和 nextAction；除非对象 指定 "additionalProperties": false，否则 schema 对象均为开放对象。
• **2024-11-05（旧版兼容）：**较旧的宿主继续使用 initialize。旧版结果中会省略仅限现代协议的字段。

Stdio 输出采用标准的、以换行符分隔的 JSON-RPC 2.0：每行恰好一个紧凑的 JSON 值。结果中 content[0].text 的 JSON 也采用紧凑格式（不带缩进），且与 structuredContent 包含相同的键和值。仅用于输入的预标准 Content-Length 帧格式仍 被旧版 FluxGit 客户端接受；服务器绝不会发送此格式。帧大小上限为 8 MiB。JSON-RPC 通知不返回响应，不带 id 发送的请求方法不会执行。

现代版 tools/list 中有 38 个工具：25 个声明 annotations.readOnlyHint: true；12 个 operation.preview.* 工具和 operation.cancel 声明 readOnlyHint: false。这些注解描述 对宿主的影响；它们不是授权机制。

错误代码：

代码	含义
-32700	解析错误
-32600	无效请求（格式错误的 JSON-RPC）
-32601	未找到方法
-32602	参数无效或工具未知
-32603	内部错误
-32022	不支持的现代 MCP 版本；data 包含 supported 和 requested
10001	网关未配置 — 安装/启动 FluxGit 以使用 FluxGit 必需的工具
10002	已配置的 FluxGit bridge 没有可提供的载荷（例如，本地回退缺少绝对路径 repoPath）
10003	本地写入握手 bridge 缺失、无效或无法访问；不得据此推断任何提案已获接受
10004	提案未完成便已结束（rejected、failed、expired 或 cancelled）
10005	网关不知道所请求的 previewId（id 错误/从未获接受，或在终态保留期后被清理）。仅重启不足以证明可以提交新提案：Approved/Executing 记录会持久恢复，且必须先核实可能已启动的 Git 操作结果。
10006	网关在打开卡片之前拒绝了提案（策略、验证或配额原因）
10007	网关返回了格式错误/不安全的规范 previewId；sidecar 拒绝跟进
10010	本地只读 Git 命令失败
10011	Agent 检测已禁用（FLUXGIT_MCP_AGENT_DETECTION_DISABLED）；agents.presence 无法作答

---

状态

这是一个正在开发中的 MCP 服务。只读功能和全部 12 个 operation.preview.* 路由均已实现；operation.cancel 仅管理由同一自报 Agent id 发起的待处理提案。写入握手会在 FluxGit 中呈现审批卡片，并通过应用的受保护流水线完成。客户端会收到结构化的生命周期结果，而不是模拟的成功结果。clientInfo.name 是供策略、配额和审计使用的净化归因信息； 该值由客户端自行报告，绝不能视为经过身份验证的身份。

路线图

• 端到端演示视频 — 公开录制 Agent 提议 → 用户批准 → FluxGit 执行的完整流程，画面来自一次实时安装。
• 可导出的 CSV/JSON 审计日志 — 已交付：对每条记录进行 Ed25519 签名（2026-05-28）。剩余工作：为 FluxGit 应用的审计面板提供 CSV/JSON 导出和保留策略。
• HTTP / SSE 传输 — 用于云端 / 共享 MCP 主机部署。
• 官方 MCP Registry — io.github.fluxgit-hq/fluxgit-mcp-server 已上线，并指向已发布的 fluxgit-mcp-sidecar crate。

许可证

Apache-2.0。请参阅 LICENSE。

相关内容

• FluxGit — 生成 FluxGit 驱动上下文的桌面应用。
• MCP agent Git — 公开的产品和协议概述。
• Claude Code、Cursor 和 Codex — 设置和工作流指南。
• Git 上下文令牌基准测试 — 可复现的样例、原始输出、脚本和校验和。
• 公开源码 — 此 Apache-2.0 许可的服务。