# acryldata/mcp-server-datahub architecture

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

- Interactive diagram: https://gitdiagram.com/acryldata/mcp-server-datahub
- Repository: https://github.com/acryldata/mcp-server-datahub

## Overview

##### Project type and purpose
- This is a Python-based “MCP server” micro-service: a middle layer that speaks the Model Context Protocol (MCP) to AI agents and translates those calls into DataHub GMS API calls (GraphQL/REST).
- It is invoked as a CLI tool (via uvx), sits between any MCP-compliant AI agent (e.g. Claude Desktop, Cursor) and a DataHub instance (Core or Cloud).

##### File structure
- Root:
- pyproject.toml, Makefile, .github/workflows/ci.yml → build/test/CI definitions
- .envrc, .python-version → local environment settings
- README.md, DEVELOPING.md → project overview & developer guide
- src/mcp_server_datahub:
- __main__.py → entrypoint for CLI
- mcp_server.py → core logic: parses MCP requests, loads config, issues GraphQL queries
- gql/*.gql → GraphQL query templates for search, entity_details, lineage, SQL listings
- py.typed → indicates typed Python package
- tests/test_mcp_server.py → unit tests for server logic

##### README insights
- Shows usage with uvx CLI shim, environment-based authentication (DATAHUB_GMS_URL/TOKEN or ~/.datahubenv), and configuration for various MCP clients.
- No frontend/UI layer—pure backend adapter.

##### Diagramming the system
a. Main components
1. AI Agent / MCP Client (e.g., Claude Desktop, Cursor, other)
2. uvx CLI shim
3. mcp-server-datahub Python service (__main__.py + mcp_server.py + gql templates)
4. DataHub GMS API (Core/Cloud, HTTP/GraphQL endpoint)
5. Configuration store (environment variables, ~/.datahubenv)
6. CI/CD pipeline (GitHub Actions) – optional

b. Relationships & interactions
- AI Agent → (stdin/stdout) → uvx CLI shim → invokes “mcp-server-datahub”
- Service reads config (env or ~/.datahubenv)
- Service → (HTTPS/GraphQL) → DataHub GMS endpoint (search, entity_details, lineage, SQL)
- DataHub → JSON responses → service formats MCP responses → back to AI agent
- CI pipeline triggers on push → runs pytest on tests/ → publishes package

c. Architectural patterns
- Adapter/Facade: MCP protocol surface adapted to DataHub GraphQL API
- Modular queries: externalized .gql files act as plug-in points
- Single CLI entrypoint micro-service

d. Key technologies
- Python 3.x (pyproject.toml, typed)
- GraphQL query templates (gql/*.gql)
- uvx CLI tool from astral-sh
- pytest for unit tests
- GitHub Actions for CI

##### Detail level
- If needed, decompose mcp_server.py into sub-modules (input parsing, query dispatch, response formatting).
- Tests invoking mcp_server functions via pytest in CI.

- Clearly depicts every runtime component
- Shows how commands and data flow end-to-end
- Highlights key architectural choices and extension points
- Aligns precisely with the project’s file structure and README-defined behavior

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    AI_Agent["AI Agent (MCP Client)"]:::external
    DataHub["DataHub GMS API"]:::external

    %% Internal Components
    subgraph "CLI & Service" 
        direction TB
        UVX_CLI["uvx CLI Shim"]:::internal
        MainEntrypoint["__main__.py (CLI Entrypoint)"]:::internal
        CoreLogic["mcp_server.py (Core Logic)"]:::internal
        subgraph "Query Templates"
            direction TB
            EntityDetails["entity_details.gql"]:::internal
            SearchQuery["search.gql"]:::internal
            OtherQueries["queries.gql"]:::internal
        end
        PyTyped["py.typed"]:::internal
    end

    %% Configuration
    Config["Configuration Store\n(env vars / ~/.datahubenv)"]:::config

    %% CI/CD & Repo
    subgraph "CI/CD & Repo Files"
        direction TB
        CI["GitHub Actions CI"]:::ci
        Tests["pytest Unit Tests"]:::ci
        Pyproject["pyproject.toml"]:::ci
        MakefileNode["Makefile"]:::ci
        Envrc[".envrc"]:::ci
        PyVersion[".python-version"]:::ci
        Readme["README.md"]:::ci
        DevGuide["DEVELOPING.md"]:::ci
    end

    %% Flow
    AI_Agent -->|"stdin/stdout"| UVX_CLI
    UVX_CLI -->|"invokes"| MainEntrypoint
    MainEntrypoint -->|"parses MCP / loads config"| CoreLogic
    CoreLogic --> Config
    CoreLogic -->|"uses templates"| EntityDetails
    CoreLogic -->|"uses templates"| SearchQuery
    CoreLogic -->|"uses templates"| OtherQueries
    CoreLogic --> DataHub
    DataHub -->|"JSON responses"| CoreLogic
    CoreLogic -->|"MCP responses"| UVX_CLI
    UVX_CLI -->|"stdout"| AI_Agent

    %% CI/CD Flow
    CI --> Tests
    CI --> Pyproject
    CI --> MakefileNode
    CI --> Envrc
    CI --> PyVersion
    CI --> Readme
    CI --> DevGuide

    %% Click Events
    click MainEntrypoint "https://github.com/acryldata/mcp-server-datahub/blob/main/src/mcp_server_datahub/__main__.py"
    click CoreLogic "https://github.com/acryldata/mcp-server-datahub/blob/main/src/mcp_server_datahub/mcp_server.py"
    click EntityDetails "https://github.com/acryldata/mcp-server-datahub/blob/main/src/mcp_server_datahub/gql/entity_details.gql"
    click SearchQuery "https://github.com/acryldata/mcp-server-datahub/blob/main/src/mcp_server_datahub/gql/search.gql"
    click OtherQueries "https://github.com/acryldata/mcp-server-datahub/blob/main/src/mcp_server_datahub/gql/queries.gql"
    click PyTyped "https://github.com/acryldata/mcp-server-datahub/blob/main/src/mcp_server_datahub/py.typed"
    click Tests "https://github.com/acryldata/mcp-server-datahub/blob/main/tests/test_mcp_server.py"
    click CI "https://github.com/acryldata/mcp-server-datahub/blob/main/.github/workflows/ci.yml"
    click Pyproject "https://github.com/acryldata/mcp-server-datahub/blob/main/pyproject.toml"
    click MakefileNode "https://github.com/acryldata/mcp-server-datahub/tree/main/Makefile"
    click Envrc "https://github.com/acryldata/mcp-server-datahub/blob/main/.envrc"
    click PyVersion "https://github.com/acryldata/mcp-server-datahub/blob/main/.python-version"
    click Readme "https://github.com/acryldata/mcp-server-datahub/blob/main/README.md"
    click DevGuide "https://github.com/acryldata/mcp-server-datahub/blob/main/DEVELOPING.md"

    %% Styles
    classDef external fill:#FFD8BE,stroke:#FFA500,stroke-width:1px
    classDef internal fill:#D0E8FF,stroke:#005CFF,stroke-width:1px
    classDef config fill:#E8FFD0,stroke:#4CAF50,stroke-width:1px
    classDef ci fill:#F0D0FF,stroke:#9C27B0,stroke-width:1px
```
