Content
# bug_tracker_mcp
[](https://www.python.org/downloads/)
[](https://github.com/jlowin/fastmcp)
A lean, agent-first Model Context Protocol (MCP) server for tracking bugs, tasks, and context across coding sessions. Designed to give AI agents (like Claude Desktop, Antigravity, and Cursor) zero-friction persistent memory for issues discovered during development.
---
## Overview
When pair-programming with AI agents, bugs and technical debt are frequently discovered mid-task. Without a persistent tracker, these issues get lost when context windows reset.
`bug_tracker_mcp` solves this with a lightweight SQLite-backed MCP server. It provides 6 fast MCP tools allowing agents to log, inspect, update, resolve, and delete bugs, all isolated per project. Every tool call requires an explicit `project` name (e.g. the repo name) supplied by the calling agent; the server never infers it from its own working directory, since a single long-lived MCP process can serve many different projects across a session.
---
## Architecture
The system is organized into decoupled Python modules:
- **FastMCP Server (`bug_tracker_mcp.server`)**: Defines stdio transport MCP tools using `fastmcp.FastMCP`. Handles argument validation, requires a `project` name on every call, and converts internal exceptions to user-friendly `ToolError` responses.
- **Database Path Resolution (`bug_tracker_mcp.scope`)**: Resolves the path to the single shared SQLite database: `$XDG_DATA_HOME/bug-tracker-mcp/bugs.db` (or `~/.local/share/bug-tracker-mcp/bugs.db`) by default, or `$BUGTRACKER_ROOT/bugs.db` if overridden.
- **SQLite Storage Layer (`bug_tracker_mcp.storage`)**: Manages SQLite connections with WAL journal mode, busy timeouts, auto-migrations via `user_version`, and full CRUD operations. Every read and write is scoped by a `project` column, so bugs logged under one project are invisible to and cannot be mutated from another.
- **Pydantic Models (`bug_tracker_mcp.models`)**: Strict Pydantic models (`Bug`, `BugSummary`, `BugListResponse`) enforcing schema and typed responses.
- **Environment Configuration (`bug_tracker_mcp.config`)**: Reads an optional environment variable override for the shared database's storage directory.
---
## Installation & Setup
Install and manage dependencies using [`uv`](https://github.com/astral-sh/uv):
```bash
# Clone repository
git clone https://github.com/realsidg/bug_tracker_mcp.git
cd bug_tracker_mcp
# Install dependencies and setup virtual environment
uv sync
```
---
## Agent Configuration
Register `bug-tracker-mcp` with your agent workspace or desktop client.
### Workspace `.mcp.json`
Add to `.mcp.json` in your workspace root:
```json
{
"mcpServers": {
"bug-tracker": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/bug_tracker_mcp",
"bug-tracker-mcp"
]
}
}
}
```
### Claude Desktop (`claude_desktop_config.json`)
Add to `~/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"
]
}
}
}
```
---
## Environment Variables
You can override the storage location by setting an environment variable:
| Variable | Description | Default |
| --- | --- | --- |
| `BUGTRACKER_ROOT` | Overrides the directory holding the shared `bugs.db` file. | `$XDG_DATA_HOME/bug-tracker-mcp` or `~/.local/share/bug-tracker-mcp`. |
---
## Tool Reference
`bug_tracker_mcp` exposes 6 tools to AI agents. Every tool requires a `project` name identifying which project the bugs belong to — use a consistent name (e.g. the repo name) for the same project across calls, since bugs are only ever returned to callers passing the matching `project`.
| Tool Name | Parameters | Description |
| --- | --- | --- |
| `log_bug` | `project` (str, required)<br>`title` (str, required)<br>`description` (str, optional)<br>`severity` (`minor` \| `major` \| `blocking`, default: `minor`)<br>`kind` (`bug` \| `improvement`, default: `bug`)<br>`location` (str, optional)<br>`tags` (list[str], optional)<br>`found_while` (str, optional) | Logs a new bug or improvement into storage and returns the created `Bug` record with auto-incremented ID. |
| `list_bugs` | `project` (str, required)<br>`status` (`open` \| `fixed` \| `all`, default: `open`)<br>`severity` (`minor` \| `major` \| `blocking`, optional)<br>`kind` (`bug` \| `improvement` \| `all`, optional)<br>`tag` (str, optional)<br>`limit` (int, default: 50)<br>`offset` (int, default: 0) | Lists lightweight `BugSummary` items within a project with filtering and pagination. |
| `get_bug` | `project` (str, required)<br>`bug_id` (int, required) | Returns complete details of a specific bug by ID within a project. Raises `ToolError` if not found. |
| `update_bug` | `project` (str, required)<br>`bug_id` (int, required)<br>`title`, `description`, `severity`, `kind`, `location`, `tags`, `found_while`, `status` (optional) | Updates specific attributes of an existing bug within a project. Raises `ToolError` if not found. |
| `resolve_bug` | `project` (str, required)<br>`bug_id` (int, required)<br>`resolution` (str, optional) | Marks a bug as `fixed`, sets optional resolution explanation, and records `fixed_at` timestamp. Raises `ToolError` if not found. |
| `delete_bug` | `project` (str, required)<br>`bug_id` (int, required) | Permanently removes a bug by ID within a project. Returns `{"deleted": true, "bug_id": bug_id}` or raises `ToolError` if not found. |
---
## Development & Testing
Run all quality checks:
```bash
# Run pytest test suite
uv run pytest
# Check code formatting and linting
uv run ruff check .
uv run ruff format --check .
# Run static type checker in strict mode
uv run mypy src
# Run pre-commit hooks
uv run pre-commit run --all-files
```
