PierreJanineh/TechDebtMCP

# Tech Debt MCP 服务器 [](https://www.npmjs.com/package/tech-debt-mcp) [](#installation) [-brightgreen)](#code-quality) 用于分析跨多种编程语言技术债务的 Model Context Protocol (MCP) 服务器。专为与 GitHub Copilot 及其他兼容 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` 配置文件的 Schema 正确性 - **可操作的建议**：提供按优先级排序的技术债务解决建议 - **灵活过滤**：按严重程度、类别或语言过滤结果 ## 支持的语言 | Language | Extensions | Key Checks | | ----------- | --------------------- | ---------------------------------------------------------------------------------- | | JavaScript | .js, .mjs, .cjs, .jsx | console.log, debugger, eslint-disable, eval, var usage | | TypeScript | .ts, .tsx, .mts, .cts | any type, @ts-ignore, non-null assertions, type assertions | | Python | .py, .pyw, .pyi | bare except, print statements, global usage, eval/exec | | Java | .java | System.out, printStackTrace, empty catch, @SuppressWarnings | | Swift | .swift | force unwrap (!), force cast (as!), force try, retain cycles, **SwiftUI patterns** | | Kotlin | .kt, .kts | !!, lateinit abuse, @Suppress, unchecked casts | | Objective-C | .m, .mm, .h | NSLog, retain cycles, deprecated methods, massive view controllers | | C++ | .cpp, .cc, .hpp, .h | raw pointers, C-style casts, goto, using namespace std | | C | .c, .h | malloc without free, goto, unsafe functions, null checks | | C# | .cs | Console.WriteLine, async void, empty catch, dispose pattern | | Go | .go | ignored errors, blank imports, fmt.Print, panic, global variables | | Rust | .rs | unwrap, expect, unsafe, allow attributes, panic, println | | Ruby | .rb | puts, binding.pry, rubocop disable, eval, global variables | | PHP | .php | var_dump, print_r, die/exit, eval, error suppression | ## 安装说明

