@imenam/mcp-documentor 1.0.55 → 1.0.57

package/dist/src/index.js

@@ -39,6 +39,9 @@ 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);
 function findProjectRoot(startDir) {
@@ -74,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();
@@ -162,7 +166,7 @@ async function handleGetInitialState(msg) {
         broadcastToGUI({
             type: "INITIAL_STATE",
             correlationId: msg.correlationId,
-            data: { config, docs, projects: config.projects, bundles },
+            data: { config, docs, projects: config.projects, bundles, readOnly: isReadOnly() },
             timestamp: new Date().toISOString(),
         });
     }
@@ -175,7 +179,7 @@ async function handleGetConfig(msg) {
     broadcastToGUI({
         type: "CONFIG_RESPONSE",
         correlationId: msg.correlationId,
-        data: { ...config, version: getConfig().version },
+        data: { ...config, version: getConfig().version, readOnly: isReadOnly() },
         timestamp: new Date().toISOString(),
     });
 }
@@ -302,6 +306,15 @@ async function handleListFoldersIPC(msg) {
     }
 }
 async function handleCreateDocIPC(msg) {
+    if (isReadOnly()) {
+        broadcastToGUI({
+            type: "CREATE_DOC_RESPONSE",
+            correlationId: msg.correlationId,
+            error: "READ_ONLY mode: creation disabled",
+            timestamp: new Date().toISOString(),
+        });
+        return;
+    }
     try {
         const { title, content, folder, tags, project } = msg.data ?? {};
         if (!title || !content)
@@ -356,6 +369,15 @@ async function handleCreateDocIPC(msg) {
     }
 }
 async function handleUpdateDocIPC(msg) {
+    if (isReadOnly()) {
+        broadcastToGUI({
+            type: "UPDATE_DOC_RESPONSE",
+            correlationId: msg.correlationId,
+            error: "READ_ONLY mode: update disabled",
+            timestamp: new Date().toISOString(),
+        });
+        return;
+    }
     try {
         const result = await updateDoc(storageEngine, embeddingEngine, {
             path: msg.data.id,
@@ -516,6 +538,15 @@ async function handleGitDiff(msg) {
     }
 }
 async function handleUpdateConfig(msg) {
+    if (isReadOnly()) {
+        broadcastToGUI({
+            type: "CONFIG_UPDATED",
+            correlationId: msg.correlationId,
+            error: "READ_ONLY mode: configuration changes disabled",
+            timestamp: new Date().toISOString(),
+        });
+        return;
+    }
     try {
         const { key, value } = msg.data;
         const envPath = path.join(rootDir, ".env");
@@ -611,403 +642,452 @@ function launchGUI() {
     guiLauncher.start();
 }
 server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-        tools: [
-            {
-                name: "create_doc",
-                description: "Create a new documentation entry with markdown content, optional tracked files, and tags.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        title: { type: "string", description: "Title of the documentation entry" },
-                        content: { type: "string", description: "Documentation content in markdown. To link to another document inline, use the syntax [text](doc://target-doc-id) — the viewer will navigate to that document on click. To link to a heading within the same document, use [text](#heading-slug). Use check_links to validate both types. For code blocks, always specify a language identifier for syntax highlighting, e.g. ```typescript, ```python, ```bash, ```json, ```yaml, ```sql. To embed a code excerpt directly from a source file, use [copy-from-codebase|/absolute/path/to/file.ts|startLine|endLine] — the tag is replaced at save time by a fenced code block with automatic language detection, and the file+range is automatically added to tracked_files. IMPORTANT: always read the source file first to identify the exact line numbers before writing the tag." },
-                        content_file: { type: "string", description: "Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
-                        tracked_files: {
-                            type: "array",
-                            items: {
-                                oneOf: [
-                                    { type: "string", description: "Plain file path for whole-file tracking" },
-                                    {
-                                        type: "object",
-                                        properties: {
-                                            path: { type: "string", description: "File path to track" },
-                                            lines: {
-                                                type: "array",
-                                                items: {
-                                                    type: "object",
-                                                    properties: {
-                                                        start: { type: "integer", minimum: 1, description: "First line of the section (1-indexed, inclusive)" },
-                                                        end: { type: "integer", minimum: 1, description: "Last line of the section (1-indexed, inclusive)" },
-                                                    },
-                                                    required: ["start", "end"],
+    const tools = [
+        {
+            name: "create_doc",
+            description: "Create a new documentation entry with markdown content, optional tracked files, and tags.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string", description: "Title of the documentation entry" },
+                    content: { type: "string", description: "Documentation content in markdown. To link to another document inline, use the syntax [text](doc://target-doc-id) — the viewer will navigate to that document on click. To link to a heading within the same document, use [text](#heading-slug). Use check_links to validate both types. For code blocks, always specify a language identifier for syntax highlighting, e.g. ```typescript, ```python, ```bash, ```json, ```yaml, ```sql. To embed a code excerpt directly from a source file, use [copy-from-codebase|/absolute/path/to/file.ts|startLine|endLine] — the tag is replaced at save time by a fenced code block with automatic language detection, and the file+range is automatically added to tracked_files. IMPORTANT: always read the source file first to identify the exact line numbers before writing the tag." },
+                    content_file: { type: "string", description: "Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
+                    tracked_files: {
+                        type: "array",
+                        items: {
+                            oneOf: [
+                                { type: "string", description: "Plain file path for whole-file tracking" },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        path: { type: "string", description: "File path to track" },
+                                        lines: {
+                                            type: "array",
+                                            items: {
+                                                type: "object",
+                                                properties: {
+                                                    start: { type: "integer", minimum: 1, description: "First line of the section (1-indexed, inclusive)" },
+                                                    end: { type: "integer", minimum: 1, description: "Last line of the section (1-indexed, inclusive)" },
                                                 },
-                                                minItems: 1,
-                                                description: "One or more line ranges to track within the file",
+                                                required: ["start", "end"],
                                             },
+                                            minItems: 1,
+                                            description: "One or more line ranges to track within the file",
                                         },
-                                        required: ["path", "lines"],
-                                        description: "Granular section tracking: only the specified line ranges are monitored",
                                     },
-                                ],
-                            },
-                            description: "Files to track for staleness detection. Use a plain path string for whole-file tracking, or { path, lines: [{ start, end }] } to track specific sections only (reduces false positives when unrelated parts of the file change).",
-                        },
-                        tags: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: "Tags for categorization",
+                                    required: ["path", "lines"],
+                                    description: "Granular section tracking: only the specified line ranges are monitored",
+                                },
+                            ],
                         },
-                        folder: { type: "string", description: "Folder path for organization, e.g. 'frontend/components'" },
-                        related_docs: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: "IDs of related documentation entries",
-                        },
-                        project: { type: "string", description: "Project to create the doc in (defaults to current project if omitted). If the project name does not exist yet, it will be created automatically." },
+                        description: "Files to track for staleness detection. Use a plain path string for whole-file tracking, or { path, lines: [{ start, end }] } to track specific sections only (reduces false positives when unrelated parts of the file change).",
+                    },
+                    tags: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Tags for categorization",
                     },
-                    required: ["title"],
+                    folder: { type: "string", description: "Folder path for organization, e.g. 'frontend/components'" },
+                    related_docs: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "IDs of related documentation entries",
+                    },
+                    project: { type: "string", description: "Project to create the doc in (defaults to current project if omitted). If the project name does not exist yet, it will be created automatically." },
                 },
+                required: ["title"],
             },
-            {
-                name: "get_doc",
-                description: "Retrieve a documentation entry by its path, including full content, tracked files, and metadata.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication' or 'authentication' for root docs" },
-                    },
-                    required: ["path"],
+        },
+        {
+            name: "get_doc",
+            description: "Retrieve a documentation entry by its path, including full content, tracked files, and metadata.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication' or 'authentication' for root docs" },
                 },
+                required: ["path"],
             },
-            {
-                name: "list_docs",
-                description: "List all documentation entries in the current project with staleness indicators.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        project: { type: "string", description: "Project to list (lists all projects if omitted)" },
-                    },
+        },
+        {
+            name: "list_docs",
+            description: "List all documentation entries in the current project with staleness indicators.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: { type: "string", description: "Project to list (lists all projects if omitted)" },
                 },
             },
-            {
-                name: "update_doc",
-                description: "Fully replace the content and/or metadata of a documentation entry. WARNING: This overwrites the entire content. Prefer patch_doc for targeted edits — only use update_doc when the changes are so extensive that a patch is impractical. To move a doc to another folder, use move_doc instead.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        path: { type: "string", description: "Path of the documentation entry to update, e.g. 'backend/auth/authentication' or 'authentication' for root docs" },
-                        title: {
-                            type: "string",
-                            description: "New display title stored in frontmatter. Does not rename the file or change the document path — use move_doc to relocate or rename on disk.",
-                        },
-                        content: { type: "string", description: "New content (replaces existing). Supports [text](doc://target-doc-path) to link inline to other documents, and [text](#heading-slug) to link to headings within this document. For code blocks, always specify a language identifier for syntax highlighting, e.g. ```typescript, ```python, ```bash, ```json, ```yaml, ```sql. To embed a code excerpt directly from a source file, use [copy-from-codebase|/absolute/path/to/file.ts|startLine|endLine] — the tag is replaced at save time by a fenced code block with automatic language detection, and the file+range is automatically added to tracked_files. IMPORTANT: always read the source file first to identify the exact line numbers before writing the tag." },
-                        content_file: { type: "string", description: "Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
-                        tracked_files: {
-                            type: "array",
-                            items: {
-                                oneOf: [
-                                    { type: "string", description: "Plain file path for whole-file tracking" },
-                                    {
-                                        type: "object",
-                                        properties: {
-                                            path: { type: "string", description: "File path to track" },
-                                            lines: {
-                                                type: "array",
-                                                items: {
-                                                    type: "object",
-                                                    properties: {
-                                                        start: { type: "integer", minimum: 1, description: "First line of the section (1-indexed, inclusive)" },
-                                                        end: { type: "integer", minimum: 1, description: "Last line of the section (1-indexed, inclusive)" },
-                                                    },
-                                                    required: ["start", "end"],
+        },
+        {
+            name: "update_doc",
+            description: "Fully replace the content and/or metadata of a documentation entry. WARNING: This overwrites the entire content. Prefer patch_doc for targeted edits — only use update_doc when the changes are so extensive that a patch is impractical. To move a doc to another folder, use move_doc instead.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path of the documentation entry to update, e.g. 'backend/auth/authentication' or 'authentication' for root docs" },
+                    title: {
+                        type: "string",
+                        description: "New display title stored in frontmatter. Does not rename the file or change the document path — use move_doc to relocate or rename on disk.",
+                    },
+                    content: { type: "string", description: "New content (replaces existing). Supports [text](doc://target-doc-path) to link inline to other documents, and [text](#heading-slug) to link to headings within this document. For code blocks, always specify a language identifier for syntax highlighting, e.g. ```typescript, ```python, ```bash, ```json, ```yaml, ```sql. To embed a code excerpt directly from a source file, use [copy-from-codebase|/absolute/path/to/file.ts|startLine|endLine] — the tag is replaced at save time by a fenced code block with automatic language detection, and the file+range is automatically added to tracked_files. IMPORTANT: always read the source file first to identify the exact line numbers before writing the tag." },
+                    content_file: { type: "string", description: "Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
+                    tracked_files: {
+                        type: "array",
+                        items: {
+                            oneOf: [
+                                { type: "string", description: "Plain file path for whole-file tracking" },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        path: { type: "string", description: "File path to track" },
+                                        lines: {
+                                            type: "array",
+                                            items: {
+                                                type: "object",
+                                                properties: {
+                                                    start: { type: "integer", minimum: 1, description: "First line of the section (1-indexed, inclusive)" },
+                                                    end: { type: "integer", minimum: 1, description: "Last line of the section (1-indexed, inclusive)" },
                                                 },
-                                                minItems: 1,
-                                                description: "One or more line ranges to track within the file",
+                                                required: ["start", "end"],
                                             },
+                                            minItems: 1,
+                                            description: "One or more line ranges to track within the file",
                                         },
-                                        required: ["path", "lines"],
-                                        description: "Granular section tracking: only the specified line ranges are monitored",
                                     },
-                                ],
-                            },
-                            description: "New list of tracked files (replaces existing). Use a plain path string for whole-file tracking, or { path, lines: [{ start, end }] } to track specific sections only (reduces false positives when unrelated parts of the file change).",
-                        },
-                        tags: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: "New tags (replaces existing)",
-                        },
-                        related_docs: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: "Paths of related documentation entries (replaces existing), e.g. ['backend/auth/authentication']",
+                                    required: ["path", "lines"],
+                                    description: "Granular section tracking: only the specified line ranges are monitored",
+                                },
+                            ],
                         },
+                        description: "New list of tracked files (replaces existing). Use a plain path string for whole-file tracking, or { path, lines: [{ start, end }] } to track specific sections only (reduces false positives when unrelated parts of the file change).",
+                    },
+                    tags: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "New tags (replaces existing)",
+                    },
+                    related_docs: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Paths of related documentation entries (replaces existing), e.g. ['backend/auth/authentication']",
                     },
-                    required: ["path"],
                 },
+                required: ["path"],
             },
-            {
-                name: "move_doc",
-                description: "Move a documentation entry to a new path (changes its folder and/or name). All existing doc:// links and related_docs references pointing to the old path are automatically rewritten across the project. This is the only way to relocate a document — update_doc does not change the location.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        path: { type: "string", description: "Current path of the documentation entry, e.g. 'backend/authentication'" },
-                        new_path: { type: "string", description: "New path for the documentation entry, e.g. 'backend/v2/authentication'. Can change folder, name, or both." },
-                    },
-                    required: ["path", "new_path"],
+        },
+        {
+            name: "move_doc",
+            description: "Move a documentation entry to a new path (changes its folder and/or name). All existing doc:// links and related_docs references pointing to the old path are automatically rewritten across the project. This is the only way to relocate a document — update_doc does not change the location.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Current path of the documentation entry, e.g. 'backend/authentication'" },
+                    new_path: { type: "string", description: "New path for the documentation entry, e.g. 'backend/v2/authentication'. Can change folder, name, or both." },
                 },
