@imenam/mcp-documentor 1.0.66 → 1.0.68

package/README.md

@@ -37,6 +37,21 @@ Global install exposes:
 
 ## MCP Configuration
 
+### Quick setup
+
+From the repo you want to document, generate a ready-to-fill `.mcp.json` in the current directory:
+
+```bash
+npx @imenam/mcp-documentor --claude-setup-mcp
+```
+
+It creates the `mcp-documentor` entry with the usual environment variables as empty placeholders —
+an empty variable is simply inactive, so the generated config runs as-is and you only fill in what
+you need. An existing `.mcp.json` is merged, other servers are preserved, and an existing
+`mcp-documentor` entry is only replaced when `--force` is passed.
+
+### Manual setup
+
 Add to your MCP client config (e.g. Cursor `mcp.json`):
 
 ```json
@@ -60,7 +75,9 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 | `OPENAI_API_KEY` | No | Enables semantic search via OpenAI embeddings (`search_docs`) |
 | `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 |
+| `APP_GROUP` | No | Groups the app under a collapsible section (folded by default) in the proxy dashboard. Apps sharing the same value appear together; if unset, the app lands in the default "ungrouped" section |
 | `MCP_DATA_DIR` | No | Overrides the default data directory (see Data storage) |
+| `MCP_LOG_DIR` | No | Overrides the log directory of both the server and the GUI worker (default: `<package>/.docs-data/logs`). Must be set in the MCP client config — the package `.env` is loaded after the logger starts |
 | `MCP_DOCUMENTOR_CODE_ROOT` | No | Base directory that tracked-file paths are stored relative to, keeping docs portable across machines (see [Portable tracked-file paths](#portable-tracked-file-paths)) |
 | `MCP_DOCUMENTOR_CODE_ROOTS` | No | JSON map of per-project code-root overrides, e.g. `{"my-proj":"/srv/my-proj"}` |
 | `READ_ONLY` | No | When set to `1`/`true`/`yes`, disables all create/update/delete tools and GUI write actions (read-only mode) |
@@ -73,25 +90,31 @@ Optional `.env` at the package root (directory containing `package.json` discove
 
 ## Available Tools
 
+Every tool that targets a specific documentation entry takes a **mandatory `project`**. It is never
+guessed and never falls back to the active project: resolving a doc path across projects is what
+made operations silently hit the wrong project when the same path existed in several. Tools that
+work on a whole project (`list_docs`, `get_doc_tree`, `check_links`, `check_freshness` without a
+`path`, `reindex_embeddings`) keep `project` optional, since omitting it means "all projects".
+
 | Tool | Description |
 |---|---|
-| `create_doc` | Create a new documentation entry linked to source files |
-| `get_doc` | Retrieve a documentation entry with full content |
-| `get_doc_metadata` | Get metadata and freshness status without loading content |
+| `create_doc` | Create a new documentation entry linked to source files (`project` required) |
+| `get_doc` | Retrieve a documentation entry with full content (`project` required) |
+| `get_doc_metadata` | Get metadata and freshness status without loading content (`project` required) |
 | `list_docs` | List docs with staleness indicators (optionally filter by project) |
 | `get_doc_tree` | Return folder/doc structure for a project (or all projects) |
-| `update_doc` | Fully replace content and/or metadata (prefer `patch_doc` for small edits) |
-| `patch_doc` | Search-and-replace a fragment of a doc’s content |
-| `move_doc` | Change a doc’s path (folder/name); use after renames to fix links |
-| `delete_doc` | Permanently delete a documentation entry |
+| `update_doc` | Fully replace content and/or metadata (`project` required; prefer `patch_doc` for small edits) |
+| `patch_doc` | Search-and-replace a fragment of a doc’s content (`project` required) |
+| `move_doc` | Change a doc’s path (folder/name) within its project (`project` required) |
+| `delete_doc` | Permanently delete a documentation entry (`project` required) |
 | `search_docs` | Semantic search over docs (natural language; requires OpenAI) |
-| `check_freshness` | Staleness for one doc or a full project scan |
-| `refresh_file_snapshot` | Mark tracked files as up-to-date without editing the doc |
-| `git_diff_doc` | Git diff for tracked files vs snapshot baseline |
+| `check_freshness` | Staleness for one doc (`project` required) or a full project scan |
+| `refresh_file_snapshot` | Mark tracked files as up-to-date without editing the doc (`project` required) |
+| `git_diff_doc` | Git diff for tracked files vs snapshot baseline (`project` required) |
 | `check_links` | Validate `related_docs`, `doc://` links, and `#heading` anchors |
 | `list_projects` | List all documentation projects |
 | `set_project` | Switch the active project **for the GUI only** (not for MCP tools) |
-| `upload_image` | Upload an image from a local file path to a project's assets; returns the markdown link to insert |
+| `upload_image` | Upload an image from a local file path to a project's assets (`project` required); returns the markdown link to insert |
 | `sync_status` | Show branch, ahead/behind counts, conflicted files, and uncommitted changes |
 | `pull_docs` | Pull updates from the remote (defensive fast-forward; reindexes new docs) |
 | `push_docs` | Commit local doc changes and push them to the remote |

package/dist/shared/schemas/doc.schema.d.ts

@@ -94,6 +94,7 @@ export declare const FreshnessReportSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type FreshnessReport = z.infer<typeof FreshnessReportSchema>;
 export declare const CreateDocArgsSchema: z.ZodObject<{
+    project: z.ZodString;
     title: z.ZodString;
     content: z.ZodOptional<z.ZodString>;
     content_file: z.ZodOptional<z.ZodString>;
@@ -110,6 +111,7 @@ export declare const CreateDocArgsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const UpdateDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
+    project: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
     content: z.ZodOptional<z.ZodString>;
     content_file: z.ZodOptional<z.ZodString>;
@@ -125,10 +127,16 @@ export declare const UpdateDocArgsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const GetDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
+    project: z.ZodString;
+}, z.core.$strip>;
+export declare const DeleteDocArgsSchema: z.ZodObject<{
+    path: z.ZodString;
+    project: z.ZodString;
 }, z.core.$strip>;
 export declare const MoveDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
     new_path: z.ZodString;
+    project: z.ZodString;
 }, z.core.$strip>;
 export declare const CheckFreshnessArgsSchema: z.ZodObject<{
     path: z.ZodOptional<z.ZodString>;
@@ -140,13 +148,16 @@ export declare const SearchDocsArgsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const RefreshFileSnapshotArgsSchema: z.ZodObject<{
     paths: z.ZodArray<z.ZodString>;
+    project: z.ZodString;
     file_paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export declare const GetDocMetadataArgsSchema: z.ZodObject<{
     path: z.ZodString;
+    project: z.ZodString;
 }, z.core.$strip>;
 export declare const PatchDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
+    project: z.ZodString;
     search: z.ZodOptional<z.ZodString>;
     search_file: z.ZodOptional<z.ZodString>;
     replacement: z.ZodOptional<z.ZodString>;
@@ -157,6 +168,7 @@ export declare const CheckLinksArgsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const GitDiffDocArgsSchema: z.ZodObject<{
     paths: z.ZodArray<z.ZodString>;
+    project: z.ZodString;
     file_paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export declare const SetProjectArgsSchema: z.ZodObject<{
@@ -164,17 +176,17 @@ export declare const SetProjectArgsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const ListDocVersionsArgsSchema: z.ZodObject<{
     path: z.ZodString;
-    project: z.ZodOptional<z.ZodString>;
+    project: z.ZodString;
 }, z.core.$strip>;
 export declare const GetDocVersionArgsSchema: z.ZodObject<{
     path: z.ZodString;
     version: z.ZodNumber;
-    project: z.ZodOptional<z.ZodString>;
+    project: z.ZodString;
 }, z.core.$strip>;
 export declare const RestoreDocVersionArgsSchema: z.ZodObject<{
     path: z.ZodString;
     version: z.ZodNumber;
-    project: z.ZodOptional<z.ZodString>;
+    project: z.ZodString;
 }, z.core.$strip>;
 export declare const ExportBundleSchema: z.ZodObject<{
     id: z.ZodString;

package/dist/shared/schemas/doc.schema.js

@@ -45,7 +45,17 @@ export const FreshnessReportSchema = z.object({
     broken: z.array(z.string()).default([]),
     total: z.number(),
 });
+/**
+ * Every tool that targets a specific documentation entry takes this. It is mandatory
+ * and never defaulted: resolving a doc path across projects is what let operations
+ * silently hit the wrong project.
+ */
+const requiredProject = (action) => z
+    .string()
+    .min(1)
+    .describe(`Project the documentation entry belongs to. Mandatory — ${action} is never resolved across projects, and never falls back to the current project.`);
 export const CreateDocArgsSchema = z.object({
+    project: requiredProject("creation").describe("Project to create the documentation entry in. Mandatory — never defaulted to the current project. The project is created automatically if it does not exist yet."),
     title: z.string().describe("Title of the documentation entry"),
     content: z.string().optional().describe("Documentation content in markdown"),
     content_file: z.string().optional().describe("Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft."),
@@ -58,6 +68,7 @@ export const CreateDocArgsSchema = z.object({
 });
 export const UpdateDocArgsSchema = z.object({
     path: z.string().describe("Path of the documentation entry to update, e.g. 'backend/auth/authentication' or 'authentication' for root docs"),
+    project: requiredProject("the update"),
     title: z.string().optional().describe("Title of the documentation entry"),
     content: z.string().optional().describe("New content (replaces existing)"),
     content_file: z.string().optional().describe("Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft."),
@@ -67,14 +78,25 @@ export const UpdateDocArgsSchema = z.object({
 });
 export const GetDocArgsSchema = z.object({
     path: z.string().describe("Path of the documentation entry, e.g. 'backend/auth/authentication' or 'authentication' for root docs"),
+    project: requiredProject("the lookup"),
+});
+export const DeleteDocArgsSchema = z.object({
+    path: z.string().describe("Path of the documentation entry to delete, e.g. 'backend/auth/authentication'"),
+    project: requiredProject("deletion"),
 });
 export const MoveDocArgsSchema = z.object({
     path: z.string().describe("Current path of the documentation entry, e.g. 'backend/auth/authentication'"),
     new_path: z.string().describe("New path for the documentation entry, e.g. 'backend/v2/authentication'. Changes folder and/or name."),
+    project: requiredProject("the move"),
 });
-export const CheckFreshnessArgsSchema = z.object({
+export const CheckFreshnessArgsSchema = z
+    .object({
     path: z.string().optional().describe("Path of a single documentation entry to check, e.g. 'backend/auth/authentication'. If omitted, checks all docs in the project."),
-    project: z.string().optional().describe("Project to scan (defaults to current project). Only used when path is omitted."),
+    project: z.string().min(1).optional().describe("Project to work in. Mandatory when path is provided; when path is omitted it selects the project to scan (all projects if omitted too)."),
+})
+    .refine((d) => !d.path || !!d.project, {
+    message: "project is required when path is provided — freshness of a single entry is never resolved across projects",
+    path: ["project"],
 });
 export const SearchDocsArgsSchema = z.object({
     query: z.string().describe("Search query in natural language"),
@@ -82,13 +104,16 @@ export const SearchDocsArgsSchema = z.object({
 });
 export const RefreshFileSnapshotArgsSchema = z.object({
     paths: z.array(z.string()).min(1).describe("Paths of documentation entries to refresh, e.g. ['backend/auth/authentication', 'setup']"),
+    project: requiredProject("the refresh").describe("Project holding every entry listed in paths. Mandatory — snapshots are never refreshed across projects. Call once per project if the entries are spread across several."),
     file_paths: z.array(z.string()).optional().describe("Specific tracked files to refresh, as absolute paths (they are matched against the stored paths, relative or absolute). Refreshes all tracked files if omitted."),
 });
 export const GetDocMetadataArgsSchema = z.object({
     path: z.string().describe("Path of the documentation entry, e.g. 'backend/auth/authentication'"),
+    project: requiredProject("the lookup"),
 });
 export const PatchDocArgsSchema = z.object({
     path: z.string().describe("Path of the documentation entry to patch, e.g. 'backend/auth/authentication'"),
+    project: requiredProject("the patch"),
     search: z.string().optional().describe("Exact text to find in the current content"),
     search_file: z.string().optional().describe("Absolute path to a text file whose content will be used as the search text. Use this to reuse a previously persisted draft."),
     replacement: z.string().optional().describe("Text to replace it with"),
@@ -103,6 +128,7 @@ export const CheckLinksArgsSchema = z.object({
 });
 export const GitDiffDocArgsSchema = z.object({
     paths: z.array(z.string()).min(1).describe("Paths of documentation entries to diff, e.g. ['backend/auth/authentication']"),
+    project: requiredProject("the diff").describe("Project holding every entry listed in paths. Mandatory — entries are never resolved across projects. Call once per project if they are spread across several."),
     file_paths: z.array(z.string()).optional().describe("Specific tracked files to diff, as absolute paths (matched against the stored paths, relative or absolute). All tracked files if omitted."),
 });
 export const SetProjectArgsSchema = z.object({
@@ -110,17 +136,17 @@ export const SetProjectArgsSchema = z.object({
 });
 export const ListDocVersionsArgsSchema = z.object({
     path: z.string(),
-    project: z.string().optional(),
+    project: requiredProject("history lookup"),
 });
 export const GetDocVersionArgsSchema = z.object({
     path: z.string(),
     version: z.number().int().positive(),
-    project: z.string().optional(),
+    project: requiredProject("history lookup"),
 });
 export const RestoreDocVersionArgsSchema = z.object({
     path: z.string(),
     version: z.number().int().positive(),
-    project: z.string().optional(),
+    project: requiredProject("the restore"),
 });
 export const ExportBundleSchema = z.object({
     id: z.string(),
@@ -134,7 +160,10 @@ export const ExportBundleSchema = z.object({
 export const PrepareExportBundleArgsSchema = z.object({
     name: z.string().describe("Bundle name (becomes the identifier via slugify)"),
     zip_filename: z.string().describe("ZIP filename to download, e.g. 'my-bundle.zip'"),
-    docs: z.array(z.string()).min(1).describe("Doc references: 'project:doc-id' or 'doc-id' for current project"),
+    docs: z
+        .array(z.string().regex(/^[^:]+:.+$/, "each doc reference must be fully qualified as 'project:doc-id'"))
+        .min(1)
+        .describe("Doc references, each fully qualified as 'project:doc-id'. The project prefix is mandatory — a bare 'doc-id' is rejected so a bundle can never pick up the wrong project's entry."),
     description: z.string().optional().describe("Short description of the bundle"),
 });
 export const DeleteExportBundleArgsSchema = z.object({

package/dist/src/cli/setup-mcp.d.ts

@@ -0,0 +1,5 @@
+export interface SetupMcpOptions {
+    cwd: string;
+    force: boolean;
+}
+export declare function runSetupMcp({ cwd, force }: SetupMcpOptions): number;

package/dist/src/cli/setup-mcp.js

@@ -0,0 +1,94 @@
+import fs from "fs";
+import path from "path";
+const SERVER_NAME = "mcp-documentor";
+const PACKAGE_NAME = "@imenam/mcp-documentor";
+/**
+ * Valeurs volontairement vides : chaque variable est inactive tant qu'elle n'est
+ * pas remplie (PROXY_URL vide = GUI désactivée, clé vide = pas d'embeddings),
+ * donc le fichier généré est utilisable tel quel, jamais à moitié cassé.
+ */
+function buildServerEntry() {
+    return {
+        command: "npx",
+        args: ["-y", PACKAGE_NAME],
+        env: {
+            PROXY_URL: "",
+            APP_GROUP: "",
+            APP_PATH: "",
+            MCP_DATA_DIR: "",
+            MCP_LOG_DIR: "",
+            MCP_DOCUMENTOR_CODE_ROOT: "",
+            MCP_DOCUMENTOR_OPENAI_API_KEY: "",
+            MCP_DOCUMENTOR_OPENAI_MODEL: "text-embedding-3-small",
+            MCP_DOCUMENTOR_SYNC_REMOTE: "",
+            MCP_DOCUMENTOR_SYNC_BRANCH: "",
+            MCP_DOCUMENTOR_SYNC_TOKEN: "",
+        },
+    };
+}
+const GENERATED_VARS = [
+    ["PROXY_URL", "URL du proxy pour exposer la GUI"],
+    ["APP_GROUP", "groupe d'affichage dans le dashboard du proxy"],
+    ["APP_PATH", "chemin de montage de la GUI derrière le proxy"],
+    ["MCP_DATA_DIR", "répertoire de données (défaut : celui du package)"],
+    ["MCP_LOG_DIR", "répertoire des logs"],
+    ["MCP_DOCUMENTOR_CODE_ROOT", "racine du code pour des chemins trackés portables"],
+    ["MCP_DOCUMENTOR_OPENAI_API_KEY", "clé OpenAI (active search_docs)"],
+    ["MCP_DOCUMENTOR_OPENAI_MODEL", "modèle d'embedding"],
+    ["MCP_DOCUMENTOR_SYNC_REMOTE", "URL HTTPS du repo privé de sync GitHub"],
+    ["MCP_DOCUMENTOR_SYNC_BRANCH", "branche de sync (défaut : main)"],
+    ["MCP_DOCUMENTOR_SYNC_TOKEN", "PAT GitHub fine-grained pour la sync"],
+];
+const OPTIONAL_VARS = [
+    ["MCP_DOCUMENTOR_CODE_ROOTS", 'code roots par projet, ex: {"my-proj":"/srv/my-proj"}'],
+    ["READ_ONLY", "1/true pour désactiver toutes les écritures"],
+    ["SYNC_PULL_ON_START", "false pour désactiver le pull au démarrage"],
+];
+export function runSetupMcp({ cwd, force }) {
+    const target = path.join(cwd, ".mcp.json");
+    let config = {};
+    const exists = fs.existsSync(target);
+    if (exists) {
+        const raw = fs.readFileSync(target, "utf-8").trim();
+        if (raw !== "") {
+            try {
+                config = JSON.parse(raw);
+            }
+            catch (err) {
+                console.error(`Erreur : ${target} contient du JSON invalide (${err.message}).`);
+                console.error("Corrigez le fichier ou supprimez-le, puis relancez la commande.");
+                return 1;
+            }
+        }
+        if (typeof config !== "object" || config === null || Array.isArray(config)) {
+            console.error(`Erreur : ${target} ne contient pas un objet JSON.`);
+            return 1;
+        }
+    }
+    if (typeof config.mcpServers !== "object" || config.mcpServers === null || Array.isArray(config.mcpServers)) {
+        config.mcpServers = {};
+    }
+    const alreadyPresent = Object.prototype.hasOwnProperty.call(config.mcpServers, SERVER_NAME);
+    if (alreadyPresent && !force) {
+        console.error(`Le serveur "${SERVER_NAME}" est déjà configuré dans ${target}.`);
+        console.error("Relancez avec --force pour écraser cette entrée (les autres serveurs sont préservés).");
+        return 1;
+    }
+    config.mcpServers[SERVER_NAME] = buildServerEntry();
+    fs.writeFileSync(target, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    const action = alreadyPresent ? "remplacée" : exists ? "ajoutée" : "créée";
+    console.log(`Configuration ${SERVER_NAME} ${action} dans ${target}`);
+    console.log("");
+    console.log('À compléter dans le champ "env" :');
+    for (const [name, description] of GENERATED_VARS) {
+        console.log(`  ${name.padEnd(30)} ${description}`);
+    }
+    console.log("");
+    console.log("Variables optionnelles à ajouter au besoin :");
+    for (const [name, description] of OPTIONAL_VARS) {
+        console.log(`  ${name.padEnd(30)} ${description}`);
+    }
+    console.log("");
+    console.log("Une variable laissée vide est simplement inactive.");
+    return 0;
+}

package/dist/src/core/log-dir.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Répertoire des logs : MCP_LOG_DIR s'il est renseigné, sinon <racine>/.docs-data/logs.
+ * Lu depuis process.env uniquement (le .env du package est chargé après l'init du
+ * logger), donc la variable doit venir de la config du client MCP.
+ */
+export declare function resolveLogDir(rootDir: string): string;

package/dist/src/core/log-dir.js

@@ -0,0 +1,12 @@
+import path from "path";
+/**
+ * Répertoire des logs : MCP_LOG_DIR s'il est renseigné, sinon <racine>/.docs-data/logs.
+ * Lu depuis process.env uniquement (le .env du package est chargé après l'init du
+ * logger), donc la variable doit venir de la config du client MCP.
+ */
+export function resolveLogDir(rootDir) {
+    const configured = process.env.MCP_LOG_DIR?.trim();
+    if (configured)
+        return path.resolve(configured);
+    return path.join(rootDir, ".docs-data", "logs");
+}

package/dist/src/core/project-scope.d.ts

@@ -0,0 +1,24 @@
+import type { StorageEngine } from "./storage-engine.js";
+import type { DocEntry } from "../../shared/schemas/doc.schema.js";
+/**
+ * Doc-targeted tools resolve their entry inside one explicitly named project.
+ * Cross-project resolution (storageEngine.resolveDoc) is deliberately not used
+ * here: it picked the first project holding the path, which silently sent reads
+ * and writes to the wrong project when the same path exists in several.
+ */
+export type ScopeError = {
+    errorText: string;
+};
+export declare function isScopeError(value: unknown): value is ScopeError;
+/** Wraps a scope error into the MCP tool result shape. */
+export declare function scopeErrorResult(error: ScopeError): {
+    isError: true;
+    content: {
+        type: string;
+        text: string;
+    }[];
+};
+export declare function assertProject(storageEngine: StorageEngine, project: string): ScopeError | null;
+export declare function resolveDocInProject(storageEngine: StorageEngine, docPath: string, project: string, action?: string): Promise<{
+    doc: DocEntry;
+} | ScopeError>;

package/dist/src/core/project-scope.js

@@ -0,0 +1,28 @@
+export function isScopeError(value) {
+    return typeof value === "object" && value !== null && "errorText" in value;
+}
+/** Wraps a scope error into the MCP tool result shape. */
+export function scopeErrorResult(error) {
+    return { isError: true, content: [{ type: "text", text: error.errorText }] };
+}
+export function assertProject(storageEngine, project) {
+    const knownProjects = storageEngine.getConfig().projects;
+    if (!knownProjects.includes(project)) {
+        return {
+            errorText: `Project "${project}" does not exist. Known projects: ${knownProjects.join(", ")}.`,
+        };
+    }
+    return null;
+}
+export async function resolveDocInProject(storageEngine, docPath, project, action = "operation") {
+    const projectError = assertProject(storageEngine, project);
+    if (projectError)
+        return projectError;
+    const doc = await storageEngine.getDoc(docPath, project);
+    if (!doc) {
+        return {
+            errorText: `Documentation entry "${docPath}" not found in project "${project}" — no ${action} performed. Check the project with list_projects or get_doc_tree before retrying.`,
+        };
+    }
+    return { doc };
+}

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

@@ -44,10 +44,6 @@ export declare class StorageEngine {
     saveDoc(doc: DocEntry, project?: string, changeType?: "create" | "update" | "patch"): Promise<void>;
     getDoc(id: string, project?: string): Promise<DocEntry | null>;
     listDocs(project?: string): Promise<DocSummary[]>;
-    resolveDoc(id: string): Promise<{
-        doc: DocEntry;
-        project: string;
-    } | null>;
     deleteDoc(id: string, project?: string): Promise<boolean>;
     moveDoc(oldId: string, newId: string, project?: string): Promise<boolean>;
     getBundles(): ExportBundle[];

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

@@ -215,15 +215,10 @@ export class StorageEngine {
         }
         return summaries;
     }
-    async resolveDoc(id) {
-        const config = this.getConfig();
-        for (const project of config.projects) {
-            const doc = await this.getDoc(id, project);
-            if (doc)
-                return { doc, project };
-        }
-        return null;
-    }
+    // resolveDoc() (first project whose tree contained the path) was removed on purpose:
+    // it silently sent reads and writes to the wrong project when the same doc path
+    // existed in several. Doc-targeted callers must name their project and go through
+    // getDoc(id, project) — see core/project-scope.ts.
     async deleteDoc(id, project) {
         const config = this.getConfig();
         const proj = project ?? config.currentProject;

package/dist/src/gui-worker.js

@@ -12,6 +12,7 @@ import { promisify } from "util";
 const execFileAsync = promisify(execFile);
 import { fileURLToPath } from "url";
 import { createLogger, setupLogging } from "@imenam/mcp-gui-interface";
+import { resolveLogDir } from "./core/log-dir.js";
 import matter from "gray-matter";
 import JSZip from "jszip";
 import puppeteer from "puppeteer-core";
@@ -31,7 +32,7 @@ const dataDir = process.env.MCP_DATA_DIR?.trim() || path.join(rootDir, ".docs-da
 const staticRoot = path.join(rootDir, "gui/dist");
 const absoluteStaticRoot = path.resolve(staticRoot);
 const configuredAppPath = process.env.APP_PATH || "/documentor-gui";
-setupLogging({ processLabel: "mcp-documentor:GUI", logDir: path.join(rootDir, ".docs-data", "logs") });
+setupLogging({ processLabel: "mcp-documentor:GUI", logDir: resolveLogDir(rootDir) });
 const logger = createLogger("mcp-documentor:GUI");
 process.on("uncaughtException", (err) => {
     logger.error(`Uncaught Exception: ${err.message}`);
@@ -347,6 +348,9 @@ app.post("/api/doc", async (c) => {
         if (!body.title || !body.content) {
             return c.json({ error: "title and content are required" }, 400);
         }
+        if (!body.project) {
+            return c.json({ error: "project is required" }, 400);
+        }
         const result = await ipcRequest("CREATE_DOC", {
             title: body.title,
             content: body.content,
@@ -364,7 +368,10 @@ app.post("/api/doc", async (c) => {
 });
 app.get("/api/doc/*", async (c) => {
     const id = decodeURIComponent(c.req.path.slice("/api/doc/".length));
-    const result = await ipcRequest("GET_DOC", { id });
+    const project = c.req.query("project");
+    if (!project)
+        return c.json({ error: "project query param is required" }, 400);
+    const result = await ipcRequest("GET_DOC", { id, project });
     if (result.error)
         return c.json({ error: result.error }, 400);
     return c.json(result.data);
@@ -372,11 +379,29 @@ app.get("/api/doc/*", async (c) => {
 app.put("/api/doc/*", async (c) => {
     try {
         const id = decodeURIComponent(c.req.path.slice("/api/doc/".length));
+        const project = c.req.query("project");
+        if (!project)
+            return c.json({ error: "project query param is required" }, 400);
         const body = await c.req.json();
         if (body.content === undefined) {
             return c.json({ error: "content is required" }, 400);
         }
-        const result = await ipcRequest("UPDATE_DOC", { id, content: body.content, title: body.title }, 15000);
+        const result = await ipcRequest("UPDATE_DOC", { id, project, content: body.content, title: body.title }, 15000);
+        if (result.error)
+            return c.json({ error: result.error }, 500);
+        return c.json(result.data ?? { success: true });
+    }
+    catch (err) {
+        return c.json({ error: err.message }, 500);
+    }
+});
+app.delete("/api/doc/*", async (c) => {
+    try {
+        const id = decodeURIComponent(c.req.path.slice("/api/doc/".length));
+        const project = c.req.query("project");
+        if (!project)
+            return c.json({ error: "project query param is required" }, 400);
+        const result = await ipcRequest("DELETE_DOC", { id, project }, 15000);
         if (result.error)
             return c.json({ error: result.error }, 500);
         return c.json(result.data ?? { success: true });
@@ -387,21 +412,30 @@ app.put("/api/doc/*", async (c) => {
 });
 app.get("/api/freshness/*", async (c) => {
     const id = decodeURIComponent(c.req.path.slice("/api/freshness/".length));
-    const result = await ipcRequest("CHECK_FRESHNESS", { id });
+    const project = c.req.query("project");
+    if (!project)
+        return c.json({ error: "project query param is required" }, 400);
+    const result = await ipcRequest("CHECK_FRESHNESS", { id, project });
     if (result.error)
         return c.json({ error: result.error }, 400);
     return c.json(result.data);
 });
 app.get("/api/git-diff/*", async (c) => {
     const id = decodeURIComponent(c.req.path.slice("/api/git-diff/".length));
-    const result = await ipcRequest("GIT_DIFF", { id }, 15000);
+    const project = c.req.query("project");
+    if (!project)
+        return c.json({ error: "project query param is required" }, 400);
+    const result = await ipcRequest("GIT_DIFF", { id, project }, 15000);
     if (result.error)
         return c.json({ error: result.error }, 400);
     return c.json(result.data);
 });
 app.get("/api/history/*", async (c) => {
     const id = decodeURIComponent(c.req.path.slice("/api/history/".length));
-    const result = await ipcRequest("GET_DOC_HISTORY", { id });
+    const project = c.req.query("project");
+    if (!project)
+        return c.json({ error: "project query param is required" }, 400);
+    const result = await ipcRequest("GET_DOC_HISTORY", { id, project });
     if (result.error)
         return c.json({ error: result.error }, 400);
     return c.json(result.data);
@@ -411,7 +445,10 @@ app.get("/api/history-version/*", async (c) => {
     const lastSlash = rest.lastIndexOf("/");
     const id = rest.slice(0, lastSlash);
     const version = parseInt(rest.slice(lastSlash + 1), 10);
-    const result = await ipcRequest("GET_DOC_VERSION", { id, version });
+    const project = c.req.query("project");
+    if (!project)
+        return c.json({ error: "project query param is required" }, 400);
+    const result = await ipcRequest("GET_DOC_VERSION", { id, version, project });
     if (result.error)
         return c.json({ error: result.error }, 400);
     return c.json(result.data);
@@ -429,8 +466,11 @@ app.get("/api/file-section/*", async (c) => {
     const docId = c.req.query("docId");
     if (!docId)
         return c.json({ error: "docId query param required" }, 400);
+    const project = c.req.query("project");
+    if (!project)
+        return c.json({ error: "project query param is required" }, 400);
     const filePath = decodeURIComponent(c.req.path.slice("/api/file-section/".length));
-    const result = await ipcRequest("GET_FILE_SECTION", { docId, filePath }, 8000);
+    const result = await ipcRequest("GET_FILE_SECTION", { docId, project, filePath }, 8000);
     if (result.error)
         return c.json({ error: result.error }, 400);
     return c.json(result.data);