@imenam/mcp-documentor 1.0.54 → 1.0.56

package/README.md

@@ -58,6 +58,7 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 | `MCP_DOCUMENTOR_OPENAI_MODEL` | No | Embedding model (default: `text-embedding-3-small`) |
 | `PROXY_URL` | No | URL of the proxy server to register and launch the GUI |
 | `MCP_DATA_DIR` | No | Overrides the default data directory (see Data storage) |
+| `READ_ONLY` | No | When set to `1`/`true`/`yes`, disables all create/update/delete tools and GUI write actions (read-only mode) |
 
 Optional `.env` at the package root (directory containing `package.json` discovered from the installed binary) is loaded when present.
 

package/dist/shared/read-only.d.ts

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

package/dist/shared/read-only.js

@@ -0,0 +1,11 @@
+/** True quand la variable d'environnement READ_ONLY est activée. */
+export function isReadOnly() {
+    const v = (process.env.READ_ONLY ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+/** Outils MCP qui créent / modifient / suppriment de la donnée. */
+export const WRITE_TOOLS = new Set([
+    "create_doc", "update_doc", "patch_doc", "move_doc", "delete_doc",
+    "restore_doc_version", "refresh_file_snapshot", "reindex_embeddings",
+    "prepare_export_bundle", "delete_export_bundle", "upload_image",
+]);

package/dist/src/core/code-ref-resolver.d.ts

@@ -0,0 +1,14 @@
+import type { TrackedFile, TrackedFileInput } from "../../shared/schemas/doc.schema.js";
+export interface CodeRefResult {
+    content: string;
+    additionalTrackedFiles: TrackedFileInput[];
+}
+export declare function resolveCodeRefs(content: string): CodeRefResult;
+export declare function snapshotTrackedFiles(inputs: TrackedFileInput[]): TrackedFile[];
+/**
+ * Merges snapshotted tracked files into an existing list.
+ * - If a file is not yet tracked: appended.
+ * - If a file is already tracked with sections and the new entry also has sections: sections are merged.
+ * - Otherwise (whole-file tracking involved): the existing entry is replaced.
+ */
+export declare function mergeTrackedFiles(existing: TrackedFile[], additions: TrackedFileInput[]): TrackedFile[];

package/dist/src/core/code-ref-resolver.js

@@ -0,0 +1,118 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { snapshotSection } from "./section-tracker.js";
+const EXT_TO_LANG = {
+    ts: "typescript",
+    tsx: "tsx",
+    js: "javascript",
+    jsx: "jsx",
+    py: "python",
+    css: "css",
+    scss: "scss",
+    json: "json",
+    md: "markdown",
+    html: "html",
+    sh: "bash",
+    yml: "yaml",
+    yaml: "yaml",
+    sql: "sql",
+    rs: "rust",
+    go: "go",
+    java: "java",
+    cs: "csharp",
+};
+// Syntax: [copy-from-codebase|/absolute/path/to/file.ts|10|50]
+// Using | as separator to avoid conflicts with Windows drive letters (C:\...)
+const CODE_REF_REGEX = /\[copy-from-codebase\|([^|]+)\|(\d+)\|(\d+)\]/g;
+function computeFileHash(absolutePath) {
+    return crypto.createHash("sha256").update(fs.readFileSync(absolutePath)).digest("hex");
+}
+export function resolveCodeRefs(content) {
+    const additionalTrackedFiles = [];
+    const resolved = content.replace(CODE_REF_REGEX, (match, filePath, startStr, endStr) => {
+        const start = parseInt(startStr, 10);
+        const end = parseInt(endStr, 10);
+        if (!fs.existsSync(filePath)) {
+            console.warn(`[copy-from-codebase] File not found: ${filePath}`);
+            return match;
+        }
+        const lines = fs.readFileSync(filePath, "utf-8").split("\n");
+        const extracted = lines.slice(start - 1, end).join("\n");
+        const ext = path.extname(filePath).slice(1).toLowerCase();
+        const lang = EXT_TO_LANG[ext] ?? "";
+        additionalTrackedFiles.push({ path: filePath, lines: [{ start, end }] });
+        return `\`\`\`${lang}\n${extracted}\n\`\`\``;
+    });
+    return { content: resolved, additionalTrackedFiles };
+}
+export function snapshotTrackedFiles(inputs) {
+    const byPath = new Map();
+    for (const input of inputs) {
+        const fp = typeof input === "string" ? input : input.path;
+        const absolutePath = path.resolve(process.cwd(), fp);
+        const mtime = fs.existsSync(absolutePath)
+            ? fs.statSync(absolutePath).mtime.toISOString()
+            : new Date().toISOString();
+        const isWhole = typeof input === "string" || input.lines.length === 0;
+        const existing = byPath.get(absolutePath);
+        if (isWhole) {
+            byPath.set(absolutePath, { mtime, lineRanges: [], wholeFile: true });
+        }
+        else if (existing) {
+            if (!existing.wholeFile) {
+                existing.lineRanges.push(...input.lines);
+            }
+        }
+        else {
+            byPath.set(absolutePath, {
+                mtime,
+                lineRanges: [...input.lines],
+                wholeFile: false,
+            });
+        }
+    }
+    const tracked = [];
+    for (const [absolutePath, { mtime, lineRanges, wholeFile }] of byPath) {
+        if (!wholeFile && lineRanges.length > 0 && fs.existsSync(absolutePath)) {
+            const sections = lineRanges
+                .filter(({ start, end }) => start <= end)
+                .map(({ start, end }) => snapshotSection(absolutePath, start, end));
+            tracked.push({ path: absolutePath, lastModifiedAt: mtime, sections });
+        }
+        else {
+            const contentHash = fs.existsSync(absolutePath) ? computeFileHash(absolutePath) : undefined;
+            tracked.push({ path: absolutePath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
+        }
+    }
+    return tracked;
+}
+/**
+ * Merges snapshotted tracked files into an existing list.
+ * - If a file is not yet tracked: appended.
+ * - If a file is already tracked with sections and the new entry also has sections: sections are merged.
+ * - Otherwise (whole-file tracking involved): the existing entry is replaced.
+ */
+export function mergeTrackedFiles(existing, additions) {
+    if (additions.length === 0)
+        return existing;
+    const snapshotted = snapshotTrackedFiles(additions);
+    const result = [...existing];
+    for (const newTf of snapshotted) {
+        const idx = result.findIndex(tf => tf.path === newTf.path);
+        if (idx < 0) {
+            result.push(newTf);
+        }
+        else if (newTf.sections && result[idx].sections) {
+            result[idx] = {
+                ...result[idx],
+                sections: [...result[idx].sections, ...newTf.sections],
+                lastModifiedAt: newTf.lastModifiedAt,
+            };
+        }
+        else {
+            result[idx] = newTf;
+        }
+    }
+    return result;
+}

package/dist/src/gui-worker.js

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