add_custom_rule
Add a custom pattern-based tech debt rule.
LABSCO SUMMARY
It scores the debt rather than only listing it, which turns 'this code is messy' into an argument about priorities.
SQALE remediation time and a debt ratio give the conversation a unit, and recommendations come back already ranked. Two boundaries worth knowing: the dependency report lists what your project pulls in for review rather than looking up CVEs, and custom rules added during a session are tracked separately from the customPatterns declared in .techdebtrc.json.
What it is
A static analyser behind an MCP interface. It scans a project for debt, scores it, and returns issues you can slice by severity, category or language rather than one undifferentiated list.
What you get
- analyze_project across a whole tree, filtered by severity, category or language and capped with maxFiles; analyze_file for a single file; get_debt_summary for the short version
- SQALE metrics: remediation time, debt ratio and an A-E rating, with your development time as an input
- Issues sliced the way you want to read them — by severity or by category — and a prioritised recommendation list
- Language-specific checks across JavaScript, TypeScript, Python, Java, Swift, Kotlin, Objective-C, C++, C, C#, Go, Rust, Ruby and PHP: force unwraps and retain cycles in Swift, bare excepts in Python, ignored errors in Go, unwrap and unsafe in Rust, empty catches in Java and C#, and so on
- Specialised SwiftUI checks for state management, view nesting, memory leaks and concurrency
- Custom rules two ways: registered for the session with a regex, message, severity and category — validated before you add them — or declared as customPatterns in .techdebtrc.json
- Dependency analysis across npm, pip, Maven and Gradle, Cargo, Go Modules, Composer, Bundler, NuGet, C/C++ and Swift, plus an offline report listing every dependency for review
- validate_config to check a .techdebtrc.json against the schema instead of discovering the mistake through odd results
- Inline suppression for genuine false positives with a techdebt-ignore-next-line comment
Requirements
Nothing to authorize — it reads the code you point it at. Run it over stdio with npx -y tech-debt-mcp@latest, or install it as a Claude Code plugin, or as an MCPB bundle for Claude Desktop that ships its dependencies and needs no network at runtime. Behaviour comes from a .techdebtrc.json in the project root: include and ignore globs, thresholds for file length, function length, complexity and nesting depth, per-rule severity overrides, per-path rule exclusions, and custom regex patterns.
Setup effort
One command — npx -y tech-debt-mcp@latest
USE CASES
01
Getting the shape of the debt in a codebase you inherited
Take the summary first, then the SQALE rating with your own development time as input.
02
Deciding what to fix first
Read the prioritised recommendations, then pull the issues at the severity you have time for.
03
Checking one file before you commit it
Analyse just that file rather than waiting on a whole-project scan.
04
Enforcing a convention your linter does not cover
Validate the pattern first, then register it as a rule and run it against the code.
05
Taking stock of what the project depends on
Parse the manifests across every ecosystem in the repo, then read the dependency report.
06
Making sure your configuration is actually being applied
Validate the config file against the schema, and list the rules registered in this session.
16 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
analyze_file
Analyze a single file for technical debt issues.
analyze_project
Analyze an entire project for technical debt. Scans all supported files and returns a comprehensive report with issues, metrics, and recommendations.
check_dependencies
Analyze project dependencies across multiple package managers.
execute_custom_rules
Execute all custom rules against code or a file.
get_debt_summary
Get a quick summary of technical debt in a project.
get_issues_by_category
Get all issues of a specific category.
get_issues_by_severity
Get all issues of a specific severity level.
get_recommendations
Get prioritized recommendations for addressing technical debt.
get_sqale_metrics
Get SQALE technical debt metrics including remediation time, debt ratio, and rating.
get_vulnerability_report
Generate an offline dependency report listing all project dependencies for vulnerability review. Note: actual CVE lookups require Phase 2b online integration.
list_session_custom_rules
List custom rules registered in this server session via add_custom_rule. Does NOT include customPatterns declared in .techdebtrc.json (those run inside analyze_project via AnalysisEngine but are not surfaced here). Renamed from list_custom_rules (TEC-51) for clarity; the old name is no longer registered.
list_supported_languages
List all programming languages supported by the analyzer.
remove_custom_rule
Remove a custom rule by ID.
validate_config
Validate a .techdebtrc.json configuration file for syntax and schema correctness.
validate_custom_pattern
Validate a custom pattern before adding it as a rule.
BEFORE YOU INSTALL
What to know first
Tools you get
16 tools when we connected.
Requires
npx on PATH
CONTEXT COST
Light Standing cost
Rated by the size of the 16 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx -y tech-debt-mcp@latestMCP Clients
VS Code
VS CODE · TERMINAL
code --add-mcp '{"name":"tech-debt-mcp","command":"npx","args":["-y","tech-debt-mcp@latest"]}'Cursor
CURSOR · TERMINAL
cursor --add-mcp '{"name":"tech-debt-mcp","command":"npx -y tech-debt-mcp@latest"}'Claude Code
CLAUDE CODE · TERMINAL
claude mcp add tech-debt-mcp -- npx -y tech-debt-mcp@latestClaude Code — plugin
CLAUDE CODE — PLUGIN · IN CLIENT
/plugin marketplace add PierreJanineh/TechDebtMCP
/plugin install tech-debt-mcp@techdebtmcpClaude Desktop, Windsurf, JetBrains IDEs
JSON
{
"mcpServers": {
"tech-debt-mcp": {
"command": "npx",
"args": [
"-y",
"tech-debt-mcp@latest"
]
}
}
}Xcode
XCODE · JSON
{
"servers": {
"tech-debt-mcp": {
"command": "npx",
"args": [
"-y",
"tech-debt-mcp@latest"
]
}
}
}
