Tech Debt MCP

技术债务MCP服务器

](https://www.npmjs.com/package/tech-debt-mcp)  [![SQALE Rating]()](#code-quality) 

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模块、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 --add-mcp '{"name":"tech-debt-mcp","command":"npx -y tech-debt-mcp@latest"}'

克劳德代码 （通过终端）：

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

克劳德桌面版 --添加到您的 claude_desktop_config.json:

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

添加到您的Windsurf MCP配置(~/.codeium/windsurf/mcp_config.json):

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

经由 AI助手 --打开 设置>工具>AI助手>模型上下文协议（MCP），单击 +，选择 JSON格式，然后粘贴：

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

经由 Xcode的GitHub副本 --打开“设置”>“MCP”选项卡>“编辑配置”(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

工具

贯穿始终的债务类别： dependency · code-quality · architecture · documentation · testing · security · performance · maintainability

Analysis — parameter reference

get_sqale_metrics 返回SQALE评级（a-E），包括星级可视化、总补救时间、债务比率以及按严重程度和类别划分的细分。

Filtering — parameter reference

Custom Rules — parameter reference

◐ execute_custom_rules 需要 要么 path 或 code，两者都不需要。空字符串 "" 为了 path 被视为省略该字段。

Dependencies — parameter reference

check_dependencies 检测npm、pip、Maven/Gradle、Cargo、Go模块、Composer、Bundler、NuGet、C/C++（CMakeLists.txt、connfile.txt/py、vcpkg.json）和Swift包管理器的清单。 get_vulnerability_report 生成离线依赖关系清单——请参见 ROADMAP.md 用于计划的在线CVE查找。

资源

两个MCP资源以JSON格式公开只读技术债务数据。两者都使用 RFC 6570 URI寺庙：the {+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检查员:

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

打开它打印的URL，切换到 资源 选项卡，并使用您的绝对项目路径读取模板URI。

配置

创建一个 .techdebtrc.json 项目根目录中的文件：

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

规则排除

使用 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，或在运行时通过 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指标

MCP使用的技术债务 SQALE 量化技术债务的方法：

时间映射的努力： 琐碎（≤5m）·小（5-30m）·中（30m-2h）·大（2-4h）·大的（4h+）

SwiftUI分析

SwiftUI应用程序的14项专门检查，涵盖 状态管理 （过度@状态、@观察对象误用、环境值安全）， 内存与生命周期 （结合保留周期、计时器清理、任务取消、关闭保留周期）， 演出 （缺少.id（）修饰符、昂贵的体计算、深度嵌套、GeometricReader误用），以及 最佳实践 （AnyView类型擦除，已弃用NavigationLink，主线程安全）。

View all SwiftUI checks with examples

状态管理问题

• @状态变量过多 -检测应使用ViewModel的>5@State变量的视图
• @观察到的对象滥用 -初始化时标记@ObservedObject（应使用@StateObject）
• 环境价值安全 -检测@Environment值的强制展开

内存和生命周期

• 合并循环引用 -在Combine水槽中发现缺失的\[弱自我\]
• 缺少计时器清理 -在onDisappear中检测计时器而不进行清理
• 缺少任务取消 -标记异步任务，不进行取消处理
• 在封闭状态下保持循环 -在onChange/onReceive中检测没有\[weak self\]的自我捕获

性能和视图层次结构

• 缺少.id（）修饰符 -检测没有稳定标识符的ForEach
• 昂贵的视图体计算 -视图体中的标记减少/排序/过滤
• 深度视图嵌套 -嵌套深度超过6级时发出警告
• GeometricReader误用 -在视图根检测GeometricReader

SwiftUI最佳实践

• AnyView类型擦除 -建议改用泛型或@ViewBuilder
• 已弃用的导航链接 -标记旧式NavigationLink模式
• 主线安全 -确保UI更新发生在主线程上

检测到的问题示例

// 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实践了它所宣扬的——用人工智能辅助的氛围编码构建，通过定期扫描自己来保持A级。内部重构（例如，嵌套减少 customRulesEngine.validatePattern 通过提取的助手--#146）由自扫描结果驱动。

自我扫描结果（v2.0.22026年4月）

• SQALE评级： A（优秀）
• 债务评分： 5/100（目标：≤5/100）
• 问题总数： 13（0临界，0高，6中等，7低）
• 补救时间： 14小时
• 健康评分： 95/100

在v2.0.2安全强化后，v2.0.1基线中的118个问题/42.4个健康状况有所下降， ruleExclusions 配置、嵌套重构（#113、#118、#131、#146）和自定义规则处理程序提取（#145）。剩余债务：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

文档

• 建筑.md -系统架构和设计模式
• ROADMAP.md -开发阶段和未来的增强功能
• 贡献.md -贡献指南
• 更改日志.md -版本历史和更改
• 发布.md -发布流程和版本指南
• TECH_DEBT_SCAN.md -自我扫描结果与之前/之后的比较
• 代码_OF_CONDUCT.md -社区标准

贡献

欢迎投稿！请参阅 贡献.md 指南和 代码_OF_CONDUCT.md 我们的社区标准。

发布

• 最新的： ](https://www.npmjs.com/package/tech-debt-mcp)
• 发布：
• 路线图： 看 ROADMAP.md 对于计划中的功能
• 安全： escapeRegExp() (src/utils/regexUtils.ts)在将捕获的字符串插值到 new RegExp() --见第128期；处理程序输出使用 basename() / getRelativePath() 为了防止故意消息和原始消息中的绝对文件系统路径泄漏 err.message 文件系统操作中的字符串在返回给客户端之前会被净化——请参阅问题#129

许可证

麻省理工学院