@imenam/mcp-documentor 1.0.54 → 1.0.55

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/index.js

@@ -620,7 +620,7 @@ 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",
@@ -700,7 +700,7 @@ 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",
@@ -841,7 +841,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         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: { 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"],

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

@@ -1,9 +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")
@@ -12,34 +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 content = validated.content_file
+        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();
@@ -53,7 +31,11 @@ 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,

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

@@ -1,6 +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);
@@ -12,9 +13,10 @@ export async function patchDoc(storageEngine, embeddingEngine, args) {
         const search = validated.search_file
             ? fs.readFileSync(validated.search_file, "utf-8")
             : validated.search;
-        const replacement = validated.replacement_file
+        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 {
@@ -26,6 +28,7 @@ export async function patchDoc(storageEngine, embeddingEngine, args) {
             };
         }
         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()) {

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

@@ -1,30 +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";
 import { persistDraft } from "../core/draft-store.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 { resolveCodeRefs, snapshotTrackedFiles, mergeTrackedFiles } from "../core/code-ref-resolver.js";
 export async function updateDoc(storageEngine, embeddingEngine, args) {
     try {
         const validated = UpdateDocArgsSchema.parse(args);
@@ -36,14 +13,25 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
         if (validated.title !== undefined) {
             doc.title = validated.title;
         }
+        let additionalTrackedFiles = [];
         if (validated.content_file !== undefined) {
-            doc.content = fs.readFileSync(validated.content_file, "utf-8");
+            const { content, additionalTrackedFiles: refs } = resolveCodeRefs(fs.readFileSync(validated.content_file, "utf-8"));
+            doc.content = content;
+            additionalTrackedFiles = refs;
         }
         else if (validated.content !== undefined) {
-            doc.content = validated.content;
+            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;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.54";
+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.54';
+export const APP_VERSION = '1.0.55';

package/package.json

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