Skip to main content
Glama
Gemini Coding Harness MCP

Gemini Coding Harness MCP

Gemini Coding Harness MCP

面向 Gemini 桌面端(Mac Gemini.app Task 任务模式 / 对话) 与 Gemini CLI 的受控本地编程 Harness MCP 服务。

项目借鉴 DeepSeek Harness(dsh) 的「Agent = Model + Harness」与 三角色解耦 思想,把工程纪律与安全护栏下沉为 MCP 服务端硬规则,而不是只靠 Prompt 约束模型。直接暴露裸 fs / bash 容易导致盲改覆盖、输出撑爆上下文或误操作宿主机;本项目通过高内聚工具与强约束策略,让通用桌面客户端具备可靠、可校验、可回滚的本地代码工程能力。


核心设计理念

  1. 三角色解耦(Interfaces ↔ Policy ↔ Provider)

    • MCP 协议层(src/mcp/)与底层执行引擎(src/providers/)通过 HarnessProvider 接口解耦,后续可平滑替换为 Docker 沙箱或外部编码子代理,无需改动任何工具契约。

  2. 把“束缚”写进代码护栏

    • 白名单与只读锁:仅访问显式启用的注册仓库,支持单仓库切换 readOnly 只读锁定;拦截 ..、绝对路径、符号链接逃逸、.git/ 内部元数据,以及 .env、*.pem、*.key、SSH 私钥、credentials.json 等敏感文件。

    • 写前必读锁(Read-before-Edit):记录每个已读文件的 sha256;未在当前会话读取或磁盘内容已变更的文件拒绝改/覆写/删,file_edit 失配时自动返回最接近代码行与行号辅助自纠。

    • 命令、环境脱敏与 TTL:剥离宿主机 *_KEY/*_TOKEN/*_SECRET 等环境变量;支持高危黑名单(standard)与 命令前缀白名单(allowlist) 双模式;所有后台命令受 maxCmdRuntimeSec 硬超时约束。

    • 上下文输出预算(Context Budgeting):代码读取按完整行预算切分并输出 nextStartLine 精准续读;超长命令/diff 日志自动落盘至 runtime/logs/(7 天/100 份自动清理),支持 log_read(logId) 分页回看。

    • 磁盘持久化 Checkpoint:首次修改或删除任意文件前自动持久化原始快照到 runtime/checkpoints/,跨会话保留,随时通过 MCP 或控制台一键回滚。

  3. 控制面与执行面分离

    • 内置零依赖 本地可视化配置控制台(--ui,仅监听 127.0.0.1:18788),强制校验 Host、Origin 与随机 X-Harness-CSRF;LLM 永远无法通过 MCP 给自己扩容白名单或放宽安全限制。


Related MCP server: Remote Workstation MCP

架构总览

┌──────────────────────────────────────────────────────────┐
│  Gemini Desktop (Mac 本地 MCP stdio / Task 模式) 或 CLI   │
└────────────────────────────┬─────────────────────────────┘
                             │ JSON-RPC (stdio / Streamable HTTP)
                             ▼
┌──────────────────────────────────────────────────────────┐
│  [1] MCP Adapter 层 (src/mcp/create-server.ts)           │
│      14 个高内聚工具 + 工程纪律 Instructions + 审计记录   │
└────────────────────────────┬─────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────┐
│  [2] Harness Policy & State 层                           │
│   ├── Path & Env Guard:白名单/只读、禁敏感文件与环境变量 │
│   ├── Command Guard:黑名单 / allowlist 白名单模式 + TTL  │
│   ├── Output Budget:按行读取分页 + log_read + 自动清理   │
│   └── Session Store:sha256 锁 + 持久化 Checkpoint + 进程组│
└────────────────────────────┬─────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────┐
│  [3] Service Provider 层 (src/providers/)                │
│      fs-ops / cmd-ops / git-ops(iOS/Swift/Node/Go/Rust) │
└──────────────────────────────────────────────────────────┘

        ▲ 仅本机浏览器操作(完全隔离于 LLM)
┌───────┴──────────────────────────────────────────────────┐
│  本地可视化配置控制台 (127.0.0.1:18788, --ui)             │
│  Finder 选目录 · 父目录扫描 · 只读锁 · 一键回滚 · 审计    │
└──────────────────────────────────────────────────────────┘

14 个高内聚工具一览

针对桌面客户端工具往返特征优化,将高频探查、受控变更与校验流程合并为 14 个高语义工具:

类别

工具名

核心能力与内置护栏

工作区

workspace_list

列出当前已启用的白名单仓库、只读状态与已同步的客户端 MCP Roots

workspace_explore

单次返回目录聚簇摘要、文件骨架(支持 subdir)、Git 状态、规则文档与 scripts

只读

code_search

基于 ripgrep 的代码检索(自动排除 .git、node_modules 及敏感文件)

file_read_batch

单次批量读取 1–8 个文件(按完整行预算切分,带 nextStartLine 与 sha256 读锁)

git_diff_summary

查看 git status、diff --stat 与预算裁剪后的统一 diff

log_read

按 logId 分页读取被预算裁剪落盘到 runtime/logs/ 的完整命令/diff 输出

编辑

file_edit

多 hunk 精确唯一替换(需先读;失配时返回最近似行号片段),自动快照并返回 diff

file_create

新建文件(自动建父目录与快照;覆盖已存在文件需显式 overwrite=true 且已读)

file_delete

受写前必读锁与持久化 Checkpoint 保护的文件删除(可一键回滚恢复)

执行

cmd_run

策略校验与环境脱敏后执行命令;12 秒内同步返回,超时自动转后台并受 TTL 约束

cmd_poll

查询后台命令状态,支持 waitSeconds(0–10 秒)长轮询

cmd_stop

按进程组(-pid)安全终止运行中的后台命令

verify_run

运行校验命令;默认 25 秒内同步完成,大项目超时自动转后台 jobId 供轮询

回滚

checkpoint_manage

create / list / revert 跨会话持久化文件快照


环境要求

  • 操作系统:macOS(核心 MCP 服务亦可在 Linux 运行;Finder 选目录弹窗依赖 macOS osascript)

  • Node.js:20+(推荐 22 LTS)

  • 依赖工具:git、ripgrep(rg,建议通过 brew install ripgrep 安装;缺失时目录探索自动回退原生遍历)


快速开始(推荐:Mac Gemini.app 本地 stdio 模式)

1. 克隆并构建

git clone https://github.com/tihonovaaybeniz-code/gemini-coding-harness.git
cd gemini-coding-harness
npm install
npm run typecheck
npm run build

2. 打开可视化配置控制台添加仓库

npm run ui
# 或在 Finder 中直接双击项目根目录下的 Open-Config-UI.command

浏览器打开 http://127.0.0.1:18788 后,可零手写配置完成管理:

  • 工作区白名单:点击 「+ Finder 选择文件夹」 选择仓库,自动识别 Git 分支、技术栈与推荐 verifyCommands;支持随时点击开关启用/停用(改完热重载立即生效,无需重启 Gemini.app)。

  • 父目录自动发现:在 「父目录自动发现」 添加常用开发目录(如 ~/Projects),自动扫描候选仓库(自动跳过 Harness 自身目录),默认不放行,手动勾选开关才正式写入白名单。

  • MCP Roots 与安全策略:实时查看客户端是否在 --stdio 握手中支持 roots/list(自动过滤 /、$HOME 与 Harness 自身目录),并调整输出字节上限、同步超时与读取行数预算。

  • 调用审计 & 接入命令:查看 runtime/audit.jsonl 最近工具调用元数据,并一键复制客户端启动命令与技能文案。

手动配置方式:参考 harness.config.example.json 复制为 harness.config.json(已被 .gitignore 忽略;首次运行也会自动生成空配置)。

3. 接入 Mac Gemini.app(本地 MCP)

  1. 打开 Mac Gemini.app → 自定义 → 关联应用 → 添加自定义关联应用,选择 本地 MCP。

  2. 服务器名称:Gemini Coding Harness

  3. 命令:填入控制台「调用审计 & 接入命令」里生成好的完整绝对路径命令(桌面应用通常不继承 nvm 的 PATH,务必使用 node 绝对路径):

    /path/to/node /path/to/gemini-coding-harness/dist/index.js --stdio
  4. 沙盒设置:

    • 推荐选 完整访问权限(安全边界由 Harness 服务端白名单、路径/命令护栏与 Checkpoint 保障,后续在控制台增减仓库无需反复改系统沙盒);

    • 或选 自定义沙盒 并显式放行 gemini-coding-harness、目标仓库目录及 Node / Homebrew 路径。

  5. (推荐)配置「技能」:将 GEMINI_SKILL.md 内容粘入 Mac Gemini.app 顶部的 「技能」 面板,让模型在 Task 模式下稳定遵循先探查、写前必读、改完必验的工程流程。


对话提示词示例

在 Mac Gemini.app(普通对话或 Task 模式)中可直接发送:

连通性与工作区检查

请调用本地 MCP `Gemini Coding Harness` 的 `workspace_list`,列出当前可用工作区和 source 来源,不要修改任何文件。

受控开发任务模板

请使用本地 MCP `Gemini Coding Harness` 在工作区 `<仓库别名>` 中完成以下任务:
1. 先调用 `workspace_explore`、`code_search` 和 `file_read_batch` 阅读相关代码;
2. 动手前调用 `checkpoint_manage(action="create")` 建立回滚点,再使用 `file_edit` 小步修改;
3. 改完后必须运行 `verify_run` 和 `git_diff_summary`;
4. 仅依据真实工具结果汇报改动清单、核心 diff 与检查退出码。

其他接入方式

Gemini CLI(本地 stdio)

在 ~/.gemini/settings.json 中添加:

{
  "mcpServers": {
    "gemini-coding-harness": {
      "command": "/path/to/node",
      "args": ["/path/to/gemini-coding-harness/dist/index.js", "--stdio"]
    }
  }
}

Streamable HTTP 模式(可选,用于云端/Web 调试)

npm start
# 默认监听 http://127.0.0.1:18787/p/<64-hex-token>/mcp
# token 自动生成于 runtime/token.txt

如需配合需要公网 HTTPS 回调的客户端,可另起本地隧道(仅建议临时调试,或配合固定域名与强鉴权):

cloudflared tunnel --url http://127.0.0.1:18787 --no-autoupdate

项目结构

gemini-coding-harness/
├── .github/workflows/ci.yml      # GitHub Actions 自动 typecheck、build 与集成测试
├── src/
│   ├── index.ts                  # CLI 入口(--stdio / --http / --ui)与 MCP Roots 探测
│   ├── config.ts                 # 热重载配置、原子保存、动态 Roots 注册表
│   ├── errors.ts                 # 结构化可执行纠错异常(HarnessError)
│   ├── workspace-scanner.ts      # 多技术栈探测、verifyCommands 推荐、父目录扫描
│   ├── mcp/create-server.ts      # 14 个高内聚 MCP 工具注册与调用审计
│   ├── policy/
│   │   ├── path-guard.ts         # 路径越界、符号链接逃逸与敏感凭证拦截
│   │   ├── command-guard.ts      # 黑名单 / allowlist 前缀白名单命令护栏
│   │   ├── env-guard.ts          # 子进程敏感环境变量脱敏
│   │   ├── output-budget.ts      # 输出预算裁剪与报错行提取
│   │   └── runtime-cleanup.ts    # 日志自动清理与 JSONL 大小轮转
│   ├── state/session-store.ts    # Read-before-Edit sha256 锁、持久化 Checkpoint、TTL 进程组
│   ├── providers/
│   │   ├── types.ts              # HarnessProvider 抽象接口
│   │   ├── exec-utils.ts         # 原子写、只读锁检查与脱敏命令执行封装
│   │   ├── fs-ops.ts             # 目录探索、批量按行读取、模糊定位编辑与删文件/读日志
│   │   ├── cmd-ops.ts            # 同步/异步命令执行与异步化 verify_run
│   │   ├── git-ops.ts            # Git Diff 摘要与 Checkpoint 管理
│   │   └── local-provider.ts     # 本地 Provider 门面
│   └── ui/
│       ├── server.ts             # 本地控制面 HTTP API(Host/Origin/CSRF 保护)
│       └── page.ts               # 单页可视化控制台前端
├── scripts/
│   ├── e2e-verify.mjs            # Streamable HTTP 全链路与护栏验证
│   └── verify-ui-and-roots.mjs   # stdio MCP Roots、护栏全覆盖与 Web UI API 验证
├── harness.config.example.json   # 配置文件示例
├── GEMINI_SKILL.md               # Gemini 客户端配套技能文案
├── Open-Config-UI.command        # macOS Finder 双击启动控制台脚本
└── LICENSE                       # MIT License

本地开发与验证

npm run typecheck
npm run build
npm test

安全说明

  • harness.config.json(含本地仓库绝对路径)与 runtime/(含 token.txt、audit.jsonl、requests.jsonl、client-probe.json、logs/)默认被 .gitignore 忽略,所有运行态数据与日志均不写入目标业务仓库。

  • 可视化控制台仅绑定 127.0.0.1,所有变更接口均强制校验 Host、Origin 与每进程随机 X-Harness-CSRF。

开源协议

本项目基于 MIT License 开源。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      B
      maintenance
      Enables coding agents to perform workspace-confined file operations, read-only Git inspection, and structured shell commands, while requiring out-of-band human approval for mutations and external executions and maintaining an audit trail.
      14
      3
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to securely inspect and edit approved code, use semantic code intelligence, run builds/tests, supervise bounded processes, inspect Git, and execute owner-approved SSH commands on engineering workstations.
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to securely inspect, search, edit, build, and test explicitly authorized local development projects over MCP, with sandboxed filesystem access and sensitive-file protection.
      2
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables LLM clients to search, read, and patch a trusted source repository with rollback-safe edits, Git operations, and allowlisted validation over stdio or OAuth-protected HTTP. Keeps secrets and arbitrary shell access out of reach while enforcing bounded batched I/O and operator-controlled workspace trust.
      MIT