@imenam/mcp-documentor 1.0.52 → 1.0.54

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/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

@@ -38,6 +38,7 @@ import { reindexEmbeddings } from "./tools/reindex-embeddings.js";
 import { prepareExportBundle } from "./tools/prepare-export-bundle.js";
 import { deleteExportBundle } from "./tools/delete-export-bundle.js";
 import { uploadImage } from "./tools/upload-image.js";
+import { getImage } from "./tools/get-image.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 function findProjectRoot(startDir) {
@@ -620,6 +621,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." },
+                        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: {
@@ -663,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,6 +701,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." },
+                        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: {
@@ -837,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" },
+                        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" },
+                        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"],
                 },
             },
             {
@@ -987,6 +992,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["filename", "filePath"],
                 },
             },
+            {
+                name: "get_image",
+                description: "Retrieve an image stored in a project's assets by its URI and return it as a base64-encoded image. Use this when a document references an image (e.g. ![alt](/api/images/{project}/{filename})) and you need to view its content.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        uri: { type: "string", description: "Image URI as it appears in the document, e.g. '/api/images/my-project/screenshot.png'" },
+                    },
+                    required: ["uri"],
+                },
+            },
         ],
     };
 });
@@ -1058,6 +1074,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "upload_image":
                 return await uploadImage(storageEngine, args);
+            case "get_image":
+                return await getImage(storageEngine, args);
             default:
                 throw new Error(`Tool not found: ${name}`);
         }

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

@@ -3,6 +3,7 @@ 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";
 export function slugify(title) {
     return title
         .normalize("NFD")
@@ -36,6 +37,9 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
     try {
         const validated = CreateDocArgsSchema.parse(args);
         const { project } = (args ?? {});
+        const content = validated.content_file
+            ? fs.readFileSync(validated.content_file, "utf-8")
+            : validated.content;
         const slug = slugify(validated.title);
         const id = validated.folder ? `${validated.folder}/${slug}` : slug;
         const now = new Date().toISOString();
@@ -54,7 +58,7 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
         const doc = {
             id,
             title: validated.title,
-            content: validated.content,
+            content,
             tracked_files: trackedFiles,
             tags: validated.tags ?? [],
             folder,
@@ -65,11 +69,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 +88,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/get-image.d.ts

@@ -0,0 +1,15 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+export declare function getImage(storageEngine: StorageEngine, args: unknown): Promise<{
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+} | {
+    content: {
+        type: string;
+        data: string;
+        mimeType: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/src/tools/get-image.js

@@ -0,0 +1,67 @@
+import fs from "fs";
+import path from "path";
+import { z } from "zod";
+const GetImageArgsSchema = z.object({
+    uri: z.string().min(1),
+});
+const MIME_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+};
+export async function getImage(storageEngine, args) {
+    try {
+        const validated = GetImageArgsSchema.parse(args);
+        // Expected URI format: /api/images/{project}/{filename}
+        const match = validated.uri.match(/^\/api\/images\/([^/]+)\/([^/]+)$/);
+        if (!match) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid image URI format. Expected: /api/images/{project}/{filename}. Got: ${validated.uri}`,
+                    },
+                ],
+            };
+        }
+        const project = decodeURIComponent(match[1]);
+        const filename = decodeURIComponent(match[2]);
+        const assetsDir = path.join(storageEngine.getDataDir(), "projects", project, "assets");
+        const filePath = path.join(assetsDir, filename);
+        // Prevent path traversal
+        if (!filePath.startsWith(assetsDir)) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: "Invalid image path." }],
+            };
+        }
+        if (!fs.existsSync(filePath)) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Image not found: ${validated.uri}` }],
+            };
+        }
+        const ext = path.extname(filename).toLowerCase();
+        const mimeType = MIME_TYPES[ext] ?? "application/octet-stream";
+        const data = fs.readFileSync(filePath).toString("base64");
+        return {
+            content: [
+                {
+                    type: "image",
+                    data,
+                    mimeType,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Error retrieving image: ${message}` }] };
+    }
+}

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

@@ -1,4 +1,6 @@
+import fs from "fs";
 import { PatchDocArgsSchema } from "../../shared/schemas/doc.schema.js";
+import { persistDraft } from "../core/draft-store.js";
 export async function patchDoc(storageEngine, embeddingEngine, args) {
     try {
         const validated = PatchDocArgsSchema.parse(args);
@@ -7,7 +9,13 @@ 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 replacement = validated.replacement_file
+            ? fs.readFileSync(validated.replacement_file, "utf-8")
+            : validated.replacement;
+        if (!doc.content.includes(search)) {
             const preview = doc.content.slice(0, 300).replace(/\n/g, "↵");
             return {
                 isError: true,
@@ -17,7 +25,7 @@ export async function patchDoc(storageEngine, embeddingEngine, args) {
                     }],
             };
         }
-        doc.content = doc.content.replace(validated.search, validated.replacement);
+        doc.content = doc.content.replace(search, replacement);
         doc.updatedAt = new Date().toISOString();
         await storageEngine.saveDoc(doc, resolvedProject, "patch");
         if (embeddingEngine.isConfigured()) {
@@ -26,12 +34,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

@@ -3,6 +3,7 @@ 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";
+import { persistDraft } from "../core/draft-store.js";
 function snapshotTrackedFiles(inputs) {
     const tracked = [];
     for (const input of inputs) {
@@ -35,7 +36,10 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
         if (validated.title !== undefined) {
             doc.title = validated.title;
         }
-        if (validated.content !== undefined) {
+        if (validated.content_file !== undefined) {
+            doc.content = fs.readFileSync(validated.content_file, "utf-8");
+        }
+        else if (validated.content !== undefined) {
             doc.content = validated.content;
         }
         if (validated.tracked_files !== undefined) {
@@ -49,17 +53,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 +83,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.52";
+export declare const APP_VERSION = "1.0.54";

package/dist/src/version.js

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

package/package.json

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