mcp-db-server 0.1.0__tar.gz

mcp_db_server-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: mcp-db-server
+Version: 0.1.0
+Summary: MCP Database Server with read-only access
+Author-email: User <user@example.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp
+Requires-Dist: python-dotenv
+Requires-Dist: pymysql
+Requires-Dist: cryptography
+Requires-Dist: DBUtils
+
+# MCP Database Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server implementation in Python that provides **strictly read-only** access to databases. It allows Large Language Models (LLMs) to inspect schemas and query data safely without risking data modification.
+
+## Features
+
+- **🛡️ Strict Read-Only**: Enforced at the driver level (e.g., SQLite `?mode=ro`) or session level (MySQL `SET SESSION TRANSACTION READ ONLY`).
+- **🏗️ Repository Pattern**: Abstracted database access allows for easy extension to other backends (PostgreSQL, MySQL) via Dependency Injection.
+- **⚡ FastMCP**: Built efficiently using the official MCP Python SDK.
+- **🔌 Connection Pooling**: Automatic connection pooling for MySQL using `DBUtils` to ensure performance and reliability.
+- **🔧 Easy Configuration**: Managed via environment variables and Makefiles.
+
+## Project Structure
+
+- `server.py`: Main entry point for the MCP server.
+- `db/`: Contains the Repository interface and implementations (`sqlite_repository.py`, `mysql_repository.py`).
+- `seed.py`: Utility script to populate the database (since the server itself is read-only).
+- `Makefile`: Automation for common tasks.
+
+## Quick Start
+
+### Prerequisites
+- Python 3.12+ (managed via `venv`)
+- `make` (optional, but recommended)
+- MySQL Server (optional, if using MySQL backend)
+
+### 1. Setup
+Use the Makefile to create a virtual environment, install dependencies, and seed a test database:
+
+```bash
+make setup
+```
+
+*This runs `pip install -r requirements.txt` and `python seed.py`.*
+
+### 2. Configuration
+The project uses `python-dotenv`. Copy the example config and adjust as needed:
+
+```bash
+cp .env.example .env
+```
+
+**Key Variables:**
+- `DB_ENGINE`: `sqlite` (Default) or `mysql`
+- `DB_ADDRESS`: Path to db file (SQLite) or Host URL (MySQL).
+- `DB_PORT`: Database port (Default: 3306 for MySQL).
+- `DB_USER` / `DB_PASSWORD`: Database credentials (required for MySQL).
+- `DB_SCHEMA`: Database name (required for MySQL).
+
+### 3. Run the Server
+Start the MCP server:
+
+```bash
+make run
+```
+*(Or directly via `venv/bin/python server.py`)*
+
+## Usage with LLMs
+
+Once running, the server exposes the following tools to connected MCP clients:
+
+1.  **`list_tables()`**
+    - Returns a list of all tables in the database.
+2.  **`describe_table(table_name: str)`**
+    - Returns the schema (columns, types, primary keys) for the specified table.
+3.  **`read_query(query: str)`**
+    - Executes a SQL `SELECT` query.
+    - **Note**: Queries attempting to modify data will raise a `Security Error` or `OperationalError`.
+
+## Development
+
+### Running Tests
+Execute the unit test suite:
+
+```bash
+make test
+```
+
+### Extending
+To add support for a new database (e.g., Postgres):
+1.  Create `db/postgres_repository.py` implementation of `DatabaseRepository`.
+2.  Update `server.py` to instantiate it when `DB_ENGINE=postgres`.

mcp_db_server-0.1.0/README.md

