io.github.PierreJanineh/tech-debt-mcp

Official

by PierreJanineh · TypeScript

MCP Server for analyzing technical debt across multiple programming languages

This MCP server provides capabilities for analyzing technical debt across multiple programming languages. It is described as an “MCP Server for analyzing technical debt,” with the scope explicitly spanning more than one language. The server is identified by the slug io-github-pierrejanineh-tech-debt-mcp and name io.github.PierreJanineh/tech-debt-mcp.

🛠️ Key Features

Analyzes technical debt
Supports analysis across multiple programming languages

🚀 Use Cases

Assess technical debt in heterogeneous codebases
Compare or evaluate technical debt across different programming languages

⚡ Developer Benefits

Centralizes technical-debt analysis in an MCP server for multi-language projects

⚠️ Limitations

Detailed tooling, supported languages, and specific analysis methods are not provided in the available source data

Topics

ai-toolscode-analysiscopilotdeveloper-toolsengineering-productivityllmmcpmodel-context-protocolstatic-analysistechnical-debt

README.md28 KBView on GitHub

Tech Debt MCP

Tech Debt MCP Server

SQALE Rating

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

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:

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

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

code

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:

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

typescript

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

python

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

Block — suppresses all lines between start and end:

typescript

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

json

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

Rating	Debt Ratio	Quality
A	≤5%	Excellent
B	6-10%	Good
C	11-20%	Fair
D	21-50%	Poor
E	>50%	Critical

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

View all SwiftUI checks with examples

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

swift

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

code

# 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

bash

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

Install

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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