gerrit-mcp-server AGENTS.md

Gerrit MCP Server Development Guide

Overview

This document serves as the comprehensive guide for developing, testing, and maintaining the gerrit-mcp-server. It provides practical instructions for all stages of the development lifecycle.

Development Environment

Prerequisites

• Python 3.12+
• uv (the build script will install it via pip if absent)

Setup

The project uses uv for dependency management. uv.lock is committed to the repository to ensure reproducible installs.

1. Run the build script:

   ./build-gerrit.sh
   

   This will create a virtual environment in .venv and install all dependencies (including dev extras) via uv sync.

2. Activate the virtual environment:

   source .venv/bin/activate
   

[!IMPORTANT] ALWAYS use the virtual environment's Python. Never use the system Python.

Testing Standards

We use pytest as our testing framework.

Structure

• Files: test_*.py
• Functions: Descriptive names like test_query_changes_returns_results.
• Pattern: Arrange, Act, Assert.

Fixtures

• Use pytest fixtures for setup and dependency injection.
• Place shared fixtures in conftest.py.
• Use unittest.mock.patch as a context manager or fixture.

Running Tests

Run tests from the project root (no venv activation needed):

uv run pytest

Making any changes to source

If any changes to source are ever made, you must run uv run pytest to validate that the changes did not break any tests. Ask the user first after any changes are made.

Code Style

Use the /astral:ruff skill if available. Otherwise, to fix and format:

uv run ruff check --fix . && uv run ruff format .

To check without modifying: uv run ruff check . && uv run ruff format --check .

Documentation

User-facing documentation lives in the docs/ directory. Keep it in sync with code changes — docs are part of the deliverable, not an afterthought.