Techdebtdiscoveragent
TechDebt Discover Agent
Installation
npx techdebtdiscoveragentAsk AI about Techdebtdiscoveragent
Powered by Claude Β· Grounded in docs
I know everything about Techdebtdiscoveragent. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π Technical Debt Discovery MCP Server
An advanced Model Context Protocol (MCP) server for automated technical debt analysis. This TypeScript-based server intelligently scans your codebase to identify common debt patterns and provides actionable insights for code improvement.
β¨ Features
- π― Smart Pattern Detection: Identifies TODO/FIXME comments, TypeScript
anyusage, console statements, deprecated APIs, and more - π Severity Classification: Categorizes findings as low, medium, or high severity
- π¨ Rich Reporting: Provides formatted reports with emojis, severity indicators, and file statistics
- βοΈ Configurable Filtering: Filter by debt type, severity level, or specific patterns
- π Performance Optimized: Efficiently skips irrelevant directories (node_modules, .git, etc.)
- π Multi-Language Support: Supports .js, .ts, .jsx, .tsx files
π Features Overview
For a comprehensive list of all features, implementation status, and technical details, see FUNCTIONALITY.md.
Quick Feature Summary
- π Pattern Detection: TODO comments, TypeScript
anyusage, console statements, deprecated APIs - π Smart Scanning: Recursive directory traversal with intelligent filtering
- π― Severity Levels: High/Medium/Low categorization with visual indicators
- βοΈ Configurable: Filter by type, severity, and target directory
- π MCP Integration: Ready for LLM integration via Model Context Protocol
π§ Technical Debt Patterns Detected
| Pattern | Severity | Description |
|---|---|---|
| TODO/FIXME Comments | Medium | Unfinished work markers |
TypeScript any Usage | High | Type safety violations |
| Console Statements | Low | Debug code left in production |
var Declarations | Medium | Outdated variable declarations |
| Deprecated APIs | High | Usage of deprecated functions |
| Complex Conditions | Medium | Overly complex if statements |
| Large Files | Medium | Files exceeding size thresholds |
π Getting Started
Prerequisites
- Node.js 16+ and npm
- TypeScript (for development)
Installation & Setup
-
Install dependencies
npm install -
Build the project
npm run build -
Start the MCP server
npm start
The server runs using stdio transport for seamless MCP client integration.
π Usage
Basic Scan
Scan the current directory for all technical debt:
{
"tool": "list-tech-debt"
}
Advanced Filtering
Scan with specific criteria:
{
"tool": "list-tech-debt",
"arguments": {
"directory": "/path/to/project",
"severity": "medium",
"includeTypes": ["typing", "complexity", "deprecation"]
}
}
Sample Output
π Technical Debt Report
π Found 5 issues in 3 files (scanned 12 total)
π **src/components/UserForm.tsx**
π΄ [typing] Uses 'any' type (TypeScript anti-pattern)
π‘ [complexity] Contains complex conditional statements
π **src/utils/helpers.js**
π‘ [modernization] Uses 'var' instead of 'let' or 'const'
π΅ [debugging] Contains console.log statements
π§ Configuration
The server supports the following parameters:
| Parameter | Type | Description | Default |
|---|---|---|---|
directory | string | Directory to scan | Current working directory |
includeTypes | string[] | Debt types to include | All types |
severity | enum | Minimum severity level | "low" |
Supported Debt Types
comments- TODO/FIXME/HACK commentstyping- TypeScript any usagedebugging- Console statementsmodernization- Outdated syntaxdeprecation- Deprecated APIscomplexity- Complex conditionssize- Large files
π MCP Integration
VS Code Integration
This server integrates seamlessly with VS Code through MCP:
- Configuration available in
.vscode/mcp.json - Use with GitHub Copilot for enhanced code analysis
- Real-time technical debt detection during development
Client Integration
For other MCP clients, connect using stdio transport:
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
// Server automatically handles MCP protocol communication
π οΈ Development
Project Structure
src/
βββ index.ts # Main MCP server implementation
βββ index.js # Compiled JavaScript (generated)
build/ # Build output directory
test.js # Test utilities
Key Components
- Pattern Detection Engine: Configurable regex patterns for debt identification
- File Scanner: Recursive directory traversal with intelligent filtering
- Report Generator: Rich formatting with severity-based sorting
- MCP Tool Handler: Protocol-compliant tool registration and execution
Extending Debt Patterns
Add new patterns to the DEBT_PATTERNS constant:
const DEBT_PATTERNS = {
// Existing patterns...
newPattern: /your-regex-here/g,
} as const;
π Resources
- Model Context Protocol Documentation - Complete MCP guide
- MCP SDK Reference - SDK examples and patterns
- Technical Debt Best Practices - Industry guidelines
π€ Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
π License
This project is open source and available under the MIT License.
Custom Copilot Instructions: See .github/copilot-instructions.md for workspace-specific AI guidance.
