sql-query-mcp 0.2.0__tar.gz → 0.3.0__tar.gz

{sql_query_mcp-0.2.0/sql_query_mcp.egg-info → sql_query_mcp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-query-mcp
-Version: 0.2.0
+Version: 0.3.0
 Summary: Read-only SQL MCP server for PostgreSQL and MySQL.
 Author: Andy Wang
 License-Expression: MIT
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://github.com/andyWang1688/sql-query-mcp
 Project-URL: Repository, https://github.com/andyWang1688/sql-query-mcp
 Project-URL: Documentation, https://github.com/andyWang1688/sql-query-mcp/blob/main/README.md
 Project-URL: Issues, https://github.com/andyWang1688/sql-query-mcp/issues
-Keywords: mcp,mcp-server,sql,database,postgresql,mysql,cli,codex,chatgpt
+Keywords: mcp,mcp-server,sql,database,postgresql,mysql,hive,cli,codex,chatgpt
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10
@@ -22,6 +22,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mcp>=1.12.4
 Requires-Dist: openpyxl>=3.1
+Requires-Dist: PyHive[hive_pure_sasl]>=0.7
 Requires-Dist: PyMySQL>=1.1
 Requires-Dist: psycopg[binary]>=3.2
 Requires-Dist: psycopg-pool>=3.2
@@ -44,6 +45,7 @@ clear boundaries.
 | --- | --- | --- |
 | PostgreSQL | Supported | Available today |
 | MySQL | Supported | Available today |
+| Hive | Supported | Available today |
 | SQLite | Candidate | Not supported yet |
 | SQL Server | Candidate | Not supported yet |
 | ClickHouse | Candidate | Not supported yet |
@@ -60,33 +62,39 @@ without exposing raw connection strings or flattening engine-specific concepts.
 ## What AI can do with it
 
 The current tool set focuses on database discovery, controlled query workflows,
-and one narrow local file import path. You can use it to help an AI assistant
-understand structure before it generates SQL or imports a prepared CSV/XLSX file
-into an existing table.
-
-MySQL supports `explain_query`, but not `explain_query(..., analyze=True)` in
-the current implementation.
-
-| Tool | PostgreSQL | MySQL | Purpose |
-| --- | --- | --- | --- |
-| `list_connections()` | Yes | Yes | List configured connections |
-| `list_schemas(connection_id)` | Yes | No | List visible PostgreSQL schemas |
-| `list_databases(connection_id)` | No | Yes | List visible MySQL databases |
-| `list_tables(connection_id, schema?, database?)` | Yes | Yes | List tables and views |
-| `describe_table(connection_id, table_name, schema?, database?)` | Yes | Yes | Inspect columns, keys, and indexes |
-| `run_select(connection_id, sql, limit?)` | Yes | Yes | Run read-only queries |
-| `explain_query(connection_id, sql, analyze?)` | Yes | Yes | Inspect query plans |
-| `get_table_sample(connection_id, table_name, schema?, database?, limit?)` | Yes | Yes | Fetch small table samples |
-| `import_table_file(connection_id, table_name, file_path, schema?, database?, sheet_name?)` | Yes | Yes | Import local CSV/XLSX files |
+asynchronous read-only queries, and one narrow local file import path. You can
+use it to help an AI assistant understand structure before it generates SQL,
+runs a bounded query, starts a long-running read-only query, or imports a
+prepared CSV/XLSX file into an existing table.
+
+MySQL and Hive support `explain_query`. Hive uses `EXPLAIN` and
+`EXPLAIN ANALYZE` for `explain_query`.
+
+| Tool | PostgreSQL | MySQL | Hive | Purpose |
+| --- | --- | --- | --- | --- |
+| `list_connections()` | Yes | Yes | Yes | List configured connections |
+| `list_schemas(connection_id)` | Yes | No | No | List visible PostgreSQL schemas |
+| `list_databases(connection_id)` | No | Yes | Yes | List visible MySQL or Hive databases |
+| `list_tables(connection_id, schema?, database?)` | Yes | Yes | Yes | List tables and views |
+| `describe_table(connection_id, table_name, schema?, database?)` | Yes | Yes | Yes | Inspect columns, keys, and indexes |
+| `run_select(connection_id, sql, limit?)` | Yes | Yes | Yes | Run short bounded read-only queries |
+| `start_query(connection_id, sql, limit?)` | Yes | Yes | Yes | Start long-running read-only queries |
+| `get_query(query_id, offset?, limit?)` | Yes | Yes | Yes | Fetch async query status and paginated results |
+| `cancel_query(query_id)` | Yes | Yes | Yes | Cancel running async queries |
+| `explain_query(connection_id, sql, analyze?)` | Yes | Yes | Yes | Inspect query plans |
+| `get_table_sample(connection_id, table_name, schema?, database?, limit?)` | Yes | Yes | Yes | Fetch small table samples |
+| `import_table_file(connection_id, table_name, file_path, schema?, database?, sheet_name?)` | Yes | Yes | Yes | Import local CSV/XLSX files |
 
 These tools are useful for tasks such as listing namespaces, inspecting table
-definitions, reviewing indexes, sampling records, analyzing read-only queries
-with `EXPLAIN`, and importing prepared local files. For full request and
-response details, see `docs/api-reference.md` (Chinese).
+definitions, reviewing indexes, sampling records, running short read-only
+queries with `run_select`, running long read-only queries with `start_query`,
+`get_query`, and `cancel_query`, analyzing read-only queries with `EXPLAIN`, and
+importing prepared local files. For full request and response details, see
+`docs/api-reference.md` (Chinese).
 
 ## How boundaries are constrained
 
-The product boundary is intentionally narrow today. Only PostgreSQL and MySQL
+The product boundary is intentionally narrow today. PostgreSQL, MySQL, and Hive
 are available today. Query tools remain read-only, and the only write path is a
 controlled local CSV/XLSX import into existing tables.
 
@@ -94,19 +102,25 @@ The service keeps those boundaries explicit in a few ways.
 
 - Connections declare `engine` explicitly, so the server never guesses from
   `connection_id`.
-- PostgreSQL uses `schema`, and MySQL uses `database`, without collapsing both
-  into one vague namespace field.
+- PostgreSQL uses `schema`, while MySQL and Hive use `database`, without
+  collapsing both into one vague namespace field.
 - Real DSNs stay in environment variables, while config files store only the
   environment variable names.
 - Query execution passes through `sqlglot` validation before reaching the
-  database.
+  database. Use `run_select` for short bounded read-only queries, and use
+  `start_query`, `get_query`, and `cancel_query` for long-running read-only
+  queries.
 - The server accepts only `SELECT` and `WITH ... SELECT`, rejects comments and
   multi-statement input, and records audit logs for each call.
 - `import_table_file` doesn't accept raw SQL. It inserts only file columns whose
   headers exactly match existing table columns.
+- Hive `import_table_file` is intended for small files only and rejects files
+  with more than 1000 data rows. Hive imports write rows one by one, so they
+  can be slow and can hit your MCP client's tool timeout. For bulk Hive loads,
+  use Hive-native `LOAD DATA`, external tables, or your existing data ingestion
+  pipeline.
 
-For MySQL, `explain_query(..., analyze=True)` is not available in the current
-implementation.
+For Hive, `explain_query` uses `EXPLAIN` and `EXPLAIN ANALYZE`.
 
 ## Quick start
 
@@ -197,11 +211,28 @@ The example config looks like this.
       "dsn_env": "MYSQL_CONN_CRM_PROD_MAIN_RO",
       "enabled": true,
       "default_database": "crm"
+    },
+    {
+      "connection_id": "warehouse_hive_prod_main_ro",
+      "engine": "hive",
+      "label": "Warehouse Hive production / Main / read-only",
+      "env": "prod",
+      "tenant": "main",
+      "role": "ro",
+      "dsn_env": "HIVE_CONN_WAREHOUSE_PROD_MAIN_RO",
+      "enabled": true,
+      "default_database": "default"
     }
   ]
 }
 ```
 
+Set DSNs in the MCP client environment. For Hive, use a Hive DSN such as:
+
+```bash
+export HIVE_CONN_WAREHOUSE_PROD_MAIN_RO='hive://user:password@hive.example.com:10000/default?auth=CUSTOM'
+```
+
 ## Documentation
 
 If you want implementation details, setup guidance, or internal structure, use
@@ -234,7 +265,7 @@ The main entry point is `sql_query_mcp/app.py`. Core modules include:
 - `sql_query_mcp/validator.py`: read-only SQL validation
 - `sql_query_mcp/introspection.py`: metadata inspection
 - `sql_query_mcp/executor.py`: query execution and limits
-- `sql_query_mcp/adapters/`: PostgreSQL and MySQL adapters
+- `sql_query_mcp/adapters/`: PostgreSQL, MySQL, and Hive adapters
 
 ## Contributing
 

{sql_query_mcp-0.2.0 → sql_query_mcp-0.3.0}/README.md

@@ -13,6 +13,7 @@ clear boundaries.
 | --- | --- | --- |
 | PostgreSQL | Supported | Available today |
 | MySQL | Supported | Available today |
+| Hive | Supported | Available today |
 | SQLite | Candidate | Not supported yet |
 | SQL Server | Candidate | Not supported yet |
 | ClickHouse | Candidate | Not supported yet |
@@ -29,33 +30,39 @@ without exposing raw connection strings or flattening engine-specific concepts.
 ## What AI can do with it
 
 The current tool set focuses on database discovery, controlled query workflows,
-and one narrow local file import path. You can use it to help an AI assistant
-understand structure before it generates SQL or imports a prepared CSV/XLSX file
-into an existing table.
-
-MySQL supports `explain_query`, but not `explain_query(..., analyze=True)` in
-the current implementation.
-
-| Tool | PostgreSQL | MySQL | Purpose |
-| --- | --- | --- | --- |
-| `list_connections()` | Yes | Yes | List configured connections |
-| `list_schemas(connection_id)` | Yes | No | List visible PostgreSQL schemas |
-| `list_databases(connection_id)` | No | Yes | List visible MySQL databases |
-| `list_tables(connection_id, schema?, database?)` | Yes | Yes | List tables and views |
-| `describe_table(connection_id, table_name, schema?, database?)` | Yes | Yes | Inspect columns, keys, and indexes |
-| `run_select(connection_id, sql, limit?)` | Yes | Yes | Run read-only queries |
-| `explain_query(connection_id, sql, analyze?)` | Yes | Yes | Inspect query plans |
-| `get_table_sample(connection_id, table_name, schema?, database?, limit?)` | Yes | Yes | Fetch small table samples |
-| `import_table_file(connection_id, table_name, file_path, schema?, database?, sheet_name?)` | Yes | Yes | Import local CSV/XLSX files |
+asynchronous read-only queries, and one narrow local file import path. You can
+use it to help an AI assistant understand structure before it generates SQL,
+runs a bounded query, starts a long-running read-only query, or imports a
+prepared CSV/XLSX file into an existing table.
+
+MySQL and Hive support `explain_query`. Hive uses `EXPLAIN` and
+`EXPLAIN ANALYZE` for `explain_query`.
+
+| Tool | PostgreSQL | MySQL | Hive | Purpose |
+| --- | --- | --- | --- | --- |
+| `list_connections()` | Yes | Yes | Yes | List configured connections |
+| `list_schemas(connection_id)` | Yes | No | No | List visible PostgreSQL schemas |
+| `list_databases(connection_id)` | No | Yes | Yes | List visible MySQL or Hive databases |
+| `list_tables(connection_id, schema?, database?)` | Yes | Yes | Yes | List tables and views |
+| `describe_table(connection_id, table_name, schema?, database?)` | Yes | Yes | Yes | Inspect columns, keys, and indexes |
+| `run_select(connection_id, sql, limit?)` | Yes | Yes | Yes | Run short bounded read-only queries |
+| `start_query(connection_id, sql, limit?)` | Yes | Yes | Yes | Start long-running read-only queries |
+| `get_query(query_id, offset?, limit?)` | Yes | Yes | Yes | Fetch async query status and paginated results |
+| `cancel_query(query_id)` | Yes | Yes | Yes | Cancel running async queries |
+| `explain_query(connection_id, sql, analyze?)` | Yes | Yes | Yes | Inspect query plans |
+| `get_table_sample(connection_id, table_name, schema?, database?, limit?)` | Yes | Yes | Yes | Fetch small table samples |
+| `import_table_file(connection_id, table_name, file_path, schema?, database?, sheet_name?)` | Yes | Yes | Yes | Import local CSV/XLSX files |
 
 These tools are useful for tasks such as listing namespaces, inspecting table
-definitions, reviewing indexes, sampling records, analyzing read-only queries
-with `EXPLAIN`, and importing prepared local files. For full request and
-response details, see `docs/api-reference.md` (Chinese).
+definitions, reviewing indexes, sampling records, running short read-only
+queries with `run_select`, running long read-only queries with `start_query`,
+`get_query`, and `cancel_query`, analyzing read-only queries with `EXPLAIN`, and
+importing prepared local files. For full request and response details, see
+`docs/api-reference.md` (Chinese).
 
 ## How boundaries are constrained
 
-The product boundary is intentionally narrow today. Only PostgreSQL and MySQL
+The product boundary is intentionally narrow today. PostgreSQL, MySQL, and Hive
 are available today. Query tools remain read-only, and the only write path is a
 controlled local CSV/XLSX import into existing tables.
 
@@ -63,19 +70,25 @@ The service keeps those boundaries explicit in a few ways.
 
 - Connections declare `engine` explicitly, so the server never guesses from
   `connection_id`.
-- PostgreSQL uses `schema`, and MySQL uses `database`, without collapsing both
-  into one vague namespace field.
+- PostgreSQL uses `schema`, while MySQL and Hive use `database`, without
+  collapsing both into one vague namespace field.
 - Real DSNs stay in environment variables, while config files store only the
   environment variable names.
 - Query execution passes through `sqlglot` validation before reaching the
-  database.
+  database. Use `run_select` for short bounded read-only queries, and use
+  `start_query`, `get_query`, and `cancel_query` for long-running read-only
+  queries.
 - The server accepts only `SELECT` and `WITH ... SELECT`, rejects comments and
   multi-statement input, and records audit logs for each call.
 - `import_table_file` doesn't accept raw SQL. It inserts only file columns whose
   headers exactly match existing table columns.
+- Hive `import_table_file` is intended for small files only and rejects files
+  with more than 1000 data rows. Hive imports write rows one by one, so they
+  can be slow and can hit your MCP client's tool timeout. For bulk Hive loads,
+  use Hive-native `LOAD DATA`, external tables, or your existing data ingestion
+  pipeline.
 
-For MySQL, `explain_query(..., analyze=True)` is not available in the current
-implementation.
+For Hive, `explain_query` uses `EXPLAIN` and `EXPLAIN ANALYZE`.
 
 ## Quick start
 
@@ -166,11 +179,28 @@ The example config looks like this.
       "dsn_env": "MYSQL_CONN_CRM_PROD_MAIN_RO",
       "enabled": true,
       "default_database": "crm"
+    },
+    {
+      "connection_id": "warehouse_hive_prod_main_ro",
+      "engine": "hive",
+      "label": "Warehouse Hive production / Main / read-only",
+      "env": "prod",
+      "tenant": "main",
+      "role": "ro",
+      "dsn_env": "HIVE_CONN_WAREHOUSE_PROD_MAIN_RO",
+      "enabled": true,
+      "default_database": "default"
     }
   ]
 }
 ```
 
