connectpak-core 0.1.0__py3-none-any.whl

connectpak/core/__init__.py

@@ -0,0 +1,30 @@
+"""Core BaseConnector, read-only guard, and MCP server runner."""
+
+from connectpak.core.base import (
+    BaseConnector,
+    Column,
+    ForeignKey,
+    Index,
+    QueryResult,
+    TableSchema,
+)
+from connectpak.core.guard import (
+    WriteOperationError,
+    assert_no_write_keywords,
+    assert_read_only,
+)
+from connectpak.core.server import build_server, serve
+
+__all__ = [
+    "BaseConnector",
+    "Column",
+    "ForeignKey",
+    "Index",
+    "QueryResult",
+    "TableSchema",
+    "WriteOperationError",
+    "assert_no_write_keywords",
+    "assert_read_only",
+    "build_server",
+    "serve",
+]

connectpak/core/base.py

@@ -0,0 +1,90 @@
+"""BaseConnector contract and shared dataclasses."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Column:
+    name: str
+    type: str
+    nullable: bool
+    default: str | None = None
+    is_primary_key: bool = False
+    comment: str | None = None
+
+
+@dataclass
+class ForeignKey:
+    columns: list[str]
+    referenced_schema: str | None
+    referenced_table: str
+    referenced_columns: list[str]
+    name: str | None = None
+
+
+@dataclass
+class Index:
+    name: str
+    columns: list[str]
+    unique: bool = False
+
+
+@dataclass
+class TableSchema:
+    schema: str | None
+    name: str
+    columns: list[Column]
+    primary_key: list[str] = field(default_factory=list)
+    foreign_keys: list[ForeignKey] = field(default_factory=list)
+    indexes: list[Index] = field(default_factory=list)
+    comment: str | None = None
+
+
+@dataclass
+class QueryResult:
+    columns: list[str]
+    rows: list[list[Any]]
+    row_count: int
+    truncated: bool = False
+    elapsed_ms: float | None = None
+
+
+class BaseConnector(ABC):
+    """Abstract base class every engine connector implements.
+
+    Subclasses MUST keep the safety contract intact:
+    parser guard + engine-level read-only + statement timeout + row cap.
+    """
+
+    name: str = "base"
+    dialect: str | None = None
+    allow_write: bool = False
+    statement_timeout_ms: int = 30_000
+    default_max_rows: int = 1000
+
+    @abstractmethod
+    def list_schemas(self) -> list[str]: ...
+
+    @abstractmethod
+    def list_tables(self, schema: str | None = None) -> list[tuple[str | None, str]]: ...
+
+    @abstractmethod
+    def describe_table(self, name: str, schema: str | None = None) -> TableSchema: ...
+
+    @abstractmethod
+    def sample_table(
+        self, name: str, schema: str | None = None, limit: int = 10
+    ) -> QueryResult: ...
+
+    @abstractmethod
+    def query(self, sql: str, max_rows: int | None = None) -> QueryResult: ...
+
+    @abstractmethod
+    def explain(self, sql: str) -> str: ...
+
+    @abstractmethod
+    def close(self) -> None: ...

connectpak/core/guard.py

@@ -0,0 +1,150 @@
+"""Read-only query guards.
+
+Blocks state-mutating statements before they reach the engine. This is the
+first of two layers — the engine-level read-only mode is the second. Both
+must remain intact.
+"""
+
+from __future__ import annotations
+
+import re
+
+import sqlglot
+from sqlglot import exp
+
+
+class WriteOperationError(ValueError):
+    """Raised when a query contains any state-mutating operation."""
+
+
+_ALLOWED_TOP_LEVEL: tuple[type[exp.Expression], ...] = (
+    exp.Select,
+    exp.Union,
+    exp.Intersect,
+    exp.Except,
+    exp.Subquery,
+    exp.With,
+    exp.Describe,
+    exp.Show,
+    exp.Pragma,
+)
+
+_FORBIDDEN: tuple[type[exp.Expression], ...] = (
+    exp.Insert,
+    exp.Update,
+    exp.Delete,
+    exp.Merge,
+    exp.Create,
+    exp.Drop,
+    exp.Alter,
+    exp.TruncateTable,
+    exp.Command,
+    # `SELECT ... INTO new_table` creates a table (T-SQL / Postgres): a write
+    # hiding inside an otherwise-allowed Select. exp.Into also covers the
+    # nested-subquery form because we walk the whole tree.
+    exp.Into,
+    # `SELECT ... FOR UPDATE` / `FOR SHARE` acquires row locks — write intent,
+    # and it can block other transactions. Not read-only.
+    exp.Lock,
+)
+
+# SQLite table-valued informational pragmas. sqlglot's sqlite dialect parses
+# both `PRAGMA table_info(users)` and the mutating `PRAGMA journal_mode=WAL`
+# as an EQ node, so we cannot tell an argument-taking read pragma from a
+# setter structurally. These names are always reads regardless of form; any
+# other pragma carrying an assignment (`name = value`) is treated as a setter
+# and rejected.
+_READ_PRAGMAS: frozenset[str] = frozenset(
+    {
+        "table_info",
+        "table_xinfo",
+        "table_list",
+        "index_info",
+        "index_xinfo",
+        "index_list",
+        "foreign_key_list",
+        "foreign_key_check",
+        "collation_list",
+        "database_list",
+        "function_list",
+        "module_list",
+        "pragma_list",
+        "compile_options",
+        "integrity_check",
+        "quick_check",
+        "freelist_count",
+        "page_count",
+        "data_version",
+    }
+)
+
+
+def _reject_mutating_pragma(pragma: exp.Pragma) -> None:
+    """Reject a PRAGMA that assigns a value (a setter), allow read forms.
+
+    Read forms are: a bare name (`PRAGMA user_version`) or a table-valued
+    informational pragma (`PRAGMA table_info(users)`). A setter such as
+    `PRAGMA journal_mode = WAL` or `PRAGMA user_version = 5` mutates and is
+    rejected.
+    """
+    inner = pragma.this
+    if not isinstance(inner, exp.EQ):
+        return  # bare name → read form
+    name_node = inner.this
+    name = (name_node.name if hasattr(name_node, "name") else str(name_node)).lower()
+    if name not in _READ_PRAGMAS:
+        raise WriteOperationError(f"mutating PRAGMA is not read-only: {name}")
+
+
+def assert_read_only(sql: str, dialect: str | None = None) -> None:
+    """Raise WriteOperationError if the SQL would change state.
+
+    - Empty / whitespace-only SQL is rejected.
+    - Each parsed top-level statement must be one of the allowed read shapes.
+    - The full AST is walked; any forbidden node anywhere triggers a reject.
+      This catches "WITH x AS (DELETE ...) SELECT ..." style attacks, as well
+      as `SELECT ... INTO`, `FOR UPDATE` locks, and mutating PRAGMA setters.
+    """
+    if sql is None or not sql.strip():
+        raise WriteOperationError("empty SQL")
+
+    try:
+        parsed = sqlglot.parse(sql, dialect=dialect)
+    except Exception as e:
+        raise WriteOperationError(f"could not parse SQL: {e}") from e
+
+    if not parsed:
+        raise WriteOperationError("empty SQL")
+
+    for stmt in parsed:
+        if stmt is None:
+            raise WriteOperationError("empty statement")
+
+        if not isinstance(stmt, _ALLOWED_TOP_LEVEL):
+            raise WriteOperationError(
+                f"top-level statement {type(stmt).__name__} is not read-only"
+            )
+
+        if isinstance(stmt, exp.Pragma):
+            _reject_mutating_pragma(stmt)
+
+        for node in stmt.walk():
+            target = node[0] if isinstance(node, tuple) else node
+            if isinstance(target, _FORBIDDEN):
+                raise WriteOperationError(
+                    f"forbidden operation found in SQL: {type(target).__name__}"
+                )
+
+
+def assert_no_write_keywords(text: str, keywords: tuple[str, ...]) -> None:
+    """Lightweight write-keyword check for query languages outside SQL.
+
+    Less robust than `assert_read_only`'s full AST walk: a keyword inside a
+    string literal can produce a false positive. Used for Cypher / CQL /
+    AQL / Gremlin where sqlglot does not provide a parser.
+    """
+    if text is None or not text.strip():
+        raise WriteOperationError("empty query")
+    for kw in keywords:
+        if re.search(rf"\b{re.escape(kw)}\b", text, re.IGNORECASE):
+            raise WriteOperationError(f"forbidden keyword in query: {kw}")

connectpak/core/server.py

@@ -0,0 +1,92 @@
+"""MCP server runner.
+
+Wraps a BaseConnector instance in a FastMCP server exposing six tools.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from typing import Any
+
+from connectpak.core.base import BaseConnector
+
+
+def _to_jsonable(obj: Any) -> Any:
+    if is_dataclass(obj) and not isinstance(obj, type):
+        return asdict(obj)
+    if isinstance(obj, list):
+        return [_to_jsonable(x) for x in obj]
+    if isinstance(obj, tuple):
+        return [_to_jsonable(x) for x in obj]
+    if isinstance(obj, dict):
+        return {k: _to_jsonable(v) for k, v in obj.items()}
+    return obj
+
+
+def default_instructions(connector: BaseConnector) -> str:
+    """Server instructions telling the client which engine is behind the tools."""
+    language = (
+        f"SQL in the {connector.dialect} dialect"
+        if connector.dialect
+        else "the engine's native query format (see its connector docs)"
+    )
+    return (
+        f"connectpak {connector.name} connector. The `query` tool takes {language}. "
+        "This connection is read-only: writes are rejected by a parser guard and by "
+        "the engine's own read-only mode, and every query has a timeout and a row cap."
+    )
+
+
+def build_server(
+    connector: BaseConnector,
+    server_name: str | None = None,
+    instructions: str | None = None,
+):
+    """Build a FastMCP server registering six tools wrapping the connector."""
+    from mcp.server.fastmcp import FastMCP
+
+    name = server_name or f"connectpak-{connector.name}"
+    mcp = FastMCP(name, instructions=instructions or default_instructions(connector))
+
+    @mcp.tool()
+    def list_schemas() -> list[str]:
+        """List schemas / namespaces visible to the connector."""
+        return connector.list_schemas()
+
+    @mcp.tool()
+    def list_tables(schema: str | None = None) -> list[dict[str, Any]]:
+        """List tables (and views) in the given schema, or all schemas if omitted."""
+        return [{"schema": s, "name": n} for s, n in connector.list_tables(schema=schema)]
+
+    @mcp.tool()
+    def describe_table(name: str, schema: str | None = None) -> dict[str, Any]:
+        """Return columns, primary key, foreign keys, and indexes for a table."""
+        return _to_jsonable(connector.describe_table(name=name, schema=schema))
+
+    @mcp.tool()
+    def sample_table(
+        name: str, schema: str | None = None, limit: int = 10
+    ) -> dict[str, Any]:
+        """Sample up to `limit` rows from the given table."""
+        return _to_jsonable(connector.sample_table(name=name, schema=schema, limit=limit))
+
+    @mcp.tool()
+    def query(sql: str, max_rows: int | None = None) -> dict[str, Any]:
+        """Run a read-only SQL query. Mutating statements are rejected."""
+        return _to_jsonable(connector.query(sql=sql, max_rows=max_rows))
+
+    @mcp.tool()
+    def explain(sql: str) -> str:
+        """Return the engine's EXPLAIN output for the given query."""
+        return connector.explain(sql=sql)
+
+    return mcp
+
+
+def serve(connector: BaseConnector) -> None:
+    """Build and run the MCP server, closing the connector on shutdown."""
+    mcp = build_server(connector)
+    try:
+        mcp.run()
+    finally:
+        connector.close()

