mcp-atlassian (Agent Skills)

# MCP Atlassian

> **Audience**: LLM-driven engineering agents

---

## Repository map

| Path | Purpose |
| --- | --- |
| `src/mcp_atlassian/` | Library source (Python ≥ 3.10) |
| `  ├─ jira/` | Jira client + 21 mixins (issues, search, SLA, metrics, …) |
| `  ├─ confluence/` | Confluence client + 8 mixins (pages, search, analytics, …) |
| `  ├─ models/` | Pydantic v2 data models (`ApiModel` base) |
| `  ├─ servers/` | FastMCP server instances (`jira_mcp`, `confluence_mcp`) |
| `  ├─ preprocessing/` | Content conversion (ADF/Storage → Markdown) |
| `  └─ utils/` | Shared utilities (auth, logging, SSL, decorators) |
| `tests/` | Pytest suite — unit, integration, real-API validation |
| `scripts/` | OAuth setup and testing scripts |

---

## Architecture

- **Mixin composition**: `JiraFetcher` composes 21 mixins, `ConfluenceFetcher` composes 8. Client inheritance is transitive through mixins.
- **FastMCP servers**: `servers/main.py` → lifespan → dependency injection via `get_jira_fetcher(ctx)` / `get_confluence_fetcher(ctx)`.
- **Tool naming**: `{service}_{action}_{target}` (e.g., `jira_create_issue`, `confluence_get_page`).
- **Config**: Environment-based `from_env()` factory on `JiraConfig` / `ConfluenceConfig` dataclasses.
- **Auth**: Basic (Cloud + Server/DC), PAT (Server/DC), OAuth 2.0 (Cloud + Server/DC) — with multi-tenant header support.
- **Models**: All extend `ApiModel` → `from_api_response()` + `to_simplified_dict()`.

---

## Dev workflow

```bash
uv sync --frozen --all-extras --dev  # install dependencies
pre-commit install                    # setup hooks
pre-commit run --all-files           # Ruff + mypy
uv run pytest -xvs                   # full test suite
uv run pytest tests/unit/ -xvs       # unit tests only
uv run pytest tests/integration/     # integration tests
uv run pytest --cov=src/mcp_atlassian --cov-report=term-missing  # coverage
```

*Tests must pass* and *lint/typing must be clean* before committing.

---

## Rules

1. **Package management**: ONLY use `uv`, NEVER `pip`
2. **Branching**: NEVER work on `main`, always create feature branches
3. **Type safety**: All functions require type hints
4. **Testing**: New features need tests, bug fixes need regression tests
5. **Commits**: Use trailers for attribution, never mention tools/AI
6. **Commit types**: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci` — scopes: `jira`, `confluence`, `server`, `auth`, `docker`, `docs`
7. **File hygiene**: Prefer editing existing files over creating new ones
8. **Tool docs**: After changing tool signatures or registrations, run `uv run python scripts/generate_tool_docs.py` and commit the diff; CI (`Docs / check`) enforces this

---

## Code conventions

- **Language**: Python ≥ 3.10
- **Line length**: 88 characters maximum
- **Imports**: Absolute imports, sorted by Ruff
- **Naming**: `snake_case` functions, `PascalCase` classes
- **Docstrings**: Google-style for all public APIs
- **Error handling**: Specific exceptions only

---

## Gotchas

- **Cloud vs Server/DC**: API endpoints, field names, and auth methods differ. Always check `is_cloud` before assuming behavior.
- **OAuth 2.0**: Supported on both Cloud and Server/Data Center. PAT is also available for Server/DC. Basic auth (user + API token) works on both Cloud and Server/DC.
- **Read-only mode**: `READ_ONLY_MODE=true` blocks all write tools at server level.
- **Type checking**: pre-commit runs **mypy** (strict mode).
- **Environment**: See `.env.example` for all configuration options (auth, proxy, SLA, filtering).

---

## Quick reference

```bash
# Running the server
uv run mcp-atlassian                 # Start server
uv run mcp-atlassian --oauth-setup   # OAuth wizard
uv run mcp-atlassian -v              # Verbose mode

# Git workflow
git checkout -b feature/description   # New feature
git checkout -b fix/issue-description # Bug fix
git commit --trailer "Reported-by:<name>"      # Attribution
git commit --trailer "Github-Issue:#<number>"  # Issue reference
```

# 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`.