# sooperset/mcp-atlassian architecture

> Architecture diagram of the GitHub repository sooperset/mcp-atlassian, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sooperset/mcp-atlassian
- Repository: https://github.com/sooperset/mcp-atlassian

## Overview

#### Purpose and Entry Points
MCP Atlassian is a Python Model Context Protocol server that exposes Jira and Confluence operations as AI-agent tools. It supports Atlassian Cloud and Server/Data Center. The package/server entry point is centered on `src/mcp_atlassian/servers/main.py`; service-specific MCP registrations live in `src/mcp_atlassian/servers/jira.py` and `src/mcp_atlassian/servers/confluence.py`.

#### MCP Server and Transport Layer
The server accepts MCP clients such as IDE agents over stdio and documented HTTP transports, then selects/configures lifecycle behavior, dependencies, error handling, and request context. This is the principal boundary between untrusted MCP requests and Atlassian operations.
- `src/mcp_atlassian/servers/main.py`
- `src/mcp_atlassian/servers/context.py`
- `src/mcp_atlassian/servers/error_handling.py`

OAuth-capable HTTP deployment includes a proxy layer and per-client storage rather than treating the process as only a single-user local stdio server.
- `src/mcp_atlassian/servers/oauth_proxy.py`
- `src/mcp_atlassian/servers/client_storage.py`
- `docs/http-transport.mdx`

#### Tool Registration, Policy, and Dispatch
Jira and Confluence server modules define the externally visible tool surface (98 tools). Toolsets and helpers organize registration and enforce tool-level selection/policy, while server dependency wiring obtains the appropriate configured clients. MCP tool calls are translated into domain-module calls and returned in MCP-compatible results.
- `src/mcp_atlassian/servers/jira.py`
- `src/mcp_atlassian/servers/confluence.py`
- `src/mcp_atlassian/utils/toolsets.py`

#### Jira Domain Adapter
The Jira adapter is organized by API capability: issues, search/JQL, projects, agile boards/sprints, transitions, comments, attachments, service management, forms, SLA, and metrics. It isolates Jira Cloud/Server API differences and request details behind a central client/configuration boundary.
- `src/mcp_atlassian/jira/client.py`
- `src/mcp_atlassian/jira/issues.py`
- `src/mcp_atlassian/jira/search.py`

Control flow is generally MCP tool → Jira domain operation → Jira client HTTP request → normalized model/result. Jira-specific preprocessing converts AI-friendly content into Jira formats before write operations.
- `src/mcp_atlassian/preprocessing/jira.py`
- `src/mcp_atlassian/jira/formatting.py`

#### Confluence Domain Adapter
The Confluence side similarly separates pages, search/CQL, spaces, comments, attachments, permissions/restrictions, templates, labels, users, and analytics. Its client handles deployment/API-version concerns, including a v2 adapter, so tool implementations need not directly encode transport variants.
- `src/mcp_atlassian/confluence/client.py`
- `src/mcp_atlassian/confluence/pages.py`
- `src/mcp_atlassian/confluence/v2_adapter.py`

Content preprocessing forms the write-path boundary between MCP text inputs and Confluence content representations.
- `src/mcp_atlassian/preprocessing/confluence.py`
- `src/mcp_atlassian/confluence/search.py`

#### Models and Shared Data Contracts
Typed/shared models represent Jira and Confluence API entities and normalize external payloads at the service boundary. They are the common contract used by domain operations, rather than exposing raw Atlassian JSON across the server layer.
- `src/mcp_atlassian/models/base.py`
- `src/mcp_atlassian/models/jira/issue.py`
- `src/mcp_atlassian/models/confluence/page.py`

#### Authentication, HTTP Security, and External Boundaries
External dependencies are Atlassian Jira and Confluence REST APIs, using Cloud API tokens, Server/Data Center personal access tokens, and OAuth 2.0 where configured. Shared utilities centralize credential/environment loading, OAuth setup/token validation, HTTP behavior, proxy support, SSL handling, pagination, and SSRF defenses.
- `src/mcp_atlassian/utils/oauth.py`
- `src/mcp_atlassian/utils/http.py`
- `src/mcp_atlassian/utils/ssrf_adapter.py`

#### Packaging and Deployment
The runtime is a Python package distributed for `uvx`/pip and containerized for production. Docker and Helm support running it as a networked MCP service, with Kubernetes deployment, service, ingress, secrets/config, RBAC, optional persistence, and autoscaling defined in the chart.
- `pyproject.toml`
- `Dockerfile`
- `helm/templates/deployment.yaml`

