# mariadb/mcp architecture

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

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

## Overview

##### Project Type and Purpose
- This is a backend microservice (“MCP MariaDB Server”) that implements the Model Context Protocol (MCP) for interacting with MariaDB databases and optional vector-store/embedding services.
- It exposes a set of “tools” (list_databases, execute_sql, create_vector_store, search_vector_store, etc.) over multiple transports (stdio, SSE, HTTP) to AI assistants or other clients.

##### File Structure Analysis
- Top-level: Dockerfile, docker-compose.yml (for containerized deployment), pyproject.toml (Python packaging), .python-version, .gitignore.
- src/
- config.py – environment/.env loader, central configuration object
- embeddings.py – adapter for external embedding providers (OpenAI, Gemini, HuggingFace)
- server.py – core MCP server setup, tool registration, transport handling (FastMCP)
- main.py – entrypoint (likely delegates to server.run or similar)
- tests/ – unit and integration tests for each tool and server behavior
- README.md – describes features, tools, configuration, usage examples, logging, testing

##### Key Components
a. Transport Layer & Client Interfaces
- stdio (default)
- SSE transport (EventStream over HTTP)
- HTTP/streamable-HTTP endpoint (/mcp)
- Clients: AI assistants (e.g., Claude Desktop, Cursor, Windsurf, VSCode extension)

b. MCP Server (Python Process)
- config module: loads DB and embedding settings
- server module: registers tools with FastMCP, handles incoming requests
- embeddings module: when EMBEDDING_PROVIDER is set, proxies calls to external API

c. MariaDB Database
- Standard tables for SQL tools
- Vector-store tables (id, document, embedding, metadata)

d. External Embedding Providers (optional)
- OpenAI API
- Gemini API
- HuggingFace models

e. Configuration & Environment
- .env or environment variables (DB_HOST, EMBEDDING_PROVIDER, API keys, MCP_READ_ONLY, etc.)
- Connection pool (MCP_MAX_POOL_SIZE)

f. Logging
- Logger writes to logs/mcp_server.log

##### Relationships & Data Flow
- Client → (stdio/SSE/HTTP) → MCP Server
- MCP Server reads configuration at startup → connects to MariaDB
- For SQL tools: MCP Server → MariaDB → result → MCP Server → Client
- For embedding tools: MCP Server → Embedding Provider API → embeddings → MCP Server → MariaDB (vector store) → Client
- Logging: MCP Server → log file

##### Architectural Patterns & Principles
- Modular “tool” registration via FastMCP (plugin-like)
- Environment-driven configuration (12-factor App)
- Clear separation of concerns: transport layer, business logic (tools), data persistence (MariaDB), external services
- Read-only enforcement toggle (MCP_READ_ONLY)
- Optional feature paths (embedding module only loaded when configured)

##### Implementation Steps
a. Configuration Loader (config.py)
b. Tool Registry & Request Dispatcher (server.py)
c. Embedding Adapter (embeddings.py)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client["AI Assistants / CLI"]:::client
    end

    %% Transport Layer
    subgraph "Transport Layer"
        Stdio["stdio"]:::transport
        SSE["SSE (HTTP)"]:::transport
        HTTP["HTTP /mcp"]:::transport
    end

    Client --> Stdio
    Client --> SSE
    Client --> HTTP

    %% MCP Server Layer
    subgraph "MCP Server (Python 3.11, FastMCP)"
        Entrypoint["Entrypoint\n(main.py)"]:::server
        Config["Configuration Loader\n(config.py)"]:::server
        Registry["Tool Registry & Dispatcher\n(server.py)"]:::server
        Embedding["Embedding Adapter\n(embeddings.py)"]:::optional
    end

    Stdio --> Registry
    SSE --> Registry
    HTTP --> Registry

    Entrypoint --> Config
    Config --> Registry
    Registry --> Embedding

    %% Data Layer
    subgraph "Data Layer"
        MariaDB["MariaDB\n(SQL & Vector Tables)"]:::database
        ExternalAPI["External Embedding APIs\n(OpenAI/Gemini/HuggingFace)"]:::external
    end

    Registry -->|"SQL Queries & Vector Store CRUD"| MariaDB
    Embedding -->|"REST API"| ExternalAPI
    ExternalAPI -->|"embeddings"| Embedding
    Embedding -->|"store/retrieve"| MariaDB

    %% Logging
    subgraph "Logging"
        Log["Log File\n(logs/mcp_server.log)"]:::log
    end

    Registry -->|"logs"| Log

    %% Containerization & Project Files
    subgraph "Containerization & Project"
        DockerfileNode["Dockerfile"]:::infra
        Compose["docker-compose.yml"]:::infra
        Pyproject["pyproject.toml"]:::infra
        Version[".python-version"]:::infra
        Tests["tests/"]:::infra
        Readme["README.md"]:::infra
    end

    %% Click Events
    click Config "https://github.com/mariadb/mcp/blob/main/src/config.py"
    click Embedding "https://github.com/mariadb/mcp/blob/main/src/embeddings.py"
    click Registry "https://github.com/mariadb/mcp/blob/main/src/server.py"
    click Entrypoint "https://github.com/mariadb/mcp/blob/main/src/main.py"
    click DockerfileNode "https://github.com/mariadb/mcp/tree/main/Dockerfile"
    click Compose "https://github.com/mariadb/mcp/blob/main/docker-compose.yml"
    click Pyproject "https://github.com/mariadb/mcp/blob/main/pyproject.toml"
    click Version "https://github.com/mariadb/mcp/blob/main/.python-version"
    click Tests "https://github.com/mariadb/mcp/tree/main/src/tests/"
    click Readme "https://github.com/mariadb/mcp/blob/main/README.md"

    %% Styles
    classDef client fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef transport fill:#e0f7fa,stroke:#006064,color:#004d40;
    classDef server fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef optional fill:#ffe0b2,stroke:#ef6c00,color:#e65100,stroke-dasharray: 5 5;
    classDef database fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20,shape:cylinder;
    classDef external fill:#ffe082,stroke:#ff8f00,color:#bf360c;
    classDef log fill:#eeeeee,stroke:#757575,color:#424242,shape:cylinder;
    classDef infra fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c;
```
