mcp-docs-service 0.2.16 → 0.3.0

package/dist/index.js

@@ -1,632 +1,681 @@
 #!/usr/bin/env node
+/**
+ * MCP Docs Service
+ *
+ * A Model Context Protocol implementation for documentation management.
+ * This service provides tools for reading, writing, and managing markdown documentation.
+ */
 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 { CallToolRequestSchema, ListToolsRequestSchema, ToolSchema, } from "@modelcontextprotocol/sdk/types.js";
 import fs from "fs/promises";
 import path from "path";
+import os from "os";
+import { z } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
-import matter from "gray-matter";
-// Import utility functions
-import { normalizePath, expandHome, validatePath } from "./utils/path.js";
-// Import handlers
-import * as DocsHandlers from "./handlers/docs.js";
-// Import schemas
-import * as ToolSchemas from "./schemas/tools.js";
-
-// 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);
-};
-
+import { createTwoFilesPatch } from "diff";
+import { glob } from "glob";
 // Command line argument parsing
 const args = process.argv.slice(2);
-let allowedDirectories = [];
+let docsDir = path.join(process.cwd(), "docs");
+let createDir = false;
 let runHealthCheck = false;
-
-// Check for health check flag
-if (args.includes("--health-check")) {
-  runHealthCheck = true;
-  // Remove the health check flag from args
-  const healthCheckIndex = args.indexOf("--health-check");
-  args.splice(healthCheckIndex, 1);
-}
-
-// Filter out any other flags (starting with --)
-const directoryArgs = args.filter((arg) => !arg.startsWith("--"));
-if (directoryArgs.length === 0) {
-  // Use default docs directory if none is provided
-  const defaultDocsDir = path.join(process.cwd(), "docs");
-  try {
-    const stats = await fs.stat(defaultDocsDir);
-    if (stats.isDirectory()) {
-      log(`Using default docs directory: ${defaultDocsDir}`);
-      allowedDirectories = [normalizePath(path.resolve(defaultDocsDir))];
-    } else {
-      errorLog(
-        `Error: Default docs directory ${defaultDocsDir} is not a directory`
-      );
-      errorLog(
-        "Usage: mcp-server-filesystem <allowed-directory> [additional-directories...]"
-      );
-      process.exit(1);
+// Parse arguments
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--docs-dir" && i + 1 < args.length) {
+        docsDir = path.resolve(args[i + 1]);
+        i++;
     }
-  } catch (error) {
-    errorLog(
-      `Error: Default docs directory ${defaultDocsDir} does not exist or is not accessible`
-    );
-    errorLog(
-      "Usage: mcp-server-filesystem <allowed-directory> [additional-directories...]"
-    );
-    process.exit(1);
-  }
-} else {
-  // Store allowed directories in normalized form
-  allowedDirectories = directoryArgs.map((dir) =>
-    normalizePath(path.resolve(expandHome(dir)))
-  );
-  // Validate that all directories exist and are accessible
-  await Promise.all(
-    directoryArgs.map(async (dir) => {
-      try {
-        const stats = await fs.stat(dir);
-        if (!stats.isDirectory()) {
-          errorLog(`Error: ${dir} is not a directory`);
-          process.exit(1);
-        }
-      } catch (error) {
-        errorLog(`Error accessing directory ${dir}:`, error);
+    else if (args[i] === "--create-dir") {
+        createDir = true;
+    }
+    else if (args[i] === "--health-check") {
+        runHealthCheck = true;
+    }
+    else if (!args[i].startsWith("--")) {
+        docsDir = path.resolve(args[i]);
+    }
+}
+// Normalize path
+docsDir = path.normalize(docsDir);
+// Ensure docs directory exists
+try {
+    const stats = await fs.stat(docsDir);
+    if (!stats.isDirectory()) {
+        console.error(`Error: ${docsDir} is not a directory`);
         process.exit(1);
-      }
-    })
-  );
+    }
 }
