# TechDebtMCP

> MCP server for analyzing and managing technical debt in codebases via the Model Context Protocol

- **Type:** MCP server
- **Install:** `agentstack add mcp-pierrejanineh-techdebtmcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [PierreJanineh](https://agentstack.voostack.com/s/pierrejanineh)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [PierreJanineh](https://github.com/PierreJanineh)
- **Source:** https://github.com/PierreJanineh/TechDebtMCP
- **Website:** https://pierrejanineh.github.io/TechDebtMCP/

## Install

```sh
agentstack add mcp-pierrejanineh-techdebtmcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Tech Debt MCP Server

[](https://www.npmjs.com/package/tech-debt-mcp)
[](#installation)
[-brightgreen)](#code-quality)
[](https://github.com/PierreJanineh/TechDebtMCP/actions/workflows/codeql.yml)
[](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

**[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"]}'
```

**One-Click Install**

**Cursor** (via Terminal):

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

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

**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).

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

Download `tech-debt-mcp-.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-.mcpb
```

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

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

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

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

### 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 (configurable limit) |
| | `get_issues_by_severity` | Read | Issues filtered by severity level |
| | `get_issues_by_category` | Read | Issues filtered by debt category |
| | `list_supported_languages` | Read | All languages with their checks |
| **Custom Rules** | `add_custom_rule` | Write | Add regex-based tech debt rule |
| | `remove_custom_rule` | Write | Remove a custom rule by ID |
| | `list_session_custom_rules` | Read | List rules added via `add_custom_rule` this session (does not include `.techdebtrc.json` `customPatterns`) |
| | `execute_custom_rules` | Read | Run custom rules against code or file |
| | `validate_custom_pattern` | Read | Test a pattern before adding it |
| **Dependencies** | `check_dependencies` | Read | Scan package manifests across 10 ecosystems |
| | `get_vulnerability_report` | Read | Offline dependency inventory for CVE review |
| | `validate_config` | Read | Validate `.techdebtrc.json` schema |

**Debt categories used throughout:** `dependency` · `code-quality` · `architecture` · `documentation` · `testing` · `security` · `performance` · `maintainability`

Analysis — parameter reference

| Tool | Parameter | Type | Required | Constraints / default | Description |
|------|-----------|------|:--------:|----------------------|-------------|
| `analyze_project` | `path` | string | ✓ | absolute filesystem path | Project root directory |
| | `languages` | string[] | | | Filter to specific languages |
| | `categories` | string[] | | see categories above | Filter by debt categories |
| | `severity` | enum | | `low` / `medium` / `high` / `critical` | Minimum severity level |
| | `maxFiles` | integer | | min: 1 | Cap on files analyzed |
| `analyze_file` | `path` | string | ✓ | absolute filesystem path | File to analyze |
| `get_debt_summary` | `path` | string | ✓ | absolute filesystem path | Project root directory |
| `get_sqale_metrics` | `path` | string | ✓ | absolute filesystem path | Project root directory |
| | `developmentTime` | number | | hours | Estimated dev time for debt-ratio calc |

`get_sqale_metrics` returns a SQALE rating (A-E) with star visualization, total remediation time, debt ratio, and breakdowns by severity and category.

Filtering — parameter reference

| Tool | Parameter | Type | Required | Constraints / default | Description |
|------|-----------|------|:--------:|----------------------|-------------|
| `get_recommendations` | `path` | string | ✓ | absolute filesystem path | Project root directory |
| | `limit` | integer | | default: 5, min: 1 | Max recommendations to return |
| `get_issues_by_severity` | `path` | string | ✓ | absolute filesystem path | Project root directory |
| | `severity` | enum | ✓ | `low` / `medium` / `high` / `critical` | Severity to filter by |
| `get_issues_by_category` | `path` | string | ✓ | absolute filesystem path | Project root directory |
| | `category` | enum | ✓ | see categories above | Debt category to filter by |
| `list_supported_languages` | — | — | — | — | No parameters |

Custom Rules — parameter reference

| Tool | Parameter | Type | Required | Constraints / default | Description |
|------|-----------|------|:--------:|----------------------|-------------|
| `add_custom_rule` | `id` | string | ✓ | | Unique rule identifier |
| | `pattern` | string | ✓ | max 1,000 chars | Regex pattern to match |
| | `message` | string | ✓ | | Issue title/message |
| | `severity` | enum | ✓ | `low` / `medium` / `high` / `critical` | Severity level |
| | `category` | enum | ✓ | see categories above | Debt category |
| | `suggestion` | string | | | How to fix the issue |
| | `languages` | string[] | | | Restrict to specific languages |
| | `flags` | string | | allowed: `d g i m s u v y`; `u` / `v` mutually exclusive | Regex flags |
| `remove_custom_rule` | `id` | string | ✓ | | Rule ID to remove |
| `list_session_custom_rules` | — | — | — | — | No parameters. Renamed from `list_custom_rules` (TEC-51) to clarify scope: only session-registered rules. |
| `execute_custom_rules` | `path` | string | ◐ | absolute path, max 500,000 bytes | File to analyze |
| | `code` | string | ◐ | 1-500,000 chars | Source code to analyze directly |
| | `language` | string | | must be a supported language ID (same set as `list_supported_languages`) | Filter rules by language |
| `validate_custom_pattern` | `id` | string | ✓ | | Unique rule identifier |
| | `pattern` | string | ✓ | max 1,000 chars | Regex to validate |
| | `message` | string | ✓ | | Issue title/message |
| | `severity` | enum | ✓ | `low` / `medium` / `high` / `critical` | Severity level |
| | `category` | enum | ✓ | see categories above | Debt category |

◐ `execute_custom_rules` requires **either** `path` **or** `code`, not both required. An empty string `""` for `path` is treated the same as omitting the field.

Dependencies — parameter reference

| Tool | Parameter | Type | Required | Constraints / default | Description |
|------|-----------|------|:--------:|----------------------|-------------|
| `check_dependencies` | `path` | string | ✓ | absolute filesystem path | Project root directory |
| | `includeDev` | boolean | | default: `true` | Include dev/test dependencies |
| `get_vulnerability_report` | `path` | string | ✓ | absolute filesystem path | Project root directory |
| | `includeDev` | boolean | | default: `false` | Include dev dependencies |
| `validate_config` | `path` | string | ✓ | absolute filesystem path | Project root directory **or** direct path to `.techdebtrc.json` |

`check_dependencies` detects manifests for npm, pip, Maven/Gradle, Cargo, Go Modules, Composer, Bundler, NuGet, C/C++ (CMakeLists.txt, conanfile.txt/py, vcpkg.json), and Swift Package Manager. `get_vulnerability_report` produces an offline dependency inventory — see [ROADMAP.md](ROADMAP.md) for planned online CVE lookup.

## Resources

Two MCP resources expose read-only tech debt data as JSON. Both use [RFC 6570 URI templates](https://datatracker.ietf.org/doc/html/rfc6570): the `{+projectPath}` syntax is *reserved expansion*, which allows the variable to contain the `/` characters of an absolute filesystem path without percent-encoding.

| URI template | Description |
|--------------|-------------|
| `debt://summary/{+projectPath}` | Health score, debt score, issue counts, and SQALE metrics |
| `debt://issues/{+projectPath}` | Filterable list of all tech debt issues; supports `severity`, `category`, and `limit` query params |

**Concrete examples** — substitute `{+projectPath}` with an absolute path. Note the double slash: the template's trailing `/` plus the path's leading `/` produce `//`, which is valid URI syntax.

```
debt://summary//Users/you/projects/myapp
debt://issues//Users/you/projects/myapp
debt://issues//Users/you/projects/myapp?severity=high&limit=50
debt://issues//Users/you/projects/myapp?category=security
```

**Testing interactively** — the easiest way to exercise tools and resources is the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npm run build
npx @modelcontextprotocol/inspector node dist/index.js
```

Open the URL it prints, switch to the **Resources** tab, and read a template URI with your absolute project path.

## Configuration

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

```json
{
  "include": ["src/**", "lib/**"],
  "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"]
    }
  ]
}
```

### Language Overrides

Override rules, severity, or file extensions on a per-language basis using `languageOverrides`. Keys must be valid [supported language](#supported-languages) identifiers.

```json
{
  "languageOverrides": {
    "typescript": {
      "rules": {
        "maxFileLines": 800,
        "maxFunctionLines": 80
      },
      "severity": {
        "todo-comment": "high"
      }
    },
    "python": {
      "extensions": [".pyx"],
      "rules": {
        "maxComplexity": 15
      }
    }
  }
}
```

- **`rules`** — per-language thresholds (override the top-level `rules` for matching files).
- **`severity`** — per-language rule severity overrides.
- **`extensions`** — additional

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [PierreJanineh](https://github.com/PierreJanineh)
- **Source:** [PierreJanineh/TechDebtMCP](https://github.com/PierreJanineh/TechDebtMCP)
- **License:** MIT
- **Homepage:** https://pierrejanineh.github.io/TechDebtMCP/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-pierrejanineh-techdebtmcp
- Seller: https://agentstack.voostack.com/s/pierrejanineh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.