**[一键安装](https://insiders.vscode.dev/redirect/mcp/install?name=tech-debt-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22tech-debt-mcp%40latest%22%5D%7D)** **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"] } } } ```

添加到您的 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"] } } } ``` ## 使用方法 启动 MCP 服务器： ``` tech-debt-mcp ``` 或用于开发： ``` npm run dev ``` ## 可用工具 ### `analyze_project` 分析整个项目的技术债务。 **参数：** - `path`（必填）：项目根目录的绝对路径 - `languages`（可选）：要分析的语言数组 - `categories`（可选）：按债务类别过滤 - `severity`（可选）：最低严重级别（low, medium, high, critical） - `maxFiles`（可选）：最多分析的文件数 ### `analyze_file` 分析单个文件的技术债务。 **参数：** - `path`（必填）：文件的绝对路径 ### `get_debt_summary` 快速获取项目技术债务摘要。 **参数：** - `path`（必填）：项目根目录的绝对路径 ### `get_sqale_metrics` 获取 SQALE 技术债务指标，包括修复时间、债务比率和评级。 **参数：** - `path`（必填）：项目根目录的绝对路径 - `developmentTime`（可选）：预估开发时间（小时）（用于计算债务比率） **输出包含：** - SQALE 评级（A-E）及星级可视化 - 人类可读格式的总修复时间 - 债务比率（如果提供了开发时间） - 按严重程度细分（Critical, High, Medium, Low） - 按类别细分（code-quality, security, maintainability 等） **示例：** ``` get_sqale_metrics --path=/path/to/project --developmentTime=2080 ``` 返回： ``` # SQALE Technical Debt 指标 **Overall Rating:** B ⭐⭐⭐⭐ **Total Remediation Time:** 4 hours 30 minutes **Debt Ratio:** 8.5% ## 按严重程度细分 | Severity | Time | |----------|------| | Critical | 30m | | High | 1h 45m | | Medium | 2h | | Low | 15m | ``` ### `list_supported_languages` 列出所有支持的编程语言及其检查项。 ### `get_recommendations` 获取解决技术债务的优先建议。 **参数：** - `path`（必填）：项目根目录的绝对路径 - `limit`（可选）：返回的最大建议数 ### `get_issues_by_severity` 获取特定严重级别的所有问题。 **参数：** - `path`（必填）：项目根目录的绝对路径 - `severity`（必填）：low, medium, high, 或 critical ### `get_issues_by_category` 获取特定类别的所有问题。 **参数：** - `path`（必填）：项目根目录的绝对路径 - `category`（必填）：dependency, code-quality, architecture, documentation, testing, security, performance, 或 maintainability ### `add_custom_rule` 添加基于自定义模式的技术债务规则。 **参数：** - `id`（必填）：规则的唯一标识符 - `pattern`（必填）：匹配的正则表达式模式 - `message`（必填）：问题标题/消息 - `severity`（必填）：low, medium, high, 或 critical - `category`（必填）：债务类别之一 - `suggestion`（可选）：如何修复该问题 - `languages`（可选）：仅应用于特定语言 - `flags`（可选）：正则表达式标志（g, i, m, s 等） ### `remove_custom_rule` 通过 ID 移除自定义规则。 **参数：** - `id`（必填）：要移除的规则 ID ### `list_custom_rules` 列出所有活跃的自定义规则及其统计信息。 ### `execute_custom_rules` 对代码或文件执行所有自定义规则。 **参数：** - `path`（可选）：要分析的文件路径 - `code`（可选）：直接分析的代码内容 - `language`（可选）：用于过滤规则的编程语言 _注意：必须提供 `path` 或 `code`。_ ### `validate_custom_pattern` 在添加为规则之前验证自定义模式。 **参数：** - `id`（必填）：规则的唯一标识符 - `pattern`（必填）：要验证的正则表达式模式 - `message`（必填）：问题标题/消息 - `severity`（必填）：low, medium, high, 或 critical - `category`（必填）：债务类别之一 ## MCP 资源（阶段 6） 除了工具之外，Tech Debt MCP 还暴露了被动的 MCP 资源，用于在不触发显式工具调用的情况下读取技术债务数据： ### `debt://summary/{projectPath}` 返回技术债务的 JSON 摘要，包括健康评分、债务评分、按严重程度/类别分类的问题计数以及 SQALE 指标。 ### `debt://issues/{projectPath}` 返回所有技术债务问题的可过滤列表。 **查询参数：** - `severity` — 按严重级别过滤（例如 `high`） - `category` — 按类别过滤（例如 `security`） - `limit` — 返回的最大问题数（默认：100） ## 依赖分析（阶段 2） 阶段 2 增加了对多个生态系统的全面依赖解析，以及一个新的 MCP 工具 `check_dependencies`，用于扫描项目中的包清单并返回结构化的依赖报告。 主要功能： - 检测 npm, pip, Maven/Gradle, Cargo, Go Modules, Composer, Bundler, NuGet, C/C++, 和 Swift Package Manager（Package.swift, Podfile, Cartfile）的包清单 - 区分生产依赖与开发依赖 - 通过 `includeDev` 参数过滤输出 - 报告解析失败的文件以便故障排除 - 离线优先设计，为未来与漏洞数据库的集成预留接口 ### `check_dependencies` 扫描项目中的包清单并返回结构化的依赖报告。 **参数：** - `path`（必填）：项目根目录的绝对路径 - `includeDev`（可选）：布尔值（默认：true）— 包括开发/测试依赖 ### `validate_config` 验证 `.techdebtrc.json` 配置文件的 Schema 正确性。 **参数：** - `path`（必填）：项目根目录的绝对路径，或直接指向 `.techdebtrc.json` 文件的路径 ### `get_vulnerability_report` 生成用于漏洞审查的离线依赖清单。以表格格式按生态系统列出所有依赖。在线 CVE 查询计划在阶段 2b 实现。 **参数：** - `path`（必填）：项目根目录的绝对路径 - `includeDev`（可选）：布尔值（默认：false）— 在报告中包括开发依赖 ## SQALE 指标 Tech Debt MCP 使用 SQALE（Software Quality Assessment based on Lifecycle Expectations）方法来量化技术债务： ### 评级系统（A-E 级） - **A**：≤5% 债务比率（优秀） - **B**：6-10% 债务比率（良好） - **C**：11-20% 债务比率（一般） - **D**：21-50% 债务比率（较差） - **E**：>50% 债务比率（严重） ### 提供的指标 - **修复时间**：修复所有问题的预估时间 - **债务比率**：技术债务占开发时间的百分比 - **格式化时间**：人类可读的时间预估（例如 "2h 30m", "3d 4h"） - **类别细分**：每个债务类别的修复时间 - **严重程度细分**：每个严重级别的修复时间 ### 工作量到时间的映射 - **trivial**：≤5 分钟 - **small**：5-30 分钟 - **medium**：30 分钟 - 2 小时 - **large**：2-4 小时 - **xlarge**：4+ 小时 ## SwiftUI 分析 Tech Debt MCP 包含针对 SwiftUI 应用程序的 **14 项专项检查**，可检测常见的反模式、内存泄漏和性能问题。 ### 状态管理问题 - **过多的 @State 变量** — 检测超过 5 个 @State 变量的视图，建议使用 ViewModel - **@ObservedObject 误用** — 标记带有初始化的 @ObservedObject（应使用 @StateObject） - **Environment 值安全性** — 检测 @Environment 值的强制解包 ### 内存与生命周期 - **Combine 循环引用** — 查找 Combine sinks 中缺失的 [weak self] - **缺失 Timer 清理** — 检测 onDisappear 中未清理的 Timer - **缺失 Task 取消** — 标记未处理取消的 async Task - **闭包中的循环引用** — 检测 onChange/onReceive 中不带 [weak self] 的 self 捕获 ### 性能与视图层级 - **缺失 .id() 修饰符** — 检测 ForEach 没有稳定标识符 - **昂贵的 View Body 计算** — 标 view body 中的 reduce/sort/filter - **深层视图嵌套** — 嵌套深度超过 6 层时发出警告 - **GeometryReader 误用** — 检测视图根部的 GeometryReader ### SwiftUI 最佳实践 - **AnyView 类型擦除** — 建议使用泛型或 @ViewBuilder 代替 - **已弃用的 NavigationLink** — 标记旧式 NavigationLink 模式 - **主线程安全** — 确保 UI 更新发生在主线程 ### 检测到的 SwiftUI 问题示例 ``` // ❌ 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]! } ``` 所有 SwiftUI 检查均遵循 Apple 最佳实践，有助于防止生产应用中的常见错误。 ## 自定义规则 使用正则表达式模式定义您自己的技术债务检查。在 `.techdebtrc.json` 中创建规则： ``` { "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"] }, { "id": "no-eval", "pattern": "\\beval\\s*\\(", "severity": "critical", "category": "security", "message": "eval() is dangerous", "suggestion": "Refactor to avoid dynamic code execution", "flags": "g" } ] } ``` ### 模式选项 - `id`（必填）：规则的唯一标识符 - `pattern`（必填）：匹配的正则表达式模式 - `message`（必填）：问题标题/消息 - `severity`（必填）：low, medium, high, 或 critical - `category`（必填）：债务类别之一 - `suggestion`（可选）：如何修复该问题 - `languages`（可选）：仅应用于特定语言 - `flags`（可选）：正则表达式标志（g, i, m, s 等） ### 示例：为您的团队自定义规则 ``` { "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"] } ] } ``` ## 债务类别 - **dependency**：过时或有漏洞的依赖 - **code-quality**：代码异味、反模式、调试语句 - **architecture**：结构性问题、耦合问题 - **documentation**：缺失或过时的文档 - **testing**：测试覆盖率及质量问题 - **security**：安全漏洞和风险 - **performance**：性能反模式 - **maintainability**：难以维护的代码 ## 配置 在项目根目录创建 `.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/**"] } } ``` ### 规则排除 使用 `ruleExclusions` 对匹配 glob 模式的文件抑制特定规则。模式使用正斜杠（`/`）作为分隔符与文件路径进行匹配，适用于所有平台。支持绝对路径和相对路径 — 使用带 `**/` 前缀的模式（例如 `**/src/analyzers/**`）以确保无论路径格式如何都能可靠匹配。这对于消除误报非常有用 — 例如，包含用于检测 `debugger` 或 `@ts-ignore` 的正则表达式模式的分析器源文件，不应被这些相同的规则标记。 ### 行内抑制注释 使用行内注释在源代码中直接抑制特定问题。当特定行或块不应被标记时（例如分析器源文件中的模式定义），这很有用。 支持 `//` 和 `#` 两种注释前缀，因此抑制指令适用于所有被分析的语言（例如 Python/Ruby 使用 `#`，TypeScript/JavaScript/Java/Go 等使用 `//`）。 **单行抑制** — 抑制紧随其后的行： ``` // techdebt-ignore-next-line debugger; // will not be reported // 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, { title: '@ts-ignore comment found', description: '@ts-ignore suppresses TypeScript errors', })); // techdebt-ignore-end ts-ignore ``` 两种形式都接受可选的规则名称。如果没有规则名称，则抑制所有规则。块可以嵌套以针对多个规则。抑制注释必须单独出现在一行中（不能附加在代码后面）。 ## 输出示例 ``` # Tech Debt 分析报告 ## 健康评分：72/100 ### 按严重程度分类的问题 | Severity | Count | |----------|-------| | 🔴 Critical | 2 | | 🟠 High | 15 | | 🟡 Medium | 45 | | 🟢 Low | 120 | ## 首要建议 1. **Address Critical Issues Immediately** Fix 2 critical security issues including eval() usage. 2. **Clean Up TODO/FIXME Comments** Found 45 TODO comments - consider creating tracked issues. ``` ## 开发 ``` # 安装依赖项 npm install # 构建 npm run build # 在开发环境中运行 npm run dev # Watch 模式 npm run watch # 运行测试 npm test ``` ## 文档 - **[TECH_DEBT_SCAN.md](TECH_DEBT_SCAN.md)** - 自我扫描结果及 .techdebtrc.json 前后对比 - **[ROADMAP.md](ROADMAP.md)** - 开发阶段和未来增强功能 - **[ARCHITECTURE.md](ARCHITECTURE.md)** - 系统架构和设计模式 - **[CONTRIBUTING.md](CONTRIBUTING.md)** - 贡献指南 - **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** - 社区标准和期望 - **[RELEASE.md](RELEASE.md)** - 发布流程和版本控制指南 - **[CHANGELOG.md](CHANGELOG.md)** - 版本历史和变更 ## 代码质量 **Tech Debt MCP 以身作则！** 🎯 ### 自我扫描结果（2026 年 2 月） - **SQALE 评级：** A ⭐⭐⭐⭐⭐（优秀） - **债务比率：** 2.9%（目标：<5%） - **总问题数：** 81 个（0 个严重，14 个高，38 个中，29 个低） - **修复时间：** ~60 小时（从 70 小时下降） - **健康评分：** 51.8/100 ### 质量标准 我们通过以下方式保持高代码质量： - **文件大小限制：** 每个文件最多 500 行 - **复杂度限制：** 最大嵌套深度 4，圈复杂度 ≤10 - **类型安全：** 无 `any` 类型，严格 TypeScript 模式 - **代码审查：** 所有 PR 都需要审查并通过自动化检查 - **自我扫描：** 使用我们自己的工具进行定期技术债务分析 - **测试排除：** 测试文件不包含在生产代码分析中 ### 配置 项目特定规则定义在 `.techdebtrc.json` 中： ``` { "ignore": ["**/node_modules/**", "**/dist/**", "**/__tests__/**"], "rules": { "maxFileLines": 500, "maxNestingDepth": 4 } } ``` **配置影响：** - 之前：101 个问题，70 小时修复时间 - 之后：81 个问题，60 小时修复时间 - 改进：减少 20 个误报，减少 10 小时 详见 [ARCHITECTURE.md](ARCHITECTURE.md#code-quality-standards) 了解详细指标和重构目标。 ## 贡献 欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南，参阅 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 了解我们的社区标准。 ## 发布 Tech Debt MCP 通过 GitHub Actions 进行自动发布： - **最新版本：** [](https://www.npmjs.com/package/tech-debt-mcp) - **发布版：** [GitHub Releases](https://github.com/PierreJanineh/TechDebtMCP/releases) - **路线图：** 详见 [ROADMAP.md](ROADMAP.md) 了解计划功能 ## 许可证 MIT

标签：AI编程助手, GitHub Copilot, Go, IPv6支持, MCP服务器, MITM代理, Model Context Protocol, Python, Ruby工具, Rust, SQALE, SwiftUI, TypeScript, WebSocket, 代码审查, 依赖分析, 可维护性, 多语言支持, 安全插件, 安全测试框架, 安全漏洞检测, 技术债务, 无后门, 暗色界面, 网络流量审计, 自动化攻击, 自定义规则, 软件维护, 错误基检测, 静态代码分析