+catch (error) {
+    // Create directory if it doesn't exist and --create-dir is specified
+    if (createDir) {
+        try {
+            await fs.mkdir(docsDir, { recursive: true });
+            console.log(`Created docs directory: ${docsDir}`);
+            // Create a sample README.md
+            const readmePath = path.join(docsDir, "README.md");
+            try {
+                await fs.access(readmePath);
+            }
+            catch {
+                const content = `---
+title: Documentation
+description: Project documentation
+---
 
-// Create server
-const server = new Server(
-  {
-    name: "secure-filesystem-server",
-    version: "1.0.0",
-  },
-  {
-    capabilities: {
-      tools: {},
-    },
-  }
-);
-// Define tools
-// ===================================================================
-// DOCUMENTATION TOOLS
-// ===================================================================
-// These tools are specifically designed for working with documentation
-// files (markdown with frontmatter)
-const documentationTools = [
-  // Read document - reads a markdown document and extracts its content and metadata
-  {
-    name: "read_document",
-    description:
-      "Read a markdown document and extract its content and metadata",
-    schema: ToolSchemas.ReadDocumentSchema,
-    handler: async (args) => {
-      return await DocsHandlers.readDocument(args.path, allowedDirectories);
-    },
-  },
-  // List documents - lists all markdown documents in a directory
-  {
-    name: "list_documents",
-    description: "List all markdown documents in a directory",
-    schema: ToolSchemas.ListDocumentsSchema,
-    handler: async (args) => {
-      return await DocsHandlers.listDocuments(
-        args.basePath || "",
-        allowedDirectories
-      );
-    },
-  },
-  // Get structure - gets the structure of the documentation directory
-  {
-    name: "get_structure",
-    description: "Get the structure of the documentation directory",
-    schema: ToolSchemas.GetStructureSchema,
-    handler: async (args) => {
-      return await DocsHandlers.getStructure(
-        args.basePath || "",
-        allowedDirectories
-      );
-    },
-  },
-  // Get navigation - gets the navigation structure for the documentation
-  {
-    name: "get_navigation",
-    description: "Get the navigation structure for the documentation",
-    schema: ToolSchemas.GetNavigationSchema,
-    handler: async (args) => {
-      return await DocsHandlers.getNavigation(
-        args.basePath || "",
-        allowedDirectories
-      );
-    },
-  },
-  // Get docs knowledge base - creates a comprehensive knowledge base of documentation
-  {
-    name: "get_docs_knowledge_base",
-    description:
-      "Create a comprehensive knowledge base of documentation for LLM context",
-    schema: ToolSchemas.GetDocsKnowledgeBaseSchema,
-    handler: async (args) => {
-      try {
-        // First get the navigation structure
-        const navResult = await DocsHandlers.getNavigation(
-          args.basePath || "",
-          allowedDirectories
-        );
-        if (navResult.isError) {
-          return navResult;
+# Documentation
+
+This is the documentation directory for your project.
+`;
+                await fs.writeFile(readmePath, content);
+                console.log(`Created sample README.md in ${docsDir}`);
+            }
         }
-        // Get all documents
-        const docsResult = await DocsHandlers.listDocuments(
-          args.basePath || "",
-          allowedDirectories
-        );
-        if (docsResult.isError) {
-          return docsResult;
+        catch (error) {
+            console.error(`Error creating docs directory: ${error}`);
+            process.exit(1);
         }
-        const documents = docsResult.metadata?.documents || [];
-        const navigation = navResult.metadata?.navigation || [];
-        // Create a map of path to document for quick lookup
-        const documentMap = new Map();
-        documents.forEach((doc) => {
-          documentMap.set(doc.path, doc);
-        });
-        // Create knowledge base structure
-        const knowledgeBase = {
-          navigation,
-          documents: [],
-          categories: {},
-          tags: {},
-        };
-        // Process documents to extract summaries if requested
-        const includeSummaries = args.includeSummaries !== false; // Default to true
-        const maxSummaryLength = args.maxSummaryLength || 500;
-        // Process all documents
-        for (const doc of documents) {
-          // Create document entry with metadata
-          const docEntry = {
-            path: doc.path,
-            name: doc.name,
-            metadata: doc.metadata || {},
-          };
-          // Add summary if requested
-          if (includeSummaries) {
-            try {
-              const docContent = await DocsHandlers.readDocument(
-                doc.path,
-                allowedDirectories
-              );
-              if (!docContent.isError && docContent.metadata?.content) {
-                // Extract a summary (first few paragraphs)
-                const content = docContent.metadata.content;
-                const paragraphs = content.split("\n\n");
-                let summary = "";
-                // Get first few paragraphs up to maxSummaryLength
-                for (const para of paragraphs) {
-                  if (summary.length + para.length <= maxSummaryLength) {
-                    summary += para + "\n\n";
-                  } else {
-                    // Add partial paragraph to reach maxSummaryLength
-                    const remainingLength = maxSummaryLength - summary.length;
-                    if (remainingLength > 0) {
-                      summary += para.substring(0, remainingLength) + "...";
+    }
+    else {
+        console.error(`Error: Docs directory does not exist: ${docsDir}`);
+        console.error(`Use --create-dir to create it automatically`);
+        process.exit(1);
+    }
+}
+console.log("MCP Documentation Service initialized with docs directory:", docsDir);
+console.log("Directory will be created if it doesn't exist");
+// Schema definitions
+const ReadDocumentArgsSchema = z.object({
+    path: z
+        .string()
+        .describe("Path to the markdown document, relative to docs directory"),
+});
+const WriteDocumentArgsSchema = z.object({
+    path: z
+        .string()
+        .describe("Path to the markdown document, relative to docs directory"),
+    content: z
+        .string()
+        .describe("Content of the document, including frontmatter"),
+    createDirectories: z
+        .boolean()
+        .default(true)
+        .describe("Create parent directories if they don't exist"),
+});
+const EditDocumentArgsSchema = z.object({
+    path: z
+        .string()
+        .describe("Path to the markdown document, relative to docs directory"),
+    edits: z.array(z.object({
+        oldText: z.string().describe("Text to search for - must match exactly"),
+        newText: z.string().describe("Text to replace with"),
+    })),
+    dryRun: z
+        .boolean()
+        .default(false)
+        .describe("Preview changes using git-style diff format"),
+});
+const ListDocumentsArgsSchema = z.object({
+    basePath: z
+        .string()
+        .optional()
+        .default("")
+        .describe("Base path within docs directory to list documents from"),
+    recursive: z.boolean().default(false).describe("List documents recursively"),
+});
+const SearchDocumentsArgsSchema = z.object({
+    query: z
+        .string()
+        .describe("Search query to find in document content or metadata"),
+    basePath: z
+        .string()
+        .optional()
+        .default("")
+        .describe("Base path within docs directory to search documents from"),
+});
+const GenerateNavigationArgsSchema = z.object({
+    basePath: z
+        .string()
+        .optional()
+        .default("")
+        .describe("Base path within docs directory to generate navigation from"),
+    outputPath: z
+        .string()
+        .optional()
+        .default("navigation.json")
+        .describe("Path to output navigation file"),
+});
+const CheckDocumentationHealthArgsSchema = z.object({
+    basePath: z
+        .string()
+        .optional()
+        .default("")
+        .describe("Base path within docs directory to check health of"),
+});
+const ToolInputSchema = ToolSchema.shape.inputSchema;
+// Utility functions
+function normalizePath(p) {
+    return path.normalize(p);
+}
+function expandHome(filepath) {
+    if (filepath.startsWith("~/") || filepath === "~") {
+        return path.join(os.homedir(), filepath.slice(1));
+    }
+    return filepath;
+}
+async function validatePath(requestedPath) {
+    // Resolve path relative to docs directory
+    const resolvedPath = path.isAbsolute(requestedPath)
+        ? requestedPath
+        : path.join(docsDir, requestedPath);
+    const normalizedPath = normalizePath(resolvedPath);
+    // Check if path is within docs directory
+    if (!normalizedPath.startsWith(docsDir)) {
+        throw new Error(`Access denied - path outside docs directory: ${normalizedPath}`);
+    }
+    return normalizedPath;
+}
+// File editing and diffing utilities
+function normalizeLineEndings(text) {
+    return text.replace(/\r\n/g, "\n");
+}
+function createUnifiedDiff(originalContent, newContent, filepath = "file") {
+    // Ensure consistent line endings for diff
+    const normalizedOriginal = normalizeLineEndings(originalContent);
+    const normalizedNew = normalizeLineEndings(newContent);
+    return createTwoFilesPatch(filepath, filepath, normalizedOriginal, normalizedNew, "original", "modified");
+}
+async function applyDocumentEdits(filePath, edits, dryRun = false) {
+    // Read file content and normalize line endings
+    const content = normalizeLineEndings(await fs.readFile(filePath, "utf-8"));
+    // Apply edits sequentially
+    let modifiedContent = content;
+    for (const edit of edits) {
+        const normalizedOld = normalizeLineEndings(edit.oldText);
+        const normalizedNew = normalizeLineEndings(edit.newText);
+        // If exact match exists, use it
+        if (modifiedContent.includes(normalizedOld)) {
+            modifiedContent = modifiedContent.replace(normalizedOld, normalizedNew);
+            continue;
+        }
+        // Otherwise, try line-by-line matching with flexibility for whitespace
+        const oldLines = normalizedOld.split("\n");
+        const contentLines = modifiedContent.split("\n");
+        let matchFound = false;
+        for (let i = 0; i <= contentLines.length - oldLines.length; i++) {
+            const potentialMatch = contentLines.slice(i, i + oldLines.length);
+            // Compare lines with normalized whitespace
+            const isMatch = oldLines.every((oldLine, j) => {
+                const contentLine = potentialMatch[j];
+                return oldLine.trim() === contentLine.trim();
+            });
+            if (isMatch) {
+                // Preserve original indentation of first line
+                const originalIndent = contentLines[i].match(/^\s*/)?.[0] || "";
+                const newLines = normalizedNew.split("\n").map((line, j) => {
+                    if (j === 0)
+                        return originalIndent + line.trimStart();
+                    // For subsequent lines, try to preserve relative indentation
+                    const oldIndent = oldLines[j]?.match(/^\s*/)?.[0] || "";
+                    const newIndent = line.match(/^\s*/)?.[0] || "";
+                    if (oldIndent && newIndent) {
+                        const relativeIndent = newIndent.length - oldIndent.length;
+                        return (originalIndent +
+                            " ".repeat(Math.max(0, relativeIndent)) +
+                            line.trimStart());
                     }
-                    break;
-                  }
-                }
-                docEntry.summary = summary.trim();
-              }
-            } catch (error) {
-              // Skip summary if there's an error
-              docEntry.summary = "Error generating summary";
+                    return line;
+                });
+                contentLines.splice(i, oldLines.length, ...newLines);
+                modifiedContent = contentLines.join("\n");
+                matchFound = true;
+                break;
+            }
+        }
+        if (!matchFound) {
+            throw new Error(`Could not find exact match for edit:\n${edit.oldText}`);
+        }
+    }
+    // Create unified diff
+    const diff = createUnifiedDiff(content, modifiedContent, filePath);
+    // Format diff with appropriate number of backticks
+    let numBackticks = 3;
+    while (diff.includes("`".repeat(numBackticks))) {
+        numBackticks++;
+    }
+    const formattedDiff = `${"`".repeat(numBackticks)}diff\n${diff}${"`".repeat(numBackticks)}\n\n`;
+    if (!dryRun) {
+        await fs.writeFile(filePath, modifiedContent, "utf-8");
+    }
+    return formattedDiff;
+}
+// Parse frontmatter from markdown content
+function parseFrontmatter(content) {
+    const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+    const match = content.match(frontmatterRegex);
+    if (!match) {
+        return { frontmatter: {}, content };
+    }
+    const frontmatterStr = match[1];
+    const contentWithoutFrontmatter = content.slice(match[0].length);
+    // Parse frontmatter as key-value pairs
+    const frontmatter = {};
+    const lines = frontmatterStr.split("\n");
+    for (const line of lines) {
+        const colonIndex = line.indexOf(":");
+        if (colonIndex !== -1) {
+            const key = line.slice(0, colonIndex).trim();
+            let value = line.slice(colonIndex + 1).trim();
+            // Handle quoted values
+            if (value.startsWith('"') && value.endsWith('"')) {
+                value = value.slice(1, -1);
             }
-          }
-          // Add to knowledge base
-          knowledgeBase.documents.push(docEntry);
-          // Organize by categories (based on directory structure)
-          const dirPath = path.dirname(doc.path);
-          if (!knowledgeBase.categories[dirPath]) {
-            knowledgeBase.categories[dirPath] = [];
-          }
-          knowledgeBase.categories[dirPath].push(docEntry);
-          // Organize by tags
-          if (doc.metadata?.tags) {
-            for (const tag of doc.metadata.tags) {
-              if (!knowledgeBase.tags[tag]) {
-                knowledgeBase.tags[tag] = [];
-              }
-              knowledgeBase.tags[tag].push(docEntry);
+            // Handle arrays
+            if (value.startsWith("[") && value.endsWith("]")) {
+                try {
+                    value = JSON.parse(value);
+                }
+                catch {
+                    // Keep as string if parsing fails
+                }
             }
-          }
+            frontmatter[key] = value;
         }
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Generated knowledge base with ${knowledgeBase.documents.length} documents`,
-            },
-          ],
-          metadata: {
-            knowledgeBase,
-          },
-        };
-      } catch (error) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error generating knowledge base: ${error.message}`,
-            },
-          ],
-          isError: true,
-        };
-      }
-    },
-  },
-  // Write document - writes content to a markdown document with frontmatter
-  {
-    name: "write_document",
-    description: "Write content to a markdown document with frontmatter",
-    schema: ToolSchemas.WriteDocumentSchema,
-    handler: async (args) => {
-      try {
-        const normalizedPath = await validatePath(
-          args.path,
-          allowedDirectories
-        );
-        // Convert metadata to frontmatter and combine with content
-        const frontmatter = args.metadata
-          ? matter.stringify(args.content, args.metadata)
-          : args.content;
-        // Ensure the directory exists
-        const dirPath = path.dirname(normalizedPath);
-        await fs.mkdir(dirPath, { recursive: true });
-        // Write the file
-        await fs.writeFile(normalizedPath, frontmatter);
-        return {
-          content: [{ type: "text", text: "Document written successfully" }],
-          metadata: {
-            path: args.path,
-          },
-        };
-      } catch (error) {
-        return {
-          content: [
-            { type: "text", text: `Error writing document: ${error.message}` },
-          ],
-          isError: true,
+    }
+    return { frontmatter, content: contentWithoutFrontmatter };
+}
+// Generate navigation structure from documents
+async function generateNavigation(basePath) {
+    const baseDir = path.join(docsDir, basePath);
+    const pattern = path.join(baseDir, "**/*.md");
+    const files = await glob(pattern);
+    // Sort files to ensure consistent order and process index.md files first
+    files.sort((a, b) => {
+        const aIsIndex = path.basename(a) === "index.md";
+        const bIsIndex = path.basename(b) === "index.md";
+        if (aIsIndex && !bIsIndex)
+            return -1;
+        if (!aIsIndex && bIsIndex)
+            return 1;
+        return a.localeCompare(b);
+    });
+    const navigation = [];
+    const directoryMap = {};
+    for (const file of files) {
+        const relativePath = path.relative(docsDir, file);
+        const content = await fs.readFile(file, "utf-8");
+        const { frontmatter } = parseFrontmatter(content);
+        const title = frontmatter.title || path.basename(file, ".md");
+        const order = frontmatter.order !== undefined ? Number(frontmatter.order) : 999;
+        const item = {
+            title,
+            path: relativePath,
+            order,
+            children: [],
         };
-      }
-    },
-  },
-  // Edit document - applies edits to a markdown document while preserving frontmatter
-  {
-    name: "edit_document",
-    description:
-      "Apply edits to a markdown document while preserving frontmatter",
-    schema: ToolSchemas.EditDocumentSchema,
-    handler: async (args) => {
-      try {
-        // First read the document to get its current content and metadata
-        const docResult = await DocsHandlers.readDocument(
-          args.path,
-          allowedDirectories
-        );
-        if (docResult.isError) {
-          return docResult;
+        const dirPath = path.dirname(relativePath);
+        if (dirPath === "." || dirPath === basePath) {
+            navigation.push(item);
         }
-        const normalizedPath = await validatePath(
-          args.path,
-          allowedDirectories
-        );
-        // Read the current content
-        const content = await fs.readFile(normalizedPath, "utf-8");
-        // Apply edits
-        let newContent = content;
-        let appliedEdits = 0;
-        for (const edit of args.edits) {
-          if (newContent.includes(edit.oldText)) {
-            newContent = newContent.replace(edit.oldText, edit.newText);
-            appliedEdits++;
-          }
+        else {
+            // Create parent directories if they don't exist in the navigation
+            const pathParts = dirPath.split(path.sep);
+            let currentPath = "";
+            let currentNavigation = navigation;
+            for (const part of pathParts) {
+                currentPath = currentPath ? path.join(currentPath, part) : part;
+                if (!directoryMap[currentPath]) {
+                    const dirItem = {
+                        title: part,
+                        path: currentPath,
+                        order: 0,
+                        children: [],
+                    };
+                    directoryMap[currentPath] = dirItem;
+                    currentNavigation.push(dirItem);
+                }
+                currentNavigation = directoryMap[currentPath].children;
+            }
+            currentNavigation.push(item);
         }
-        // Write the updated content
-        await fs.writeFile(normalizedPath, newContent);
-        return {
-          content: [{ type: "text", text: "Document edited successfully" }],
-          metadata: {
-            path: args.path,
-            appliedEdits,
-          },
-        };
-      } catch (error) {
-        return {
-          content: [
-            { type: "text", text: `Error editing document: ${error.message}` },
-          ],
-          isError: true,
-        };
-      }
-    },
-  },
-  // Delete document - deletes a markdown document
-  {
-    name: "delete_document",
-    description: "Delete a markdown document",
-    schema: ToolSchemas.DeleteDocumentSchema,
-    handler: async (args) => {
-      try {
-        const normalizedPath = await validatePath(
-          args.path,
-          allowedDirectories
-        );
-        // Check if the file exists and is a markdown file
-        const stats = await fs.stat(normalizedPath);
-        if (!stats.isFile() || !normalizedPath.endsWith(".md")) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `Error: ${args.path} is not a markdown document`,
-              },
-            ],
-            isError: true,
-          };
+    }
+    // Sort navigation items by order
+    function sortNavigation(items) {
+        items.sort((a, b) => a.order - b.order);
+        for (const item of items) {
+            if (item.children && item.children.length > 0) {
+                sortNavigation(item.children);
+            }
         }
-        // Delete the file
-        await fs.unlink(normalizedPath);
-        return {
-          content: [{ type: "text", text: "Document deleted successfully" }],
-          metadata: {
-            path: args.path,
-          },
-        };
-      } catch (error) {
-        return {
-          content: [
-            { type: "text", text: `Error deleting document: ${error.message}` },
-          ],
-          isError: true,
-        };
-      }
-    },
-  },
-  // Search documents - searches for markdown documents matching criteria
-  {
-    name: "search_documents",
-    description: "Search for markdown documents matching criteria",
-    schema: ToolSchemas.SearchDocumentsSchema,
-    handler: async (args) => {
-      try {
-        // Get the list of documents first
-        const listResult = await DocsHandlers.listDocuments(
-          args.basePath || "",
-          allowedDirectories
-        );
-        if (listResult.isError) {
-          return listResult;
+    }
+    sortNavigation(navigation);
+    return navigation;
+}
+// Check documentation health
+async function checkDocumentationHealth(basePath) {
+    const baseDir = path.join(docsDir, basePath);
+    const pattern = path.join(baseDir, "**/*.md");
+    const files = await glob(pattern);
+    const results = {
+        totalDocuments: files.length,
+        documentsWithMissingFrontmatter: 0,
+        documentsWithMissingTitle: 0,
+        documentsWithMissingDescription: 0,
+        brokenLinks: 0,
+        orphanedDocuments: 0,
+        issues: [],
+    };
+    // Check frontmatter and content
+    for (const file of files) {
+        const relativePath = path.relative(docsDir, file);
+        const content = await fs.readFile(file, "utf-8");
+        const { frontmatter } = parseFrontmatter(content);
+        if (Object.keys(frontmatter).length === 0) {
+            results.documentsWithMissingFrontmatter++;
+            results.issues.push(`${relativePath}: Missing frontmatter`);
+        }
+        if (!frontmatter.title) {
+            results.documentsWithMissingTitle++;
+            results.issues.push(`${relativePath}: Missing title in frontmatter`);
+        }
+        if (!frontmatter.description) {
+            results.documentsWithMissingDescription++;
+            results.issues.push(`${relativePath}: Missing description in frontmatter`);
         }
-        let documents = listResult.metadata?.documents || [];
-        // Filter by query if provided
-        if (args.query) {
-          documents = documents.filter((doc) => {
-            // Check if query matches document path, name, or metadata
-            const docString = JSON.stringify(doc).toLowerCase();
-            return docString.includes(args.query.toLowerCase());
-          });
+        // Check for internal links
+        const linkRegex = /\[.*?\]\((.*?)\)/g;
+        let match;
+        while ((match = linkRegex.exec(content)) !== null) {
+            const link = match[1];
+            // Only check relative links to markdown files
+            if (!link.startsWith("http") &&
+                !link.startsWith("#") &&
+                link.endsWith(".md")) {
+                const linkPath = path.join(path.dirname(file), link);
+                try {
+                    await fs.access(linkPath);
+                }
+                catch {
+                    results.brokenLinks++;
+                    results.issues.push(`${relativePath}: Broken link to ${link}`);
+                }
+            }
         }
-        // Filter by tags if provided
-        if (args.tags && args.tags.length > 0) {
-          documents = documents.filter((doc) => {
-            const docTags = doc.metadata?.tags || [];
-            return args.tags.some((tag) => docTags.includes(tag));
-          });
+    }
+    // Generate navigation to check for orphaned documents
+    const navigation = await generateNavigation(basePath);
+    function collectPaths(items) {
+        let paths = [];
+        for (const item of items) {
+            paths.push(item.path);
+            if (item.children && item.children.length > 0) {
+                paths = paths.concat(collectPaths(item.children));
+            }
         }
-        // Filter by status if provided
-        if (args.status) {
-          documents = documents.filter(
-            (doc) => doc.metadata?.status === args.status
-          );
+        return paths;
+    }
+    const navigationPaths = collectPaths(navigation);
+    for (const file of files) {
+        const relativePath = path.relative(docsDir, file);
+        if (!navigationPaths.includes(relativePath)) {
+            results.orphanedDocuments++;
+            results.issues.push(`${relativePath}: Orphaned document (not in navigation)`);
         }
-        return {
-          content: [
+    }
+    // Calculate health score (0-100)
+    const totalIssues = results.documentsWithMissingFrontmatter +
+        results.documentsWithMissingTitle +
+        results.documentsWithMissingDescription +
+        results.brokenLinks +
+        results.orphanedDocuments;
+    const maxIssues = results.totalDocuments * 5; // 5 possible issues per document
+    const healthScore = Math.max(0, 100 - Math.round((totalIssues / maxIssues) * 100));
+    return {
+        ...results,
+        healthScore,
+    };
+}
+// Server setup
+const server = new Server({
+    name: "mcp-docs-service",
+    version: "0.3.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Tool handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
             {
-              type: "text",
-              text: `Found ${documents.length} matching documents`,
+                name: "read_document",
+                description: "Read a markdown document from the docs directory. Returns the document content " +
+                    "including frontmatter. Use this tool when you need to examine the contents of a " +
+                    "single document.",
+                inputSchema: zodToJsonSchema(ReadDocumentArgsSchema),
             },
-          ],
-          metadata: {
-            documents,
-          },
-        };
-      } catch (error) {
-        return {
-          content: [
             {
-              type: "text",
-              text: `Error searching documents: ${error.message}`,
+                name: "write_document",
+                description: "Create a new markdown document or completely overwrite an existing document with new content. " +
+                    "Use with caution as it will overwrite existing documents without warning. " +
+                    "Can create parent directories if they don't exist.",
+                inputSchema: zodToJsonSchema(WriteDocumentArgsSchema),
             },
-          ],
-          isError: true,
-        };
-      }
-    },
-  },
-  // Check documentation health - checks the health of documentation
-  {
-    name: "check_documentation_health",
-    description: "Check the health of documentation and identify issues",
-    schema: ToolSchemas.CheckDocumentationHealthSchema,
-    handler: async (args) => {
-      try {
-        // If basePath is provided, validate it
-        let validatedBasePath = "";
-        if (args.basePath) {
-          try {
-            validatedBasePath = await validatePath(
-              args.basePath,
-              allowedDirectories
-            );
-          } catch (error) {
-            // If validation fails, use the first allowed directory
-            console.warn(
-              `Warning: Invalid basePath "${args.basePath}". Using default directory instead.`
-            );
-            validatedBasePath = allowedDirectories[0];
-          }
-        }
-        return await DocsHandlers.checkDocumentationHealth(
-          validatedBasePath,
-          {
-            checkLinks: args.checkLinks,
-            checkMetadata: args.checkMetadata,
-            checkOrphans: args.checkOrphans,
-            requiredMetadataFields: args.requiredMetadataFields,
-          },
-          allowedDirectories
-        );
-      } catch (error) {
-        return {
-          content: [
             {
-              type: "text",
-              text: `Error checking documentation health: ${error.message}`,
+                name: "edit_document",
+                description: "Make line-based edits to a markdown document. Each edit replaces exact line sequences " +
+                    "with new content. Returns a git-style diff showing the changes made.",
+                inputSchema: zodToJsonSchema(EditDocumentArgsSchema),
             },
-          ],
-          isError: true,
-        };
-      }
-    },
-  },
-];
-// Combine all tools
-const tools = [...documentationTools];
-// Register tool handlers
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return {
-    tools: tools.map((tool) => ({
-      name: tool.name,
-      description: tool.description,
-      inputSchema: zodToJsonSchema(tool.schema),
-    })),
-  };
+            {
+                name: "list_documents",
+                description: "List all markdown documents in the docs directory or a subdirectory. " +
+                    "Returns the relative paths to all documents.",
+                inputSchema: zodToJsonSchema(ListDocumentsArgsSchema),
+            },
+            {
+                name: "search_documents",
+                description: "Search for markdown documents containing specific text in their content or frontmatter. " +
+                    "Returns the relative paths to matching documents.",
+                inputSchema: zodToJsonSchema(SearchDocumentsArgsSchema),
+            },
+            {
+                name: "generate_navigation",
+                description: "Generate a navigation structure from the markdown documents in the docs directory. " +
+                    "Returns a JSON structure that can be used for navigation menus.",
+                inputSchema: zodToJsonSchema(GenerateNavigationArgsSchema),
+            },
+            {
+                name: "check_documentation_health",
+                description: "Check the health of the documentation by analyzing frontmatter, links, and navigation. " +
+                    "Returns a report with issues and a health score.",
+                inputSchema: zodToJsonSchema(CheckDocumentationHealthArgsSchema),
+            },
+        ],
+    };
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-  // Find the requested tool
-  const tool = tools.find((t) => t.name === name);
-  if (!tool) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Tool not found: ${name}`,
-        },
-      ],
-      isError: true,
-    };
-  }
-  try {
-    // Parse and validate arguments
-    const parsedArgs = tool.schema.parse(args);
-    // Call the tool handler with the appropriate type
-    const result = await tool.handler(parsedArgs);
-    // Ensure the content field is always an array
-    if (!result.content || !Array.isArray(result.content)) {
-      result.content = [
-        { type: "text", text: "Operation completed successfully" },
-      ];
+    try {
+        const { name, arguments: args } = request.params;
+        switch (name) {
+            case "read_document": {
+                const parsed = ReadDocumentArgsSchema.safeParse(args);
+                if (!parsed.success) {
+                    throw new Error(`Invalid arguments for read_document: ${parsed.error}`);
+                }
+                const validPath = await validatePath(parsed.data.path);
+                const content = await fs.readFile(validPath, "utf-8");
+                return {
+                    content: [{ type: "text", text: content }],
+                    metadata: {
+                        path: parsed.data.path,
+                        ...parseFrontmatter(content).frontmatter,
+                    },
+                };
+            }
+            case "write_document": {
+                const parsed = WriteDocumentArgsSchema.safeParse(args);
+                if (!parsed.success) {
+                    throw new Error(`Invalid arguments for write_document: ${parsed.error}`);
+                }
+                const validPath = await validatePath(parsed.data.path);
+                // Create parent directories if needed
+                if (parsed.data.createDirectories) {
+                    const dirPath = path.dirname(validPath);
+                    await fs.mkdir(dirPath, { recursive: true });
+                }
+                await fs.writeFile(validPath, parsed.data.content, "utf-8");
+                return {
+                    content: [
+                        { type: "text", text: `Successfully wrote to ${parsed.data.path}` },
+                    ],
+                };
+            }
+            case "edit_document": {
+                const parsed = EditDocumentArgsSchema.safeParse(args);
+                if (!parsed.success) {
+                    throw new Error(`Invalid arguments for edit_document: ${parsed.error}`);
+                }
+                const validPath = await validatePath(parsed.data.path);
+                const result = await applyDocumentEdits(validPath, parsed.data.edits, parsed.data.dryRun);
+                return {
+                    content: [{ type: "text", text: result }],
+                };
+            }
+            case "list_documents": {
+                const parsed = ListDocumentsArgsSchema.safeParse(args);
+                if (!parsed.success) {
+                    throw new Error(`Invalid arguments for list_documents: ${parsed.error}`);
+                }
+                const baseDir = path.join(docsDir, parsed.data.basePath);
+                const pattern = parsed.data.recursive
+                    ? path.join(baseDir, "**/*.md")
+                    : path.join(baseDir, "*.md");
+                const files = await glob(pattern);
+                const relativePaths = files.map((file) => path.relative(docsDir, file));
+                return {
+                    content: [{ type: "text", text: relativePaths.join("\n") }],
+                };
+            }
+            case "search_documents": {
+                const parsed = SearchDocumentsArgsSchema.safeParse(args);
+                if (!parsed.success) {
+                    throw new Error(`Invalid arguments for search_documents: ${parsed.error}`);
+                }
+                const baseDir = path.join(docsDir, parsed.data.basePath);
+                const pattern = path.join(baseDir, "**/*.md");
+                const files = await glob(pattern);
+                const results = [];
+                for (const file of files) {
+                    const content = await fs.readFile(file, "utf-8");
+                    if (content.toLowerCase().includes(parsed.data.query.toLowerCase())) {
+                        results.push(path.relative(docsDir, file));
+                    }
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: results.length > 0
+                                ? `Found ${results.length} matching documents:\n${results.join("\n")}`
+                                : "No matching documents found",
+                        },
+                    ],
+                };
+            }
+            case "generate_navigation": {
+                const parsed = GenerateNavigationArgsSchema.safeParse(args);
+                if (!parsed.success) {
+                    throw new Error(`Invalid arguments for generate_navigation: ${parsed.error}`);
+                }
+                const navigation = await generateNavigation(parsed.data.basePath);
+                // Write navigation to file if outputPath is provided
+                if (parsed.data.outputPath) {
+                    const outputPath = await validatePath(parsed.data.outputPath);
+                    await fs.writeFile(outputPath, JSON.stringify(navigation, null, 2), "utf-8");
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Navigation structure:\n${JSON.stringify(navigation, null, 2)}`,
+                        },
+                    ],
+                };
+            }
+            case "check_documentation_health": {
+                const parsed = CheckDocumentationHealthArgsSchema.safeParse(args);
+                if (!parsed.success) {
+                    throw new Error(`Invalid arguments for check_documentation_health: ${parsed.error}`);
+                }
+                const healthReport = await checkDocumentationHealth(parsed.data.basePath);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Documentation Health Report:
+Health Score: ${healthReport.healthScore}/100
+
+Summary:
+- Total Documents: ${healthReport.totalDocuments}
+- Documents with Missing Frontmatter: ${healthReport.documentsWithMissingFrontmatter}
+- Documents with Missing Title: ${healthReport.documentsWithMissingTitle}
+- Documents with Missing Description: ${healthReport.documentsWithMissingDescription}
+- Broken Links: ${healthReport.brokenLinks}
+- Orphaned Documents: ${healthReport.orphanedDocuments}
+
+Issues:
+${healthReport.issues.map((issue) => `- ${issue}`).join("\n")}
+`,
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${errorMessage}` }],
+            isError: true,
+        };
     }
