Skip to content

AGENTS.md

Latest commit

 

History

History
96 lines (72 loc) · 3.8 KB

AGENTS.md

File metadata and controls

96 lines (72 loc) · 3.8 KB

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

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

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

# 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