documcp

Instructions

Implementation Reference

• src/tools/readme-best-practices.ts:65-200 (handler)

  Main handler function that validates input, reads README, generates checklist, calculates score, provides recommendations, and optionally generates templates and community files.
  export async function readmeBestPractices( input: Partial<ReadmeBestPracticesInput>, ): Promise< MCPToolResponse<{ bestPracticesReport: BestPracticesReport; recommendations: string[]; nextSteps: string[]; }> > { const startTime = Date.now(); try { // Validate input with defaults const validatedInput = ReadmeBestPracticesInputSchema.parse(input); const { readme_path, project_type, generate_template, output_directory, include_community_files, target_audience, } = validatedInput; // Read README content let readmeContent = ""; try { readmeContent = await readFile(readme_path, "utf-8"); } catch (error) { if (!generate_template) { return { success: false, error: { code: "README_NOT_FOUND", message: "README file not found. Use generate_template: true to create a new README.", details: error instanceof Error ? error.message : "Unknown error", resolution: "Set generate_template: true to create a new README from template", }, metadata: { toolVersion: "1.0.0", executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, }; } } // Generate checklist based on project type and content const checklist = generateChecklist( readmeContent, project_type, target_audience, ); // Calculate overall score const { score, grade } = calculateOverallScore(checklist); // Generate recommendations const recommendations = generateRecommendations( checklist, project_type, target_audience, ); // Generate templates if requested const templates = generate_template ? generateTemplates(project_type, generate_template) : {}; // Generate community files if requested const communityFiles = include_community_files ? generateCommunityFiles(project_type) : {}; // Calculate summary metrics const summary = calculateSummaryMetrics(checklist); // Write files if output directory specified if (output_directory && generate_template) { await writeGeneratedFiles( templates, communityFiles, output_directory, readme_path, ); } const report: BestPracticesReport = { overallScore: score, grade, checklist, recommendations, templates, communityFiles, summary, }; const nextSteps = generateNextSteps( report.checklist, true, output_directory, ); return { success: true, data: { bestPracticesReport: report, recommendations, nextSteps, }, metadata: { toolVersion: "1.0.0", executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), analysisId: `readme-best-practices-${Date.now()}`, }, }; } catch (error) { return { success: false, error: { code: "ANALYSIS_FAILED", message: "Failed to analyze README best practices", details: error instanceof Error ? error.message : "Unknown error", resolution: "Check README file path and permissions, ensure valid project type", }, metadata: { toolVersion: "1.0.0", executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, }; } }
• src/tools/readme-best-practices.ts:7-35 (schema)

  Zod schema for input validation, defining parameters such as readme_path, project_type, generate_template, output_directory, include_community_files, and target_audience with descriptions and defaults.
  const ReadmeBestPracticesInputSchema = z.object({ readme_path: z.string().describe("Path to the README file to analyze"), project_type: z .enum(["library", "application", "tool", "documentation", "framework"]) .optional() .default("library") .describe("Type of project for tailored analysis"), generate_template: z .boolean() .optional() .default(false) .describe("Generate README templates and community files"), output_directory: z .string() .optional() .describe("Directory to write generated templates and community files"), include_community_files: z .boolean() .optional() .default(true) .describe( "Generate community health files (CONTRIBUTING.md, CODE_OF_CONDUCT.md, etc.)", ), target_audience: z .enum(["beginner", "intermediate", "advanced", "mixed"]) .optional() .default("mixed") .describe("Target audience for recommendations"), });
• src/tools/readme-best-practices.ts:202-394 (helper)

  Core helper function that analyzes README content against best practices checklist items, categorized by severity (critical, important, recommended), with project-type specific checks.
  function generateChecklist( content: string, projectType: string, _targetAudience: string, ): ChecklistItem[] { const checklist: ChecklistItem[] = []; const lines = content.split("\n"); const lowerContent = content.toLowerCase(); // Essential Sections checklist.push({ category: "Essential Sections", item: "Project Title", present: /^#\s+.+/m.test(content), severity: "critical", description: "Clear, descriptive project title as main heading", example: "# My Awesome Project", }); checklist.push({ category: "Essential Sections", item: "One-line Description", present: />\s*.+/.test(content) || lines.some( (line) => line.trim().length > 20 && line.trim().length < 100 && !line.startsWith("#"), ), severity: "critical", description: "Brief one-line description of what the project does", example: "> A fast, lightweight JavaScript framework for building web applications", }); checklist.push({ category: "Essential Sections", item: "Installation Instructions", present: /install/i.test(lowerContent) && /npm|yarn|pip|cargo|go get|git clone/i.test(lowerContent), severity: "critical", description: "Clear installation or setup instructions", example: "```bash\nnpm install package-name\n```", }); checklist.push({ category: "Essential Sections", item: "Basic Usage Example", present: /usage|example|quick start|getting started/i.test(lowerContent) && /```/.test(content), severity: "critical", description: "Working code example showing basic usage", example: '```javascript\nconst lib = require("package-name");\nlib.doSomething();\n```', }); // Important Sections checklist.push({ category: "Important Sections", item: "Prerequisites/Requirements", present: /prerequisite|requirement|dependencies|node|python|java|version/i.test( lowerContent, ), severity: "important", description: "Clear system requirements and dependencies", example: "- Node.js 16+\n- Docker (optional)", }); checklist.push({ category: "Important Sections", item: "License Information", present: /license/i.test(lowerContent) || /mit|apache|gpl|bsd/i.test(lowerContent), severity: "important", description: "Clear license information", example: "## License\n\nMIT License - see [LICENSE](LICENSE) file", }); checklist.push({ category: "Important Sections", item: "Contributing Guidelines", present: /contribut/i.test(lowerContent), severity: "important", description: "Information on how to contribute to the project", example: "See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines", }); // Community Health checklist.push({ category: "Community Health", item: "Code of Conduct", present: /code of conduct/i.test(lowerContent), severity: "recommended", description: "Link to code of conduct for community projects", example: "Please read our [Code of Conduct](CODE_OF_CONDUCT.md)", }); checklist.push({ category: "Community Health", item: "Issue Templates", present: /issue template|bug report|feature request/i.test(lowerContent), severity: "recommended", description: "Reference to issue templates for better bug reports", example: "Use our [issue templates](.github/ISSUE_TEMPLATE/) when reporting bugs", }); // Visual Elements checklist.push({ category: "Visual Elements", item: "Badges", present: /\[!\[.*\]\(.*\)\]\(.*\)/.test(content) || /badge/i.test(lowerContent), severity: "recommended", description: "Status badges for build, version, license, etc.", example: "[](link-url)", }); checklist.push({ category: "Visual Elements", item: "Screenshots/Demo", present: /!\[.*\]\(.*\.(png|jpg|jpeg|gif|webp)\)/i.test(content) || /screenshot|demo|gif/i.test(lowerContent), severity: projectType === "application" || projectType === "tool" ? "important" : "recommended", description: "Visual demonstration of the project (especially for applications)", example: "", }); // Content Quality checklist.push({ category: "Content Quality", item: "Appropriate Length", present: lines.length >= 20 && lines.length <= 300, severity: "important", description: "README length appropriate for project complexity (20-300 lines)", example: "Keep main README focused, link to detailed docs", }); checklist.push({ category: "Content Quality", item: "Clear Section Headers", present: (content.match(/^##\s+/gm) || []).length >= 3, severity: "important", description: "Well-organized content with clear section headers", example: "## Installation\n## Usage\n## Contributing", }); checklist.push({ category: "Content Quality", item: "Working Links", present: !/\[.*\]\(\)/.test(content) && !/\[.*\]\(#\)/.test(content), severity: "important", description: "All links should be functional (no empty or placeholder links)", example: "[Documentation](https://example.com/docs)", }); // Project-specific checks if (projectType === "library" || projectType === "framework") { checklist.push({ category: "Library Specific", item: "API Documentation", present: /api|methods|functions|reference/i.test(lowerContent), severity: "important", description: "API documentation or link to detailed API reference", example: "See [API Documentation](docs/api.md) for detailed method reference", }); } if (projectType === "application" || projectType === "tool") { checklist.push({ category: "Application Specific", item: "Configuration Options", present: /config|settings|options|environment/i.test(lowerContent), severity: "important", description: "Configuration and customization options", example: "See [Configuration Guide](docs/configuration.md)", }); } return checklist; }
• src/tools/readme-best-practices.ts:396-423 (helper)

  Calculates overall score and letter grade from the checklist using weighted severity scoring.
  function calculateOverallScore(checklist: ChecklistItem[]): { score: number; grade: string; } { const weights = { critical: 3, important: 2, recommended: 1 }; let totalScore = 0; let maxScore = 0; checklist.forEach((item) => { const weight = weights[item.severity]; maxScore += weight; if (item.present) { totalScore += weight; } }); const percentage = maxScore > 0 ? Math.round((totalScore / maxScore) * 100) : 0; let grade: string; if (percentage >= 90) grade = "A"; else if (percentage >= 80) grade = "B"; else if (percentage >= 70) grade = "C"; else if (percentage >= 60) grade = "D"; else grade = "F"; return { score: percentage, grade }; }