Tech Debt MCP Server

A Model Context Protocol (MCP) server for analyzing technical debt across multiple programming languages. Designed to integrate with GitHub Copilot and other MCP-compatible tools.

Built with Vibe Coding - This project was developed using AI-assisted "vibe coding" techniques, leveraging GitHub Copilot to rapidly prototype and iterate on features while maintaining code quality and test coverage.

Quality Assurance - This project practices what it preaches! Tech Debt MCP maintains an A rating (3.4% debt ratio) by regularly scanning itself and following strict code quality standards. See Code Quality for details.

Features

• Multi-language support: JavaScript, TypeScript, Python, Java, Swift, Kotlin, Objective-C, C++, C, C#, Go, Rust, Ruby, PHP
• Comprehensive analysis: Detects various types of tech debt including code quality issues, security vulnerabilities, and maintainability problems
• SQALE Metrics: Calculate technical debt with SQALE rating system (A-E scale)
• SwiftUI Analysis: Specialized checks for SwiftUI patterns, state management, memory leaks, view nesting, and concurrency issues
• Custom Rules: Define your own pattern-based checks with regex support
• Dependency Analysis: Parse package manifests across 10 ecosystems (npm, pip, Maven/Gradle, Cargo, Go Modules, Composer, Bundler, NuGet, C/C++, Swift)
• Inline Suppression: Suppress false positives with // techdebt-ignore-next-line or block comments
• Config Validation: Validate .techdebtrc.json configuration files for schema correctness
• Actionable recommendations: Provides prioritized suggestions for addressing technical debt
• Flexible filtering: Filter results by severity, category, or language

Supported Languages

| Language | Extensions | Key Checks | | ----------- | --------------------- | ---------------------------------------------------------------------------------- | | JavaScript | .js, .mjs, .cjs, .jsx | console.log, debugger, eslint-disable, eval, var usage | | TypeScript | .ts, .tsx, .mts, .cts | any type, @ts-ignore, non-null assertions, type assertions | | Python | .py, .pyw, .pyi | bare except, print statements, global usage, eval/exec | | Java | .java | System.out, printStackTrace, empty catch, @SuppressWarnings | | Swift | .swift | force unwrap (!), force cast (as!), force try, retain cycles, SwiftUI patterns | | Kotlin | .kt, .kts | !!, lateinit abuse, @Suppress, unchecked casts | | Objective-C | .m, .mm, .h | NSLog, retain cycles, deprecated methods, massive view controllers | | C++ | .cpp, .cc, .hpp, .h | raw pointers, C-style casts, goto, using namespace std | | C | .c, .h | malloc without free, goto, unsafe functions, null checks | | C# | .cs | Console.WriteLine, async void, empty catch, dispose pattern | | Go | .go | ignored errors, blank imports, fmt.Print, panic, global variables | | Rust | .rs | unwrap, expect, unsafe, allow attributes, panic, println | | Ruby | .rb | puts, binding.pry, rubocop disable, eval, global variables | | PHP | .php | var_dump, print_r, die/exit, eval, error suppression |

Installation

<details> <summary><img src="https://img.shields.io/badge/VS_Code-Install%20Server-007ACC?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTIzLjE1IDIuNTg3IDE4LjIxLjIxYTEuNDk0IDEuNDk0IDAgMCAwLTEuNzA1LjI5bC05LjQ2IDguNjMtNC4xMi0zLjEyOGEuOTk5Ljk5OSAwIDAgMC0xLjI3Ni4wNTdMLjMyNyA3LjI2MUExIDEgMCAwIDAgMCA4LjA2OGwzLjU5MiAzLjI5M0wwIDEzLjYxNmExIDEgMCAwIDAgLjMyNy44MDdsMS4zMTEgMS4zMTFhLjk5OS45OTkgMCAwIDAgMS4yNzYuMDU3bDQuMTItMy4xMjggOS40NiA4LjYzYTEuNDkyIDEuNDkyIDAgMCAwIDEuNzA0LjI5bDQuOTQyLTIuMzc3QTEuNSAxLjUgMCAwIDAgMjQgMTguMDE0VjUuOTg2YTEuNSAxLjUgMCAwIDAtLjg1LTEuMzk5ek0xOC41IDE2LjEyIDkuNDEgMTEuMzYxbDkuMDktNC43NTh6IiBmaWxsPSIjZmZmIi8+PC9zdmc+" alt="VS Code: Install Server"></summary>

