内容
# bug_tracker_mcp
[](https://www.python.org/downloads/)
[](https://github.com/jlowin/fastmcp)
一款用于跟踪代码会话中错误、任务和上下文的轻量级、以代理为优先的模型上下文协议（MCP）服务器。旨在为AI代理（如Claude Desktop、Antigravity和Cursor）提供零摩擦的持久内存，以便在开发过程中发现问题。
---
## 概述
在与AI代理进行结对编程时，错误和技术债务经常在任务中途被发现。没有持久的跟踪器，这些问题在上下文窗口重置时就会丢失。
`bug_tracker_mcp`通过轻量级SQLite支持的MCP服务器解决了这个问题。它提供了6种快速MCP工具，允许代理记录、检查、更新、解决和删除错误，所有这些都针对每个项目隔离。每次工具调用都需要一个明确的`项目`名称（例如存储库名称），由调用代理提供；服务器永远不会从其自己的工作目录推断它，因为单个长期运行的MCP进程可以在会话中为多个不同项目提供服务。
---
## 架构
系统被组织成解耦的Python模块：
- **FastMCP服务器（`bug_tracker_mcp.server`）**：使用`fastmcp.FastMCP`定义stdio传输MCP工具。处理参数验证，在每次调用中需要一个`项目`名称，并将内部异常转换为用户友好的`ToolError`响应。
- **数据库路径解析（`bug_tracker_mcp.scope`）**：解析到单个共享SQLite数据库的路径：默认情况下为`$XDG_DATA_HOME/bug-tracker-mcp/bugs.db`（或`~/.local/share/bug-tracker-mcp/bugs.db`），如果覆盖，则为`$BUGTRACKER_ROOT/bugs.db`。
- **SQLite存储层（`bug_tracker_mcp.storage`）**：使用WAL日志模式、忙碌超时、通过`user_version`自动迁移和完整的CRUD操作管理SQLite连接。每个读写都按`项目`列范围限定，因此在一个项目下记录的错误对于另一个项目是不可见的，无法被修改。
- **Pydantic模型（`bug_tracker_mcp.models`）**：严格的Pydantic模型（`Bug`、`BugSummary`、`BugListResponse`）强制执行模式和类型响应。
- **环境配置（`bug_tracker_mcp.config`）**：读取用于共享数据库存储目录的可选环境变量覆盖。
---
## 安装与设置
使用[`uv`](https://github.com/astral-sh/uv)安装和管理依赖项：
```bash
# 克隆仓库
git clone https://github.com/realsidg/bug_tracker_mcp.git
cd bug_tracker_mcp
# 安装依赖项并设置虚拟环境
uv sync
```
---
## 代理配置
在您的代理工作区或桌面客户端中注册`bug-tracker-mcp`。
### 工作区 `.mcp.json`
在工作区根目录的 `.mcp.json` 中添加：
```json
{
"mcpServers": {
"bug-tracker": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/bug_tracker_mcp",
"bug-tracker-mcp"
]
}
}
}
```
### 克劳德桌面 (`claude_desktop_config.json`)
在 `~/Library/Application Support/Claude/claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"bug-tracker": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/bug_tracker_mcp",
"bug-tracker-mcp"
]
}
}
}
```
---
## 环境变量
您可以通过设置环境变量来覆盖存储位置：
| 变量 | 描述 | 默认值 |
| --- | --- | --- |
| `BUGTRACKER_ROOT` | 覆盖保存 `bugs.db` 文件的目录。 | `$XDG_DATA_HOME/bug-tracker-mcp` 或 `~/.local/share/bug-tracker-mcp`。 |
---
## 工具参考
`bug_tracker_mcp` 向 AI 代理公开了 6 种工具。每种工具都需要一个 `项目` 名称来标识属于该项目的错误 - 在跨调用中使用一致的名称（例如存储库名称），因为错误仅返回给传递匹配 `项目` 的调用者。
| 工具名称 | 参数 | 描述 |
| --- | --- | --- |
| `log_bug` | `项目`（字符串，必填）<br>`标题`（字符串，必填）<br>`描述`（字符串，可选）<br>`严重程度`（`minor` \| `major` \| `blocking`，默认为 `minor`）<br>`类型`（`bug` \| `improvement`，默认为 `bug`）<br>`位置`（字符串，可选）<br>`标签`（列表[字符串]，可选）<br>`发现于`（字符串，可选） | 将新的错误或改进记录到存储中，并返回创建的带有自动递增 ID 的 `Bug` 记录。 |
| `list_bugs` | `项目`（字符串，必填）<br>`状态`（`open` \| `fixed` \| `all`，默认为 `open`）<br>`严重程度`（`minor` \| `major` \| `blocking`，可选）<br>`类型`（`bug` \| `improvement` \| `all`，可选）<br>`标签`（字符串，可选）<br>`限制`（整数，默认为 50）<br>`偏移量`（整数，默认为 0） | 列出项目内的轻量级 `BugSummary` 项，并支持筛选和分页。 |
| `get_bug` | `项目`（字符串，必填）<br>`bug_id`（整数，必填） | 返回项目中特定错误的完整详细信息。如果未找到，则引发 `ToolError`。 |
| `update_bug` | `项目`（字符串，必填）<br>`bug_id`（整数，必填）<br>`标题`、`描述`、`严重程度`、`类型`、`位置`、`标签`、`发现于`、`状态`（可选） | 更新项目中现有错误的特定属性。如果未找到，则引发 `ToolError`。 |
| `resolve_bug` | `项目`（字符串，必填）<br>`bug_id`（整数，必填）<br>`解决方案`（字符串，可选） | 将错误标记为 `fixed`，设置可选的解决方案解释，并记录 `fixed_at` 时间戳。如果未找到，则引发 `ToolError`。 |
| `delete_bug` | `项目`（字符串，必填）<br>`bug_id`（整数，必填） | 永久删除项目中指定 ID 的错误。返回 `{"deleted": true, "bug_id": bug_id}` 或如果未找到则引发 `ToolError`。 |
---
## 开发与测试
运行所有质量检查：
```bash
# 运行 pytest 测试套件
uv run pytest
# 检查代码格式和 linting
uv run ruff check .
uv run ruff format --check .
# 在严格模式下运行静态类型检查器
uv run mypy src
# 运行 pre-commit 钩子
uv run pre-commit run --all-files
```
