bug_tracker_mcp

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 across project-local (git repo root .bugtracker/bugs.db) or global system (~/.local/share/bug-tracker-mcp/bugs.db) scopes.

---

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, scope resolution, and converts internal exceptions to user-friendly ToolError responses.
• Scope Resolution (bug_tracker_mcp.scope): Automatically detects local project root by walking parent directories for .git or respects explicit directory overrides. Supports two scopes:
  • local (default): <git_root>/.bugtracker/bugs.db
  • global: $XDG_DATA_HOME/bug-tracker-mcp/bugs.db (or ~/.local/share/bug-tracker-mcp/bugs.db)
• 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.
• Pydantic Models (bug_tracker_mcp.models): Strict Pydantic models (Bug, BugSummary, BugListResponse) enforcing schema and typed responses.
• Environment Configuration (bug_tracker_mcp.config): Reads optional environment variable overrides for custom local/global database paths.

---

Installation & Setup

Install and manage dependencies using uv:

# 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:

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

{
  "mcpServers": {
    "bug-tracker": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/bug_tracker_mcp",
        "bug-tracker-mcp"
      ]
    }
  }
}

---

Environment Variables

You can override storage locations by setting environment variables:

Variable	Description	Default
BUGTRACKER_LOCAL_ROOT	Overrides root directory for local scope storage (.bugtracker/bugs.db created inside this path).	Nearest directory containing .git (or current directory if none found).
BUGTRACKER_GLOBAL_ROOT	Overrides root directory for global scope storage (bugs.db created inside this path).	$XDG_DATA_HOME/bug-tracker-mcp or ~/.local/share/bug-tracker-mcp.

---

Tool Reference

bug_tracker_mcp exposes 6 tools to AI agents:

Tool Name	Parameters	Description
log_bug	title (str, required)<br>description (str, optional)<br>severity (minor | major | blocking, default: minor) <br>location (str, optional)<br>tags (list[str], optional)<br>found_while (str, optional)<br>scope (local | global, default: local)	Logs a new bug into storage and returns the created Bug record with auto-incremented ID.
list_bugs	status (open | fixed | all, default: open)<br>severity (minor | major | blocking, optional)<br>tag (str, optional)<br>limit (int, default: 50)<br>offset (int, default: 0)<br>scope (local | global, default: local)	Lists lightweight BugSummary items with filtering and pagination.
get_bug	bug_id (int, required)<br>scope (local | global, default: local)	Returns complete details of a specific bug by ID. Raises ToolError if not found.
update_bug	bug_id (int, required)<br>title, description, severity, location, tags, found_while, status (optional)<br>scope (local | global, default: local)	Updates specific attributes of an existing bug. Raises ToolError if not found.
resolve_bug	bug_id (int, required)<br>resolution (str, optional)<br>scope (local | global, default: local)	Marks a bug as fixed, sets optional resolution explanation, and records fixed_at timestamp. Raises ToolError if not found.
delete_bug	bug_id (int, required)<br>scope (local | global, default: local)	Permanently removes a bug by ID. Returns {"deleted": true, "bug_id": bug_id} or raises ToolError if not found.

---

Development & Testing

Run all quality checks:

# 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