@imenam/mcp-documentor 1.0.23

package/gui/dist/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>MCP Documentor</title>
+    <script type="module" crossorigin src="/assets/index-CzuFn4Pp.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BwyK1pan.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/gui/dist/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@imenam/mcp-documentor",
+  "version": "1.0.23",
+  "main": "dist/src/index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "generate-version": "node scripts/generate-version.js",
+    "build:backend": "npm run generate-version && tsc",
+    "build:gui": "cd gui && npm install && npm run build",
+    "build": "npm run build:backend && npm run build:gui",
+    "start": "node dist/src/index.js",
+    "prepublishOnly": "npm run build",
+    "release": "npm version patch && npm publish && git push --follow-tags"
+  },
+  "keywords": [
+    "mcp",
+    "documentation",
+    "markdown",
+    "semantic-search",
+    "model-context-protocol",
+    "ai"
+  ],
+  "author": "Imena",
+  "license": "ISC",
+  "description": "MCP server to create, manage and search project documentation with staleness tracking and semantic search.",
+  "dependencies": {
+    "@hono/node-server": "^1.19.10",
+    "@imenam/mcp-gui-interface": "^1.0.3",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "better-sqlite3": "^12.8.0",
+    "dotenv": "^17.3.1",
+    "github-slugger": "^2.0.0",
+    "gray-matter": "^4.0.3",
+    "hono": "^4.12.5",
+    "openai": "^6.25.0",
+    "zod": "^4.3.6"
+  },
+  "type": "module",
+  "bin": {
+    "mcp-documentor": "dist/src/index.js",
+    "mcp-documentor-migrate": "scripts/migrate-links.js"
+  },
+  "files": [
+    "dist",
+    "gui/dist",
+    "README.md",
+    "scripts"
+  ],
+  "config": {
+    "FIXED_GUI_PORT": "4205",
+    "PROXY_URL": ""
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/generate-version.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.join(__dirname, '..');
+
+const packagePath = path.join(rootDir, 'package.json');
+const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+
+const versionContent = `// Auto-generated version file - do not edit manually
+export const APP_VERSION = '${pkg.version}';
+`;
+
+const outputPath = path.join(rootDir, 'src', 'version.ts');
+fs.writeFileSync(outputPath, versionContent, 'utf8');
+
+console.log(`Generated version file: ${outputPath}`);
+console.log(`  Version: ${pkg.version}`);

package/scripts/migrate-links.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+/**
+ * migrate-links.js
+ *
+ * Migrates inter-document references from the old slug-only format
+ * to the new full-path format (folder/name) introduced in Task 10.
+ *
+ * Fixes two types of links:
+ *   - related_docs:  ["old-slug"]         → ["folder/old-slug"]
+ *   - inline links:  (doc://old-slug)      → (doc://folder/old-slug)
+ *                    (doc://old-slug#h)    → (doc://folder/old-slug#h)
+ *
+ * Usage:
+ *   node scripts/migrate-links.js [--dry-run] [--data-dir /path/to/.docs-data]
+ *
+ * Options:
+ *   --dry-run     Show what would be changed without modifying any file.
+ *   --data-dir    Override the data directory (default: <project-root>/.docs-data).
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import matter from "gray-matter";
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.join(__dirname, "..");
+
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+
+const dataDirArgIdx = args.indexOf("--data-dir");
+const dataDir =
+  dataDirArgIdx !== -1 && args[dataDirArgIdx + 1]
+    ? args[dataDirArgIdx + 1]
+    : path.join(rootDir, ".docs-data");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function walkMdFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkMdFiles(fullPath));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+/** Derive the doc path (id) from an absolute file path within a project dir. */
+function filePathToDocId(filePath, projectDir) {
+  return path
+    .relative(projectDir, filePath)
+    .replace(/\.md$/, "")
+    .split(path.sep)
+    .join("/");
+}
+
+// ---------------------------------------------------------------------------
+// Load config
+// ---------------------------------------------------------------------------
+
+const configPath = path.join(dataDir, "config.json");
+if (!fs.existsSync(configPath)) {
+  console.error(`[ERROR] config.json not found at: ${configPath}`);
+  console.error("       Make sure --data-dir points to the right directory.");
+  process.exit(1);
+}
+
+const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+const projects = config.projects ?? ["default"];
+
+console.log(`${dryRun ? "[DRY RUN] " : ""}migrate-links`);
+console.log(`Data dir : ${dataDir}`);
+console.log(`Projects : ${projects.join(", ")}`);
+console.log("");
+
+// ---------------------------------------------------------------------------
+// Step 1 — Build the global map:  slug → [{ project, fullId }]
+//
+// A "slug" is the last segment of a doc path (the filename without .md).
+// If a slug appears in multiple projects or folders, the reference is ambiguous.
+// ---------------------------------------------------------------------------
+
+/** @type {Map<string, Array<{ project: string, fullId: string }>>} */
+const slugMap = new Map();
+
+for (const project of projects) {
+  const projectDir = path.join(dataDir, "projects", project);
+  for (const filePath of walkMdFiles(projectDir)) {
+    const fullId = filePathToDocId(filePath, projectDir);
+    const slug = fullId.split("/").pop();
+
+    if (!slugMap.has(slug)) slugMap.set(slug, []);
+    slugMap.get(slug).push({ project, fullId });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step 2 — Scan every doc and fix links
+// ---------------------------------------------------------------------------
+
+let totalDocsChanged = 0;
+let totalLinksFixed = 0;
+let totalLinksNotFound = 0;
+let totalLinksAmbiguous = 0;
+
+/**
+ * Resolve an old slug-only reference to its full path.
+ * Returns { resolved: string } on success, or { error: string } otherwise.
+ */
+function resolveSlug(slug) {
+  const matches = slugMap.get(slug) ?? [];
+  if (matches.length === 0) return { error: "NOT FOUND" };
+  if (matches.length > 1) {
+    return { error: `AMBIGUOUS → [${matches.map((m) => m.fullId).join(", ")}]` };
+  }
+  return { resolved: matches[0].fullId };
+}
+
+for (const project of projects) {
+  const projectDir = path.join(dataDir, "projects", project);
+  const files = walkMdFiles(projectDir);
+
+  if (files.length === 0) continue;
+
+  console.log(`\n### Project: ${project} (${files.length} docs)`);
+  console.log("");
+
+  for (const filePath of files) {
+    const fullId = filePathToDocId(filePath, projectDir);
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const parsed = matter(raw);
+
+    const docChanges = [];
+    let docChanged = false;
+
+    // -----------------------------------------------------------------------
+    // Fix related_docs
+    // -----------------------------------------------------------------------
+
+    if (Array.isArray(parsed.data.related_docs)) {
+      const newRelatedDocs = [];
+
+      for (const ref of parsed.data.related_docs) {
+        // Already a full path — nothing to do
+        if (ref.includes("/")) {
+          newRelatedDocs.push(ref);
+          continue;
+        }
+
+        const result = resolveSlug(ref);
+
+        if (result.resolved) {
+          docChanges.push(`  [related_docs] "${ref}"  →  "${result.resolved}"`);
+          newRelatedDocs.push(result.resolved);
+          docChanged = true;
+          totalLinksFixed++;
+        } else {
+          docChanges.push(`  [related_docs] "${ref}"  →  ${result.error} (kept as-is)`);
+          newRelatedDocs.push(ref);
+          if (result.error === "NOT FOUND") totalLinksNotFound++;
+          else totalLinksAmbiguous++;
+        }
+      }
+
+      if (docChanged) {
+        parsed.data.related_docs = newRelatedDocs;
+      }
+    }
+
+    // -----------------------------------------------------------------------
+    // Fix inline doc:// links in content
+    //
+    // Matches: doc://slug  or  doc://slug#anchor
+    // Does NOT touch: doc://folder/slug (already full path)
+    // -----------------------------------------------------------------------
+
+    // Pattern captures:  group1 = slug-or-path,  group2 = optional #anchor
+    const docLinkRegex = /doc:\/\/([^)#\s]+)(#[^)\s]*)?/g;
+    let newContent = parsed.content;
+
+    // Collect all matches first to avoid mutation during iteration
+    const contentMatches = [];
+    let m;
+    while ((m = docLinkRegex.exec(parsed.content)) !== null) {
+      contentMatches.push({ full: m[0], ref: m[1], anchor: m[2] ?? "" });
+    }
+
+    for (const { full, ref, anchor } of contentMatches) {
+      // Already a full path
+      if (ref.includes("/")) continue;
+
+      const result = resolveSlug(ref);
+
+      if (result.resolved) {
+        const newLink = `doc://${result.resolved}${anchor}`;
+        docChanges.push(`  [doc link]    "${full}"  →  "${newLink}"`);
+        // Replace only this specific occurrence (anchor included for precision)
+        newContent = newContent.replaceAll(full, newLink);
+        docChanged = true;
+        totalLinksFixed++;
+      } else {
+        docChanges.push(`  [doc link]    "${full}"  →  ${result.error} (kept as-is)`);
+        if (result.error === "NOT FOUND") totalLinksNotFound++;
+        else totalLinksAmbiguous++;
+      }
+    }
+
+    // -----------------------------------------------------------------------
+    // Report & write
+    // -----------------------------------------------------------------------
+
+    if (docChanges.length > 0) {
+      console.log(`  [${fullId}]`);
+      docChanges.forEach((c) => console.log(c));
+      console.log("");
+    }
+
+    if (docChanged) {
+      totalDocsChanged++;
+      if (!dryRun) {
+        const output = matter.stringify(newContent, parsed.data);
+        fs.writeFileSync(filePath, output, "utf-8");
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+console.log("─".repeat(60));
+console.log(`Links fixed          : ${totalLinksFixed}`);
+if (totalLinksNotFound > 0) {
+  console.log(`Links not found      : ${totalLinksNotFound}  ← target doc doesn't exist`);
+}
+if (totalLinksAmbiguous > 0) {
+  console.log(`Links ambiguous      : ${totalLinksAmbiguous}  ← same slug in multiple folders, fix manually`);
+}
+console.log(`Docs modified        : ${totalDocsChanged}`);
+
+if (dryRun) {
+  console.log("");
+  console.log("[DRY RUN] No files were modified.");
+  console.log("          Run without --dry-run to apply the changes.");
+}