@imenam/mcp-documentor 1.0.66 → 1.0.67

package/README.md

@@ -60,6 +60,7 @@ 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_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"}` |
@@ -73,25 +74,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/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

@@ -347,6 +347,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 +367,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 +378,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 +411,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 +444,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 +465,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);