MCP Documentation Server

Instructions

Implementation Reference

• src/tools/getDocsByCategory.ts:105-304 (handler)

  Main handler implementation: defines the tool object with execute method that scans documentation files, categorizes them based on filename heuristics, extracts metadata, and returns a structured Markdown overview by category.

  export const getDocsByCategory = {
    name: "get_docs_by_category",
    description: "Get documentation organized by category. Returns structured overview of available documentation in each area.",
    inputSchema: inputSchema.shape,
    
    async execute(args: z.infer<typeof inputSchema>) {
      const { category } = args;
      
      try {
        const docsPath = docsDirectory;
        const files = readdirSync(docsPath).filter(file => file.endsWith('.md'));
        
        if (category === "overview") {
          // Return overview of all categories
          const categoryStats: Record<string, DocInfo[]> = {
            getting_started: [],
            concepts: [],
            development: [],
            specification: [],
            tools: [],
            community: []
          };
          
          for (const file of files) {
            const filePath = join(docsPath, file);
            const content = readFileSync(filePath, 'utf-8');
            const fileCategory = categorizeFile(file);
            
            if (fileCategory in categoryStats) {
              categoryStats[fileCategory].push({
                file,
                title: extractTitle(content),
                description: extractDescription(content),
                uri: `mcp-docs://${file}`
              });
            }
          }
          
          let response = `# 📚 MCP Documentation Overview\n\n`;
          response += `## Available Documentation Categories\n\n`;
          
          const categoryDescriptions = {
            getting_started: "🚀 **Getting Started** - Introduction to MCP and basic concepts",
            concepts: "🧠 **Core Concepts** - Architecture, primitives, and design principles", 
            development: "🛠️ **Development** - Building servers and clients",
            specification: "📋 **Protocol Specification** - Technical protocol details",
            tools: "🔧 **Tools & Debugging** - Development tools and troubleshooting",
            community: "👥 **Community** - Governance, communication, and contribution guidelines"
          };
          
          for (const [cat, docs] of Object.entries(categoryStats)) {
            if (docs.length > 0) {
              response += `### ${categoryDescriptions[cat as keyof typeof categoryDescriptions]}\n`;
              response += `*${docs.length} document${docs.length === 1 ? '' : 's'} available*\n\n`;
              
              for (const doc of docs.slice(0, 5)) {
                response += `- **${doc.title}** - ${doc.description}\n`;
                response += `  *Resource*: \`${doc.uri}\`\n`;
              }
              
              if (docs.length > 5) {
                response += `  *... and ${docs.length - 5} more documents*\n`;
              }
              response += `\n`;
            }
          }
          
          response += `## 🎯 Quick Actions\n\n`;
          response += `- **Search**: Use \`search_docs("your query")\` to find specific information\n`;
          response += `- **Browse by category**: Use \`get_docs_by_category("category_name")\`\n`;
          response += `- **Get guidance**: Use \`mcp_docs_guide("topic")\` for structured guides\n`;
          response += `- **Access full document**: Use resources like \`mcp-docs://filename.md\`\n\n`;
          
          response += `## 📖 Recommended Reading Path\n\n`;
          response += `1. **Start here**: Getting started documentation\n`;
          response += `2. **Understand**: Core concepts and architecture\n`;
          response += `3. **Build**: Development guides for servers/clients\n`;
          response += `4. **Reference**: Protocol specification when needed\n`;
          response += `5. **Debug**: Tools and troubleshooting guides\n`;
          
          return {
            content: [{
              type: "text" as const,
              text: response
            }]
          };
        }
        
        // Return specific category
        const categoryDocs: DocInfo[] = [];
        
        for (const file of files) {
          const filePath = join(docsPath, file);
          const content = readFileSync(filePath, 'utf-8');
          const fileCategory = categorizeFile(file);
          
          if (fileCategory === category) {
            categoryDocs.push({
              file,
              title: extractTitle(content),
              description: extractDescription(content),
              uri: `mcp-docs://${file}`
            });
          }
        }
        
        if (categoryDocs.length === 0) {
          return {
            content: [{
              type: "text" as const,
              text: `No documentation found in category "${category}".
  
  Available categories:
  - getting_started: Introduction and basics
  - concepts: Architecture and design principles
  - development: Building servers and clients
  - specification: Technical protocol details
  - tools: Development tools and debugging
  - community: Governance and contribution guidelines`
            }]
          };
        }
        
        // Format category-specific response
        const categoryTitles = {
          getting_started: "🚀 Getting Started with MCP",
          concepts: "🧠 MCP Core Concepts",
          development: "🛠️ MCP Development",
          specification: "📋 Protocol Specification",
          tools: "🔧 Tools & Debugging",
          community: "👥 Community & Governance"
        };
        
        let response = `# ${categoryTitles[category as keyof typeof categoryTitles]}\n\n`;
        response += `## ${categoryDocs.length} Document${categoryDocs.length === 1 ? '' : 's'} Available\n\n`;
        
        // Group by subcategory if applicable
        const subcategories: Record<string, DocInfo[]> = {};
        
        for (const doc of categoryDocs) {
          let subcategory = "General";
          
          if (category === "concepts") {
            if (doc.file.includes("architecture")) subcategory = "Architecture";
            else if (doc.file.includes("tools")) subcategory = "Tools";
            else if (doc.file.includes("resources")) subcategory = "Resources";
            else if (doc.file.includes("prompts")) subcategory = "Prompts";
            else if (doc.file.includes("transports")) subcategory = "Transports";
          } else if (category === "development") {
            if (doc.file.includes("server")) subcategory = "Server Development";
            else if (doc.file.includes("client")) subcategory = "Client Development";
            else if (doc.file.includes("connect")) subcategory = "Connection Setup";
          } else if (category === "specification") {
            if (doc.file.includes("basic")) subcategory = "Base Protocol";
            else if (doc.file.includes("server")) subcategory = "Server Features";
            else if (doc.file.includes("client")) subcategory = "Client Features";
          }
          
          if (!subcategories[subcategory]) {
            subcategories[subcategory] = [];
          }
          subcategories[subcategory].push(doc);
        }
        
        // Display by subcategory
        for (const [subcat, docs] of Object.entries(subcategories)) {
          if (Object.keys(subcategories).length > 1) {
            response += `### ${subcat}\n\n`;
          }
          
          for (const doc of docs) {
            response += `#### ${doc.title}\n`;
            response += `${doc.description}\n\n`;
            response += `**📄 Resource**: \`${doc.uri}\`\n`;
            response += `**📁 File**: \`${doc.file}\`\n\n`;
          }
        }
        
        response += `## 🔗 Related Actions\n\n`;
        response += `- **Search within category**: \`search_docs("query", "${category}")\`\n`;
        response += `- **Get structured guide**: \`mcp_docs_guide("${category === 'getting_started' ? 'getting_started' : 'core_concepts'}")\`\n`;
        response += `- **View all categories**: \`get_docs_by_category("overview")\`\n`;
        
        return {
          content: [{
            type: "text" as const,
            text: response
          }]
        };
        
      } catch (error) {
        return {
          content: [{
            type: "text" as const,
            text: `Error accessing documentation: ${error instanceof Error ? error.message : String(error)}`
          }]
        };
      }
    }
  };

