@imenam/mcp-documentor 1.0.23 → 1.0.25

package/README.md

@@ -6,12 +6,13 @@ Connect it to Cursor, Claude Desktop, or any MCP-compatible agent to let your AI
 
 ## Features
 
-- **Create & update docs** — write markdown documentation entries linked to source files
+- **Create & update docs** — write markdown documentation entries linked to source files; prefer partial edits via `patch_doc`
 - **Staleness tracking** — automatically detects when tracked files have changed since the last doc update
 - **Semantic search** — find relevant docs by meaning (requires an OpenAI API key)
-- **Multi-project support** — organize docs into separate projects and switch between them
-- **GUI** — built-in web interface to browse and read documentation
+- **Multi-project support** — organize docs into separate projects; MCP tools work across projects; `set_project` only changes what the GUI shows
+- **GUI** — built-in web interface when a proxy is configured (`PROXY_URL`); without it, the GUI worker is not started
 - **Proxy-aware** — integrates with the [proxy-setup](https://github.com/Imena/proxy-setup) for GUI exposure
+- **Links & structure** — `check_links`, `get_doc_tree`, `move_doc`, and `git_diff_doc` for maintenance workflows
 
 ## Installation
 
@@ -25,6 +26,11 @@ Or install globally:
 npm install -g @imenam/mcp-documentor
 ```
 
+Global install exposes:
+
+- `mcp-documentor` — MCP server
+- `mcp-documentor-migrate` — CLI helper for migrating inline doc links (see `scripts/migrate-links.js`)
+
 ## MCP Configuration
 
 Add to your MCP client config (e.g. Cursor `mcp.json`):
@@ -47,8 +53,12 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 
 | Variable | Required | Description |
 |---|---|---|
-| `OPENAI_API_KEY` | No | Enables semantic search via OpenAI embeddings |
-| `PROXY_URL` | No | URL of the proxy server to register the GUI |
+| `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 |
+| `MCP_DATA_DIR` | No | Overrides the default data directory (see Data storage) |
+
+Optional `.env` at the package root (directory containing `package.json` discovered from the installed binary) is loaded when present.
 
 ## Available Tools
 
@@ -57,17 +67,23 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 | `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 |
-| `list_docs` | List all docs in the current project with staleness indicators |
-| `update_doc` | Update an existing documentation entry |
-| `search_docs` | Search docs by keyword or semantic similarity |
-| `check_freshness` | Check if a doc is up-to-date relative to its tracked files |
-| `refresh_file_snapshot` | Mark files as up-to-date without editing the doc content |
+| `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 |
+| `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_links` | Validate `related_docs`, `doc://` links, and `#heading` anchors |
 | `list_projects` | List all documentation projects |
-| `set_project` | Switch to a different project |
+| `set_project` | Switch the active project **for the GUI only** (not for MCP tools) |
 
 ## Data Storage
 
-Documentation is stored locally in a `data/` directory next to the server process. This directory is **not** included in the npm package — it is created at runtime in the working directory.
+By default, data lives under **`.docs-data`** next to the resolved package root (the folder that contains `package.json` for the running install). Set **`MCP_DATA_DIR`** to use another directory. Contents include projects, SQLite/embeddings, and logs under `.docs-data/logs`. This tree is **not** part of the npm package; it is created at runtime.
 
 ## License
 

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

@@ -60,6 +60,7 @@ export declare const CreateDocArgsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const UpdateDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
     content: z.ZodOptional<z.ZodString>;
     tracked_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;

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

@@ -32,6 +32,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"),
+    title: z.string().optional().describe("Title of the documentation entry"),
     content: z.string().optional().describe("New content (replaces existing)"),
     tracked_files: z.array(z.string()).optional().describe("New list of file paths (replaces existing)"),
     tags: z.array(z.string()).optional().describe("New tags (replaces existing)"),

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

@@ -25,5 +25,6 @@ export declare class StorageEngine {
     } | null>;
     deleteDoc(id: string, project?: string): Promise<boolean>;
     moveDoc(oldId: string, newId: string, project?: string): Promise<boolean>;
+    rewriteLinks(oldId: string, newId: string, project?: string): Promise<string[]>;
 }
 export {};

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