-    return result;
-  } catch (error) {
-    console.error(`Error executing tool ${name}:`, error);
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Error calling tool ${name}: ${error.message}`,
-        },
-      ],
-      isError: true,
-    };
-  }
 });
-// If health check flag is set, run the health check and exit
+// Run health check if requested
 if (runHealthCheck) {
-  console.log("Running documentation health check...");
-  try {
-    const healthCheckResult = await DocsHandlers.checkDocumentationHealth(
-      "", // Use the first allowed directory
-      {
-        checkLinks: true,
-        checkMetadata: true,
-        checkOrphans: true,
-        requiredMetadataFields: ["title", "description", "status"],
-      },
-      allowedDirectories
-    );
-    if (healthCheckResult.isError) {
-      console.error("Health check failed:", healthCheckResult.content[0].text);
-      process.exit(1);
+    try {
+        const healthReport = await checkDocumentationHealth("");
+        console.log(`Documentation Health Report:`);
+        console.log(`Health Score: ${healthReport.healthScore}/100`);
+        console.log(`\nSummary:`);
+        console.log(`- Total Documents: ${healthReport.totalDocuments}`);
+        console.log(`- Documents with Missing Frontmatter: ${healthReport.documentsWithMissingFrontmatter}`);
+        console.log(`- Documents with Missing Title: ${healthReport.documentsWithMissingTitle}`);
+        console.log(`- Documents with Missing Description: ${healthReport.documentsWithMissingDescription}`);
+        console.log(`- Broken Links: ${healthReport.brokenLinks}`);
+        console.log(`- Orphaned Documents: ${healthReport.orphanedDocuments}`);
+        console.log(`\nIssues:`);
+        healthReport.issues.forEach((issue) => console.log(`- ${issue}`));
+        process.exit(0);
     }
-    const metadata = healthCheckResult.metadata || {};
-    console.log("\n=== DOCUMENTATION HEALTH CHECK RESULTS ===\n");
-    console.log(`Overall Health Score: ${metadata.score || 0}%`);
-    console.log(`Total Documents: ${metadata.totalDocuments || 0}`);
-    console.log(
-      `Metadata Completeness: ${metadata.metadataCompleteness || 0}%`
-    );
-    console.log(`Broken Links: ${metadata.brokenLinks || 0}`);
-    if (metadata.issues && metadata.issues.length > 0) {
-      console.log("\nIssues Found:");
-      // Group issues by type
-      const issuesByType = {};
-      metadata.issues.forEach((issue) => {
-        if (!issuesByType[issue.type]) {
-          issuesByType[issue.type] = [];
-        }
-        issuesByType[issue.type].push(issue);
-      });
-      // Display issues by type
-      for (const [type, issues] of Object.entries(issuesByType)) {
-        console.log(
-          `\n${type.replace("_", " ").toUpperCase()} (${issues.length}):`
-        );
-        issues.forEach((issue) => {
-          console.log(`- ${issue.path}: ${issue.message}`);
-        });
-      }
-    } else {
-      console.log("\nNo issues found. Documentation is in good health!");
+    catch (error) {
+        console.error(`Error running health check: ${error}`);
+        process.exit(1);
     }
-    console.log("\n=== END OF HEALTH CHECK ===\n");
-    // Exit with success
-    process.exit(0);
-  } catch (error) {
-    console.error("Error running health check:", error);
-    process.exit(1);
-  }
 }
-// Connect to transport and start the server
-const transport = new StdioServerTransport();
-await server.connect(transport);
-//# sourceMappingURL=index.js.map
+// Start server
+async function runServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.log("MCP Documentation Management Service started.");
+    console.log("Using docs directory:", docsDir);
+    console.log("Reading from stdin, writing results to stdout...");
+}
+runServer().catch((error) => {
+    console.error("Fatal error running server:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map