MCP Documentation Service

Instructions

Implementation Reference

• src/handlers/navigation.ts:24-122 (handler)

  The generateNavigation method in the NavigationHandler class executes the core logic of the 'generate_documentation_navigation' tool. It glob-searches for .md files, parses frontmatter for titles and orders, constructs a hierarchical navigation structure with directories, sorts by order, and returns JSON.

  async generateNavigation(basePath = ""): Promise<ToolResponse> {
    try {
      const baseDir = path.join(this.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: any[] = [];
      const directoryMap: Record<string, any> = {};
  
      for (const file of files) {
        const relativePath = path.relative(this.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: [],
        };
  
        const dirPath = path.dirname(relativePath);
  
        if (dirPath === "." || dirPath === basePath) {
          navigation.push(item);
        } 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);
        }
      }
  
      // Sort navigation items by order
      function sortNavigation(items: any[]) {
        items.sort((a, b) => a.order - b.order);
  
        for (const item of items) {
          if (item.children && item.children.length > 0) {
            sortNavigation(item.children);
          }
        }
      }
  
      sortNavigation(navigation);
  
      return {
        content: [{ type: "text", text: JSON.stringify(navigation, null, 2) }],
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text",
            text: `Error generating navigation: ${errorMessage}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:236-241 (registration)

  Registration of the tool in the ListToolsRequestHandler, specifying name, description, and input schema (ListDocumentsSchema).

    name: "generate_documentation_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(ListDocumentsSchema) as any,
  },

• src/schemas/tools.ts:13-16 (schema)

  Zod schema defining the input parameters for the tool: optional basePath (string) and recursive (boolean, default false). Extends ToolInputSchema.

  export const ListDocumentsSchema = ToolInputSchema.extend({
    basePath: z.string().optional(),
    recursive: z.boolean().default(false),
  });

• src/index.ts:375-385 (registration)

  Dispatch handler in CallToolRequestHandler that validates input with ListDocumentsSchema and delegates to navigationHandler.generateNavigation(basePath).

  case "generate_documentation_navigation": {
    const parsed = ListDocumentsSchema.safeParse(args);
    if (!parsed.success) {
      throw new Error(
        `Invalid arguments for generate_navigation: ${parsed.error}`
      );
    }
    return await navigationHandler.generateNavigation(
      parsed.data.basePath
    );
  }