Project Health Auditor

MCP Server Plugin for Claude Code

Analyze local repositories for code health, complexity, test coverage gaps, and git churn patterns. Get multi-dimensional insights into your codebase health combining complexity metrics, change frequency, and test coverage.

Features

4 Powerful MCP Tools

1. list_repo_files - File Discovery

• List all files in a repository with glob pattern matching
• Exclude patterns (node_modules, .git, dist, build)
• Returns file count and full file list

2. file_metrics - Code Health Analysis

• Cyclomatic complexity calculation
• Function/method counting
• Comment ratio analysis
• File size and line count
• Health score (0-100) based on multiple factors

3. git_churn - Change Frequency Analysis

• Identify files that change frequently
• Track authors per file
• Find hot spots in your codebase
• Analyze commit patterns over time

4. map_tests - Test Coverage Mapping

• Map source files to test files
• Identify files missing tests
• Calculate test coverage ratio
• Get actionable recommendations

Installation

# Install the plugin
/plugin install project-health-auditor@claude-code-plugins-plus

# The MCP server will be automatically available

Usage

Quick Analysis

Analyze the health of /path/to/my-project

Claude will use the MCP tools to:

1. List all source files
2. Analyze complexity of key files
3. Check git churn patterns
4. Map test coverage

Individual Tool Usage

List Repository Files:

Use list_repo_files on /path/to/repo with globs ["src/**/*.ts", "lib/**/*.js"]

Analyze File Metrics:

What's the complexity of src/services/auth.ts?

Check Git Churn:

Show me the most frequently changed files in the last 6 months

Map Tests:

Which files are missing tests in this project?

️ MCP Tools Reference

list_repo_files

Purpose: Discover files in a repository

Input:

{
  repoPath: string;           // Absolute path to repository
  globs?: string[];           // Patterns to match (default: ["**/*"])
  exclude?: string[];         // Patterns to exclude
}

Output:

{
  "repoPath": "/path/to/repo",
  "totalFiles": 245,
  "files": ["src/index.ts", "src/utils/helper.ts", ...],
  "patterns": ["**/*"],
  "excluded": ["node_modules/**", ".git/**"]
}

file_metrics

Purpose: Analyze a single file's health

Input:

{
  filePath: string;  // Absolute path to file
}

Output:

{
  "file": "src/services/auth.ts",
  "size": 12543,
  "lines": 342,
  "extension": ".ts",
  "complexity": {
    "cyclomatic": 28,
    "functions": 12,
    "averagePerFunction": 2
  },
  "comments": {
    "lines": 45,
    "ratio": 13.16
  },
  "healthScore": 75
}

Health Score Factors:

• High complexity (>10 per function): -30 points
• Medium complexity (5-10): -15 points
• Low comments (<5%): -10 points
• Good comments (>20%): +10 points
• Very long files (>500 lines): -20 points
• Long files (>300 lines): -10 points

git_churn

Purpose: Find frequently changing files (hot spots)

Input:

{
  repoPath: string;             // Absolute path to git repository
  since?: string;               // Time period (default: "6 months ago")
}

Output:

{
  "repoPath": "/path/to/repo",
  "since": "6 months ago",
  "totalCommits": 342,
  "filesChanged": 156,
  "topChurnFiles": [
    {
      "file": "src/api/handler.ts",
      "commits": 45,
      "authors": ["Alice", "Bob"],
      "authorCount": 2
    }
  ],
  "summary": {
    "highChurn": 12,      // >10 commits
    "mediumChurn": 34,    // 5-10 commits
    "lowChurn": 110       // <5 commits
  }
…

High churn files are candidates for refactoring or stabilization.

map_tests

Purpose: Identify test coverage gaps

Input:

{
  repoPath: string;  // Absolute path to repository
}

Output:

{
  "repoPath": "/path/to/repo",
  "summary": {
    "totalSourceFiles": 156,
    "totalTestFiles": 98,
    "testedFiles": 102,
    "coverageRatio": 65.38
  },
  "coverage": {
    "src/services/auth.ts": ["src/services/auth.test.ts"],
    "src/utils/helper.ts": ["src/utils/helper.spec.ts"]
  },
  "missingTests": [
    "src/api/legacy.ts",
    "src/utils/old-helper.ts"
  ],
  "recommendations": [
    "️  Test coverage is below 80%. Consider adding tests for remaining files.",
…

Use Cases

1. Pre-Refactoring Analysis

Before refactoring, identify: