connectpak 0.1.0__py3-none-any.whl

connectpak/launcher/__init__.py

@@ -0,0 +1,94 @@
+"""One `connectpak` command for every engine.
+
+Give it a connection string and it picks the engine from it, then hands off
+to that engine's own CLI (`connectpak-sql-postgres`, ...), so the read-only
+guard, timeout, and row cap are exactly the engine's.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from urllib.parse import urlsplit
+
+from connectpak.launcher.engines import BY_KEY, ENGINES, SQLITE_SUFFIXES, Engine
+
+CONNECTION_VAR = "CONNECTPAK_CONNECTION"
+ENGINE_VAR = "CONNECTPAK_ENGINE"
+
+
+class LaunchError(ValueError):
+    """The connection or engine setting can't be resolved to one engine."""
+
+
+def detect_engine(connection: str) -> Engine | None:
+    """Return the engine a connection string unambiguously names, else None."""
+    value = connection.strip()
+    scheme = urlsplit(value).scheme.lower() if "://" in value else ""
+    if scheme:
+        for engine in ENGINES:
+            if scheme in engine.schemes:
+                return engine
+        if scheme in ("ws", "wss") and ".neptune.amazonaws.com" in value.lower():
+            return BY_KEY["neptune"]
+        return None
+    if value.lower().endswith(SQLITE_SUFFIXES) or value == ":memory:":
+        return BY_KEY["sqlite"]
+    return None
+
+
+def resolve(
+    connection: str | None, engine_key: str | None, environ: dict[str, str]
+) -> tuple[Engine, str]:
+    """Pick the engine and the connection value to hand to its CLI."""
+    engine_key = (engine_key or "").strip().lower()
+    connection = (connection or "").strip()
+
+    if engine_key and engine_key not in BY_KEY:
+        raise LaunchError(
+            f"unknown engine {engine_key!r}. Choose one of: {', '.join(BY_KEY)}"
+        )
+
+    if not connection:
+        # No unified setting: fall back to an engine-specific variable, so
+        # existing CONNECTPAK_<ENGINE>_* setups keep working.
+        candidates = [BY_KEY[engine_key]] if engine_key else list(ENGINES)
+        found = [e for e in candidates if environ.get(e.env_var, "").strip()]
+        if len(found) == 1:
+            return found[0], environ[found[0].env_var].strip()
+        if len(found) > 1:
+            names = ", ".join(f"${e.env_var}" for e in found)
+            raise LaunchError(
+                f"several engine variables are set ({names}). "
+                f"Set ${ENGINE_VAR} to choose one."
+            )
+        raise LaunchError(
+            f"no connection configured. Set ${CONNECTION_VAR} (and ${ENGINE_VAR} "
+            "if the engine can't be read from it)."
+        )
+
+    engine = BY_KEY[engine_key] if engine_key else detect_engine(connection)
+    if engine is None:
+        raise LaunchError(
+            "can't tell which database this connection is for. Set "
+            f"${ENGINE_VAR} to one of: {', '.join(BY_KEY)}"
+        )
+    if engine.key == "sqlite" and connection.lower().startswith("sqlite://"):
+        # SQLAlchemy form: sqlite:///rel.db -> rel.db, sqlite:////abs.db -> /abs.db
+        connection = connection.split("://", 1)[1]
+        if connection.startswith("/"):
+            connection = connection[1:]
+    return engine, connection
+
+
+def run(engine: Engine, connection: str, argv: list[str]) -> int:
+    """Hand off to the engine's CLI with its connection env var set."""
+    import sys
+
+    os.environ[engine.env_var] = connection
+    module = importlib.import_module(engine.module)
+    sys.argv = [engine.cli, *argv]
+    return module.main()
+
+
+__all__ = ["CONNECTION_VAR", "ENGINE_VAR", "LaunchError", "detect_engine", "resolve", "run"]

connectpak/launcher/__main__.py

