👁 Tech Debt MCP

Tech Debt MCP Server

👁 npm version
👁 Add to MCP
👁 SQALE Rating
👁 CodeQL
👁 Documentation

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

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

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

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

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: 👁 npm version
  
• 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