Skip to content

Agent Access (MCP) ​

Git Repo Sync exposes repository inspection and sync triggering to agents as an MCP (Model Context Protocol) server over stdio. Repository configuration is read-only: the source and backup targets are derived from each local repository's .git/config; the app neither manages clones and remotes nor offers tools to add, edit or remove repositories. The repository list is the physical reality — it is produced by scanning the first-level subdirectories of the base directory on every call, and a directory that disappears leaves the list. Agents run the app's mcp mode as a child process; it talks newline-delimited JSON-RPC 2.0 and shares the same SQLite database as the GUI.

Client Configuration ​

Copy the API Key from the app's Settings (or MCP) page first, then configure your MCP client (adjust the path per platform):

json
{
  "mcpServers": {
    "git-repo-sync": {
      "command": "C:\\Program Files\\GitRepoSync\\git-repo-sync.exe",
      "args": ["mcp"],
      "env": { "GIT_REPO_SYNC_API_KEY": "<your API key>" }
    }
  }
}

Authentication ​

  • Provide the API key via the GIT_REPO_SYNC_API_KEY environment variable or the --api-key argument (the argument wins); it must match the key shown on the Settings page
  • You can regenerate the key on the Settings page at any time — update your client configuration afterwards

Available Tools ​

ToolDescription
list_reposList the repositories under the base directory (scanned live from disk) with their latest sync status
sync_repoSync one repository immediately (name, asynchronous)
sync_reposTrigger syncs in bulk: a names list or a days range (0 = all, N = stale within N days, including never-synced — same semantics as the UI); unconfigured repositories are skipped and reported
stop_syncsStop syncing: terminate queued and running tasks (names optional, defaults to all active tasks), effective across processes; returns the dequeued and stop-flagged repositories
get_sync_statusQuery the latest sync status of all repositories
list_logsList operation logs newest-first (limit optional, default 200, max 1000; read-only, writes no log)
get_base_dirGet the local base directory
set_base_dirChange the local base directory

Tool Semantics ​

A repository's identity is its directory name name under the base directory:

  • The list is the physical reality: the repository list is produced by scanning the first-level subdirectories of the base directory on every call — any directory containing .git is a repository, and its source and backup targets are derived from .git/config. A directory that disappears leaves the list and stops participating in syncs; putting it back brings it back automatically
  • Repository configuration is read-only: the app neither manages clones and remotes nor offers tools to add, edit or remove repositories — clone the repository into the {base directory}/{repo name} relay directory yourself, and add backup targets with git remote add <remote> <url>
  • upstream is a reserved remote name: it is excluded when scanning (a fork's upstream never participates in syncing, so a fork is never pushed back to its origin)

Help ​

The protocol provides a help method that returns exactly the same help text as the command-line --help (commands, environment variables, the repository conventions, the tool list and parameter names):

json
{"jsonrpc": "2.0", "id": 1, "method": "help"}

Agents can learn how to use the server from it, without reading the docs.

Localization ​

  • Tool descriptions, parameter descriptions and runtime messages follow the locale field of the client's initialize request
  • The GIT_REPO_SYNC_LANG (zh / en) environment variable overrides it
  • Chinese is the default when neither is given; tool names are protocol contracts and never localized

Stability ​

  • The GUI and the MCP subprocess share one SQLite database (WAL + 5s busy_timeout: write conflicts wait instead of erroring)
  • Single sync executor (daemon role): both the GUI and MCP can start syncs; tasks are delivered through a SQLite queue and consumed serially by the one executor (elected via a sync-daemon.lock file in the data directory), so two pipelines never operate on the same relay directory concurrently; stop requests travel through SQLite too and take effect across processes
  • A per-request exception is answered as a JSON-RPC internal error; the process keeps running
  • After a client disconnects, the process waits for in-flight syncs to finish before exiting
  • Each request's method and duration are written to stderr, which helps diagnose disconnects