How mariadb/mcp works
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)