@imenam/mcp-documentor 1.0.82 → 1.0.83

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

@@ -99,11 +99,18 @@ export declare const FreshnessReportSchema: z.ZodObject<{
     sourceError: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type FreshnessReport = z.infer<typeof FreshnessReportSchema>;
+/**
+ * Descriptions des formes alternatives d'un texte (`<x>_file_path`, `<x>_file_content`,
+ * `<x>_draft`). `<x>_file_path` / `<x>_file_content` forment la paire que le relais de
+ * mcp-http-gateway reconnaît : il lit le fichier sur la machine de l'agent et en envoie
+ * le contenu.
+ */
+export declare function textSourceDescriptions(prefix: string, what: string): {
+    file_path: string;
+    file_content: string;
+    draft: string;
+};
 export declare const CreateDocArgsSchema: z.ZodObject<{
-    project: z.ZodString;
-    title: 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<{
@@ -114,13 +121,14 @@ export declare const CreateDocArgsSchema: z.ZodObject<{
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     folder: z.ZodOptional<z.ZodString>;
     related_docs: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
-export declare const UpdateDocArgsSchema: z.ZodObject<{
-    path: z.ZodString;
+    content_file_path: z.ZodOptional<z.ZodString>;
+    content_file_content: z.ZodOptional<z.ZodString>;
+    content_draft: z.ZodOptional<z.ZodString>;
     project: z.ZodString;
-    title: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
     content: z.ZodOptional<z.ZodString>;
-    content_file: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const UpdateDocArgsSchema: z.ZodObject<{
     tracked_files: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         path: z.ZodString;
         lines: z.ZodArray<z.ZodObject<{
@@ -130,6 +138,13 @@ export declare const UpdateDocArgsSchema: z.ZodObject<{
     }, z.core.$strip>]>>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     related_docs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    content_file_path: z.ZodOptional<z.ZodString>;
+    content_file_content: z.ZodOptional<z.ZodString>;
+    content_draft: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    project: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const GetDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
@@ -162,12 +177,16 @@ export declare const GetDocMetadataArgsSchema: z.ZodObject<{
     project: z.ZodString;
 }, z.core.$strip>;
 export declare const PatchDocArgsSchema: z.ZodObject<{
+    replacement_file_path: z.ZodOptional<z.ZodString>;
+    replacement_file_content: z.ZodOptional<z.ZodString>;
+    replacement_draft: z.ZodOptional<z.ZodString>;
+    replacement: z.ZodOptional<z.ZodString>;
+    search_file_path: z.ZodOptional<z.ZodString>;
+    search_file_content: z.ZodOptional<z.ZodString>;
+    search_draft: z.ZodOptional<z.ZodString>;
     path: z.ZodString;
     project: 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.ZodString;

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

@@ -70,24 +70,45 @@ 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.`);
+/**
+ * Descriptions des formes alternatives d'un texte (`<x>_file_path`, `<x>_file_content`,
+ * `<x>_draft`). `<x>_file_path` / `<x>_file_content` forment la paire que le relais de
+ * mcp-http-gateway reconnaît : il lit le fichier sur la machine de l'agent et en envoie
+ * le contenu.
+ */
+export function textSourceDescriptions(prefix, what) {
+    return {
+        file_path: `Absolute path to a UTF-8 text file on the agent machine whose content is used as ${what}, instead of ${prefix}. The file is left untouched.`,
+        file_content: "Filled in by the mcp-http-gateway relay, never by the agent: the base64 content of the file read on the agent machine.",
+        draft: `Name of a draft saved by the server after a failed call (the name is given in the error message), used as ${what} instead of ${prefix}. The draft is deleted once the call succeeds.`,
+    };
+}
+function textSourceFields(prefix, what) {
+    const d = textSourceDescriptions(prefix, what);
+    return {
+        [`${prefix}_file_path`]: z.string().optional().describe(d.file_path),
+        [`${prefix}_file_content`]: z.string().optional().describe(d.file_content),
+        [`${prefix}_draft`]: z.string().optional().describe(d.draft),
+    };
+}
 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."),
+    ...textSourceFields("content", "the content"),
     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. Provide absolute paths, or paths relative to the project's code root; they are stored relative to that root so the docs stay portable across machines. Tracked files must exist at the project's code source — which is the local working copy by default, or a branch of a GitHub repository when one is configured for the project (check_freshness reports which)."),
     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",
+}).refine(d => d.content !== undefined || d.content_file_path !== undefined || d.content_file_content !== undefined || d.content_draft !== undefined, {
+    message: "One of content, content_file_path or content_draft 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"),
     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."),
+    ...textSourceFields("content", "the new content"),
     tracked_files: z.array(TrackedFileInputSchema).optional().describe("New list of tracked files (replaces existing). Files already tracked with the same scope keep their stored snapshot, so this never changes staleness — only refresh_file_snapshot acknowledges file changes. 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. Provide absolute paths, or paths relative to the project's code root."),
     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)"),
@@ -131,13 +152,13 @@ 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."),
+    ...textSourceFields("search", "the search text"),
     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",
+    ...textSourceFields("replacement", "the replacement"),
+}).refine(d => d.search !== undefined || d.search_file_path !== undefined || d.search_file_content !== undefined || d.search_draft !== undefined, {
+    message: "One of search, search_file_path or search_draft is required",
+}).refine(d => d.replacement !== undefined || d.replacement_file_path !== undefined || d.replacement_file_content !== undefined || d.replacement_draft !== undefined, {
+    message: "One of replacement, replacement_file_path or replacement_draft is required",
 });
 export const CheckLinksArgsSchema = z.object({
     project: requiredProject("the link check").describe("Project whose entries are checked. Mandatory — links are never checked across projects, and there is no current-project fallback."),

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

@@ -1,2 +1,4 @@
+/** Enregistre un brouillon et renvoie son nom. */
 export declare function persistDraft(dataDir: string, label: string, content: string): string;
-export declare function readDraft(filePath: string): string;
+export declare function readDraft(dataDir: string, name: string): string;
+export declare function deleteDraft(dataDir: string, name: string): void;

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

@@ -1,14 +1,34 @@
 import fs from "fs";
 import path from "path";
+/**
+ * Brouillons : le texte envoyé par un appel qui a échoué, conservé côté serveur pour être
+ * réutilisé par nom. Le nom seul circule, jamais le chemin : il désigne un fichier de la
+ * machine du serveur, que l'agent n'a pas forcément sous la main.
+ */
+function draftsDir(dataDir) {
+    return path.join(dataDir, "errors-tmp-files");
+}
+function draftFile(dataDir, name) {
+    if (path.basename(name) !== name || name === "." || name === "..") {
+        throw new Error(`Invalid draft name: "${name}". Pass the name returned in the error message, without any path.`);
+    }
+    return path.join(draftsDir(dataDir), name);
+}
+/** Enregistre un brouillon et renvoie son nom. */
 export function persistDraft(dataDir, label, content) {
-    const draftsDir = path.join(dataDir, "errors-tmp-files");
-    fs.mkdirSync(draftsDir, { recursive: true });
+    fs.mkdirSync(draftsDir(dataDir), { 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;
+    const name = `${timestamp}-${label}.txt`;
+    fs.writeFileSync(path.join(draftsDir(dataDir), name), content, "utf-8");
+    return name;
+}
+export function readDraft(dataDir, name) {
+    const file = draftFile(dataDir, name);
+    if (!fs.existsSync(file)) {
+        throw new Error(`Draft not found: "${name}".`);
+    }
+    return fs.readFileSync(file, "utf-8");
 }
-export function readDraft(filePath) {
-    return fs.readFileSync(filePath, "utf-8");
+export function deleteDraft(dataDir, name) {
+    fs.unlinkSync(draftFile(dataDir, name));
 }

package/dist/src/core/text-input.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Un texte fourni à un outil, sous l'une de trois formes exclusives :
+ *  - en ligne (`inline`) ;
+ *  - par un fichier de la machine de l'agent (`filePath`). Derrière mcp-http-gateway, le
+ *    relais lit ce fichier et envoie son contenu en base64 dans `fileContent` ;
+ *  - par le nom d'un brouillon conservé côté serveur (`draft`).
+ */
+export interface TextInput {
+    inline?: string;
+    filePath?: string;
+    fileContent?: string;
+    draft?: string;
+}
+/** Noms des paramètres de l'outil, pour les messages d'erreur. */
+export interface TextInputParams {
+    inline: string;
+    file: string;
+    draft: string;
+}
+export declare const CONTENT_PARAMS: TextInputParams;
+export declare const SEARCH_PARAMS: TextInputParams;
+export declare const REPLACEMENT_PARAMS: TextInputParams;
+export interface ResolvedText {
+    text: string;
+    /** Nom du brouillon utilisé, à supprimer une fois l'opération réussie. */
+    draft?: string;
+}
+/** Renvoie le texte, ou `undefined` quand aucune forme n'est fournie. Le fichier de l'agent n'est jamais modifié. */
+export declare function resolveTextInput(dataDir: string, input: TextInput, params: TextInputParams): ResolvedText | undefined;

package/dist/src/core/text-input.js

@@ -0,0 +1,29 @@
+import fs from "fs";
+import { readDraft } from "./draft-store.js";
+export const CONTENT_PARAMS = { inline: "content", file: "content_file_path", draft: "content_draft" };
+export const SEARCH_PARAMS = { inline: "search", file: "search_file_path", draft: "search_draft" };
+export const REPLACEMENT_PARAMS = { inline: "replacement", file: "replacement_file_path", draft: "replacement_draft" };
+function countSources(input) {
+    const file = input.filePath !== undefined || input.fileContent !== undefined;
+    return [input.inline !== undefined, file, input.draft !== undefined].filter(Boolean).length;
+}
+/** Renvoie le texte, ou `undefined` quand aucune forme n'est fournie. Le fichier de l'agent n'est jamais modifié. */
+export function resolveTextInput(dataDir, input, params) {
+    const count = countSources(input);
+    if (count === 0)
+        return undefined;
+    if (count > 1) {
+        throw new Error(`Provide only one of ${params.inline}, ${params.file} or ${params.draft}.`);
+    }
+    if (input.inline !== undefined)
+        return { text: input.inline };
+    if (input.draft !== undefined)
+        return { text: readDraft(dataDir, input.draft), draft: input.draft };
+    if (input.fileContent !== undefined) {
+        return { text: Buffer.from(input.fileContent.replace(/^data:[^;,]*;base64,/, ""), "base64").toString("utf-8") };
+    }
+    if (!fs.existsSync(input.filePath)) {
+        throw new Error(`File not found: ${input.filePath} (${params.file}).`);
+    }
+    return { text: fs.readFileSync(input.filePath, "utf-8") };
+}

package/dist/src/index.js

@@ -45,6 +45,7 @@ import { getImage } from "./tools/get-image.js";
 import { SyncEngine } from "./core/git-sync.js";
 import { syncStatus, pullDocs, pushDocs, syncDocs, resolveSyncConflict } from "./tools/sync.js";
 import { listConflicts, getConflictHunks, resolveConflictHunks } from "./tools/conflicts.js";
+import { textSourceDescriptions, } from "../shared/schemas/doc.schema.js";
 import { isReadOnly, WRITE_TOOLS } from "../shared/read-only.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -883,6 +884,15 @@ async function reconnectGui(args) {
 }
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     const PROJECT_PARAM_DESCRIPTION = "Project the documentation entry belongs to. REQUIRED — never guessed, and never defaulted to the current project. Use list_projects or get_doc_tree if you are unsure which project holds the entry.";
+    /** Propriétés `<x>_file_path` / `<x>_file_content` / `<x>_draft` d'un texte, pour les schémas publiés. */
+    const textSourceProperties = (prefix, what) => {
+        const d = textSourceDescriptions(prefix, what);
+        return {
+            [`${prefix}_file_path`]: { type: "string", description: d.file_path },
+            [`${prefix}_file_content`]: { type: "string", description: d.file_content },
+            [`${prefix}_draft`]: { type: "string", description: d.draft },
+        };
+    };
     const tools = [
         {
             name: "create_doc",
@@ -892,7 +902,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 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. 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)." },
+                    ...textSourceProperties("content", "the content"),
                     tracked_files: {
                         type: "array",
                         items: {
@@ -973,7 +983,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         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. 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)." },
+                    ...textSourceProperties("content", "the new content"),
                     tracked_files: {
                         type: "array",
                         items: {
@@ -1105,12 +1115,12 @@ 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" },
-                    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)." },
+                    ...textSourceProperties("search", "the search text"),
                     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)." },
+                    ...textSourceProperties("replacement", "the replacement"),
                     project: { type: "string", description: PROJECT_PARAM_DESCRIPTION },
                 },
-                required: ["path", "search", "project"],
+                required: ["path", "project"],
             },
         },
         {

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

@@ -1,6 +1,6 @@
-import fs from "fs";
 import { CreateDocArgsSchema } from "../../shared/schemas/doc.schema.js";
-import { persistDraft } from "../core/draft-store.js";
+import { persistDraft, deleteDraft } from "../core/draft-store.js";
+import { resolveTextInput, CONTENT_PARAMS } from "../core/text-input.js";
 import { resolveCodeRefs, snapshotTrackedFiles } from "../core/code-ref-resolver.js";
 export function slugify(title) {
     return title
@@ -14,10 +14,13 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
     try {
         const validated = CreateDocArgsSchema.parse(args);
         const { project } = validated;
-        const rawContent = validated.content_file
-            ? fs.readFileSync(validated.content_file, "utf-8")
-            : validated.content;
-        const { content, additionalTrackedFiles } = await resolveCodeRefs(rawContent, project);
+        const source = resolveTextInput(storageEngine.getDataDir(), {
+            inline: validated.content,
+            filePath: validated.content_file_path,
+            fileContent: validated.content_file_content,
+            draft: validated.content_draft,
+        }, CONTENT_PARAMS);
+        const { content, additionalTrackedFiles } = await resolveCodeRefs(source.text, project);
         const slug = slugify(validated.title);
         const id = validated.folder ? `${validated.folder}/${slug}` : slug;
         const now = new Date().toISOString();
@@ -54,8 +57,8 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
                 await embeddingEngine.saveEmbedding(id, embedding, resolvedProject);
             }
         }
-        if (validated.content_file) {
-            fs.unlinkSync(validated.content_file);
+        if (source.draft) {
+            deleteDraft(storageEngine.getDataDir(), source.draft);
         }
         return {
             content: [
@@ -70,10 +73,10 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
         const message = err instanceof Error ? err.message : String(err);
         const rawContent = args?.content;
         if (rawContent) {
-            const draftPath = persistDraft(storageEngine.getDataDir(), "create-doc", rawContent);
+            const draft = 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.` }],
+                content: [{ type: "text", text: `Error creating doc: ${message}\n\n⚠️ The content has been saved as draft "${draft}".\nYou can reuse it directly via the content_draft parameter instead of rewriting it.` }],
             };
         }
         return { isError: true, content: [{ type: "text", text: `Error creating doc: ${message}` }] };

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

@@ -1,6 +1,6 @@
-import fs from "fs";
 import { PatchDocArgsSchema } from "../../shared/schemas/doc.schema.js";
-import { persistDraft } from "../core/draft-store.js";
+import { persistDraft, deleteDraft } from "../core/draft-store.js";
+import { resolveTextInput, SEARCH_PARAMS, REPLACEMENT_PARAMS } from "../core/text-input.js";
 import { resolveCodeRefs, mergeTrackedFiles } from "../core/code-ref-resolver.js";
 import { resolveDocInProject, isScopeError, scopeErrorResult } from "../core/project-scope.js";
 export async function patchDoc(storageEngine, embeddingEngine, args) {
@@ -11,13 +11,21 @@ export async function patchDoc(storageEngine, embeddingEngine, args) {
             return scopeErrorResult(resolved);
         const { doc } = resolved;
         const resolvedProject = validated.project;
-        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 } = await resolveCodeRefs(rawReplacement, resolvedProject);
+        const dataDir = storageEngine.getDataDir();
+        const searchSource = resolveTextInput(dataDir, {
+            inline: validated.search,
+            filePath: validated.search_file_path,
+            fileContent: validated.search_file_content,
+            draft: validated.search_draft,
+        }, SEARCH_PARAMS);
+        const replacementSource = resolveTextInput(dataDir, {
+            inline: validated.replacement,
+            filePath: validated.replacement_file_path,
+            fileContent: validated.replacement_file_content,
+            draft: validated.replacement_draft,
+        }, REPLACEMENT_PARAMS);
+        const search = searchSource.text;
+        const { content: replacement, additionalTrackedFiles } = await resolveCodeRefs(replacementSource.text, resolvedProject);
         if (!doc.content.includes(search)) {
             const preview = doc.content.slice(0, 300).replace(/\n/g, "↵");
             return {
@@ -38,10 +46,10 @@ 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);
+        if (searchSource.draft)
+            deleteDraft(dataDir, searchSource.draft);
+        if (replacementSource.draft)
+            deleteDraft(dataDir, replacementSource.draft);
         return {
             content: [{ type: "text", text: `Documentation entry "${validated.path}" patched successfully.` }],
         };
@@ -53,16 +61,16 @@ export async function patchDoc(storageEngine, embeddingEngine, args) {
         if (rawSearch || rawReplacement) {
             const parts = [];
             if (rawSearch) {
-                const searchPath = persistDraft(storageEngine.getDataDir(), "patch-doc-search", rawSearch);
-                parts.push(`search → ${searchPath}`);
+                const searchDraft = persistDraft(storageEngine.getDataDir(), "patch-doc-search", rawSearch);
+                parts.push(`search → draft "${searchDraft}"`);
             }
             if (rawReplacement) {
-                const replacementPath = persistDraft(storageEngine.getDataDir(), "patch-doc-replacement", rawReplacement);
-                parts.push(`replacement → ${replacementPath}`);
+                const replacementDraft = persistDraft(storageEngine.getDataDir(), "patch-doc-replacement", rawReplacement);
+                parts.push(`replacement → draft "${replacementDraft}"`);
             }
             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.` }],
+                content: [{ type: "text", text: `Error patching doc: ${message}\n\n⚠️ The following content has been saved as drafts:\n${parts.join("\n")}\nYou can reuse them directly via the search_draft / replacement_draft parameters instead of rewriting them.` }],
             };
         }
         return { isError: true, content: [{ type: "text", text: `Error patching doc: ${message}` }] };

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

@@ -1,6 +1,6 @@
-import fs from "fs";
 import { UpdateDocArgsSchema } from "../../shared/schemas/doc.schema.js";
-import { persistDraft } from "../core/draft-store.js";
+import { persistDraft, deleteDraft } from "../core/draft-store.js";
+import { resolveTextInput, CONTENT_PARAMS } from "../core/text-input.js";
 import { resolveCodeRefs, resnapshotPreserving, mergeTrackedFiles } from "../core/code-ref-resolver.js";
 import { resolveDocInProject, isScopeError, scopeErrorResult } from "../core/project-scope.js";
 export async function updateDoc(storageEngine, embeddingEngine, args) {
@@ -15,13 +15,14 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
             doc.title = validated.title;
         }
         let additionalTrackedFiles = [];
-        if (validated.content_file !== undefined) {
-            const { content, additionalTrackedFiles: refs } = await resolveCodeRefs(fs.readFileSync(validated.content_file, "utf-8"), resolvedProject);
-            doc.content = content;
-            additionalTrackedFiles = refs;
-        }
-        else if (validated.content !== undefined) {
-            const { content, additionalTrackedFiles: refs } = await resolveCodeRefs(validated.content, resolvedProject);
+        const source = resolveTextInput(storageEngine.getDataDir(), {
+            inline: validated.content,
+            filePath: validated.content_file_path,
+            fileContent: validated.content_file_content,
+            draft: validated.content_draft,
+        }, CONTENT_PARAMS);
+        if (source) {
+            const { content, additionalTrackedFiles: refs } = await resolveCodeRefs(source.text, resolvedProject);
             doc.content = content;
             additionalTrackedFiles = refs;
         }
@@ -47,22 +48,24 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
         }
         doc.updatedAt = new Date().toISOString();
         await storageEngine.saveDoc(doc, resolvedProject, "update");
-        if ((validated.content !== undefined || validated.content_file !== undefined) && embeddingEngine.isConfigured()) {
+        if (source && 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);
+        if (source?.draft) {
+            deleteDraft(storageEngine.getDataDir(), source.draft);
         }
         const changes = [];
         if (validated.title !== undefined)
             changes.push(`title (${doc.title})`);
         if (validated.content !== undefined)
             changes.push("content");
-        if (validated.content_file !== undefined)
+        if (validated.content_file_path !== undefined || validated.content_file_content !== undefined)
             changes.push("content (from file)");
+        if (validated.content_draft !== undefined)
+            changes.push(`content (from draft "${validated.content_draft}")`);
         if (trackedResult !== undefined) {
             const parts = [`${doc.tracked_files.length} files`];
             if (trackedResult.preserved.length > 0)
@@ -87,10 +90,10 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
         const message = err instanceof Error ? err.message : String(err);
         const rawContent = args?.content;
         if (rawContent) {
-            const draftPath = persistDraft(storageEngine.getDataDir(), "update-doc", rawContent);
+            const draft = 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.` }],
+                content: [{ type: "text", text: `Error updating doc: ${message}\n\n⚠️ The content has been saved as draft "${draft}".\nYou can reuse it directly via the content_draft 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.82";
+export declare const APP_VERSION = "1.0.83";

package/dist/src/version.js

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

package/package.json

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