@@ -0,0 +1,44 @@
+"""CLI entry point: `connectpak` — one command for every engine."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from connectpak.launcher import CONNECTION_VAR, ENGINE_VAR, LaunchError, resolve, run
+from connectpak.launcher.engines import ENGINES
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="connectpak",
+        description="Serve any connectpak engine over MCP, read-only. The engine is "
+                    "read from the connection string, or set with --engine.",
+        epilog="Other options (--max-rows, --statement-timeout-ms, ...) are passed "
+               "through to the engine's own CLI.",
+    )
+    parser.add_argument("--connection", default=os.environ.get(CONNECTION_VAR),
+                        help=f"Connection string (default: ${CONNECTION_VAR}).")
+    parser.add_argument("--engine", default=os.environ.get(ENGINE_VAR),
+                        help=f"Engine to use if it can't be detected (default: ${ENGINE_VAR}).")
+    parser.add_argument("--list-engines", action="store_true",
+                        help="Print the supported engines and exit.")
+    args, passthrough = parser.parse_known_args()
+
+    if args.list_engines:
+        for e in ENGINES:
+            print(f"{e.key:<14} {e.display:<16} e.g. {e.example}")
+        return 0
+
+    try:
+        engine, connection = resolve(args.connection, args.engine, dict(os.environ))
+    except LaunchError as exc:
+        print(f"connectpak: error: {exc}", file=sys.stderr)
+        return 2
+    print(f"connectpak: serving {engine.display} (read-only)", file=sys.stderr)
+    return run(engine, connection, passthrough)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

connectpak/launcher/engines.py

@@ -0,0 +1,115 @@
+"""Registry of every connectpak engine.
+
+This is the single source of truth for the `connectpak` launcher (which
+engine handles a connection string) and for `scripts/gen_plugins.py`
+(what the plugin documents and forwards). It must stay stdlib-only so the
+generator can load it without installing anything.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+AWS_ENV = (
+    "AWS_PROFILE",
+    "AWS_REGION",
+    "AWS_DEFAULT_REGION",
+    "AWS_ACCESS_KEY_ID",
+    "AWS_SECRET_ACCESS_KEY",
+    "AWS_SESSION_TOKEN",
+    "AWS_CONFIG_FILE",
+    "AWS_SHARED_CREDENTIALS_FILE",
+)
+GCP_ENV = ("GOOGLE_APPLICATION_CREDENTIALS", "GOOGLE_CLOUD_PROJECT", "CLOUDSDK_CONFIG")
+
+
+@dataclass(frozen=True)
+class Engine:
+    key: str  # what users type for CONNECTPAK_ENGINE, e.g. "postgres"
+    package: str  # directory under packages/, e.g. "sql-postgres"
+    display: str
+    family: str  # "sql" | "document" | "graph" | "vector"
+    env_var: str  # the engine CLI's connection env var
+    example: str
+    # URL schemes that identify this engine unambiguously.
+    schemes: tuple[str, ...] = ()
+    # Cloud credential env vars the engine's SDK reads (forwarded by Codex).
+    passthrough_env: tuple[str, ...] = field(default=())
+
+    @property
+    def cli(self) -> str:
+        return f"connectpak-{self.package}"
+
+    @property
+    def module(self) -> str:
+        track, name = self.package.split("-", 1)
+        return f"connectpak.{track}.{name}.__main__"
+
+
+ENGINES: tuple[Engine, ...] = (
+    # SQL
+    Engine("postgres", "sql-postgres", "Postgres", "sql", "CONNECTPAK_POSTGRES_DSN",
+           "postgresql://reader:pw@db.example.com:5432/app", ("postgresql", "postgres")),
+    Engine("sqlite", "sql-sqlite", "SQLite", "sql", "CONNECTPAK_SQLITE_PATH",
+           "/Users/me/data/analytics.sqlite", ("sqlite",)),
+    Engine("mysql", "sql-mysql", "MySQL", "sql", "CONNECTPAK_MYSQL_DSN",
+           "mysql://reader:pw@db.example.com:3306/app", ("mysql", "mariadb")),
+    Engine("clickhouse", "sql-clickhouse", "ClickHouse", "sql", "CONNECTPAK_CLICKHOUSE_DSN",
+           "clickhouse://reader:pw@localhost:8123/default", ("clickhouse",)),
+    Engine("sqlserver", "sql-sqlserver", "SQL Server", "sql", "CONNECTPAK_SQLSERVER_DSN",
+           "mssql://reader:pw@db.example.com:1433/app", ("mssql", "sqlserver")),
+    Engine("oracle", "sql-oracle", "Oracle", "sql", "CONNECTPAK_ORACLE_DSN",
+           "reader/pw@db.example.com:1521/ORCLPDB1"),
+    Engine("bigquery", "sql-bigquery", "BigQuery", "sql", "CONNECTPAK_BIGQUERY_PROJECT",
+           "my-gcp-project", passthrough_env=GCP_ENV),
+    Engine("snowflake", "sql-snowflake", "Snowflake", "sql", "CONNECTPAK_SNOWFLAKE_DSN",
+           "snowflake://user:pw@account/db/schema?warehouse=WH&role=READONLY", ("snowflake",)),
+    Engine("redshift", "sql-redshift", "Redshift", "sql", "CONNECTPAK_REDSHIFT_DSN",
+           "redshift://user:pw@host:5439/db", ("redshift",)),
+    Engine("databricks", "sql-databricks", "Databricks", "sql", "CONNECTPAK_DATABRICKS_DSN",
+           "databricks://token:dapi-xxxxx@host.cloud.databricks.com?http_path=/sql/1.0/...",
+           ("databricks",)),
+    # Document / key-value / search
+    Engine("mongodb", "nosql-mongodb", "MongoDB", "document", "CONNECTPAK_MONGODB_URI",
+           "mongodb://user:pw@host:27017/dbname", ("mongodb", "mongodb+srv")),
+    Engine("dynamodb", "nosql-dynamodb", "DynamoDB", "document", "CONNECTPAK_DYNAMODB_REGION",
+           "us-east-1", passthrough_env=AWS_ENV),
+    Engine("elasticsearch", "nosql-elasticsearch", "Elasticsearch", "document",
+           "CONNECTPAK_ELASTICSEARCH_URL", "http://elastic:pw@localhost:9200"),
+    Engine("cassandra", "nosql-cassandra", "Cassandra", "document",
+           "CONNECTPAK_CASSANDRA_HOSTS", "user:pw@127.0.0.1:9042"),
+    # Graph
+    Engine("neo4j", "graph-neo4j", "Neo4j", "graph", "CONNECTPAK_NEO4J_URI",
+           "neo4j+s://neo4j:pw@cluster.example.com",
+           ("neo4j", "neo4j+s", "neo4j+ssc", "bolt", "bolt+s", "bolt+ssc")),
+    Engine("memgraph", "graph-memgraph", "Memgraph", "graph", "CONNECTPAK_MEMGRAPH_URI",
+           "bolt://user:pw@localhost:7687"),
+    Engine("arangodb", "graph-arangodb", "ArangoDB", "graph", "CONNECTPAK_ARANGODB_URL",
+           "http://root:pw@localhost:8529/_system"),
+    Engine("neptune", "graph-neptune", "Amazon Neptune", "graph", "CONNECTPAK_NEPTUNE_URL",
+           "wss://my-cluster.cluster-xxxx.us-east-1.neptune.amazonaws.com:8182/gremlin"),
+    # Vector
+    Engine("pgvector", "vector-pgvector", "pgvector", "vector", "CONNECTPAK_PGVECTOR_DSN",
+           "postgresql://reader:pw@db.example.com:5432/app"),
+    Engine("pinecone", "vector-pinecone", "Pinecone", "vector", "CONNECTPAK_PINECONE_API_KEY",
+           "pcsk_xxxxx"),
+    Engine("weaviate", "vector-weaviate", "Weaviate", "vector", "CONNECTPAK_WEAVIATE_URL",
+           "https://my-cluster.weaviate.network"),
+    Engine("qdrant", "vector-qdrant", "Qdrant", "vector", "CONNECTPAK_QDRANT_URL",
+           "https://api-key@my-cluster.qdrant.io"),
+    Engine("chroma", "vector-chroma", "Chroma", "vector", "CONNECTPAK_CHROMA_URL",
+           "http://localhost:8000"),
+    Engine("milvus", "vector-milvus", "Milvus", "vector", "CONNECTPAK_MILVUS_URI",
+           "http://localhost:19530"),
+)
+
+BY_KEY: dict[str, Engine] = {e.key: e for e in ENGINES}
+
+FAMILIES: dict[str, str] = {
+    "sql": "SQL databases and warehouses",
+    "document": "document, key-value, and search stores",
+    "graph": "graph databases",
+    "vector": "vector databases",
+}
+
+SQLITE_SUFFIXES = (".db", ".sqlite", ".sqlite3", ".db3")

