Tech Debt Mcp

Tech Debt MCP サーバー

16 個のツール · 2 個のリソース · 14 言語 · 10 個の依存関係エコシステム

複数のプログラミング言語にわたる技術的負債を分析するための Model Context Protocol（MCP）サーバーです。GitHub Copilot、Claude、Cursor など、MCP 互換ツールとの連携を想定して設計されています。

特長

• 複数言語に対応：JavaScript、TypeScript、Python、Java、Swift、Kotlin、Objective-C、C++、C、C#、Go、Rust、Ruby、PHP
• 包括的な分析：コード品質の問題、セキュリティ上の脆弱性、保守性の問題など、さまざまな種類の技術的負債を検出します
• SQALE メトリクス：SQALE 評価システム（A〜E スケール）で技術的負債を算出します
• SwiftUI 分析：SwiftUI のパターン、状態管理、メモリリーク、ビューのネスト、並行処理の問題を専門的にチェックします
• カスタムルール：正規表現に対応したパターンベースのチェックを独自に定義できます
• 依存関係の分析：10 個のエコシステム（npm、pip、Maven/Gradle、Cargo、Go Modules、Composer、Bundler、NuGet、C/C++、Swift）のパッケージマニフェストを解析します
• インライン抑制：// techdebt-ignore-next-line またはブロックコメントを使って誤検知を抑制できます
• 設定の検証：.techdebtrc.json 設定ファイルがスキーマに準拠しているか検証します
• 実用的な推奨事項：技術的負債への対処に向けた、優先順位付きの提案を提示します
• 柔軟なフィルタリング：重大度、カテゴリ、言語で結果を絞り込めます
• セキュリティ強化（v2.0.2）：すべてのツールおよびリソースのパス入力でパストラバーサルを防止し、カスタムルールの正規表現を ReDoS から保護し、SwiftUI チェックで正規表現インジェクションをエスケープし、すべてのエラーメッセージで絶対パスを無害化します。また、プッシュおよび PR のたびに CodeQL SAST スキャンを実行します

対応言語

インストール

ワンクリックでインストール

VS Code（ターミナル経由）：

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

ワンクリックでインストール

Cursor（ターミナル経由）：

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

Claude Code（ターミナル経由）：

claude mcp add tech-debt-mcp -- npx -y tech-debt-mcp@latest

Claude Desktop — claude_desktop_config.json に追加します：

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

Claude Code プラグイン — このリポジトリのマーケットプレイスを追加してから、プラグインをインストールします：

/plugin marketplace add PierreJanineh/TechDebtMCP
/plugin install tech-debt-mcp@techdebtmcp

プラグインは内部で npx -y tech-debt-mcp@latest を実行します。ソースのバンドルは不要で、公開済みの npm リリースが常に使用されます。プラグイン利用者向けドキュメント（インストール手順、トランスクリプトの例、セキュリティ方針）については、plugin/README.md を参照してください。

Claude Desktop MCPB バンドル — node_modules を同梱したワンクリックインストールです（npx は不要で、実行時のインターネット接続も必要ありません）。

最新の GitHub リリースから tech-debt-mcp-<version>.mcpb をダウンロードし、macOS または Windows 版の Claude で開きます。

バンドルをローカルでビルドするには：

npm install --include=dev --ignore-scripts
npm run mcpb:pack
# -> mcpb/tech-debt-mcp-<version>.mcpb

Windsurf の MCP 設定（~/.codeium/windsurf/mcp_config.json）に追加します：

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

AI Assistant 経由 — Settings > Tools > AI Assistant > Model Context Protocol (MCP) を開き、+ をクリックして As JSON を選択し、次を貼り付けます：

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

GitHub Copilot for Xcode 経由 — Settings > MCP tab > Edit Config (mcp.json) を開きます：

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

手動セットアップ

MCP クライアントの設定に追加します：

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

開発時は npm run dev を実行します。

ツール

