mcp-atlassian-user

# MCP Atlassian - Development Guide

Model Context Protocol (MCP) server for Atlassian products (Jira & Confluence). Python ≥3.10.

## Build, Test, and Lint

**Dependencies**:
```bash
uv sync --frozen --all-extras --dev  # Install all dependencies
```

**Code Quality** (required before commit):
```bash
pre-commit run --all-files           # Run all checks: ruff, prettier, mypy
```

**Testing**:
```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=mcp_atlassian

# Run single test file
uv run pytest tests/unit/test_preprocessing.py

# Run single test function
uv run pytest tests/unit/test_preprocessing.py::test_specific_function
```

**Running the Server**:
```bash
uv run mcp-atlassian                 # Start MCP server
uv run mcp-atlassian --oauth-setup   # OAuth configuration wizard
uv run mcp-atlassian -v              # Verbose logging mode
```

## Architecture

### Mixin-Based Composition
Functionality is organized into **focused mixins** that compose together:
- **Jira**: `JiraFetcher` inherits from 13 feature mixins (ProjectsMixin, IssuesMixin, WorklogMixin, etc.)
- **Confluence**: `ConfluenceFetcher` inherits from 7 feature mixins (SearchMixin, PagesMixin, SpacesMixin, etc.)

Each mixin lives in its own module under `src/mcp_atlassian/jira/` or `src/mcp_atlassian/confluence/`.

### Client + Fetcher Pattern
- **Client classes** (`JiraClient`, `ConfluenceClient`): Authentication, configuration, and API session management
- **Fetcher classes** (`JiraFetcher`, `ConfluenceFetcher`): Business operations by composing mixins; inherit from Client

### Protocol-Based Dependencies
Mixins declare dependencies via Protocol interfaces instead of direct imports:
```python
class IssuesMixin(AttachmentsOperationsProto, FieldsOperationsProto):
    # Mixin knows it needs attachment and field operations
    # Protocols define the contract without circular imports
```

The final Fetcher class satisfies all protocols through multiple inheritance.

### Data Models
- All models extend `ApiModel` base class with `from_api_response()` for deserialization
- Use `TimestampMixin` for timestamp handling across Jira/Confluence models
- Models support `to_simplified_dict()` for MCP tool responses
- Located in `src/mcp_atlassian/models/`

### MCP Server Layer
Servers (`src/mcp_atlassian/servers/`) use FastMCP framework:
- Instantiate Fetchers via dependency injection (`get_jira_fetcher()`, `get_confluence_fetcher()`)
- Wrap fetcher methods as MCP tools using `@mcp.tool()` decorator
- Handle error conversion and response serialization
- Support read-only and write modes

## Key Conventions

### Package Management
**Always use `uv`, never `pip`**. This is a hard requirement for dependency management.

### Branching Strategy
**Never work on `main`**. Always create feature branches:
```bash
git checkout -b feature/your-feature-name   # For new features
git checkout -b fix/issue-description       # For bug fixes
```

### Tool Naming
MCP tools follow the pattern: `{service}_{action}`
- Examples: `jira_create_issue`, `confluence_get_page`, `jira_search`

### Type Safety
- All functions require type hints
- Use modern union syntax: `str | None` (not `Optional[str]`)
- Use `type[T]` for class types
- Collections: `list[str]`, `dict[str, Any]`

### Code Style
- **Line length**: 88 characters maximum (enforced by ruff)
- **Imports**: Absolute imports, sorted by ruff
- **Naming**: `snake_case` for functions/variables, `PascalCase` for classes
- **Docstrings**: Google-style format for all public APIs
- **Error handling**: Use specific exceptions, avoid bare `except:`

### Testing
- New features require tests
- Bug fixes require regression tests
- Test files mirror source structure: `tests/unit/` and `tests/integration/`
- Use fixtures from `tests/fixtures/` for test data

### Commit Messages
Use git trailers for attribution:
```bash
git commit --trailer "Reported-by:<name>"          # For bug reports
git commit --trailer "Github-Issue:#<number>"      # For issue references
```

**Never mention tools or AI assistants in commit messages**.

## Authentication Support
The codebase supports multiple authentication methods:
- **API Tokens**: Cloud deployments (username + token)
- **Personal Access Tokens (PAT)**: Server/Data Center deployments
- **OAuth 2.0**: Interactive user authentication with consent flow

Auth configuration lives in `src/mcp_atlassian/utils/auth.py`.

## Pre-commit Hooks
Pre-commit runs:
- **ruff-format**: Auto-format Python code
- **ruff**: Lint with auto-fix (select rules in pyproject.toml)
- **mypy**: Type checking (currently lenient, see TODO comments in .pre-commit-config.yaml)
- **prettier**: Format YAML/JSON
- **Standard checks**: trailing whitespace, file endings, YAML/TOML validity

Tests are **not** run by pre-commit hooks—run them manually with `uv run pytest`.