Main entry points: [`src/mcp_atlassian/servers/main.py`](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/servers/main.py) (Server entry point), [`src/mcp_atlassian/jira/issues.py`](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/jira/issues.py) (Jira domain operations), [`src/mcp_atlassian/confluence/pages.py`](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/confluence/pages.py) (Confluence domain operations), [`src/mcp_atlassian/utils/toolsets.py`](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/utils/toolsets.py) (Tool policy & selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP Runtime"]
  node_mcp_clients(("MCP clients<br/>external client"))
  node_server_main["Server entry point<br/>Python server<br/>[main.py]"]
  node_server_context_errors["Request context &amp; errors<br/>server middleware<br/>[context.py]"]
  node_tool_registration["Jira &amp; Confluence tools<br/>MCP tool surface<br/>[jira.py]"]
  node_toolsets["Tool policy &amp; selection<br/>tool dispatch<br/>[toolsets.py]"]
  node_oauth_http["OAuth HTTP proxy<br/>HTTP transport<br/>[oauth_proxy.py]"]
  node_client_storage[("Per-client storage<br/>client state<br/>[client_storage.py]")]
end

subgraph group_jira["Jira Adapter"]
  node_jira_operations["Jira domain operations<br/>domain adapter<br/>[issues.py]"]
  node_jira_preprocessing["Jira content formatting<br/>write preprocessing<br/>[jira.py]"]
  node_jira_client["Jira client<br/>API client<br/>[client.py]"]
end

subgraph group_confluence["Confluence Adapter"]
  node_confluence_operations["Confluence domain operations<br/>domain adapter<br/>[pages.py]"]
  node_confluence_preprocessing["Confluence content preprocessing<br/>write preprocessing<br/>[confluence.py]"]
  node_confluence_client["Confluence client &amp; v2 adapter<br/>API client<br/>[client.py]"]
end

subgraph group_shared["Shared Contracts &amp; Security"]
  node_shared_models["Normalized models<br/>data contracts<br/>[base.py]"]
  node_auth_http_security["Auth, HTTP &amp; SSRF controls<br/>security utilities<br/>[oauth.py]"]
end

subgraph group_deployment["Packaging &amp; Deployment"]
  node_package_container["Python package &amp; container<br/>distribution<br/>[pyproject.toml]"]
  node_helm_deployment["Helm Kubernetes deployment<br/>deployment chart<br/>[deployment.yaml]"]
end

node_atlassian_apis{{"Atlassian REST APIs<br/>external APIs"}}

node_mcp_clients -->|"stdio / HTTP requests"| node_server_main
node_server_main -->|"establishes context"| node_server_context_errors
node_server_main -->|"loads tools"| node_tool_registration
node_server_main -->|"network transport"| node_oauth_http
node_oauth_http -->|"client state"| node_client_storage
node_tool_registration -->|"selection policy"| node_toolsets
node_toolsets -->|"dispatches Jira calls"| node_jira_operations
node_toolsets -->|"dispatches Confluence calls"| node_confluence_operations
node_jira_operations -->|"formats writes"| node_jira_preprocessing
node_jira_operations -->|"uses"| node_jira_client
node_confluence_operations -->|"formats writes"| node_confluence_preprocessing
node_confluence_operations -->|"uses"| node_confluence_client
node_jira_operations -->|"normalized results"| node_shared_models
node_confluence_operations -->|"normalized results"| node_shared_models
node_jira_client -->|"authenticated HTTP"| node_auth_http_security
node_confluence_client -->|"authenticated HTTP"| node_auth_http_security
node_auth_http_security -->|"secured REST access"| node_atlassian_apis
node_package_container -.->|"packages runtime"| node_server_main
node_helm_deployment -->|"deploys container"| node_package_container
node_helm_deployment -.->|"hosts HTTP service"| node_oauth_http

click node_server_main "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/servers/main.py"
click node_server_context_errors "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/servers/context.py"
click node_tool_registration "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/servers/jira.py"
click node_toolsets "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/utils/toolsets.py"
click node_oauth_http "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/servers/oauth_proxy.py"
click node_client_storage "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/servers/client_storage.py"
click node_jira_operations "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/jira/issues.py"
click node_jira_preprocessing "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/preprocessing/jira.py"
click node_jira_client "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/jira/client.py"
click node_confluence_operations "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/confluence/pages.py"
click node_confluence_preprocessing "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/preprocessing/confluence.py"
click node_confluence_client "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/confluence/client.py"
click node_shared_models "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/models/base.py"
click node_auth_http_security "https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/utils/oauth.py"
click node_package_container "https://github.com/sooperset/mcp-atlassian/blob/main/pyproject.toml"
click node_helm_deployment "https://github.com/sooperset/mcp-atlassian/blob/main/helm/templates/deployment.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_clients,node_server_main,node_server_context_errors,node_tool_registration,node_toolsets,node_oauth_http,node_client_storage toneBlue
class node_jira_operations,node_jira_preprocessing,node_jira_client toneAmber
class node_confluence_operations,node_confluence_preprocessing,node_confluence_client toneMint
class node_shared_models,node_auth_http_security toneRose
class node_package_container,node_helm_deployment toneIndigo
class node_atlassian_apis toneNeutral
```

## Components

### MCP Runtime

MCP request boundary, tool registration, and HTTP deployment support.

- **MCP clients**: external client · IDE agents connect over stdio or HTTP.
- [Server entry point](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/servers/main.py): Python server · Configures lifecycle, dependencies, transport, and request context. · `src/mcp_atlassian/servers/main.py`
- [Request context & errors](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/servers/context.py): server middleware · Supplies request context and MCP-safe error handling. · `src/mcp_atlassian/servers/context.py`
- [Jira & Confluence tools](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/servers/jira.py): MCP tool surface · Registers the externally visible Jira and Confluence tools. · `src/mcp_atlassian/servers/jira.py`
- [Tool policy & selection](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/utils/toolsets.py): tool dispatch · Organizes toolsets and applies tool-level selection policy. · `src/mcp_atlassian/utils/toolsets.py`
- [OAuth HTTP proxy](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/servers/oauth_proxy.py): HTTP transport · Supports OAuth-capable network deployment and per-client state. · `src/mcp_atlassian/servers/oauth_proxy.py`
- [Per-client storage](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/servers/client_storage.py): client state · Stores state for HTTP/OAuth clients. · `src/mcp_atlassian/servers/client_storage.py`

### Jira Adapter

Jira operations and API compatibility boundary.

- [Jira domain operations](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/jira/issues.py): domain adapter · Issues, JQL search, projects, agile, service management, and write operations. · `src/mcp_atlassian/jira/issues.py`
- [Jira content formatting](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/preprocessing/jira.py): write preprocessing · Converts AI-friendly content into Jira representations. · `src/mcp_atlassian/preprocessing/jira.py`
- [Jira client](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/jira/client.py): API client · Centralizes Cloud and Server/Data Center request differences. · `src/mcp_atlassian/jira/client.py`

### Confluence Adapter

Confluence operations and API compatibility boundary.

- [Confluence domain operations](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/confluence/pages.py): domain adapter · Pages, CQL search, spaces, content, permissions, and attachments. · `src/mcp_atlassian/confluence/pages.py`
- [Confluence content preprocessing](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/preprocessing/confluence.py): write preprocessing · Transforms MCP text inputs into Confluence content representations. · `src/mcp_atlassian/preprocessing/confluence.py`
- [Confluence client & v2 adapter](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/confluence/client.py): API client · Hides deployment, API-version, and v2 transport variants. · `src/mcp_atlassian/confluence/client.py`

### Shared Contracts & Security

Normalized entities and shared external-access controls.

- [Normalized models](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/models/base.py): data contracts · Typed Jira and Confluence entities isolate server code from raw API payloads. · `src/mcp_atlassian/models/base.py`
- [Auth, HTTP & SSRF controls](https://github.com/sooperset/mcp-atlassian/blob/main/src/mcp_atlassian/utils/oauth.py): security utilities · Centralizes credentials, OAuth, HTTP behavior, SSL, pagination, and SSRF defenses. · `src/mcp_atlassian/utils/oauth.py`

### Packaging & Deployment

Local package, container, and Kubernetes deployment artifacts.

- [Python package & container](https://github.com/sooperset/mcp-atlassian/blob/main/pyproject.toml): distribution · Distributed through pip/uvx and packaged for container runtime. · `pyproject.toml`
- [Helm Kubernetes deployment](https://github.com/sooperset/mcp-atlassian/blob/main/helm/templates/deployment.yaml): deployment chart · Deploys networked MCP service with ingress, secrets, RBAC, persistence, and autoscaling options. · `helm/templates/deployment.yaml`

### Other components

- **Atlassian REST APIs**: external APIs · Jira and Confluence Cloud or Server/Data Center endpoints.

## Connections

- MCP clients → Server entry point: stdio / HTTP requests
- Server entry point → Request context & errors: establishes context
- Server entry point → Jira & Confluence tools: loads tools
- Server entry point → OAuth HTTP proxy: network transport
- OAuth HTTP proxy → Per-client storage: client state
- Jira & Confluence tools → Tool policy & selection: selection policy
- Tool policy & selection → Jira domain operations: dispatches Jira calls
- Tool policy & selection → Confluence domain operations: dispatches Confluence calls
- Jira domain operations → Jira content formatting: formats writes
- Jira domain operations → Jira client: uses
- Confluence domain operations → Confluence content preprocessing: formats writes
- Confluence domain operations → Confluence client & v2 adapter: uses
- Jira domain operations → Normalized models: normalized results
- Confluence domain operations → Normalized models: normalized results
- Jira client → Auth, HTTP & SSRF controls: authenticated HTTP
- Confluence client & v2 adapter → Auth, HTTP & SSRF controls: authenticated HTTP
- Auth, HTTP & SSRF controls → Atlassian REST APIs: secured REST access
- Python package & container → Server entry point: packages runtime
- Helm Kubernetes deployment → Python package & container: deploys container
- Helm Kubernetes deployment → OAuth HTTP proxy: hosts HTTP service