+                required: ["path", "new_path"],
             },
-            {
-                name: "search_docs",
-                description: "Semantic search across documentation entries using natural language. Requires OpenAI API key.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        query: { type: "string", description: "Search query in natural language" },
-                        top_k: { type: "number", description: "Number of results to return (default: 5)" },
-                    },
-                    required: ["query"],
+        },
+        {
+            name: "search_docs",
+            description: "Semantic search across documentation entries using natural language. Requires OpenAI API key.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Search query in natural language" },
+                    top_k: { type: "number", description: "Number of results to return (default: 5)" },
                 },
+                required: ["query"],
             },
-            {
-                name: "check_freshness",
-                description: "Check freshness of documentation. Pass a path to check a single entry, or omit it to scan all docs in a project and get a full staleness report.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        path: { type: "string", description: "Path of a single documentation entry to check, e.g. 'backend/auth/authentication'. If omitted, scans all docs in the project." },
-                        project: { type: "string", description: "Project to scan (scans all projects if omitted). Only used when path is omitted." },
-                    },
-                    required: [],
+        },
+        {
+            name: "check_freshness",
+            description: "Check freshness of documentation. Pass a path to check a single entry, or omit it to scan all docs in a project and get a full staleness report.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path of a single documentation entry to check, e.g. 'backend/auth/authentication'. If omitted, scans all docs in the project." },
+                    project: { type: "string", description: "Project to scan (scans all projects if omitted). Only used when path is omitted." },
                 },
