mcp-docs-service 0.3.9 → 0.4.0

package/dist/cli/bin.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * MCP Docs Service CLI
+ *
+ * This is the entry point for the CLI version of the MCP Docs Service.
+ * It simply imports and runs the main service.
+ */
+import "../index.js";

package/dist/cli/bin.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * MCP Docs Service CLI
+ *
+ * This is the entry point for the CLI version of the MCP Docs Service.
+ * It simply imports and runs the main service.
+ */
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+// Get the current directory
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Check if we're running under MCP Inspector
+const isMCPInspector = process.env.MCP_INSPECTOR === "true" ||
+    process.argv.some((arg) => arg.includes("modelcontextprotocol/inspector"));
+// Create a logging function that respects MCP Inspector mode
+const log = (...args) => {
+    if (!isMCPInspector) {
+        console.log(...args);
+    }
+};
+const errorLog = (...args) => {
+    console.error(...args);
+};
+// Parse command line arguments
+const args = process.argv.slice(2);
+log("CLI Arguments:", JSON.stringify(args));
+let docsDir = path.join(process.cwd(), "docs");
+let createDir = false;
+let healthCheck = false;
+let showHelp = false;
+// MCP Inspector specific handling
+// When run through MCP Inspector, it might pass arguments in a different format
+if (isMCPInspector) {
+    log("Detected MCP Inspector environment");
+    // Try to find a valid docs directory in all arguments
+    // This is a more aggressive approach but should work with various argument formats
+    for (const arg of process.argv) {
+        if (arg.endsWith("/docs") || arg.includes("/docs ")) {
+            const potentialPath = arg.split(" ")[0];
+            log("Found potential docs path in MCP Inspector args:", potentialPath);
+            if (fs.existsSync(potentialPath)) {
+                docsDir = path.resolve(potentialPath);
+                log("Using docs directory from MCP Inspector:", docsDir);
+                break;
+            }
+        }
+    }
+    // If we couldn't find a valid docs directory, use the default
+    log("Using docs directory:", docsDir);
+}
+else {
+    // Standard argument parsing
+    for (let i = 0; i < args.length; i++) {
+        log(`Processing arg[${i}]:`, args[i]);
+        if (args[i] === "--docs-dir" && i + 1 < args.length) {
+            docsDir = path.resolve(args[i + 1]);
+            log("Setting docs dir from --docs-dir flag:", docsDir);
+            i++; // Skip the next argument
+        }
+        else if (args[i] === "--create-dir") {
+            createDir = true;
+        }
+        else if (args[i] === "--health-check") {
+            healthCheck = true;
+        }
+        else if (args[i] === "--help" || args[i] === "-h") {
+            showHelp = true;
+        }
+        else if (!args[i].startsWith("--")) {
+            // Handle positional argument as docs directory
+            const potentialPath = path.resolve(args[i]);
+            log("Potential positional path:", potentialPath);
+            log("Path exists?", fs.existsSync(potentialPath));
+            if (fs.existsSync(potentialPath)) {
+                docsDir = potentialPath;
+                log("Setting docs dir from positional argument:", docsDir);
+            }
+            else {
+                log("Path doesn't exist, not using as docs dir:", potentialPath);
+            }
+        }
+    }
+}
+log("Final docs dir:", docsDir);
+// Show help if requested
+if (showHelp) {
+    console.log(`
+MCP Docs Service - Documentation Management Service
+
+Usage:
+  mcp-docs-service [options]
+  mcp-docs-service <docs-directory> [options]
+
+Options:
+  --docs-dir <path>   Specify the docs directory (default: ./docs)
+  --create-dir        Create the docs directory if it doesn't exist
+  --health-check      Run a health check on the documentation
+  --help, -h          Show this help message
+  `);
+    process.exit(0);
+}
+// Create docs directory if it doesn't exist and --create-dir is specified
+if (createDir) {
+    try {
+        if (!fs.existsSync(docsDir)) {
+            fs.mkdirSync(docsDir, { recursive: true });
+            log(`Created docs directory: ${docsDir}`);
+        }
+    }
+    catch (error) {
+        errorLog(`Error creating docs directory: ${error}`);
+        process.exit(1);
+    }
+}
+// Ensure the docs directory exists
+if (!fs.existsSync(docsDir)) {
+    errorLog(`Error: Docs directory does not exist: ${docsDir}`);
+    errorLog(`Use --create-dir to create it automatically`);
+    process.exit(1);
+}
+// Add the docs directory to process.argv so it's available to the main service
+process.argv.push(docsDir);
+// Add health check flag to process.argv if specified
+if (healthCheck) {
+    process.argv.push("--health-check");
+}
+// Import the main service
+import "../index.js";
+// The main service will handle the CLI arguments and execution
+// No additional code needed here as the main index.ts already has CLI functionality
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":"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"}

