duckquery-mcp 0.1.0__tar.gz

duckquery_mcp-0.1.0/.gitignore

@@ -0,0 +1,206 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+!frontend/src/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+!api/duckquery.spec
+
+# PyInstaller build artifacts
+api/dist/
+api/build/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/
+.hypothesis/
+
+# Generated lint reports (do not commit)
+pylint-report.json
+api/pylint-report.json
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.idea/
+.vscode/
+
+# Node.js
+node_modules/
+dist/
+.DS_Store
+
+# Temp files
+*.tmp
+*.swp
+
+# Project specific files - 敏感信息和数据文件
+# Sensitive information and data files
+api/mysql_configs.json
+api/postgresql_configs.json
+api/mysql_datasources.json
+api/temp_files/*
+!api/temp_files/.gitkeep
+api/core/temp_files/*
+!api/core/temp_files/.gitkeep
+api/exports/*
+!api/exports/.gitkeep
+api/host_documents/
+api/host_downloads/
+api/server_mounts/
+exports/*
+!exports/.gitkeep
+temp_files/*
+!temp_files/.gitkeep
+config/mysql-configs.json
+config/postgresql-configs.json
+config/mysql-production.json
+config/datasources.json
+/data/
+!/data/uploads/.gitkeep
+!/data/duckdb/.gitkeep
+api/data/
+
+# DuckDB相关文件
+.duckdb/
+*.db
+*.duckdb
+
+# 清理报告文件
+cleanup-report.txt
+
+# 真实配置文件（只保留.example文件）
+# Real configuration files (keep only .example files)
+**/mysql-configs.json
+**/datasources.json
+**/app-config.json
+**/file-datasources.json
+**/sql-favorites.json
+**/secret.key
+!**/*.example
+
+# Frontend build outputs
+frontend/dist/
+frontend/build/
+
+# Additional Node.js ignores
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.npm
+.eslintcache
+
+# OS specific
+Thumbs.db
+ehthumbs.db
+.Spotlight-V100
+.Trashes
+
+# Local clipboard and temporary files
+.gemini-clipboard/
+
+# Backend writes a per-deployment runtime descriptor here
+# (Docker sets APP_ROOT=/app -> ./api/runtime.json). Generated, not source.
+api/runtime.json
+
+# Logs
+logs/
+*.log
+
+# Database files
+*.db
+*.sqlite
+*.sqlite3
+
+# Backup files
+*.bak
+*.backup
+
+# Cursor IDE files
+.cursorrules
+.cursor/
+.claude/
+# Git hook scripts at repo root only (do not ignore frontend/src/hooks)
+/hooks/
+CLAUDE.md
+# runtime file data sources cache
+data/file_datasources.json
+
+# 本地运行时数据库/扩展(联邦扩展二进制、DuckDB 数据与 WAL)，不入库
+data-test/
+*.duckdb_extension
+*.db.wal
+*.db.wal.broken.*
+
+# DuckDB 离线扩展预下载产物(由 fetch_duckdb_extensions.py 生成)
+api/extensions/
+# Tauri sidecar(打包时由 CI 暂存的 PyInstaller onedir,勿入库)
+frontend/src-tauri/binaries/

duckquery_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: duckquery-mcp
+Version: 0.1.0
+Summary: MCP server for a locally-running DuckQuery backend
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'

duckquery_mcp-0.1.0/README.md

@@ -0,0 +1,44 @@
+# duckquery-mcp
+
+An MCP server that exposes a locally-running DuckQuery backend to MCP clients
+(Claude Code, Cursor, Codex). Start DuckQuery first (desktop app, Docker, or
+`uvicorn main:app --port 48001`); this server auto-discovers it.
+
+## Run
+
+```bash
+uvx duckquery-mcp            # zero-install
+# or: pipx run duckquery-mcp
+```
+
+Env:
+- `DUCKQUERY_API_BASE` — explicit backend URL (e.g. `http://127.0.0.1:48001`). Optional; auto-discovered otherwise (runtime.json, then probes 48001/8000/8001).
+- `DUCKQUERY_MCP_MODE` — `read-only` | `normal` (default) | `full`.
+
+## Add to a CLI
+
+Claude Code:
+```bash
+claude mcp add duckquery -- uvx duckquery-mcp
+```
+
+Cursor / Codex (`mcp.json`):
+```json
+{
+  "mcpServers": {
+    "duckquery": {
+      "command": "uvx",
+      "args": ["duckquery-mcp"],
+      "env": { "DUCKQUERY_MCP_MODE": "normal" }
+    }
+  }
+}
+```
+
+## Tools
+
+High-level tools (query, ask, discover, add sources, configure LLM, transform,
+export) plus a generic `duckquery_request` passthrough. Safety mode gates which
+tools are exposed: `read-only` hides all mutating tools; `normal` exposes them
+but destructive raw SQL and non-GET passthrough require `confirm=true`; `full`
+removes the gate.

duckquery_mcp-0.1.0/duckquery_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

duckquery_mcp-0.1.0/duckquery_mcp/__main__.py

@@ -0,0 +1,7 @@
+def main() -> None:
+    from duckquery_mcp.server import run
+    run()
+
+
+if __name__ == "__main__":
+    main()

duckquery_mcp-0.1.0/duckquery_mcp/client.py

@@ -0,0 +1,94 @@
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+
+class BackendNotFound(Exception):
+    pass
+
+
+class BackendError(Exception):
+    pass
+
+
+def runtime_file() -> Path:
+    """Mirror api/core/common/paths.get_user_data_dir() / 'runtime.json'."""
+    override = os.getenv("APP_ROOT")
+    if override:
+        return Path(override) / "runtime.json"
+    home = Path(os.path.expanduser("~"))
+    if sys.platform == "darwin":
+        base = home / "Library" / "Application Support" / "DuckQuery"
+    elif sys.platform.startswith("win"):
+        base = Path(os.getenv("APPDATA") or home) / "DuckQuery"
+    else:
+        base = home / ".local" / "share" / "DuckQuery"
+    return base / "runtime.json"
+
+
+class DuckQueryClient:
+    def __init__(self, cfg) -> None:
+        self.cfg = cfg
+        self._base: str | None = None
+        self._http = httpx.AsyncClient(timeout=cfg.timeout)
+
+    async def _healthy(self, base: str) -> bool:
+        try:
+            r = await self._http.get(f"{base}/health")
+            return r.status_code == 200 and r.json().get("status") == "healthy"
+        except Exception:
+            return False
+
+    async def base(self) -> str:
+        if self._base and await self._healthy(self._base):
+            return self._base
+        # 1. explicit env
+        if self.cfg.api_base and await self._healthy(self.cfg.api_base):
+            self._base = self.cfg.api_base
+            return self._base
+        # 2. runtime.json
+        rf = runtime_file()
+        if rf.exists():
+            try:
+                b = json.loads(rf.read_text()).get("base")
+                if b and await self._healthy(b):
+                    self._base = b
+                    return self._base
+            except Exception:
+                pass
+        # 3. probe known ports
+        for port in self.cfg.probe_ports:
+            b = f"http://127.0.0.1:{port}"
+            if await self._healthy(b):
+                self._base = b
+                return self._base
+        raise BackendNotFound(
+            "DuckQuery backend not found — start the DuckQuery app "
+            "or set DUCKQUERY_API_BASE."
+        )
+
+    async def call(self, method: str, path: str, *, json_body: Any = None,
+                   params: dict | None = None) -> Any:
+        base = await self.base()
+        r = await self._http.request(method, f"{base}{path}", json=json_body, params=params)
+        try:
+            payload = r.json()
+        except Exception:
+            r.raise_for_status()
+            return {"raw": r.text}
+        if r.status_code >= 400:
+            msg = None
+            if isinstance(payload, dict):
+                # FastAPI uses "detail"; DuckQuery's envelope uses "message"/"messageCode"
+                msg = payload.get("detail") or payload.get("message") or payload.get("messageCode")
+            raise BackendError(str(msg) if msg else f"HTTP {r.status_code}")
+        if isinstance(payload, dict):
+            if payload.get("success") is False:
+                raise BackendError(payload.get("message") or payload.get("messageCode") or "request failed")
+            if "data" in payload:
+                return payload["data"]
+        return payload

duckquery_mcp-0.1.0/duckquery_mcp/config.py

@@ -0,0 +1,26 @@
+import os
+from dataclasses import dataclass
+
+MODES = ("read-only", "normal", "full")
+
+
+@dataclass(frozen=True)
+class Config:
+    api_base: str | None
+    mode: str
+    timeout: float
+    row_cap: int
+    probe_ports: tuple[int, ...]
+
+
+def load_config() -> Config:
+    mode = os.getenv("DUCKQUERY_MCP_MODE", "normal")
+    if mode not in MODES:
+        raise SystemExit(f"DUCKQUERY_MCP_MODE must be one of {MODES}, got {mode!r}")
+    return Config(
+        api_base=os.getenv("DUCKQUERY_API_BASE") or None,
+        mode=mode,
+        timeout=float(os.getenv("DUCKQUERY_MCP_TIMEOUT", "120")),
+        row_cap=int(os.getenv("DUCKQUERY_MCP_ROW_CAP", "200")),
+        probe_ports=(48001, 8000, 8001),
+    )

duckquery_mcp-0.1.0/duckquery_mcp/safety.py

@@ -0,0 +1,17 @@
+import re
+
+_READ = re.compile(r"^\s*(SELECT|WITH|EXPLAIN|PRAGMA|DESCRIBE|SHOW)\b", re.I)
+
+
+def is_write_sql(sql: str) -> bool:
+    """True unless the statement is clearly read-only."""
+    return _READ.match(sql or "") is None
+
+
+def tool_allowed(tier: str, mode: str) -> bool:
+    """tier: 'read' | 'write'. mode: 'read-only' | 'normal' | 'full'."""
+    if mode == "full":
+        return True
+    if mode == "normal":
+        return True
+    return tier == "read"  # read-only

duckquery_mcp-0.1.0/duckquery_mcp/server.py

@@ -0,0 +1,17 @@
+from mcp.server.fastmcp import FastMCP
+
+from duckquery_mcp.client import DuckQueryClient
+from duckquery_mcp.config import load_config
+from duckquery_mcp.tools import register_all
+
+
+def build() -> FastMCP:
+    cfg = load_config()
+    client = DuckQueryClient(cfg)
+    mcp = FastMCP("duckquery")
+    register_all(mcp, client, cfg)
+    return mcp
+
+
+def run() -> None:
+    build().run()  # stdio transport by default

duckquery_mcp-0.1.0/duckquery_mcp/tools/__init__.py

@@ -0,0 +1,57 @@
+import inspect
+
+from mcp.server.fastmcp import FastMCP
+
+from duckquery_mcp.client import BackendError, BackendNotFound, DuckQueryClient
+from duckquery_mcp.config import Config
+from duckquery_mcp.safety import tool_allowed
+from duckquery_mcp.tools import ai_settings, discover, export, passthrough, query, sources, transform
+
+
+def register_all(mcp: FastMCP, client: DuckQueryClient, cfg: Config) -> None:
+    def add(tier: str):
+        """Register tool (only if its tier is allowed by mode), binding client/cfg and
+        preserving the user-facing parameter signature for the MCP schema."""
+        def deco(fn):
+            if not tool_allowed(tier, cfg.mode):
+                return fn
+            sig = inspect.signature(fn)
+            user_params = [p for n, p in sig.parameters.items() if n not in ("client", "cfg")]
+
+            async def wrapped(**kwargs):
+                try:
+                    return await fn(client, cfg, **kwargs)
+                except (BackendNotFound, BackendError) as exc:
+                    return {"error": str(exc)}
+
+            wrapped.__name__ = fn.__name__
+            wrapped.__doc__ = fn.__doc__
+            wrapped.__signature__ = sig.replace(parameters=user_params)
+            mcp.tool()(wrapped)
+            return fn
+        return deco
+
+    add("read")(discover.list_tables)
+    add("read")(discover.describe_table)
+    add("read")(discover.list_connections)
+    add("read")(discover.list_db_objects)
+    add("read")(query.run_sql)
+    add("read")(query.federated_query)
+    add("read")(query.ask)
+    add("read")(query.explain_sql)
+    add("read")(query.suggest_chart)
+    add("read")(query.chat)
+    add("read")(query.error_fix)
+    add("write")(sources.add_connection)
+    add("write")(sources.add_local_file_source)
+    add("write")(sources.import_excel)
+    add("write")(sources.paste_data)
+    add("write")(sources.read_url)
+    add("write")(transform.save_as_table)
+    add("write")(transform.pivot)
+    add("write")(transform.set_operations)
+    add("read")(ai_settings.get_ai_settings)
+    add("write")(ai_settings.configure_llm)
+    add("write")(ai_settings.test_llm_provider)
+    add("read")(export.export_results)
+    add("read")(passthrough.duckquery_request)

duckquery_mcp-0.1.0/duckquery_mcp/tools/ai_settings.py

@@ -0,0 +1,18 @@
+from typing import Any
+
+
+async def get_ai_settings(client, cfg) -> Any:
+    """Current AI/LLM settings (api keys are masked by the backend)."""
+    return await client.call("GET", "/api/settings/ai")
+
+
+async def configure_llm(client, cfg, *, settings: dict) -> Any:
+    """Update AI/LLM settings. `settings` matches AISettingsPayload fields:
+    enabled (bool), default_provider (str|None), providers (list[dict]),
+    features (dict), timeout_seconds (int), num_retries (int)."""
+    return await client.call("PUT", "/api/settings/ai", json_body=settings)
+
+
+async def test_llm_provider(client, cfg, *, provider_id: str) -> Any:
+    """Test connectivity/credentials for one configured provider."""
+    return await client.call("POST", f"/api/ai/providers/{provider_id}/test")

duckquery_mcp-0.1.0/duckquery_mcp/tools/discover.py

@@ -0,0 +1,49 @@
+from typing import Any
+
+from duckquery_mcp.util import normalize_connection_id
+
+
+async def list_tables(client, cfg) -> Any:
+    """List DuckDB tables currently loaded in the local engine."""
+    return await client.call("GET", "/api/duckdb/tables")
+
+
+async def describe_table(client, cfg, *, name: str) -> Any:
+    """Columns/types/sample for one DuckDB table."""
+    return await client.call("GET", f"/api/duckdb/tables/detail/{name}")
+
+
+async def list_connections(client, cfg) -> Any:
+    """List saved external database connections (MySQL/Postgres)."""
+    return await client.call("GET", "/api/datasources/databases/list")
+
+
+async def list_db_objects(client, cfg, *, connection_id: str, kind: str = "tables") -> Any:
+    """List schemas or tables in an external connection. kind: 'schemas' | 'tables'.
+
+    The connection_id from list_connections (e.g. 'db_SORDER') is accepted; its 'db_'
+    prefix is normalized. For 'tables', returns COMPACT entries (table name + comment +
+    column_count) capped at 200 — a big schema's full column lists would be huge. To get
+    one table's columns, run `federated_query("SELECT * FROM alias.<table> LIMIT 0", ...)`.
+    """
+    cid = normalize_connection_id(connection_id)
+    data = await client.call("GET", f"/api/datasources/databases/{cid}/{kind}")
+    tables = data.get("tables") if isinstance(data, dict) else None
+    if isinstance(tables, list):
+        cap = 200
+        compact = [
+            {
+                "table_name": t.get("table_name"),
+                "comment": t.get("table_comment"),
+                "column_count": len(t.get("columns") or []),
+            }
+            for t in tables[:cap]
+        ]
+        return {
+            "connection_id": data.get("connection_id"),
+            "database": data.get("database"),
+            "table_count": len(tables),
+            "truncated": len(tables) > cap,
+            "tables": compact,
+        }
+    return data

duckquery_mcp-0.1.0/duckquery_mcp/tools/export.py

@@ -0,0 +1,11 @@
+from typing import Any
+
+
+async def export_results(client, cfg, *, sql: str, format: str = "parquet",
+                         attach_databases: list | None = None) -> Any:
+    """Export a query result to a file; returns file_id, download_url, format, row_count_estimate.
+    format: 'parquet' (default) or 'csv'. Only SELECT queries are allowed."""
+    body: dict = {"sql": sql, "format": format}
+    if attach_databases is not None:
+        body["attach_databases"] = attach_databases
+    return await client.call("POST", "/api/query-results/export", json_body=body)

duckquery_mcp-0.1.0/duckquery_mcp/tools/passthrough.py

@@ -0,0 +1,11 @@
+from typing import Any
+
+
+async def duckquery_request(client, cfg, *, method: str, path: str,
+                            json: dict | None = None, confirm: bool = False) -> Any:
+    """Call any DuckQuery API endpoint directly (escape hatch for features without a dedicated tool).
+    Non-GET methods require confirm=True unless mode is 'full'."""
+    method = method.upper()
+    if method != "GET" and cfg.mode != "full" and not confirm:
+        return {"error": "This is a mutating request; pass confirm=true to proceed."}
+    return await client.call(method, path, json_body=json)

duckquery_mcp-0.1.0/duckquery_mcp/tools/query.py

@@ -0,0 +1,95 @@
+from typing import Any
+
+from duckquery_mcp.client import DuckQueryClient
+from duckquery_mcp.config import Config
+
+
+def _truncate(data: dict, cfg: Config) -> dict:
+    """Compact a /execute-style result; cap rows at cfg.row_cap."""
+    rows = data.get("data") or []
+    capped = rows[: cfg.row_cap]
+    return {
+        "columns": data.get("columns"),
+        "rows": capped,
+        "row_count": data.get("row_count", len(rows)),
+        "truncated": len(rows) > len(capped),
+    }
+
+
+async def run_sql(client: DuckQueryClient, cfg: Config, *, sql: str, preview: bool = True) -> Any:
+    """Run DuckDB SQL against local tables. Returns columns + (capped) rows."""
+    from duckquery_mcp.safety import is_write_sql
+    if cfg.mode == "read-only" and is_write_sql(sql):
+        return {"error": "read-only mode: only SELECT / WITH / EXPLAIN are allowed."}
+    data = await client.call("POST", "/api/duckdb/execute",
+                             json_body={"sql": sql, "is_preview": preview})
+    return _truncate(data, cfg)
+
+
+async def federated_query(client: DuckQueryClient, cfg: Config, *, sql: str, attach_databases: list) -> Any:
+    """Run SQL across attached external DBs (MySQL/Postgres) + local tables.
+
+    attach_databases: [{"alias": "m", "connection_id": "SORDER"}]. Connection ids from
+    list_connections (e.g. "db_SORDER") are accepted — the "db_" prefix is normalized.
+    Reference an attached table as alias.table, e.g. SELECT * FROM m.orders LIMIT 100.
+    """
+    from duckquery_mcp.safety import is_write_sql
+    from duckquery_mcp.util import normalize_connection_id
+    if cfg.mode == "read-only" and is_write_sql(sql):
+        return {"error": "read-only mode: only SELECT / WITH / EXPLAIN are allowed."}
+    attach = [
+        {**db, "connection_id": normalize_connection_id(db["connection_id"])}
+        if isinstance(db, dict) and db.get("connection_id") else db
+        for db in (attach_databases or [])
+    ]
+    data = await client.call("POST", "/api/duckdb/federated-query",
+                             json_body={"sql": sql, "attach_databases": attach, "is_preview": True})
+    return _truncate(data, cfg)
+
+
+async def ask(client: DuckQueryClient, cfg: Config, *, question: str, tables: list | None = None, locale: str = "zh") -> Any:
+    """Natural-language question -> generated DuckDB SQL -> executed result."""
+    gen = await client.call("POST", "/api/ai/nl-to-sql",
+                            json_body={"question": question, "tables": tables or [], "locale": locale})
+    sql = gen.get("sql") if isinstance(gen, dict) else None
+    if not sql:
+        return {"error": "no SQL generated", "raw": gen}
+    result = await run_sql(client, cfg, sql=sql)
+    return {"generated_sql": sql, **result}
+
+
+async def explain_sql(client: DuckQueryClient, cfg: Config, *, sql: str, locale: str = "zh") -> Any:
+    """Plain-language explanation of a SQL statement."""
+    return await client.call("POST", "/api/ai/explain-sql", json_body={"sql": sql, "locale": locale})
+
+
+async def suggest_chart(
+    client: DuckQueryClient,
+    cfg: Config,
+    *,
+    columns: list,
+    sample: list | None = None,
+    locale: str = "zh",
+) -> Any:
+    """Suggest a chart type for a query result. Pass columns (list of {name, type}) and optional sample rows."""
+    return await client.call("POST", "/api/ai/suggest-chart",
+                             json_body={"columns": columns, "sample": sample or [], "locale": locale})
+
+
+async def chat(
+    client: DuckQueryClient,
+    cfg: Config,
+    *,
+    messages: list,
+    tables: list | None = None,
+    locale: str = "zh",
+) -> Any:
+    """Free-form data conversation with the configured LLM. messages is [{role, content}, ...]."""
+    return await client.call("POST", "/api/ai/chat",
+                             json_body={"messages": messages, "tables": tables or [], "locale": locale})
+
+
+async def error_fix(client: DuckQueryClient, cfg: Config, *, sql: str, error_message: str) -> Any:
+    """Error doctor: suggest a fix for a failing query, given the error."""
+    return await client.call("POST", "/api/ai/error-fix",
+                             json_body={"sql": sql, "error": error_message})

duckquery_mcp-0.1.0/duckquery_mcp/tools/sources.py

@@ -0,0 +1,142 @@
+from typing import Any
+
+
+async def add_connection(client, cfg, *, connection: dict, test: bool = True) -> Any:
+    """Save (and optionally test) an external DB connection.
+
+    `connection` must follow the DatabaseConnection shape:
+      {name, type, params: {host, port, database, username, password, ...}}
+    where `type` is one of: mysql, postgresql, sqlite, etc.
+    `test=True` (default) verifies the connection before saving; set to False to save without testing.
+    """
+    return await client.call(
+        "POST",
+        "/api/datasources/databases",
+        params={"test_connection": str(test).lower()},
+        json_body=connection,
+    )
+
+
+async def add_local_file_source(
+    client,
+    cfg,
+    *,
+    path: str,
+    table_alias: str | None = None,
+    import_mode: str = "auto",
+    csv_delimiter: str | None = None,
+    csv_has_header: bool | None = None,
+    csv_encoding: str | None = None,
+) -> Any:
+    """Register a local CSV/Parquet/JSON/Excel file as a DuckDB table.
+
+    Desktop mode allows any local path (ALLOW_ARBITRARY_LOCAL_PATHS=1).
+    `import_mode`: auto | smart | raw (controls type inference on load).
+    CSV-specific options (`csv_delimiter`, `csv_has_header`, `csv_encoding`) are ignored for non-CSV files.
+    """
+    body: dict = {"path": path, "import_mode": import_mode}
+    if table_alias is not None:
+        body["table_alias"] = table_alias
+    if csv_delimiter is not None:
+        body["csv_delimiter"] = csv_delimiter
+    if csv_has_header is not None:
+        body["csv_has_header"] = csv_has_header
+    if csv_encoding is not None:
+        body["csv_encoding"] = csv_encoding
+    return await client.call("POST", "/api/server-files/import", json_body=body)
+
+
+async def import_excel(
+    client,
+    cfg,
+    *,
+    path: str,
+    sheets: list,
+    import_mode: str = "auto",
+) -> Any:
+    """Import selected Excel sheets as DuckDB tables.
+
+    Each item in `sheets` is a dict matching ExcelSheetImportConfig:
+      {name: str, target_table: str, header_rows?: int, header_row_index?: int,
+       fill_merged?: bool, mode?: "create"|"append"|"replace"}
+    `import_mode`: auto | smart | raw.
+    """
+    return await client.call(
+        "POST",
+        "/api/server-files/excel/import",
+        json_body={"path": path, "sheets": sheets, "import_mode": import_mode},
+    )
+
+
+async def paste_data(
+    client,
+    cfg,
+    *,
+    table_name: str,
+    column_names: list,
+    column_types: list,
+    data_rows: list,
+    delimiter: str = ",",
+    has_header: bool = False,
+) -> Any:
+    """Create a DuckDB table from pasted tabular data.
+
+    `column_names`: list of column name strings, e.g. ["id", "name"].
+    `column_types`: list of type strings matching column_names, e.g. ["INTEGER", "VARCHAR"].
+      Supported types: VARCHAR, INTEGER, DOUBLE, DATE, BOOLEAN.
+    `data_rows`: list of rows, each a list of string cell values,
+      e.g. [["1", "Alice"], ["2", "Bob"]].
+    `delimiter`: used only for context (data is already parsed into rows).
+    `has_header`: whether the first row of data_rows is a header (usually False since
+      column_names is explicit).
+    """
+    return await client.call(
+        "POST",
+        "/api/paste-data",
+        json_body={
+            "table_name": table_name,
+            "column_names": column_names,
+            "column_types": column_types,
+            "data_rows": data_rows,
+            "delimiter": delimiter,
+            "has_header": has_header,
+        },
+    )
+
+
+async def read_url(
+    client,
+    cfg,
+    *,
+    url: str,
+    table_alias: str,
+    file_type: str | None = None,
+    import_mode: str = "auto",
+    encoding: str = "utf-8",
+    delimiter: str = ",",
+    header: bool = True,
+    prefer_native: bool = True,
+) -> Any:
+    """Download a remote file URL and load it into a DuckDB table.
+
+    `url`: public HTTP/HTTPS URL (GitHub blob URLs are auto-converted to raw).
+    `table_alias`: desired table name (de-duplicated if it already exists).
+    `file_type`: csv | json | parquet | excel (auto-detected from URL/Content-Type if omitted).
+    `import_mode`: auto | smart | raw.
+    `prefer_native`: try DuckDB/httpfs direct read first (faster), fall back to HTTP download.
+    Internal/loopback addresses and S3 URLs are blocked by the backend.
+    """
+    return await client.call(
+        "POST",
+        "/api/read_from_url",
+        json_body={
+            "url": url,
+            "table_alias": table_alias,
+            "file_type": file_type,
+            "import_mode": import_mode,
+            "encoding": encoding,
+            "delimiter": delimiter,
+            "header": header,
+            "prefer_native": prefer_native,
+        },
+    )

duckquery_mcp-0.1.0/duckquery_mcp/tools/transform.py

@@ -0,0 +1,20 @@
+from typing import Any
+
+
+async def save_as_table(client, cfg, *, sql: str, table_name: str) -> Any:
+    """Materialize a query's result as a new DuckDB table."""
+    # Router reads "table_alias" (or "tableAlias"); public param kept as table_name for clarity.
+    return await client.call("POST", "/api/save_query_to_duckdb",
+                             json_body={"sql": sql, "table_alias": table_name})
+
+
+async def pivot(client, cfg, *, config: dict, pivot_config: dict, execute: bool = False) -> Any:
+    """Pivot a table. execute=False previews; execute=True writes the pivoted result."""
+    path = "/api/pivot-query/generate" if execute else "/api/pivot-query/preview"
+    return await client.call("POST", path, json_body={"config": config, "pivot_config": pivot_config})
+
+
+async def set_operations(client, cfg, *, config: dict, execute: bool = False) -> Any:
+    """UNION/INTERSECT/EXCEPT across DuckDB tables. Pass config (SetOperationConfig dict). execute=False previews."""
+    path = "/api/set-operations/execute" if execute else "/api/set-operations/preview"
+    return await client.call("POST", path, json_body={"config": config})

duckquery_mcp-0.1.0/duckquery_mcp/util.py

@@ -0,0 +1,6 @@
+def normalize_connection_id(connection_id: str) -> str:
+    """Strip the ``db_`` prefix that ``/databases/list`` adds to connection ids but the
+    introspect / federated-query endpoints don't accept. So an id like ``db_SORDER``
+    (from list_connections) becomes ``SORDER`` (what those endpoints look up)."""
+    cid = str(connection_id)
+    return cid[3:] if cid.startswith("db_") else cid

duckquery_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "duckquery-mcp"
+version = "0.1.0"
+description = "MCP server for a locally-running DuckQuery backend"
+requires-python = ">=3.10"
+dependencies = ["mcp>=1.2.0", "httpx>=0.27"]
+
+[project.scripts]
+duckquery-mcp = "duckquery_mcp.__main__:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "respx>=0.21"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

duckquery_mcp-0.1.0/tests/conftest.py

@@ -0,0 +1,8 @@
+import pytest
+from duckquery_mcp.config import Config
+
+
+@pytest.fixture
+def cfg():
+    return Config(api_base=None, mode="normal", timeout=5.0,
+                  row_cap=200, probe_ports=(48001, 8000, 8001))

duckquery_mcp-0.1.0/tests/test_client.py

@@ -0,0 +1,77 @@
+import respx
+import httpx
+import pytest
+from duckquery_mcp.client import DuckQueryClient, BackendNotFound, BackendError
+
+
+@respx.mock
+async def test_probe_finds_healthy_backend(cfg):
+    respx.get("http://127.0.0.1:48001/health").mock(
+        return_value=httpx.Response(200, json={"status": "healthy"}))
+    client = DuckQueryClient(cfg)
+    assert await client.base() == "http://127.0.0.1:48001"
+
+
+@respx.mock
+async def test_env_base_wins(cfg):
+    cfg = cfg.__class__(**{**cfg.__dict__, "api_base": "http://127.0.0.1:7000"})
+    respx.get("http://127.0.0.1:7000/health").mock(
+        return_value=httpx.Response(200, json={"status": "healthy"}))
+    client = DuckQueryClient(cfg)
+    assert await client.base() == "http://127.0.0.1:7000"
+
+
+@respx.mock
+async def test_none_found_raises(cfg):
+    respx.get(url__regex=r".*/health").mock(return_value=httpx.Response(503))
+    client = DuckQueryClient(cfg)
+    with pytest.raises(BackendNotFound):
+        await client.base()
+
+
+@respx.mock
+async def test_call_unwraps_success_envelope(cfg):
+    respx.get("http://127.0.0.1:48001/health").mock(
+        return_value=httpx.Response(200, json={"status": "healthy"}))
+    respx.post("http://127.0.0.1:48001/api/duckdb/execute").mock(
+        return_value=httpx.Response(200, json={
+            "success": True, "data": {"row_count": 1, "data": [{"n": 16}]},
+            "messageCode": "QUERY_EXECUTED"}))
+    client = DuckQueryClient(cfg)
+    out = await client.call("POST", "/api/duckdb/execute", json_body={"sql": "SELECT 8+8 AS n"})
+    assert out["row_count"] == 1
+
+
+@respx.mock
+async def test_call_raises_on_failure_envelope(cfg):
+    respx.get("http://127.0.0.1:48001/health").mock(
+        return_value=httpx.Response(200, json={"status": "healthy"}))
+    respx.post("http://127.0.0.1:48001/api/duckdb/execute").mock(
+        return_value=httpx.Response(200, json={
+            "success": False, "message": "syntax error", "messageCode": "QUERY_FAILED"}))
+    client = DuckQueryClient(cfg)
+    with pytest.raises(BackendError, match="syntax error"):
+        await client.call("POST", "/api/duckdb/execute", json_body={"sql": "SELEC 1"})
+
+
+@respx.mock
+async def test_call_raises_on_http_4xx(cfg):
+    respx.get("http://127.0.0.1:48001/health").mock(
+        return_value=httpx.Response(200, json={"status": "healthy"}))
+    respx.post("http://127.0.0.1:48001/api/duckdb/execute").mock(
+        return_value=httpx.Response(404, json={"detail": "Not Found"}))
+    client = DuckQueryClient(cfg)
+    with pytest.raises(BackendError, match="Not Found"):
+        await client.call("POST", "/api/duckdb/execute", json_body={"sql": "x"})
+
+
+@respx.mock
+async def test_call_4xx_surfaces_envelope_message(cfg):
+    respx.get("http://127.0.0.1:48001/health").mock(
+        return_value=httpx.Response(200, json={"status": "healthy"}))
+    respx.post("http://127.0.0.1:48001/api/ai/explain-sql").mock(
+        return_value=httpx.Response(400, json={
+            "success": False, "messageCode": "ai_not_configured", "message": "AI not configured"}))
+    client = DuckQueryClient(cfg)
+    with pytest.raises(BackendError, match="not configured"):
+        await client.call("POST", "/api/ai/explain-sql", json_body={"sql": "x"})