+Set DSNs in the MCP client environment. For Hive, use a Hive DSN such as:
+
+```bash
+export HIVE_CONN_WAREHOUSE_PROD_MAIN_RO='hive://user:password@hive.example.com:10000/default?auth=CUSTOM'
+```
+
 ## Documentation
 
 If you want implementation details, setup guidance, or internal structure, use
@@ -203,7 +233,7 @@ The main entry point is `sql_query_mcp/app.py`. Core modules include:
 - `sql_query_mcp/validator.py`: read-only SQL validation
 - `sql_query_mcp/introspection.py`: metadata inspection
 - `sql_query_mcp/executor.py`: query execution and limits
-- `sql_query_mcp/adapters/`: PostgreSQL and MySQL adapters
+- `sql_query_mcp/adapters/`: PostgreSQL, MySQL, and Hive adapters
 
 ## Contributing
 

{sql_query_mcp-0.2.0 → sql_query_mcp-0.3.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sql-query-mcp"
-version = "0.2.0"
+version = "0.3.0"
 description = "Read-only SQL MCP server for PostgreSQL and MySQL."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "Andy Wang" }]
-keywords = ["mcp", "mcp-server", "sql", "database", "postgresql", "mysql", "cli", "codex", "chatgpt"]
+keywords = ["mcp", "mcp-server", "sql", "database", "postgresql", "mysql", "hive", "cli", "codex", "chatgpt"]
 classifiers = [
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
@@ -25,6 +25,7 @@ classifiers = [
 dependencies = [
   "mcp>=1.12.4",
   "openpyxl>=3.1",
+  "PyHive[hive_pure_sasl]>=0.7",
   "PyMySQL>=1.1",
   "psycopg[binary]>=3.2",
   "psycopg-pool>=3.2",

sql_query_mcp-0.3.0/sql_query_mcp/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Database adapters."""
+
+from .hive import HiveAdapter
+from .mysql import MySQLAdapter
+from .postgres import PostgresAdapter
+
+__all__ = ["HiveAdapter", "MySQLAdapter", "PostgresAdapter"]

sql_query_mcp-0.3.0/sql_query_mcp/adapters/hive.py

@@ -0,0 +1,147 @@
+"""Hive adapter."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Iterator, List
+from urllib.parse import parse_qs, unquote, urlparse
+
+try:
+    from pyhive import hive
+except ImportError:  # pragma: no cover - runtime dependency
+    hive = None
+
+from ..errors import ConfigurationError
+
+
+class HiveAdapter:
+    engine = "hive"
+
+    @contextmanager
+    def connection(self, connection_id: str, dsn: str) -> Iterator[object]:
+        if hive is None:
+            raise ConfigurationError("缺少 PyHive 依赖，请先安装项目依赖。")
+
+        conn = hive.Connection(**self._parse_dsn(dsn))
+        try:
+            yield conn
+        finally:
+            conn.close()
+
+    def close(self) -> None:
+        return None
+
+    def set_statement_timeout(self, conn: object, timeout_ms: int) -> None:
+        return None
+
+    def build_sample_query(self, database: str, table_name: str, sentinel_limit: int) -> str:
+        return f"SELECT * FROM {self._qualified_table(database, table_name)} LIMIT {int(sentinel_limit)}"
+
+    def build_insert_query(self, database: str, table_name: str, columns: List[str]) -> str:
+        quoted_columns = ", ".join(self._quote_identifier(column) for column in columns)
+        placeholders = ", ".join(["%s"] * len(columns))
+        return f"INSERT INTO {self._qualified_table(database, table_name)} ({quoted_columns}) VALUES ({placeholders})"
+
+    def build_explain_query(self, sql_text: str, analyze: bool = False) -> str:
+        prefix = "EXPLAIN ANALYZE" if analyze else "EXPLAIN"
+        return f"{prefix} {sql_text}"
+
+    def extract_plan(self, rows):
+        return [self._first_value(row) for row in rows]
+
+    def column_names(self, description) -> List[str]:
+        return [column[0] for column in (description or [])]
+
+    def normalize_rows(self, rows, columns: List[str]) -> List[dict]:
+        return [dict(zip(columns, row)) for row in rows]
+
+    def list_databases(self, conn: object) -> List[str]:
+        with conn.cursor() as cur:
+            cur.execute("SHOW DATABASES")
+            return [self._first_value(row) for row in cur.fetchall()]
+
+    def list_tables(self, conn: object, database: str):
+        with conn.cursor() as cur:
+            cur.execute(f"SHOW TABLES IN {self._quote_identifier(database)}")
+            return [
+                {
+                    "database_name": database,
+                    "table_name": self._first_value(row),
+                    "table_type": None,
+                }
+                for row in cur.fetchall()
+            ]
+
+    def describe_table(self, conn: object, database: str, table_name: str):
+        with conn.cursor() as cur:
+            cur.execute(f"DESCRIBE {self._qualified_table(database, table_name)}")
+            rows = cur.fetchall()
+
+        columns = []
+        in_partitions = False
+        for row in rows:
+            name = self._first_value(row)
+            if not name:
+                continue
+            if str(name).startswith("# Partition Information"):
+                in_partitions = True
+                continue
+            if str(name).startswith("#"):
+                continue
+            values = self._row_values(row)
+            data_type = values[1] if len(values) > 1 else None
+            comment = values[2] if len(values) > 2 else None
+            columns.append(
+                {
+                    "column_name": name,
+                    "data_type": data_type,
+                    "udt_name": None,
+                    "nullable": True,
+                    "default": None,
+                    "primary_key": False,
+                    "extra": comment,
+                    "partition_key": in_partitions,
+                }
+            )
+
+        if not columns:
+            return None
+        return {"columns": columns, "indexes": []}
+
+    def _parse_dsn(self, dsn: str) -> dict:
+        parsed = urlparse(dsn)
+        if parsed.scheme not in {"hive", "hive+pyhive"}:
+            raise ConfigurationError(f"Hive DSN 必须使用 hive:// 或 hive+pyhive://，当前为 {parsed.scheme}")
+
+        supported_query_keys = {"auth", "kerberos_service_name", "password"}
+        query_params = {key: values[-1] for key, values in parse_qs(parsed.query).items()}
+        unsupported = sorted(set(query_params) - supported_query_keys)
+        if unsupported:
+            raise ConfigurationError(f"Hive DSN 包含暂不支持的参数: {unsupported}")
+
+        connect_args = {
+            "host": parsed.hostname or "localhost",
+            "port": parsed.port or 10000,
+            "username": unquote(parsed.username) if parsed.username else None,
+            "password": unquote(parsed.password) if parsed.password else query_params.get("password"),
+            "database": parsed.path.lstrip("/") or None,
+            "auth": query_params.get("auth"),
+            "kerberos_service_name": query_params.get("kerberos_service_name"),
+        }
+        return {key: value for key, value in connect_args.items() if value is not None}
+
+    def _quote_identifier(self, value: str) -> str:
+        return "`" + value.replace("`", "``") + "`"
+
+    def _qualified_table(self, database: str, table_name: str) -> str:
+        return f"{self._quote_identifier(database)}.{self._quote_identifier(table_name)}"
+
+    def _first_value(self, row):
+        if isinstance(row, dict):
+            return next(iter(row.values()))
+        return row[0]
+
+    def _row_values(self, row):
+        if isinstance(row, dict):
+            return list(row.values())
+        return list(row)

{sql_query_mcp-0.2.0 → sql_query_mcp-0.3.0}/sql_query_mcp/app.py

@@ -6,6 +6,7 @@ from typing import Optional
 
 from mcp.server.fastmcp import FastMCP
 
+from .async_queries import AsyncQueryService
 from .audit import AuditLogger
 from .config import load_config
 from .errors import SqlQueryMCPError
@@ -22,6 +23,7 @@ def create_app() -> FastMCP:
     metadata = MetadataService(registry, app_config.settings, audit_logger)
     executor = QueryExecutor(registry, app_config.settings, audit_logger)
     importer = TableFileImporter(registry, app_config.settings, audit_logger)
+    async_queries = AsyncQueryService(registry, app_config.settings, audit_logger)
 
     mcp = FastMCP("sql-query-mcp", json_response=True)
 
@@ -39,7 +41,7 @@ def create_app() -> FastMCP:
 
     @mcp.tool()
     def list_databases(connection_id: str) -> dict:
-        """List visible databases for a MySQL connection."""
+        """List visible databases for a MySQL or Hive connection."""
 
         return _run_tool(lambda: metadata.list_databases(connection_id))
 
@@ -49,7 +51,7 @@ def create_app() -> FastMCP:
         schema: Optional[str] = None,
         database: Optional[str] = None,
     ) -> dict:
-        """List tables and views for a resolved PostgreSQL schema or MySQL database."""
+        """List tables and views for a resolved schema or database."""
 
         return _run_tool(lambda: metadata.list_tables(connection_id, schema, database))
 
@@ -88,6 +90,24 @@ def create_app() -> FastMCP:
 
         return _run_tool(lambda: executor.get_table_sample(connection_id, table_name, schema, database, limit))
 
+    @mcp.tool()
+    def start_query(connection_id: str, sql: str, limit: Optional[int] = None) -> dict:
+        """Start an asynchronous read-only SELECT or CTE query."""
+
+        return _run_tool(lambda: async_queries.start_query(connection_id, sql, limit))
+
+    @mcp.tool()
+    def get_query(query_id: str, offset: int = 0, limit: Optional[int] = None) -> dict:
+        """Get asynchronous query status and paginated results when complete."""
+
+        return _run_tool(lambda: async_queries.get_query(query_id, offset, limit))
+
+    @mcp.tool()
+    def cancel_query(query_id: str) -> dict:
+        """Cancel a running asynchronous query."""
+
+        return _run_tool(lambda: async_queries.cancel_query(query_id))
+
     @mcp.tool()
     def import_table_file(
         connection_id: str,