# 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](https://badge.fury.io/js/code-health-mcp.svg)](https://www.npmjs.com/package/code-health-mcp)
[![Beta](https://img.shields.io/badge/status-beta-yellow.svg)](https://github.com/nagavitalp/code-health-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)

## 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

```bash
# 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](./docs/VSCODE_SETUP.md) for more details.

#### For Claude Desktop

Add to your Claude Desktop configuration:

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

```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:

```bash
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](./docs/QUICK_START.md) - Get running in 5 minutes
- [Installation Guide](./docs/INSTALLATION.md) - Detailed installation instructions
- [Configuration Guide](./docs/CONFIGURATION.md) - Configure server settings
- [Deployment Guide](./docs/DEPLOYMENT.md) - Deploy in various environments

### Reference
- [Package Information](./docs/PACKAGE_INFO.md) - Package details and publishing
- [Error Handling](./docs/ERROR_HANDLING.md) - Error handling patterns and recovery

## Development

### Prerequisites
- Node.js >= 18.0.0
- npm >= 8.0.0
- Git (for historical analysis features)

### Setup

```bash
# 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

```bash
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:

```bash
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:

```bash
# 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:
```json
{
  "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](./docs/CONFIGURATION.md) for detailed options.

## Troubleshooting

### Common Issues

**Server not starting**: Verify Node.js version >= 18.0.0
```bash
node --version
```

**Permission errors**: Use npx or configure npm prefix
```bash
npx codebase-health-mcp
```

**Git not found**: Install Git for historical analysis
```bash
git --version
```

See [Installation Guide](./docs/INSTALLATION.md) 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](LICENSE) file for details

## Support

- **Issues**: [GitHub Issues](https://github.com/nagavitalp/code-health-mcp/issues)
- **Documentation**: [docs/](./docs/)
- **Discussions**: [GitHub Discussions](https://github.com/nagavitalp/code-health-mcp/discussions)

## Acknowledgments

Built with:
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- [TypeScript](https://www.typescriptlang.org/)
- [simple-git](https://github.com/steveukx/git-js)
- [SQLite3](https://github.com/TryGhost/node-sqlite3)

---

**Made with ❤️ for better code quality**