How morristai/iceberg-mcp works
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