TechDebtMCP

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 | vardump, printr, die/exit, dynamic code execution, error suppression |

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

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

/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 and open it with Claude for macOS or Windows.

To build the bundle locally:

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

{
  "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

Every tool declares a tool annotation — 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: 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:

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:

{
  "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.

{
  "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
• Source: PierreJanineh/TechDebtMCP
• License: MIT
• Homepage: https://pierrejanineh.github.io/TechDebtMCP/

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