One-Click Install

VS Code (via Terminal):

code --add-mcp '{"name":"tech-debt-mcp","command":"npx","args":["-y","tech-debt-mcp@latest"]}'

</details> <details> <summary><img src="https://img.shields.io/badge/Cursor-Install%20Server-26251E?logo=cursor&logoColor=F7F7F4" alt="Cursor: Install Server"></summary>

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=tech-debt-mcp&config=eyJjb21tYW5kIjoibnB4IC15IHRlY2gtZGVidC1tY3BAbGF0ZXN0In0=">One-Click Install</a>

Cursor (via Terminal):

cursor --add-mcp '{"name":"tech-debt-mcp","command":"npx -y tech-debt-mcp@latest"}'

</details> <details> <summary><img src="https://img.shields.io/badge/Claude-Install%20Server-d97757?logo=Claude&logoColor=f5f5f5" alt="Claude: Install Server"></summary>

Claude Code (via Terminal):

claude mcp add tech-debt-mcp -- npx -y tech-debt-mcp@latest

Claude Desktop — add to your claude_desktop_config.json:

{
  "mcpServers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

</details> <details> <summary><img src="https://img.shields.io/badge/Windsurf-Install%20Server-0B100F?logo=Windsurf&logoColor=f5f5f5" alt="Windsurf: Install Server"></summary>

Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

</details> <details> <summary><img src="https://img.shields.io/badge/JetBrains-Install%20Server-FF0007?logo=jetbrains&logoColor=f5f5f5" alt="JetBrains: Install Server"></summary>

Via AI Assistant — open Settings > Tools > AI Assistant > Model Context Protocol (MCP), click +, select As JSON, and paste:

{
  "mcpServers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

</details> <details> <summary><img src="https://img.shields.io/badge/Xcode-Install%20Server-147EFB?logo=xcode&logoColor=f5f5f5" alt="Xcode: Install Server"></summary>

Via GitHub Copilot for Xcode — open Settings > MCP tab > Edit Config (mcp.json):

{
  "servers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

</details>

Manual Setup

Add to your MCP client config:

{
  "mcpServers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

Usage

Start the MCP server:

tech-debt-mcp

Or for development:

npm run dev

Available Tools

analyze_project

Analyze an entire project for technical debt.

Parameters:

• path (required): Absolute path to the project root
• languages (optional): Array of languages to analyze
• categories (optional): Filter by debt categories
• severity (optional): Minimum severity level (low, medium, high, critical)
• maxFiles (optional): Maximum files to analyze

analyze_file

Analyze a single file for technical debt.

Parameters:

• path (required): Absolute path to the file

get_debt_summary

Get a quick summary of technical debt in a project.

Parameters:

• path (required): Absolute path to the project root

get_sqale_metrics

Get SQALE technical debt metrics including remediation time, debt ratio, and rating.

Parameters:

• path (required): Absolute path to the project root
• developmentTime (optional): Estimated development time in hours (for debt ratio calculation)

Output includes:

• SQALE rating (A-E) with star visualization
• Total remediation time in human-readable format
• Debt ratio (if development time provided)
• Breakdown by severity (Critical, High, Medium, Low)
• Breakdown by category (code-quality, security, maintainability, etc.)

Example:

get_sqale_metrics --path=/path/to/project --developmentTime=2080

Returns:

# SQALE Technical Debt Metrics

**Overall Rating:** B ⭐⭐⭐⭐
**Total Remediation Time:** 4 hours 30 minutes
**Debt Ratio:** 8.5%

## Breakdown by Severity
| Severity | Time |
|----------|------|
| Critical | 30m |
| High | 1h 45m |
| Medium | 2h |
| Low | 15m |

list_supported_languages

List all supported programming languages with their checks.

get_recommendations

Get prioritized recommendations for addressing technical debt.

Parameters:

• path (required): Absolute path to the project root
• limit (optional): Maximum recommendations to return

get_issues_by_severity

Get all issues of a specific severity level.

Parameters:

• path (required): Absolute path to the project root
• severity (required): low, medium, high, or critical

get_issues_by_category

Get all issues of a specific category.

Parameters:

• path (required): Absolute path to the project root
• category (required): dep