すべてのツールでツールアノテーションを宣言しています。Read ツールは副作用がなく（readOnlyHint: true）、Write ツールはサーバーセッションの状態を変更します（destructiveHint: true）。

全体で使用される負債カテゴリ： dependency · code-quality · architecture · documentation · testing · security · performance · maintainability

リソース

2つの MCP リソースにより、読み取り専用の技術的負債データを JSON 形式で公開します。どちらも RFC 6570 URI テンプレート を使用します。{+projectPath} 構文は 予約展開 であり、絶対ファイルシステムパスに含まれる / 文字をパーセントエンコードせずに変数へ含めることができます。

具体例 — {+projectPath} を絶対パスに置き換えてください。スラッシュが2つ並んでいる点に注意してください。テンプレート末尾の / とパス先頭の / が合わさって // になりますが、これは有効な URI 構文です。

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

対話的なテスト — ツールとリソースを試す最も簡単な方法は、MCP Inspector を使うことです。

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

表示された URL を開き、Resources タブに切り替えて、絶対パスのプロジェクトパスを指定したテンプレート URI を読み取ってください。

設定

プロジェクトのルートに .techdebtrc.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"]
    }
  ]
}

言語ごとの上書き

languageOverrides を使用して、言語ごとにルール、重大度、またはファイル拡張子を上書きします。キーには、有効なサポート対象言語の識別子を指定する必要があります。

{
  "languageOverrides": {
    "typescript": {
      "rules": {
        "maxFileLines": 800,
        "maxFunctionLines": 80
      },
      "severity": {
        "todo-comment": "high"
      }
    },
    "python": {
      "extensions": [".pyx"],
      "rules": {
        "maxComplexity": 15
      }
    }
  }
}

• rules — 言語ごとのしきい値です（一致するファイルではトップレベルの rules を上書きします）。
• severity — 言語ごとのルール重大度の上書きです。
• extensions — この言語に割り当てる追加のファイル拡張子です（デフォルト以外）。

ルールの除外

