# Error Tracker MCP Server
基于 Model Context Protocol (MCP) 的错误追踪服务器，自动化处理代码错误：查找代码责任人（Bitbucket）→ 获取 PR 信息 → 创建 JIRA 任务。
## 快速开始
### 1. 安装与编译
```bash
npm install
npm run build
```
### 2. 配置环境变量
创建 `.env` 文件（参考 `.env.example`）：
```bash
# 服务器配置
HTTP_PORT=3000 # HTTP 模式端口（默认 3000）
COMPATIBLE_PORT=3001 # 兼容模式端口（默认 3001）
DEFAULT_BRANCH=main # 默认调查分支（默认 main）
# Bitbucket 配置
BITBUCKET_USERNAME=your_username
BITBUCKET_PASSWORD=your_password
BITBUCKET_BASE_URL=https://your-bitbucket-server.com
BITBUCKET_PROJECT=your_project
BITBUCKET_REPO=your_repo
PR_TARGET_BRANCH=main # PR 目标分支过滤（默认 main）
# JIRA 配置
JIRA_USERNAME=your_username
JIRA_PASSWORD=your_password
JIRA_BASE_URL=https://your-jira-server.com
JIRA_PROJECT_KEY=YOUR_PROJECT
JIRA_ISSUE_TYPE_ID=10101
JIRA_PRIORITY_ID=10000
JIRA_COMPONENT_ID=12505
```
### 3. 选择运行模式
| 模式 | 适用场景 | 启动命令 |
|------|---------|----------|
| **stdio** | 本地使用（Claude Desktop） | `npm start` |
| **HTTP** | 远程部署（新客户端） | `npm run start:http` |
| **兼容** | 远程部署（新旧客户端） | `npm run start:compatible` |
## 核心功能
| 工具 | 功能说明 |
|------|----------|
| `find_code_owner` | 通过文件路径和行号查找代码最后修改者 |
| `get_pull_request` | 根据 commit ID 查找相关 Pull Request |
| `get_commits_by_path` | 获取指定目录路径的提交记录（支持时间范围、分支过滤），返回作者、时间、提交ID等信息 |
| `get_method_code` | 获取错误行所在的完整方法代码，为 AI 提供上下文用于根因分析（自动识别方法边界，支持多层堆栈智能定位） |
| `investigate_error` | 自动调查错误（查找责任人 + PR 信息） |
| `create_jira_ticket` | 基于调查结果创建并分配 JIRA 任务 |
| `track_error_full` | 完整流程：调查 → 分析 → 创建 JIRA（一键完成） |
## 客户端配置
### 方式一：stdio 模式（本地使用 - Claude Desktop）
编辑配置文件：
- **MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"error-tracker": {
"command": "node",
"args": ["-r", "dotenv/config", "/绝对路径/error/build/index.js"]
}
}
}
```
> 💡 需在项目根目录创建 `.env` 文件配置环境变量
### 方式二：HTTP 模式（远程服务器）
#### Streamable HTTP (推荐 - 新协议)
适用于支持 MCP 2025-03-26 协议的客户端：
```json
{
"mcpServers": {
"error-tracker": {
"url": "http://localhost:3000/mcp"
}
}
}
```
#### SSE 模式（兼容 - 旧协议）
适用于仅支持 MCP 2024-11-05 协议的客户端：
```json
{
"mcpServers": {
"error-tracker": {
"url": "http://localhost:3000/sse"
}
}
}
```
**端口说明**：
- HTTP 模式默认端口：`3000`（通过 `.env` 中 `HTTP_PORT` 配置）
- 兼容模式默认端口：`3001`（通过 `.env` 中 `COMPATIBLE_PORT` 配置）
- 启动命令：`npm run start:http`（仅新协议）或 `npm run start:compatible`（新旧协议都支持）
**协议选择**：
- 新客户端 → 使用 `/mcp` 端点（Streamable HTTP）
- 旧客户端 → 使用 `/sse` 端点（传统 SSE）
- 不确定 → 使用兼容模式服务器（`npm run start:compatible`）同时支持两种
## 使用示例
### 场景1：查找代码责任人
```
请帮我查找这个文件第161行是谁写的：
src/main/java/com/example/service/UserService.java
```
### 场景2：获取错误上下文代码
```
请获取这个错误行所在方法的完整代码：
文件: src/main/java/com/example/service/UserService.java
行号: 161
```
### 场景3：分析模块最近变更
```
请分析理算模块最近7天的提交记录：
目录: cbs_claim_catalog/cbs_claim/src/main/java/cbs/claim/application/settlement
我需要看到最近有哪些人修改过这个模块，以及提交的时间范围。
```
### 场景4：完整错误追踪
```
我遇到空指针异常：
文件: src/main/java/com/example/service/UserService.java
行号: 161
错误信息：
java.lang.NullPointerException: Cannot invoke method on null object
at UserService.checkUser(UserService.java:161)
请创建 JIRA 任务，标题"修复空指针异常"，标签 "bug" "urgent"
```
## 使用场景与轻量提示
JIRA 相关参数通常在 `.env` 中配置，日常使用只需给出最少的上下文即可。把错误堆栈直接粘贴给 AI，模型会自动识别并调用合适的工具。
提示约定：除非你明确提供标题，模型会基于错误上下文自动生成合适的 JIRA 标题与描述。
### 快速一键闭环（不需要分析）
示例提示：
```
我这有个错误，请你直接完成责任人定位、关联 PR 并创建 JIRA：
文件: src/main/java/com/example/service/UserService.java
行号: 161
错误堆栈：
java.lang.NullPointerException: Cannot invoke method on null object
at UserService.checkUser(UserService.java:161)
JIRA：标题「修复空指针异常」，标签「bug」「urgent」。
```
说明：模型会自动进行代码所有者定位和 PR 检索，并用 `.env` 中的 JIRA 配置创建任务，无需显式写出工具名称。
### 先让模型分析，再落任务
示例提示：
```
请先根据下面的错误做简要原因分析与修复建议，然后帮我创建一个 JIRA：
文件: src/main/java/com/example/service/UserService.java
行号: 161
错误堆栈：
java.lang.NullPointerException: Cannot invoke method on null object
at UserService.checkUser(UserService.java:161)
JIRA：标题「修复空指针异常（含原因分析）」即可。
```
说明：模型会输出结构化的分析结论（原因/影响/建议）并在创建 JIRA 时自动带上摘要；无需指定工具名，模型会自行选择步骤。
### 深度分析错误上下文
示例提示：
```
我需要分析这个异常的根本原因，请先获取完整方法代码：
文件: src/main/java/com/example/service/UserService.java
行号: 161
然后分析可能的异常原因并给出修复建议。
```
说明：模型会自动调用 `get_method_code` 工具获取完整方法代码，然后基于完整上下文进行分析，比仅有堆栈信息更准确。
### 智能分析堆栈定位根本原因
示例提示：
```
这是一个完整的错误堆栈，请逐层获取错误行所在方法的完整代码：
java.lang.NullPointerException: Cannot invoke method on null object
at com.example.utils.StringUtil.isEmpty(StringUtil.java:45)
at com.example.service.UserService.validateUser(UserService.java:161)
at com.example.controller.LoginController.login(LoginController.java:89)
at com.example.gateway.ApiGateway.handleRequest(ApiGateway.java:203)
找到最可能的位置后，对错误进行调查，然后结合代码对错误进行分析，最后创建 JIRA。
```
说明：模型会智能分析堆栈：
1. 自动获取堆栈中多层方法的完整代码
2. 结合代码逻辑判断根本原因（调用者参数不合规 vs 工具类缺陷）
3. 定位到最可能出错的业务代码层，而非最底层的工具方法
4. 余下步骤参见"先让模型分析，再落任务"
### 其他常见场景
- 多文件/多位置排查（模块级）：
```
用户登录偶发失败，请按模块排查并指出最可能的改动来源：
模块: auth、session、gateway
错误堆栈（多段粘贴即可）：
...
```
- 批量错误收敛并统一创建任务：
```
我有三处相似的 NPE，请合并分析并创建一个总任务，附上三个具体文件与行号作为子任务描述：
1) auth/UserService.java:161
2) session/SessionManager.java:45
3) gateway/LoginController.java:102
错误堆栈已在上文粘贴。
```
- 只分派给代码责任人（不创建 JIRA）：
```
请定位这段错误的代码责任人并把结论返回给我，不需要创建 JIRA：
文件: src/main/java/com/example/service/UserService.java
行号: 161
错误堆栈：...
```
## 远程部署
### Docker 部署
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["node", "-r", "dotenv/config", "build/compatible-server.js"]
```
```bash
docker build -t error-tracker-mcp .
docker run -d -p 3000:3000 --env-file .env error-tracker-mcp
```
### PM2 部署
```bash
pm2 start npm --name "error-tracker" -- run start:compatible
pm2 save && pm2 startup
```
## 故障排除
| 问题 | 解决方案 |
|------|----------|
| 认证失败 | 检查 `.env` 文件中的用户名和密码 |
| 找不到文件 | 确保文件路径相对于仓库根目录，检查 `DEFAULT_BRANCH` 配置 |
| 端口占用 | 修改 `.env` 中的 `HTTP_PORT` 或 `COMPATIBLE_PORT` |
## 技术架构
- **传输模式**：stdio / Streamable HTTP / 兼容模式（详见 [ARCHITECTURE.md](./ARCHITECTURE.md)）
- **开发调试**：调试技巧和贡献指南见 [DEVELOPMENT.md](./DEVELOPMENT.md)
- **技术栈**：TypeScript + MCP SDK + Express + Axios
## 未来功能规划 (TODO)
### 🎯 深度分析增强
- [ ] **trace_error_root_cause_chain** - 错误根因链追踪
- 场景：深度追踪多层调用链，找到真正的根源而非表面现象
- 功能：
- 解析完整堆栈的每一层方法代码
- AI 分析每层的职责和可能的问题点
- 定位最初的根因（如参数来源、数据状态异常）
- 生成分层分析报告，标注真正的 root cause
- 价值：避免只看最底层错误行，找到业务逻辑层的源头问题
### 🤖 自动化修复增强
- [ ] **auto_fix_and_commit** - 自动修复代码并提交
- 场景：AI 分析错误后自动生成修复代码，创建 PR 并指派给代码责任人
- 完整流程：
1. 调用 `get_method_code` 获取错误代码上下文
2. 调用 `investigate_error` 定位代码责任人
3. AI 生成修复代码（基于 errorAnalysis 中的 codeExample）
4. AI 生成对应的单元测试代码
5. 自动创建特性分支（如 `fix/NPE-UserService-161`）
6. 修改源文件和测试文件并提交到新分支
7. 创建 Pull Request，指定 reviewer 为代码责任人
8. PR 描述自动关联 JIRA 工单号
- 价值：端到端自动化（发现问题 → 修复 → 测试 → 代码审查），大幅减少人工介入
### 📊 智能辅助功能
- [ ] **analyze_business_error_by_changes** - 业务错误代码变更分析
- 场景：无堆栈信息的业务逻辑错误（如理算金额错误、数据不一致），通过分析最近代码变更定位问题
- 典型流程：
1. 业务人员发现异常（如：某客户理算金额少了 100 元）
2. 运维描述现象给 AI："理算模块最近出现金额计算错误，折扣未正确应用"
3. AI 自动分析指定业务模块的最近提交记录（可自定义时间范围，默认 7 天）
4. 对比代码变更点与业务现象的关联性
5. 输出可疑提交列表 + 责任人 + 变更说明
- 价值：解决无堆栈信息的业务逻辑问题，特别适合数据计算、状态流转等隐性错误
- [ ] **batch_analyze_errors** - 批量错误分析
- 一次性分析多个相关错误，判断是否同一根因
### 📈 运营分析功能
- [ ] **analyze_error_trends** - 错误趋势分析
- 场景：按产品线/模块/时间维度统计错误趋势，发现高风险区域
- 分析维度：
- 按产品线统计（寿险、财险、健康险各自的错误率）
- 按业务模块统计（承保、理赔、保全的错误热点）
- 按时间趋势统计（版本发布后的错误激增）
- 输出：可视化报表 + 高风险模块预警 + 重构建议
- 价值：指导资源投入方向，提前预防高风险区域
- [ ] **build_error_knowledge_base** - 错误知识库沉淀
- 场景：自动沉淀常见保险业务错误的解决方案
- 功能：
- 自动分类错误类型（费率应用错误、年龄校验错误等）
- 关联历史修复方案和PR
- AI总结通用解决模式
- 生成新人培训案例库
- 价值：避免重复踩坑，加速新人成长
### �🔧 现有工具增强
- [ ] **get_method_code** 增强
- 支持 `includeCallers`: 同时返回调用该方法的代码
- 支持 `contextLevel`: 控制上下文深度（1-3层）
- [ ] **investigate_error** 增强
- 支持 `blameFullMethod`: 对整个方法进行 blame
- 支持 `includeRecentContributors`: 返回该文件近期所有贡献者
## 许可证
MIT
