pgsafe-mcp 1.0.0__py3-none-any.whl

pgsafe/__init__.py

@@ -0,0 +1,8 @@
+"""
+PgSafe MCP (Lite Edition)
+Zero-Trust Database Inspection and Safe Query Guard MCP Server for AI Agents.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Johann Schiffer / NEXUS"
+__license__ = "MIT"

pgsafe/_genesis.py

@@ -0,0 +1,11 @@
+"""Upgrade notice. Printed to stderr so MCP stdio traffic on stdout is never affected."""
+import os
+import sys
+
+NOTICE = 'PgSafe MCP (open edition). Starter Kit, free: https://johanld.gumroad.com/l/khffw | Enterprise Suite ($19): https://johanld.gumroad.com/l/tzuvz'
+
+
+def print_upgrade_notice():
+    if os.environ.get("GENESIS_NO_NOTICE") == "1":
+        return
+    print(NOTICE, file=sys.stderr)

pgsafe/adapters/base.py

@@ -0,0 +1,26 @@
+"""
+Base Database Adapter Interface for PgSafe.
+"""
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, Tuple
+
+class BaseAdapter(ABC):
+    @abstractmethod
+    def connect(self):
+        """Establishes database connection."""
+        pass
+
+    @abstractmethod
+    def list_tables(self) -> List[str]:
+        """Returns list of user tables in the database."""
+        pass
+
+    @abstractmethod
+    def describe_table(self, table_name: str) -> List[Dict[str, Any]]:
+        """Returns column names, types, and constraints for a table."""
+        pass
+
+    @abstractmethod
+    def execute_read_only(self, sql: str) -> Tuple[List[str], List[List[Any]]]:
+        """Executes a read-only query and returns (columns, rows)."""
+        pass

pgsafe/adapters/postgres_adapter.py

@@ -0,0 +1,72 @@
+"""
+PostgreSQL Database Adapter with READ ONLY transaction guarantees.
+"""
+from typing import List, Dict, Any, Tuple, Optional
+from .base import BaseAdapter
+
+class PostgresAdapter(BaseAdapter):
+    def __init__(self, connection_url: str):
+        self.connection_url = connection_url
+        self._conn = None
+
+    def connect(self):
+        if self._conn:
+            return self._conn
+
+        try:
+            # Attempt psycopg2 or psycopg or asyncpg
+            import psycopg
+            self._conn = psycopg.connect(self.connection_url)
+            # Guarantee read-only session at PostgreSQL engine level
+            with self._conn.cursor() as cur:
+                cur.execute("SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;")
+            return self._conn
+        except ImportError:
+            try:
+                import psycopg2
+                self._conn = psycopg2.connect(self.connection_url)
+                self._conn.set_session(readonly=True)
+                return self._conn
+            except ImportError:
+                raise RuntimeError(
+                    "PostgreSQL driver not installed. Install psycopg via: pip install psycopg[binary] "
+                    "or use SQLite adapter."
+                )
+
+    def list_tables(self) -> List[str]:
+        conn = self.connect()
+        with conn.cursor() as cur:
+            cur.execute("""
+                SELECT table_name 
+                FROM information_schema.tables 
+                WHERE table_schema = 'public' 
+                ORDER BY table_name;
+            """)
+            return [r[0] for r in cur.fetchall()]
+
+    def describe_table(self, table_name: str) -> List[Dict[str, Any]]:
+        conn = self.connect()
+        with conn.cursor() as cur:
+            cur.execute("""
+                SELECT column_name, data_type, is_nullable, column_default
+                FROM information_schema.columns
+                WHERE table_schema = 'public' AND table_name = %s
+                ORDER BY ordinal_position;
+            """, (table_name,))
+            return [
+                {
+                    "name": r[0],
+                    "type": r[1],
+                    "nullable": r[2] == "YES",
+                    "default": r[3]
+                }
+                for r in cur.fetchall()
+            ]
+
+    def execute_read_only(self, sql: str) -> Tuple[List[str], List[List[Any]]]:
+        conn = self.connect()
+        with conn.cursor() as cur:
+            cur.execute(sql)
+            columns = [desc[0] for desc in cur.description] if cur.description else []
+            rows = [list(r) for r in cur.fetchall()]
+            return columns, rows

pgsafe/adapters/sqlite_adapter.py

@@ -0,0 +1,57 @@
+"""
+SQLite Database Adapter with Read-Only URI enforcement.
+"""
+import sqlite3
+from typing import List, Dict, Any, Tuple
+from .base import BaseAdapter
+
+class SQLiteAdapter(BaseAdapter):
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        self._conn = None
+
+    def connect(self):
+        if not self._conn:
+            # Enforce read-only mode via SQLite URI if file exists
+            uri = f"file:{self.db_path}?mode=ro"
+            try:
+                self._conn = sqlite3.connect(uri, uri=True, timeout=10.0)
+            except sqlite3.OperationalError:
+                # Fallback to standard connect with PRAGMA query_only
+                self._conn = sqlite3.connect(self.db_path, timeout=10.0)
+                self._conn.execute("PRAGMA query_only = ON;")
+            self._conn.row_factory = sqlite3.Row
+        return self._conn
+
+    def list_tables(self) -> List[str]:
+        conn = self.connect()
+        cursor = conn.cursor()
+        cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name;")
+        return [row[0] for row in cursor.fetchall()]
+
+    def describe_table(self, table_name: str) -> List[Dict[str, Any]]:
+        conn = self.connect()
+        cursor = conn.cursor()
+        # Sanitize table_name to identifier
+        safe_name = "".join(c for c in table_name if c.isalnum() or c == "_")
+        cursor.execute(f"PRAGMA table_info({safe_name});")
+        rows = cursor.fetchall()
+        return [
+            {
+                "cid": r[0],
+                "name": r[1],
+                "type": r[2],
+                "notnull": bool(r[3]),
+                "dflt_value": r[4],
+                "pk": bool(r[5])
+            }
+            for r in rows
+        ]
+
+    def execute_read_only(self, sql: str) -> Tuple[List[str], List[List[Any]]]:
+        conn = self.connect()
+        cursor = conn.cursor()
+        cursor.execute(sql)
+        columns = [desc[0] for desc in cursor.description] if cursor.description else []
+        rows = [list(r) for r in cursor.fetchall()]
+        return columns, rows

pgsafe/cli.py

@@ -0,0 +1,74 @@
+"""
+PgSafe CLI inspection tool.
+Usage:
+  python -m pgsafe.cli tables --db sqlite:///demo.db
+  python -m pgsafe.cli describe users --db sqlite:///demo.db
+  python -m pgsafe.cli query "SELECT * FROM users" --db sqlite:///demo.db
+"""
+
+import argparse
+import json
+import sys
+from .adapters.sqlite_adapter import SQLiteAdapter
+from .adapters.postgres_adapter import PostgresAdapter
+from .guards.readonly import ReadOnlyGuard
+from .guards.cost_analyzer import CostAnalyzer
+
+def main():
+    parser = argparse.ArgumentParser(description="PgSafe CLI database utility")
+    parser.add_argument("--db", default="sqlite:///data/nexus.db", help="Database connection URL")
+    subparsers = parser.add_subparsers(dest="command", help="Sub-commands")
+
+    subparsers.add_parser("tables", help="List database tables")
+
+    desc_parser = subparsers.add_parser("describe", help="Describe table structure")
+    desc_parser.add_argument("table", help="Table name")
+
+    query_parser = subparsers.add_parser("query", help="Execute safe read-only query")
+    query_parser.add_argument("sql", help="SQL query")
+    query_parser.add_argument("--limit", type=int, default=100, help="Row limit")
+
+    args = parser.parse_args()
+
+    url = args.db
+    if url.startswith("postgres://") or url.startswith("postgresql://"):
+        adapter = PostgresAdapter(url)
+    else:
+        clean_path = url.replace("sqlite:///", "").replace("sqlite://", "")
+        adapter = SQLiteAdapter(clean_path)
+
+    if args.command == "tables":
+        tables = adapter.list_tables()
+        print(json.dumps({"tables": tables, "count": len(tables)}, indent=2))
+
+    elif args.command == "describe":
+        cols = adapter.describe_table(args.table)
+        print(json.dumps({"table": args.table, "columns": cols}, indent=2))
+
+    elif args.command == "query":
+        is_safe, reason = ReadOnlyGuard.validate(args.sql)
+        if not is_safe:
+            print(f"[SECURITY BLOCKED] {reason}", file=sys.stderr)
+            sys.exit(1)
+
+        safe_sql = CostAnalyzer.enforce_limit(args.sql, default_limit=args.limit)
+        cols, rows = adapter.execute_read_only(safe_sql)
+        print(json.dumps({"columns": cols, "rows": rows, "count": len(rows)}, indent=2))
+
+    else:
+        parser.print_help()
+
+
+
+_main_impl = main
+
+
+def main():
+    from ._genesis import print_upgrade_notice
+    try:
+        return _main_impl()
+    finally:
+        print_upgrade_notice()
+
+if __name__ == "__main__":
+    main()

pgsafe/guards/cost_analyzer.py

@@ -0,0 +1,41 @@
+"""
+Query Cost and Performance Safety Guard.
+Enforces query limits and guards against unconstrained table scans.
+"""
+import re
+
+class CostAnalyzer:
+    @staticmethod
+    def enforce_limit(sql: str, default_limit: int = 100, max_limit: int = 1000) -> str:
+        """
+        Inspects SQL and ensures a LIMIT clause is applied.
+        If a LIMIT is present and exceeds max_limit, caps it.
+        If no LIMIT is present, appends default_limit.
+        """
+        cleaned = sql.strip().rstrip(";")
+        limit_match = re.search(r"\bLIMIT\s+(\d+)\b", cleaned, re.IGNORECASE)
+
+        if limit_match:
+            current_limit = int(limit_match.group(1))
+            if current_limit > max_limit:
+                return re.sub(r"\bLIMIT\s+\d+\b", f"LIMIT {max_limit}", cleaned, flags=re.IGNORECASE)
+            return cleaned
+        else:
+            return f"{cleaned} LIMIT {default_limit}"
+
+    @staticmethod
+    def evaluate_risk(sql: str) -> dict:
+        """Evaluates heuristic risk metrics."""
+        warnings = []
+        sql_upper = sql.upper()
+
+        if "WHERE" not in sql_upper and "SELECT" in sql_upper:
+            warnings.append("Query lacks a WHERE clause; full table scan may occur.")
+
+        if "JOIN" in sql_upper and "ON" not in sql_upper and "USING" not in sql_upper:
+            warnings.append("JOIN statement without explicit ON/USING condition (possible Cartesian product).")
+
+        return {
+            "risk_level": "medium" if warnings else "low",
+            "warnings": warnings
+        }

pgsafe/guards/readonly.py

@@ -0,0 +1,57 @@
+"""
+SQL Read-Only Security Guard.
+Inspects SQL statements to guarantee no mutations or destructive statements are executed.
+"""
+import re
+from typing import Tuple
+
+BLOCKED_PATTERNS = [
+    r"\bDROP\b",
+    r"\bTRUNCATE\b",
+    r"\bDELETE\b",
+    r"\bUPDATE\b",
+    r"\bINSERT\b",
+    r"\bALTER\b",
+    r"\bCREATE\b",
+    r"\bGRANT\b",
+    r"\bREVOKE\b",
+    r"\bEXEC\b",
+    r"\bEXECUTE\b",
+    r"\bCALL\b",
+    r"\bRENAME\b",
+    r"\bREPLACE\b"
+]
+
+COMPILED_BLOCKED = [re.compile(p, re.IGNORECASE) for p in BLOCKED_PATTERNS]
+
+class ReadOnlyGuard:
+    @staticmethod
+    def validate(sql: str) -> Tuple[bool, str]:
+        """
+        Validates whether SQL is strictly read-only.
+        Returns (is_safe: bool, reason: str).
+        """
+        cleaned = sql.strip()
+        if not cleaned:
+            return False, "Empty query provided."
+
+        # Remove SQL comments (-- comment and /* comment */)
+        cleaned_no_comments = re.sub(r"--.*?$", "", cleaned, flags=re.MULTILINE)
+        cleaned_no_comments = re.sub(r"/\*.*?\*/", "", cleaned_no_comments, flags=re.DOTALL).strip()
+
+        # Check semicolon chaining (disallow multi-statement injection)
+        statements = [s.strip() for s in cleaned_no_comments.split(";") if s.strip()]
+        if len(statements) > 1:
+            return False, "Multiple SQL statements detected (semicolon chaining disallowed)."
+
+        first_word = statements[0].split()[0].upper() if statements else ""
+        allowed_starts = {"SELECT", "EXPLAIN", "WITH", "PRAGMA", "SHOW", "DESCRIBE"}
+        if first_word not in allowed_starts:
+            return False, f"Statement type '{first_word}' is disallowed. Only read-only queries are permitted."
+
+        for pattern in COMPILED_BLOCKED:
+            if pattern.search(cleaned_no_comments):
+                match = pattern.pattern.replace(r"\b", "")
+                return False, f"Blocked keyword detected in query: '{match}'"
+
+        return True, "Query verified as read-only."

pgsafe/server.py

@@ -0,0 +1,248 @@
+"""
+PgSafe MCP: Model Context Protocol Server (Lite Edition)
+Implements standard JSON-RPC 2.0 stdio transport with Zero-Trust database access.
+"""
+
+import sys
+import os
+import json
+import logging
+from typing import Dict, Any, List, Optional
+from .guards.readonly import ReadOnlyGuard
+from .guards.cost_analyzer import CostAnalyzer
+from .adapters.sqlite_adapter import SQLiteAdapter
+from .adapters.postgres_adapter import PostgresAdapter
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] [PgSafe] %(message)s",
+    stream=sys.stderr
+)
+logger = logging.getLogger("PgSafeServer")
+
+class PgSafeMCPServer:
+    def __init__(self, db_url: Optional[str] = None):
+        self.db_url = db_url or os.getenv("DATABASE_URL", "sqlite:///demo.db")
+        self.server_name = "pgsafe-mcp"
+        self.server_version = "1.0.0"
+        self.adapter = self._init_adapter(self.db_url)
+
+    def _init_adapter(self, url: str):
+        if url.startswith("postgres://") or url.startswith("postgresql://"):
+            return PostgresAdapter(url)
+        else:
+            # Assume SQLite path or sqlite:///
+            clean_path = url.replace("sqlite:///", "").replace("sqlite://", "")
+            return SQLiteAdapter(clean_path)
+
+    def get_tools_definition(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "list_tables",
+                "description": "List all public database tables available for inspection and querying.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {}
+                }
+            },
+            {
+                "name": "describe_table",
+                "description": "Retrieve column definitions, data types, nullability, and keys for a specific table.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "table_name": {
+                            "type": "string",
+                            "description": "Name of the table to inspect"
+                        }
+                    },
+                    "required": ["table_name"]
+                }
+            },
+            {
+                "name": "safe_query",
+                "description": "Execute a strictly read-only SQL query with automatic LIMIT enforcement and mutation blocking.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "SQL query to execute (must be SELECT/EXPLAIN)"
+                        },
+                        "limit": {
+                            "type": "integer",
+                            "description": "Maximum rows to return (default: 100, max: 1000)"
+                        }
+                    },
+                    "required": ["query"]
+                }
+            },
+            {
+                "name": "analyze_query",
+                "description": "Analyze a SQL query for dangerous operations, unindexed scans, and Cartesian join risks without executing it.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "SQL query to inspect"
+                        }
+                    },
+                    "required": ["query"]
+                }
+            }
+        ]
+
+    def handle_tool_call(self, name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        if name == "list_tables":
+            tables = self.adapter.list_tables()
+            return {"success": True, "tables": tables, "count": len(tables)}
+
+        elif name == "describe_table":
+            table_name = arguments.get("table_name", "")
+            columns = self.adapter.describe_table(table_name)
+            return {"success": True, "table": table_name, "columns": columns}
+
+        elif name == "safe_query":
+            raw_sql = arguments.get("query", "")
+            limit = arguments.get("limit", 100)
+
+            # 1. Read-only validation
+            is_safe, reason = ReadOnlyGuard.validate(raw_sql)
+            if not is_safe:
+                return {
+                    "success": False,
+                    "error": f"Security Guard Blocked Query: {reason}",
+                    "blocked": True
+                }
+
+            # 2. Limit enforcement & risk evaluation
+            safe_sql = CostAnalyzer.enforce_limit(raw_sql, default_limit=limit, max_limit=1000)
+            risk = CostAnalyzer.evaluate_risk(raw_sql)
+
+            # 3. Execution
+            try:
+                cols, rows = self.adapter.execute_read_only(safe_sql)
+                return {
+                    "success": True,
+                    "query_executed": safe_sql,
+                    "columns": cols,
+                    "rows": rows,
+                    "row_count": len(rows),
+                    "risk_analysis": risk
+                }
+            except Exception as e:
+                return {
+                    "success": False,
+                    "error": f"Database execution error: {str(e)}"
+                }
+
+        elif name == "analyze_query":
+            raw_sql = arguments.get("query", "")
+            is_safe, reason = ReadOnlyGuard.validate(raw_sql)
+            risk = CostAnalyzer.evaluate_risk(raw_sql)
+            return {
+                "success": True,
+                "is_read_only": is_safe,
+                "security_verdict": reason,
+                "performance_risk": risk
+            }
+
+        else:
+            raise ValueError(f"Unknown tool: {name}")
+
+    def handle_request(self, request: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        req_id = request.get("id")
+        method = request.get("method")
+        params = request.get("params", {})
+
+        if req_id is None:
+            if method == "notifications/initialized":
+                logger.info("Client completed initialization handshake.")
+            return None
+
+        if method == "initialize":
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {
+                    "protocolVersion": "2024-11-05",
+                    "capabilities": {"tools": {}},
+                    "serverInfo": {
+                        "name": self.server_name,
+                        "version": self.server_version
+                    }
+                }
+            }
+
+        elif method == "ping":
+            return {"jsonrpc": "2.0", "id": req_id, "result": {}}
+
+        elif method == "tools/list":
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {"tools": self.get_tools_definition()}
+            }
+
+        elif method == "tools/call":
+            tool_name = params.get("name")
+            tool_args = params.get("arguments", {})
+            try:
+                output = self.handle_tool_call(tool_name, tool_args)
+                return {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": json.dumps(output, indent=2, ensure_ascii=False)
+                            }
+                        ],
+                        "isError": not output.get("success", True) if "success" in output else False
+                    }
+                }
+            except Exception as e:
+                logger.error(f"Error calling tool {tool_name}: {e}")
+                return {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "error": {"code": -32000, "message": str(e)}
+                }
+        else:
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "error": {"code": -32601, "message": f"Method not found: {method}"}
+            }
+
+    def run_stdio(self):
+        logger.info(f"Starting {self.server_name} v{self.server_version} stdio listener...")
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                request = json.loads(line)
+                response = self.handle_request(request)
+                if response is not None:
+                    sys.stdout.write(json.dumps(response) + "\n")
+                    sys.stdout.flush()
+            except Exception as e:
+                logger.error(f"Error processing stdio line: {e}")
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(
+        prog="pgsafe-mcp",
+        description="PgSafe MCP: Zero-Trust Database Inspection & Safe Query Guard for AI Agents"
+    )
+    parser.add_argument("-v", "--version", action="version", version="%(prog)s 1.0.0")
+    parser.add_argument("--db-url", type=str, default=None, help="Database connection URL (Postgres or SQLite). Defaults to DATABASE_URL or sqlite:///demo.db")
+    args, unknown = parser.parse_known_args()
+    server = PgSafeMCPServer(db_url=args.db_url)
+    server.run_stdio()
+
+if __name__ == "__main__":
+    main()

pgsafe_mcp-1.0.0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: pgsafe-mcp
+Version: 1.0.0
+Summary: Zero-Trust Database Inspection and Safe Query Guard MCP Server for AI Agents
+Author: Johann Schiffer
+License: MIT
+Project-URL: Homepage, https://johannschiffer.github.io
+Project-URL: Repository, https://github.com/johannschiffer/pgsafe-mcp
+Project-URL: Starter Kit, https://johanld.gumroad.com/l/genesis-starter-kit
+Project-URL: Enterprise Suite, https://johanld.gumroad.com/l/genesis-enterprise-suite
+Keywords: mcp,model-context-protocol,postgres,sqlite,database,claude,cursor,security,ai-agent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1.0; extra == "postgres"
+Dynamic: license-file
+
+# PgSafe MCP (Lite Edition)
+
+<a href="https://glama.ai/mcp/servers/@johannschiffer/pgsafe-mcp">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@johannschiffer/pgsafe-mcp/badge" alt="pgsafe-mcp MCP server" />
+</a>
+
+
+> **Free:** [Genesis Starter Kit](https://johanld.gumroad.com/l/genesis-starter-kit) (25 `.cursorrules`/`CLAUDE.md` rulesets + MCP configs). Try the [live config builder](https://johannschiffer.github.io).
+> **Full stack:** all six servers in [Genesis Enterprise Suite ($19)](https://johanld.gumroad.com/l/genesis-enterprise-suite).
+
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-brightgreen.svg)](https://python.org)
+[![MCP Compliant](https://img.shields.io/badge/MCP-2024--11--05-purple.svg)](https://modelcontextprotocol.io)
+
+**PgSafe MCP** is a Zero-Trust Model Context Protocol server that enables AI agents in **Claude Desktop**, **Cursor**, **Windsurf**, and **Antigravity** to inspect schemas and run analytical SQL queries without risking accidental data loss, destructive mutations (`DROP`, `TRUNCATE`, `DELETE`), or runaway table scans.
+
+---
+
+## Run without cloning
+
+```bash
+uvx --from git+https://github.com/johannschiffer/pgsafe-mcp pgsafe-mcp
+```
+
+Claude Desktop / Cursor config entry:
+
+```json
+{
+  "mcpServers": {
+    "pgsafe-mcp": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/johannschiffer/pgsafe-mcp",
+        "pgsafe-mcp"
+      ]
+    }
+  }
+}
+```
+
+[![CI](https://github.com/johannschiffer/pgsafe-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/johannschiffer/pgsafe-mcp/actions/workflows/ci.yml)
+
+## 🛡️ Why PgSafe MCP?
+
+Giving an AI assistant raw access to your database is terrifying:
+1. **Accidental Deletions:** One ambiguous prompt can lead an LLM to generate `DROP TABLE` or `DELETE FROM users;`.
+2. **Production Table Locks:** An unindexed query with a multi-table Cartesian product can consume 100% CPU and lock production tables.
+3. **Multi-Statement Injection:** LLMs can be tricked via prompt injection into chaining malicious SQL commands (`SELECT 1; TRUNCATE audit_logs;`).
+
+**PgSafe** acts as a strict guardrail sitting between the AI agent and your database engine.
+
+---
+
+## ⚡ Features (Lite Edition)
+
+- 🔒 **Enforced Read-Only Guard**: Automatically detects and blocks all destructive statements (`DROP`, `TRUNCATE`, `ALTER`, `UPDATE`, `INSERT`, `DELETE`).
+- 🛑 **Anti-Chaining Protection**: Disallows multi-statement execution via semicolons.
+- ⏱️ **Automatic LIMIT Injection**: Ensures every `SELECT` query has a capped `LIMIT` clause (default: 100 rows, max: 1,000) to protect database memory.
+- 📊 **Zero-Cost Schema Reflection**: Tools to explore public tables and columns without executing custom introspection queries.
+- 🪶 **Zero Dependency Core**: Native support for SQLite out of the box; optional PostgreSQL adapter.
+
+---
+
+## 🚀 Quick Setup in 2 Minutes
+
+### 1. Installation
+
+```bash
+git clone https://github.com/johannschiffer/pgsafe-mcp.git
+cd pgsafe-mcp
+pip install .
+```
+
+For PostgreSQL support:
+```bash
+pip install "psycopg[binary]>=3.1.0"
+```
+
+### 2. Configure Claude Desktop (`claude_desktop_config.json`)
+
+On Linux: `~/.config/Claude/claude_desktop_config.json`  
+On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "pgsafe": {
+      "command": "python",
+      "args": ["-m", "pgsafe.server"],
+      "cwd": "/path/to/pgsafe-mcp",
+      "env": {
+        "DATABASE_URL": "postgresql://user:password@localhost:5432/production_db"
+      }
+    }
+  }
+}
+```
+
+For SQLite, simply point to your `.db` file:
+```json
+{
+  "mcpServers": {
+    "pgsafe": {
+      "command": "python",
+      "args": ["-m", "pgsafe.server"],
+      "cwd": "/path/to/pgsafe-mcp",
+      "env": {
+        "DATABASE_URL": "sqlite:///data/nexus.db"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ MCP Tools Exposed to AI Agents
+
+| Tool | Parameters | Description |
+|---|---|---|
+| `list_tables` | *(none)* | Returns list of all user tables in the database |
+| `describe_table` | `table_name` | Returns column names, data types, nullability, and primary keys |
+| `safe_query` | `query`, `limit` | Executes strictly read-only SQL with forced LIMIT enforcement |
+| `analyze_query` | `query` | Inspects SQL for unindexed table scan and Cartesian join risks |
+
+---
+
+## 💎 Need Enterprise Data Protection? Upgrade to PgSafe Pro
+
+Running against live production workloads with sensitive customer data?
+
+| Feature | Lite (Open Source) | Enterprise Suite ($19) |
+|---|:---:|:---:|
+| **Read-Only SQL Validation** | ✅ | ✅ |
+| **Forced LIMIT Injection** | ✅ | ✅ |
+| **PostgreSQL & SQLite** | ✅ | ✅ |
+| **MySQL, MariaDB & ClickHouse** | ❌ | ✅ |
+| **Automatic PII Redaction & Masking** *(Emails, Cards, Hashes)* | ❌ | ✅ |
+| **Dry-Run Mutation Simulation** *(Auto-Rollback Test Harness)* | ❌ | ✅ |
+| **Index Recommendation Advisor** | ❌ | ✅ |
+| **Production Docker & Compose** | ❌ | ✅ |
+| **Full Pytest Suite & Architecture Guide** | ❌ | ✅ |
+
+👉 **[Get the Genesis Enterprise Suite ($19)](https://johanld.gumroad.com/l/genesis-enterprise-suite)**
+
+---
+
+## 📄 License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Genesis MCP Ecosystem
+
+| Module | What it does | Repo |
+|---|---|---|
+| **CrawlEngine MCP** | Anti-bot web scraping, clean Markdown, proxy rotation and TLS evasion | [GitHub](https://github.com/johannschiffer/crawlengine-mcp) |
+| **BrowserBridge MCP** | Deterministic headless browser automation with cryptographic action receipts | [GitHub](https://github.com/johannschiffer/browserbridge-mcp) |
+| **PgSafe MCP** (this repo) | Zero-trust PostgreSQL/SQLite guard, live PII masking, zero-downtime migration checks | [GitHub](https://github.com/johannschiffer/pgsafe-mcp) |
+| **OmniBridge MCP** | Multi-channel notification and webhook bus with a persistent SQLite WAL queue | [GitHub](https://github.com/johannschiffer/omnibridge-mcp) |
+| **SysFlow MCP** | Safe Linux administration plane: systemd, port audit, isolated execution | [GitHub](https://github.com/johannschiffer/sysflow-mcp) |
+| **FastMCP Forge** | Production MCP server scaffolder: stdio, SSE and auth middleware | [GitHub](https://github.com/johannschiffer/fastmcp-forge) |
+
+[Live config builder](https://johannschiffer.github.io) | [Starter Kit, free](https://johanld.gumroad.com/l/genesis-starter-kit) | [Enterprise Suite, $19](https://johanld.gumroad.com/l/genesis-enterprise-suite)

pgsafe_mcp-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pgsafe/__init__.py,sha256=Q_NyArbT8zp__Hm_aBbcd_35D0ieobWvOQmr1lGEVPc,194
+pgsafe/_genesis.py,sha256=kPHV2Lr__lgG6R1e623tIVnuV8xu_mpuLddMCIuMEMM,398
+pgsafe/cli.py,sha256=2HNm8_Dfv-IjerToqEAt72ZiJJ_P9B-SotX7K5QbvuU,2456
+pgsafe/server.py,sha256=I4oS2j637xvfC8cVlR9laJSv4N6IIcBfnUAe7elmw7A,9320
+pgsafe/adapters/base.py,sha256=gOaFoukdhh802fLGZT2HSF3f4cTp_JKPeoTjg12sv-g,752
+pgsafe/adapters/postgres_adapter.py,sha256=Jc2PFznZh0zKWyOOFGTZyNnRcSVTBEoAvs3IhKqhpR8,2647
+pgsafe/adapters/sqlite_adapter.py,sha256=DbsuiWvtjxPaK0itDdo3ZdvL8JJbgxn6uE84oKY4E30,2104
+pgsafe/guards/cost_analyzer.py,sha256=W9NO0y3GqCliYx93ZeAn-EYvlWxcTey-5xce5h-qQVk,1526
+pgsafe/guards/readonly.py,sha256=oh_XlpXJQU6JHOXxUHsOkGMdxEU07JE0Uf4K_vhmoBM,1972
+pgsafe_mcp-1.0.0.dist-info/licenses/LICENSE,sha256=zLLbcUl3FzNRmjK-IvqP0a4PoChg0sjBic0oWv_gBIE,1080
+pgsafe_mcp-1.0.0.dist-info/METADATA,sha256=bqA036o3w_W6eIiG_Phg4jlEg-9OKY57QO8zIFkG52M,7440
+pgsafe_mcp-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pgsafe_mcp-1.0.0.dist-info/entry_points.txt,sha256=9nAz_qrU4TXf4Fj6TnCaaVy1GnZdUq8HE7YMrUPf8Qo,79
+pgsafe_mcp-1.0.0.dist-info/top_level.txt,sha256=PCARi_rb1jjS_uO898jnATj0e72zQc8M5hsrGKv6_VU,7
+pgsafe_mcp-1.0.0.dist-info/RECORD,,

pgsafe_mcp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pgsafe_mcp-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pgsafe-cli = pgsafe.cli:main
+pgsafe-mcp = pgsafe.server:main

pgsafe_mcp-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johann Schiffer / NEXUS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pgsafe_mcp-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pgsafe