+                required: [],
+            },
+        },
+        {
+            name: "set_project",
+            description: "Switch the active project and update it as the default for all subsequent MCP tool operations. If the project name does not exist yet, it is created automatically. Also controls what the GUI displays.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: { type: "string", description: "Project name to switch to (created if it does not exist)" },
+                },
+                required: ["project"],
+            },
+        },
+        {
+            name: "list_projects",
+            description: "List all available documentation projects and show which one is currently active.",
+            inputSchema: {
+                type: "object",
+                properties: {},
             },
-            {
-                name: "set_project",
-                description: "Switch the active project and update it as the default for all subsequent MCP tool operations. If the project name does not exist yet, it is created automatically. Also controls what the GUI displays.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        project: { type: "string", description: "Project name to switch to (created if it does not exist)" },
+        },
+        {
+            name: "refresh_file_snapshot",
+            description: "Mark tracked files as up-to-date by updating their snapshot timestamps. Use when file changes don't affect the documentation. Accepts one or more doc paths.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    paths: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Paths of documentation entries to refresh, e.g. ['backend/auth/authentication', 'setup']",
+                    },
+                    file_paths: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Specific tracked file paths to refresh (all tracked files if omitted)",
                     },
-                    required: ["project"],
                 },
+                required: ["paths"],
             },
