Skip to content

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,便于排查断连类问题