TechDebtMCP

<p align="center">
  <img src="mcpb/icon.png" alt="Tech Debt MCP" width="160" height="160" />
</p>

<h1 align="center">Tech Debt MCP Server</h1>

[![npm version](https://img.shields.io/npm/v/tech-debt-mcp)](https://www.npmjs.com/package/tech-debt-mcp)
[![Add to MCP](https://img.shields.io/badge/MCP-Install_Server-6f42c1)](#installation)
[![SQALE Rating](https://img.shields.io/badge/SQALE-A_(0.7%25)-brightgreen)](#code-quality)
[![CodeQL](https://github.com/PierreJanineh/TechDebtMCP/actions/workflows/codeql.yml/badge.svg)](https://github.com/PierreJanineh/TechDebtMCP/actions/workflows/codeql.yml)
[![Documentation](https://img.shields.io/badge/docs-pierrejanineh.github.io%2FTechDebtMCP-4b5563)](https://pierrejanineh.github.io/TechDebtMCP/)

**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
- **Security hardened (v2.0.2)**: Path traversal prevention on all tool and resource path inputs, ReDoS-safe custom-rule regex validation, regex-injection escaping in SwiftUI checks, absolute-path sanitization in all error messages, and CodeQL SAST scanning on every push/PR

## Supported Languages

| Language    | Extensions            | Key Checks                                                                         |
| ----------- | --------------------- | ---------------------------------------------------------------------------------- |
| JavaScript  | .js, .mjs, .cjs, .jsx | console.log, debugger, eslint-disable, usage of dynamic code execution, 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, dynamic code execution                |
| 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, dynamic code execution, global variables       |
| PHP         | .php                  | var_dump, print_r, die/exit, dynamic code execution, 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](https://insiders.vscode.dev/redirect/mcp/install?name=tech-debt-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22tech-debt-mcp%40latest%22%5D%7D)**

**VS Code** (via Terminal):

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

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

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

**Claude Desktop** — add to your `claude_desktop_config.json`:

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

</details>

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

**Claude Code plugin** — add this repo's marketplace, then install the plugin:

```sh
/plugin marketplace add PierreJanineh/TechDebtMCP
/plugin install tech-debt-mcp@techdebtmcp
```

The plugin runs `npx -y tech-debt-mcp@latest` under the hood — no source bundling, always tracks the published npm release. See [`plugin/README.md`](plugin/README.md) for plugin-user-facing docs (install flow, example transcripts, security posture).

</details>

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

**Claude Desktop MCPB bundle** — single-click install with bundled `node_modules` (no `npx`, no internet required at runtime).

Download `tech-debt-mcp-<version>.mcpb` from the [latest GitHub Release](https://github.com/PierreJanineh/TechDebtMCP/releases/latest) and open it with Claude for macOS or Windows.

To build the bundle locally:

```sh
npm install --include=dev --ignore-scripts
npm run mcpb:pack
# -> mcpb/tech-debt-mcp-<version>.mcpb
```

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

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

```json
{
  "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`):

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

</details>

### Manual Setup

Add to your MCP client config:

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

For development: `npm run dev`

## Tools

Every tool declares a [tool annotation](https://modelcontextprotocol.io/specification/server/tools#tool-annotations) — `Read` tools are side-effect-free (`readOnlyHint: true`); `Write` tools mutate server session state (`destructiveHint: true`).

| Category | Tool | Type | Description |
|----------|------|------|-------------|
| **Analysis** | `analyze_project` | Read | Analyze entire project — filter by language, category, severity, maxFiles |
| | `analyze_file` | Read | Analyze a single file |
| | `get_debt_summary` | Read | Quick summary with health score and issue counts |
| | `get_sqale_metrics` | Read | SQALE rating, remediation time, debt ratio, breakdowns |
| **Filtering** | `get_recommendations` | Read | Prioritized fix suggestions (con