mcp-win-stdio-db 0.2.3__tar.gz

mcp_win_stdio_db-0.2.3/.gitignore

@@ -0,0 +1,60 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+*.manifest
+*.spec
+api.txt
+pip-log.txt
+pip-delete-this-directory.txt
+pypi api.txt
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+*.mo
+*.pot
+
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+.idea/
+.vscode/
+*.swp
+*.swo
+
+*.log

mcp_win_stdio_db-0.2.3/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: mcp-win-stdio-db
+Version: 0.2.3
+Summary: Unified Database Model Context Protocol (MCP) server for PostgreSQL & MySQL: 20 tools for multi-server querying, DBA operations (create, drop, clone, dump, terminate), and cross-schema auto-resolution.
+Author: Mohan Kumar Indala
+License-Expression: MIT
+Keywords: ai,claude,database,dba,llm,mariadb,mcp,mysql,postgres,postgresql
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Requires-Dist: mcp-win-stdio>=0.2.3
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: pymysql>=1.1.0
+Description-Content-Type: text/markdown
+
+# mcp-win-stdio-db
+
+Unified Database Model Context Protocol (MCP) server for **PostgreSQL** and **MySQL** with multi-server in-memory pooling, sibling database auto-derivation, cross-schema resolution, and complete DBA operations.
+
+Part of the **`mcp-win-stdio`** Windows-optimized suite.
+
+---
+
+## 🚀 Features (20 Tools)
+
+- **Polyglot Database Engine**: Handles PostgreSQL (`psycopg2`) and MySQL (`pymysql`) transparently side-by-side.
+- **In-Memory Connection Pooling**: Fast continuous queries with zero reconnection latency and persistent `use_database` sticky state.
+- **Detailed Diagnostic Error Reporting**: Forwards native PostgreSQL error codes (e.g. 23503 FK violation), offending constraint names, column names, and error details directly to Claude so issues can be diagnosed immediately.
+- **Sibling Database Auto-Derivation**: On PostgreSQL (`localhost:5432`), auto-discovers sibling databases (`showreel`, `dsr`, `location_booking`, `sap`, etc.) on the fly.
+- **DBA & Management Tools**: `create_database`, `drop_database` (with safety guard), `clone_database` (instant template clone), `terminate_connections`, `list_active_queries`, `dump_database`, and `restore_database`.
+- **Self-Contained `SERVERS` JSON**: Configure multiple database instances in one environment variable without external files.
+
+---
+
+## 🛠️ Included Tools (20 Tools)
+
+1. `list_connections`: Lists all active and configured database connections.
+2. `use_database`: Switches active connection or switches database on current server.
+3. `list_databases`: Lists all databases on the active server.
+4. `list_schemas`: Lists all schemas in the active PostgreSQL database.
+5. `describe_table`: Detailed schema inspection (columns, nullability, PKs, FKs, indexes). Auto-resolves cross-schema tables in PostgreSQL.
+6. `schema_overview`: Compact overview of all user tables and views.
+7. `get_table_sample`: Returns sample rows and estimated row count.
+8. `search_schema`: Case-insensitive regex search for table, view, or column names.
+9. `read_query`: Safe SELECT queries returning structured JSON with row counts.
+10. `execute_query`: Executes DML / DDL statements with transaction commit/rollback and detailed error forwarding.
+11. `explain_query`: Generates EXPLAIN query execution plan.
+12. `get_database_stats`: Table sizes, row estimates, index sizes, and total database size.
+13. `add_connection`: Dynamically adds a new PostgreSQL or MySQL connection string at runtime.
+14. `create_database`: Creates a new database on the active server.
+15. `drop_database`: Safety-guarded DROP DATABASE (requires `confirmName` matching target name).
+16. `clone_database`: Fast database cloning using PostgreSQL TEMPLATE mechanism.
+17. `terminate_connections`: Terminates active connections to a specific database (PostgreSQL only).
+18. `list_active_queries`: Lists running queries, connection duration, and process IDs.
+19. `dump_database`: Dumps database to SQL file using native `pg_dump` or `mysqldump`.
+20. `restore_database`: Restores database from SQL dump file using native `psql` or `mysql`.
+
+---
+
+## 📦 Installation
+
+```powershell
+pip install mcp-win-stdio-db
+```
+*(Installing this package automatically installs `mws` CLI orchestrator)*.
+
+---
+
+## 🚀 One-Command Claude Setup
+
+```powershell
+mws setup db
+# or:
+mws add db
+```
+
+### Manual Configuration Example
+In `%APPDATA%\Claude\claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "db": {
+      "command": "python",
+      "args": ["-m", "mcp_win_stdio.db"],
+      "env": {
+        "SERVERS": "{\"postgres\":\"postgresql://postgres:password@localhost:5432/mydb\",\"mysql\":\"mysql://user:pass@localhost:3306/mydb\"}"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 📖 CLI Commands & Interactive Guide
+
+```powershell
+mws db guide       # Complete tool reference & prompt recipes
+mws db doctor      # Verify PostgreSQL/MySQL adapters and native dump tools
+mws db setup       # Configure Claude Desktop / Claude Code
+mws db run         # Launch server over stdio
+```
+
+---
+
+## 📜 License
+MIT License. Copyright (c) 2026 Mohan Kumar Indala.

mcp_win_stdio_db-0.2.3/README.md

@@ -0,0 +1,92 @@
+# mcp-win-stdio-db
+
+Unified Database Model Context Protocol (MCP) server for **PostgreSQL** and **MySQL** with multi-server in-memory pooling, sibling database auto-derivation, cross-schema resolution, and complete DBA operations.
+
+Part of the **`mcp-win-stdio`** Windows-optimized suite.
+
+---
+
+## 🚀 Features (20 Tools)
+
+- **Polyglot Database Engine**: Handles PostgreSQL (`psycopg2`) and MySQL (`pymysql`) transparently side-by-side.
+- **In-Memory Connection Pooling**: Fast continuous queries with zero reconnection latency and persistent `use_database` sticky state.
+- **Detailed Diagnostic Error Reporting**: Forwards native PostgreSQL error codes (e.g. 23503 FK violation), offending constraint names, column names, and error details directly to Claude so issues can be diagnosed immediately.
+- **Sibling Database Auto-Derivation**: On PostgreSQL (`localhost:5432`), auto-discovers sibling databases (`showreel`, `dsr`, `location_booking`, `sap`, etc.) on the fly.
+- **DBA & Management Tools**: `create_database`, `drop_database` (with safety guard), `clone_database` (instant template clone), `terminate_connections`, `list_active_queries`, `dump_database`, and `restore_database`.
+- **Self-Contained `SERVERS` JSON**: Configure multiple database instances in one environment variable without external files.
+
+---
+
+## 🛠️ Included Tools (20 Tools)
+
+1. `list_connections`: Lists all active and configured database connections.
+2. `use_database`: Switches active connection or switches database on current server.
+3. `list_databases`: Lists all databases on the active server.
+4. `list_schemas`: Lists all schemas in the active PostgreSQL database.
+5. `describe_table`: Detailed schema inspection (columns, nullability, PKs, FKs, indexes). Auto-resolves cross-schema tables in PostgreSQL.
+6. `schema_overview`: Compact overview of all user tables and views.
+7. `get_table_sample`: Returns sample rows and estimated row count.
+8. `search_schema`: Case-insensitive regex search for table, view, or column names.
+9. `read_query`: Safe SELECT queries returning structured JSON with row counts.
+10. `execute_query`: Executes DML / DDL statements with transaction commit/rollback and detailed error forwarding.
+11. `explain_query`: Generates EXPLAIN query execution plan.
+12. `get_database_stats`: Table sizes, row estimates, index sizes, and total database size.
+13. `add_connection`: Dynamically adds a new PostgreSQL or MySQL connection string at runtime.
+14. `create_database`: Creates a new database on the active server.
+15. `drop_database`: Safety-guarded DROP DATABASE (requires `confirmName` matching target name).
+16. `clone_database`: Fast database cloning using PostgreSQL TEMPLATE mechanism.
+17. `terminate_connections`: Terminates active connections to a specific database (PostgreSQL only).
+18. `list_active_queries`: Lists running queries, connection duration, and process IDs.
+19. `dump_database`: Dumps database to SQL file using native `pg_dump` or `mysqldump`.
+20. `restore_database`: Restores database from SQL dump file using native `psql` or `mysql`.
+
+---
+
+## 📦 Installation
+
+```powershell
+pip install mcp-win-stdio-db
+```
+*(Installing this package automatically installs `mws` CLI orchestrator)*.
+
+---
+
+## 🚀 One-Command Claude Setup
+
+```powershell
+mws setup db
+# or:
+mws add db
+```
+
+### Manual Configuration Example
+In `%APPDATA%\Claude\claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "db": {
+      "command": "python",
+      "args": ["-m", "mcp_win_stdio.db"],
+      "env": {
+        "SERVERS": "{\"postgres\":\"postgresql://postgres:password@localhost:5432/mydb\",\"mysql\":\"mysql://user:pass@localhost:3306/mydb\"}"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 📖 CLI Commands & Interactive Guide
+
+```powershell
+mws db guide       # Complete tool reference & prompt recipes
+mws db doctor      # Verify PostgreSQL/MySQL adapters and native dump tools
+mws db setup       # Configure Claude Desktop / Claude Code
+mws db run         # Launch server over stdio
+```
+
+---
+
+## 📜 License
+MIT License. Copyright (c) 2026 Mohan Kumar Indala.

mcp_win_stdio_db-0.2.3/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-win-stdio-db"
+version = "0.2.3"
+description = "Unified Database Model Context Protocol (MCP) server for PostgreSQL & MySQL: 20 tools for multi-server querying, DBA operations (create, drop, clone, dump, terminate), and cross-schema auto-resolution."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Mohan Kumar Indala" }
+]
+keywords = ["mcp", "claude", "database", "postgres", "postgresql", "mysql", "mariadb", "dba", "ai", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Win32 (MS Windows)",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+]
+
+dependencies = [
+    "mcp-win-stdio>=0.2.3",
+    "mcp>=1.2.0",
+    "psycopg2-binary>=2.9.0",
+    "pymysql>=1.1.0",
+]
+
+[project.scripts]
+mcp-win-stdio-db = "mcp_win_stdio.db.cli:main"
+mws-db = "mcp_win_stdio.db.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_win_stdio"]

mcp_win_stdio_db-0.2.3/src/mcp_win_stdio/db/__init__.py

@@ -0,0 +1,5 @@
+"""
+Unified Database MCP Server for mcp-win-stdio (PostgreSQL & MySQL).
+"""
+
+__version__ = "0.2.3"

mcp_win_stdio_db-0.2.3/src/mcp_win_stdio/db/__main__.py

@@ -0,0 +1,8 @@
+"""
+Direct module execution for mcp_win_stdio.db.
+"""
+
+from mcp_win_stdio.db.server import mcp
+
+if __name__ == "__main__":
+    mcp.run()

mcp_win_stdio_db-0.2.3/src/mcp_win_stdio/db/cli.py

@@ -0,0 +1,87 @@
+"""
+CLI entry point for mcp-win-stdio-db.
+"""
+
+import argparse
+import sys
+from mcp_win_stdio.db import __version__
+from mcp_win_stdio.db.server import mcp
+
+
+def cmd_run(args: argparse.Namespace) -> None:
+    """Run Database MCP server over stdio."""
+    mcp.run()
+
+
+def cmd_doctor(args: argparse.Namespace) -> None:
+    """Check Database MCP health and dependencies."""
+    print(f"\n=== mcp-win-stdio-db Doctor Diagnostic (v{__version__}) ===\n")
+    print(f"[OK] Python: {sys.version.split()[0]} ({sys.executable})")
+
+    for dep in ("mcp", "psycopg2", "pymysql"):
+        try:
+            __import__(dep)
+            print(f"[OK] Driver: {dep:<12}")
+        except ImportError:
+            print(f"[FAIL] Driver: {dep:<12} (MISSING - run `pip install {dep}`)")
+
+    print("\n--- Native DB Dump Utilities ---")
+    import shutil
+    for util in ("pg_dump", "psql", "mysqldump", "mysql"):
+        loc = shutil.which(util)
+        if loc:
+            print(f"[OK] Tool: {util:<12} -> {loc}")
+        else:
+            print(f"[INFO] Tool: {util:<12} -> (Not on PATH, fallback SQL execution used)")
+
+    print("\nDiagnostic complete.\n")
+
+
+def cmd_guide(args: argparse.Namespace) -> None:
+    """Print guide and prompt recipes."""
+    print("""
+=== mcp-win-stdio-db Guide & Recipes ===
+
+Tools Provided:
+  - list_connections, use_database, list_databases, list_schemas
+  - describe_table, schema_overview, get_table_sample, search_schema
+  - read_query, execute_query, explain_query, get_database_stats
+  - create_database, drop_database, clone_database, terminate_connections
+  - list_active_queries, dump_database, restore_database
+
+Configuration:
+  Pass SERVERS env var as JSON:
+  SERVERS='{"showreel":"postgresql://...","dsr":"postgresql://...","ijitest":"mysql://..."}'
+
+Run in Claude / Copilot:
+  python -m mcp_win_stdio.db.server
+""")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="mcp-win-stdio-db",
+        description="Unified Database MCP Server CLI (PostgreSQL & MySQL)",
+    )
+    parser.add_argument("--version", "-v", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    sub_guide = subparsers.add_parser("guide", help="View usage guide and recipes")
+    sub_guide.set_defaults(func=cmd_guide)
+
+    sub_doctor = subparsers.add_parser("doctor", help="Check database drivers and native tools")
+    sub_doctor.set_defaults(func=cmd_doctor)
+
+    sub_run = subparsers.add_parser("run", help="Run Database MCP server over stdio")
+    sub_run.set_defaults(func=cmd_run)
+
+    args = parser.parse_args()
+    if hasattr(args, "func"):
+        args.func(args)
+    else:
+        # Default action is run
+        cmd_run(args)
+
+
+if __name__ == "__main__":
+    main()

mcp_win_stdio_db-0.2.3/src/mcp_win_stdio/db/guide.py

@@ -0,0 +1,165 @@
+"""
+Usage guide and prompt recipes for Database MCP server (mcp-win-stdio.db).
+"""
+
+def print_db_guide() -> None:
+    guide_text = """
+================================================================================
+           Polyglot Database MCP Server (mcp-win-stdio.db)
+================================================================================
+
+Description:
+  Unified Model Context Protocol server for PostgreSQL and MySQL databases.
+  Supports cross-database switching, cross-schema auto-resolution, fast JSON queries,
+  DBA administrative tools (safe DROP, CREATE, CLONE), native DUMP / RESTORE,
+  DDL reconstruction, PII-safe sampling, database-wide health auditing, and
+  schema diff with auto-generated migration SQL.
+
+Available Tools (23 Tools):
+--------------------------------------------------------------------------------
+CONNECTION MANAGEMENT
+1.  list_connections
+    - Lists all active and configured database connections from SERVERS env.
+
+2.  use_database
+    - Switches active connection or switches database on current server.
+    - Args: name (str), database (optional str)
+
+3.  add_connection
+    - Dynamically adds a new PostgreSQL or MySQL connection string at runtime.
+    - Args: name (str), url (str)
+
+SCHEMA INSPECTION
+4.  list_databases
+    - Lists all databases on the active server.
+
+5.  list_schemas
+    - Lists all schemas in the active PostgreSQL database.
+
+6.  describe_table
+    - Full schema inspection: columns, data types, nullability, defaults, PKs,
+      foreign keys, and indexes. Auto-resolves cross-schema tables in PostgreSQL.
+    - Args: tableName (str), schemaName (optional str)
+
+7.  schema_overview
+    - Compact overview of all user tables and views.
+    - Args: schemaName (optional str)
+
+8.  compact_schema_overview                                          [NEW v0.2.3]
+    - Ultra-compact one-liner per table: schema.table (col: type PK, col2: FK->ref)
+    - Ideal for large databases — fits entire schema in minimal tokens.
+    - Args: schemaName (optional str), connection (optional str)
+
+9.  get_table_ddl                                                    [NEW v0.2.3]
+    - Reconstructs the full CREATE TABLE DDL with column types, NOT NULL,
+      defaults, all constraints (PK, FK, UNIQUE, CHECK), and extra indexes.
+    - PostgreSQL only (MySQL falls back to SHOW CREATE TABLE).
+    - Args: tableName (str), schema (optional str), connection (optional str)
+
+10. search_schema
+    - Case-insensitive regex search for table, view, or column names.
+    - Args: query (str)
+
+DATA ACCESS
+11. get_table_sample                                                 [NEW v0.2.3]
+    - Returns sample rows (default: 5) and estimated row count for quick inspection.
+    - mask_sensitive=True (default) auto-redacts PII columns (password, token,
+      secret, ssn, api_key, credit_card, etc.) as [REDACTED_SENSITIVE].
+    - Args: tableName (str), schemaName (optional str), limit (optional int),
+            mask_sensitive (optional bool, default: True)
+
+12. read_query
+    - Safe SELECT queries returning structured JSON with row counts.
+    - Args: sql (str), limit (optional int)
+
+13. execute_query
+    - Executes DML / DDL statements (INSERT, UPDATE, DELETE, CREATE, ALTER) with
+      transaction commit/rollback and affected row counts.
+    - Args: sql (str), dry_run (optional bool)
+
+14. explain_query
+    - Generates EXPLAIN query execution plan.
+    - Args: sql (str), analyze (optional bool)
+
+DIAGNOSTICS & HEALTH
+15. get_database_stats
+    - Table size, row estimates, index sizes, and total database size.
+
+16. list_active_queries
+    - Lists running queries, connection duration, and process IDs.
+
+17. audit_database_health                                            [NEW v0.2.3]
+    - Database-wide health audit (PostgreSQL only). Returns three categories:
+        • unindexed_foreign_keys: FK columns lacking a supporting index (slow JOINs).
+        • unused_indexes: Indexes with zero scans — candidates for DROP.
+        • bloated_tables: Tables with >20% dead tuples needing VACUUM.
+    - Each finding includes a 'fix' field with the recommended SQL statement.
+    - Args: schema (optional str, default: 'public', use '*' for all schemas),
+            connection (optional str)
+
+18. compare_schemas                                                  [ENHANCED]
+    - Compares two connections: missing tables, missing columns, type mismatches.
+    - Now includes migration_sql: auto-generated ALTER/CREATE statements to bring
+      target schema up to source.
+    - Args: source_connection (str), target_connection (str), schema (optional str)
+
+DBA MANAGEMENT
+19. create_database
+    - Creates a new database on the active server.
+    - Args: name (str), template (optional str, Postgres only), encoding (optional str)
+
+20. drop_database
+    - Safety-guarded DROP DATABASE (requires confirmName matching target name).
+    - Args: name (str), confirmName (str), force (optional bool)
+
+21. clone_database
+    - Fast database cloning using PostgreSQL TEMPLATE mechanism.
+    - Args: sourceDb (str), targetDb (str)
+
+22. terminate_connections
+    - Terminates active connections to a specific database (PostgreSQL only).
+    - Args: dbName (str)
+
+23. dump_database / restore_database
+    - dump_database: Dumps database to SQL file using native pg_dump or mysqldump.
+      Args: outputPath (str), tables (optional list)
+    - restore_database: Restores database from SQL dump file using native psql or mysql.
+      Args: inputPath (str), targetDb (optional str)
+
+--------------------------------------------------------------------------------
+Error Handling:
+--------------------------------------------------------------------------------
+All tools return rich PostgreSQL error details when a query fails:
+  • pgcode       — PostgreSQL error code (e.g. 23503 for FK violation)
+  • severity     — ERROR / FATAL / WARNING
+  • detail       — Full PostgreSQL DETAIL message
+  • hint         — PostgreSQL HINT for resolution
+  • constraint   — Constraint name (for constraint violations)
+  • table        — Table name from error context
+  • suggestion   — Human-readable fix suggestion from the built-in suggestion map
+
+--------------------------------------------------------------------------------
+Environment Variables:
+--------------------------------------------------------------------------------
+* SERVERS: JSON dictionary mapping server names to connection strings.
+  Example:
+  {
+    "showreel": "postgresql://postgres:pass@localhost:5432/showreel",
+    "dsr": "postgresql://postgres:pass@localhost:5432/dsr",
+    "ijitest": "mysql://user:pass@srv604.hstgr.io:3306/db_name"
+  }
+
+--------------------------------------------------------------------------------
+Example Prompts for Claude:
+--------------------------------------------------------------------------------
+* "What databases are configured and what tables are in the active database?"
+* "Switch to the ijitest database and describe the users table."
+* "Show me the full DDL for the orders table."
+* "Show a sample of the users table — mask any sensitive columns."
+* "Run a health audit on the showreel database and tell me what to fix."
+* "Compare the dev and prod schemas and generate migration SQL for differences."
+* "Create a clone of the showreel database named showreel_backup."
+* "Show the active queries running on PostgreSQL right now."
+================================================================================
+"""
+    print(guide_text)