Installation

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

One-Click Install

VS Code (via Terminal):

code --add-mcp '{"name":"tech-debt-mcp","command":"npx","args":["-y","tech-debt-mcp@latest"]}'

</details>

<details> <summary><img src="https://img.shields.io/badge/Cursor-Install%20Server-26251E?logo=cursor&logoColor=F7F7F4" alt="Cursor: Install Server"></summary>

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

<details> <summary><img src="https://img.shields.io/badge/Claude-Install%20Server-d97757?logo=Claude&logoColor=f5f5f5" alt="Claude: Install Server"></summary>

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>

<details> <summary><img src="https://img.shields.io/badge/Claude_Code-Install%20as%20Plugin-d97757?logo=Claude&logoColor=f5f5f5" alt="Claude Code: Install as Plugin"></summary>

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.

</details>

<details> <summary><img src="https://img.shields.io/badge/Claude_Desktop-Install%20MCPB%20Bundle-d97757?logo=Claude&logoColor=f5f5f5" alt="Claude Desktop: Install MCPB Bundle"></summary>

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:

```sh npm install --include=dev --ignore-scripts npm run mcpb:pack

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

Example Custom Rules

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

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

```

Configuration

Create a .techdebtrc.json file in your project root:

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

SQALE Metrics

Tech Debt MCP uses SQALE methodology to quantify technical debt:

Effort-to-time mapping: trivial (≤5m) · small (5-30m) · medium (30m-2h) · large (2-4h) · xlarge (4h+)