@imenam/mcp-documentor 1.0.53 → 1.0.55

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

@@ -90,7 +90,8 @@ export declare const FreshnessReportSchema: z.ZodObject<{
 export type FreshnessReport = z.infer<typeof FreshnessReportSchema>;
 export declare const CreateDocArgsSchema: z.ZodObject<{
     title: z.ZodString;
-    content: z.ZodString;
+    content: z.ZodOptional<z.ZodString>;
+    content_file: z.ZodOptional<z.ZodString>;
     tracked_files: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         path: z.ZodString;
         lines: z.ZodArray<z.ZodObject<{
@@ -106,6 +107,7 @@ export declare const UpdateDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
     content: z.ZodOptional<z.ZodString>;
+    content_file: z.ZodOptional<z.ZodString>;
     tracked_files: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         path: z.ZodString;
         lines: z.ZodArray<z.ZodObject<{
@@ -140,8 +142,10 @@ export declare const GetDocMetadataArgsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const PatchDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
-    search: z.ZodString;
-    replacement: z.ZodString;
+    search: z.ZodOptional<z.ZodString>;
+    search_file: z.ZodOptional<z.ZodString>;
+    replacement: z.ZodOptional<z.ZodString>;
+    replacement_file: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const CheckLinksArgsSchema: z.ZodObject<{
     project: z.ZodOptional<z.ZodString>;

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

@@ -45,16 +45,20 @@ export const FreshnessReportSchema = z.object({
 });
 export const CreateDocArgsSchema = z.object({
     title: z.string().describe("Title of the documentation entry"),
-    content: z.string().describe("Documentation content in markdown"),
+    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."),
     tracked_files: z.array(TrackedFileInputSchema).optional().describe("Files to track for staleness detection. Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive."),
     tags: z.array(z.string()).optional().describe("Tags for categorization"),
     folder: z.string().optional().describe("Folder path for organization, e.g. 'frontend/components'"),
     related_docs: z.array(z.string()).optional().describe("IDs of related documentation entries"),
+}).refine(d => d.content || d.content_file, {
+    message: "Either content or content_file is required",
 });
 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)"),
+    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."),
     tracked_files: z.array(TrackedFileInputSchema).optional().describe("New list of tracked files (replaces existing). Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive."),
     tags: z.array(z.string()).optional().describe("New tags (replaces existing)"),
     related_docs: z.array(z.string()).optional().describe("Paths of related documentation entries (replaces existing)"),
@@ -83,8 +87,14 @@ export const GetDocMetadataArgsSchema = z.object({
 });
 export const PatchDocArgsSchema = z.object({
     path: z.string().describe("Path of the documentation entry to patch, e.g. 'backend/auth/authentication'"),
-    search: z.string().describe("Exact text to find in the current content"),
-    replacement: z.string().describe("Text to replace it with"),
+    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"),
+    replacement_file: z.string().optional().describe("Absolute path to a text file whose content will be used as the replacement. Use this to reuse a previously persisted draft."),
+}).refine(d => d.search || d.search_file, {
+    message: "Either search or search_file is required",
+}).refine(d => d.replacement || d.replacement_file, {
+    message: "Either replacement or replacement_file is required",
 });
 export const CheckLinksArgsSchema = z.object({
     project: z.string().optional().describe("Project to check (defaults to current project)"),

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/core/draft-store.d.ts

@@ -0,0 +1,2 @@
+export declare function persistDraft(dataDir: string, label: string, content: string): string;
+export declare function readDraft(filePath: string): string;

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

@@ -0,0 +1,14 @@
+import fs from "fs";
+import path from "path";
+export function persistDraft(dataDir, label, content) {
+    const draftsDir = path.join(dataDir, "errors-tmp-files");
+    fs.mkdirSync(draftsDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const filename = `${timestamp}-${label}.txt`;
+    const filePath = path.join(draftsDir, filename);
+    fs.writeFileSync(filePath, content, "utf-8");
+    return filePath;
+}
+export function readDraft(filePath) {
+    return fs.readFileSync(filePath, "utf-8");
+}

package/dist/src/index.js

@@ -620,7 +620,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     type: "object",
                     properties: {
                         title: { type: "string", description: "Title of the documentation entry" },
-                        content: { type: "string", description: "Documentation content in markdown. To link to another document inline, use the syntax [text](doc://target-doc-id) — the viewer will navigate to that document on click. To link to a heading within the same document, use [text](#heading-slug). Use check_links to validate both types. For code blocks, always specify a language identifier for syntax highlighting, e.g. ```typescript, ```python, ```bash, ```json, ```yaml, ```sql." },
+                        content: { type: "string", description: "Documentation content in markdown. To link to another document inline, use the syntax [text](doc://target-doc-id) — the viewer will navigate to that document on click. To link to a heading within the same document, use [text](#heading-slug). Use check_links to validate both types. For code blocks, always specify a language identifier for syntax highlighting, e.g. ```typescript, ```python, ```bash, ```json, ```yaml, ```sql. To embed a code excerpt directly from a source file, use [copy-from-codebase|/absolute/path/to/file.ts|startLine|endLine] — the tag is replaced at save time by a fenced code block with automatic language detection, and the file+range is automatically added to tracked_files. IMPORTANT: always read the source file first to identify the exact line numbers before writing the tag." },
+                        content_file: { type: "string", description: "Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
                         tracked_files: {
                             type: "array",
                             items: {
@@ -664,7 +665,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         },
                         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"],
+                    required: ["title"],
                 },
             },
             {
@@ -699,7 +700,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             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." },
+                        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. To embed a code excerpt directly from a source file, use [copy-from-codebase|/absolute/path/to/file.ts|startLine|endLine] — the tag is replaced at save time by a fenced code block with automatic language detection, and the file+range is automatically added to tracked_files. IMPORTANT: always read the source file first to identify the exact line numbers before writing the tag." },
+                        content_file: { type: "string", description: "Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
                         tracked_files: {
                             type: "array",
                             items: {
@@ -838,9 +840,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {
                         path: { type: "string", description: "Path of the documentation entry to patch, e.g. 'backend/auth/authentication'" },
                         search: { type: "string", description: "Exact text to find in the current content" },
-                        replacement: { type: "string", description: "Text to replace it with" },
+                        search_file: { type: "string", description: "Absolute path to a text file whose content will be used as the search text. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
+                        replacement: { type: "string", description: "Text to replace it with. Supports [copy-from-codebase|/absolute/path/to/file.ts|startLine|endLine] — the tag is replaced at save time by a fenced code block, and the file+range is automatically added to tracked_files. IMPORTANT: always read the source file first to identify the exact line numbers before writing the tag." },
+                        replacement_file: { type: "string", description: "Absolute path to a text file whose content will be used as the replacement. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
                     },
-                    required: ["path", "search", "replacement"],
+                    required: ["path", "search"],
                 },
             },
             {

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

@@ -1,8 +1,7 @@
 import fs from "fs";
-import path from "path";
 import { CreateDocArgsSchema } from "../../shared/schemas/doc.schema.js";
-import { computeFileHash } from "./check-freshness.js";
-import { snapshotSection } from "../core/section-tracker.js";
+import { persistDraft } from "../core/draft-store.js";
+import { resolveCodeRefs, snapshotTrackedFiles } from "../core/code-ref-resolver.js";
 export function slugify(title) {
     return title
         .normalize("NFD")
@@ -11,31 +10,14 @@ export function slugify(title) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-|-$/g, "");
 }
-function snapshotTrackedFiles(inputs) {
-    const tracked = [];
-    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();
-        if (typeof input !== "string" && input.lines.length > 0 && fs.existsSync(absolutePath)) {
-            const sections = input.lines
-                .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;
-}
 export async function createDoc(storageEngine, embeddingEngine, args) {
     try {
         const validated = CreateDocArgsSchema.parse(args);
         const { project } = (args ?? {});
+        const rawContent = validated.content_file
+            ? fs.readFileSync(validated.content_file, "utf-8")
+            : validated.content;
+        const { content, additionalTrackedFiles } = resolveCodeRefs(rawContent);
         const slug = slugify(validated.title);
         const id = validated.folder ? `${validated.folder}/${slug}` : slug;
         const now = new Date().toISOString();
@@ -49,12 +31,16 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
         if (project) {
             storageEngine.ensureProject(project);
         }
-        const trackedFiles = validated.tracked_files ? snapshotTrackedFiles(validated.tracked_files) : [];
+        const allTrackedInputs = [
+            ...(validated.tracked_files ?? []),
+            ...additionalTrackedFiles,
+        ];
+        const trackedFiles = allTrackedInputs.length > 0 ? snapshotTrackedFiles(allTrackedInputs) : [];
         const folder = validated.folder;
         const doc = {
             id,
             title: validated.title,
-            content: validated.content,
+            content,
             tracked_files: trackedFiles,
             tags: validated.tags ?? [],
             folder,
@@ -65,11 +51,14 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
         const resolvedProject = project ?? storageEngine.getConfig().currentProject;
         await storageEngine.saveDoc(doc, resolvedProject, "create");
         if (embeddingEngine.isConfigured()) {
-            const embedding = await embeddingEngine.generateEmbedding(validated.content);
+            const embedding = await embeddingEngine.generateEmbedding(content);
             if (embedding) {
                 await embeddingEngine.saveEmbedding(id, embedding, resolvedProject);
             }
         }
+        if (validated.content_file) {
+            fs.unlinkSync(validated.content_file);
+        }
         return {
             content: [
                 {
@@ -81,6 +70,14 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        const rawContent = args?.content;
+        if (rawContent) {
+            const draftPath = persistDraft(storageEngine.getDataDir(), "create-doc", rawContent);
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error creating doc: ${message}\n\n⚠️ The content has been saved to: ${draftPath}\nYou can reuse it directly via the content_file parameter instead of rewriting it.` }],
+            };
+        }
         return { isError: true, content: [{ type: "text", text: `Error creating doc: ${message}` }] };
     }
 }

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

@@ -1,4 +1,7 @@
+import fs from "fs";
 import { PatchDocArgsSchema } from "../../shared/schemas/doc.schema.js";
+import { persistDraft } from "../core/draft-store.js";
+import { resolveCodeRefs, mergeTrackedFiles } from "../core/code-ref-resolver.js";
 export async function patchDoc(storageEngine, embeddingEngine, args) {
     try {
         const validated = PatchDocArgsSchema.parse(args);
@@ -7,7 +10,14 @@ export async function patchDoc(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 (!doc.content.includes(validated.search)) {
+        const search = validated.search_file
+            ? fs.readFileSync(validated.search_file, "utf-8")
+            : validated.search;
+        const rawReplacement = validated.replacement_file
+            ? fs.readFileSync(validated.replacement_file, "utf-8")
+            : validated.replacement;
+        const { content: replacement, additionalTrackedFiles } = resolveCodeRefs(rawReplacement);
+        if (!doc.content.includes(search)) {
             const preview = doc.content.slice(0, 300).replace(/\n/g, "↵");
             return {
                 isError: true,
@@ -17,7 +27,8 @@ export async function patchDoc(storageEngine, embeddingEngine, args) {
                     }],
             };
         }
-        doc.content = doc.content.replace(validated.search, validated.replacement);
+        doc.content = doc.content.replace(search, replacement);
+        doc.tracked_files = mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles);
         doc.updatedAt = new Date().toISOString();
         await storageEngine.saveDoc(doc, resolvedProject, "patch");
         if (embeddingEngine.isConfigured()) {
@@ -26,12 +37,33 @@ export async function patchDoc(storageEngine, embeddingEngine, args) {
                 await embeddingEngine.saveEmbedding(validated.path, embedding, resolvedProject);
             }
         }
+        if (validated.search_file)
+            fs.unlinkSync(validated.search_file);
+        if (validated.replacement_file)
+            fs.unlinkSync(validated.replacement_file);
         return {
             content: [{ type: "text", text: `Documentation entry "${validated.path}" patched successfully.` }],
         };
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        const rawSearch = args?.search;
+        const rawReplacement = args?.replacement;
+        if (rawSearch || rawReplacement) {
+            const parts = [];
+            if (rawSearch) {
+                const searchPath = persistDraft(storageEngine.getDataDir(), "patch-doc-search", rawSearch);
+                parts.push(`search → ${searchPath}`);
+            }
+            if (rawReplacement) {
+                const replacementPath = persistDraft(storageEngine.getDataDir(), "patch-doc-replacement", rawReplacement);
+                parts.push(`replacement → ${replacementPath}`);
+            }
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error patching doc: ${message}\n\n⚠️ The following content has been saved:\n${parts.join("\n")}\nYou can reuse them directly via the search_file / replacement_file parameters instead of rewriting them.` }],
+            };
+        }
         return { isError: true, content: [{ type: "text", text: `Error patching doc: ${message}` }] };
     }
 }

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

@@ -1,29 +1,7 @@
 import fs from "fs";
-import path from "path";
 import { UpdateDocArgsSchema } from "../../shared/schemas/doc.schema.js";
-import { computeFileHash } from "./check-freshness.js";
-import { snapshotSection } from "../core/section-tracker.js";
-function snapshotTrackedFiles(inputs) {
-    const tracked = [];
-    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();
-        if (typeof input !== "string" && input.lines.length > 0 && fs.existsSync(absolutePath)) {
-            const sections = input.lines
-                .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;
-}
+import { persistDraft } from "../core/draft-store.js";
+import { resolveCodeRefs, snapshotTrackedFiles, mergeTrackedFiles } from "../core/code-ref-resolver.js";
 export async function updateDoc(storageEngine, embeddingEngine, args) {
     try {
         const validated = UpdateDocArgsSchema.parse(args);
@@ -35,11 +13,25 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
         if (validated.title !== undefined) {
             doc.title = validated.title;
         }
-        if (validated.content !== undefined) {
-            doc.content = validated.content;
+        let additionalTrackedFiles = [];
+        if (validated.content_file !== undefined) {
+            const { content, additionalTrackedFiles: refs } = resolveCodeRefs(fs.readFileSync(validated.content_file, "utf-8"));
+            doc.content = content;
+            additionalTrackedFiles = refs;
+        }
+        else if (validated.content !== undefined) {
+            const { content, additionalTrackedFiles: refs } = resolveCodeRefs(validated.content);
+            doc.content = content;
+            additionalTrackedFiles = refs;
         }
         if (validated.tracked_files !== undefined) {
-            doc.tracked_files = snapshotTrackedFiles(validated.tracked_files);
+            doc.tracked_files = snapshotTrackedFiles([
+                ...validated.tracked_files,
+                ...additionalTrackedFiles,
+            ]);
+        }
+        else {
+            doc.tracked_files = mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles);
         }
         if (validated.tags !== undefined) {
             doc.tags = validated.tags;
@@ -49,17 +41,22 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
         }
         doc.updatedAt = new Date().toISOString();
         await storageEngine.saveDoc(doc, resolvedProject, "update");
-        if (validated.content !== undefined && embeddingEngine.isConfigured()) {
-            const embedding = await embeddingEngine.generateEmbedding(validated.content);
+        if ((validated.content !== undefined || validated.content_file !== undefined) && embeddingEngine.isConfigured()) {
+            const embedding = await embeddingEngine.generateEmbedding(doc.content);
             if (embedding) {
                 await embeddingEngine.saveEmbedding(validated.path, embedding, resolvedProject);
             }
         }
+        if (validated.content_file !== undefined) {
+            fs.unlinkSync(validated.content_file);
+        }
         const changes = [];
         if (validated.title !== undefined)
             changes.push(`title (${doc.title})`);
         if (validated.content !== undefined)
             changes.push("content");
+        if (validated.content_file !== undefined)
+            changes.push("content (from file)");
         if (validated.tracked_files !== undefined)
             changes.push(`tracked_files (${doc.tracked_files.length} files)`);
         if (validated.tags !== undefined)
@@ -74,6 +71,14 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        const rawContent = args?.content;
+        if (rawContent) {
+            const draftPath = persistDraft(storageEngine.getDataDir(), "update-doc", rawContent);
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error updating doc: ${message}\n\n⚠️ The content has been saved to: ${draftPath}\nYou can reuse it directly via the content_file parameter instead of rewriting it.` }],
+            };
+        }
         return { isError: true, content: [{ type: "text", text: `Error updating doc: ${message}` }] };
     }
 }

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.53";
+export declare const APP_VERSION = "1.0.55";

package/dist/src/version.js

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

package/package.json

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