技术债务分析服务器

Tech Debt MCP Server

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

支持的语言

安装

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

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

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

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

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

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

{
  "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寺庙：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 项目根目录中的文件：

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

如果没有规则名称，所有规则都将被抑制。块可以嵌套。压制性评论必须出现在自己的行中。

自定义规则示例

范围说明： customPatterns 定义于 .techdebtrc.json 仅适用于 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指标

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

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

SwiftUI分析

SwiftUI应用程序的14项专门检查，涵盖 状态管理 （过度@状态、@观察对象误用、环境值安全）， 内存与生命周期 （结合保留周期、计时器清理、任务取消、关闭保留周期）， 演出 （缺少.id（）修饰符、昂贵的体计算、深度嵌套、GeometricReader误用），以及 最佳实践 （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实践了它所宣扬的——用人工智能辅助的氛围编码构建，通过定期扫描自己来保持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 -隐私政策（也托管在 https://pierrejanineh.github.io/TechDebtMCP/privacy)
• 插件/README.md -插件面向用户的文档（安装、示例转录、安全态势）

隐私

Tech Debt MCP完全在您的机器上运行。安装后，它会读取您传递给它的文件，通过本地stdio传输将问题返回给MCP客户端，而不做其他任何事情——服务器本身不进行出站网络调用，没有遥测，没有分析，也不使用第三方服务。通过以下方式安装 npm/npx 按照标准的包管理器行为联系npm注册表；MCPB捆绑包预先安装，不需要进一步的网络接入。看 PRIVACY.md 或托管策略 https://pierrejanineh.github.io/TechDebtMCP/privacy 了解详情。

贡献

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

发布

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

许可证

麻省理工学院