-            {
-                name: "list_projects",
-                description: "List all available documentation projects and show which one is currently active.",
-                inputSchema: {
-                    type: "object",
-                    properties: {},
+        },
+        {
+            name: "get_doc_metadata",
+            description: "Get metadata of a documentation entry (path, title, tags, dates, tracked files with freshness) without loading the full content.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
                 },
+                required: ["path"],
             },
-            {
-                name: "refresh_file_snapshot",
-                description: "Mark tracked files as up-to-date by updating their snapshot timestamps. Use when file changes don't affect the documentation. Accepts one or more doc paths.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        paths: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: "Paths of documentation entries to refresh, e.g. ['backend/auth/authentication', 'setup']",
-                        },
-                        file_paths: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: "Specific tracked file paths to refresh (all tracked files if omitted)",
-                        },
-                    },
-                    required: ["paths"],
+        },
+        {
+            name: "patch_doc",
+            description: "PREFERRED method for modifying documentation. Replaces a specific portion of a documentation entry's content using an exact search-and-replace, without touching the rest of the doc. Always use this instead of update_doc when making partial changes.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path of the documentation entry to patch, e.g. 'backend/auth/authentication'" },
+                    search: { type: "string", description: "Exact text to find in the current content" },
+                    search_file: { type: "string", description: "Absolute path to a text file whose content will be used as the search text. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
+                    replacement: { type: "string", description: "Text to replace it with. Supports [copy-from-codebase|/absolute/path/to/file.ts|startLine|endLine] — the tag is replaced at save time by a fenced code block, and the file+range is automatically added to tracked_files. IMPORTANT: always read the source file first to identify the exact line numbers before writing the tag." },
+                    replacement_file: { type: "string", description: "Absolute path to a text file whose content will be used as the replacement. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
                 },
+                required: ["path", "search"],
             },