@@ -0,0 +1,82 @@
+# MCP Database Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server implementation in Python that provides **strictly read-only** access to databases. It allows Large Language Models (LLMs) to inspect schemas and query data safely without risking data modification.
+
+## Features
+
+- **🛡️ Strict Read-Only**: Enforced at the driver level (e.g., SQLite `?mode=ro`) or session level (MySQL `SET SESSION TRANSACTION READ ONLY`).
+- **🏗️ Repository Pattern**: Abstracted database access allows for easy extension to other backends (PostgreSQL, MySQL) via Dependency Injection.
+- **⚡ FastMCP**: Built efficiently using the official MCP Python SDK.
+- **🔌 Connection Pooling**: Automatic connection pooling for MySQL using `DBUtils` to ensure performance and reliability.
+- **🔧 Easy Configuration**: Managed via environment variables and Makefiles.
+
+## Project Structure
+
+- `server.py`: Main entry point for the MCP server.
+- `db/`: Contains the Repository interface and implementations (`sqlite_repository.py`, `mysql_repository.py`).
+- `seed.py`: Utility script to populate the database (since the server itself is read-only).
+- `Makefile`: Automation for common tasks.
+
+## Quick Start
+
+### Prerequisites
+- Python 3.12+ (managed via `venv`)
+- `make` (optional, but recommended)
+- MySQL Server (optional, if using MySQL backend)
+
+### 1. Setup
+Use the Makefile to create a virtual environment, install dependencies, and seed a test database:
+
+```bash
+make setup
+```
+
+*This runs `pip install -r requirements.txt` and `python seed.py`.*
+
+### 2. Configuration
+The project uses `python-dotenv`. Copy the example config and adjust as needed:
+
+```bash
+cp .env.example .env
+```
+
+**Key Variables:**
+- `DB_ENGINE`: `sqlite` (Default) or `mysql`
+- `DB_ADDRESS`: Path to db file (SQLite) or Host URL (MySQL).
+- `DB_PORT`: Database port (Default: 3306 for MySQL).
+- `DB_USER` / `DB_PASSWORD`: Database credentials (required for MySQL).
+- `DB_SCHEMA`: Database name (required for MySQL).
+
+### 3. Run the Server
+Start the MCP server:
+
+```bash
+make run
+```
+*(Or directly via `venv/bin/python server.py`)*
+
+## Usage with LLMs
+
+Once running, the server exposes the following tools to connected MCP clients:
+
+1.  **`list_tables()`**
+    - Returns a list of all tables in the database.
+2.  **`describe_table(table_name: str)`**
+    - Returns the schema (columns, types, primary keys) for the specified table.
+3.  **`read_query(query: str)`**
+    - Executes a SQL `SELECT` query.
+    - **Note**: Queries attempting to modify data will raise a `Security Error` or `OperationalError`.
+
+## Development
+
+### Running Tests
+Execute the unit test suite:
+
+```bash
+make test
+```
+
+### Extending
+To add support for a new database (e.g., Postgres):
+1.  Create `db/postgres_repository.py` implementation of `DatabaseRepository`.
+2.  Update `server.py` to instantiate it when `DB_ENGINE=postgres`.

mcp_db_server-0.1.0/db/mysql_repository.py

@@ -0,0 +1,116 @@
+import pymysql
+import os
+from typing import List, Union
+from .repository import DatabaseRepository
+
+from dbutils.pooled_db import PooledDB
+
+class MysqlRepository(DatabaseRepository):
+    def __init__(self, host: str, user: str, password: str, database: str, port: int = 3306):
+        self.host = host
+        self.user = user
+        self.password = password
+        self.database = database
+        self.port = port
+        
+        # Initialize connection pool
+        # mincached=2, maxcached=5 are reasonable defaults
+        self.pool = PooledDB(
+            creator=pymysql,
+            mincached=2,
+            maxcached=5,
+            blocking=True,  # Wait for connection if pool is empty
+            host=self.host,
+            user=self.user,
+            password=self.password,
+            database=self.database,
+            port=self.port,
+            cursorclass=pymysql.cursors.Cursor
+        )
+
+    def _get_connection(self):
+        # Get connection from pool
+        return self.pool.connection()
+
+    def list_tables(self) -> List[str]:
+        try:
+            conn = self._get_connection()
+            with conn.cursor() as cursor:
+                 cursor.execute("SHOW TABLES")
+                 # result is tuple of tuples
+                 tables = [row[0] for row in cursor.fetchall()]
+            conn.close()
+            return tables
+        except Exception as e:
+            return [f"Error listing tables: {e}"]
+
+    def describe_table(self, table_name: str) -> str:
+        try:
+            conn = self._get_connection()
+            with conn.cursor() as cursor:
+                # Validate table exists (prevent injection)
+                cursor.execute("SHOW TABLES")
+                tables = [row[0] for row in cursor.fetchall()]
+                if table_name not in tables:
+                    return f"Error: Table '{table_name}' does not exist."
+
+                cursor.execute(f"DESCRIBE {table_name}")
+                columns = cursor.fetchall()
+            conn.close()
+
+            schema = []
+            # Field, Type, Null, Key, Default, Extra
+            for col in columns:
+                col_name = col[0]
+                col_type = col[1]
+                key = col[3]
+                
+                col_str = f"- {col_name} ({col_type})"
+                if key == 'PRI':
+                    col_str += " [PK]"
+                schema.append(col_str)
+
+            return f"Schema for {table_name}:\n" + "\n".join(schema)
+        except Exception as e:
+            return f"Error describing table: {e}"
+
+    def read_query(self, query: str) -> str:
+        normalized_query = query.strip().upper()
+        if not normalized_query.startswith("SELECT"):
+            return "Error: Only SELECT queries are allowed."
+
+        try:
+            conn = self._get_connection()
+            try:
+                with conn.cursor() as cursor:
+                    # Enforce Read Only mode for this session
+                    cursor.execute("SET SESSION TRANSACTION READ ONLY")
+                    
+                    cursor.execute(query)
+                    results = cursor.fetchall()
+
+                    output = []
+                    if cursor.description:
+                        col_names = [desc[0] for desc in cursor.description]
+                        output.append(" | ".join(col_names))
+                        output.append("-" * len(" | ".join(col_names)))
+
+                    if not results:
+                        return "No results found."
+
+                    for row in results:
+                        row_str = " | ".join(str(item) for item in row)
+                        output.append(row_str)
+
+                    return "\n".join(output)
+            finally:
+                conn.close()
+
+        except pymysql.OperationalError as e:
+            # Code 1290 is The MySQL server is running with the --read-only option so it cannot execute this statement
+            # Or similar for session read only
+            if e.args[0] == 1792: # Cannot execute statement in a READ ONLY transaction.
+                 return "Security Error: Attempted write operation in read-only mode."
+            return f"Database Error: {e}"
+        except Exception as e:
+            return f"Error: {e}"

