documcp

Instructions

Implementation Reference

• src/tools/setup-structure.ts:72-181 (handler)

  The primary handler function `setupStructure` that implements the core logic of the 'setup_structure' tool. It creates a Diataxis-compliant documentation structure in the specified path, supporting various static site generators (SSG), with optional example content.
  export async function setupStructure( args: unknown, ): Promise<{ content: any[] }> { const startTime = Date.now(); const { path: docsPath, ssg, includeExamples } = inputSchema.parse(args); try { const createdDirs: string[] = []; const createdFiles: string[] = []; // Create base docs directory await fs.mkdir(docsPath, { recursive: true }); // Create Diataxis structure for (const [category, info] of Object.entries(DIATAXIS_STRUCTURE)) { const categoryPath = path.join(docsPath, category); await fs.mkdir(categoryPath, { recursive: true }); createdDirs.push(categoryPath); // Create index file for category const indexPath = path.join(categoryPath, "index.md"); const indexContent = generateCategoryIndex( category, info.description, ssg, includeExamples, ); await fs.writeFile(indexPath, indexContent); createdFiles.push(indexPath); // Create example content if requested if (includeExamples) { const examplePath = path.join(categoryPath, info.example); const exampleContent = generateExampleContent( category, info.example, ssg, ); await fs.writeFile(examplePath, exampleContent); createdFiles.push(examplePath); } } // Create root index const rootIndexPath = path.join(docsPath, "index.md"); const rootIndexContent = generateRootIndex(ssg); await fs.writeFile(rootIndexPath, rootIndexContent); createdFiles.push(rootIndexPath); const structureResult = { docsPath, ssg, includeExamples, directoriesCreated: createdDirs, filesCreated: createdFiles, diataxisCategories: Object.keys(DIATAXIS_STRUCTURE), totalDirectories: createdDirs.length, totalFiles: createdFiles.length, }; const response: MCPToolResponse<typeof structureResult> = { success: true, data: structureResult, metadata: { toolVersion: "1.0.0", executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, recommendations: [ { type: "info", title: "Diataxis Structure Created", description: `Successfully created ${createdDirs.length} directories and ${createdFiles.length} files`, }, ], nextSteps: [ { action: "Generate Sitemap", toolRequired: "manage_sitemap", description: "Create sitemap.xml as source of truth for documentation links (required for SEO)", priority: "high", }, { action: "Setup GitHub Pages Deployment", toolRequired: "deploy_pages", description: "Create automated deployment workflow", priority: "medium", }, ], }; return formatMCPResponse(response); } catch (error) { const errorResponse: MCPToolResponse = { success: false, error: { code: "STRUCTURE_SETUP_FAILED", message: `Failed to setup structure: ${error}`, resolution: "Ensure the documentation path is writable and accessible", }, metadata: { toolVersion: "1.0.0", executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, }; return formatMCPResponse(errorResponse); } }
• src/tools/setup-structure.ts:6-10 (schema)

  Zod validation schema for tool inputs: `path` (docs root), `ssg` (enum: jekyll, hugo, docusaurus, mkdocs, eleventy), `includeExamples` (optional boolean, default true).
  const inputSchema = z.object({ path: z.string(), ssg: z.enum(["jekyll", "hugo", "docusaurus", "mkdocs", "eleventy"]), includeExamples: z.boolean().optional().default(true), });
• src/tools/setup-structure.ts:13-30 (helper)

  Configuration object defining the four Diataxis documentation categories (tutorials, how-to, reference, explanation) with descriptions and example filenames.
  const DIATAXIS_STRUCTURE = { tutorials: { description: "Learning-oriented guides for newcomers", example: "getting-started.md", }, "how-to": { description: "Task-oriented guides for specific goals", example: "deploy-to-production.md", }, reference: { description: "Information-oriented technical descriptions", example: "api-documentation.md", }, explanation: { description: "Understanding-oriented conceptual discussions", example: "architecture-overview.md", }, };
• src/tools/setup-structure.ts:183-233 (helper)

  Helper function `generateCategoryIndex` that creates index.md frontmatter and content for each Diataxis category, adapted to the specified SSG.
  function generateCategoryIndex( category: string, description: string, ssg: string, includeExamples: boolean = true, ): string { const title = category.charAt(0).toUpperCase() + category.slice(1).replace("-", " "); let frontmatter = ""; switch (ssg) { case "docusaurus": frontmatter = `--- id: ${category}-index title: ${title} sidebar_label: ${title} ---\n\n`; break; case "mkdocs": case "jekyll": case "hugo": frontmatter = `--- title: ${title} description: ${description} ---\n\n`; break; } return `${frontmatter}# ${title} ${description} ## Available Guides This section contains ${category} documentation following the Diataxis framework. ${generateDiataxisExplanation(category)} ## Contents ${ includeExamples ? `- [Example: ${ DIATAXIS_STRUCTURE[category as keyof typeof DIATAXIS_STRUCTURE].example }](./${ DIATAXIS_STRUCTURE[category as keyof typeof DIATAXIS_STRUCTURE].example })` : "- Coming soon..." } `; }