# morristai/iceberg-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/morristai/iceberg-mcp
- Repository: https://github.com/morristai/iceberg-mcp

## Overview

##### Project type and purpose
- This is a single‐binary Rust application implementing an MCP (Model Context Protocol) server for Apache Iceberg catalogs.
- It exposes MCP “tools” (namespaces, tables, table_schema, table_properties) over an async JSON-RPC or HTTP‐style interface, configurable for REST and AWS Glue backends.

##### File structure
- Top‐level:
- Cargo.toml / Cargo.lock – Rust project manifest and dependency lock.
- src/
– main.rs: binary entrypoint, configuration & startup.
– server.rs: core server logic (async listener, request routing, MCP tool handlers).
– utils.rs: helper functions (catalog client factories, common data transformations, logging setup).
- CI workflow (.github/workflows/ci.yml), .gitignore, README, and a changelog.

##### README for additional insights
- Describes supported catalog types (REST, AWS Glue) and tooling endpoints.
- Emphasizes async execution and logging.
- Shows how the binary is invoked and integrated with a client (Claude Desktop).

##### Main components
A. Client (e.g., Claude Desktop)
– Spawns the iceberg-mcp binary, communicates via MCP protocol (stdin/stdout JSON‐RPC).
B. CLI Binary (iceberg-mcp)
1. Configuration Loader
- Reads environment variables (CATALOG_KIND, REST_URI, AWS credentials, LOG_LEVEL).
2. Logger
- Initializes structured logging per LOG_LEVEL.
3. Async Runtime
- Tokio or equivalent, provides task execution for server and backends.
4. Server Module (server.rs)
- MCP Request Dispatcher
- Endpoint Handlers (“namespaces”, “tables”, etc.)
- Validation & Error Handling
5. Catalog Client Factory (in utils.rs)
- Instantiates either:
— REST Catalog Client (HTTP calls to REST_URI)
— AWS Glue Catalog Client (AWS SDK calls, S3 interactions)
C. External Systems
– REST Iceberg Catalog Service
– AWS Glue Catalog Service & S3 Data Lake
D. Tools / API Endpoints
– namespaces
– tables
– table_schema
– table_properties

##### Relationships and data flows
1. Client → Binary: spawns process, sends MCP JSON‐RPC requests.
2. Binary:
a. Loads configuration → initializes Logger & Async Runtime
b. Starts MCP Server → listens for incoming requests
c. On request: dispatch to appropriate handler in server.rs
d. Handler calls into Catalog Client (utils.rs)
e. Catalog Client issues HTTP calls (REST) or AWS SDK calls (Glue + S3)
f. Response unmarshaled → formatted as MCP response → sent on stdout
3. Binary → External Catalogs: over network (HTTP or AWS APIs)

##### Architectural patterns and design principles
- Modular separation: main.rs (infrastructure), server.rs (business logic), utils.rs (factory & shared helpers)
- Asynchronous event‐driven server (Tokio runtime)
- Dependency injection via environment variables → pluggable catalog backends
- Clear error propagation and logging at each layer

##### Essential elements
- Clear labels for:
- Client (Claude Desktop / MCP Host)
- Configuration Loader
- Logger
- Async Runtime
- MCP Server (Request Dispatcher + Handlers)
- Catalog Clients (REST, Glue)
- External Services (Iceberg REST API, AWS Glue & S3)
- Pluggability: environment variable → backend selection

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Client["Claude Desktop\n(MCP Host)"]:::client

    %% Binary Modules
    subgraph "iceberg-mcp Binary"
        ConfigLoader["Configuration Loader"]:::internal
        Logger["Logger"]:::internal
        AsyncRuntime["Async Runtime\n(Tokio)"]:::internal
        MCPServer["MCP Server\n(Request Dispatcher & Handlers)"]:::internal
        CatalogFactory["Catalog Client Factory"]:::internal
        RESTClient["REST Catalog Client"]:::internal
        GlueClient["AWS Glue Catalog Client"]:::internal
    end

    %% External Services
    RESTService["REST Iceberg Catalog Service"]:::external
    GlueService["AWS Glue Catalog & S3"]:::external

    %% Project Artifacts
    subgraph "Project Artifacts"
        Cargo["Cargo.toml"]:::internal
        CI["CI Workflow (.github/workflows/ci.yml)"]:::internal
        README["README.md"]:::internal
    end

    %% Data Flows
    Client -->|"stdin/stdout JSON-RPC"| MCPServer
    ConfigLoader -->|"loads env"| Logger
    ConfigLoader -->|"loads env"| AsyncRuntime
    AsyncRuntime -->|"spawns server"| MCPServer
    MCPServer -->|"dispatch requests"| CatalogFactory
    CatalogFactory -->|"creates REST client"| RESTClient
    CatalogFactory -->|"creates Glue client"| GlueClient
    RESTClient -->|"HTTP"| RESTService
    GlueClient -->|"AWS SDK"| GlueService

    %% Click Events
    click ConfigLoader "https://github.com/morristai/iceberg-mcp/blob/main/src/main.rs"
    click AsyncRuntime "https://github.com/morristai/iceberg-mcp/blob/main/src/main.rs"
    click MCPServer "https://github.com/morristai/iceberg-mcp/blob/main/src/server.rs"
    click CatalogFactory "https://github.com/morristai/iceberg-mcp/blob/main/src/utils.rs"
    click RESTClient "https://github.com/morristai/iceberg-mcp/blob/main/src/utils.rs"
    click GlueClient "https://github.com/morristai/iceberg-mcp/blob/main/src/utils.rs"
    click Logger "https://github.com/morristai/iceberg-mcp/blob/main/src/utils.rs"
    click Cargo "https://github.com/morristai/iceberg-mcp/blob/main/Cargo.toml"
    click CI "https://github.com/morristai/iceberg-mcp/blob/main/.github/workflows/ci.yml"
    click README "https://github.com/morristai/iceberg-mcp/blob/main/README.md"

    %% Styles
    classDef client fill:#f96,stroke:#333,color:#fff;
    classDef internal fill:#bbf,stroke:#333,color:#000;
    classDef external fill:#bfb,stroke:#333,color:#000;
```
