Tech Debt Mcp

技术债务 MCP 服务

16 个工具 · 2 个资源 · 14 种语言 · 10 种依赖生态

用于分析多种编程语言技术债务的模型上下文协议（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 Release下载 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 标签页 > 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

资源

两个 MCP 资源以 JSON 格式公开只读技术债务数据。两者都使用 RFC 6570 URI 模板：{+projectPath} 语法是保留字符扩展，允许变量包含绝对文件系统路径中的 / 字符，而无需进行百分号编码。

具体示例 — 将 {+projectPath} 替换为绝对路径。请注意双斜杠：模板末尾的 / 与路径开头的 / 会组成 //，这是有效的 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，对与 glob 模式匹配的文件停用特定规则。在所有平台上，模式均使用正斜杠（/）。使用带 **/ 前缀的模式（例如 **/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 辅助的 vibe coding 构建，并定期扫描自身，保持 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 个降至目前的 13 个，健康评分从 42.4 提升至 95。剩余债务：5 处嵌套热点（4 处位于服务端／核心模块，另有 1 处位于 eslint.config.mjs）、7 处系统边界类型断言，以及 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