fumadocs-mcp

Instructions

Implementation Reference

• src/tools/list-topics.ts:15-67 (handler)

  The main listTopics handler function that executes the tool logic. It accepts an optional section parameter and either shows an overview of all sections (when section='all') or displays all topics within a specific section.

  export async function listTopics(params: ListTopicsParams): Promise<string> {
    const { section = "all" } = params;
  
    if (section === "all") {
      const sections = getAllSections();
      const output: string[] = [
        "# Fumadocs Documentation Topics\n",
        "Available documentation sections:\n",
      ];
  
      for (const sec of sections) {
        output.push(`## ${sec.name} (${sec.id})`);
        output.push(`${sec.entries.length} topics available\n`);
  
        // Show first 5 entries as preview
        const preview = sec.entries.slice(0, 5);
        for (const entry of preview) {
          output.push(`- [${entry.title}](${entry.path}): ${entry.description}`);
        }
  
        if (sec.entries.length > 5) {
          output.push(`- ... and ${sec.entries.length - 5} more topics`);
        }
        output.push("");
      }
  
      output.push("\n---");
      output.push("Use `list_topics` with a specific section to see all topics in that section.");
  
      return output.join("\n");
    }
  
    // Specific section
    const sectionName = SECTIONS[section as SectionId];
    const entries = getEntriesBySection(section as SectionId);
  
    if (entries.length === 0) {
      return `No topics found in section: ${section}`;
    }
  
    const output: string[] = [
      `# ${sectionName} Documentation\n`,
      `${entries.length} topics available:\n`,
    ];
  
    for (const entry of entries) {
      output.push(`## ${entry.title}`);
      output.push(`Path: ${entry.path}`);
      output.push(`${entry.description}\n`);
    }
  
    return output.join("\n");
  }

• src/tools/list-topics.ts:4-9 (schema)

  The Zod schema defining the input validation for the list_topics tool. It accepts an optional 'section' parameter that must be one of the allowed values: 'all', 'cli', 'headless', 'framework', 'mdx', or 'ui'.

  export const listTopicsSchema = {
    section: z
      .enum(["all", "cli", "headless", "framework", "mdx", "ui"])
      .optional()
      .describe("Section to list topics from, or 'all' for overview"),
  };

• src/tools/list-topics.ts:11-13 (schema)

  TypeScript type definition for the ListTopicsParams, ensuring type safety for the optional section parameter.

  export type ListTopicsParams = {
    section?: "all" | SectionId;
  };

• src/index.ts:26-37 (registration)

  Registration of the list_topics tool with the MCP server. Defines the tool name, description, schema, and the handler function that wraps the listTopics implementation.

  // Register list_topics tool
  server.tool(
    "list_topics",
    "Browse available Fumadocs documentation sections and topics. Use without parameters to see all sections, or specify a section to see all topics in that section.",
    listTopicsSchema,
    async (params) => {
      const result = await listTopics(params);
      return {
        content: [{ type: "text", text: result }],
      };
    }
  );

• src/data/docs-index.ts:538-549 (helper)

  Helper functions used by the listTopics handler: getEntriesBySection() filters documentation entries by section, and getAllSections() returns all sections with their associated entries.

  export function getEntriesBySection(section: SectionId): DocEntry[] {
    return DOCS_INDEX.filter((entry) => entry.section === section);
  }
  
  // Get all sections with their entries
  export function getAllSections(): { id: SectionId; name: string; entries: DocEntry[] }[] {
    return (Object.keys(SECTIONS) as SectionId[]).map((id) => ({
      id,
      name: SECTIONS[id],
      entries: getEntriesBySection(id),
    }));
  }