# MCP Atlassian

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

---

## Repository map

| Path | Purpose |
| --- | --- |
| `src/mcp_atlassian/` | Library source (Python ≥ 3.10) |
| `  ├─ jira/` | Jira client + mixins (issues, search, SLA, metrics, …) |
| `  ├─ confluence/` | Confluence client + 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` and `ConfluenceFetcher` are composed from the mixins listed in their `__init__.py`; 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
```