mcp-atlassian copilot-instructions.md

MCP Atlassian - Development Guide

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

Build, Test, and Lint

Dependencies:

uv sync --frozen --all-extras --dev  # Install all dependencies

Code Quality (required before commit):

pre-commit run --all-files           # Run all checks: ruff, prettier, mypy

Testing:

# 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:

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:

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/