# aarora79/aws-cost-explorer-mcp-server architecture

> Architecture diagram of the GitHub repository aarora79/aws-cost-explorer-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aarora79/aws-cost-explorer-mcp-server
- Repository: https://github.com/aarora79/aws-cost-explorer-mcp-server

## Overview

##### Project Type and Purpose
- This is an open‑source Python MCP (Model Control Protocol) server + client toolchain that exposes AWS Cost Explorer and Amazon Bedrock model invocation logs through Anthropic’s MCP framework.
- It provides both a server component (`server.py`) implementing a set of MCP‑annotated “tools” (AWS spend queries), and multiple clients: a CLI SSE client (`mcp_sse_client.py`), a Chainlit-based chatbot (`app.py`), and a LangGraph Agent client (`langgraph_agent_mcp_sse_client.py`).
- The purpose is to let users (via Claude Desktop or custom agents) query AWS spend and usage data in natural language.

##### File Structure Analysis
- Top‑level artifacts:
- server.py – the MCP server entrypoint, registers AWS Cost Explorer and CloudWatch query tools.
- app.py – a Chainlit app that spins up a LangGraph Agent using the MCP server’s tools.
- mcp_sse_client.py & langgraph_agent_mcp_sse_client.py – example client scripts using SSE transport.
- Dockerfile & pyproject.toml – for containerized deployment and dependency management.
- chainlit.md – documentation for the Chainlit app.
- No deep subdirectories—this is a single‐service codebase with multiple client scripts.
- Configuration/environment driven via ENV vars: AWS credentials, MCP_TRANSPORT (stdio vs sse), SSE host/port, Bedrock log group, cross‐account role.

##### README Insights
- Two transport modes: stdio for local, SSE (HTTP port 8000 or HTTPS via nginx reverse‐proxy) for remote.
- Chainlit app and Docker/UV deployment paths are documented.

##### Components & Interactions
a. Main Components:
- **User Layer**:
- Human user interacting via Claude Desktop, Chainlit web UI, or custom CLI.
- **Client Layer**:
- MCP Client (embedded in Claude Desktop or LangGraph Agent).
- CLI SSE client scripts (`mcp_sse_client.py`, `langgraph_agent_mcp_sse_client.py`).
- Chainlit Agent (`app.py`).
- **Transport Layer**:
- stdio (local)
- SSE (HTTP/S)
- Optional HTTPS reverse proxy (nginx) in remote setup.
- **Server Layer**:
- MCP Server (`server.py`, built on FastMCP) exposing tools:
– get_ec2_spend_last_day()
– get_detailed_breakdown_by_day()
– get_bedrock_daily_usage_stats()
– get_bedrock_hourly_usage_stats()
- Runs in Python 3.12 environment, optionally containerized via Docker or launched with UV.
- **AWS Services**:
- AWS Cost Explorer API
- AWS CloudWatch Logs (Bedrock invocation logs)
- IAM roles & cross‐account role assumption (via CROSS_ACCOUNT_ROLE_NAME)

b. Relationships & Data Flows:
- User → Client UI (Claude Desktop or web UI) → MCP Client module
- MCP Server → AWS Cost Explorer API (JSON over HTTPS)
- MCP Server → AWS CloudWatch Logs API (JSON over HTTPS)
- Server → (optional) nginx reverse proxy for HTTPS termination → Server

c. Architectural Patterns & Principles:
- **RPC Microservice**: Loose coupling between clients and server via JSON‑RPC 2.0 (MCP).
- **Transport Abstraction**: Switchable transports (stdio vs SSE vs HTTPS).
- **Extensibility**: New AWS query tools are simply annotated functions in `server.py`.
- **Infrastructure as Code**: Dockerfile + UV to standardize deployments.
- **Security Boundary**: AWS credentials and cross‐account roles separated at the server, no credentials in clients.

d. Key Technologies & Libraries:
- Python 3.12
- FastMCP (MCP server framework)
- Anthropic MCP protocol
- Docker & UV (for packaging/running)
- Chainlit & LangChain MCP Adapter (for chat UI)
- AWS SDK (boto3) under the hood in server
- nginx (optional) for HTTPS reverse proxy

