@imenam/mcp-documentor 1.0.56 → 1.0.57

package/README.md

@@ -14,6 +14,7 @@ Connect it to Cursor, Claude Desktop, or any MCP-compatible agent to let your AI
 - **Proxy-aware** — integrates with the [proxy-setup](https://github.com/Imena/proxy-setup) for GUI exposure
 - **Links & structure** — `check_links`, `get_doc_tree`, `move_doc`, and `git_diff_doc` for maintenance workflows
 - **Image support** — upload images to a project's assets via `upload_image` (local file path) or directly from the GUI editor; images are stored per-project and rendered inline in the viewer and in PDF exports
+- **GitHub sync** — share your documentation across machines by backing the data directory with a private GitHub repo; the repo/token are fixed by the administrator via environment variables, and the agent can only `pull_docs` / `push_docs` / `sync_docs`
 
 ## Installation
 
@@ -59,6 +60,10 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 | `PROXY_URL` | No | URL of the proxy server to register and launch the GUI |
 | `MCP_DATA_DIR` | No | Overrides the default data directory (see Data storage) |
 | `READ_ONLY` | No | When set to `1`/`true`/`yes`, disables all create/update/delete tools and GUI write actions (read-only mode) |
+| `MCP_DOCUMENTOR_SYNC_REMOTE` | No | HTTPS URL of the private GitHub repo to sync with; enables GitHub sync when set |
+| `MCP_DOCUMENTOR_SYNC_BRANCH` | No | Branch to sync (default: `main`) |
+| `MCP_DOCUMENTOR_SYNC_TOKEN` | No | Fine-grained GitHub PAT used for HTTPS auth (see GitHub sync) |
+| `SYNC_PULL_ON_START` | No | Set to `false` to disable the automatic pull at server startup |
 
 Optional `.env` at the package root (directory containing `package.json` discovered from the installed binary) is loaded when present.
 
@@ -83,6 +88,11 @@ Optional `.env` at the package root (directory containing `package.json` discove
 | `list_projects` | List all documentation projects |
 | `set_project` | Switch the active project **for the GUI only** (not for MCP tools) |
 | `upload_image` | Upload an image from a local file path to a project's assets; returns the markdown link to insert |
+| `sync_status` | Show branch, ahead/behind counts, conflicted files, and uncommitted changes |
+| `pull_docs` | Pull updates from the remote (defensive fast-forward; reindexes new docs) |
+| `push_docs` | Commit local doc changes and push them to the remote |
+| `sync_docs` | Full sync: pull then push (push skipped if the pull reveals a conflict) |
+| `resolve_sync_conflict` | Bulk-resolve merge conflicts by keeping `mine` or `theirs`, then stage |
 
 ## Images in documents
 
@@ -110,10 +120,69 @@ The tool copies the file into `.docs-data/projects/{project}/assets/` and return
 - **URL tab** — paste any external image URL; the markdown link is inserted at the cursor position
 - **Project images gallery** — click any previously uploaded image to re-insert it
 
+## Syncing across machines with GitHub
+
+You can share documentation between several machines by backing the data directory with a **private** GitHub repository. The approach is git-based: only the human-readable markdown, assets, and the shared project list are versioned. Derived state (embeddings) is regenerated locally, and version history stays local to each machine.
+
+### What is and isn't synced
+
+| Synced (versioned) | Local only (gitignored) |
+|---|---|
+| `projects/**` (markdown + assets) | `embeddings.db` (regenerated after pull) |
+| `config.json` (project list) | `history.db` (per-machine version history) |
+| | `local-state.json` (active project) |
+
+### Setup
+
+The sync target is **administrator-controlled**: the repository, branch and token are read from environment variables and **cannot be set or changed by the agent**. The agent can only pull/push against whatever repo you configured.
+
+1. Create an **empty private repo** on GitHub (e.g. `my-docs`).
+2. Create a **fine-grained PAT** scoped to that single repo (Repository permissions → **Contents: Read and write**).
+3. Add the sync environment variables to your MCP client config, per machine:
+
+```jsonc
+{
+  "mcpServers": {
+    "mcp-documentor": {
+      "command": "npx",
+      "args": ["-y", "@imenam/mcp-documentor"],
+      "env": {
+        "MCP_DOCUMENTOR_SYNC_REMOTE": "https://github.com/<you>/my-docs.git",
+        "MCP_DOCUMENTOR_SYNC_BRANCH": "main",            // optional, defaults to "main"
+        "MCP_DOCUMENTOR_SYNC_TOKEN": "github_pat_..."
+      }
+    }
+  }
+}
+```
+
+The token is injected into the `origin` URL inside `.git/config` only (which git never commits) — it is never pushed.
+
+### Daily workflow
+
+- `sync_docs` — pull then push in one step (recommended).
+- `pull_docs` / `push_docs` — granular control.
+- `sync_status` — inspect ahead/behind, conflicts, and uncommitted changes.
+
+By default the server also performs a **defensive pull at startup**: it only fast-forwards a clean working tree and never overwrites local changes (disable with `SYNC_PULL_ON_START=false`). On the first run, a machine with no local data simply clones the remote.
+
+### Conflicts
+
+Because docs are plain markdown, merge conflicts are readable. When `pull_docs` reports a conflict:
+
+- edit the conflicted `.md` files directly (remove the `<<<<<<<` / `>>>>>>>` markers), **or**
+- run `resolve_sync_conflict` with `strategy: "mine"` or `"theirs"` to take one side in bulk,
+
+then run `push_docs` to publish the resolution. If you have **uncommitted** local changes while the remote has moved, the pull reports `diverged` without touching anything — push your changes first, then pull again.
+
+> Read-only machines (`READ_ONLY=1`) can still `pull_docs` and `sync_status`, but `push_docs`, `sync_docs`, and `resolve_sync_conflict` are disabled.
+
 ## Data Storage
 
 By default, data lives under **`.docs-data`** next to the resolved package root (the folder that contains `package.json` for the running install). Set **`MCP_DATA_DIR`** to use another directory. Contents include projects, SQLite/embeddings, and logs under `.docs-data/logs`. This tree is **not** part of the npm package; it is created at runtime.
 
+The active project is a machine-local preference kept in `local-state.json` (gitignored), separate from the shared `config.json`. On first run, a legacy `currentProject` stored in `config.json` is migrated automatically. GitHub sync settings live in environment variables, not on disk.
+
 ## License
 
 ISC

package/dist/shared/read-only.js

@@ -8,4 +8,7 @@ export const WRITE_TOOLS = new Set([
     "create_doc", "update_doc", "patch_doc", "move_doc", "delete_doc",
     "restore_doc_version", "refresh_file_snapshot", "reindex_embeddings",
     "prepare_export_bundle", "delete_export_bundle", "upload_image",
+    // Sync: pull_docs and sync_status stay allowed (read-only consumer machines
+    // still pull updates); these mutate local/remote state and are blocked.
+    "push_docs", "sync_docs", "resolve_sync_conflict",
 ]);

package/dist/src/core/git-sync.d.ts

@@ -0,0 +1,56 @@
+import type { StorageEngine } from "./storage-engine.js";
+export interface SyncStatus {
+    branch: string;
+    ahead: number;
+    behind: number;
+    dirty: string[];
+    conflicted: string[];
+}
+export type PullResult = {
+    status: "up-to-date";
+} | {
+    status: "updated";
+    changed: string[];
+} | {
+    status: "diverged";
+    ahead: number;
+    behind: number;
+} | {
+    status: "conflict";
+    conflicted: string[];
+};
+export declare class SyncEngine {
+    private storage;
+    private git;
+    private dataDir;
+    constructor(storage: StorageEngine);
+    isConfigured(): boolean;
+    /**
+     * Builds an authenticated HTTPS URL by injecting the PAT. The result is only
+     * ever stored in .git/config (which git never commits), never versioned.
+     */
+    private authedUrl;
+    private requireConfig;
+    /**
+     * Ensures the data dir is a git repo with a .gitignore and an authenticated
+     * origin. The token is stored only in .git/config (which git never commits),
+     * so normal origin-based fetch/push work and upstream tracking — required for
+     * ahead/behind detection — stays accurate.
+     */
+    ensureRepo(): Promise<void>;
+    status(): Promise<SyncStatus>;
+    /**
+     * Defensive pull: only fast-forwards a clean working tree. Never auto-merges
+     * a divergent history, so local data is never silently overwritten.
+     */
+    pull(): Promise<PullResult>;
+    private diffNames;
+    /** Stages versioned files, commits if there is anything to commit, and pushes. */
+    push(message?: string): Promise<{
+        pushed: boolean;
+        committed: boolean;
+        message: string;
+    }>;
+    /** Bulk-resolve conflicts by taking one side, then stage the resolved files. */
+    resolveConflict(strategy: "mine" | "theirs", paths?: string[]): Promise<string[]>;
+}

package/dist/src/core/git-sync.js

@@ -0,0 +1,215 @@
+import fs from "fs";
+import path from "path";
+import { simpleGit } from "simple-git";
+import { createLogger } from "@imenam/mcp-gui-interface";
+const logger = createLogger("GitSync");
+const GITIGNORE_CONTENT = [
+    "# Derived / machine-local state — never synced",
+    "embeddings.db",
+    "embeddings.db-shm",
+    "embeddings.db-wal",
+    "history.db",
+    "history.db-shm",
+    "history.db-wal",
+    "*.db-shm",
+    "*.db-wal",
+    "logs/",
+    "temps/",
+    "errors-tmp-files/",
+    "export-bundles.json",
+    "local-state.json",
+    "",
+].join("\n");
+export class SyncEngine {
+    storage;
+    git;
+    dataDir;
+    constructor(storage) {
+        this.storage = storage;
+        this.dataDir = storage.getDataDir();
+        fs.mkdirSync(this.dataDir, { recursive: true });
+        this.git = simpleGit(this.dataDir);
+    }
+    isConfigured() {
+        const cfg = this.storage.getSyncConfig();
+        return !!cfg?.remoteUrl;
+    }
+    /**
+     * Builds an authenticated HTTPS URL by injecting the PAT. The result is only
+     * ever stored in .git/config (which git never commits), never versioned.
+     */
+    authedUrl(cfg) {
+        const token = cfg.token;
+        if (!token)
+            return cfg.remoteUrl;
+        try {
+            const u = new URL(cfg.remoteUrl);
+            if (u.protocol !== "https:")
+                return cfg.remoteUrl;
+            u.username = token;
+            u.password = "";
+            return u.toString();
+        }
+        catch {
+            return cfg.remoteUrl;
+        }
+    }
+    requireConfig() {
+        const cfg = this.storage.getSyncConfig();
+        if (!cfg?.remoteUrl) {
+            throw new Error("Sync is not configured. Set MCP_DOCUMENTOR_SYNC_REMOTE (and MCP_DOCUMENTOR_SYNC_TOKEN) in the server environment.");
+        }
+        return cfg;
+    }
+    /**
+     * Ensures the data dir is a git repo with a .gitignore and an authenticated
+     * origin. The token is stored only in .git/config (which git never commits),
+     * so normal origin-based fetch/push work and upstream tracking — required for
+     * ahead/behind detection — stays accurate.
+     */
+    async ensureRepo() {
+        const cfg = this.requireConfig();
+        const authed = this.authedUrl(cfg);
+        const gitignorePath = path.join(this.dataDir, ".gitignore");
+        if (!fs.existsSync(gitignorePath)) {
+            fs.writeFileSync(gitignorePath, GITIGNORE_CONTENT, "utf-8");
+        }
+        if (!fs.existsSync(path.join(this.dataDir, ".git"))) {
+            await this.git.init();
+            logger.info(`Initialized git repo in ${this.dataDir}`);
+        }
+        // (Re)point origin at the authenticated URL.
+        const remotes = await this.git.getRemotes(true);
+        const origin = remotes.find((r) => r.name === "origin");
+        if (!origin) {
+            await this.git.addRemote("origin", authed);
+        }
+        else if (origin.refs.fetch !== authed) {
+            await this.git.remote(["set-url", "origin", authed]);
+        }
+        // Make sure we're on the configured branch.
+        const branches = await this.git.branchLocal();
+        if (branches.current !== cfg.branch) {
+            try {
+                await this.git.checkoutLocalBranch(cfg.branch);
+            }
+            catch {
+                await this.git.checkout(cfg.branch);
+            }
+        }
+    }
+    async status() {
+        this.requireConfig();
+        const s = await this.git.status();
+        return {
+            branch: s.current ?? "",
+            ahead: s.ahead,
+            behind: s.behind,
+            dirty: s.files.map((f) => f.path),
+            conflicted: s.conflicted,
+        };
+    }
+    /**
+     * Defensive pull: only fast-forwards a clean working tree. Never auto-merges
+     * a divergent history, so local data is never silently overwritten.
+     */
+    async pull() {
+        const cfg = this.requireConfig();
+        await this.ensureRepo();
+        await this.git.fetch("origin", cfg.branch);
+        const remoteRef = `refs/remotes/origin/${cfg.branch}`;
+        // No remote branch yet (fresh repo) — nothing to pull.
+        const hasRemote = await this.git
+            .raw(["rev-parse", "--verify", "--quiet", remoteRef])
+            .then(() => true)
+            .catch(() => false);
+        if (!hasRemote)
+            return { status: "up-to-date" };
+        // Fresh clone: the local branch has no commit yet, so status can't compute
+        // ahead/behind. Materialize the remote branch directly.
+        const hasLocalCommit = await this.git.revparse(["--verify", "HEAD"]).then(() => true).catch(() => false);
+        if (!hasLocalCommit) {
+            await this.git.raw(["reset", "--hard", `origin/${cfg.branch}`]);
+            await this.git.branch(["--set-upstream-to", `origin/${cfg.branch}`, cfg.branch]).catch(() => { });
+            const changed = (await this.git.raw(["ls-tree", "-r", "--name-only", "HEAD"])).split("\n").filter(Boolean);
+            return { status: "updated", changed };
+        }
+        // Ensure upstream tracking so status ahead/behind is meaningful.
+        await this.git.branch(["--set-upstream-to", `origin/${cfg.branch}`, cfg.branch]).catch(() => { });
+        const status = await this.git.status();
+        if (status.behind === 0)
+            return { status: "up-to-date" };
+        // Uncommitted local changes block a safe merge — never risk clobbering them.
+        // Surface as diverged so the user commits/pushes (or stashes) first.
+        if (status.files.length > 0) {
+            return { status: "diverged", ahead: status.ahead, behind: status.behind };
+        }
+        const before = await this.git.revparse(["HEAD"]).catch(() => "");
+        // Pure behind → fast-forward.
+        if (status.ahead === 0) {
+            await this.git.merge(["--ff-only", `origin/${cfg.branch}`]);
+            const after = await this.git.revparse(["HEAD"]).catch(() => "");
+            return { status: "updated", changed: await this.diffNames(before, after) };
+        }
+        // Diverged with a clean tree → attempt a real merge. A conflict stops with
+        // markers in place (both versions preserved) so it can be resolved + pushed.
+        try {
+            await this.git.merge([`origin/${cfg.branch}`]);
+        }
+        catch {
+            const after = await this.git.status();
+            if (after.conflicted.length > 0)
+                return { status: "conflict", conflicted: after.conflicted };
+            throw new Error("Merge failed without recorded conflicts. Resolve manually in the data directory.");
+        }
+        const merged = await this.git.revparse(["HEAD"]).catch(() => "");
+        return { status: "updated", changed: await this.diffNames(before, merged) };
+    }
+    async diffNames(before, after) {
+        if (!before || !after || before === after)
+            return [];
+        return (await this.git.raw(["diff", "--name-only", before, after])).split("\n").filter(Boolean);
+    }
+    /** Stages versioned files, commits if there is anything to commit, and pushes. */
+    async push(message) {
+        const cfg = this.requireConfig();
+        await this.ensureRepo();
+        // .gitignore (written by ensureRepo) excludes all derived/local state,
+        // so -A safely stages only versioned files (projects/, config.json, .gitignore).
+        await this.git.add(["-A"]);
+        const status = await this.git.status();
+        let committed = false;
+        if (status.staged.length > 0 || status.created.length > 0 || status.deleted.length > 0 || status.modified.length > 0) {
+            const machine = process.env.COMPUTERNAME || process.env.HOSTNAME || "unknown-machine";
+            const msg = message?.trim() || `docs sync from ${machine} · ${new Date().toISOString()}`;
+            await this.git.commit(msg);
+            committed = true;
+        }
+        try {
+            await this.git.push(["-u", "origin", `HEAD:${cfg.branch}`]);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            if (/fetch first|non-fast-forward|\[rejected\]/i.test(msg)) {
+                throw new Error("Push rejected: the remote has commits you don't have locally. Run pull_docs to integrate them, then push again.");
+            }
+            throw e;
+        }
+        return { pushed: true, committed, message: committed ? "Committed and pushed." : "Nothing new to commit; pushed existing commits." };
+    }
+    /** Bulk-resolve conflicts by taking one side, then stage the resolved files. */
+    async resolveConflict(strategy, paths) {
+        this.requireConfig();
+        const status = await this.git.status();
+        const targets = paths && paths.length > 0 ? paths : status.conflicted;
+        if (targets.length === 0)
+            return [];
+        // During a merge, "ours" = current branch (mine), "theirs" = incoming.
+        const sideFlag = strategy === "mine" ? "--ours" : "--theirs";
+        for (const p of targets) {
+            await this.git.raw(["checkout", sideFlag, "--", p]);
+            await this.git.add([p]);
+        }
+        return targets;
+    }
+}

package/dist/src/core/storage-engine.d.ts

@@ -5,6 +5,17 @@ interface GlobalConfig {
     projects: string[];
     foldersMigrated?: boolean;
 }
+/**
+ * GitHub sync settings. Sourced exclusively from environment variables — the
+ * repository, branch and token are administration concerns and must never be
+ * settable by the agent at runtime.
+ */
+export interface SyncConfig {
+    remoteUrl: string;
+    branch: string;
+    /** PAT for HTTPS auth (MCP_DOCUMENTOR_SYNC_TOKEN). */
+    token?: string;
+}
 export declare class StorageEngine {
     private rootDir;
     private historyStore?;
@@ -13,8 +24,19 @@ export declare class StorageEngine {
     getDataDir(): string;
     getProjectDir(project?: string): string;
     private getConfigPath;
+    private getLocalStatePath;
+    private readLocalState;
+    private writeLocalState;
+    /**
+     * Returns the merged config. The shared part (projects list, migration flags)
+     * comes from config.json (versioned), while currentProject is a machine-local
+     * preference sourced from local-state.json (gitignored). Legacy config.json
+     * files that still embed currentProject are migrated transparently.
+     */
     getConfig(): GlobalConfig;
     saveConfig(config: GlobalConfig): void;
+    /** Reads sync settings from environment variables (admin-controlled, not agent-settable). */
+    getSyncConfig(): SyncConfig | undefined;
     ensureProject(project: string): void;
     private walkMdFiles;
     private docIdToFilePath;

package/dist/src/core/storage-engine.js

@@ -27,22 +27,81 @@ export class StorageEngine {
     getConfigPath() {
         return path.join(this.getDataDir(), "config.json");
     }
+    getLocalStatePath() {
+        return path.join(this.getDataDir(), "local-state.json");
+    }
+    readLocalState() {
+        const p = this.getLocalStatePath();
+        if (fs.existsSync(p)) {
+            try {
+                return JSON.parse(fs.readFileSync(p, "utf-8"));
+            }
+            catch {
+                logger.warn("Failed to parse local-state.json, using defaults");
+            }
+        }
+        return {};
+    }
+    writeLocalState(state) {
+        const p = this.getLocalStatePath();
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(state, null, 2), "utf-8");
+    }
+    /**
+     * Returns the merged config. The shared part (projects list, migration flags)
+     * comes from config.json (versioned), while currentProject is a machine-local
+     * preference sourced from local-state.json (gitignored). Legacy config.json
+     * files that still embed currentProject are migrated transparently.
+     */
     getConfig() {
         const configPath = this.getConfigPath();
+        let shared = {};
         if (fs.existsSync(configPath)) {
             try {
-                return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+                shared = JSON.parse(fs.readFileSync(configPath, "utf-8"));
             }
             catch {
                 logger.warn("Failed to parse config.json, using defaults");
             }
         }
-        return { currentProject: "default", projects: ["default"] };
+        const local = this.readLocalState();
+        const projects = shared.projects ?? ["default"];
+        // Migrate a legacy currentProject embedded in config.json into local-state.
+        if (shared.currentProject !== undefined && local.currentProject === undefined) {
+            local.currentProject = shared.currentProject;
+            this.writeLocalState(local);
+            delete shared.currentProject;
+            fs.writeFileSync(configPath, JSON.stringify(shared, null, 2), "utf-8");
+            logger.info("Migrated currentProject from config.json to local-state.json");
+        }
+        return {
+            currentProject: local.currentProject ?? projects[0] ?? "default",
+            projects,
+            foldersMigrated: shared.foldersMigrated,
+        };
     }
     saveConfig(config) {
+        // Shared, versioned part → config.json (currentProject is intentionally excluded).
         const configPath = this.getConfigPath();
+        const shared = {
+            projects: config.projects,
+            foldersMigrated: config.foldersMigrated,
+        };
         fs.mkdirSync(path.dirname(configPath), { recursive: true });
-        fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+        fs.writeFileSync(configPath, JSON.stringify(shared, null, 2), "utf-8");
+        // Machine-local part → local-state.json.
+        const local = this.readLocalState();
+        local.currentProject = config.currentProject;
+        this.writeLocalState(local);
+    }
+    /** Reads sync settings from environment variables (admin-controlled, not agent-settable). */
+    getSyncConfig() {
+        const remoteUrl = process.env.MCP_DOCUMENTOR_SYNC_REMOTE?.trim();
+        if (!remoteUrl)
+            return undefined;
+        const branch = process.env.MCP_DOCUMENTOR_SYNC_BRANCH?.trim() || "main";
+        const token = process.env.MCP_DOCUMENTOR_SYNC_TOKEN?.trim() || undefined;
+        return { remoteUrl, branch, token };
     }
     ensureProject(project) {
         const projectDir = path.join(this.getDataDir(), "projects", project);

package/dist/src/index.js

@@ -39,6 +39,8 @@ import { prepareExportBundle } from "./tools/prepare-export-bundle.js";
 import { deleteExportBundle } from "./tools/delete-export-bundle.js";
 import { uploadImage } from "./tools/upload-image.js";
 import { getImage } from "./tools/get-image.js";
+import { SyncEngine } from "./core/git-sync.js";
+import { syncStatus, pullDocs, pushDocs, syncDocs, resolveSyncConflict } from "./tools/sync.js";
 import { isReadOnly, WRITE_TOOLS } from "../shared/read-only.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -75,6 +77,7 @@ embeddingStore.init(storageEngine.getDataDir(), openaiModel);
 const historyStore = new HistoryStore();
 historyStore.init(storageEngine.getDataDir());
 storageEngine.setHistoryStore(historyStore);
+const syncEngine = new SyncEngine(storageEngine);
 const server = new Server({ name: "mcp-documentor", version: APP_VERSION }, { capabilities: { tools: {} } });
 let guiLauncher;
 const sseControllers = new Set();
@@ -1030,6 +1033,48 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 required: ["uri"],
             },
         },
+        {
+            name: "sync_status",
+            description: "Show the synchronization status: current branch, how many commits the local repo is ahead/behind the remote, conflicted files, and uncommitted changes. The sync target (repository, branch, token) is fixed by the server administrator via environment variables and cannot be changed from here.",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "pull_docs",
+            description: "Pull documentation updates from the GitHub remote. Defensive: only fast-forwards a clean working tree, never auto-merges a divergent history (local data is never overwritten). Reindexes embeddings for new documents after a successful update.",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "push_docs",
+            description: "Commit local documentation changes (markdown + assets + project list) and push them to the GitHub remote.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    message: { type: "string", description: "Optional commit message (a default with machine name and timestamp is used otherwise)" },
+                },
+            },
+        },
+        {
+            name: "sync_docs",
+            description: "Full synchronization: pull (defensive) then push. If the pull reveals a divergence or conflict, the push is skipped so it can be resolved first.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    message: { type: "string", description: "Optional commit message for the push step" },
+                },
+            },
+        },
+        {
+            name: "resolve_sync_conflict",
+            description: "Bulk-resolve sync merge conflicts by keeping one side for the conflicted files, then stage them. For nuanced resolution, edit the conflicted markdown files directly instead. After resolving, run push_docs.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    strategy: { type: "string", enum: ["mine", "theirs"], description: "'mine' keeps the local version, 'theirs' keeps the incoming remote version" },
+                    paths: { type: "array", items: { type: "string" }, description: "Specific conflicted file paths to resolve (defaults to all conflicted files)" },
+                },
+                required: ["strategy"],
+            },
+        },
     ];
     return {
         tools: isReadOnly() ? tools.filter((t) => !WRITE_TOOLS.has(t.name)) : tools,
@@ -1111,6 +1156,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return await uploadImage(storageEngine, args);
             case "get_image":
                 return await getImage(storageEngine, args);
+            case "sync_status":
+                return await syncStatus(syncEngine);
+            case "pull_docs":
+                return await pullDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore);
+            case "push_docs":
+                return await pushDocs(syncEngine, args);
+            case "sync_docs":
+                return await syncDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore, args);
+            case "resolve_sync_conflict":
+                return await resolveSyncConflict(syncEngine, args);
             default:
                 throw new Error(`Tool not found: ${name}`);
         }
