How acryldata/mcp-server-datahub works
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