Add MCP tool for on-demand Git documentation sync

This commit is contained in:
Joren de Graaf
2026-11-06 15:01:54 +01:00
parent 3a12d56f8b
commit 2a6450b416
3 changed files with 104 additions and 3 deletions
+2
View File
@@ -26,6 +26,8 @@ The Documentation page provides folder navigation, a sanitized Markdown view, se
Read-only MCP tools are `docs_list`, `docs_search`, `docs_read`, `docs_history`, and `docs_diff`. They use existing `projects:read` authorization and project membership. Search results return short snippets; reads return at most 250 lines or 30,000 characters with a continuation cue. Revisions must be retained commits for the requested path. MCP never returns Git credentials and does not accept arbitrary repository URLs or local filesystem paths. Codex working directly in a local checkout should read `docs/` there; remote clients use MCP.
`docs_sync(project, expected_remote_commit?)` lets a client with `projects:write` scope and project edit access request the same bounded refresh as the authenticated UI button. It returns `completed`, `already_current`, `in_progress`, or `failed` with the observed remote and indexed commits, document count, timestamps, safe error, and cooldown hint. `expected_remote_commit` must be a full Git hash; a different observed remote commit is reported as a failed expectation even if the new index was committed. Calls within the 30-second manual cooldown do not fetch again. A successful index refresh does not advance the separate documentation accuracy audit. After `completed`, clients can call `docs_list` or `docs_read` for the returned indexed commit.
## Recovery and rollback
If fetches fail, check the configured host allowlist, the repository's default branch and access, private credential scope, and mirror permissions. The last good index remains available. A subsequent successful refresh atomically replaces it, including deletions. To rebuild a corrupted mirror, stop both services, move only that project's UUID-named mirror directory aside, then refresh. Keep its old directory until the new index is verified if historical reads matter. Deleting a project removes its mirror after the database transaction commits. Database migrations and the previous application version are the application rollback path; preserve a database backup before rolling back schema changes. No documentation changes are pushed by the web app.