-            {
-                name: "get_doc_metadata",
-                description: "Get metadata of a documentation entry (path, title, tags, dates, tracked files with freshness) without loading the full content.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
+        },
+        {
+            name: "git_diff_doc",
+            description: "Show the git diff for each tracked file of one or more docs, between their current state and the last commit before the stored snapshot date.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    paths: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Paths of documentation entries to diff, e.g. ['backend/auth/authentication']",
+                    },
+                    file_paths: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Specific tracked file paths to diff (all tracked files if omitted)",
                     },
-                    required: ["path"],
                 },
+                required: ["paths"],
             },
-            {
-                name: "patch_doc",
-                description: "PREFERRED method for modifying documentation. Replaces a specific portion of a documentation entry's content using an exact search-and-replace, without touching the rest of the doc. Always use this instead of update_doc when making partial changes.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        path: { type: "string", description: "Path of the documentation entry to patch, e.g. 'backend/auth/authentication'" },
-                        search: { type: "string", description: "Exact text to find in the current content" },
-                        search_file: { type: "string", description: "Absolute path to a text file whose content will be used as the search text. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
-                        replacement: { type: "string", description: "Text to replace it with. Supports [copy-from-codebase|/absolute/path/to/file.ts|startLine|endLine] — the tag is replaced at save time by a fenced code block, and the file+range is automatically added to tracked_files. IMPORTANT: always read the source file first to identify the exact line numbers before writing the tag." },
-                        replacement_file: { type: "string", description: "Absolute path to a text file whose content will be used as the replacement. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
-                    },
-                    required: ["path", "search"],
+        },
+        {
+            name: "check_links",
+            description: "Check all links across a project and report broken references. Validates: related_docs IDs, inline doc links ([text](doc://id)) in content, and anchor links ([text](#heading-slug)) in content.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: { type: "string", description: "Project to check (defaults to current project)" },
                 },
+                required: [],
             },
