@imenam/mcp-documentor 1.0.55 → 1.0.56

package/dist/src/index.js

@@ -39,6 +39,7 @@ 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 { isReadOnly, WRITE_TOOLS } from "../shared/read-only.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 function findProjectRoot(startDir) {
@@ -162,7 +163,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 +176,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 +303,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 +366,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 +535,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 +639,410 @@ 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",
-                        },
-                        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",
+                                    required: ["path", "lines"],
+                                    description: "Granular section tracking: only the specified line ranges are monitored",
+                                },
+                            ],
                         },
-                        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).",
                     },
-                    required: ["title"],
+                    tags: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Tags for categorization",
+                    },
+                    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).",
                     },
-                    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." },
+                    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", "new_path"],
                 },
+                required: ["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: "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: "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: "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: "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: "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: "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)" },
                 },
+                required: ["project"],
             },
-            {
-                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)",
-                        },
+        },
+        {
+            name: "list_projects",
+            description: "List all available documentation projects and show which one is currently active.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+        {
+            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"],
                 },
+                required: ["paths"],
             },
-            {
-                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: "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: "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: "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: "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)",
-                        },
+        },
+        {
+            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"],
                 },
+                required: ["paths"],
             },
-            {
-                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: "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: "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: "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: "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_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: "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: "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_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: "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: "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: "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: "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: "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: "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)" },
+        },
+        {
+            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: ["name", "zip_filename", "docs"],
+                    description: { type: "string", description: "Short description of the bundle (optional)" },
                 },
+                required: ["name", "zip_filename", "docs"],
             },
-            {
-                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: "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: "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: "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: "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: "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"],
             },
-        ],
+        },
+    ];
+    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":