# dremio/dremio-mcp architecture

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

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

## Overview

##### Project Type & Purpose
- This is a Python‐based CLI application that implements an MCP (Model Context Protocol) server.
- It sits between an LLM frontend (e.g., Claude Desktop) and Dremio’s REST API (and optionally Prometheus).
- It exposes “tools” (data pattern discovery, introspection, metrics) via MCP messages.

##### Main Components
A. External Clients & Services
1. LLM Frontend (Claude Desktop)
2. Dremio Engine (REST API)
3. Prometheus (optional)
B. CLI & Entry Point
1. uv / Typer CLI
2. Commands: `run`, `config`, `tools`
C. MCP Server Core
1. Transport Layer (`src/dremioai/api/transport.py`) – handles JSON MCP messages over STDIN/STDOUT or HTTP.
2. Protocol Router – dispatches messages to tool implementations.
D. Tool Implementations (`src/dremioai/tools/tools.py`)
1. Data Patterns
2. Self-Introspection
3. Prometheus Metrics
E. API Clients
1. Dremio API modules (`src/dremioai/api/dremio/*.py`)
2. OAuth2 (`src/dremioai/api/oauth2.py`)
3. Prometheus client (`src/dremioai/api/prometheus/vm.py`)
F. Configuration & Utilities
1. Settings loader (`src/dremioai/config/settings.py`)
2. Tool registry (`src/dremioai/config/tools.py`)
3. Logging (`src/dremioai/log.py`)
G. Framework Adapters (for testing/integration)
1. LangChain adapter (`src/dremioai/servers/frameworks/langchain/*.py`)
2. BeeAI adapter (`src/dremioai/servers/frameworks/beeai/*.py`)

##### Relationships & Data Flow
- Claude → MCP Server Core (MCP JSON requests)
- MCP Core → Transport → Protocol Router → Tool implementation
- Tool → API Client → Dremio or Prometheus
- API response → Tool logic → MCP response → Claude
- Config/Settings used by CLI and MCP Core at startup
- Framework Adapters wrap the MCP Core for local/testing harnesses

##### Architectural Patterns & Principles
- Modular layering: CLI → Protocol/Transport → Tools → API Clients → External Services
- Plugin‐style tool registration (register new MCP tools via `tools.py`)
- Separation of concerns: each API domain in its own module, config isolated
- Adapters for different agent frameworks (LangChain, BeeAI)

