@imenam/mcp-documentor 1.0.86 → 1.0.87

package/README.md

@@ -120,7 +120,7 @@ that work on a whole project (`list_docs`, `get_doc_tree`, `check_freshness` wit
 | `get_doc_tree` | Return folder/doc structure for a project (or all projects) |
 | `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) |
+| `move_doc` | Change a doc’s path (`new_path`) and/or project (`new_project`); links are rewritten across all projects (`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 (`project` required) or a full project scan |

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

@@ -156,8 +156,9 @@ export declare const DeleteDocArgsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const MoveDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
-    new_path: z.ZodString;
+    new_path: z.ZodOptional<z.ZodString>;
     project: z.ZodString;
+    new_project: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const CheckFreshnessArgsSchema: z.ZodObject<{
     path: z.ZodOptional<z.ZodString>;

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

@@ -123,8 +123,19 @@ export const DeleteDocArgsSchema = z.object({
 });
 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."),
+    new_path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("New path for the documentation entry, e.g. 'backend/v2/authentication'. Changes folder and/or name. Omitted: the entry keeps its current path, which requires new_project."),
     project: requiredProject("the move"),
+    new_project: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Project the entry is moved to. Omitted: the entry stays in `project`."),
+}).refine((args) => args.new_path !== undefined || args.new_project !== undefined, {
+    message: "Provide new_path, new_project, or both.",
 });
 export const CheckFreshnessArgsSchema = z
     .object({

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

@@ -11,7 +11,7 @@ export declare class EmbeddingEngine {
     cosineSimilarity(a: number[], b: number[]): number;
     saveEmbedding(docId: string, embedding: number[], project: string): Promise<void>;
     removeEmbedding(docId: string, project: string): Promise<void>;
-    moveEmbedding(oldDocId: string, newDocId: string, project: string): Promise<void>;
+    moveEmbedding(oldDocId: string, project: string, newDocId: string, newProject: string): Promise<void>;
     search(query: string, project: string, topK: number, getDocContent: (id: string) => Promise<{
         title: string;
         content: string;

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

@@ -66,9 +66,9 @@ export class EmbeddingEngine {
         this.store.remove(project, docId);
         logger.debug(`Embedding removed for doc "${docId}" in project "${project}"`);
     }
-    async moveEmbedding(oldDocId, newDocId, project) {
-        this.store.move(project, oldDocId, newDocId);
-        logger.debug(`Embedding moved: "${oldDocId}" → "${newDocId}" in project "${project}"`);
+    async moveEmbedding(oldDocId, project, newDocId, newProject) {
+        this.store.move(project, oldDocId, newProject, newDocId);
+        logger.debug(`Embedding moved: "${project}:${oldDocId}" → "${newProject}:${newDocId}"`);
     }
     async search(query, project, topK, getDocContent) {
         return this.searchAcrossProjects(query, [project], topK, async (_proj, docId) => getDocContent(docId));

package/dist/src/core/embedding-store.d.ts

@@ -5,7 +5,7 @@ export declare class EmbeddingStore {
     private getDb;
     save(project: string, docId: string, embedding: number[]): void;
     remove(project: string, docId: string): void;
-    move(project: string, oldDocId: string, newDocId: string): void;
+    move(project: string, oldDocId: string, newProject: string, newDocId: string): void;
     loadAll(project: string): Map<string, number[]>;
     loadAllProjects(projects: string[]): Array<{
         project: string;

package/dist/src/core/embedding-store.js

@@ -65,11 +65,11 @@ export class EmbeddingStore {
             .run(project, docId);
         logger.debug(`Embedding removed: [${project}] ${docId}`);
     }
-    move(project, oldDocId, newDocId) {
+    move(project, oldDocId, newProject, newDocId) {
         this.getDb()
-            .prepare("UPDATE embeddings SET doc_id = ? WHERE project = ? AND doc_id = ?")
-            .run(newDocId, project, oldDocId);
-        logger.debug(`Embedding moved: [${project}] ${oldDocId} → ${newDocId}`);
+            .prepare("UPDATE embeddings SET project = ?, doc_id = ? WHERE project = ? AND doc_id = ?")
+            .run(newProject, newDocId, project, oldDocId);
+        logger.debug(`Embedding moved: [${project}] ${oldDocId} → [${newProject}] ${newDocId}`);
     }
     loadAll(project) {
         const rows = this.getDb()

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

@@ -58,9 +58,19 @@ export declare class StorageEngine {
      */
     listDocsDetailed(project: string): Promise<DocListing[]>;
     deleteDoc(id: string, project: string): Promise<boolean>;
-    moveDoc(oldId: string, newId: string, project: string): Promise<boolean>;
+    /**
+     * Moves a doc to `newId` in `newProject`. Across projects, the moved doc's own
+     * same-project references (`doc://id`, bare related_docs) are qualified with the
+     * source project so they keep pointing at the same entries; the history records
+     * a delete in the source project and a create in the target.
+     */
+    moveDoc(oldId: string, project: string, newId: string, newProject: string): Promise<boolean>;
     getBundles(): ExportBundle[];
     saveBundles(bundles: ExportBundle[]): void;
-    rewriteLinks(oldId: string, newId: string, project: string): Promise<string[]>;
+    /**
+     * Rewrites every reference to `project:oldId` so it points at `newProject:newId`.
+     * In the source project, bare references become qualified when the doc left it.
+     */
+    rewriteLinks(oldId: string, project: string, newId: string, newProject: string): Promise<string[]>;
 }
 export {};

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

@@ -227,24 +227,37 @@ export class StorageEngine {
         logger.info(`Doc deleted: ${filePath}`);
         return true;
     }
-    async moveDoc(oldId, newId, project) {
+    /**
+     * Moves a doc to `newId` in `newProject`. Across projects, the moved doc's own
+     * same-project references (`doc://id`, bare related_docs) are qualified with the
+     * source project so they keep pointing at the same entries; the history records
+     * a delete in the source project and a create in the target.
+     */
+    async moveDoc(oldId, project, newId, newProject) {
         const projectDir = this.getProjectDir(project);
         const oldFilePath = this.docIdToFilePath(oldId, projectDir);
         if (!fs.existsSync(oldFilePath))
             return false;
-        const newFilePath = this.docIdToFilePath(newId, projectDir);
+        const newProjectDir = this.getProjectDir(newProject);
+        const newFilePath = this.docIdToFilePath(newId, newProjectDir);
         if (fs.existsSync(newFilePath)) {
-            throw new Error(`A document already exists at path "${newId}".`);
+            throw new Error(`A document already exists at path "${newId}" in project "${newProject}".`);
         }
         const doc = await this.getDoc(oldId, project);
         if (!doc)
             return false;
+        const crossProject = newProject !== project;
+        if (crossProject) {
+            this.historyStore?.record(project, doc, "delete");
+            doc.content = doc.content.replace(/doc:\/\/([^):#\s]+)(?=[)#\s]|$)/g, `doc://${project}:$1`);
+            doc.related_docs = doc.related_docs.map((ref) => (ref.includes(":") ? ref : `${project}:${ref}`));
+        }
         const newParts = newId.split("/");
         doc.id = newId;
         doc.folder = newParts.length > 1 ? newParts.slice(0, -1).join("/") : undefined;
         doc.updatedAt = new Date().toISOString();
         fs.mkdirSync(path.dirname(newFilePath), { recursive: true });
-        await this.saveDoc(doc, project, "update");
+        await this.saveDoc(doc, newProject, crossProject ? "create" : "update");
         fs.unlinkSync(oldFilePath);
         this.cleanEmptyDirs(path.dirname(oldFilePath), projectDir);
         logger.info(`Doc moved: ${oldFilePath} → ${newFilePath}`);
@@ -265,22 +278,29 @@ export class StorageEngine {
         const p = path.join(this.getDataDir(), "export-bundles.json");
         fs.writeFileSync(p, JSON.stringify(bundles, null, 2), "utf-8");
     }
-    async rewriteLinks(oldId, newId, project) {
+    /**
+     * Rewrites every reference to `project:oldId` so it points at `newProject:newId`.
+     * In the source project, bare references become qualified when the doc left it.
+     */
+    async rewriteLinks(oldId, project, newId, newProject) {
         const config = this.getConfig();
         const proj = project;
+        const crossProject = newProject !== proj;
+        const qualifiedTarget = `${newProject}:${newId}`;
+        const bareTarget = crossProject ? qualifiedTarget : newId;
+        const boundary = "(?=[)#\\s]|$)";
         const updated = [];
-        // Within the same project: rewrite same-project refs and explicit self-cross-project refs
+        // Within the source project: rewrite bare refs and explicit self-cross-project refs
         const sameProjDocs = await this.listDocs(proj);
         for (const summary of sameProjDocs) {
-            if (summary.id === newId)
+            if (!crossProject && summary.id === newId)
                 continue;
             const doc = await this.getDoc(summary.id, proj);
             if (!doc)
                 continue;
             let changed = false;
-            let newContent = doc.content.replace(new RegExp(`doc://${escapeRegex(oldId)}`, "g"), `doc://${newId}`);
-            // Also rewrite explicit self cross-project refs (doc://proj:oldId → doc://proj:newId)
-            newContent = newContent.replace(new RegExp(`doc://${escapeRegex(proj)}:${escapeRegex(oldId)}`, "g"), `doc://${proj}:${newId}`);
+            let newContent = doc.content.replace(new RegExp(`doc://${escapeRegex(oldId)}${boundary}`, "g"), `doc://${bareTarget}`);
+            newContent = newContent.replace(new RegExp(`doc://${escapeRegex(proj)}:${escapeRegex(oldId)}${boundary}`, "g"), `doc://${qualifiedTarget}`);
             if (newContent !== doc.content) {
                 doc.content = newContent;
                 changed = true;
@@ -288,11 +308,11 @@ export class StorageEngine {
             const newRelated = doc.related_docs.map((ref) => {
                 if (ref === oldId) {
                     changed = true;
-                    return newId;
+                    return bareTarget;
                 }
                 if (ref === `${proj}:${oldId}`) {
                     changed = true;
-                    return `${proj}:${newId}`;
+                    return qualifiedTarget;
                 }
                 return ref;
             });
@@ -303,7 +323,7 @@ export class StorageEngine {
                 updated.push(summary.id);
             }
         }
-        // In other projects: rewrite cross-project refs pointing to this project
+        // In other projects: rewrite cross-project refs pointing to the source project
         for (const otherProj of config.projects) {
             if (otherProj === proj)
                 continue;
@@ -313,7 +333,7 @@ export class StorageEngine {
                 if (!doc)
                     continue;
                 let changed = false;
-                const newContent = doc.content.replace(new RegExp(`doc://${escapeRegex(proj)}:${escapeRegex(oldId)}`, "g"), `doc://${proj}:${newId}`);
+                const newContent = doc.content.replace(new RegExp(`doc://${escapeRegex(proj)}:${escapeRegex(oldId)}${boundary}`, "g"), `doc://${qualifiedTarget}`);
                 if (newContent !== doc.content) {
                     doc.content = newContent;
                     changed = true;
@@ -321,7 +341,7 @@ export class StorageEngine {
                 const newRelated = doc.related_docs.map((ref) => {
                     if (ref === `${proj}:${oldId}`) {
                         changed = true;
-                        return `${proj}:${newId}`;
+                        return qualifiedTarget;
                     }
                     return ref;
                 });

package/dist/src/index.js

@@ -1129,15 +1129,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
             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.",
+            description: "Move a documentation entry to a new path (changes its folder and/or name) and/or to another project. All existing doc:// links and related_docs references pointing to the old location are automatically rewritten across all projects. When the entry changes project, its own same-project links are qualified with the source project so they keep their target, and its tracked_files are then resolved against the target project's code source. This is the only way to relocate a document — update_doc does not change the location. Provide new_path, new_project, or both.",
             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." },
-                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION + " The doc stays in this project — move_doc never moves an entry across projects." },
+                    new_path: { type: "string", description: "New path for the documentation entry, e.g. 'backend/v2/authentication'. Can change folder, name, or both. Omitted: the entry keeps its current path (new_project is then required)." },
+                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION + " This is the project the entry is moved from." },
+                    new_project: { type: "string", description: "Project the entry is moved to. Must already exist (see list_projects). Omitted: the entry stays in `project`." },
                 },
-                required: ["path", "new_path", "project"],
+                required: ["path", "project"],
             },
         },
         {

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

@@ -1,29 +1,43 @@
 import { MoveDocArgsSchema } from "../../shared/schemas/doc.schema.js";
-import { resolveDocInProject, isScopeError, scopeErrorResult } from "../core/project-scope.js";
+import { resolveDocInProject, assertProject, isScopeError, scopeErrorResult } from "../core/project-scope.js";
 export async function moveDoc(storageEngine, embeddingEngine, args) {
     try {
         const validated = MoveDocArgsSchema.parse(args);
         const resolved = await resolveDocInProject(storageEngine, validated.path, validated.project, "move");
         if (isScopeError(resolved))
             return scopeErrorResult(resolved);
-        const resolvedProject = validated.project;
-        const moved = await storageEngine.moveDoc(validated.path, validated.new_path, resolvedProject);
+        const project = validated.project;
+        const newProject = validated.new_project ?? project;
+        const newPath = validated.new_path ?? validated.path;
+        const targetError = assertProject(storageEngine, newProject);
+        if (targetError)
+            return scopeErrorResult(targetError);
+        if (newProject === project && newPath === validated.path) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `"${validated.path}" is already at this path in project "${project}" — nothing to move.` }],
+            };
+        }
+        const moved = await storageEngine.moveDoc(validated.path, project, newPath, newProject);
         if (!moved) {
             return {
                 isError: true,
                 content: [{ type: "text", text: `Failed to move "${validated.path}".` }],
             };
         }
-        await embeddingEngine.moveEmbedding(validated.path, validated.new_path, resolvedProject);
-        const rewritten = await storageEngine.rewriteLinks(validated.path, validated.new_path, resolvedProject);
+        await embeddingEngine.moveEmbedding(validated.path, project, newPath, newProject);
+        const rewritten = await storageEngine.rewriteLinks(validated.path, project, newPath, newProject);
         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.";
+        const crossProjectNote = newProject !== project
+            ? `\n\nLes fichiers suivis (tracked_files) sont désormais résolus depuis la source de code du projet "${newProject}" — lancer check_freshness pour vérifier qu'ils y existent.`
+            : "";
         return {
             content: [
                 {
                     type: "text",
-                    text: `Documentation entry moved successfully.\nFrom: "${validated.path}"\nTo:   "${validated.new_path}"${rewriteNote}`,
+                    text: `Documentation entry moved successfully.\nFrom: "${project}:${validated.path}"\nTo:   "${newProject}:${newPath}"${rewriteNote}${crossProjectNote}`,
                 },
             ],
         };

package/package.json

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