duckquery_mcp-0.1.0/tests/test_config.py

@@ -0,0 +1,26 @@
+import pytest
+from duckquery_mcp.config import load_config, MODES
+
+
+def test_defaults(monkeypatch):
+    for k in ("DUCKQUERY_API_BASE", "DUCKQUERY_MCP_MODE", "DUCKQUERY_MCP_ROW_CAP"):
+        monkeypatch.delenv(k, raising=False)
+    cfg = load_config()
+    assert cfg.api_base is None
+    assert cfg.mode == "normal"
+    assert cfg.row_cap == 200
+    assert cfg.probe_ports == (48001, 8000, 8001)
+
+
+def test_env_override(monkeypatch):
+    monkeypatch.setenv("DUCKQUERY_API_BASE", "http://127.0.0.1:9999")
+    monkeypatch.setenv("DUCKQUERY_MCP_MODE", "read-only")
+    cfg = load_config()
+    assert cfg.api_base == "http://127.0.0.1:9999"
+    assert cfg.mode == "read-only"
+
+
+def test_bad_mode(monkeypatch):
+    monkeypatch.setenv("DUCKQUERY_MCP_MODE", "bogus")
+    with pytest.raises(SystemExit):
+        load_config()

duckquery_mcp-0.1.0/tests/test_integration.py