• src/tools/getDocsByCategory.ts:18-28 (schema)

  Zod input schema defining the required 'category' parameter as an enum of available documentation categories.

  const inputSchema = z.object({
    category: z.enum([
      "overview",
      "getting_started",
      "concepts", 
      "development",
      "specification",
      "tools",
      "community"
    ]).describe("The documentation category to explore")
  });

• src/index.ts:155-178 (registration)

  Tool registration in ListToolsRequestHandler: provides the JSON schema, name, and description for tool discovery.

  {
    name: "get_docs_by_category",
    description:
      "Get documentation organized by category. Returns structured overview of available documentation in each area.",
    inputSchema: {
      type: "object",
      properties: {
        category: {
          type: "string",
          enum: [
            "overview",
            "getting_started",
            "concepts",
            "development",
            "specification",
            "tools",
            "community",
          ],
          description: "The documentation category to explore",
        },
      },
      required: ["category"],
    },
  },

• src/index.ts:195-196 (registration)

  Tool execution handler in CallToolRequestHandler switch statement: dispatches to the tool's execute method.

  case "get_docs_by_category":
    return await getDocsByCategory.execute(args as any);

• src/tools/getDocsByCategory.ts:37-52 (helper)

  Helper function to categorize documentation files based on filename keywords for grouping.

  function categorizeFile(filename: string): string {
    if (filename.includes("getting-started") || filename.includes("intro")) {
      return "getting_started";
    } else if (filename.includes("concepts") || filename.includes("learn") || filename.includes("architecture")) {
      return "concepts";
    } else if (filename.includes("develop") || filename.includes("build") || filename.includes("connect")) {
      return "development";
    } else if (filename.includes("basic") || filename.includes("server") || filename.includes("client") || filename.includes("specification")) {
      return "specification";
    } else if (filename.includes("tools") || filename.includes("debugging") || filename.includes("inspector")) {
      return "tools";
    } else if (filename.includes("community") || filename.includes("governance") || filename.includes("communication")) {
      return "community";
    }
    return "other";
  }