MCP Documentation Service

Instructions

Implementation Reference

• src/handlers/documents.ts:881-960 (handler)

  The core handler function that implements the tool logic: scans all .md files in the basePath (default docs dir), parses frontmatter using parseFrontmatter helper, checks for required metadata fields (default: title, description, status), collects missing ones, computes completeness percentage, and returns a ToolResponse with results.

  /**
   * Validate metadata in documentation
   */
  async validateMetadata(
    basePath = "",
    requiredFields?: string[]
  ): Promise<ToolResponse> {
    try {
      const validBasePath = await this.validatePath(basePath || this.docsDir);
  
      // Default required fields if not specified
      const fields = requiredFields || ["title", "description", "status"];
  
      // Find all markdown files
      const files = await glob("**/*.md", { cwd: validBasePath });
  
      const missingMetadata: Array<{
        file: string;
        missingFields: string[];
      }> = [];
  
      // Check each file for metadata
      for (const file of files) {
        const filePath = path.join(validBasePath, file);
        const content = await fs.readFile(filePath, "utf-8");
  
        // Parse frontmatter
        const { frontmatter } = parseFrontmatter(content);
  
        // Check for required fields
        const missing = fields.filter((field) => !frontmatter[field]);
  
        if (missing.length > 0) {
          missingMetadata.push({
            file: path.relative(this.docsDir, filePath),
            missingFields: missing,
          });
        }
      }
  
      // Calculate completeness percentage
      const totalFields = files.length * fields.length;
      const missingFields = missingMetadata.reduce(
        (sum, item) => sum + item.missingFields.length,
        0
      );
      const completenessPercentage =
        totalFields > 0
          ? Math.round(((totalFields - missingFields) / totalFields) * 100)
          : 100;
  
      return {
        content: [
          {
            type: "text",
            text:
              missingMetadata.length > 0
                ? `Found ${missingMetadata.length} files with missing metadata. Completeness: ${completenessPercentage}%`
                : `All ${files.length} files have complete metadata. Completeness: 100%`,
          },
        ],
        metadata: {
          missingMetadata,
          filesChecked: files.length,
          requiredFields: fields,
          completenessPercentage,
          basePath: path.relative(this.docsDir, validBasePath),
        },
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      return {
        content: [
          { type: "text", text: `Error validating metadata: ${errorMessage}` },
        ],
        isError: true,
      };
    }
  }

• src/schemas/tools.ts:98-101 (schema)

  Zod schema defining the input parameters for the tool: optional basePath (defaults to root) and optional array of requiredFields.

  export const ValidateMetadataSchema = ToolInputSchema.extend({
    basePath: z.string().optional().default(""),
    requiredFields: z.array(z.string()).optional(),
  });

• src/index.ts:290-294 (registration)

  Tool registration in the MCP server's listTools handler, specifying name, description, and input schema.

  {
    name: "validate_documentation_metadata",
    description: "Ensure all documents have required metadata fields.",
    inputSchema: zodToJsonSchema(ValidateMetadataSchema) as any,
  },

• src/index.ts:483-494 (handler)

  Dispatch handler in the main CallToolRequestSchema switch statement that validates input and calls the DocumentHandler's validateMetadata method.

  case "validate_documentation_metadata": {
    const parsed = ValidateMetadataSchema.safeParse(args);
    if (!parsed.success) {
      throw new Error(
        `Invalid arguments for validate_metadata: ${parsed.error}`
      );
    }
    return await documentHandler.validateMetadata(
      parsed.data.basePath,
      parsed.data.requiredFields
    );
  }

• src/handlers/documents.ts:40-83 (helper)

  Helper function used by validateMetadata to parse YAML frontmatter from markdown files and extract metadata fields.

  export function parseFrontmatter(content: string): {
    frontmatter: Record<string, any>;
    content: string;
  } {
    const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n/;
    const match = content.match(frontmatterRegex);
  
    if (!match) {
      return { frontmatter: {}, content };
    }
  
    const frontmatterStr = match[1];
    const contentWithoutFrontmatter = content.slice(match[0].length);
  
    // Parse frontmatter as key-value pairs
    const frontmatter: Record<string, any> = {};
    const lines = frontmatterStr.split("\n");
  
    for (const line of lines) {
      const colonIndex = line.indexOf(":");
      if (colonIndex !== -1) {
        const key = line.slice(0, colonIndex).trim();
        let value = line.slice(colonIndex + 1).trim();
  
        // Handle quoted values
        if (value.startsWith('"') && value.endsWith('"')) {
          value = value.slice(1, -1);
        }
  
        // Handle arrays
        if (value.startsWith("[") && value.endsWith("]")) {
          try {
            value = JSON.parse(value);
          } catch {
            // Keep as string if parsing fails
          }
        }
  
        frontmatter[key] = value;
      }
    }
  
    return { frontmatter, content: contentWithoutFrontmatter };
  }