@artern/git-relay-mcp
v0.1.0
Published
A stdio MCP server that relays a local Git branch to remote agents through clone, head lookup, and patch replay tools.
Maintainers
arternReadme
Git Relay MCP
Git Relay MCP 是一个基于 stdio 的 MCP Server，设计目标是配合 mcp-proxy 使用，让远端 AI agent 能在不直接访问本地文件系统的前提下，对 NodeG 上某个本地 Git 仓库分支进行克隆、读取 HEAD 和回放补丁。
能力概览
clone_tar：对配置好的分支执行深度 1 克隆，移除origin，再把整个克隆目录打成 tar 并以 base64 返回。get_head：返回当前分支 HEAD 的 commit id 和少量提交元数据。apply_patch_series：把git format-patch --stdout产出的 mbox 补丁流通过git am --3way回放到目标分支。
使用方式
pnpx mcp-proxy -- pnpx -y @artern/git-relay-mcp --repo /path/to/local-git-repo --branch dev-001其中：
--repo是标准参数名--local仍然可用，但只作为兼容别名--branch必须是本地分支名，且不能是master、main、dev
启动校验
服务启动时会检查：
- 仓库路径存在
- 路径是一个 Git working tree
- 指定分支存在于本地
refs/heads/ - 分支名不是
master、main、dev
任何一项不满足，服务都会直接拒绝启动。
典型工作流
- NodeG 通过
mcp-proxy启动本服务。 - NodeA 连接该 MCP 服务并调用
clone_tar。 - NodeA 解包 tar，得到一个可继续提交的浅克隆仓库。
- NodeA 在该克隆目录中进行修改和提交。
- NodeA 调用
get_head获取 NodeG 当前分支的 HEAD。 - NodeA 基于该 HEAD 执行
git format-patch <head>..HEAD --stdout。 - NodeA 调用
apply_patch_series，把补丁流和expectedHead发回 NodeG。
Tool 契约
clone_tar
输入：{}
输出字段：
repoNamebranchheadCommitarchiveFormatmediaTypeencodingshallowdepthincludesGitDiroriginPolicysuggestedDirectoryNamearchiveData
get_head
输入：{}
输出字段：
repoNamebranchheadCommitheadShortCommitheadAuthorNameheadAuthorEmailheadCommittedAtheadSubject
apply_patch_series
输入字段：
expectedHead：必须精确等于get_head返回的headCommitpatchContent：git format-patch --stdout生成的原始 mbox 文本
输出字段：
repoNamebranchpreviousHeadexpectedHeadnewHeadappliedCommitCountappliedCommitIdsusedThreeWayMergeworkingTreeCleanAfterApply
运行注意事项
apply_patch_series会按仓库分支串行执行，避免并发回放。- 如果
git am中途失败，服务会尽力执行git am --abort做清理。 - 服务可能会在 apply 前把工作区切换到配置的目标分支。
- tool 结果中不会暴露 NodeG 上的绝对仓库路径。
开发与测试
nvm use 20
pnpm install
pnpm build
pnpm test当前自动化测试覆盖：
- 成功链路：
clone_tar、get_head、apply_patch_series expectedHead过期拒绝git am失败后的自动--abort回滚- 启动时禁止主分支名校验
发布到 npm
npm login
pnpm test
npm publish --access public当前包名已准备为 @artern/git-relay-mcp。
提交到 GitHub 前建议
建议仓库地址使用：
https://github.com/artern/git-relay-mcp
当前 package.json 已预置该仓库地址、主页地址和 issue 地址；如果你最终使用了别的仓库名，再同步修改即可。