# livshitsa/al-mcp-atlassian architecture

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

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

## Overview

##### Main Components
- MCP Server: Central component that handles client requests and exposes integration endpoints.
- Confluence Module: Includes the client, configuration, and tools for managing Confluence pages, comments, spaces, and search operations.
- Model Layer: Defined under the “models” directory; holds representations and abstractions for the data exchanged with Atlassian APIs.
- Preprocessing: An intermediary layer in “preprocessing” that may transform or prepare data before sending off to external APIs.
- External Clients: Include various interfaces (CLI via uvx, Docker containers, IDE integration setups for Cursor and Claude) that start and interact with the MCP server.
- API/Transport Layers: Based on README, you have different transport options such as stdio and SSE, which govern how data flows between the MCP server and the client tools.
- Testing/MOCK Layer: Although not part of production, the comprehensive tests (unit, integration, fixtures) inform us about relevant boundaries and expected inputs/outputs.

##### Out Component Relationships and Interactions
- A “Confluence Client” module (from src/mcp_atlassian/confluence) which communicates with external Confluence Cloud or Server/Data Center endpoints, using configuration data and API tokens.
- A “Jira Client” module (as identified by tests in tests/unit/jira) that interfaces with Jira endpoints.
- A “Model Layer” that both clients reference to create or use domain objects.
- A “Preprocessing” component that prepares or validates data before invoking client operations.
- External integrations:
- Transport layer:

##### Architectural Patterns and Design Principles
- Modular Design: The project is neatly modularized with separate directories for integration (confluence and jira), models, and preprocessing functionality.
- Layered Architecture: Clearly separate core logic (server, data models) from peripheral concerns (CLI integration, configuration).
- Dependency Injection/Configuration: External configuration is loaded via environment variables, command-line arguments, or files (e.g., Docker’s .env), emphasizing the need for clear configuration boundaries.
- Testing and Mocks: Strong emphasis on testing with unit and fixture directories promotes a design that isolates components for better maintainability.

##### Relevant Technologies and Frameworks
- Python as the core programming language.
- uvx (and by extension, uv) as the CLI interface.
- Docker and PIP are options for deployment and installation.
- The integration hints at the use of Atlassian’s API (for both Confluence and Jira) using HTTP interactions.
- Tools like mypy and configuration files (pyproject.toml, ruff.toml) indicate static type checking and linting enforcement.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Clients
    subgraph "External Clients"
        cli["CLI (uvx)"]:::external
        docker["Docker Deployment"]:::external
        ide["IDE Integration (Cursor & Claude)"]:::external
    end

    %% Transport Layers
    subgraph "Transport Layers"
        stdio["Stdio Transport"]:::transport
        sse["SSE Transport"]:::transport
    end

    %% External APIs
    subgraph "Atlassian APIs"
        confluenceAPI["Confluence API"]:::external
        jiraAPI["Jira API"]:::external
    end

    %% Internal Core
    mcpServer["MCP Server"]:::server

    subgraph "Internal Modules"
        confluenceModule["Confluence Module"]:::module
        jiraModule["Jira Module"]:::module
        modelLayer["Model Layer"]:::module
        preprocessing["Preprocessing Module"]:::module
    end

    %% Testing and Mocks
    testingLayer["Testing/MOCK Layer"]:::module

    %% Connections: External Clients -> MCP Server using Transports
    cli -->|"via stdio/SSE"| mcpServer
    docker -->|"via stdio/SSE"| mcpServer
    ide -->|"via stdio/SSE"| mcpServer

    %% MCP Server Internal Interactions
    mcpServer -->|"calls"| preprocessing
    preprocessing -->|"processes data for"| confluenceModule
    mcpServer -->|"calls"| confluenceModule
    mcpServer -->|"calls"| jiraModule
    mcpServer -->|"utilizes"| modelLayer
    modelLayer -->|"supports"| confluenceModule
    modelLayer -->|"supports"| jiraModule

    %% MCP Server Transport Links
    mcpServer -->|"communicates"| stdio
    mcpServer -->|"communicates"| sse

    %% External API Interactions
    confluenceModule -->|"requests"| confluenceAPI
    jiraModule -->|"requests"| jiraAPI

    %% Testing Layer interacts with internal modules
    testingLayer ---|"tests"| confluenceModule
    testingLayer ---|"tests"| jiraModule
    testingLayer ---|"tests"| modelLayer

    %% Click Events
    click mcpServer "https://github.com/livshitsa/al-mcp-atlassian/blob/main/src/mcp_atlassian/server.py"
    click confluenceModule "https://github.com/livshitsa/al-mcp-atlassian/tree/main/src/mcp_atlassian/confluence"
    click jiraModule "https://github.com/livshitsa/al-mcp-atlassian/tree/main/tests/unit/jira"
    click modelLayer "https://github.com/livshitsa/al-mcp-atlassian/tree/main/src/mcp_atlassian/models"
    click preprocessing "https://github.com/livshitsa/al-mcp-atlassian/tree/main/src/mcp_atlassian/preprocessing"
    click testingLayer "https://github.com/livshitsa/al-mcp-atlassian/tree/main/tests"

    %% Styles
    classDef external fill:#FFEBEE,stroke:#B71C1C,stroke-width:2px;
    classDef module fill:#E3F2FD,stroke:#1E88E5,stroke-width:2px;
    classDef transport fill:#E8F5E9,stroke:#43A047,stroke-width:2px;
    classDef server fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px;
```