@@ -0,0 +1,15 @@
+import os
+import pytest
+from duckquery_mcp.client import DuckQueryClient
+from duckquery_mcp.config import load_config
+from duckquery_mcp.tools.query import run_sql
+
+pytestmark = pytest.mark.skipif(
+    not os.getenv("DUCKQUERY_INTEGRATION"),
+    reason="set DUCKQUERY_INTEGRATION=1 with a running backend")
+
+
+async def test_run_sql_live():
+    cfg = load_config()
+    out = await run_sql(DuckQueryClient(cfg), cfg, sql="SELECT 6*7 AS n")
+    assert out["rows"] == [{"n": 42}]

duckquery_mcp-0.1.0/tests/test_normalize.py

@@ -0,0 +1,48 @@
+import json
+
+import httpx
+import respx
+
+from duckquery_mcp.client import DuckQueryClient
+from duckquery_mcp.tools.discover import list_db_objects
+from duckquery_mcp.tools.query import federated_query
+from duckquery_mcp.util import normalize_connection_id
+
+
+def test_normalize_strips_db_prefix():
+    assert normalize_connection_id("db_SORDER") == "SORDER"
+    assert normalize_connection_id("SORDER") == "SORDER"
+    assert normalize_connection_id("db_db_x") == "db_x"  # only one prefix stripped
+
+
+@respx.mock
+async def test_list_db_objects_strips_id_and_compacts(cfg):
+    base = "http://127.0.0.1:48001"
+    respx.get(f"{base}/health").mock(return_value=httpx.Response(200, json={"status": "healthy"}))
+    # must hit the STRIPPED id (SORDER), not db_SORDER
+    route = respx.get(f"{base}/api/datasources/databases/SORDER/tables").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {
+            "connection_id": "SORDER", "database": "store_order",
+            "tables": [
+                {"table_name": "t1", "table_comment": "c1", "columns": [{"name": "a"}, {"name": "b"}]},
+                {"table_name": "t2", "table_comment": "c2", "columns": [{"name": "x"}]},
+            ]}}))
+    out = await list_db_objects(DuckQueryClient(cfg), cfg, connection_id="db_SORDER")
+    assert route.called
+    assert out["table_count"] == 2
+    assert out["truncated"] is False
+    assert out["tables"][0] == {"table_name": "t1", "comment": "c1", "column_count": 2}
+    assert "columns" not in out["tables"][0]  # heavy per-table columns dropped
+
+
+@respx.mock
+async def test_federated_query_strips_connection_id(cfg):
+    base = "http://127.0.0.1:48001"
+    respx.get(f"{base}/health").mock(return_value=httpx.Response(200, json={"status": "healthy"}))
+    route = respx.post(f"{base}/api/duckdb/federated-query").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {
+            "columns": ["n"], "data": [{"n": 1}], "row_count": 1}}))
+    await federated_query(DuckQueryClient(cfg), cfg, sql="SELECT 1 AS n FROM m.t",
+                          attach_databases=[{"alias": "m", "connection_id": "db_SORDER"}])
+    sent = json.loads(route.calls.last.request.content)
+    assert sent["attach_databases"][0]["connection_id"] == "SORDER"

