Architecture Overview¶

Two thin interface layers (Typer CLIs and the FastMCP server) sit on shared HTTP clients. All Jira and Confluence logic lives in the clients and converters; the interfaces hold argument parsing and output formatting only.

graph TB
    subgraph Interfaces
        CLI[jira / confluence CLI]
        SHELL[jira shell]
        MCP[jira-mcp server]
    end
    subgraph Core
        JC[JiraClient]
        CC[ConfluenceClient]
        ADF[markdown to ADF]
        STO[markdown to storage format]
        Q[quality scoring]
    end
    CLI --> JC
    CLI --> CC
    SHELL --> JC
    MCP --> JC
    MCP --> CC
    CLI --> Q
    MCP --> Q
    JC --> ADF
    CC --> STO

Modules¶

Surface parity¶

Every capability is exposed on both the CLI (jira, confluence) and the MCP server. tests/test_surface_parity.py declares the mapping from MCP tool name to CLI command path and fails when an MCP tool has no CLI command or a CLI command has no MCP tool. The only CLI commands outside the mapping are config and shell, which have no MCP equivalent by design. Adding a capability means adding it to the client, both surfaces, and the mapping in one change.

Data models¶

class Issue:
    key: str  # "PROJ-123"
    summary: str
    status: str
    assignee: str | None  # display name
    reporter: str | None  # display name
    project: str
    priority: str | None
    created: datetime
    updated: datetime
    due_date: date | None
    description: str | None
    attachments: list[Attachment]
    labels: list[str]
    components: list[str]  # component names
    fix_versions: list[str]  # version names


class Comment:
    id: str
    author: str
    body: str
    created: datetime


class User:
    account_id: str
    display_name: str
    email: str | None  # may be None for privacy
    active: bool
    avatar_url: str | None


class Space:
    id: str  # numeric
    key: str  # "DEV"
    name: str
    type: str  # "global", "personal"
    status: str


class Page:
    id: str  # numeric
    title: str
    space_id: str | None  # absent in search results
    status: str
    version: int | None  # absent in search results
    body: str | None  # storage XHTML, only when fetched in full
    url: str | None  # server-relative web UI path

Issue field writes¶

IssueCreateParams and IssueUpdateParams carry the same metadata fields. People fields (assignee, reporter) are account IDs; setting the reporter requires the "Modify Reporter" project permission. components and fix_versions are lists of names that must already exist in the project; an update replaces the stored list. due_date is an ISO date. Fields left as None are not sent. Subtasks are ordinary issues with parent set:

client.create_issue(
    IssueCreateParams(
        project="PROJ", summary="Subtask", issue_type="Sub-task", parent="PROJ-123"
    )
)

API endpoints¶

Jira uses REST API v3. Confluence CRUD uses REST API v2; CQL search uses the v1 endpoint, which has no v2 equivalent.

Updating a page requires the current version number; the client fetches the page first and submits the incremented version.