-            {
-                name: "git_diff_doc",
-                description: "Show the git diff for each tracked file of one or more docs, between their current state and the last commit before the stored snapshot date.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        paths: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: "Paths of documentation entries to diff, e.g. ['backend/auth/authentication']",
-                        },
-                        file_paths: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: "Specific tracked file paths to diff (all tracked files if omitted)",
-                        },
-                    },
-                    required: ["paths"],
+        },
+        {
+            name: "delete_doc",
+            description: "Permanently delete a documentation entry. Works across all projects — no need to set the active project first.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path of the documentation entry to delete, e.g. 'backend/auth/authentication'" },
                 },
+                required: ["path"],
             },
-            {
-                name: "check_links",
-                description: "Check all links across a project and report broken references. Validates: related_docs IDs, inline doc links ([text](doc://id)) in content, and anchor links ([text](#heading-slug)) in content.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        project: { type: "string", description: "Project to check (defaults to current project)" },
-                    },
-                    required: [],
+        },
+        {
+            name: "get_doc_tree",
+            description: "Get the full documentation tree showing folders, subfolders, and documentation names (not file names). Useful to quickly understand the documentation structure of a project.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: { type: "string", description: "Project to display (shows all projects if omitted)" },
                 },
             },
-            {
-                name: "delete_doc",
-                description: "Permanently delete a documentation entry. Works across all projects — no need to set the active project first.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        path: { type: "string", description: "Path of the documentation entry to delete, e.g. 'backend/auth/authentication'" },
-                    },
-                    required: ["path"],
+        },
+        {
+            name: "list_doc_versions",
+            description: "List all saved versions of a documentation entry, with date and change type.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
+                    project: { type: "string", description: "Project to look in (defaults to current project)" },
                 },
+                required: ["path"],
             },
-            {
-                name: "get_doc_tree",
-                description: "Get the full documentation tree showing folders, subfolders, and documentation names (not file names). Useful to quickly understand the documentation structure of a project.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        project: { type: "string", description: "Project to display (shows all projects if omitted)" },
-                    },
+        },
+        {
+            name: "get_doc_version",
+            description: "Retrieve the full content of a specific version of a documentation entry.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
+                    version: { type: "number", description: "Version number to retrieve" },
+                    project: { type: "string", description: "Project to look in (defaults to current project)" },
                 },
+                required: ["path", "version"],
             },
-            {
-                name: "list_doc_versions",
-                description: "List all saved versions of a documentation entry, with date and change type.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
-                        project: { type: "string", description: "Project to look in (defaults to current project)" },
-                    },
-                    required: ["path"],
+        },
+        {
+            name: "restore_doc_version",
+            description: "Restore a documentation entry to a previous version. The current state is saved as a new version before overwriting.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
+                    version: { type: "number", description: "Version number to restore" },
+                    project: { type: "string", description: "Project to look in (defaults to current project)" },
                 },
+                required: ["path", "version"],
             },
-            {
-                name: "get_doc_version",
-                description: "Retrieve the full content of a specific version of a documentation entry.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
-                        version: { type: "number", description: "Version number to retrieve" },
-                        project: { type: "string", description: "Project to look in (defaults to current project)" },
-                    },
-                    required: ["path", "version"],
+        },
+        {
+            name: "reindex_embeddings",
+            description: "Generate missing embeddings for all documentation entries in a project (or all projects). Useful when importing existing documentation that was created outside the MCP. Use force: true to regenerate embeddings for all docs, including those already indexed.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: { type: "string", description: "Project to reindex (processes all projects if omitted)" },
+                    force: { type: "boolean", description: "If true, regenerates embeddings for all docs even if they are already indexed (default: false)" },
                 },
+                required: [],
             },
-            {
-                name: "restore_doc_version",
-                description: "Restore a documentation entry to a previous version. The current state is saved as a new version before overwriting.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
-                        version: { type: "number", description: "Version number to restore" },
-                        project: { type: "string", description: "Project to look in (defaults to current project)" },
+        },
+        {
+            name: "prepare_export_bundle",
+            description: "Create or update a named export bundle: a set of documentation references that the user can download as a ZIP from the GUI. The ZIP contains clean markdown content (no frontmatter). Existing bundle with the same name is replaced.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Bundle display name (becomes the identifier via slugify)" },
+                    zip_filename: { type: "string", description: "ZIP filename to download, e.g. 'my-bundle.zip'" },
+                    docs: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Doc references to include: 'project:doc-id' for cross-project, or 'doc-id' for current project",
                     },
