Agent 接入(MCP)
Git Repo Sync 以 MCP(Model Context Protocol)Server 的形式向 Agent 开放仓库查询与同步触发能力,传输方式为 stdio。仓库配置只读:源与备份目标由本地仓库的 .git/config 派生,软件不代管克隆与远端,也不提供仓库增删改工具。仓库列表即物理实况——每次扫描基地址下的一级子目录得到,目录消失即从列表中移除。Agent 以子进程运行本程序的 mcp 模式,与图形界面访问同一个 SQLite 数据库,协议为换行分隔的 JSON-RPC 2.0。
客户端配置
先在软件设置页(或 MCP 页)复制 API Key,然后在支持 MCP 的 Agent 客户端中配置(路径按平台调整):
json
{
"mcpServers": {
"git-repo-sync": {
"command": "C:\\Program Files\\GitRepoSync\\git-repo-sync.exe",
"args": ["mcp"],
"env": { "GIT_REPO_SYNC_API_KEY": "<你的 API Key>" }
}
}
}鉴权说明
- APIKEY 通过环境变量
GIT_REPO_SYNC_API_KEY或--api-key参数提供(参数优先级更高),与软件设置页的 API Key 一致方可访问 - 可在设置页随时重新生成 API Key,重新生成后需同步更新客户端配置
可用工具
| 工具 | 说明 |
|---|---|
list_repos | 列出基地址内的仓库(实时扫描物理目录)及最近同步状态 |
sync_repo | 立即同步指定仓库(name,异步) |
sync_repos | 批量触发同步:names 列表或 days 范围(0=全部,N=最近 N 天未同步,含从未同步,与界面范围一致);未配置仓库自动跳过,按仓库报告是否启动 |
stop_syncs | 停止同步:终止排队与运行中的任务(names 可选,缺省全部活动任务),跨进程生效;返回出队与标记停止的仓库 |
get_sync_status | 查询所有仓库最近同步状态 |
list_logs | 按时间倒序列出操作日志(limit 可选,默认 200、上限 1000;只读不写日志) |
get_base_dir | 查询本地仓库基地址 |
set_base_dir | 修改本地仓库基地址 |
工具语义
仓库身份即基地址下的目录名 name:
- 列表即物理实况:仓库列表每次扫描基地址下的一级子目录得到——含
.git的目录即为仓库,源地址与备份目标由.git/config派生。目录消失即从列表中移除、也不再参与同步,重新放回即自动回来 - 仓库配置只读:软件不代管克隆与远端,也不提供仓库增删改工具——请自行把仓库 clone 到
{基地址}/{仓库名}中转目录,并用git remote add <远端名> <地址>添加备份目标 upstream为保留远端名:扫描时排除(fork 上游不参与同步,避免把 fork 反向推送回原仓库)
帮助
协议提供 help 方法,返回与命令行 --help 完全相同的帮助文本(命令、环境变量、仓库来源约定、工具清单与参数口径):
json
{"jsonrpc": "2.0", "id": 1, "method": "help"}Agent 可据此自助了解用法,无需查阅文档。
多语言
- MCP 工具描述、参数描述与运行时消息按 Agent 客户端
initialize请求的locale字段返回 - 可用环境变量
GIT_REPO_SYNC_LANG(zh/en)强制指定 - 均未提供时默认中文;工具名称为协议契约,不随语言变化
稳定性
- GUI 与 MCP 子命令共用同一 SQLite(WAL + 5 秒 busy_timeout,多进程写冲突等待而非报错)
- 同步执行者单例(守护角色):GUI 与 MCP 均可发起同步,任务经 SQLite 队列投递、由唯一执行者(数据目录
sync-daemon.lock竞选产生)串行消费,杜绝两条流水线并发操作同一中转目录;停止请求同样经 SQLite 传递,跨进程生效 - 单请求异常被捕获并以 JSON-RPC 内部错误应答,进程不退出
- 客户端断开后进程会等待在途同步完成再退出,不会中断同步
- 每个请求的方法与耗时输出到 stderr,便于排查断连类问题