-brightgreen) A Model Context Protocol (MCP) server for analyzing technical debt across multiple programming languages. Designed to integrate with GitHub Copilot and other MCP-compatible tools. - 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
Add this skill
npx mdskills install PierreJanineh/techdebtmcpComprehensive multi-language technical debt analyzer with SQALE metrics, custom rules, and dependency parsing
1# Tech Debt MCP Server23[](https://www.npmjs.com/package/tech-debt-mcp)4[](#installation)5[-brightgreen)](#code-quality)67A Model Context Protocol (MCP) server for analyzing technical debt across multiple programming languages. Designed to integrate with GitHub Copilot and other MCP-compatible tools.89> **Built with Vibe Coding** - This project was developed using AI-assisted "vibe coding" techniques, leveraging GitHub Copilot to rapidly prototype and iterate on features while maintaining code quality and test coverage.10>11> **Quality Assurance** - This project practices what it preaches! Tech Debt MCP maintains an **A rating** (3.4% debt ratio) by regularly scanning itself and following strict code quality standards. See [Code Quality](#code-quality) for details.1213## Features1415- **Multi-language support**: JavaScript, TypeScript, Python, Java, Swift, Kotlin, Objective-C, C++, C, C#, Go, Rust, Ruby, PHP16- **Comprehensive analysis**: Detects various types of tech debt including code quality issues, security vulnerabilities, and maintainability problems17- **SQALE Metrics**: Calculate technical debt with SQALE rating system (A-E scale)18- **SwiftUI Analysis**: Specialized checks for SwiftUI patterns, state management, memory leaks, view nesting, and concurrency issues19- **Custom Rules**: Define your own pattern-based checks with regex support20- **Dependency Analysis**: Parse package manifests across 10 ecosystems (npm, pip, Maven/Gradle, Cargo, Go Modules, Composer, Bundler, NuGet, C/C++, Swift)21- **Config Validation**: Validate `.techdebtrc.json` configuration files for schema correctness22- **Actionable recommendations**: Provides prioritized suggestions for addressing technical debt23- **Flexible filtering**: Filter results by severity, category, or language2425## Supported Languages2627| Language | Extensions | Key Checks |28| ----------- | --------------------- | ---------------------------------------------------------------------------------- |29| JavaScript | .js, .mjs, .cjs, .jsx | console.log, debugger, eslint-disable, eval, var usage |30| TypeScript | .ts, .tsx, .mts, .cts | any type, @ts-ignore, non-null assertions, type assertions |31| Python | .py, .pyw, .pyi | bare except, print statements, global usage, eval/exec |32| Java | .java | System.out, printStackTrace, empty catch, @SuppressWarnings |33| Swift | .swift | force unwrap (!), force cast (as!), force try, retain cycles, **SwiftUI patterns** |34| Kotlin | .kt, .kts | !!, lateinit abuse, @Suppress, unchecked casts |35| Objective-C | .m, .mm, .h | NSLog, retain cycles, deprecated methods, massive view controllers |36| C++ | .cpp, .cc, .hpp, .h | raw pointers, C-style casts, goto, using namespace std |37| C | .c, .h | malloc without free, goto, unsafe functions, null checks |38| C# | .cs | Console.WriteLine, async void, empty catch, dispose pattern |39| Go | .go | ignored errors, blank imports, fmt.Print, panic, global variables |40| Rust | .rs | unwrap, expect, unsafe, allow attributes, panic, println |41| Ruby | .rb | puts, binding.pry, rubocop disable, eval, global variables |42| PHP | .php | var_dump, print_r, die/exit, eval, error suppression |4344## Installation4546<details>47<summary><img src="https://img.shields.io/badge/VS_Code-Install%20Server-007ACC?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTIzLjE1IDIuNTg3IDE4LjIxLjIxYTEuNDk0IDEuNDk0IDAgMCAwLTEuNzA1LjI5bC05LjQ2IDguNjMtNC4xMi0zLjEyOGEuOTk5Ljk5OSAwIDAgMC0xLjI3Ni4wNTdMLjMyNyA3LjI2MUExIDEgMCAwIDAgMCA4LjA2OGwzLjU5MiAzLjI5M0wwIDEzLjYxNmExIDEgMCAwIDAgLjMyNy44MDdsMS4zMTEgMS4zMTFhLjk5OS45OTkgMCAwIDAgMS4yNzYuMDU3bDQuMTItMy4xMjggOS40NiA4LjYzYTEuNDkyIDEuNDkyIDAgMCAwIDEuNzA0LjI5bDQuOTQyLTIuMzc3QTEuNSAxLjUgMCAwIDAgMjQgMTguMDE0VjUuOTg2YTEuNSAxLjUgMCAwIDAtLjg1LTEuMzk5ek0xOC41IDE2LjEyIDkuNDEgMTEuMzYxbDkuMDktNC43NTh6IiBmaWxsPSIjZmZmIi8+PC9zdmc+" alt="VS Code: Install Server"></summary>4849**[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)**5051**VS Code** (via Terminal):5253```sh54code --add-mcp '{"name":"tech-debt-mcp","command":"npx","args":["-y","tech-debt-mcp@latest"]}'55```5657</details>5859<details>60<summary><img src="https://img.shields.io/badge/Cursor-Install%20Server-26251E?logo=cursor&logoColor=F7F7F4" alt="Cursor: Install Server"></summary>6162**<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=tech-debt-mcp&config=eyJjb21tYW5kIjoibnB4IC15IHRlY2gtZGVidC1tY3BAbGF0ZXN0In0=">One-Click Install</a>**6364**Cursor** (via Terminal):6566```sh67cursor --add-mcp '{"name":"tech-debt-mcp","command":"npx -y tech-debt-mcp@latest"}'68```6970</details>7172<details>73<summary><img src="https://img.shields.io/badge/Claude-Install%20Server-d97757?logo=Claude&logoColor=f5f5f5" alt="Claude: Install Server"></summary>7475**Claude Code** (via Terminal):7677```sh78claude mcp add tech-debt-mcp -- npx -y tech-debt-mcp@latest79```8081**Claude Desktop** — add to your `claude_desktop_config.json`:8283```json84{85 "mcpServers": {86 "tech-debt-mcp": {87 "command": "npx",88 "args": ["-y", "tech-debt-mcp@latest"]89 }90 }91}92```9394</details>9596<details>97<summary><img src="https://img.shields.io/badge/Windsurf-Install%20Server-0B100F?logo=Windsurf&logoColor=f5f5f5" alt="Windsurf: Install Server"></summary>9899Add to your Windsurf MCP configuration (`~/.codeium/windsurf/mcp_config.json`):100101```json102{103 "mcpServers": {104 "tech-debt-mcp": {105 "command": "npx",106 "args": ["-y", "tech-debt-mcp@latest"]107 }108 }109}110```111112</details>113114<details>115<summary><img src="https://img.shields.io/badge/JetBrains-Install%20Server-FF0007?logo=jetbrains&logoColor=f5f5f5" alt="JetBrains: Install Server"></summary>116117Via **AI Assistant** — open **Settings > Tools > AI Assistant > Model Context Protocol (MCP)**, click **+**, select **As JSON**, and paste:118119```json120{121 "mcpServers": {122 "tech-debt-mcp": {123 "command": "npx",124 "args": ["-y", "tech-debt-mcp@latest"]125 }126 }127}128```129130</details>131132<details>133<summary><img src="https://img.shields.io/badge/Xcode-Install%20Server-147EFB?logo=xcode&logoColor=f5f5f5" alt="Xcode: Install Server"></summary>134135Via **GitHub Copilot for Xcode** — open Settings > MCP tab > Edit Config (`mcp.json`):136137```json138{139 "servers": {140 "tech-debt-mcp": {141 "command": "npx",142 "args": ["-y", "tech-debt-mcp@latest"]143 }144 }145}146```147148</details>149150### Manual Setup151152Add to your MCP client config:153154```json155{156 "mcpServers": {157 "tech-debt-mcp": {158 "command": "npx",159 "args": ["-y", "tech-debt-mcp@latest"]160 }161 }162}163```164165166## Usage167168Start the MCP server:169170```bash171tech-debt-mcp172```173174Or for development:175176```bash177npm run dev178```179180## Available Tools181182### `analyze_project`183184Analyze an entire project for technical debt.185186**Parameters:**187188- `path` (required): Absolute path to the project root189- `languages` (optional): Array of languages to analyze190- `categories` (optional): Filter by debt categories191- `severity` (optional): Minimum severity level (low, medium, high, critical)192- `maxFiles` (optional): Maximum files to analyze193194### `analyze_file`195196Analyze a single file for technical debt.197198**Parameters:**199200- `path` (required): Absolute path to the file201202### `get_debt_summary`203204Get a quick summary of technical debt in a project.205206**Parameters:**207208- `path` (required): Absolute path to the project root209210### `get_sqale_metrics`211212Get SQALE technical debt metrics including remediation time, debt ratio, and rating.213214**Parameters:**215216- `path` (required): Absolute path to the project root217- `developmentTime` (optional): Estimated development time in hours (for debt ratio calculation)218219**Output includes:**220221- SQALE rating (A-E) with star visualization222- Total remediation time in human-readable format223- Debt ratio (if development time provided)224- Breakdown by severity (Critical, High, Medium, Low)225- Breakdown by category (code-quality, security, maintainability, etc.)226227**Example:**228229```bash230get_sqale_metrics --path=/path/to/project --developmentTime=2080231```232233Returns:234235```236# SQALE Technical Debt Metrics237238**Overall Rating:** B ⭐⭐⭐⭐239**Total Remediation Time:** 4 hours 30 minutes240**Debt Ratio:** 8.5%241242## Breakdown by Severity243| Severity | Time |244|----------|------|245| Critical | 30m |246| High | 1h 45m |247| Medium | 2h |248| Low | 15m |249```250251### `list_supported_languages`252253List all supported programming languages with their checks.254255### `get_recommendations`256257Get prioritized recommendations for addressing technical debt.258259**Parameters:**260261- `path` (required): Absolute path to the project root262- `limit` (optional): Maximum recommendations to return263264### `get_issues_by_severity`265266Get all issues of a specific severity level.267268**Parameters:**269270- `path` (required): Absolute path to the project root271- `severity` (required): low, medium, high, or critical272273### `get_issues_by_category`274275Get all issues of a specific category.276277**Parameters:**278279- `path` (required): Absolute path to the project root280- `category` (required): dependency, code-quality, architecture, documentation, testing, security, performance, or maintainability281282### `add_custom_rule`283284Add a custom pattern-based tech debt rule.285286**Parameters:**287288- `id` (required): Unique identifier for the rule289- `pattern` (required): Regex pattern to match290- `message` (required): Issue title/message291- `severity` (required): low, medium, high, or critical292- `category` (required): One of the debt categories293- `suggestion` (optional): How to fix the issue294- `languages` (optional): Apply only to specific languages295- `flags` (optional): Regex flags (g, i, m, s, etc.)296297### `remove_custom_rule`298299Remove a custom rule by ID.300301**Parameters:**302303- `id` (required): ID of the rule to remove304305### `list_custom_rules`306307List all active custom rules with their statistics.308309### `execute_custom_rules`310311Execute all custom rules against code or a file.312313**Parameters:**314315- `path` (optional): Path to the file to analyze316- `code` (optional): Code content to analyze directly317- `language` (optional): Programming language for filtering rules318319_Note: Either `path` or `code` must be provided._320321### `validate_custom_pattern`322323Validate a custom pattern before adding it as a rule.324325**Parameters:**326327- `id` (required): Unique identifier for the rule328- `pattern` (required): Regex pattern to validate329- `message` (required): Issue title/message330- `severity` (required): low, medium, high, or critical331- `category` (required): One of the debt categories332333## Dependency Analysis (Phase 2)334335Phase 2 adds comprehensive dependency parsing across multiple ecosystems and a new MCP tool `check_dependencies` that scans a project for package manifests and returns a structured dependency report.336337Key capabilities:338339- Detects package manifests for npm, pip, Maven/Gradle, Cargo, Go Modules, Composer, Bundler, NuGet, C/C++, and Swift Package Manager (Package.swift, Podfile, Cartfile)340- Separates production vs development dependencies341- Filters output by `includeDev` parameter342- Reports files that failed to parse for troubleshooting343- Offline-first design with future integration points for vulnerability databases344345### `check_dependencies`346347Scan a project for package manifests and return a structured dependency report.348349**Parameters:**350351- `path` (required): Absolute path to the project root352- `includeDev` (optional): boolean (default: true) — include dev/test dependencies353354### `validate_config`355356Validate a `.techdebtrc.json` configuration file for schema correctness.357358**Parameters:**359360- `path` (required): Absolute path to the project root directory or directly to a `.techdebtrc.json` file361362### `get_vulnerability_report`363364Generate an offline dependency inventory for vulnerability review. Lists all dependencies by ecosystem in a tabular format. Online CVE lookup is planned for Phase 2b.365366**Parameters:**367368- `path` (required): Absolute path to the project root369- `includeDev` (optional): boolean (default: false) — include dev dependencies in the report370371372373## SQALE Metrics374375Tech Debt MCP uses SQALE (Software Quality Assessment based on Lifecycle Expectations) methodology to quantify technical debt:376377### Rating System (A-E Scale)378379- **A**: ≤5% debt ratio (Excellent)380- **B**: 6-10% debt ratio (Good)381- **C**: 11-20% debt ratio (Fair)382- **D**: 21-50% debt ratio (Poor)383- **E**: >50% debt ratio (Critical)384385### Metrics Provided386387- **Remediation Time**: Estimated time to fix all issues388- **Debt Ratio**: Technical debt as percentage of development time389- **Formatted Time**: Human-readable time estimates (e.g., "2h 30m", "3d 4h")390- **Category Breakdown**: Remediation time per debt category391- **Severity Breakdown**: Remediation time per severity level392393### Effort-to-Time Mapping394395- **trivial**: ≤5 minutes396- **small**: 5-30 minutes397- **medium**: 30 min - 2 hours398- **large**: 2-4 hours399- **xlarge**: 4+ hours400401## SwiftUI Analysis402403Tech Debt MCP includes **14 specialized checks** for SwiftUI applications, detecting common anti-patterns, memory leaks, and performance issues.404405### State Management Issues406407- **Excessive @State Variables** - Detects views with >5 @State variables that should use a ViewModel408- **@ObservedObject Misuse** - Flags @ObservedObject with initialization (should use @StateObject)409- **Environment Value Safety** - Detects force unwrapping of @Environment values410411### Memory & Lifecycle412413- **Combine Circular References** - Finds missing [weak self] in Combine sinks414- **Missing Timer Cleanup** - Detects Timers without cleanup in onDisappear415- **Missing Task Cancellation** - Flags async Tasks without cancellation handling416- **Retain Cycles in Closures** - Detects self captures in onChange/onReceive without [weak self]417418### Performance & View Hierarchy419420- **Missing .id() Modifiers** - Detects ForEach without stable identifiers421- **Expensive View Body Calculations** - Flags reduce/sort/filter in view bodies422- **Deep View Nesting** - Warns when nesting depth exceeds 6 levels423- **GeometryReader Misuse** - Detects GeometryReader at view root424425### SwiftUI Best Practices426427- **AnyView Type Erasure** - Suggests using generics or @ViewBuilder instead428- **Deprecated NavigationLink** - Flags old-style NavigationLink patterns429- **Main Thread Safety** - Ensures UI updates happen on main thread430431### Example SwiftUI Issues Detected432433```swift434// ❌ Excessive @State - should use ViewModel435struct UserView: View {436 @State private var firstName = ""437 @State private var lastName = ""438 @State private var email = ""439 @State private var phone = ""440 @State private var address = ""441 @State private var city = "" // 6+ @State variables!442 // ...443}444445// ❌ @ObservedObject with initialization446struct ContentView: View {447 @ObservedObject var viewModel = UserViewModel() // Should be @StateObject!448 // ...449}450451// ❌ Missing Timer cleanup452struct TimerView: View {453 var body: some View {454 Text("Hello")455 .onAppear {456 Timer.scheduledTimer(...) // Missing .onDisappear cleanup!457 }458 }459}460461// ❌ Retain cycle in Combine462publisher463 .sink { value in464 self.updateUI(value) // Missing [weak self]!465 }466```467468All SwiftUI checks follow Apple's best practices and help prevent common bugs in production apps.469470## Custom Rules471472Define your own tech debt checks using regex patterns. Create rules in `.techdebtrc.json`:473474```json475{476 "customPatterns": [477 {478 "id": "no-console-log",479 "pattern": "console\\.log",480 "severity": "low",481 "category": "code-quality",482 "message": "Remove console.log() statements",483 "suggestion": "Use proper logging library instead",484 "languages": ["javascript", "typescript"]485 },486 {487 "id": "no-eval",488 "pattern": "\\beval\\s*\\(",489 "severity": "critical",490 "category": "security",491 "message": "eval() is dangerous",492 "suggestion": "Refactor to avoid dynamic code execution",493 "flags": "g"494 }495 ]496}497```498499### Pattern Options500501- `id` (required): Unique identifier for the rule502- `pattern` (required): Regex pattern to match503- `message` (required): Issue title/message504- `severity` (required): low, medium, high, or critical505- `category` (required): One of the debt categories506- `suggestion` (optional): How to fix the issue507- `languages` (optional): Apply only to specific languages508- `flags` (optional): Regex flags (g, i, m, s, etc.)509510### Example: Custom Rules for Your Team511512```json513{514 "customPatterns": [515 {516 "id": "no-magic-numbers",517 "pattern": "=\\s*\\d{3,}",518 "severity": "medium",519 "category": "maintainability",520 "message": "Magic number detected",521 "suggestion": "Extract to named constant"522 },523 {524 "id": "forbidden-library",525 "pattern": "import.*moment.*from",526 "severity": "medium",527 "category": "dependency",528 "message": "moment.js is deprecated",529 "suggestion": "Use native Date or date-fns instead",530 "languages": ["javascript", "typescript"]531 }532 ]533}534```535536## Debt Categories537538- **dependency**: Outdated or vulnerable dependencies539- **code-quality**: Code smells, anti-patterns, debug statements540- **architecture**: Structural issues, coupling problems541- **documentation**: Missing or outdated documentation542- **testing**: Test coverage and quality issues543- **security**: Security vulnerabilities and risks544- **performance**: Performance anti-patterns545- **maintainability**: Code that's hard to maintain546547## Configuration548549Create a `.techdebtrc.json` file in your project root:550551```json552{553 "ignore": ["vendor/**", "generated/**"],554 "rules": {555 "maxFileLines": 500,556 "maxFunctionLines": 50,557 "maxComplexity": 10,558 "maxNestingDepth": 4559 },560 "severity": {561 "todo-comment": "low",562 "console-log": "medium"563 }564}565```566567## Example Output568569```570# Tech Debt Analysis Report571572## Health Score: 72/100573574### Issues by Severity575| Severity | Count |576|----------|-------|577| 🔴 Critical | 2 |578| 🟠 High | 15 |579| 🟡 Medium | 45 |580| 🟢 Low | 120 |581582## Top Recommendations5835841. **Address Critical Issues Immediately**585 Fix 2 critical security issues including eval() usage.5865872. **Clean Up TODO/FIXME Comments**588 Found 45 TODO comments - consider creating tracked issues.589```590591## Development592593```bash594# Install dependencies595npm install596597# Build598npm run build599600# Run in development601npm run dev602603# Watch mode604npm run watch605606# Run tests607npm test608```609610## Documentation611612- **[TECH_DEBT_SCAN.md](TECH_DEBT_SCAN.md)** - Self-scan results with before/after .techdebtrc.json comparison613- **[ROADMAP.md](ROADMAP.md)** - Development phases and future enhancements614- **[ARCHITECTURE.md](ARCHITECTURE.md)** - System architecture and design patterns615- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines616- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** - Community standards and expectations617- **[RELEASE.md](RELEASE.md)** - Release process and versioning guide618- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes619620## Code Quality621622**Tech Debt MCP practices what it preaches!** 🎯623624### Self-Scan Results (Feb 2026)625626- **SQALE Rating:** A ⭐⭐⭐⭐⭐ (Excellent)627- **Debt Ratio:** 2.9% (Target: <5%)628- **Total Issues:** 81 (0 critical, 14 high, 38 medium, 29 low)629- **Remediation Time:** ~60 hours (down from 70 hours)630- **Health Score:** 51.8/100631632> **📊 See [TECH_DEBT_SCAN.md](TECH_DEBT_SCAN.md)** for complete self-scan results including before/after comparison showing how `.techdebtrc.json` configuration reduced false positives by 20 issues (-19.8%).633634### Quality Standards635636We maintain high code quality through:637638- **File size limits:** Max 500 lines per file639- **Complexity limits:** Max nesting depth of 4, cyclomatic complexity ≤10640- **Type safety:** No `any` types, strict TypeScript mode641- **Code review:** All PRs require review and pass automated checks642- **Self-scanning:** Regular tech debt analysis using our own tool643- **Test exclusions:** Test files excluded from production code analysis644645### Configuration646647Project-specific rules are defined in `.techdebtrc.json`:648649```json650{651 "ignore": ["**/node_modules/**", "**/dist/**", "**/__tests__/**"],652 "rules": {653 "maxFileLines": 500,654 "maxNestingDepth": 4655 }656}657```658659**Impact of Configuration:**660- Before: 101 issues, 70 hours remediation661- After: 81 issues, 60 hours remediation662- Improvement: -20 false positives, -10 hours663664See [ARCHITECTURE.md](ARCHITECTURE.md#code-quality-standards) for detailed metrics and refactoring targets.665666## Contributing667668Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for our community standards.669670## Releases671672Tech Debt MCP uses automated releases via GitHub Actions:673674- **Latest:** [](https://www.npmjs.com/package/tech-debt-mcp)675- **Releases:** [GitHub Releases](https://github.com/PierreJanineh/TechDebtMCP/releases)676- **Roadmap:** See [ROADMAP.md](ROADMAP.md) for planned features677678## License679680MIT681
Full transparency — inspect the skill content before installing.