# bug_tracker_mcp

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/MCP-FastMCP%203.x-green.svg)](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
```