connectpak-0.1.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: connectpak
+Version: 0.1.0
+Summary: Read-only MCP database connectors for LLMs: one command for 24 engines (SQL, NoSQL, graph, vector).
+Project-URL: Homepage, https://github.com/arunvenkatadri/connectpak
+Project-URL: Repository, https://github.com/arunvenkatadri/connectpak
+License: MIT
+Keywords: claude-code,codex,database,llm,mcp,read-only
+Requires-Python: >=3.11
+Requires-Dist: connectpak-core==0.1.0
+Requires-Dist: connectpak-graph-arangodb==0.1.0
+Requires-Dist: connectpak-graph-memgraph==0.1.0
+Requires-Dist: connectpak-graph-neo4j==0.1.0
+Requires-Dist: connectpak-graph-neptune==0.1.0
+Requires-Dist: connectpak-nosql-cassandra==0.1.0
+Requires-Dist: connectpak-nosql-dynamodb==0.1.0
+Requires-Dist: connectpak-nosql-elasticsearch==0.1.0
+Requires-Dist: connectpak-nosql-mongodb==0.1.0
+Requires-Dist: connectpak-sql-bigquery==0.1.0
+Requires-Dist: connectpak-sql-clickhouse==0.1.0
+Requires-Dist: connectpak-sql-databricks==0.1.0
+Requires-Dist: connectpak-sql-mysql==0.1.0
+Requires-Dist: connectpak-sql-oracle==0.1.0
+Requires-Dist: connectpak-sql-postgres==0.1.0
+Requires-Dist: connectpak-sql-redshift==0.1.0
+Requires-Dist: connectpak-sql-snowflake==0.1.0
+Requires-Dist: connectpak-sql-sqlite==0.1.0
+Requires-Dist: connectpak-sql-sqlserver==0.1.0
+Requires-Dist: connectpak-vector-chroma==0.1.0
+Requires-Dist: connectpak-vector-milvus==0.1.0
+Requires-Dist: connectpak-vector-pgvector==0.1.0
+Requires-Dist: connectpak-vector-pinecone==0.1.0
+Requires-Dist: connectpak-vector-qdrant==0.1.0
+Requires-Dist: connectpak-vector-weaviate==0.1.0
+Description-Content-Type: text/markdown
+
+# connectpak
+
+One command that serves any of connectpak's 24 read-only database connectors
+over MCP. It installs every engine package and picks the engine from the
+connection string.
+
+```bash
+CONNECTPAK_CONNECTION="postgresql://reader:pw@localhost:5432/app" uvx connectpak
+CONNECTPAK_ENGINE=bigquery CONNECTPAK_CONNECTION=my-gcp-project uvx connectpak
+uvx connectpak --list-engines
+```
+
+Engines detected from the connection string: Postgres, MySQL/MariaDB,
+ClickHouse, SQL Server, Snowflake, Redshift, Databricks, MongoDB, Neo4j,
+SQLite (a `.db`/`.sqlite` path, or a SQLAlchemy-style `sqlite:///relative.db` / `sqlite:////absolute.db` URL), and Neptune. For the others
+(Oracle, BigQuery, DynamoDB, Elasticsearch, Cassandra, Memgraph, ArangoDB,
+pgvector, Pinecone, Weaviate, Qdrant, Chroma, Milvus), set
+`CONNECTPAK_ENGINE`. If `CONNECTPAK_CONNECTION` isn't set, the engine's own
+variable (such as `CONNECTPAK_POSTGRES_DSN`) is used.
+
+To install only one engine, use its own package instead, such as
+`connectpak-sql-postgres`. See the
+[main README](https://github.com/arunvenkatadri/connectpak) for the safety
+model and query formats.

connectpak-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+connectpak/launcher/__init__.py,sha256=GLp_8hqZr4HH0qM6eN_bP23ERzIHq4zDGnV6MorpxoA,3505
+connectpak/launcher/__main__.py,sha256=0JjA9hHwe0b2_YUVk8_f51POeDtG4dqXLBSbqN1vM0w,1710
+connectpak/launcher/engines.py,sha256=5m36-yJhuXnf5WOU2ZGav5fdsITeCNQoHMeBnNNCCxM,5592
+connectpak-0.1.0.dist-info/METADATA,sha256=uNpQWr4Po5Acz5JLsi6GN6rXiE-wuIqAatRUGmwAqn8,2738
+connectpak-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+connectpak-0.1.0.dist-info/entry_points.txt,sha256=XuwhvK6cTdRMaGNyTQWi_oveFSVjx1VZ1GaDxsSEF08,65
+connectpak-0.1.0.dist-info/RECORD,,

connectpak-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

connectpak-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+connectpak = connectpak.launcher.__main__:main