Gemini Coding Harness MCP
Provides Git repository inspection and diff tooling for local workspaces, including git status, diff --stat, unified diff summaries, and checkpoint-based rollback of file changes.
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.
Gemini Coding Harness MCP
面向 Gemini 桌面端(Mac Gemini.app Task 任务模式 / 对话) 与 Gemini CLI 的受控本地编程 Harness MCP 服务。
项目借鉴 DeepSeek Harness(dsh) 的「Agent = Model + Harness」与 三角色解耦 思想,把工程纪律与安全护栏下沉为 MCP 服务端硬规则,而不是只靠 Prompt 约束模型。直接暴露裸 fs / bash 容易导致盲改覆盖、输出撑爆上下文或误操作宿主机;本项目通过高内聚工具与强约束策略,让通用桌面客户端具备可靠、可校验、可回滚的本地代码工程能力。
核心设计理念
三角色解耦(Interfaces ↔ Policy ↔ Provider)
MCP 协议层(
src/mcp/)与底层执行引擎(src/providers/)通过HarnessProvider接口解耦,后续可平滑替换为 Docker 沙箱或外部编码子代理,无需改动任何工具契约。
把“束缚”写进代码护栏
白名单与只读锁:仅访问显式启用的注册仓库,支持单仓库切换
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 或控制台一键回滚。
控制面与执行面分离
内置零依赖 本地可视化配置控制台(
--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 个高语义工具:
类别 | 工具名 | 核心能力与内置护栏 |
工作区 |
| 列出当前已启用的白名单仓库、只读状态与已同步的客户端 MCP Roots |
| 单次返回目录聚簇摘要、文件骨架(支持 | |
只读 |
| 基于 |
| 单次批量读取 1–8 个文件(按完整行预算切分,带 | |
| 查看 | |
| 按 | |
编辑 |
| 多 hunk 精确唯一替换(需先读;失配时返回最近似行号片段),自动快照并返回 diff |
| 新建文件(自动建父目录与快照;覆盖已存在文件需显式 | |
| 受写前必读锁与持久化 Checkpoint 保护的文件删除(可一键回滚恢复) | |
执行 |
| 策略校验与环境脱敏后执行命令;12 秒内同步返回,超时自动转后台并受 TTL 约束 |
| 查询后台命令状态,支持 | |
| 按进程组( | |
| 运行校验命令;默认 25 秒内同步完成,大项目超时自动转后台 | |
回滚 |
|
|
环境要求
操作系统:macOS(核心 MCP 服务亦可在 Linux 运行;
Finder选目录弹窗依赖 macOSosascript)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 build2. 打开可视化配置控制台添加仓库
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)
打开 Mac
Gemini.app→ 自定义 → 关联应用 → 添加自定义关联应用,选择 本地 MCP。服务器名称:
Gemini Coding Harness命令:填入控制台「调用审计 & 接入命令」里生成好的完整绝对路径命令(桌面应用通常不继承
nvm的PATH,务必使用node绝对路径):/path/to/node /path/to/gemini-coding-harness/dist/index.js --stdio沙盒设置:
推荐选 完整访问权限(安全边界由 Harness 服务端白名单、路径/命令护栏与 Checkpoint 保障,后续在控制台增减仓库无需反复改系统沙盒);
或选 自定义沙盒 并显式放行
gemini-coding-harness、目标仓库目录及 Node / Homebrew 路径。
(推荐)配置「技能」:将 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
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Autonomous agent guardrails, bash sandboxing, MCP rugpull diffing & prompt firewalls.
Fail-closed policy guardrails for AI agents running kubectl, terraform, helm, and argocd.
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
Related MCP Servers
- FlicenseAqualityBmaintenanceEnables 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.143-
- AlicenseNot gradedqualityBmaintenanceEnables 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.2Apache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables 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.2AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables 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