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):
{
"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_KEYenvironment variable or the--api-keyargument (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
| Tool | Description |
|---|---|
list_repos | List the repositories under the base directory (scanned live from disk) with their latest sync status |
sync_repo | Sync one repository immediately (name, asynchronous) |
sync_repos | Trigger 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_syncs | Stop 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_status | Query the latest sync status of all repositories |
list_logs | List operation logs newest-first (limit optional, default 200, max 1000; read-only, writes no log) |
get_base_dir | Get the local base directory |
set_base_dir | Change 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
.gitis 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 withgit remote add <remote> <url> upstreamis 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):
{"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
localefield of the client'sinitializerequest - 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.lockfile 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