@@ -1122,9 +1177,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
     }
 });
+async function syncPullOnStartup() {
+    if (!syncEngine.isConfigured())
+        return;
+    if ((process.env.SYNC_PULL_ON_START ?? "").trim().toLowerCase() === "false")
+        return;
+    try {
+        const res = await syncEngine.pull();
+        if (res.status === "updated") {
+            logger.info(`Startup sync: pulled ${res.changed.length} changed file(s).`);
+            if (embeddingEngine.isConfigured()) {
+                await reindexEmbeddings(storageEngine, embeddingEngine, embeddingStore, {});
+            }
+        }
+        else if (res.status === "diverged") {
+            logger.warn(`Startup sync: local history diverged (ahead ${res.ahead}, behind ${res.behind}). Started on local data — run sync_status / sync_docs to reconcile.`);
+        }
+        else if (res.status === "conflict") {
+            logger.warn(`Startup sync: merge conflict in ${res.conflicted.length} file(s). Started on local data — resolve with resolve_sync_conflict.`);
+        }
+        else {
+            logger.info("Startup sync: already up to date.");
+        }
+    }
+    catch (err) {
+        logger.error(`Startup sync failed (non-fatal): ${err?.message ?? err}`);
+    }
+}
 async function main() {
     await migrateFolders(storageEngine);
     await migrateEmbeddings(embeddingStore, storageEngine);
+    await syncPullOnStartup();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     logger.info("MCP Server connected and running on stdio");

package/dist/src/tools/sync.d.ts

@@ -0,0 +1,17 @@
+import type { SyncEngine } from "../core/git-sync.js";
+import type { StorageEngine } from "../core/storage-engine.js";
+import type { EmbeddingEngine } from "../core/embedding-engine.js";
+import type { EmbeddingStore } from "../core/embedding-store.js";
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+};
+export declare function syncStatus(syncEngine: SyncEngine): Promise<ToolResult>;
+export declare function pullDocs(syncEngine: SyncEngine, storageEngine: StorageEngine, embeddingEngine: EmbeddingEngine, embeddingStore: EmbeddingStore): Promise<ToolResult>;
+export declare function pushDocs(syncEngine: SyncEngine, args: unknown): Promise<ToolResult>;
+export declare function syncDocs(syncEngine: SyncEngine, storageEngine: StorageEngine, embeddingEngine: EmbeddingEngine, embeddingStore: EmbeddingStore, args: unknown): Promise<ToolResult>;
+export declare function resolveSyncConflict(syncEngine: SyncEngine, args: unknown): Promise<ToolResult>;
+export {};

