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

• 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

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

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

get_sqale_metrics returns a SQALE rating (A-E) with star visualization, total remediation time, debt ratio, and breakdowns by severity and 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.

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

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 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 file extensions (beyond the defaults) to attribute to this language.

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.

Example Custom Rules

Scope note: customPatterns defined in .techdebtrc.json are applied only by analyze_project, which loads the project config before scanning. analyze_file invokes the language analyzer directly without loading .techdebtrc.json, so config-defined patterns are not applied on that path. Use add_custom_rule at runtime (or call execute_custom_rules directly) to run custom patterns against a single file.

Define patterns in .techdebtrc.json under customPatterns, or register them at runtime via the add_custom_rule MCP tool:

{
  "customPatterns": [
    {
      "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"]
    }
  ]
}

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. Internal refactors (e.g., nesting reduction in customRulesEngine.validatePattern via extracted helper — #146) are driven by self-scan findings.

Self-Scan Results (v2.0.2, April 2026)

• SQALE Rating: A (Excellent)

• Debt Score: 5/100 (Target: ≤5/100)

• Total Issues: 13 (0 critical, 0 high, 6 medium, 7 low)

• Remediation Time: 14 hours

• Health Score: 95/100

Down from 118 issues / 42.4 health in the v2.0.1 baseline after the v2.0.2 security hardening, ruleExclusions config, nesting refactors (#113, #118, #131, #146), and custom-rules handler extraction (#145). Remaining debt: 5 nesting hotspots (4 in server / core modules + 1 in eslint.config.mjs), 7 type-assertion usages at system boundaries, and 1 non-null assertion. See TECH_DEBT_SCAN.md for per-issue detail.

Development

npm install --include=dev --ignore-scripts  # Install dependencies (incl. devDependencies)
npm run typecheck  # Type-check without emitting output
npm run lint       # Lint source files
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

• PRIVACY.md - Privacy policy (also hosted at https://pierrejanineh.github.io/TechDebtMCP/privacy)

• plugin/README.md - Plugin-user-facing docs (install, example transcripts, security posture)

Privacy

Tech Debt MCP runs entirely on your machine. Once installed, it reads files you pass it, returns issues to your MCP client over the local stdio transport, and does nothing else — the server itself makes no outbound network calls, has no telemetry, no analytics, and uses no third-party services. Installation via npm/npx does contact the npm registry as standard package-manager behavior; the MCPB bundle ships pre-installed and needs no further network access. See PRIVACY.md or the hosted policy at https://pierrejanineh.github.io/TechDebtMCP/privacy for details.

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

• Security: escapeRegExp() (src/utils/regexUtils.ts) must be used when interpolating captured strings into new RegExp() — see issue #128; handler output uses basename() / getRelativePath() to prevent absolute filesystem path leakage in intentional messages, and raw err.message strings from filesystem operations are sanitized before being returned to clients — see issue #129

License

MIT