duckquery_mcp-0.1.0/tests/test_passthrough.py

@@ -0,0 +1,19 @@
+import respx, httpx, pytest
+from duckquery_mcp.client import DuckQueryClient
+from duckquery_mcp.tools.passthrough import duckquery_request
+
+
+@respx.mock
+async def test_get_passthrough(cfg):
+    base = "http://127.0.0.1:48001"
+    respx.get(f"{base}/health").mock(return_value=httpx.Response(200, json={"status": "healthy"}))
+    respx.get(f"{base}/api/async-tasks").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {"tasks": []}}))
+    out = await duckquery_request(DuckQueryClient(cfg), cfg, method="GET", path="/api/async-tasks")
+    assert out == {"tasks": []}
+
+
+async def test_non_get_needs_confirm_in_normal(cfg):
+    out = await duckquery_request(DuckQueryClient(cfg), cfg, method="DELETE",
+                                  path="/api/duckdb/tables/t", confirm=False)
+    assert "confirm" in out["error"].lower()

duckquery_mcp-0.1.0/tests/test_safety.py

@@ -0,0 +1,19 @@
+from duckquery_mcp.safety import is_write_sql, tool_allowed
+
+
+def test_read_sql():
+    assert is_write_sql("SELECT * FROM t") is False
+    assert is_write_sql("  with x as (select 1) select * from x") is False
+
+
+def test_write_sql():
+    assert is_write_sql("DROP TABLE t") is True
+    assert is_write_sql("delete from t") is True
+    assert is_write_sql("garbage") is True  # unknown -> treat as write
+
+
+def test_tool_allowed_by_mode():
+    assert tool_allowed("read", "read-only") is True
+    assert tool_allowed("write", "read-only") is False
+    assert tool_allowed("write", "normal") is True
+    assert tool_allowed("write", "full") is True

