MCP Servers

Tech Debt MCP Server

A server for analyzing technical debt across multiple programming languages, integrating with MCP-compatible tools to detect code quality issues and provide prioritized recommendations.

README

<h1 align="center">Tech Debt MCP Server</h1>

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

</details>

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=tech-debt-mcp&config=eyJjb21tYW5kIjoibnB4IC15IHRlY2gtZGVidC1tY3BAbGF0ZXN0In0=">One-Click Install</a>

Cursor (via Terminal):

cursor --add-mcp '{"name":"tech-debt-mcp","command":"npx -y tech-debt-mcp@latest"}'

</details>

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

</details>

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

</details>

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

</details>

Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):

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

</details>

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

</details>

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

</details>

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

<details> <summary>Analysis — parameter reference</summary>

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.

</details>

<details> <summary>Filtering — parameter reference</summary>

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

</details>

<details> <summary>Custom Rules — parameter reference</summary>

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.

</details>

<details> <summary>Dependencies — parameter reference</summary>

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.

</details>

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

<details> <summary>View all SwiftUI checks with examples</summary>

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

</details>

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

Recommended Servers

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official

Featured

TypeScript

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official

Featured

Local

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official

Featured

TypeScript

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official

Featured

Python

E2B

Using MCP to run code via e2b.

Official

Featured

Neon Database

MCP server for interacting with Neon Management API and databases

Official

Featured

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official

Featured

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official

Featured