@imenam/mcp-documentor 1.0.23

package/dist/src/index.js

@@ -0,0 +1,678 @@
+#!/usr/bin/env node
+import dotenv from "dotenv";
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { APP_VERSION } from "./version.js";
+import { GuiLauncher, createLogger, setupLogging } from "@imenam/mcp-gui-interface";
+import { StorageEngine } from "./core/storage-engine.js";
+import { EmbeddingStore } from "./core/embedding-store.js";
+import { EmbeddingEngine } from "./core/embedding-engine.js";
+import { createDoc } from "./tools/create-doc.js";
+import { getDoc } from "./tools/get-doc.js";
+import { listDocs } from "./tools/list-docs.js";
+import { updateDoc } from "./tools/update-doc.js";
+import { searchDocs } from "./tools/search-docs.js";
+import { checkFreshness, computeFreshness } from "./tools/check-freshness.js";
+import { setProject } from "./tools/set-project.js";
+import { listProjects } from "./tools/list-projects.js";
+import { refreshFileSnapshot } from "./tools/refresh-file-snapshot.js";
+import { getDocMetadata } from "./tools/get-doc-metadata.js";
+import { patchDoc } from "./tools/patch-doc.js";
+import { gitDiffDoc } from "./tools/git-diff-doc.js";
+import { checkLinks } from "./tools/check-links.js";
+import { deleteDoc } from "./tools/delete-doc.js";
+import { moveDoc } from "./tools/move-doc.js";
+import { getDocTree } from "./tools/get-doc-tree.js";
+import { migrateFolders } from "./core/migrate-folders.js";
+import { migrateEmbeddings } from "./core/migrate-embeddings.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function findProjectRoot(startDir) {
+    let current = startDir;
+    while (current !== path.dirname(current)) {
+        if (fs.existsSync(path.join(current, "package.json"))) {
+            return current;
+        }
+        current = path.dirname(current);
+    }
+    return startDir;
+}
+const rootDir = findProjectRoot(__dirname);
+const packageEnvPath = path.join(rootDir, ".env");
+setupLogging({ processLabel: "MASTER", logDir: path.join(rootDir, ".docs-data", "logs") });
+const logger = createLogger("MASTER");
+function getConfig() {
+    if (fs.existsSync(packageEnvPath)) {
+        dotenv.config({ path: packageEnvPath });
+    }
+    return {
+        proxyUrl: process.env.PROXY_URL,
+        version: APP_VERSION,
+    };
+}
+getConfig();
+const storageEngine = new StorageEngine(rootDir);
+const embeddingStore = new EmbeddingStore();
+const embeddingEngine = new EmbeddingEngine(embeddingStore);
+storageEngine.ensureProject(storageEngine.getConfig().currentProject);
+const openaiModel = process.env.MCP_DOCUMENTOR_OPENAI_MODEL || "text-embedding-3-small";
+embeddingStore.init(storageEngine.getDataDir(), openaiModel);
+const server = new Server({ name: "mcp-documentor", version: APP_VERSION }, { capabilities: { tools: {} } });
+let guiLauncher;
+const sseControllers = new Set();
+function broadcastToGUI(message) {
+    const child = guiLauncher.getProcess();
+    if (child?.connected) {
+        try {
+            child.send(message);
+        }
+        catch (err) {
+            logger.error(`Failed to send IPC message: ${err.message}`);
+        }
+    }
+}
+function handleIPCMessage(msg) {
+    if (msg.type === "ALREADY_RUNNING") {
+        logger.info(`GUI is already running at: ${msg.data?.url || "unknown URL"}.`);
+    }
+    else if (msg.type === "READY") {
+        logger.info(`GUI is ready! Access it at: ${msg.data.url}`);
+    }
+    else if (msg.type === "GET_INITIAL_STATE") {
+        handleGetInitialState(msg);
+    }
+    else if (msg.type === "GET_CONFIG") {
+        handleGetConfig(msg);
+    }
+    else if (msg.type === "UPDATE_PROJECT") {
+        handleUpdateProject(msg);
+    }
+    else if (msg.type === "LIST_PROJECTS") {
+        handleListProjects(msg);
+    }
+    else if (msg.type === "LIST_DOCS") {
+        handleListDocs(msg);
+    }
+    else if (msg.type === "GET_DOC") {
+        handleGetDoc(msg);
+    }
+    else if (msg.type === "CHECK_FRESHNESS") {
+        handleCheckFreshness(msg);
+    }
+    else if (msg.type === "SEARCH_DOCS") {
+        handleSearchDocs(msg);
+    }
+    else if (msg.type === "UPDATE_CONFIG") {
+        handleUpdateConfig(msg);
+    }
+    else if (msg.type === "GIT_DIFF") {
+        handleGitDiff(msg);
+    }
+    else {
+        logger.debug(`Unhandled message from GUI: ${msg.type}`);
+    }
+}
+async function handleGetInitialState(msg) {
+    try {
+        const config = storageEngine.getConfig();
+        const docs = await storageEngine.listDocs();
+        for (const doc of docs) {
+            const full = await storageEngine.getDoc(doc.id); // doc.id is now the full path
+            if (full && full.tracked_files.length > 0) {
+                const report = computeFreshness(full.tracked_files);
+                doc.isStale = report.status === "stale";
+            }
+        }
+        broadcastToGUI({
+            type: "INITIAL_STATE",
+            correlationId: msg.correlationId,
+            data: { config, docs, projects: config.projects },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        logger.error(`Failed to get initial state: ${err.message}`);
+    }
+}
+async function handleGetConfig(msg) {
+    const config = storageEngine.getConfig();
+    broadcastToGUI({
+        type: "CONFIG_RESPONSE",
+        correlationId: msg.correlationId,
+        data: { ...config, version: getConfig().version },
+        timestamp: new Date().toISOString(),
+    });
+}
+async function handleUpdateProject(msg) {
+    try {
+        const project = path.basename(msg.data.project);
+        if (!project || project === "..")
+            throw new Error("Invalid project name");
+        storageEngine.ensureProject(project);
+        const config = storageEngine.getConfig();
+        config.currentProject = project;
+        storageEngine.saveConfig(config);
+        const docs = await storageEngine.listDocs();
+        for (const doc of docs) {
+            const full = await storageEngine.getDoc(doc.id);
+            if (full && full.tracked_files.length > 0) {
+                const report = computeFreshness(full.tracked_files);
+                doc.isStale = report.status === "stale";
+            }
+        }
+        broadcastToGUI({
+            type: "UPDATE_PROJECT_RESPONSE",
+            correlationId: msg.correlationId,
+            data: { success: true, currentProject: project },
+            timestamp: new Date().toISOString(),
+        });
+        broadcastToGUI({
+            type: "INITIAL_STATE",
+            data: { config: storageEngine.getConfig(), docs, projects: storageEngine.getConfig().projects },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        broadcastToGUI({
+            type: "UPDATE_PROJECT_RESPONSE",
+            correlationId: msg.correlationId,
+            error: err.message,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
+async function handleListProjects(msg) {
+    const config = storageEngine.getConfig();
+    broadcastToGUI({
+        type: "LIST_PROJECTS_RESPONSE",
+        correlationId: msg.correlationId,
+        data: { projects: config.projects },
+        timestamp: new Date().toISOString(),
+    });
+}
+async function handleListDocs(msg) {
+    try {
+        const docs = await storageEngine.listDocs();
+        for (const doc of docs) {
+            const full = await storageEngine.getDoc(doc.id);
+            if (full && full.tracked_files.length > 0) {
+                const report = computeFreshness(full.tracked_files);
+                doc.isStale = report.status === "stale";
+            }
+        }
+        broadcastToGUI({
+            type: "LIST_DOCS_RESPONSE",
+            correlationId: msg.correlationId,
+            data: { docs },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        broadcastToGUI({
+            type: "LIST_DOCS_RESPONSE",
+            correlationId: msg.correlationId,
+            error: err.message,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
+async function handleGetDoc(msg) {
+    try {
+        const resolved = await storageEngine.resolveDoc(msg.data.id ?? msg.data.path);
+        broadcastToGUI({
+            type: "GET_DOC_RESPONSE",
+            correlationId: msg.correlationId,
+            data: resolved ? { doc: resolved.doc } : null,
+            error: resolved ? undefined : "Doc not found",
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        broadcastToGUI({
+            type: "GET_DOC_RESPONSE",
+            correlationId: msg.correlationId,
+            error: err.message,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
+async function handleCheckFreshness(msg) {
+    try {
+        const resolved = await storageEngine.resolveDoc(msg.data.id ?? msg.data.path);
+        const doc = resolved?.doc;
+        if (!doc) {
+            broadcastToGUI({
+                type: "CHECK_FRESHNESS_RESPONSE",
+                correlationId: msg.correlationId,
+                error: "Doc not found",
+                timestamp: new Date().toISOString(),
+            });
+            return;
+        }
+        const report = computeFreshness(doc.tracked_files);
+        broadcastToGUI({
+            type: "CHECK_FRESHNESS_RESPONSE",
+            correlationId: msg.correlationId,
+            data: { report },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        broadcastToGUI({
+            type: "CHECK_FRESHNESS_RESPONSE",
+            correlationId: msg.correlationId,
+            error: err.message,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
+async function handleSearchDocs(msg) {
+    try {
+        const { query, top_k, all_projects } = msg.data;
+        let results;
+        if (all_projects) {
+            const config = storageEngine.getConfig();
+            results = await embeddingEngine.searchAcrossProjects(query, config.projects, top_k || 10, async (project, docPath) => {
+                const doc = await storageEngine.getDoc(docPath, project);
+                if (!doc)
+                    return null;
+                return { title: doc.title, content: doc.content };
+            });
+        }
+        else {
+            const currentProject = storageEngine.getConfig().currentProject;
+            results = await embeddingEngine.search(query, currentProject, top_k || 5, async (docPath) => {
+                const doc = await storageEngine.getDoc(docPath);
+                if (!doc)
+                    return null;
+                return { title: doc.title, content: doc.content };
+            });
+        }
+        broadcastToGUI({
+            type: "SEARCH_DOCS_RESPONSE",
+            correlationId: msg.correlationId,
+            data: { results },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        broadcastToGUI({
+            type: "SEARCH_DOCS_RESPONSE",
+            correlationId: msg.correlationId,
+            error: err.message,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
+async function handleGitDiff(msg) {
+    try {
+        const result = await gitDiffDoc(storageEngine, { paths: [msg.data.id ?? msg.data.path] });
+        const text = result.content[0]?.text ?? "";
+        broadcastToGUI({
+            type: "GIT_DIFF_RESPONSE",
+            correlationId: msg.correlationId,
+            data: { diff: text, isError: !!result.isError },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        broadcastToGUI({
+            type: "GIT_DIFF_RESPONSE",
+            correlationId: msg.correlationId,
+            error: err.message,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
+async function handleUpdateConfig(msg) {
+    try {
+        const { key, value } = msg.data;
+        const envPath = path.join(rootDir, ".env");
+        let envContent = "";
+        if (fs.existsSync(envPath)) {
+            envContent = fs.readFileSync(envPath, "utf-8");
+        }
+        const regex = new RegExp(`^${key}=.*$`, "m");
+        if (regex.test(envContent)) {
+            envContent = envContent.replace(regex, `${key}=${value}`);
+        }
+        else {
+            envContent += `\n${key}=${value}`;
+        }
+        fs.writeFileSync(envPath, envContent, "utf-8");
+        getConfig();
+        broadcastToGUI({
+            type: "CONFIG_UPDATED",
+            correlationId: msg.correlationId,
+            data: { success: true },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        broadcastToGUI({
+            type: "CONFIG_UPDATED",
+            correlationId: msg.correlationId,
+            error: err.message,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
+guiLauncher = new GuiLauncher({
+    guiPath: path.join(__dirname, "gui-worker.js"),
+    env: { ...process.env },
+    maxRestarts: 0,
+    onMessage: (msg) => {
+        handleIPCMessage(msg);
+    },
+});
+function launchGUI() {
+    if (!process.env.PROXY_URL) {
+        logger.info('[MASTER] PROXY_URL non défini — GUI désactivée.');
+        return;
+    }
+    logger.info("Launching GUI worker...");
+    guiLauncher.start();
+}
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "create_doc",
+                description: "Create a new documentation entry with markdown content, optional tracked files, and tags.",
+                inputSchema: {
+                    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." },
+                        tracked_files: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "File paths to track for staleness detection",
+                        },
+                        tags: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Tags for categorization",
+                        },
+                        folder: { type: "string", description: "Folder path for organization, e.g. 'frontend/components'" },
+                        related_docs: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "IDs of related documentation entries",
+                        },
+                        project: { type: "string", description: "Project to create the doc in (defaults to current project if omitted)" },
+                    },
+                    required: ["title", "content"],
+                },
+            },
+            {
+                name: "get_doc",
+                description: "Retrieve a documentation entry by its path, including full content, tracked files, and metadata.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication' or 'authentication' for root docs" },
+                    },
+                    required: ["path"],
+                },
+            },
+            {
+                name: "list_docs",
+                description: "List all documentation entries in the current project with staleness indicators.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project: { type: "string", description: "Project to list (lists all projects if omitted)" },
+                    },
+                },
+            },
+            {
+                name: "update_doc",
+                description: "Fully replace the content and/or metadata of a documentation entry. WARNING: This overwrites the entire content. Prefer patch_doc for targeted edits — only use update_doc when the changes are so extensive that a patch is impractical. To move a doc to another folder, use move_doc instead.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Path of the documentation entry to update, e.g. 'backend/auth/authentication' or 'authentication' for root docs" },
+                        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." },
+                        tracked_files: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "New list of file paths (replaces existing)",
+                        },
+                        tags: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "New tags (replaces existing)",
+                        },
+                        related_docs: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Paths of related documentation entries (replaces existing), e.g. ['backend/auth/authentication']",
+                        },
+                    },
+                    required: ["path"],
+                },
+            },
+            {
+                name: "move_doc",
+                description: "Move a documentation entry to a new path (changes its folder and/or name). This is the only way to relocate a document — update_doc does not change the location. After moving, use check_links to detect any broken references.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Current path of the documentation entry, e.g. 'backend/authentication'" },
+                        new_path: { type: "string", description: "New path for the documentation entry, e.g. 'backend/v2/authentication'. Can change folder, name, or both." },
+                    },
+                    required: ["path", "new_path"],
+                },
+            },
+            {
+                name: "search_docs",
+                description: "Semantic search across documentation entries using natural language. Requires OpenAI API key.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string", description: "Search query in natural language" },
+                        top_k: { type: "number", description: "Number of results to return (default: 5)" },
+                    },
+                    required: ["query"],
+                },
+            },
+            {
+                name: "check_freshness",
+                description: "Check freshness of documentation. Pass a path to check a single entry, or omit it to scan all docs in a project and get a full staleness report.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Path of a single documentation entry to check, e.g. 'backend/auth/authentication'. If omitted, scans all docs in the project." },
+                        project: { type: "string", description: "Project to scan (scans all projects if omitted). Only used when path is omitted." },
+                    },
+                    required: [],
+                },
+            },
+            {
+                name: "set_project",
+                description: "Switch the active project for the GUI display. This does NOT affect MCP tool operations — tools work across all projects automatically. Use only to control what the graphical interface shows.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project: { type: "string", description: "Project name to switch to" },
+                    },
+                    required: ["project"],
+                },
+            },
+            {
+                name: "list_projects",
+                description: "List all available documentation projects and show which one is currently active.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "refresh_file_snapshot",
+                description: "Mark tracked files as up-to-date by updating their snapshot timestamps. Use when file changes don't affect the documentation. Accepts one or more doc paths.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        paths: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Paths of documentation entries to refresh, e.g. ['backend/auth/authentication', 'setup']",
+                        },
+                        file_paths: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Specific tracked file paths to refresh (all tracked files if omitted)",
+                        },
+                    },
+                    required: ["paths"],
+                },
+            },
+            {
+                name: "get_doc_metadata",
+                description: "Get metadata of a documentation entry (path, title, tags, dates, tracked files with freshness) without loading the full content.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
+                    },
+                    required: ["path"],
+                },
+            },
+            {
+                name: "patch_doc",
+                description: "PREFERRED method for modifying documentation. Replaces a specific portion of a documentation entry's content using an exact search-and-replace, without touching the rest of the doc. Always use this instead of update_doc when making partial changes.",
+                inputSchema: {
+                    type: "object",
+                    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" },
+                    },
+                    required: ["path", "search", "replacement"],
+                },
+            },
+            {
+                name: "git_diff_doc",
+                description: "Show the git diff for each tracked file of one or more docs, between their current state and the last commit before the stored snapshot date.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        paths: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Paths of documentation entries to diff, e.g. ['backend/auth/authentication']",
+                        },
+                        file_paths: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Specific tracked file paths to diff (all tracked files if omitted)",
+                        },
+                    },
+                    required: ["paths"],
+                },
+            },
+            {
+                name: "check_links",
+                description: "Check all links across a project and report broken references. Validates: related_docs IDs, inline doc links ([text](doc://id)) in content, and anchor links ([text](#heading-slug)) in content.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project: { type: "string", description: "Project to check (defaults to current project)" },
+                    },
+                    required: [],
+                },
+            },
+            {
+                name: "delete_doc",
+                description: "Permanently delete a documentation entry. Works across all projects — no need to set the active project first.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Path of the documentation entry to delete, e.g. 'backend/auth/authentication'" },
+                    },
+                    required: ["path"],
+                },
+            },
+            {
+                name: "get_doc_tree",
+                description: "Get the full documentation tree showing folders, subfolders, and documentation names (not file names). Useful to quickly understand the documentation structure of a project.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project: { type: "string", description: "Project to display (shows all projects if omitted)" },
+                    },
+                },
+            },
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "create_doc":
+                return await createDoc(storageEngine, embeddingEngine, args);
+            case "get_doc":
+                return await getDoc(storageEngine, args);
+            case "list_docs":
+                return await listDocs(storageEngine, args);
+            case "update_doc":
+                return await updateDoc(storageEngine, embeddingEngine, args);
+            case "search_docs":
+                return await searchDocs(storageEngine, embeddingEngine, args);
+            case "check_freshness":
+                return await checkFreshness(storageEngine, args);
+            case "set_project":
+                return await setProject(storageEngine, args);
+            case "list_projects":
+                return await listProjects(storageEngine);
+            case "refresh_file_snapshot":
+                return await refreshFileSnapshot(storageEngine, args);
+            case "get_doc_metadata":
+                return await getDocMetadata(storageEngine, args);
+            case "patch_doc":
+                return await patchDoc(storageEngine, embeddingEngine, args);
+            case "git_diff_doc":
+                return await gitDiffDoc(storageEngine, args);
+            case "check_links":
+                return await checkLinks(storageEngine, args);
+            case "delete_doc":
+                return await deleteDoc(storageEngine, embeddingEngine, args);
+            case "move_doc":
+                return await moveDoc(storageEngine, embeddingEngine, args);
+            case "get_doc_tree":
+                return await getDocTree(storageEngine, args);
+            default:
+                throw new Error(`Tool not found: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    await migrateFolders(storageEngine);
+    await migrateEmbeddings(embeddingStore, storageEngine);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("MCP Server connected and running on stdio");
+    launchGUI();
+}
+main().catch((err) => {
+    logger.error(`Fatal error: ${err.message}`);
+    process.exit(1);
+});
+process.on("uncaughtException", (err) => {
+    logger.error(`Uncaught Exception in MASTER: ${err.message}`);
+    logger.error(err.stack || "No stack trace");
+    guiLauncher.getProcess()?.kill("SIGTERM");
+    process.exit(1);
+});