duckquery_mcp-0.1.0/tests/test_tools_ai_export.py

@@ -0,0 +1,14 @@
+import respx, httpx
+from duckquery_mcp.client import DuckQueryClient
+from duckquery_mcp.tools.ai_settings import get_ai_settings
+
+
+@respx.mock
+async def test_get_ai_settings_masked(cfg):
+    base = "http://127.0.0.1:48001"
+    respx.get(f"{base}/health").mock(return_value=httpx.Response(200, json={"status": "healthy"}))
+    respx.get(f"{base}/api/settings/ai").mock(
+        return_value=httpx.Response(200, json={"success": True,
+            "data": {"default_provider": "openai", "providers": [{"id": "openai", "api_key": "****"}]}}))
+    out = await get_ai_settings(DuckQueryClient(cfg), cfg)
+    assert out["providers"][0]["api_key"] == "****"

duckquery_mcp-0.1.0/tests/test_tools_discover.py

@@ -0,0 +1,14 @@
+import respx
+import httpx
+from duckquery_mcp.client import DuckQueryClient
+from duckquery_mcp.tools.discover import list_tables
+
+
+@respx.mock
+async def test_list_tables(cfg):
+    base = "http://127.0.0.1:48001"
+    respx.get(f"{base}/health").mock(return_value=httpx.Response(200, json={"status": "healthy"}))
+    respx.get(f"{base}/api/duckdb/tables").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {"tables": ["a", "b"]}}))
+    out = await list_tables(DuckQueryClient(cfg), cfg)
+    assert out == {"tables": ["a", "b"]}