connectpak_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.5
+Name: connectpak-core
+Version: 0.1.0
+Summary: Core BaseConnector, read-only SQL guard, and MCP server runner for connectpak.
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.0
+Requires-Dist: sqlglot>=23.0
+Description-Content-Type: text/markdown
+
+# connectpak-core
+
+Core building blocks shared by every connectpak engine package:
+
+- `BaseConnector` — abstract base class defining the connector contract.
+- `assert_read_only` — sqlglot-based parser guard that blocks any
+  state-mutating SQL before it ever reaches the engine.
+- `build_server` / `serve` — turns a connector into a Model Context Protocol
+  (MCP) server with six tools wrapping the connector methods.
+
+You normally do not depend on this package directly — install one of the
+engine packages (e.g. `connectpak-sql-postgres`) and it will pull `core` in
+transitively.

connectpak_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+connectpak/core/__init__.py,sha256=bwIoekzRtBZaCVP9dKKcEkJJf2r7X-hrt-O8IsUek5M,601
+connectpak/core/base.py,sha256=QcK4vKyhW8eUYukRdFX-xg7fSxQcx7BrC4y5JZIjFZ8,2113
+connectpak/core/guard.py,sha256=1bpOGwPvj7oSxYa6ViskWmvUAkxZ16X-sJTESpc_Lr8,4912
+connectpak/core/server.py,sha256=QRFRLAIR-FojC04-nbcdykwr-8kRMngxKefMsZiFwK8,3221
+connectpak_core-0.1.0.dist-info/METADATA,sha256=Nr2gCLfh-7V2fjsrPbpoMTpXMMGz2fqnN1GA0RLKQHM,871
+connectpak_core-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+connectpak_core-0.1.0.dist-info/RECORD,,

connectpak_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any