Confluence MCP Server

Implements a FastMCP-based server that exposes 72 Atlassian tools across three transport modes: stdio for IDE integration, Server-Sent Events for real-time streaming, and streamable-http for service deployments. The server uses a layered architecture with AtlassianMCP as the main entry point that mounts jira_mcp and confluence_mcp sub-servers, each with their own tool registries. Transport selection is determined at CLI invocation time via argument parsing in the main() function, with the server lifecycle managed through async context managers (main_lifespan) that handle startup/shutdown of shared configuration state.

Exposes a search capability that queries Confluence pages using the Confluence REST API's CQL (Confluence Query Language) engine, supporting full-text search across page titles and content bodies, combined with metadata filters (space, labels, created date, author). The search operation is implemented as a tool that constructs CQL queries from user parameters, executes them against the Confluence client, and returns paginated results with page metadata (ID, title, space key, URL, last modified). Results are limited to 50 pages per request with pagination support via start index.

Implements a flexible authentication system supporting multiple credential types: API tokens (Jira/Confluence Cloud), Personal Access Tokens (Server/Data Center), OAuth 2.0 3LO (three-legged OAuth for user delegation), and bring-your-own-token scenarios. Authentication is configured via environment variables (for single-tenant deployments) or HTTP headers (for multi-tenant deployments). The system uses a credential resolver that detects the deployment type (Cloud vs Server/Data Center) and selects the appropriate authentication method. OAuth 2.0 flows are handled through a token manager that handles refresh token rotation and expiration.

Uses the FastMCP framework's dependency injection system to manage tool registration, configuration, and lifecycle. Tools are registered as decorated Python functions with type hints and docstrings that are automatically converted to MCP tool schemas. The DI container manages shared state (JiraClient, ConfluenceClient, configuration) and injects dependencies into tool functions at runtime. Tool discovery is automatic — all registered tools are exposed to MCP clients without manual schema definition. The system supports tool access control through decorators that enforce permission checks before tool execution.

Implements comprehensive error handling across all Atlassian API calls with automatic retry logic for transient failures (rate limits, timeouts, 5xx errors). The system uses exponential backoff with jitter to avoid thundering herd problems when retrying failed requests. Errors are categorized (client errors, server errors, rate limits, timeouts) and mapped to MCP error responses with actionable messages. The retry logic respects Atlassian API rate limit headers (Retry-After) and adjusts backoff timing accordingly.

Implements automatic detection and adaptation of Atlassian API differences between Cloud and Server/Data Center deployments. The system detects the deployment type at initialization (via URL pattern or explicit configuration), and routes API calls to the appropriate endpoint format. Content transformation (for Confluence pages) adapts to different storage formats between Cloud and Server/Data Center. JQL dialects are adapted for Jira Cloud vs Server/Data Center differences. The implementation maintains a compatibility matrix that documents known differences and applies appropriate transformations.

Retrieves full Confluence page content by page ID and transforms it from Confluence's native storage format (XHTML-like markup) into plain text or markdown for AI consumption. The implementation uses a content transformation layer (ContentTransformer) that parses Confluence storage format, extracts text content, preserves heading hierarchy and list structure, and handles Cloud vs Server/Data Center format differences automatically. The page read operation also returns metadata (title, space, author, created/modified dates, labels) and supports retrieving page hierarchy (parent/child relationships).

Enables creating new Confluence pages or updating existing pages with content validation and conflict detection. The implementation accepts page content in plain text or markdown, validates the input against Confluence's storage format constraints, constructs the appropriate REST API payload, and executes the create/update operation. Update operations include version conflict detection (using page version numbers) to prevent overwriting concurrent edits. The tool returns the created/updated page ID, URL, and version number for subsequent operations.

Provides tools to explore Confluence space structure and page hierarchies, including listing all spaces in a workspace, retrieving pages within a space, and traversing parent-child page relationships. The implementation queries the Confluence API to fetch space metadata (space key, name, description, type) and page trees, returning hierarchical structures that show page nesting. This capability enables AI agents to understand documentation organization and navigate to relevant sections without full-text search.

Implements issue search using Jira Query Language (JQL), a powerful query syntax that supports complex filtering by issue type, status, assignee, priority, labels, custom fields, and temporal conditions. The search tool constructs JQL queries from user parameters, executes them against the Jira API, and returns paginated results with issue metadata (key, summary, status, assignee, priority, created/updated dates). The implementation handles Cloud vs Server/Data Center JQL dialect differences and supports saved filters (JQL stored in Jira).

Enables creating new Jira issues or updating existing issues with automatic field validation, required field detection, and workflow state transition support. The implementation queries the Jira API to fetch issue type schemas (which fields are required, their types, and allowed values), validates user input against these schemas, constructs the appropriate REST API payload, and executes the create/update operation. Update operations support workflow transitions (e.g., moving an issue from 'Open' to 'In Progress') by detecting available transitions and applying the requested state change.

Provides tools to add comments to Jira issues and log work (time tracking) on issues. The implementation supports creating comments with optional mention syntax (@user), adding internal comments (visible only to Jira administrators), and logging work with time estimates and work descriptions. Worklog entries are tracked separately from comments and contribute to issue time tracking metrics. The tools return comment/worklog IDs and timestamps for subsequent operations.

Exposes Jira Agile (Scrum and Kanban) board operations, including listing boards, retrieving sprint information, moving issues between sprints or board columns, and querying sprint metrics. The implementation queries the Jira Agile API (separate from the core Jira API) to fetch board configurations, active sprints, and issue assignments. Sprint operations support moving issues to different sprints, starting/ending sprints, and retrieving sprint velocity and burndown data. Board operations support moving issues between columns (workflow states) on Kanban boards.

Provides tools to query Jira's issue type and custom field schemas, enabling AI agents to discover what fields are available, which are required, what values are allowed, and how to format field values for create/update operations. The implementation caches schema information per project and issue type, reducing API calls for repeated queries. Schema discovery returns field metadata including field type (text, select, date, etc.), allowed values for select fields, and validation rules.