@@ -3,6 +3,9 @@ import path from "path";
 import matter from "gray-matter";
 import { createLogger } from "@imenam/mcp-gui-interface";
 const logger = createLogger("StorageEngine");
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 export class StorageEngine {
     rootDir;
     constructor(rootDir) {
@@ -188,4 +191,35 @@ export class StorageEngine {
         logger.info(`Doc moved: ${oldFilePath} → ${newFilePath}`);
         return true;
     }
+    async rewriteLinks(oldId, newId, project) {
+        const docs = await this.listDocs(project);
+        const updated = [];
+        for (const summary of docs) {
+            if (summary.id === newId)
+                continue;
+            const doc = await this.getDoc(summary.id, project);
+            if (!doc)
+                continue;
+            let changed = false;
+            const newContent = doc.content.replace(new RegExp(`doc://${escapeRegex(oldId)}`, "g"), `doc://${newId}`);
+            if (newContent !== doc.content) {
+                doc.content = newContent;
+                changed = true;
+            }
+            const newRelated = doc.related_docs.map((ref) => {
+                if (ref === oldId) {
+                    changed = true;
+                    return newId;
+                }
+                return ref;
+            });
+            doc.related_docs = newRelated;
+            if (changed) {
+                doc.updatedAt = new Date().toISOString();
+                await this.saveDoc(doc, project);
+                updated.push(summary.id);
+            }
+        }
+        return updated;
+    }
 }

package/dist/src/index.js

@@ -404,7 +404,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             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)" },
+                        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", "content"],
                 },
@@ -437,6 +437,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     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." },
                         tracked_files: {
                             type: "array",
@@ -459,7 +463,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "move_doc",
-                description: "Move a documentation entry to a new path (changes its folder and/or name). This is the only way to relocate a document — update_doc does not change the location. After moving, use check_links to detect any broken references.",
+                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: {
@@ -495,11 +499,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "set_project",
-                description: "Switch the active project for the GUI display. This does NOT affect MCP tool operations — tools work across all projects automatically. Use only to control what the graphical interface shows.",
+                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" },
+                        project: { type: "string", description: "Project name to switch to (created if it does not exist)" },
                     },
                     required: ["project"],
                 },

package/dist/src/tools/move-doc.js

@@ -18,11 +18,15 @@ export async function moveDoc(storageEngine, embeddingEngine, args) {
             };
         }
         await embeddingEngine.moveEmbedding(validated.path, validated.new_path, resolvedProject);
+        const rewritten = await storageEngine.rewriteLinks(validated.path, validated.new_path, resolvedProject);
+        const rewriteNote = rewritten.length > 0
+            ? `\n\nLiens mis à jour automatiquement dans ${rewritten.length} doc(s) :\n${rewritten.map((id) => `  - ${id}`).join("\n")}`
+            : "\n\nAucune référence existante à mettre à jour.";
         return {
             content: [
                 {
                     type: "text",
-                    text: `Documentation entry moved successfully.\nFrom: "${validated.path}"\nTo:   "${validated.new_path}"\n\nNote: if other documents reference "${validated.path}" in their related_docs or via doc:// links, use check_links to detect broken references.`,
+                    text: `Documentation entry moved successfully.\nFrom: "${validated.path}"\nTo:   "${validated.new_path}"${rewriteNote}`,
                 },
             ],
         };

package/dist/src/tools/update-doc.js

@@ -24,6 +24,9 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
             return { isError: true, content: [{ type: "text", text: `Documentation entry "${validated.path}" not found in any project.` }] };
         }
         const { doc, project: resolvedProject } = resolved;
+        if (validated.title !== undefined) {
+            doc.title = validated.title;
+        }
         if (validated.content !== undefined) {
             doc.content = validated.content;
         }
@@ -45,6 +48,8 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
             }
         }
         const changes = [];
+        if (validated.title !== undefined)
+            changes.push(`title (${doc.title})`);
         if (validated.content !== undefined)
             changes.push("content");
         if (validated.tracked_files !== undefined)

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.23";
+export declare const APP_VERSION = "1.0.25";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated version file - do not edit manually
-export const APP_VERSION = '1.0.23';
+export const APP_VERSION = '1.0.25';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-documentor",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",