From e687d8df7cc8671d1b2795e3be5f2df52ca0cc8e Mon Sep 17 00:00:00 2001 From: Matt Harrington Date: Thu, 25 Jun 2026 11:20:29 -0700 Subject: [PATCH] Improve setup docs and add .env.example Fix server entrypoint paths (src/server.py), correct MCP client config examples for Cursor/Claude, document MySQL 8.x compatibility, and add a copy-paste .env.example for local and Docker setups. Co-authored-by: Cursor --- .env.example | 30 +++++++++++++++++++++++ README.md | 69 +++++++++++++++++++++++++++++----------------------- 2 files changed, 68 insertions(+), 31 deletions(-) create mode 100644 .env.example diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..2337960 --- /dev/null +++ b/.env.example @@ -0,0 +1,30 @@ +# Copy to .env and fill in your values: +# cp .env.example .env + +# --- Database (required) --- +DB_HOST=127.0.0.1 +DB_PORT=3306 +DB_USER=your_db_user +DB_PASSWORD=your_db_password +DB_NAME=your_default_database + +# --- MCP server --- +MCP_READ_ONLY=true +MCP_MAX_POOL_SIZE=10 + +# --- Optional: SSL/TLS --- +# DB_SSL=false +# DB_SSL_CA= +# DB_SSL_CERT= +# DB_SSL_KEY= +# DB_SSL_VERIFY_CERT=true +# DB_SSL_VERIFY_IDENTITY=false + +# --- Optional: embeddings (pulls heavy deps; leave unset for SQL-only use) --- +# EMBEDDING_PROVIDER=openai +# OPENAI_API_KEY= +# GEMINI_API_KEY= +# HF_MODEL= + +# --- Docker on Mac/Windows: DB on the host (e.g. SSH tunnel on localhost) --- +# DB_HOST=host.docker.internal diff --git a/README.md b/README.md index e9f0b2c..de82150 100644 --- a/README.md +++ b/README.md @@ -28,11 +28,15 @@ The MCP MariaDB Server exposes a set of tools for interacting with MariaDB datab - Creating and managing vector stores for embedding-based search - Integrating with embedding providers (currently OpenAI, Gemini, and HuggingFace) (optional) +### MySQL compatibility + +The server uses **asyncmy** (MySQL wire protocol) and works with **MySQL 8.x** as well as MariaDB — for example read-only access through an SSH tunnel to Amazon RDS. SQL queries, JSON columns, parameterized `execute_sql`, and read-only enforcement behave the same on MySQL. MariaDB-only features (vector stores, etc.) require MariaDB; for MySQL-only deployments, use the standard SQL and schema tools. + --- ## Core Components -- **server.py**: Main MCP server logic and tool definitions. +- **src/server.py**: Main MCP server logic and tool definitions. - **config.py**: Loads configuration from environment and `.env` files. - **embeddings.py**: Handles embedding service integration (OpenAI). - **tests/**: Manual and automated test documentation and scripts. @@ -129,7 +133,11 @@ A vector store table has the following columns: ## Configuration & Environment Variables -All configuration is via environment variables (typically set in a `.env` file): +All configuration is via environment variables (typically set in a `.env` file). Copy `.env.example` to `.env` and edit values: + +```bash +cp .env.example .env +``` | Variable | Description | Required | Default | |------------------------|--------------------------------------------------------|----------|--------------| @@ -255,22 +263,23 @@ For production use, you should create a dedicated database user with minimal pri uv lock uv sync ``` -4. **Create `.env`** in the project root (see [Configuration](#configuration--environment-variables)) +4. **Create `.env`** in the project root: `cp .env.example .env` (see [Configuration](#configuration--environment-variables)) 5. **Run the server** **Standard Input/Output (default):** ```bash - uv run server.py + uv run src/server.py ``` + Stdio is the default transport — no flag needed for Cursor, Claude Desktop, or Windsurf. **SSE Transport:** ```bash - uv run server.py --transport sse --host 127.0.0.1 --port 9001 + uv run src/server.py --transport sse --host 127.0.0.1 --port 9001 ``` **HTTP Transport (streamable HTTP):** ```bash - uv run server.py --transport http --host 127.0.0.1 --port 9001 --path /mcp + uv run src/server.py --transport http --host 127.0.0.1 --port 9001 --path /mcp ``` --- @@ -335,7 +344,10 @@ For production use, you should create a dedicated database user with minimal pri ## Integration - Claude desktop/Cursor/Windsurf/VSCode -### Option 1: Direct Command (stdio) +### Option 1: Direct Command (stdio, default) + +Recommended for Cursor, Claude Desktop, and Windsurf. Use an absolute path to `uv` if your IDE does not inherit your shell `PATH`. Stdio is the default — you do not need `--transport stdio`. + ```json { "mcpServers": { @@ -343,20 +355,24 @@ For production use, you should create a dedicated database user with minimal pri "command": "uv", "args": [ "--directory", - "path/to/mariadb-mcp-server/", + "/absolute/path/to/mcp", "run", - "server.py" - ], - "envFile": "path/to/mcp-server-mariadb-vector/.env" + "src/server.py" + ], + "envFile": "/absolute/path/to/mcp/.env" } } } ``` +Alternatively, set `DB_*` variables under `"env"` instead of `envFile`. + +The server connects to the database at startup; if the DB is unreachable, the MCP client will show **Connection closed**. + ### Option 2: SSE Transport ```json { - "servers": { + "mcpServers": { "mariadb-mcp-server": { "url": "http://{host}:9001/sse", "type": "sse" @@ -368,7 +384,7 @@ For production use, you should create a dedicated database user with minimal pri ### Option 3: HTTP Transport ```json { - "servers": { + "mcpServers": { "mariadb-mcp-server": { "url": "http://{host}:9001/mcp", "type": "streamable-http" @@ -377,43 +393,34 @@ For production use, you should create a dedicated database user with minimal pri } ``` -### Option 4: Docker container +### Option 4: Docker container (stdio) + +For stdio MCP, do not publish ports or pass `--host` — the client talks over stdin/stdout. If the database runs on the **host** (e.g. an SSH tunnel on `127.0.0.1:3306`), set `DB_HOST=host.docker.internal` (Docker Desktop on Mac/Windows) instead of `127.0.0.1`. ```json { - "servers": { + "mcpServers": { "mariadb-mcp-server": { "command": "docker", "args": [ "run", "-i", "--rm", - "-p", - "9001:9001", - "-e", - "DB_HOST=", - "-e", - "DB_PORT=", - "-e", - "DB_USER=", - "-e", - "DB_PASSWORD=", - "-e", - "DB_NAME=", - "mariadb-mcp-server", + "--env-file", + "/absolute/path/to/mcp/.env", + "mcp-mariadb-mcp", "python", "src/server.py", - "--host", - "0.0.0.0", "--transport", "stdio" ] } } } - ``` +Build the image first: `docker compose build mariadb-mcp` (or `docker build -t mcp-mariadb-mcp .`). + --- ## Logging