Skip to main content
Glama
code-health-mcp

code-health-mcp

by nagavitalp

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.

npm version Beta License: MIT Node.js Version

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

Related MCP server: Smart Code Reviewer

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

Reference

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

Acknowledgments

Built with:


Made with ❤️ for better code quality

Available Tools

5 tools
analyze_fileA

Analyze a single source code file for readability, maintainability, and complexity metrics

Inputs: filePath (required).

analyze_repositoryB

Perform batch analysis of an entire repository for code health metrics

Inputs: repositoryPath (required), filePatterns.

get_dependency_graphB

Analyze dependency relationships and identify highly coupled components

Inputs: repositoryPath (required), includeExternal.

predict_refactor_riskA

Predict which files are at risk of needing refactoring based on trends and metrics

Inputs: repositoryPath (required), riskThreshold.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct dimension of code health: single-file analysis, repository-wide analysis, historical trends, risk prediction, and dependency structure. There is no overlapping purpose or ambiguity between these five tools.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (analyze_file, analyze_repository, get_complexity_trends, predict_refactor_risk, get_dependency_graph). This makes the toolset highly predictable and easy to navigate.

    Tool Count5/5

    Five tools is well-scoped for a focused code health analysis server. Each tool covers a meaningful capability without redundancy or bloat, and the number is within the ideal 3–15 range.

    Completeness5/5

    The toolset covers the full analysis lifecycle: targeted file inspection, whole-repository analysis, historical trends, forward-looking risk prediction, and dependency coupling. For a read-only analysis domain, there are no obvious missing operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Analyzes codebases to generate dependency graphs and architectural insights across multiple programming languages, helping developers understand code structure and validate against architectural rules.
      6
      49 npm
      20
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables comprehensive code analysis including quality assessment, security vulnerability detection, refactoring suggestions, complexity calculations, and automatic documentation generation for multiple programming languages.
      5
      9 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides comprehensive codebase analysis including project structure evaluation, cross-language duplicate detection, microservices validation, and configuration optimization with AI-powered pattern learning that generates actionable improvement reports.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      AI-powered code quality analysis that detects security issues, bugs, code smells, and performance problems across multiple languages.
      4
      -