mcp_db_server-0.1.0/db/repository.py

@@ -0,0 +1,21 @@
+from abc import ABC, abstractmethod
+from typing import List, Union
+
+class DatabaseRepository(ABC):
+    @abstractmethod
+    def list_tables(self) -> List[str]:
+        """List all tables in the database."""
+        pass
+
+    @abstractmethod
+    def describe_table(self, table_name: str) -> str:
+        """Get schema information for a specific table."""
+        pass
+
+    @abstractmethod
+    def read_query(self, query: str) -> str:
+        """
+        Execute a read-only query.
+        Returns a formatted string (table) or an error string.
+        """
+        pass

mcp_db_server-0.1.0/db/sqlite_repository.py

@@ -0,0 +1,94 @@
+import sqlite3
+import os
+from typing import List
+from .repository import DatabaseRepository
+
+class SqliteRepository(DatabaseRepository):
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        if not os.path.exists(self.db_path):
+            raise FileNotFoundError(f"Database file not found: {self.db_path}")
+
+    def _get_connection(self):
+        # Enforce read-only mode at driver level
+        return sqlite3.connect(f"file:{os.path.abspath(self.db_path)}?mode=ro", uri=True)
+
+    def list_tables(self) -> List[str]:
+        try:
+            conn = self._get_connection()
+            cursor = conn.cursor()
+            cursor.execute("SELECT name FROM sqlite_master WHERE type='table';")
+            tables = [row[0] for row in cursor.fetchall()]
+            conn.close()
+            return tables
+        except Exception as e:
+            return [f"Error listing tables: {e}"]
+
+    def describe_table(self, table_name: str) -> str:
+        try:
+            conn = self._get_connection()
+            cursor = conn.cursor()
+            
+            # Validate table existence first
+            cursor.execute("SELECT name FROM sqlite_master WHERE type='table';")
+            tables = [row[0] for row in cursor.fetchall()]
+            
+            if table_name not in tables:
+                conn.close()
+                return f"Error: Table '{table_name}' does not exist."
+                
+            cursor.execute(f"PRAGMA table_info({table_name})")
+            columns = cursor.fetchall()
+            conn.close()
+            
+            schema = []
+            for col in columns:
+                # PRAGMA table_info returns: cid, name, type, notnull, dflt_value, pk
+                col_name = col[1]
+                col_type = col[2]
+                pk = col[5]
+                
+                col_str = f"- {col_name} ({col_type})"
+                if pk:
+                    col_str += " [PK]"
+                schema.append(col_str)
+                
+            return f"Schema for {table_name}:\n" + "\n".join(schema)
+            
+        except Exception as e:
+            return f"Error describing table: {e}"
+
+    def read_query(self, query: str) -> str:
+        normalized_query = query.strip().upper()
+        if not normalized_query.startswith("SELECT"):
+            return "Error: Only SELECT queries are allowed."
+
+        try:
+            conn = self._get_connection()
+            cursor = conn.cursor()
+            cursor.execute(query)
+            results = cursor.fetchall()
+            
+            output = []
+            if cursor.description:
+                col_names = [desc[0] for desc in cursor.description]
+                output.append(" | ".join(col_names))
+                output.append("-" * len(" | ".join(col_names)))
+                
+            conn.close()
+            
+            if not results:
+                return "No results found."
+
+            for row in results:
+                row_str = " | ".join(str(item) for item in row)
+                output.append(row_str)
+                
+            return "\n".join(output)
+            
+        except sqlite3.OperationalError as e:
+            if "readonly" in str(e):
+                return f"Security Error: Attempted write operation on read-only database."
+            return f"Database Error: {e}"
+        except Exception as e:
+            return f"Error: {e}"

