Tech Debt MCP Server

16 Tools · 2 Resources · 14 Languages · 10 Dependency Ecosystems

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

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

Related MCP server: project-advisors-mcp

Supported Languages

Installation

One-Click Install

VS Code (via Terminal):

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

One-Click Install

Cursor (via Terminal):

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

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"]
    }
  }
}

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

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

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"]
    }
  }
}

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"]
    }
  }
}

Manual Setup

Add to your MCP client config:

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

For development: npm run dev

Tools

analyze_project

Analyze an entire project for technical debt.

• 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.

• path (required): Absolute path to the file

get_debt_summary

Get a quick summary of technical debt in a project.

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

get_sqale_metrics

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

• 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, debt ratio, and breakdowns by severity and category.

get_recommendations

Get prioritized recommendations for addressing technical debt.

• 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.

• 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.

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

• category (required): dependency, code-quality, architecture, documentation, testing, security, performance, or maintainability

list_supported_languages

List all supported programming languages with their checks. No parameters.

add_custom_rule

Add a custom pattern-based tech debt rule.

• id (required): Unique identifier for the rule

• pattern (required): Regex pattern to match

• message (required): Issue title/message

• severity (required): low, medium, high, or critical

• category (required): One of the debt categories

• suggestion (optional): How to fix the issue

• languages (optional): Apply only to specific languages

• flags (optional): Regex flags (g, i, m, s, etc.)

Example custom rules:

[
  {
    "id": "no-magic-numbers",
    "pattern": "=\\s*\\d{3,}",
    "severity": "medium",
    "category": "maintainability",
    "message": "Magic number detected",
    "suggestion": "Extract to named constant"
  },
  {
    "id": "forbidden-library",
    "pattern": "import.*moment.*from",
    "severity": "medium",
    "category": "dependency",
    "message": "moment.js is deprecated",
    "suggestion": "Use native Date or date-fns instead",
    "languages": ["javascript", "typescript"]
  }
]

remove_custom_rule

Remove a custom rule by ID.

• id (required): ID of the rule to remove

list_custom_rules

List all active custom rules with their statistics. No parameters.

execute_custom_rules

Run all custom rules against code or a file.

• path (optional): Path to the file to analyze

• code (optional): Code content to analyze directly

• language (optional): Programming language for filtering rules

Either path or code must be provided.

validate_custom_pattern

Validate a custom pattern before adding it as a rule.

• id (required): Unique identifier for the rule

• pattern (required): Regex pattern to validate

• message (required): Issue title/message

• severity (required): low, medium, high, or critical

• category (required): One of the debt categories

check_dependencies

Scan a project for package manifests and return a structured dependency report.

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

• includeDev (optional): boolean (default: true) — include dev/test dependencies

Detects manifests for npm, pip, Maven/Gradle, Cargo, Go Modules, Composer, Bundler, NuGet, C/C++, and Swift Package Manager. Separates production vs development dependencies and reports files that failed to parse.

validate_config

Validate a .techdebtrc.json configuration file for schema correctness.

• path (required): Absolute path to the project root directory or directly to a .techdebtrc.json file

get_vulnerability_report

Generate an offline dependency inventory for vulnerability review. Lists all dependencies by ecosystem in a tabular format. See ROADMAP.md for planned online CVE lookup.

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

• includeDev (optional): boolean (default: false) — include dev dependencies in the report

Resources

Configuration

Create a .techdebtrc.json file in your project root:

{
  "ignore": ["vendor/**", "generated/**"],
  "rules": {
    "maxFileLines": 500,
    "maxFunctionLines": 50,
    "maxComplexity": 10,
    "maxNestingDepth": 4
  },
  "severity": {
    "todo-comment": "low",
    "console-log": "medium"
  },
  "ruleExclusions": {
    "debugger": ["**/src/analyzers/**"],
    "ts-ignore": ["**/src/analyzers/**"]
  },
  "customPatterns": [
    {
      "id": "no-console-log",
      "pattern": "console\\.log",
      "severity": "low",
      "category": "code-quality",
      "message": "Remove console.log() statements",
      "suggestion": "Use proper logging library instead",
      "languages": ["javascript", "typescript"]
    }
  ]
}

Rule Exclusions

