Tech Debt Mcp

-> mcpb/tech-debt-mcp-<version>.mcpb

</details>
<details>

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

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

</details>

<details>

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

</details>

<details>

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

</details>

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

<summary><strong>Analysis — parameter reference</strong></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><strong>Filtering — parameter reference</strong></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><strong>Custom Rules — parameter reference</strong></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><strong>Dependencies — parameter reference</strong></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:

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