##### Don’t Overthink—Capture Everything
- Break the server into as many logical components as you see in the file tree.
- Even small modules (e.g., `src/dremioai/api/util.py`) can be shown as utilities.
- The more explicit you are, the easier it is to see extension points and data flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        direction TB
        Claude["Claude Desktop"]:::external
        DremioAPI["Dremio REST API"]:::external
        Prometheus["Prometheus Service"]:::external
    end

    %% CLI & Entry Point
    subgraph "CLI & Entry Point"
        direction TB
        CLI_Main["__main__.py"]:::core
        CLI_Run["run / config / tools commands"]:::core
    end

    %% MCP Server Core
    subgraph "MCP Server Core"
        direction TB
        Transport["MCP Transport Layer"]:::core
        Router["Protocol Router"]:::core
        ToolsImpl["Tool Implementations"]:::tool
    end

    %% API Clients
    subgraph "API Clients"
        direction TB
        DremioCatalog["Dremio Catalog Client"]:::api
        DremioEngines["Dremio Engines Client"]:::api
        DremioProjects["Dremio Projects Client"]:::api
        DremioSearch["Dremio Search Client"]:::api
        DremioSQL["Dremio SQL Client"]:::api
        DremioUsage["Dremio Usage Client"]:::api
        OAuth2["OAuth2 Client"]:::api
        PromClient["Prometheus Client"]:::api
        Util["Utility Module"]:::util
    end

    %% Configuration & Utilities
    subgraph "Configuration & Utilities"
        direction TB
        Settings["Settings Loader"]:::util
        ToolsCfg["Tool Registry"]:::util
        Logging["Logging Setup"]:::util
    end

    %% Framework Adapters
    subgraph "Framework Adapters"
        direction TB
        LangChainSrv["LangChain Adapter (server)"]:::adapter
        LangChainTools["LangChain Adapter (tools)"]:::adapter
        BeeAISrv["BeeAI Adapter"]:::adapter
    end

    %% Relationships
    Claude -->|"MCP JSON over STDIN/STDOUT"| Transport
    CLI_Main -->|invokes| Transport
    CLI_Run -->|commands| CLI_Main

    Transport -->|"dispatch"| Router
    Router -->|"calls"| ToolsImpl
    ToolsImpl -->|"uses"| DremioCatalog
    ToolsImpl -->|"uses"| DremioEngines
    ToolsImpl -->|"uses"| DremioProjects
    ToolsImpl -->|"uses"| DremioSearch
    ToolsImpl -->|"uses"| DremioSQL
    ToolsImpl -->|"uses"| DremioUsage
    ToolsImpl -->|"uses"| OAuth2
    ToolsImpl -->|"uses"| PromClient
    ToolsImpl -->|"calls util"| Util

    DremioCatalog -->|HTTP/REST| DremioAPI
    DremioEngines -->|HTTP/REST| DremioAPI
    DremioProjects -->|HTTP/REST| DremioAPI
    DremioSearch -->|HTTP/REST| DremioAPI
    DremioSQL -->|HTTP/REST| DremioAPI
    DremioUsage -->|HTTP/REST| DremioAPI
    OAuth2 -->|HTTP/REST| DremioAPI
    PromClient -->|HTTP/REST| Prometheus

    Settings -->|loaded by| CLI_Main
    Settings -->|loaded by| Router
    ToolsCfg -->|used by| Router
    Logging -->|initialized by| CLI_Main

    LangChainSrv -->|wraps| Router
    LangChainTools -->|wraps| ToolsImpl
    BeeAISrv -->|wraps| Router

    %% Click Events
    click CLI_Main "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/cli/__main__.py"
    click ICONOISE "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/cli/engines.py"
    click CLI_Main "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/cli/oauth.py"
    click CLI_Main "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/cli/prometheus.py"
    click CLI_Main "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/cli/search.py"
    click Transport "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/transport.py"
    click Router "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/servers/mcp.py"
    click ToolsImpl "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/tools/tools.py"
    click DremioCatalog "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/dremio/catalog.py"
    click DremioEngines "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/dremio/engines.py"
    click DremioProjects "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/dremio/projects.py"
    click DremioSearch "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/dremio/search.py"
    click DremioSQL "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/dremio/sql.py"
    click DremioUsage "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/dremio/usage.py"
    click OAuth2 "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/oauth2.py"
    click PromClient "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/prometheus/vm.py"
    click Util "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/api/util.py"
    click Settings "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/config/settings.py"
    click ToolsCfg "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/config/tools.py"
    click Logging "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/log.py"
    click LangChainSrv "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/servers/frameworks/langchain/server.py"
    click LangChainTools "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/servers/frameworks/langchain/tools.py"
    click BeeAISrv "https://github.com/dremio/dremio-mcp/blob/main/src/dremioai/servers/frameworks/beeai/server.py"

    %% Styles
    classDef external fill:#bfdbfe,stroke:#1e40af,color:#1e3a8a;
    classDef core fill:#dcfce7,stroke:#166534,color:#14532d;
    classDef api fill:#d1fae5,stroke:#059669,color:#065f46;
    classDef util fill:#fef9c3,stroke:#a16207,color:#713f12;
    classDef tool fill:#fed7aa,stroke:#c2410c,color:#7c2d12;
    classDef adapter fill:#f3e8ff,stroke:#6b21a8,color:#4c1d95;
```