-                    required: ["path", "version"],
+                    description: { type: "string", description: "Short description of the bundle (optional)" },
                 },
+                required: ["name", "zip_filename", "docs"],
             },
-            {
-                name: "reindex_embeddings",
-                description: "Generate missing embeddings for all documentation entries in a project (or all projects). Useful when importing existing documentation that was created outside the MCP. Use force: true to regenerate embeddings for all docs, including those already indexed.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        project: { type: "string", description: "Project to reindex (processes all projects if omitted)" },
-                        force: { type: "boolean", description: "If true, regenerates embeddings for all docs even if they are already indexed (default: false)" },
-                    },
-                    required: [],
+        },
+        {
+            name: "delete_export_bundle",
+            description: "Delete an export bundle by its identifier (slug).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "Bundle identifier to delete (slug, e.g. 'my-bundle')" },
                 },
+                required: ["id"],
             },
-            {
-                name: "prepare_export_bundle",
-                description: "Create or update a named export bundle: a set of documentation references that the user can download as a ZIP from the GUI. The ZIP contains clean markdown content (no frontmatter). Existing bundle with the same name is replaced.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        name: { type: "string", description: "Bundle display name (becomes the identifier via slugify)" },
-                        zip_filename: { type: "string", description: "ZIP filename to download, e.g. 'my-bundle.zip'" },
-                        docs: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: "Doc references to include: 'project:doc-id' for cross-project, or 'doc-id' for current project",
-                        },
-                        description: { type: "string", description: "Short description of the bundle (optional)" },
-                    },
-                    required: ["name", "zip_filename", "docs"],
+        },
+        {
+            name: "upload_image",
+            description: "Upload an image to a project's assets from a local file path and get back the markdown link to insert in a document. Returns the URL and a ready-to-use markdown snippet: ![alt](/api/images/{project}/{filename}).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    filename: { type: "string", description: "Filename with extension, e.g. 'screenshot.png'" },
+                    filePath: { type: "string", description: "Absolute path to the image file on the server" },
+                    project: { type: "string", description: "Target project (defaults to current project)" },
+                    alt: { type: "string", description: "Alt text for the markdown image link (optional)" },
                 },
+                required: ["filename", "filePath"],
             },
-            {
-                name: "delete_export_bundle",
-                description: "Delete an export bundle by its identifier (slug).",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        id: { type: "string", description: "Bundle identifier to delete (slug, e.g. 'my-bundle')" },
-                    },
-                    required: ["id"],
+        },
+        {
+            name: "get_image",
+            description: "Retrieve an image stored in a project's assets by its URI and return it as a base64-encoded image. Use this when a document references an image (e.g. ![alt](/api/images/{project}/{filename})) and you need to view its content.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    uri: { type: "string", description: "Image URI as it appears in the document, e.g. '/api/images/my-project/screenshot.png'" },
                 },
+                required: ["uri"],
             },
-            {
-                name: "upload_image",
-                description: "Upload an image to a project's assets from a local file path and get back the markdown link to insert in a document. Returns the URL and a ready-to-use markdown snippet: ![alt](/api/images/{project}/{filename}).",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        filename: { type: "string", description: "Filename with extension, e.g. 'screenshot.png'" },
-                        filePath: { type: "string", description: "Absolute path to the image file on the server" },
-                        project: { type: "string", description: "Target project (defaults to current project)" },
-                        alt: { type: "string", description: "Alt text for the markdown image link (optional)" },
-                    },
-                    required: ["filename", "filePath"],
+        },
+        {
+            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: "get_image",
-                description: "Retrieve an image stored in a project's assets by its URI and return it as a base64-encoded image. Use this when a document references an image (e.g. ![alt](/api/images/{project}/{filename})) and you need to view its content.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        uri: { type: "string", description: "Image URI as it appears in the document, e.g. '/api/images/my-project/screenshot.png'" },
-                    },
-                    required: ["uri"],
+        },
+        {
+            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,
     };
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    if (isReadOnly() && WRITE_TOOLS.has(name)) {
+        return {
+            content: [{ type: "text", text: `Error: tool "${name}" is disabled (READ_ONLY mode).` }],
+            isError: true,
+        };
+    }
     try {
         switch (name) {
             case "create_doc":
@@ -1076,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}`);
         }
@@ -1087,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");