documcp

Instructions

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),
    };
  }