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.",
    " High priority: Add tests for 23 files in critical directories"
  ]
}

Use Cases

1. Pre-Refactoring Analysis

Before refactoring, identify:

• High complexity files (complexity > 10)
• High churn files (commits > 10)
• Files missing tests

Strategy: Refactor high-complexity, high-churn files first.

2. Code Review Preparation

Analyze changed files:

What's the complexity of the files I changed in the last commit?

3. Test Coverage Improvement

Find critical files without tests:

Which files in src/services/ are missing tests?

4. Technical Debt Identification

Combine metrics to find problematic files:

• High complexity + High churn + Missing tests = Technical debt hot spot

5. Onboarding New Developers

Show new team members:

• Most frequently changed files
• Core files with good health scores
• Areas needing test coverage

Health Score Interpretation

| Score | Health | Action | |-------|--------|--------| | 90-100 | Excellent | Maintain current quality | | 70-89 | Good | Minor improvements recommended | | 50-69 | Fair | Consider refactoring | | 30-49 | Poor | Refactoring needed | | 0-29 | Critical | Immediate attention required |

️ Architecture

Technology Stack

• TypeScript - Type-safe implementation
• @modelcontextprotocol/sdk - MCP server framework
• glob - File pattern matching
• simple-git - Git operations
• zod - Runtime type validation

Project Structure

project-health-auditor/
├── servers/
│   └── code-metrics.ts        # MCP server with 4 tools
├── tests/
│   └── code-metrics.test.ts   # Comprehensive tests
├── .claude-plugin/
│   └── plugin.json            # Plugin metadata
├── .mcp.json                  # MCP server configuration
├── package.json               # Dependencies
├── tsconfig.json              # TypeScript config
└── README.md                  # This file

Development

Build

npm run build

Test

npm test              # Run tests
npm run test:ci       # CI mode (no watch)

Type Check

npm run typecheck

Run Locally

npm run dev

Metrics Explained

Cyclomatic Complexity

Measures the number of independent paths through code:

• 1-10: Simple, low risk
• 11-20: Moderate complexity
• 21-50: High complexity, hard to test
• 50+: Very high risk, needs refactoring

Calculation: Count of control flow keywords (if, for, while, switch, &&, ||, ?) + 1

Git Churn

Frequency of file changes:

• High churn (>10 commits): Hot spot, may need stabilization
• Medium churn (5-10): Normal development activity
• Low churn (<5): Stable or new file

Why it matters: High churn + High complexity = Technical debt

Test Coverage Ratio

Percentage of source files with corresponding tests:

• 80-100%: Excellent
• 60-79%: Good
• 40-59%: Fair
• <40%: Poor

Contributing

This plugin is part of the Claude Code Plugins marketplace.

Report Issues

https://github.com/jeremylongshore/claude-code-plugins/issues

Suggest Features

Open an issue with the enhancement label.

License

MIT License - see LICENSE file

Credits

Built by: Intent Solutions IO Website: https://intentsolutions.io Email: [email protected]

Part of the Claude Code Plugins Marketplace

Related Plugins

• conversational-api-debugger - API debugging with OpenAPI specs
• test-coverage-booster - AI-powered test generation
• performance-profiler - Full-stack performance analysis

** Generated with Claude Code** Co-Authored-By: Claude [email protected]