code-health-mcp
Integrates with GitHub Copilot in VS Code to analyze code quality metrics, track trends, and predict risks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@code-health-mcp Analyze file src/index.ts for code quality"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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-mcpNote: 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:
Press
Ctrl+Shift+P(orCmd+Shift+Pon macOS)Type: "MCP: Add Server"
Select "npm"
Enter package:
code-health-mcpEnter name:
code-healthRestart 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-mcpBasic Usage
Once configured, use natural language with your MCP client:
Analyze the file src/index.ts for code quality metricsShow me which files in this repository are at highest risk of needing refactoringWhat 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 a single source file | Get detailed metrics for one file |
| Batch analyze entire repository | Get overview of codebase health |
| Retrieve historical complexity data | Track quality over time (auto-builds cache on first use) |
| Get refactoring risk predictions | Prioritize technical debt |
| 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 devAvailable 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 testsProject 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.jsonLanguage 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 cachingOptional 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 weightsExample 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 --versionPermission errors: Use npx or configure npm prefix
npx codebase-health-mcpGit not found: Install Git for historical analysis
git --versionSee Installation Guide for more troubleshooting.
Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Submit a pull request
License
MIT License - see LICENSE file for details
Support
Issues: GitHub Issues
Documentation: docs/
Discussions: GitHub Discussions
Acknowledgments
Built with:
Made with ❤️ for better code quality
Available Tools
5 toolsanalyze_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_complexity_trendsA
Get historical complexity trends for files over time using git history
Inputs: filePath (required), dateRange.
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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Enterprise code intelligence for M&A, security audits, and tech debt. Hosted server with 200k free.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Related MCP Servers
- AlicenseAqualityDmaintenanceAnalyzes codebases to generate dependency graphs and architectural insights across multiple programming languages, helping developers understand code structure and validate against architectural rules.649 npm20MIT
- AlicenseAqualityDmaintenanceEnables comprehensive code analysis including quality assessment, security vulnerability detection, refactoring suggestions, complexity calculations, and automatic documentation generation for multiple programming languages.59 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides 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
- FlicenseNot gradedqualityDmaintenanceAI-powered code quality analysis that detects security issues, bugs, code smells, and performance problems across multiple languages.4-