duckquery_mcp-0.1.0/tests/test_tools_query.py

@@ -0,0 +1,66 @@
+import respx
+import httpx
+from duckquery_mcp.client import DuckQueryClient
+from duckquery_mcp.tools.query import run_sql
+
+
+@respx.mock
+async def test_run_sql_returns_rows(cfg):
+    respx.get("http://127.0.0.1:48001/health").mock(
+        return_value=httpx.Response(200, json={"status": "healthy"}))
+    respx.post("http://127.0.0.1:48001/api/duckdb/execute").mock(
+        return_value=httpx.Response(200, json={
+            "success": True,
+            "data": {"columns": ["n"], "data": [{"n": 16}], "row_count": 1},
+            "messageCode": "QUERY_EXECUTED"}))
+    client = DuckQueryClient(cfg)
+    out = await run_sql(client, cfg, sql="SELECT 8+8 AS n")
+    assert out["row_count"] == 1
+    assert out["rows"] == [{"n": 16}]
+    assert out["truncated"] is False
+
+
+@respx.mock
+async def test_run_sql_truncates(cfg):
+    cfg = cfg.__class__(**{**cfg.__dict__, "row_cap": 2})
+    respx.get("http://127.0.0.1:48001/health").mock(
+        return_value=httpx.Response(200, json={"status": "healthy"}))
+    respx.post("http://127.0.0.1:48001/api/duckdb/execute").mock(
+        return_value=httpx.Response(200, json={
+            "success": True,
+            "data": {"columns": ["n"], "data": [{"n": i} for i in range(5)], "row_count": 5},
+            "messageCode": "QUERY_EXECUTED"}))
+    client = DuckQueryClient(cfg)
+    out = await run_sql(client, cfg, sql="SELECT * FROM big")
+    assert len(out["rows"]) == 2
+    assert out["truncated"] is True
+    assert out["row_count"] == 5
+
+
+async def test_run_sql_blocks_write_in_readonly(cfg):
+    ro = cfg.__class__(**{**cfg.__dict__, "mode": "read-only"})
+    out = await run_sql(None, ro, sql="DROP TABLE t")  # short-circuits before any HTTP call
+    assert "read-only" in out["error"].lower()
+
+
+async def test_federated_query_blocks_write_in_readonly(cfg):
+    ro = cfg.__class__(**{**cfg.__dict__, "mode": "read-only"})
+    from duckquery_mcp.tools.query import federated_query
+    out = await federated_query(None, ro, sql="DROP TABLE t", attach_databases=[])
+    assert "read-only" in out["error"].lower()
+
+
+@respx.mock
+async def test_ask_generates_then_runs(cfg):
+    base = "http://127.0.0.1:48001"
+    respx.get(f"{base}/health").mock(return_value=httpx.Response(200, json={"status": "healthy"}))
+    respx.post(f"{base}/api/ai/nl-to-sql").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {"sql": "SELECT 1 AS n"}}))
+    respx.post(f"{base}/api/duckdb/execute").mock(
+        return_value=httpx.Response(200, json={"success": True,
+            "data": {"columns": ["n"], "data": [{"n": 1}], "row_count": 1}}))
+    from duckquery_mcp.tools.query import ask
+    client = DuckQueryClient(cfg)
+    out = await ask(client, cfg, question="how many?")
+    assert out["generated_sql"] == "SELECT 1 AS n"
+    assert out["rows"] == [{"n": 1}]

