documcp

import { readFile, writeFile, mkdir } from "fs/promises"; import { join } from "path"; import { z } from "zod"; import { MCPToolResponse } from "../types/api.js"; // Input validation schema 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"), }); type ReadmeBestPracticesInput = z.infer<typeof ReadmeBestPracticesInputSchema>; interface ChecklistItem { category: string; item: string; present: boolean; severity: "critical" | "important" | "recommended"; description: string; example?: string; } interface BestPracticesReport { overallScore: number; grade: string; checklist: ChecklistItem[]; recommendations: string[]; templates: Record<string, string>; communityFiles: Record<string, string>; summary: { criticalIssues: number; importantIssues: number; recommendedImprovements: number; sectionsPresent: number; totalSections: number; estimatedImprovementTime: string; }; } 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(), }, }; } } 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; } 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 }; } function generateRecommendations( checklist: ChecklistItem[], projectType: string, targetAudience: string, ): string[] { const recommendations: string[] = []; const missing = checklist.filter((item) => !item.present); // Critical issues first const critical = missing.filter((item) => item.severity === "critical"); if (critical.length > 0) { recommendations.push( `🚨 Critical: Fix ${critical.length} essential sections: ${critical .map((item) => item.item) .join(", ")}`, ); } // Important issues const important = missing.filter((item) => item.severity === "important"); if (important.length > 0) { recommendations.push( `⚠️ Important: Add ${important.length} key sections: ${important .map((item) => item.item) .join(", ")}`, ); } // Project-specific recommendations if (projectType === "library") { recommendations.push( "📚 Library Focus: Emphasize installation, basic usage, and API documentation", ); } else if (projectType === "application") { recommendations.push( "🖥️ Application Focus: Include screenshots, configuration options, and deployment guides", ); } // Target audience specific recommendations if (targetAudience === "beginner") { recommendations.push( "👶 Beginner-Friendly: Use simple language, provide detailed examples, include troubleshooting", ); } else if (targetAudience === "advanced") { recommendations.push( "🎯 Advanced Users: Focus on technical details, performance notes, and extensibility", ); } // General improvements const recommended = missing.filter((item) => item.severity === "recommended"); if (recommended.length > 0) { recommendations.push( `✨ Enhancement: Consider adding ${recommended .map((item) => item.item) .join(", ")}`, ); } return recommendations; } function generateTemplates( projectType: string, _generateTemplate: boolean, ): Record<string, string> { const templates: Record<string, string> = {}; if (projectType === "library") { templates["README-library.md"] = `# Project Name > One-line description of what this library does [![Build Status][build-badge]][build-link] [![npm version][npm-badge]][npm-link] [![License][license-badge]][license-link] ## TL;DR What it does in 2-3 sentences. Who should use it. ## Quick Start ### Install \`\`\`bash npm install package-name \`\`\` ### Use \`\`\`javascript const lib = require('package-name'); // Basic usage example const result = lib.doSomething(); console.log(result); \`\`\` ## When to Use This - ✅ When you need X functionality - ✅ When you want Y capability - ❌ When you need Z (use [alternative] instead) ## API Reference ### \`doSomething(options)\` Description of the main method. **Parameters:** - \`options\` (Object): Configuration options - \`param1\` (string): Description of parameter - \`param2\` (boolean, optional): Description of optional parameter **Returns:** Description of return value **Example:** \`\`\`javascript const result = lib.doSomething({ param1: 'value', param2: true }); \`\`\` ## Full Documentation [Link to full documentation](docs/) ## Contributing We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License MIT License - see [LICENSE](LICENSE) file for details. [build-badge]: https://github.com/username/repo/workflows/CI/badge.svg [build-link]: https://github.com/username/repo/actions [npm-badge]: https://img.shields.io/npm/v/package-name.svg [npm-link]: https://www.npmjs.com/package/package-name [license-badge]: https://img.shields.io/badge/license-MIT-blue.svg [license-link]: LICENSE `; } if (projectType === "application" || projectType === "tool") { templates["README-application.md"] = `# Project Name > One-line description of what this application does  ## What This Does Brief explanation of the application's purpose and key features: - 🚀 Feature 1: Description - 📊 Feature 2: Description - 🔧 Feature 3: Description ## Quick Start ### Prerequisites - Node.js 16+ - Docker (optional) - Other requirements ### Install & Run \`\`\`bash git clone https://github.com/username/repo.git cd project-name npm install npm start \`\`\` Visit \`http://localhost:3000\` to see the application. ## Configuration ### Environment Variables \`\`\`bash # Copy example config cp .env.example .env # Edit configuration nano .env \`\`\` ### Key Settings - \`PORT\`: Server port (default: 3000) - \`DATABASE_URL\`: Database connection string - \`API_KEY\`: External service API key ## Usage Examples ### Basic Usage \`\`\`bash npm run command -- --option value \`\`\` ### Advanced Usage \`\`\`bash npm run command -- --config custom.json --verbose \`\`\` ## Deployment See [Deployment Guide](docs/deployment.md) for production setup. ## Troubleshooting ### Common Issues **Issue 1: Error message** - Solution: Steps to resolve **Issue 2: Another error** - Solution: Steps to resolve See [FAQ](docs/FAQ.md) for more help. ## Contributing We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License MIT License - see [LICENSE](LICENSE) file for details. `; } return templates; } function generateCommunityFiles(_projectType: string): Record<string, string> { const files: Record<string, string> = {}; files["CONTRIBUTING.md"] = `# Contributing to Project Name Thank you for your interest in contributing! This document provides guidelines for contributing to this project. ## Getting Started 1. Fork the repository 2. Clone your fork: \`git clone https://github.com/yourusername/repo.git\` 3. Create a feature branch: \`git checkout -b feature-name\` 4. Make your changes 5. Test your changes: \`npm test\` 6. Commit your changes: \`git commit -m "Description of changes"\` 7. Push to your fork: \`git push origin feature-name\` 8. Create a Pull Request ## Development Setup \`\`\`bash npm install npm run dev \`\`\` ## Code Style - Use TypeScript for new code - Follow existing code formatting - Run \`npm run lint\` before committing - Add tests for new features ## Pull Request Guidelines - Keep PRs focused and small - Include tests for new functionality - Update documentation as needed - Ensure CI passes - Link to relevant issues ## Reporting Issues Use our [issue templates](.github/ISSUE_TEMPLATE/) when reporting bugs or requesting features. ## Code of Conduct Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md). `; files["CODE_OF_CONDUCT.md"] = `# Code of Conduct ## Our Pledge We pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. ## Our Standards Examples of behavior that contributes to creating a positive environment include: - Using welcoming and inclusive language - Being respectful of differing viewpoints and experiences - Gracefully accepting constructive criticism - Focusing on what is best for the community - Showing empathy towards other community members Examples of unacceptable behavior include: - The use of sexualized language or imagery and unwelcome sexual attention or advances - Trolling, insulting/derogatory comments, and personal or political attacks - Public or private harassment - Publishing others' private information without explicit permission - Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 1.4. `; files["SECURITY.md"] = `# Security Policy ## Supported Versions | Version | Supported | | ------- | ------------------ | | 1.x.x | :white_check_mark: | | < 1.0 | :x: | ## Reporting a Vulnerability If you discover a security vulnerability, please report it privately: 1. **Do not** create a public issue 2. Email security@example.com with details 3. Include steps to reproduce if possible 4. We will respond within 48 hours ## Security Best Practices When using this project: - Keep dependencies updated - Use environment variables for secrets - Follow principle of least privilege - Regularly audit your setup Thank you for helping keep our project secure! `; return files; } async function writeGeneratedFiles( templates: Record<string, string>, communityFiles: Record<string, string>, outputDirectory: string, _originalReadmePath: string, ): Promise<void> { try { // Create output directory await mkdir(outputDirectory, { recursive: true }); // Write templates for (const [filename, content] of Object.entries(templates)) { const filePath = join(outputDirectory, filename); await writeFile(filePath, content, "utf-8"); } // Write community files for (const [filename, content] of Object.entries(communityFiles)) { const filePath = join(outputDirectory, filename); await writeFile(filePath, content, "utf-8"); } // Create .github directory structure const githubDir = join(outputDirectory, ".github"); await mkdir(githubDir, { recursive: true }); const issueTemplateDir = join(githubDir, "ISSUE_TEMPLATE"); await mkdir(issueTemplateDir, { recursive: true }); // Bug report template const bugReportTemplate = `--- name: Bug report about: Create a report to help us improve title: '[BUG] ' labels: bug assignees: '' --- **Describe the bug** A clear and concise description of what the bug is. **To Reproduce** Steps to reproduce the behavior: 1. Go to '...' 2. Click on '....' 3. Scroll down to '....' 4. See error **Expected behavior** A clear and concise description of what you expected to happen. **Screenshots** If applicable, add screenshots to help explain your problem. **Environment:** - OS: [e.g. iOS] - Browser [e.g. chrome, safari] - Version [e.g. 22] **Additional context** Add any other context about the problem here. `; await writeFile( join(issueTemplateDir, "bug_report.yml"), bugReportTemplate, "utf-8", ); // Feature request template const featureRequestTemplate = `--- name: Feature request about: Suggest an idea for this project title: '[FEATURE] ' labels: enhancement assignees: '' --- **Is your feature request related to a problem? Please describe.** A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] **Describe the solution you'd like** A clear and concise description of what you want to happen. **Describe alternatives you've considered** A clear and concise description of any alternative solutions or features you've considered. **Additional context** Add any other context or screenshots about the feature request here. `; await writeFile( join(issueTemplateDir, "feature_request.yml"), featureRequestTemplate, "utf-8", ); // Pull request template const prTemplate = `## Description Brief description of changes made. ## Type of Change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Documentation update ## Testing - [ ] Tests pass locally - [ ] New tests added for new functionality - [ ] Manual testing completed ## Checklist - [ ] Code follows project style guidelines - [ ] Self-review completed - [ ] Documentation updated - [ ] No new warnings introduced `; await writeFile( join(githubDir, "PULL_REQUEST_TEMPLATE.md"), prTemplate, "utf-8", ); } catch (error) { throw new Error( `Failed to write generated files: ${ error instanceof Error ? error.message : "Unknown error" }`, ); } } function calculateSummaryMetrics(checklist: ChecklistItem[]) { const criticalIssues = checklist.filter( (item) => !item.present && item.severity === "critical", ).length; const importantIssues = checklist.filter( (item) => !item.present && item.severity === "important", ).length; const recommendedImprovements = checklist.filter( (item) => !item.present && item.severity === "recommended", ).length; const sectionsPresent = checklist.filter((item) => item.present).length; const totalSections = checklist.length; // Estimate improvement time based on missing items const totalMissing = criticalIssues + importantIssues + recommendedImprovements; let estimatedTime = ""; if (totalMissing === 0) { estimatedTime = "No improvements needed"; } else if (totalMissing <= 3) { estimatedTime = "30 minutes - 1 hour"; } else if (totalMissing <= 6) { estimatedTime = "1-2 hours"; } else if (totalMissing <= 10) { estimatedTime = "2-4 hours"; } else { estimatedTime = "4+ hours (consider phased approach)"; } return { criticalIssues, importantIssues, recommendedImprovements, sectionsPresent, totalSections, estimatedImprovementTime: estimatedTime, }; } function generateNextSteps( checklist: ChecklistItem[], generateTemplate: boolean, outputDirectory?: string, ): string[] { const nextSteps: string[] = []; const missing = checklist.filter((item) => !item.present); if (missing.length === 0) { nextSteps.push( "✅ README follows all best practices - no immediate action needed", ); nextSteps.push( "📊 Consider periodic reviews to maintain quality as project evolves", ); return nextSteps; } // Critical issues first const critical = missing.filter((item) => item.severity === "critical"); if (critical.length > 0) { nextSteps.push( `🚨 Priority 1: Address ${critical.length} critical issues immediately`, ); critical.forEach((item) => { nextSteps.push(` • Add ${item.item}: ${item.description}`); }); } // Important issues const important = missing.filter((item) => item.severity === "important"); if (important.length > 0) { nextSteps.push( `⚠️ Priority 2: Address ${important.length} important sections within 1 week`, ); } // Template usage if (generateTemplate && outputDirectory) { nextSteps.push(`📝 Review generated templates in ${outputDirectory}/`); nextSteps.push("🔄 Customize templates to match your project specifics"); nextSteps.push( "📋 Use community files (.github templates, CONTRIBUTING.md) to improve project health", ); } // General improvements nextSteps.push( "🔍 Run this analysis periodically to maintain README quality", ); nextSteps.push( "👥 Consider getting feedback from new users on README clarity", ); return nextSteps; }