documcp

Instructions

Implementation Reference

• src/tools/optimize-readme.ts:100-218 (handler)

  The main handler function `optimizeReadme` that implements the core logic of the `optimize_readme` MCP tool. It handles input validation, README parsing, TL;DR generation, section extraction, documentation structure creation, and returns structured results in MCPToolResponse format.
  export async function optimizeReadme( input: Partial<OptimizeReadmeInput>, ): Promise< MCPToolResponse<{ optimization: OptimizationResult; nextSteps: string[] }> > { const startTime = Date.now(); try { // Validate input const validatedInput = OptimizeReadmeInputSchema.parse(input); const { readme_path, strategy, max_length, include_tldr, output_path, create_docs_directory, } = validatedInput; // Read original README const originalContent = await fs.readFile(readme_path, "utf-8"); const originalLength = originalContent.split("\n").length; // Parse README structure const sections = parseReadmeStructure(originalContent); // Generate TL;DR if requested const tldrGenerated = include_tldr ? generateTldr(originalContent, sections) : null; // Identify sections to extract const extractedSections = identifySectionsToExtract( sections, strategy, max_length, ); // Create basic optimization result const optimizedContent = originalContent + "\n\n## TL;DR\n\n" + (tldrGenerated || "Quick overview of the project."); const restructuringChanges = [ { type: "added" as const, section: "TL;DR", description: "Added concise project overview", impact: "Helps users quickly understand project value", }, ]; const optimizedLength = optimizedContent.split("\n").length; const reductionPercentage = Math.round( ((originalLength - optimizedLength) / originalLength) * 100, ); // Create docs directory and extract detailed content if requested if (create_docs_directory && extractedSections.length > 0) { await createDocsStructure(path.dirname(readme_path), extractedSections); } // Write optimized README if output path specified if (output_path) { await fs.writeFile(output_path, optimizedContent, "utf-8"); } const recommendations = generateOptimizationRecommendations( originalLength, optimizedLength, extractedSections, strategy, ); const optimization: OptimizationResult = { originalLength, optimizedLength, reductionPercentage, optimizedContent, extractedSections, tldrGenerated, restructuringChanges, recommendations, }; const nextSteps = generateOptimizationNextSteps( optimization, validatedInput, ); return { success: true, data: { optimization, nextSteps, }, metadata: { toolVersion: "1.0.0", executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, }; } catch (error) { return { success: false, error: { code: "OPTIMIZATION_FAILED", message: "Failed to optimize README", details: error instanceof Error ? error.message : "Unknown error", resolution: "Check README file path and permissions", }, metadata: { toolVersion: "1.0.0", executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, }; } }
• src/tools/optimize-readme.ts:7-23 (schema)

  Zod input schema `OptimizeReadmeInputSchema` and TypeScript type `OptimizeReadmeInput` defining the parameters for the `optimize_readme` tool, including README path, optimization strategy, length limits, and output options.
  const OptimizeReadmeInputSchema = z.object({ readme_path: z.string().min(1, "README path is required"), strategy: z .enum([ "community_focused", "enterprise_focused", "developer_focused", "general", ]) .optional() .default("community_focused"), max_length: z.number().min(50).max(1000).optional().default(300), include_tldr: z.boolean().optional().default(true), preserve_existing: z.boolean().optional().default(false), output_path: z.string().optional(), create_docs_directory: z.boolean().optional().default(true), });
• src/tools/optimize-readme.ts:230-289 (helper)

  Helper function `parseReadmeStructure` that parses the README markdown into structured sections (title, content, level, lines, word count, essential flag) used for analysis and optimization decisions.
  function parseReadmeStructure(content: string): ReadmeSection[] { const lines = content.split("\n"); const sections: ReadmeSection[] = []; let currentTitle = ""; let currentLevel = 0; let currentStartLine = 0; lines.forEach((line, index) => { const headingMatch = line.match(/^(#{1,6})\s+(.+)$/); if (headingMatch) { // Save previous section if (currentTitle) { const endLine = index - 1; const sectionContent = lines .slice(currentStartLine, endLine + 1) .join("\n"); const wordCount = sectionContent.split(/\s+/).length; const isEssential = isEssentialSection(currentTitle); sections.push({ title: currentTitle, content: sectionContent, level: currentLevel, startLine: currentStartLine, endLine: endLine, wordCount: wordCount, isEssential: isEssential, }); } // Start new section currentTitle = headingMatch[2].trim(); currentLevel = headingMatch[1].length; currentStartLine = index; } }); // Add final section if (currentTitle) { const endLine = lines.length - 1; const sectionContent = lines .slice(currentStartLine, endLine + 1) .join("\n"); const wordCount = sectionContent.split(/\s+/).length; const isEssential = isEssentialSection(currentTitle); sections.push({ title: currentTitle, content: sectionContent, level: currentLevel, startLine: currentStartLine, endLine: endLine, wordCount: wordCount, isEssential: isEssential, }); } return sections; }