Merge branch 'main' into feature/explain

Author: rocknroll17

README.md

@@ -27,7 +27,7 @@ The MCP MariaDB Server exposes a set of tools for interacting with MariaDB datab
 - Query performance analysis with EXPLAIN and EXPLAIN EXTENDED
 - Comprehensive tool usage guide for LLM self-discovery
 - Creating and managing vector stores for embedding-based search
-- Integrating with embedding providers (currently OpenAI, Gemini, and HuggingFace)
+- Integrating with embedding providers (currently OpenAI, Gemini, and HuggingFace) (optional)
 
 ---
 
@@ -65,6 +65,8 @@ The MCP MariaDB Server exposes a set of tools for interacting with MariaDB datab
   - Creates a new database if it doesn't exist.
   - Parameters: `database_name` (string, required)  
 
+### Query Performance Analysis Tools
+
 - **explain_query**
   - Executes EXPLAIN on a SQL query to show the execution plan for performance analysis.
   - Parameters: `sql_query` (string, required), `database_name` (string, required), `parameters` (list, optional)
@@ -75,7 +77,9 @@ The MCP MariaDB Server exposes a set of tools for interacting with MariaDB datab
   - Parameters: `sql_query` (string, required), `database_name` (string, required), `parameters` (list, optional)
   - _Note: Provides comprehensive analysis including filtered rows percentage and extra optimization details._
 
-### Vector Store & Embedding Tools
+### Vector Store & Embedding Tools (optional)
+
+**Note**: These tools are only available when `EMBEDDING_PROVIDER` is configured. If no embedding provider is set, these tools will be disabled.
 
 - **create_vector_store**
   - Creates a new vector store (table) for embeddings.
@@ -101,6 +105,10 @@ The MCP MariaDB Server exposes a set of tools for interacting with MariaDB datab
 
 ## Embeddings & Vector Store
 
+### Overview
+
+The MCP MariaDB Server provides **optional** embedding and vector store capabilities. These features can be enabled by configuring an embedding provider, or completely disabled if you only need standard database operations.
+
 ### Supported Providers
 
 - **OpenAI**
@@ -109,11 +117,10 @@ The MCP MariaDB Server exposes a set of tools for interacting with MariaDB datab
 
 ### Configuration
 
-- `EMBEDDING_PROVIDER`: Set to `openai` (default option), can change it to required providers
+- `EMBEDDING_PROVIDER`: Set to `openai`, `gemini`, `huggingface`, or leave unset to disable
 - `OPENAI_API_KEY`: Required if using OpenAI embeddings
-- GEMINI_API_KEY`: Required if using Gemini embeddings
-- Open models from HUGGINGFACE: Required open model currently provided option for "intfloat/multilingual-e5-large-instruct" & "BAAI/bge-m3"
-
+- `GEMINI_API_KEY`: Required if using Gemini embeddings
+- `HF_MODEL`: Required if using HuggingFace embeddings (e.g., "intfloat/multilingual-e5-large-instruct" or "BAAI/bge-m3")
 ### Model Selection
 
 - Default and allowed models are configurable in code (`DEFAULT_OPENAI_MODEL`, `ALLOWED_OPENAI_MODELS`)
@@ -142,13 +149,14 @@ All configuration is via environment variables (typically set in a `.env` file):
 | `DB_NAME`              | Default database (optional; can be set per query)      | No       |              |
 | `MCP_READ_ONLY`        | Enforce read-only SQL mode (`true`/`false`)            | No       | `true`       |
 | `MCP_MAX_POOL_SIZE`    | Max DB connection pool size                            | No       | `10`         |
-| `EMBEDDING_PROVIDER`   | Embedding provider (`openai`/`gemini`/`huggingface`)   | No       | `openai`     |
-| `OPENAI_API_KEY`       | API key for OpenAI embeddings                          | Yes (if using embeddings) | |
-| `GEMINII_API_KEY`      | API key for Gemini embeddings                          | Yes (if using embeddings) | |
-| `HF_MODEL`             | Open models from Huggingface                           | Yes (if using embeddings) | |
+| `EMBEDDING_PROVIDER`   | Embedding provider (`openai`/`gemini`/`huggingface`)   | No     |`None`(Disabled)|
+| `OPENAI_API_KEY`       | API key for OpenAI embeddings                          | Yes (if EMBEDDING_PROVIDER=openai) | |
+| `GEMINI_API_KEY`       | API key for Gemini embeddings                          | Yes (if EMBEDDING_PROVIDER=gemini) | |
+| `HF_MODEL`             | Open models from Huggingface                           | Yes (if EMBEDDING_PROVIDER=huggingface) | |
 
 #### Example `.env` file
 
+**With Embedding Support (OpenAI):**
 ```dotenv
 DB_HOST=localhost
 DB_USER=your_db_user