##### Detail Level
- Don’t just show “Client → Server”; break out each transport mode.
- Environment variables feeding into the server (AWS creds, BEDROCK_LOG_GROUP_NAME, CROSS_ACCOUNT_ROLE_NAME, MCP_TRANSPORT).
- If desired, annotate the Docker/container boundary and the UV runtime.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        direction TB
        User["Human User"]:::user
        Claude["Claude Desktop"]:::ui
        ChainlitUI["Chainlit Web UI"]:::ui
        CustomCLI["Custom CLI App"]:::ui
    end

    User --> Claude
    User --> ChainlitUI
    User --> CustomCLI

    %% Client Layer
    subgraph "Client Layer"
        direction TB
        MCPClient["MCP Client Module"]:::client
        SSE_CLI["CLI SSE Client"]:::client
        LG_SSE_CLI["LangGraph Agent SSE Client"]:::client
        ChainlitAgent["Chainlit Agent (LangGraph)"]:::client
    end

    Claude --> MCPClient
    CustomCLI --> MCPClient
    ChainlitUI --> ChainlitAgent
    ChainlitAgent --> MCPClient
    MCPClient --> SSE_CLI
    MCPClient --> LG_SSE_CLI

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        StdIO["stdio (Local)"]:::transport
        SSE["SSE (HTTP/S)"]:::transport
        Nginx["HTTPS Reverse Proxy\n(nginx)"]:::proxy
    end

    MCPClient -->|stdio| StdIO
    MCPClient -->|SSE| SSE
    SSE --> Nginx
    Nginx --> SSE

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        subgraph "Containerized Server" 
            direction TB
            DockerBoundary(("Docker/UV")):::container
            Server["MCP Server\n(server.py)\n• get_ec2_spend_last_day()\n• get_detailed_breakdown_by_day()\n• get_bedrock_daily_usage_stats()\n• get_bedrock_hourly_usage_stats()"]:::server
            DockerBoundary --> Server
        end
        Env["Env Vars:\nAWS_CREDS, BEDROCK_LOG_GROUP_NAME,\nCROSS_ACCOUNT_ROLE_NAME,\nMCP_TRANSPORT"]:::note
    end

    StdIO --> Server
    SSE --> Server

    %% AWS Services
    subgraph "AWS Services"
        direction TB
        CE["Cost Explorer API"]:::aws
        CW["CloudWatch Logs API"]:::aws
        IAM["IAM & Cross-Account Roles"]:::aws
    end

    Server --> CE
    Server --> CW
    Server --> IAM

    %% Legend
    subgraph "Legend"
        direction TB
        U["User & UI"]:::user
        C["Clients & Agents"]:::client
        T["Transport Channels"]:::transport
        S["Server & Tools"]:::server
        A["AWS Services"]:::aws
        P["Proxy"]:::proxy
        N["Environment Variables"]:::note
        O["Container"]:::container
    end

    %% Click Events
    click Server "https://github.com/aarora79/aws-cost-explorer-mcp-server/blob/main/server.py"
    click ChainlitAgent "https://github.com/aarora79/aws-cost-explorer-mcp-server/blob/main/app.py"
    click SSE_CLI "https://github.com/aarora79/aws-cost-explorer-mcp-server/blob/main/mcp_sse_client.py"
    click LG_SSE_CLI "https://github.com/aarora79/aws-cost-explorer-mcp-server/blob/main/langgraph_agent_mcp_sse_client.py"
    click DockerBoundary "https://github.com/aarora79/aws-cost-explorer-mcp-server/tree/main/Dockerfile"
    click Env "https://github.com/aarora79/aws-cost-explorer-mcp-server/blob/main/pyproject.toml"
    click ChainlitUI "https://github.com/aarora79/aws-cost-explorer-mcp-server/blob/main/chainlit.md"
    click U "https://github.com/aarora79/aws-cost-explorer-mcp-server/blob/main/README.md"
    click img "https://github.com/aarora79/aws-cost-explorer-mcp-server/tree/main/img/"
    click uvlock "https://github.com/aarora79/aws-cost-explorer-mcp-server/blob/main/uv.lock"
    click LIC "https://github.com/aarora79/aws-cost-explorer-mcp-server/tree/main/LICENSE"
    click GITIGNORE "https://github.com/aarora79/aws-cost-explorer-mcp-server/blob/main/.gitignore"

    %% Styles
    classDef user fill:#AED6F1,stroke:#1F618D,color:#1F618D
    classDef ui fill:#AED6F1,stroke:#1F618D,color:#1F618D
    classDef client fill:#A9DFBF,stroke:#196F3D,color:#196F3D
    classDef transport stroke-dasharray: 5 5,stroke:#7D3C98
    classDef proxy fill:#D2B4DE,stroke:#7D3C98,color:#7D3C98,shape:diamond
    classDef server fill:#F5B7B1,stroke:#C0392B,color:#C0392B
    classDef aws fill:#D5D8DC,stroke:#566573,color:#566573,shape:cloud
    classDef container fill:#FDEBD0,stroke:#B9770E,color:#B9770E
    classDef note fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef legend fill:#FFFFFF,stroke:#000000,color:#000000,font-style:italic,opacity:0.3
    class LIC,GITIGNORE,uvlock,img,U,E,N,O user
    class LIC,GITIGNORE,uvlock,img,U,E,N,O legend
```