Use ruleExclusions to suppress specific rules for files matching glob patterns. Patterns use forward slashes (/) on all platforms. Use **/ prefixed patterns (e.g., **/src/analyzers/**) for reliable matching regardless of path format.

Inline Suppression

Suppress specific issues directly in source code. Both // and # comment prefixes are supported across all languages.

Single-line — suppresses the next line:

// techdebt-ignore-next-line debugger
debugger; // only the 'debugger' rule is suppressed

# techdebt-ignore-next-line print-statement
print("debug output")  # will not be reported

Block — suppresses all lines between start and end:

// techdebt-ignore-start ts-ignore
issues.push(...this.checkPattern(filePath, content, /@ts-ignore/g, { ... }));
// techdebt-ignore-end ts-ignore

Without a rule name, all rules are suppressed. Blocks can be nested. Suppression comments must appear on their own line.

SQALE Metrics

Tech Debt MCP uses SQALE methodology to quantify technical debt:

Effort-to-time mapping: trivial (≤5m) · small (5-30m) · medium (30m-2h) · large (2-4h) · xlarge (4h+)

SwiftUI Analysis

14 specialized checks for SwiftUI apps covering state management (excessive @State, @ObservedObject misuse, environment value safety), memory & lifecycle (Combine retain cycles, timer cleanup, task cancellation, closure retain cycles), performance (missing .id() modifiers, expensive body calculations, deep nesting, GeometryReader misuse), and best practices (AnyView type erasure, deprecated NavigationLink, main thread safety).

State Management Issues

• Excessive @State Variables - Detects views with >5 @State variables that should use a ViewModel

• @ObservedObject Misuse - Flags @ObservedObject with initialization (should use @StateObject)

• Environment Value Safety - Detects force unwrapping of @Environment values

Memory & Lifecycle

• Combine Circular References - Finds missing [weak self] in Combine sinks

• Missing Timer Cleanup - Detects Timers without cleanup in onDisappear

• Missing Task Cancellation - Flags async Tasks without cancellation handling

• Retain Cycles in Closures - Detects self captures in onChange/onReceive without [weak self]

Performance & View Hierarchy

• Missing .id() Modifiers - Detects ForEach without stable identifiers

• Expensive View Body Calculations - Flags reduce/sort/filter in view bodies

• Deep View Nesting - Warns when nesting depth exceeds 6 levels

• GeometryReader Misuse - Detects GeometryReader at view root

SwiftUI Best Practices

• AnyView Type Erasure - Suggests using generics or @ViewBuilder instead

• Deprecated NavigationLink - Flags old-style NavigationLink patterns

• Main Thread Safety - Ensures UI updates happen on main thread

Example Issues Detected

// Excessive @State - should use ViewModel
struct UserView: View {
  @State private var firstName = ""
  @State private var lastName = ""
  @State private var email = ""
  @State private var phone = ""
  @State private var address = ""
  @State private var city = ""  // 6+ @State variables!
}

// @ObservedObject with initialization
struct ContentView: View {
  @ObservedObject var viewModel = UserViewModel()  // Should be @StateObject!
}

// Missing Timer cleanup
struct TimerView: View {
  var body: some View {
    Text("Hello")
      .onAppear {
        Timer.scheduledTimer(...)  // Missing .onDisappear cleanup!
      }
  }
}

// Retain cycle in Combine
publisher
  .sink { value in
    self.updateUI(value)  // Missing [weak self]!
  }

Example Output

# Tech Debt Analysis Report

## Health Score: 72/100

### Issues by Severity
| Severity | Count |
|----------|-------|
| Critical | 2 |
| High | 15 |
| Medium | 45 |
| Low | 120 |

## Top Recommendations

1. **Address Critical Issues Immediately**
   Fix 2 critical security issues.

2. **Clean Up TODO/FIXME Comments**
   Found 45 TODO comments - consider creating tracked issues.

Code Quality

Tech Debt MCP practices what it preaches — built with AI-assisted vibe coding, it maintains an A rating by regularly scanning itself.

Self-Scan Results (March 2026)

• SQALE Rating: A (Excellent)

• Debt Ratio: 4.6% (Target: <5%)

• Total Issues: 118 (0 critical, 12 high, 49 medium, 57 low)

• Remediation Time: ~96 hours

• Health Score: 42.4/100

Issue count increased from 81 to 118 due to wider scan scope in v2.0.1 (more files analyzed), not regression. See TECH_DEBT_SCAN.md for full results.

Development

npm install       # Install dependencies
npm run build     # Compile TypeScript
npm run dev       # Run with ts-node
npm run watch     # Watch mode
npm test          # Run tests

Documentation

• ARCHITECTURE.md - System architecture and design patterns

• ROADMAP.md - Development phases and future enhancements

• CONTRIBUTING.md - Contribution guidelines

• CHANGELOG.md - Version history and changes

• RELEASE.md - Release process and versioning guide

• TECH_DEBT_SCAN.md - Self-scan results with before/after comparison

• CODE_OF_CONDUCT.md - Community standards

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines and CODE_OF_CONDUCT.md for our community standards.

Releases

• Latest:

• Releases: GitHub Releases

• Roadmap: See ROADMAP.md for planned features

License

MIT