package/dist/handlers/docs.d.ts

@@ -0,0 +1,26 @@
+import { ToolResponse } from "../types/tools.js";
+/**
+ * Reads a markdown document and extracts its content and metadata
+ */
+export declare function readDocument(docPath: string, allowedDirectories: string[]): Promise<ToolResponse>;
+/**
+ * Lists all markdown documents in a directory
+ */
+export declare function listDocuments(basePath: string, allowedDirectories: string[]): Promise<ToolResponse>;
+/**
+ * Gets the structure of the documentation directory
+ */
+export declare function getStructure(basePath: string, allowedDirectories: string[]): Promise<ToolResponse>;
+/**
+ * Gets the navigation structure for the documentation
+ */
+export declare function getNavigation(basePath: string, allowedDirectories: string[]): Promise<ToolResponse>;
+/**
+ * Checks the health of documentation
+ */
+export declare function checkDocumentationHealth(basePath: string, options: {
+    checkLinks?: boolean;
+    checkMetadata?: boolean;
+    checkOrphans?: boolean;
+    requiredMetadataFields?: string[];
+}, allowedDirectories: string[]): Promise<ToolResponse>;

package/dist/handlers/docs.js

@@ -0,0 +1,513 @@
+import fs from "fs/promises";
+import path from "path";
+import { validatePath } from "../utils/path.js";
+import matter from "gray-matter";
+/**
+ * Reads a markdown document and extracts its content and metadata
+ */
+export async function readDocument(docPath, allowedDirectories) {
+    try {
+        const normalizedPath = await validatePath(docPath, allowedDirectories);
+        // Read the file
+        const content = await fs.readFile(normalizedPath, "utf-8");
+        // Parse frontmatter
+        const { data: metadata, content: markdownContent } = matter(content);
+        return {
+            content: [{ type: "text", text: "Document read successfully" }],
+            metadata: {
+                path: docPath,
+                content: markdownContent,
+                metadata,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: "text", text: `Error reading document: ${error.message}` },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Lists all markdown documents in a directory
+ */
+export async function listDocuments(basePath, allowedDirectories) {
+    try {
+        const normalizedBasePath = basePath
+            ? await validatePath(basePath, allowedDirectories)
+            : allowedDirectories[0];
+        const documents = [];
+        async function processDirectory(dirPath) {
+            const entries = await fs.readdir(dirPath, { withFileTypes: true });
+            for (const entry of entries) {
+                const entryPath = path.join(dirPath, entry.name);
+                if (entry.isDirectory()) {
+                    await processDirectory(entryPath);
+                }
+                else if (entry.name.endsWith(".md")) {
+                    try {
+                        const content = await fs.readFile(entryPath, "utf-8");
+                        const { data: metadata } = matter(content);
+                        documents.push({
+                            path: entryPath,
+                            name: entry.name,
+                            metadata: metadata,
+                        });
+                    }
+                    catch (error) {
+                        console.error(`Error processing ${entryPath}: ${error.message}`);
+                    }
+                }
+            }
+        }
+        await processDirectory(normalizedBasePath);
+        return {
+            content: [{ type: "text", text: `Found ${documents.length} documents` }],
+            metadata: {
+                documents,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: "text", text: `Error listing documents: ${error.message}` },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Gets the structure of the documentation directory
+ */
+export async function getStructure(basePath, allowedDirectories) {
+    try {
+        const normalizedBasePath = basePath
+            ? await validatePath(basePath, allowedDirectories)
+            : allowedDirectories[0];
+        async function buildStructure(dirPath, relativePath = "") {
+            try {
+                const entries = await fs.readdir(dirPath, { withFileTypes: true });
+                const children = [];
+                let metadata;
+                // Check if there's an index.md file to get directory metadata
+                const indexPath = path.join(dirPath, "index.md");
+                try {
+                    const indexStat = await fs.stat(indexPath);
+                    if (indexStat.isFile()) {
+                        const content = await fs.readFile(indexPath, "utf-8");
+                        const { data } = matter(content);
+                        metadata = data;
+                    }
+                }
+                catch (error) {
+                    // No index.md file, that's fine
+                }
+                // Process all entries
+                for (const entry of entries) {
+                    const entryPath = path.join(dirPath, entry.name);
+                    const entryRelativePath = path.join(relativePath, entry.name);
+                    if (entry.isDirectory()) {
+                        const subDir = await buildStructure(entryPath, entryRelativePath);
+                        children.push(subDir);
+                    }
+                    else if (entry.name.endsWith(".md") && entry.name !== "index.md") {
+                        try {
+                            const content = await fs.readFile(entryPath, "utf-8");
+                            const { data } = matter(content);
+                            children.push({
+                                name: entry.name,
+                                path: entryRelativePath,
+                                type: "file",
+                                metadata: data,
+                                children: [],
+                            });
+                        }
+                        catch (error) {
+                            children.push({
+                                name: entry.name,
+                                path: entryRelativePath,
+                                type: "file",
+                                error: error.message,
+                                children: [],
+                            });
+                        }
+                    }
+                }
+                // Sort children by order metadata if available, then by name
+                children.sort((a, b) => {
+                    const orderA = a.metadata?.order ?? Infinity;
+                    const orderB = b.metadata?.order ?? Infinity;
+                    if (orderA !== orderB) {
+                        return orderA - orderB;
+                    }
+                    return a.name.localeCompare(b.name);
+                });
+                return {
+                    name: path.basename(dirPath),
+                    path: relativePath,
+                    type: "directory",
+                    metadata,
+                    children,
+                };
+            }
+            catch (error) {
+                return {
+                    name: path.basename(dirPath),
+                    path: relativePath,
+                    type: "directory",
+                    error: error.message,
+                    children: [],
+                };
+            }
+        }
+        const structure = await buildStructure(normalizedBasePath);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Documentation structure retrieved successfully",
+                },
+            ],
+            metadata: {
+                structure,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: "text", text: `Error getting structure: ${error.message}` },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Gets the navigation structure for the documentation
+ */
+export async function getNavigation(basePath, allowedDirectories) {
+    try {
+        const normalizedBasePath = basePath
+            ? await validatePath(basePath, allowedDirectories)
+            : allowedDirectories[0];
+        // First try to load navigation from .navigation file
+        const navigationFilePath = path.join(normalizedBasePath, ".navigation");
+        const navigationJsonPath = path.join(normalizedBasePath, "_navigation.json");
+        const navigationYmlPath = path.join(normalizedBasePath, "_navigation.yml");
+        let navigation = [];
+        // Try to load from .navigation file
+        try {
+            const navigationContent = await fs.readFile(navigationFilePath, "utf-8");
+            navigation = JSON.parse(navigationContent);
+            console.log("Loaded navigation from .navigation file");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Navigation structure loaded from .navigation file",
+                    },
+                ],
+                metadata: {
+                    navigation,
+                },
+            };
+        }
+        catch (error) {
+            console.log("No .navigation file found or error loading it:", error.message);
+        }
+        // Try to load from _navigation.json file
+        try {
+            const navigationContent = await fs.readFile(navigationJsonPath, "utf-8");
+            navigation = JSON.parse(navigationContent);
+            console.log("Loaded navigation from _navigation.json file");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Navigation structure loaded from _navigation.json file",
+                    },
+                ],
+                metadata: {
+                    navigation,
+                },
+            };
+        }
+        catch (error) {
+            console.log("No _navigation.json file found or error loading it:", error.message);
+        }
+        // If no navigation file found, build from structure
+        console.log("Building navigation from directory structure");
+        // Get the structure
+        const structureResponse = await getStructure(basePath, allowedDirectories);
+        if (structureResponse.isError) {
+            return structureResponse;
+        }
+        const structure = structureResponse.metadata?.structure;
+        // Build navigation from structure
+        function buildNavigation(structure) {
+            const sections = [];
+            function processNode(node, parentPath = []) {
+                // Skip nodes with errors
+                if (node.error) {
+                    return;
+                }
+                if (node.type === "directory") {
+                    // Create a section for this directory
+                    const section = {
+                        title: node.metadata?.title || node.name,
+                        path: node.path ? `/${node.path}` : null,
+                        items: [],
+                        order: node.metadata?.order ?? Infinity,
+                    };
+                    // Process children
+                    for (const child of node.children) {
+                        if (child.type === "file") {
+                            // Add file as an item
+                            section.items.push({
+                                title: child.metadata?.title || child.name.replace(/\.md$/, ""),
+                                path: `/${child.path}`,
+                                order: child.metadata?.order ?? Infinity,
+                            });
+                        }
+                        else if (child.type === "directory") {
+                            // Process subdirectory
+                            const childSections = processNode(child, [
+                                ...parentPath,
+                                node.name,
+                            ]);
+                            if (childSections) {
+                                sections.push(...childSections);
+                            }
+                        }
+                    }
+                    // Sort items by order
+                    section.items.sort((a, b) => {
+                        if (a.order !== b.order) {
+                            return a.order - b.order;
+                        }
+                        return a.title.localeCompare(b.title);
+                    });
+                    // Only add section if it has items
+                    if (section.items.length > 0) {
+                        sections.push(section);
+                    }
+                    return sections;
+                }
+                return null;
+            }
+            processNode(structure);
+            // Sort sections by order
+            sections.sort((a, b) => {
+                if (a.order !== b.order) {
+                    return a.order - b.order;
+                }
+                return a.title.localeCompare(b.title);
+            });
+            return sections;
+        }
+        navigation = buildNavigation(structure);
+        // Add debug logging
+        console.log("Navigation structure:", JSON.stringify(navigation, null, 2));
+        return {
+            content: [
+                { type: "text", text: "Navigation structure retrieved successfully" },
+            ],
+            metadata: {
+                navigation,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: "text", text: `Error getting navigation: ${error.message}` },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Checks the health of documentation
+ */
+export async function checkDocumentationHealth(basePath, options, allowedDirectories) {
+    try {
+        // Set default options
+        const checkLinks = options.checkLinks !== false;
+        const checkMetadata = options.checkMetadata !== false;
+        const checkOrphans = options.checkOrphans !== false;
+        const requiredMetadataFields = options.requiredMetadataFields || [
+            "title",
+            "description",
+            "status",
+        ];
+        // Use the first allowed directory if basePath is empty
+        const effectiveBasePath = basePath || allowedDirectories[0];
+        // Get all documents
+        const docsResult = await listDocuments(effectiveBasePath, allowedDirectories);
+        if (docsResult.isError) {
+            return docsResult;
+        }
+        const documents = docsResult.metadata?.documents || [];
+        // Get navigation if checking for orphans
+        let navigation = [];
+        if (checkOrphans) {
+            const navResult = await getNavigation(effectiveBasePath, allowedDirectories);
+            if (!navResult.isError && navResult.metadata?.navigation) {
+                navigation = navResult.metadata.navigation;
+            }
+        }
+        // Initialize health check result
+        const healthResult = {
+            score: 0,
+            totalDocuments: documents.length,
+            issues: [],
+            metadataCompleteness: 0,
+            brokenLinks: 0,
+            orphanedDocuments: 0,
+            missingReferences: 0,
+            documentsByStatus: {},
+            documentsByTag: {},
+        };
+        // Track documents by status and tags
+        documents.forEach((doc) => {
+            // Track by status
+            if (doc.metadata?.status) {
+                const status = doc.metadata.status;
+                healthResult.documentsByStatus[status] =
+                    (healthResult.documentsByStatus[status] || 0) + 1;
+            }
+            // Track by tags
+            if (doc.metadata?.tags && Array.isArray(doc.metadata.tags)) {
+                doc.metadata.tags.forEach((tag) => {
+                    healthResult.documentsByTag[tag] =
+                        (healthResult.documentsByTag[tag] || 0) + 1;
+                });
+            }
+        });
+        // Check metadata completeness
+        if (checkMetadata) {
+            let totalFields = 0;
+            let missingFields = 0;
+            for (const doc of documents) {
+                const metadata = doc.metadata || {};
+                for (const field of requiredMetadataFields) {
+                    totalFields++;
+                    if (!metadata[field]) {
+                        missingFields++;
+                        healthResult.issues.push({
+                            path: doc.path,
+                            type: "missing_metadata",
+                            severity: "error",
+                            message: `Missing required metadata field: ${field}`,
+                            details: { field },
+                        });
+                    }
+                }
+            }
+            // Calculate metadata completeness percentage
+            healthResult.metadataCompleteness =
+                totalFields > 0
+                    ? Math.round(((totalFields - missingFields) / totalFields) * 100)
+                    : 100;
+        }
+        // Check for orphaned documents (not in navigation)
+        if (checkOrphans) {
+            // Completely disable orphaned documents check
+            console.log("Orphaned documents check is disabled");
+            healthResult.orphanedDocuments = 0;
+            // Ensure we don't have any orphaned document issues in the result
+            healthResult.issues = healthResult.issues.filter((issue) => issue.type !== "orphaned");
+        }
+        // Check for broken links
+        if (checkLinks) {
+            // Create a set of all valid document paths
+            const validPaths = new Set();
+            for (const doc of documents) {
+                validPaths.add(doc.path);
+                // Also add without .md extension
+                validPaths.add(doc.path.replace(/\.md$/, ""));
+            }
+            // Check each document for links
+            for (const doc of documents) {
+                try {
+                    const content = await fs.readFile(doc.path, "utf-8");
+                    // Find markdown links [text](link)
+                    const linkRegex = /\[([^\]]+)\]\(([^)]+)\)/g;
+                    let match;
+                    while ((match = linkRegex.exec(content)) !== null) {
+                        const link = match[2];
+                        // Only check internal links (not external URLs)
+                        if (!link.startsWith("http://") && !link.startsWith("https://")) {
+                            // Resolve the link relative to the document
+                            const docDir = path.dirname(doc.path);
+                            const resolvedPath = path.resolve(docDir, link);
+                            // Check if the link target exists
+                            if (!validPaths.has(resolvedPath) &&
+                                !validPaths.has(resolvedPath + ".md")) {
+                                healthResult.brokenLinks++;
+                                healthResult.issues.push({
+                                    path: doc.path,
+                                    type: "broken_link",
+                                    severity: "error",
+                                    message: `Broken link: ${link}`,
+                                    details: { link, linkText: match[1] },
+                                });
+                            }
+                        }
+                    }
+                }
+                catch (error) {
+                    // Skip files that can't be read
+                    console.error(`Error reading file ${doc.path}:`, error);
+                }
+            }
+        }
+        // Calculate health score
+        // The score is based on:
+        // - Metadata completeness (70%)
+        // - No broken links (30%)
+        // - Orphaned documents check is disabled
+        const metadataScore = healthResult.metadataCompleteness * 0.7;
+        const brokenLinksScore = healthResult.brokenLinks === 0
+            ? 30
+            : Math.max(0, 30 - (healthResult.brokenLinks / healthResult.totalDocuments) * 100);
+        // Calculate the final score
+        healthResult.score = Math.round(metadataScore + brokenLinksScore);
+        // Create a clean result object to ensure proper JSON formatting
+        const finalResult = {
+            score: healthResult.score,
+            totalDocuments: healthResult.totalDocuments,
+            issues: healthResult.issues,
+            metadataCompleteness: healthResult.metadataCompleteness,
+            brokenLinks: healthResult.brokenLinks,
+            orphanedDocuments: 0,
+            missingReferences: healthResult.missingReferences,
+            documentsByStatus: healthResult.documentsByStatus,
+            documentsByTag: healthResult.documentsByTag,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Documentation health check completed. Overall health score: ${finalResult.score}%`,
+                },
+            ],
+            metadata: finalResult,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error checking documentation health: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=docs.js.map