@imenam/mcp-documentor 1.0.55 → 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
 
@@ -58,6 +59,11 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 | `MCP_DOCUMENTOR_OPENAI_MODEL` | No | Embedding model (default: `text-embedding-3-small`) |
 | `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.
 
@@ -82,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
 
@@ -109,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.d.ts

@@ -0,0 +1,4 @@
+/** True quand la variable d'environnement READ_ONLY est activée. */
+export declare function isReadOnly(): boolean;
+/** Outils MCP qui créent / modifient / suppriment de la donnée. */
+export declare const WRITE_TOOLS: Set<string>;

package/dist/shared/read-only.js

@@ -0,0 +1,14 @@
+/** True quand la variable d'environnement READ_ONLY est activée. */
+export function isReadOnly() {
+    const v = (process.env.READ_ONLY ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+/** Outils MCP qui créent / modifient / suppriment de la donnée. */
+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/gui-worker.js

@@ -4,6 +4,7 @@ import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
 import { ProxyClient } from "@imenam/mcp-gui-interface";
 import { IPCMessageSchema } from "../shared/schemas/doc.schema.js";
+import { isReadOnly } from "../shared/read-only.js";
 import path from "path";
 import fs from "fs";
 import { execFile } from "child_process";
@@ -184,6 +185,23 @@ function setupIpcErrorHandlers() {
     });
 }
 // --- HTTP Routes ---
+// Bloque les écritures GUI en mode lecture seule (READ_ONLY).
+const READ_ONLY_WRITE_ROUTES = [
+    { method: "POST", prefix: "/api/doc" },
+    { method: "PUT", prefix: "/api/doc/" },
+    { method: "POST", prefix: "/api/images" },
+    { method: "POST", prefix: "/api/configurations/apply" },
+];
+app.use("*", async (c, next) => {
+    if (isReadOnly()) {
+        const m = c.req.method;
+        const p = c.req.path;
+        if (READ_ONLY_WRITE_ROUTES.some((r) => r.method === m && p.startsWith(r.prefix))) {
+            return c.json({ error: "READ_ONLY mode: write operations are disabled" }, 403);
+        }
+    }
+    return next();
+});
 app.get("/proxy/health", (c) => {
     const memory = process.memoryUsage();
     return c.json({