package/dist/src/tools/sync.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { reindexEmbeddings } from "./reindex-embeddings.js";
+function ok(text) {
+    return { content: [{ type: "text", text }] };
+}
+function err(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+const NOT_CONFIGURED = "Sync is not configured. Set MCP_DOCUMENTOR_SYNC_REMOTE (and MCP_DOCUMENTOR_SYNC_TOKEN) in the server environment.";
+export async function syncStatus(syncEngine) {
+    try {
+        if (!syncEngine.isConfigured())
+            return ok(NOT_CONFIGURED);
+        const s = await syncEngine.status();
+        const lines = [
+            `Branch: ${s.branch}`,
+            `Ahead: ${s.ahead} commit(s) · Behind: ${s.behind} commit(s)`,
+            s.conflicted.length > 0 ? `Conflicted files (${s.conflicted.length}):\n  - ${s.conflicted.join("\n  - ")}` : "No conflicts.",
+            s.dirty.length > 0 ? `Uncommitted changes (${s.dirty.length}):\n  - ${s.dirty.join("\n  - ")}` : "Working tree clean.",
+        ];
+        return ok(lines.join("\n"));
+    }
+    catch (e) {
+        return err(`Error getting sync status: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+function describePull(res) {
+    switch (res.status) {
+        case "up-to-date":
+            return "Already up to date — nothing to pull.";
+        case "updated":
+            return `Pulled ${res.changed.length} changed file(s):\n  - ${res.changed.join("\n  - ")}`;
+        case "diverged":
+            return `You have uncommitted local changes while the remote has ${res.behind} new commit(s). No changes applied — your local data is intact. Run push_docs to commit and publish your changes, then pull again to merge.`;
+        case "conflict":
+            return `Merge conflict in ${res.conflicted.length} file(s):\n  - ${res.conflicted.join("\n  - ")}\nEdit these markdown files to resolve, or use resolve_sync_conflict, then push_docs.`;
+    }
+}
+/** Reindex embeddings for new docs after a successful merge. Best-effort. */
+async function reindexAfterPull(res, storageEngine, embeddingEngine, embeddingStore) {
+    if (res.status !== "updated" || res.changed.length === 0)
+        return "";
+    if (!embeddingEngine.isConfigured())
+        return "\n(Embeddings not reindexed: OpenAI key not configured.)";
+    try {
+        await reindexEmbeddings(storageEngine, embeddingEngine, embeddingStore, {});
+        return "\nEmbeddings reindexed for new documents.";
+    }
+    catch (e) {
+        return `\n(Embedding reindex failed: ${e instanceof Error ? e.message : String(e)})`;
+    }
+}
+export async function pullDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore) {
+    try {
+        if (!syncEngine.isConfigured())
+            return err(NOT_CONFIGURED);
+        const res = await syncEngine.pull();
+        const reindexNote = await reindexAfterPull(res, storageEngine, embeddingEngine, embeddingStore);
+        return ok(describePull(res) + reindexNote);
+    }
+    catch (e) {
+        return err(`Error pulling docs: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+const PushDocsArgs = z.object({ message: z.string().optional() });
+export async function pushDocs(syncEngine, args) {
+    try {
+        if (!syncEngine.isConfigured())
+            return err(NOT_CONFIGURED);
+        const v = PushDocsArgs.parse(args);
+        const res = await syncEngine.push(v.message);
+        return ok(res.message);
+    }
+    catch (e) {
+        return err(`Error pushing docs: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+export async function syncDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore, args) {
+    try {
+        if (!syncEngine.isConfigured())
+            return err(NOT_CONFIGURED);
+        const v = PushDocsArgs.parse(args);
+        const pull = await syncEngine.pull();
+        const reindexNote = await reindexAfterPull(pull, storageEngine, embeddingEngine, embeddingStore);
+        // Don't push over a divergence/conflict — surface it so the user can resolve first.
+        if (pull.status === "diverged" || pull.status === "conflict") {
+            return ok(`Pull step:\n${describePull(pull)}${reindexNote}\n\nPush skipped until the above is resolved.`);
+        }
+        const push = await syncEngine.push(v.message);
+        return ok(`Pull step: ${describePull(pull)}${reindexNote}\n\nPush step: ${push.message}`);
+    }
+    catch (e) {
+        return err(`Error syncing docs: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+const ResolveConflictArgs = z.object({
+    strategy: z.enum(["mine", "theirs"]),
+    paths: z.array(z.string()).optional(),
+});
+export async function resolveSyncConflict(syncEngine, args) {
+    try {
+        if (!syncEngine.isConfigured())
+            return err(NOT_CONFIGURED);
+        const v = ResolveConflictArgs.parse(args);
+        const resolved = await syncEngine.resolveConflict(v.strategy, v.paths);
+        if (resolved.length === 0)
+            return ok("No conflicted files to resolve.");
+        return ok(`Resolved ${resolved.length} file(s) keeping "${v.strategy}":\n  - ${resolved.join("\n  - ")}\nReview and run push_docs to finalize.`);
+    }
+    catch (e) {
+        return err(`Error resolving conflict: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.56";
+export declare const APP_VERSION = "1.0.57";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated version file - do not edit manually
-export const APP_VERSION = '1.0.56';
+export const APP_VERSION = '1.0.57';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-documentor",
-  "version": "1.0.56",
+  "version": "1.0.57",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
@@ -35,6 +35,7 @@
     "jszip": "^3.10.1",
     "openai": "^6.25.0",
     "puppeteer-core": "^25.0.4",
+    "simple-git": "^3.36.0",
     "zod": "^4.3.6"
   },
   "type": "module",