ruleExclusions を使用して、グロブパターンに一致するファイルに対する特定のルールを抑制します。パターンには、すべてのプラットフォームでスラッシュ（/）を使用します。パス形式にかかわらず確実に一致させるには、**/ で始まるパターン（例：**/src/analyzers/**）を使用します。

インライン抑制

ソースコード内で特定の問題を直接抑制します。すべての言語で、コメントの接頭辞として // と # の両方がサポートされています。

単一行 — 次の行を抑制します。

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

ブロック — 開始行と終了行の間にあるすべての行を抑制します。

// techdebt-ignore-start ts-ignore
issues.push(...this.checkPattern(filePath, content, /@ts-ignore/g, { ... }));
// techdebt-ignore-end ts-ignore

ルール名を指定しない場合は、すべてのルールが抑制されます。ブロックは入れ子にできます。抑制コメントは単独の行に記述する必要があります。

カスタムルールの例

適用範囲に関する注意： .techdebtrc.json で定義した customPatterns は、スキャン前にプロジェクト設定を読み込む analyze_project でのみ適用されます。analyze_file は .techdebtrc.json を読み込まずに言語アナライザーを直接呼び出すため、この経路では設定で定義したパターンは適用されません。単一ファイルにカスタムパターンを適用するには、実行時に add_custom_rule を使用するか、execute_custom_rules を直接呼び出してください。

.techdebtrc.json の customPatterns の下にパターンを定義するか、add_custom_rule MCP ツールを使って実行時に登録します。

{
  "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 メトリクス

Tech Debt MCP では、SQALE 手法を使用して技術的負債を定量化します。

作業時間の対応関係： ごく小（≤5m） · 小（5-30m） · 中（30m-2h） · 大（2-4h） · 特大（4h+）

SwiftUI 分析

SwiftUI アプリ向けの14種類の専用チェックを提供します。状態管理（過剰な @State、@ObservedObject の誤用、環境値の安全性）、メモリとライフサイクル（Combine の保持サイクル、タイマーのクリーンアップ、タスクのキャンセル、クロージャの保持サイクル）、パフォーマンス（.id() 修飾子の不足、body 内の負荷の高い計算、深いネスト、GeometryReader の誤用）、ベストプラクティス（AnyView による型消去、非推奨の NavigationLink、メインスレッドの安全性）を対象とします。

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

出力例

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

コード品質

Tech Debt MCP は自らが推奨する実践を実行しています。AI 支援によるバイブコーディングで構築され、定期的に自身をスキャンすることで A 評価を維持しています。内部リファクタリング（例：ヘルパーの抽出による customRulesEngine.validatePattern のネスト削減 — #146）は、セルフスキャンで見つかった問題をもとに行われます。

セルフスキャン結果（v2.0.2、2026年4月）

• SQALE 評価: A（優秀）
• 負債スコア: 5/100（目標：≤5/100）
• 問題の合計: 13件（重大 0件、高 0件、中 6件、低 7件）
• 修正所要時間: 14時間
• 健全性スコア: 95/100

v2.0.2 のセキュリティ強化、ruleExclusions 設定、ネストのリファクタリング（#113、#118、#131、#146）、カスタムルールハンドラーの抽出（#145）により、v2.0.1 のベースラインである118件の問題／42.4の健全性から改善しました。残る負債：ネストのホットスポット5か所（server／core モジュール内に4か所、eslint.config.mjs に1か所）、システム境界での型アサーションの使用7件、非 null アサーション1件。問題ごとの詳細は TECH_DEBT_SCAN.md を参照してください。

開発

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

ドキュメント

• ARCHITECTURE.md - システムアーキテクチャと設計パターン
• ROADMAP.md - 開発フェーズと今後の機能拡張
• CONTRIBUTING.md - 貢献ガイドライン
• CHANGELOG.md - バージョン履歴と変更内容
• RELEASE.md - リリース手順とバージョン管理ガイド
• TECH_DEBT_SCAN.md - 変更前後の比較を含むセルフスキャン結果
• CODE_OF_CONDUCT.md - コミュニティ基準
• PRIVACY.md - プライバシーポリシー（https://pierrejanineh.github.io/TechDebtMCP/privacy でも公開されています）
• plugin/README.md - プラグイン利用者向けドキュメント（インストール、トランスクリプト例、セキュリティ方針）

プライバシー

Tech Debt MCP はすべてお使いのマシン上で動作します。インストール後は、渡されたファイルを読み取り、ローカルの stdio トランスポート経由で MCP クライアントに問題を返すだけで、それ以外の処理は行いません。サーバー自体は外部ネットワークへの接続を行わず、テレメトリや分析機能もなく、サードパーティサービスも使用しません。npm／npx によるインストールでは、標準的なパッケージマネージャーの動作として npm レジストリに接続します。MCPB バンドルにはあらかじめインストールされており、それ以上のネットワークアクセスは不要です。詳細は PRIVACY.md、または公開ポリシー https://pierrejanineh.github.io/TechDebtMCP/privacy を参照してください。

貢献

貢献を歓迎します！ガイドラインについては CONTRIBUTING.md、コミュニティ基準については CODE_OF_CONDUCT.md をご覧ください。

リリース

• 最新:
• リリース: GitHub Releases
• ロードマップ: 予定されている機能については ROADMAP.md をご覧ください
• セキュリティ: キャプチャした文字列を new RegExp() に埋め込む場合は escapeRegExp()（src/utils/regexUtils.ts）を使用する必要があります（issue #128 を参照）。ハンドラーの出力では basename()／getRelativePath() を使用し、意図的なメッセージに絶対ファイルシステムパスが漏れるのを防ぎます。また、ファイルシステム操作から取得した生の err.message 文字列は、クライアントに返す前にサニタイズされます（issue #129 を参照）

ライセンス

MIT