duckquery_mcp-0.1.0/tests/test_tools_sources.py

@@ -0,0 +1,17 @@
+import respx
+import httpx
+from duckquery_mcp.client import DuckQueryClient
+from duckquery_mcp.tools.sources import add_local_file_source
+
+
+@respx.mock
+async def test_add_local_file_source(cfg):
+    base = "http://127.0.0.1:48001"
+    respx.get(f"{base}/health").mock(return_value=httpx.Response(200, json={"status": "healthy"}))
+    route = respx.post(f"{base}/api/server-files/import").mock(
+        return_value=httpx.Response(200, json={"success": True,
+            "data": {"table_name": "sales", "row_count": 42}}))
+    out = await add_local_file_source(DuckQueryClient(cfg), cfg, path="/data/sales.csv")
+    assert out["table_name"] == "sales"
+    sent = route.calls.last.request
+    assert b"/data/sales.csv" in sent.content

duckquery_mcp-0.1.0/tests/test_tools_transform.py

@@ -0,0 +1,13 @@
+import respx, httpx
+from duckquery_mcp.client import DuckQueryClient
+from duckquery_mcp.tools.transform import save_as_table
+
+
+@respx.mock
+async def test_save_as_table(cfg):
+    base = "http://127.0.0.1:48001"
+    respx.get(f"{base}/health").mock(return_value=httpx.Response(200, json={"status": "healthy"}))
+    respx.post(f"{base}/api/save_query_to_duckdb").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {"table_name": "t2"}}))
+    out = await save_as_table(DuckQueryClient(cfg), cfg, sql="SELECT 1", table_name="t2")
+    assert out["table_name"] == "t2"