Code Health MCP Server

A Model Context Protocol (MCP) server that provides comprehensive code quality analysis through quantitative metrics and trend analysis. Supports C#, Python, and TypeScript codebases with historical tracking and refactoring risk prediction.

Features

Core Analysis

• File Analysis: Analyze individual files for readability, maintainability, and complexity metrics
• Repository Analysis: Batch analyze entire repositories with intelligent caching
• Multi-Language Support: Comprehensive support for TypeScript, JavaScript, Python, and C#

Advanced Capabilities

• Historical Trends: Track complexity changes over time using git history (automatically builds cache on first request)
• Risk Prediction: Predict files likely to need refactoring based on trend analysis
• Dependency Analysis: Analyze dependency relationships, coupling, and circular dependencies
• Performance Optimized: Handles repositories with 100k+ lines of code efficiently
• Smart Caching: Automatically populates historical data cache when needed - no manual setup required

Metrics Provided

• Readability scores (identifier entropy, comment ratio, line length)
• Maintainability scores (cyclomatic complexity, coupling, cohesion)
• Nesting depth and code structure analysis
• Dependency fan-in/fan-out metrics
• Git churn and change frequency
• Refactoring risk scores with explanations

Quick Start

Installation

# No installation needed! Use npx to run directly:
npx code-health-mcp

# Or install globally if you prefer:
npm install -g code-health-mcp

Note: When using npx in your MCP configuration, the package is automatically downloaded and cached. No manual installation required!

MCP Client Configuration

For VS Code (GitHub Copilot)

Prerequisites: VS Code 1.96.0+, GitHub Copilot, and GitHub Copilot Chat extensions

Setup:

1. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
2. Type: "MCP: Add Server"
3. Select "npm"
4. Enter package: code-health-mcp
5. Enter name: code-health
6. Restart VS Code

Use @code-health in Copilot Chat. See VS Code Setup Guide for more details.

For Claude Desktop

Add to your Claude Desktop configuration:

macOS/Linux: ~/.config/claude/config.json
Windows: %APPDATA%\Claude\config.json

{
  "mcpServers": {
    "code-health": {
      "command": "npx",
      "args": ["code-health-mcp"]
    }
  }
}

For Other MCP Clients

The server uses stdio transport and works with any MCP-compatible client:

npx code-health-mcp

Basic Usage

Once configured, use natural language with your MCP client:

Analyze the file src/index.ts for code quality metrics

Show me which files in this repository are at highest risk of needing refactoring

What are the complexity trends for src/server.ts over the last 50 commits?

Available Tools

The server exposes five MCP tools:

| Tool | Description | Use Case | |------|-------------|----------| | analyze_file | Analyze a single source file | Get detailed metrics for one file | | analyze_repository | Batch analyze entire repository | Get overview of codebase health | | get_complexity_trends | Retrieve historical complexity data | Track quality over time (auto-builds cache on first use) | | predict_refactor_risk | Get refactoring risk predictions | Prioritize technical debt | | get_dependency_graph | Analyze dependency relationships | Understand coupling and architecture |

Documentation

Getting Started

• Quick Start Guide - Get running in 5 minutes
• Installation Guide - Detailed installation instructions
• Configuration Guide - Configure server settings
• Deployment Guide - Deploy in various environments

Reference

• Package Information - Package details and publishing
• Error Handling - Error handling patterns and recovery

Development

Prerequisites

• Node.js >= 18.0.0
• npm >= 8.0.0
• Git (for historical analysis features)

Setup

# Clone the repository
git clone https://github.com/nagavitalp/code-health-mcp.git
cd code-health-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Available Scripts

npm run build        # Build TypeScript to JavaScript
npm run build:prod   # Production build (no source maps)
npm run dev          # Run in development mode with tsx
npm run start        # Run the built server
npm run watch        # Watch mode for development
npm run clean        # Clean build artifacts
npm run test         # Run tests
npm run lint         # Type check without emitting
npm run validate     # Run lint and tests

Project Structure

codebase-health-mcp/
├── src/
│   ├── analysis/          # Code analysis engine
│   │   ├── parsers/       # Language-specific parsers
│   │   ├── metrics/       # Metric calculation
│   │   └── __tests__/     # Tests
│   ├── server.ts          # Main MCP server
│   ├── server-config.ts   # Configuration management
│   ├── logger.ts          # Logging utilities
│   ├── error-handler.ts   # Error handling
│   └── index.ts           # Entry point
├── docs/                  # Documentation
├── dist/                  # Built output
└── package.json

Language Support

TypeScript/JavaScript

• Full AST analysis using TypeScript compiler API
• ES modules and CommonJS support
• Modern JavaScript features
• Type definitions and interfaces

Python

• AST-based analysis using Python's ast module
• Python 3.x syntax support
• Class, function, and module analysis
• Import and package dependency tracking

C#

• Syntax tree parsing for .NET code
• Support for modern C# features
• Class, method, and namespace analysis
• Using statements and assembly references

Performance

• Analysis Speed: < 5 seconds for repositories up to 100k lines
• Memory Usage: < 500MB for large repository analysis
• Caching: Intelligent caching avoids recomputing unchanged files
• Scalability: Handles large monorepos efficiently

Requirements

Required

• Node.js >= 18.0.0
• Git (for historical analysis)

Optional

• .NET SDK (for enhanced C# analysis)
• Python 3.x (for enhanced Python analysis)

Configuration

Environment Variables

Configure via environment variables:

NODE_ENV=production          # Environment mode
LOG_LEVEL=info              # Logging verbosity
CACHE_DIR=.cache            # Cache directory
GIT_HISTORY_DEPTH=100       # Commits to analyze
ENABLE_CACHE=true           # Enable caching

Optional Configuration File

Create code-health.config.json in your project root to customize analysis behavior:

# Copy the example configuration
cp node_modules/code-health-mcp/code-health.config.example.json code-health.config.json

# Edit to customize thresholds and weights

Example configuration:

{
  "complexityThresholds": {
    "cyclomaticComplexity": {
      "low": 5,
      "medium": 10,
      "high": 20
    }
  },
  "riskFactorWeights": {
    "complexityTrend": 0.4,
    "churnFrequency": 0.25
  }
}

Note: code-health.config.json is for your local use only and should be added to .gitignore.

See Configuration Guide for detailed options.

Troubleshooting

Common Issues

Server not starting: Verify Node.js version >= 18.0.0

node --version

Permission errors: Use npx or configure npm prefix

npx codebase-health-mcp

Git not found: Install Git for historical analysis

git --version

See Installation Guide for more troubleshooting.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Documentation: docs/
• Discussions: GitHub Discussions

Acknowledgments

Built with:

• Model Context Protocol SDK
• TypeScript
• simple-git
• SQLite3

Made with ❤️ for better code quality