analyze_readme
Analyzes README files to assess length, evaluate structure, and identify optimization opportunities for improved documentation quality.
Instructions
Comprehensive README analysis with length assessment, structure evaluation, and optimization opportunities
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes | Path to the project directory containing README | |
| target_audience | No | Target audience for analysis | community_contributors |
| optimization_level | No | Level of optimization suggestions | moderate |
| max_length_target | No | Target maximum length in lines |
Implementation Reference
- src/tools/analyze-readme.ts:131-250 (handler)The primary handler function `analyzeReadme` that implements the core logic for README analysis. It validates input, locates and reads the README, performs multi-dimensional analysis (length, structure, content, community readiness), computes scores, generates recommendations, and returns structured MCPToolResponse.export async function analyzeReadme( input: Partial<AnalyzeReadmeInput>, ): Promise<MCPToolResponse<{ analysis: ReadmeAnalysis; nextSteps: string[] }>> { const startTime = Date.now(); try { // Validate input const validatedInput = AnalyzeReadmeInputSchema.parse(input); const { project_path, target_audience, optimization_level, max_length_target, } = validatedInput; // Find README file const readmePath = await findReadmeFile(project_path); if (!readmePath) { return { success: false, error: { code: "README_NOT_FOUND", message: "No README file found in the project directory", details: "Looked for README.md, README.txt, readme.md in project root", resolution: "Create a README.md file in the project root directory", }, metadata: { toolVersion: "1.0.0", executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, }; } // Read README content const readmeContent = await fs.readFile(readmePath, "utf-8"); // Get project context const projectContext = await analyzeProjectContext(project_path); // Perform comprehensive analysis const lengthAnalysis = analyzeLengthMetrics( readmeContent, max_length_target, ); const structureAnalysis = analyzeStructure(readmeContent); const contentAnalysis = analyzeContent(readmeContent); const communityReadiness = analyzeCommunityReadiness( readmeContent, projectContext, ); // Generate optimization opportunities const optimizationOpportunities = generateOptimizationOpportunities( lengthAnalysis, structureAnalysis, contentAnalysis, communityReadiness, optimization_level, target_audience, ); // Calculate overall score const overallScore = calculateOverallScore( lengthAnalysis, structureAnalysis, contentAnalysis, communityReadiness, ); // Generate recommendations const recommendations = generateRecommendations( optimizationOpportunities, target_audience, optimization_level, ); const analysis: ReadmeAnalysis = { lengthAnalysis, structureAnalysis, contentAnalysis, communityReadiness, optimizationOpportunities, overallScore, recommendations, }; const nextSteps = generateNextSteps(analysis, optimization_level); return { success: true, data: { analysis, nextSteps, }, metadata: { toolVersion: "1.0.0", executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), analysisId: `readme-analysis-${Date.now()}`, }, }; } catch (error) { return { success: false, error: { code: "ANALYSIS_FAILED", message: "Failed to analyze README", details: error instanceof Error ? error.message : "Unknown error", resolution: "Check project path and README file accessibility", }, metadata: { toolVersion: "1.0.0", executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, }; } }
- src/tools/analyze-readme.ts:7-23 (schema)Zod input schema defining parameters for the analyze_readme tool: project_path (required), target_audience, optimization_level, and max_length_target.const AnalyzeReadmeInputSchema = z.object({ project_path: z.string().min(1, "Project path is required"), target_audience: z .enum([ "community_contributors", "enterprise_users", "developers", "general", ]) .optional() .default("community_contributors"), optimization_level: z .enum(["light", "moderate", "aggressive"]) .optional() .default("moderate"), max_length_target: z.number().min(50).max(1000).optional().default(300), });
- src/tools/analyze-readme.ts:252-272 (helper)Helper function to locate the README file by trying common naming conventions in the project root.async function findReadmeFile(projectPath: string): Promise<string | null> { const possibleNames = [ "README.md", "README.txt", "readme.md", "Readme.md", "README", ]; for (const name of possibleNames) { const filePath = path.join(projectPath, name); try { await fs.access(filePath); return filePath; } catch { continue; } } return null; }
- src/tools/analyze-readme.ts:302-314 (helper)Helper function that computes length metrics for the README content against target length.function analyzeLengthMetrics(content: string, targetLines: number) { const lines = content.split("\n"); const words = content.split(/\s+/).length; const currentLines = lines.length; return { currentLines, currentWords: words, targetLines, exceedsTarget: currentLines > targetLines, reductionNeeded: Math.max(0, currentLines - targetLines), }; }