mcp_db_server-0.1.0/mcp_db_server.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: mcp-db-server
+Version: 0.1.0
+Summary: MCP Database Server with read-only access
+Author-email: User <user@example.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp
+Requires-Dist: python-dotenv
+Requires-Dist: pymysql
+Requires-Dist: cryptography
+Requires-Dist: DBUtils
+
+# MCP Database Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server implementation in Python that provides **strictly read-only** access to databases. It allows Large Language Models (LLMs) to inspect schemas and query data safely without risking data modification.
+
+## Features
+
+- **🛡️ Strict Read-Only**: Enforced at the driver level (e.g., SQLite `?mode=ro`) or session level (MySQL `SET SESSION TRANSACTION READ ONLY`).
+- **🏗️ Repository Pattern**: Abstracted database access allows for easy extension to other backends (PostgreSQL, MySQL) via Dependency Injection.
+- **⚡ FastMCP**: Built efficiently using the official MCP Python SDK.
+- **🔌 Connection Pooling**: Automatic connection pooling for MySQL using `DBUtils` to ensure performance and reliability.
+- **🔧 Easy Configuration**: Managed via environment variables and Makefiles.
+
+## Project Structure
+
+- `server.py`: Main entry point for the MCP server.
+- `db/`: Contains the Repository interface and implementations (`sqlite_repository.py`, `mysql_repository.py`).
+- `seed.py`: Utility script to populate the database (since the server itself is read-only).
+- `Makefile`: Automation for common tasks.
+
+## Quick Start
+
+### Prerequisites
+- Python 3.12+ (managed via `venv`)
+- `make` (optional, but recommended)
+- MySQL Server (optional, if using MySQL backend)
+
+### 1. Setup
+Use the Makefile to create a virtual environment, install dependencies, and seed a test database:
+
+```bash
+make setup
+```
+
+*This runs `pip install -r requirements.txt` and `python seed.py`.*
+
+### 2. Configuration
+The project uses `python-dotenv`. Copy the example config and adjust as needed:
+
+```bash
+cp .env.example .env
+```
+
+**Key Variables:**
+- `DB_ENGINE`: `sqlite` (Default) or `mysql`
+- `DB_ADDRESS`: Path to db file (SQLite) or Host URL (MySQL).
+- `DB_PORT`: Database port (Default: 3306 for MySQL).
+- `DB_USER` / `DB_PASSWORD`: Database credentials (required for MySQL).
+- `DB_SCHEMA`: Database name (required for MySQL).
+
+### 3. Run the Server
+Start the MCP server:
+
+```bash
+make run
+```
+*(Or directly via `venv/bin/python server.py`)*
+
+## Usage with LLMs
+
+Once running, the server exposes the following tools to connected MCP clients:
+
+1.  **`list_tables()`**
+    - Returns a list of all tables in the database.
+2.  **`describe_table(table_name: str)`**
+    - Returns the schema (columns, types, primary keys) for the specified table.
+3.  **`read_query(query: str)`**
+    - Executes a SQL `SELECT` query.
+    - **Note**: Queries attempting to modify data will raise a `Security Error` or `OperationalError`.
+
+## Development
+
+### Running Tests
+Execute the unit test suite:
+
+```bash
+make test
+```
+
+### Extending
+To add support for a new database (e.g., Postgres):
+1.  Create `db/postgres_repository.py` implementation of `DatabaseRepository`.
+2.  Update `server.py` to instantiate it when `DB_ENGINE=postgres`.

mcp_db_server-0.1.0/mcp_db_server.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+db/mysql_repository.py
+db/repository.py
+db/sqlite_repository.py
+mcp_db_server.egg-info/PKG-INFO
+mcp_db_server.egg-info/SOURCES.txt
+mcp_db_server.egg-info/dependency_links.txt
+mcp_db_server.egg-info/entry_points.txt
+mcp_db_server.egg-info/requires.txt
+mcp_db_server.egg-info/top_level.txt

mcp_db_server-0.1.0/mcp_db_server.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mcp_db_server-0.1.0/mcp_db_server.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-db-server = server:main

mcp_db_server-0.1.0/mcp_db_server.egg-info/requires.txt

@@ -0,0 +1,5 @@
+mcp
+python-dotenv
+pymysql
+cryptography
+DBUtils

mcp_db_server-0.1.0/mcp_db_server.egg-info/top_level.txt

@@ -0,0 +1 @@
+db

mcp_db_server-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-db-server"
+version = "0.1.0"
+description = "MCP Database Server with read-only access"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+  {name = "User", email = "user@example.com"}
+]
+dependencies = [
+    "mcp",
+    "python-dotenv",
+    "pymysql",
+    "cryptography",
+    "DBUtils"
+]
+
+[project.scripts]
+mcp-db-server = "server:main"  # Assuming we refactor server.py to have a main() function exposed

mcp_db_server-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+