{"_id":"@artern/git-relay-mcp","name":"@artern/git-relay-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@artern/git-relay-mcp","version":"0.1.0","description":"A stdio MCP server that relays a local Git branch to remote agents through clone, head lookup, and patch replay tools.","author":{"name":"artern"},"homepage":"https://github.com/artern/git-relay-mcp#readme","bugs":{"url":"https://github.com/artern/git-relay-mcp/issues"},"repository":{"type":"git","url":"git+https://github.com/artern/git-relay-mcp.git"},"type":"module","bin":{"git-relay-mcp":"dist/index.js"},"publishConfig":{"access":"public"},"scripts":{"build":"node esbuild.js","watch":"node esbuild.js --watch","typecheck":"tsc --noEmit","test":"pnpm run build && node --test","prepublishOnly":"pnpm test","prepare":"pnpm run build"},"keywords":["mcp","git","mcp-proxy","format-patch","git-am","model-context-protocol","stdio"],"license":"MIT","engines":{"node":">=20.0.0"},"packageManager":"pnpm@10.33.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.25.76"},"devDependencies":{"@types/node":"^20.17.50","esbuild":"^0.25.4","typescript":"^5.8.3"},"_id":"@artern/git-relay-mcp@0.1.0","gitHead":"6c5b1f33e3bdafa56bba666f360d8ead2b6f5e06","_nodeVersion":"20.19.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-ZR+LdlmfIMRvqRF+E7TsQNurw5nbPsh3A8xfm2ZjfCePsA9ke0o32hNvV5ZFCbAPmvsCTsHvIr2lRhCi8agwYg==","shasum":"ba84a61a45b4840326dabca227036bba3e93cf27","tarball":"https://registry.npmjs.org/@artern/git-relay-mcp/-/git-relay-mcp-0.1.0.tgz","fileCount":7,"unpackedSize":1988269,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDTwbpbyaOkSRlfkOVYJ2RMX3ZcU1f/XOgZU7NNJFt6uQIhAMGkbr2ptbsc59eEzHL17uEelBwYzfTkAHi/DhCMDGHj"}]},"_npmUser":{"name":"artern","email":"artern@126.com"},"directories":{},"maintainers":[{"name":"artern","email":"artern@126.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/git-relay-mcp_0.1.0_1778338125777_0.27281658264949904"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-09T14:48:45.687Z","0.1.0":"2026-05-09T14:48:45.954Z","modified":"2026-05-09T14:48:46.150Z"},"maintainers":[{"name":"artern","email":"artern@126.com"}],"description":"A stdio MCP server that relays a local Git branch to remote agents through clone, head lookup, and patch replay tools.","homepage":"https://github.com/artern/git-relay-mcp#readme","keywords":["mcp","git","mcp-proxy","format-patch","git-am","model-context-protocol","stdio"],"repository":{"type":"git","url":"git+https://github.com/artern/git-relay-mcp.git"},"author":{"name":"artern"},"bugs":{"url":"https://github.com/artern/git-relay-mcp/issues"},"license":"MIT","readme":"# Git Relay MCP\n\n[English README](./README.md)\n\nGit Relay MCP 是一个基于 stdio 的 MCP Server，设计目标是配合 `mcp-proxy` 使用，让远端 AI agent 能在不直接访问本地文件系统的前提下，对 NodeG 上某个本地 Git 仓库分支进行克隆、读取 HEAD 和回放补丁。\n\n## 能力概览\n\n- `clone_tar`：对配置好的分支执行深度 1 克隆，移除 `origin`，再把整个克隆目录打成 tar 并以 base64 返回。\n- `get_head`：返回当前分支 HEAD 的 commit id 和少量提交元数据。\n- `apply_patch_series`：把 `git format-patch --stdout` 产出的 mbox 补丁流通过 `git am --3way` 回放到目标分支。\n\n## 使用方式\n\n```bash\npnpx mcp-proxy -- pnpx -y @artern/git-relay-mcp --repo /path/to/local-git-repo --branch dev-001\n```\n\n其中：\n\n- `--repo` 是标准参数名\n- `--local` 仍然可用，但只作为兼容别名\n- `--branch` 必须是本地分支名，且不能是 `master`、`main`、`dev`\n\n## 启动校验\n\n服务启动时会检查：\n\n- 仓库路径存在\n- 路径是一个 Git working tree\n- 指定分支存在于本地 `refs/heads/`\n- 分支名不是 `master`、`main`、`dev`\n\n任何一项不满足，服务都会直接拒绝启动。\n\n## 典型工作流\n\n1. NodeG 通过 `mcp-proxy` 启动本服务。\n2. NodeA 连接该 MCP 服务并调用 `clone_tar`。\n3. NodeA 解包 tar，得到一个可继续提交的浅克隆仓库。\n4. NodeA 在该克隆目录中进行修改和提交。\n5. NodeA 调用 `get_head` 获取 NodeG 当前分支的 HEAD。\n6. NodeA 基于该 HEAD 执行 `git format-patch ..HEAD --stdout`。\n7. NodeA 调用 `apply_patch_series`，把补丁流和 `expectedHead` 发回 NodeG。\n\n## Tool 契约\n\n### `clone_tar`\n\n输入：`{}`\n\n输出字段：\n\n- `repoName`\n- `branch`\n- `headCommit`\n- `archiveFormat`\n- `mediaType`\n- `encoding`\n- `shallow`\n- `depth`\n- `includesGitDir`\n- `originPolicy`\n- `suggestedDirectoryName`\n- `archiveData`\n\n### `get_head`\n\n输入：`{}`\n\n输出字段：\n\n- `repoName`\n- `branch`\n- `headCommit`\n- `headShortCommit`\n- `headAuthorName`\n- `headAuthorEmail`\n- `headCommittedAt`\n- `headSubject`\n\n### `apply_patch_series`\n\n输入字段：\n\n- `expectedHead`：必须精确等于 `get_head` 返回的 `headCommit`\n- `patchContent`：`git format-patch --stdout` 生成的原始 mbox 文本\n\n输出字段：\n\n- `repoName`\n- `branch`\n- `previousHead`\n- `expectedHead`\n- `newHead`\n- `appliedCommitCount`\n- `appliedCommitIds`\n- `usedThreeWayMerge`\n- `workingTreeCleanAfterApply`\n\n## 运行注意事项\n\n- `apply_patch_series` 会按仓库分支串行执行，避免并发回放。\n- 如果 `git am` 中途失败，服务会尽力执行 `git am --abort` 做清理。\n- 服务可能会在 apply 前把工作区切换到配置的目标分支。\n- tool 结果中不会暴露 NodeG 上的绝对仓库路径。\n\n## 开发与测试\n\n```bash\nnvm use 20\npnpm install\npnpm build\npnpm test\n```\n\n当前自动化测试覆盖：\n\n- 成功链路：`clone_tar`、`get_head`、`apply_patch_series`\n- `expectedHead` 过期拒绝\n- `git am` 失败后的自动 `--abort` 回滚\n- 启动时禁止主分支名校验\n\n## 发布到 npm\n\n```bash\nnpm login\npnpm test\nnpm publish --access public\n```\n\n当前包名已准备为 `@artern/git-relay-mcp`。\n\n## 提交到 GitHub 前建议\n\n建议仓库地址使用：\n\n- `https://github.com/artern/git-relay-mcp`\n\n当前 `package.json` 已预置该仓库地址、主页地址和 issue 地址；如果你最终使用了别的仓库名，再同步修改即可。","readmeFilename":"README.zh-CN.md","_rev":"1-5f191492d38b9533faaf77cdfb05be61"}