@@ -165,6 +173,17 @@ GEMINI_API_KEY=AI...
 HF_MODEL="BAAI/bge-m3"
 ```
 
+**Without Embedding Support:**
+```dotenv
+DB_HOST=localhost
+DB_USER=your_db_user
+DB_PASSWORD=your_db_password
+DB_PORT=3306
+DB_NAME=your_default_database
+MCP_READ_ONLY=true
+MCP_MAX_POOL_SIZE=10
+```
+
 ---
 
 ## Installation & Setup
@@ -256,9 +275,9 @@ HF_MODEL="BAAI/bge-m3"
 ```
 ---
 
-## Integration - Claude desktop/Cursor/Windsurf
+## Integration - Claude desktop/Cursor/Windsurf/VSCode
 
-```python
+```json
 {
   "mcpServers": {
     "MariaDB_Server": {
@@ -274,6 +293,18 @@ HF_MODEL="BAAI/bge-m3"
   }
 }
 ```
+or
+**If already running MCP server**
+```json
+{
+  "servers": {
+    "mariadb-mcp-server": {
+      "url": "http://{host}:9001/sse",
+      "type": "sse"
+    }
+  }
+}
+```
 ---
 
 ## Logging

docker-compose.yml

@@ -0,0 +1,25 @@
+services:
+  mariadb-server:
+    image: mariadb:11
+    container_name: mariadb
+    environment:
+      MARIADB_ROOT_PASSWORD: rootpassword123
+      MARIADB_DATABASE: demo
+      MARIADB_USER: user
+      MARIADB_PASSWORD: password123
+    ports:
+      - "3306:3306"
+    healthcheck:
+      test: ["CMD", "mariadb-admin", "ping", "-h", "127.0.0.1", "-p'rootpassword123'"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+  mariadb-mcp:
+    build: .
+    container_name: mariadb-mcp
+    env_file: .env
+    ports:
+      - "9001:9001"
+    depends_on:
+      mariadb-server:
+        condition: service_healthy

src/config.py

@@ -59,7 +59,8 @@
 
 # --- Embedding Configuration ---
 # Provider selection ('openai' or 'gemini' or 'huggingface')
-EMBEDDING_PROVIDER = os.getenv("EMBEDDING_PROVIDER", "openai").lower()
+EMBEDDING_PROVIDER = os.getenv("EMBEDDING_PROVIDER")
+EMBEDDING_PROVIDER = EMBEDDING_PROVIDER.lower() if EMBEDDING_PROVIDER else None
 # API Keys
 OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
 GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
@@ -86,8 +87,8 @@
         logger.error("EMBEDDING_PROVIDER is 'huggingface' but HF_MODEL is missing.")
         raise ValueError("HuggingFace model is required when EMBEDDING_PROVIDER is 'huggingface'.")
 else:
-    logger.error(f"Invalid EMBEDDING_PROVIDER specified: '{EMBEDDING_PROVIDER}'. Use 'openai' or 'gemini' or 'huggingface'.")
-    raise ValueError(f"Invalid EMBEDDING_PROVIDER: '{EMBEDDING_PROVIDER}'.")
+    EMBEDDING_PROVIDER = None
+    logger.info(f"No EMBEDDING_PROVIDER selected or it is set to None. Disabling embedding features.")
 
 logger.info(f"Read-only mode: {MCP_READ_ONLY}")
 logger.info(f"Logging to console and to file: {LOG_FILE_PATH} (Level: {LOG_LEVEL}, MaxSize: {LOG_MAX_BYTES}B, Backups: {LOG_BACKUP_COUNT})")

src/server.py

@@ -12,14 +12,17 @@
 # Import configuration settings
 from config import (
     DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME,
-    MCP_READ_ONLY, MCP_MAX_POOL_SIZE, logger
+    MCP_READ_ONLY, MCP_MAX_POOL_SIZE, EMBEDDING_PROVIDER,
+    logger
 )
 
 # Import EmbeddingService for vector store creation
 from embeddings import EmbeddingService
 
 # Singleton instance for embedding service
-embedding_service = EmbeddingService()
+embedding_service = None
+if EMBEDDING_PROVIDER is not None:
+    embedding_service = EmbeddingService()
 
 from asyncmy.errors import Error as AsyncMyError
 
@@ -746,11 +749,12 @@ def register_tools(self):
         self.mcp.add_tool(self.create_database)
         self.mcp.add_tool(self.explain_query)
         self.mcp.add_tool(self.explain_query_extended)
-        self.mcp.add_tool(self.create_vector_store)
-        self.mcp.add_tool(self.list_vector_stores)
-        self.mcp.add_tool(self.delete_vector_store)
-        self.mcp.add_tool(self.insert_docs_vector_store)
-        self.mcp.add_tool(self.search_vector_store)
+        if EMBEDDING_PROVIDER is not None:
+            self.mcp.add_tool(self.create_vector_store)
+            self.mcp.add_tool(self.list_vector_stores)
+            self.mcp.add_tool(self.delete_vector_store)
+            self.mcp.add_tool(self.insert_docs_vector_store)
+            self.mcp.add_tool(self.search_vector_store)
         logger.info("Registered MCP tools explicitly.")
 
     # --- Async Main Server Logic ---