documcp

Instructions

Implementation Reference

• src/tools/setup-structure.ts:6-10 (schema)

  Zod schema for input validation: path (string), ssg (enum of static site generators), includeExamples (boolean, optional, 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:72-181 (handler)

  Core handler function that validates input with schema, creates Diataxis-compliant documentation structure (tutorials, how-to, reference, explanation directories with index.md and optional examples), generates frontmatter/content based on SSG, and returns formatted MCPToolResponse with results, recommendations, and nextSteps.

  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:13-30 (helper)

  Constant defining the four Diataxis categories with descriptions and example filenames used to structure the documentation directories and files.

  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",
    },
  };