queryview 0.0.2__tar.gz → 0.0.3__tar.gz

{queryview-0.0.2 → queryview-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: queryview
-Version: 0.0.2
+Version: 0.0.3
 Summary: QueryView: FastAPI + SQLModel backend and React SPA over the ClickHouse HTTP interface
 Project-URL: Homepage, https://github.com/kolodkin/queryview
 Project-URL: Repository, https://github.com/kolodkin/queryview
@@ -16,6 +16,7 @@ Requires-Dist: duckdb>=1.0
 Requires-Dist: fastapi>=0.110
 Requires-Dist: httpx>=0.27
 Requires-Dist: mcp<2,>=1.9
+Requires-Dist: platformdirs>=4
 Requires-Dist: pyyaml>=6
 Requires-Dist: sqlalchemy[asyncio]>=2.0
 Requires-Dist: sqlmodel>=0.0.16
@@ -46,7 +47,9 @@ docker run -p 8000:8000 ghcr.io/kolodkin/queryview:latest
 ```
 
 To serve on a different host port, remap it (the container keeps listening on
-8000, which its healthcheck probes): `docker run -p 9000:8000 ...`.
+8000, which its healthcheck probes): `docker run -p 9000:8000 ...`. QueryView
+expects to be reached from localhost only, so prefer binding the published port
+to loopback: `docker run -p 127.0.0.1:8000:8000 ...`.
 
 State (the SQLite DB and its encryption key) lives in `/home/queryview`; mount a
 volume there to persist it across containers:
@@ -154,14 +157,34 @@ An installed wheel serves the bundled UI by default — see
 ## MCP server
 
 The backend mounts a FastMCP server (Streamable HTTP) at
-`http://localhost:8000/mcp`. There is nothing extra to start — it runs inside
-the server process (`uvx queryview`, `npm run dev`, ...). Hook up an MCP client,
-e.g.:
+`http://localhost:8000/mcp/`. There is nothing extra to start — it runs inside
+the server process (`uvx queryview`, `npm run dev`, ...). Registering the client
+is a separate, one-time step on the machine running the agent: an HTTP MCP
+server can't install itself into someone else's client.
 
 ```bash
-claude mcp add --transport http queryview http://localhost:8000/mcp
+claude mcp add --transport http queryview http://localhost:8000/mcp/
 ```
 
+Three things to get right:
+
+- **Prefer the trailing slash.** The mount serves `/mcp/`. The slashless
+  `/mcp` also works — it 307-redirects — but registering the canonical path
+  skips a round trip on every call.
+- **Match the port.** The URL must point at the port QueryView actually
+  listens on — `--port 9000` means `http://localhost:9000/mcp/`, and
+  `docker run -p 9000:8000` means the *host* port, `9000`, not the container's
+  `8000`.
+- **Start QueryView first.** The client dials this URL when it starts; if
+  nothing is listening it reports a connection error and stays failed until you
+  reconnect it.
+
+QueryView is a **local, single-user tool**: it assumes it is reachable only from
+localhost. `/mcp/` is unauthenticated, and its tools can query every configured
+connection and rewrite workspace git state, so don't publish the port. Bind the
+container to loopback — `docker run -p 127.0.0.1:8000:8000 ...` — since a plain
+`-p 8000:8000` listens on all interfaces.
+
 Tools: `run_query` (read-only SQL, rows returned to the agent), `push_query`
 and `push_dashboard` (fill a live browser session), `list_queries` /
 `list_dashboards`, and `git_store` / `git_history` / `git_restore` (workspace
@@ -178,6 +201,10 @@ The single-page prompt UI is described in [docs/queryview.md](docs/queryview.md)
 connecting (`new <type>` / `connect <name>`), SQLite persistence, and session
 auto-connect are specified in [docs/connect.md](docs/connect.md).
 
-Connections are stored in SQLite (`backend/queryview.db`, override with
-`DB_PATH`); the backend writes that file and a local password-encryption key
-(`backend/queryview.db.key`, override with `DB_KEY_PATH`).
+Connections are stored in SQLite. The default location is the platform's
+user-data directory — `$XDG_DATA_HOME/queryview/queryview.db` (i.e.
+`~/.local/share/queryview/`) on Linux, `~/Library/Application Support/queryview/`
+on macOS, `%LOCALAPPDATA%\queryview\` on Windows — overridable with `DB_PATH`.
+Alongside it the backend writes a local password-encryption key
+(`<db>.key`, override with `DB_KEY_PATH`) and the workspace git-sync clones
+(`<db>.gitsync/`, override with `GIT_SYNC_DIR`).

{queryview-0.0.2 → queryview-0.0.3}/README.md

@@ -22,7 +22,9 @@ docker run -p 8000:8000 ghcr.io/kolodkin/queryview:latest
 ```
 
 To serve on a different host port, remap it (the container keeps listening on
-8000, which its healthcheck probes): `docker run -p 9000:8000 ...`.
+8000, which its healthcheck probes): `docker run -p 9000:8000 ...`. QueryView
+expects to be reached from localhost only, so prefer binding the published port
+to loopback: `docker run -p 127.0.0.1:8000:8000 ...`.
 
 State (the SQLite DB and its encryption key) lives in `/home/queryview`; mount a
 volume there to persist it across containers:
@@ -130,14 +132,34 @@ An installed wheel serves the bundled UI by default — see
 ## MCP server
 
 The backend mounts a FastMCP server (Streamable HTTP) at
-`http://localhost:8000/mcp`. There is nothing extra to start — it runs inside
-the server process (`uvx queryview`, `npm run dev`, ...). Hook up an MCP client,
-e.g.:
+`http://localhost:8000/mcp/`. There is nothing extra to start — it runs inside
+the server process (`uvx queryview`, `npm run dev`, ...). Registering the client
+is a separate, one-time step on the machine running the agent: an HTTP MCP
+server can't install itself into someone else's client.
 
 ```bash
-claude mcp add --transport http queryview http://localhost:8000/mcp
+claude mcp add --transport http queryview http://localhost:8000/mcp/
 ```
 
+Three things to get right:
+
+- **Prefer the trailing slash.** The mount serves `/mcp/`. The slashless
+  `/mcp` also works — it 307-redirects — but registering the canonical path
+  skips a round trip on every call.
+- **Match the port.** The URL must point at the port QueryView actually
+  listens on — `--port 9000` means `http://localhost:9000/mcp/`, and
+  `docker run -p 9000:8000` means the *host* port, `9000`, not the container's
+  `8000`.
+- **Start QueryView first.** The client dials this URL when it starts; if
+  nothing is listening it reports a connection error and stays failed until you
+  reconnect it.
+
+QueryView is a **local, single-user tool**: it assumes it is reachable only from
+localhost. `/mcp/` is unauthenticated, and its tools can query every configured
+connection and rewrite workspace git state, so don't publish the port. Bind the
+container to loopback — `docker run -p 127.0.0.1:8000:8000 ...` — since a plain
+`-p 8000:8000` listens on all interfaces.
+
 Tools: `run_query` (read-only SQL, rows returned to the agent), `push_query`
 and `push_dashboard` (fill a live browser session), `list_queries` /
 `list_dashboards`, and `git_store` / `git_history` / `git_restore` (workspace
@@ -154,6 +176,10 @@ The single-page prompt UI is described in [docs/queryview.md](docs/queryview.md)
 connecting (`new <type>` / `connect <name>`), SQLite persistence, and session
 auto-connect are specified in [docs/connect.md](docs/connect.md).
 
-Connections are stored in SQLite (`backend/queryview.db`, override with
-`DB_PATH`); the backend writes that file and a local password-encryption key
-(`backend/queryview.db.key`, override with `DB_KEY_PATH`).
+Connections are stored in SQLite. The default location is the platform's
+user-data directory — `$XDG_DATA_HOME/queryview/queryview.db` (i.e.
+`~/.local/share/queryview/`) on Linux, `~/Library/Application Support/queryview/`
+on macOS, `%LOCALAPPDATA%\queryview\` on Windows — overridable with `DB_PATH`.
+Alongside it the backend writes a local password-encryption key
+(`<db>.key`, override with `DB_KEY_PATH`) and the workspace git-sync clones
+(`<db>.gitsync/`, override with `GIT_SYNC_DIR`).

{queryview-0.0.2 → queryview-0.0.3}/backend/queryview/connect.py

@@ -14,6 +14,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar
 
+import platformdirs
 from cryptography.hazmat.primitives.ciphers.aead import AESGCM
 from sqlalchemy.ext.asyncio import create_async_engine
 from sqlmodel import Field, SQLModel, col, select
@@ -40,10 +41,14 @@ class Connection(SQLModel, table=True):
 
 
 def _db_path() -> Path:
+    """The SQLite store's path: DB_PATH, else the platform's user-data dir
+    (`$XDG_DATA_HOME/queryview` on Linux, `Application Support` on macOS,
+    `%LOCALAPPDATA%` on Windows). Deliberately not package-relative — that put
+    the DB in site-packages, which is uv's disposable cache under `uvx`."""
     env = os.environ.get("DB_PATH")
     if env:
         return Path(env)
-    return Path(__file__).resolve().parent.parent / "queryview.db"
+    return Path(platformdirs.user_data_dir("queryview")) / "queryview.db"
 
 
 _engine = None
@@ -80,6 +85,9 @@ async def _ensure_schema() -> None:
         return
     from alembic import command
 
+    # SQLite won't create a missing parent, and the user-data dir doesn't exist
+    # on a fresh install; the key file and git-sync clones land here too.
+    _db_path().parent.mkdir(parents=True, exist_ok=True)
     command.upgrade(_alembic_config(), "head")
     _schema_ready = True
 

{queryview-0.0.2 → queryview-0.0.3}/backend/queryview/main.py

@@ -11,7 +11,13 @@ from pathlib import Path
 from typing import Any
 
 from fastapi import FastAPI, Request
-from fastapi.responses import FileResponse, JSONResponse, PlainTextResponse, StreamingResponse
+from fastapi.responses import (
+    FileResponse,
+    JSONResponse,
+    PlainTextResponse,
+    RedirectResponse,
+    StreamingResponse,
+)
 
 from . import gitsync, remote, workspaces, yamlio
 from .connect import (
@@ -100,6 +106,14 @@ app = FastAPI(title="queryview-backend", lifespan=lifespan)
 app.mount("/mcp", mcp.streamable_http_app())
 
 
+# The GET-only catch-all below suppresses Starlette's own /mcp -> /mcp/ redirect
+# (see test_mcp_mount.py), so issue it explicitly. 307 preserves method and
+# body; Streamable HTTP uses POST, GET and DELETE.
+@app.api_route("/mcp", methods=["GET", "POST", "DELETE"], include_in_schema=False)
+async def mcp_slash_redirect() -> RedirectResponse:
+    return RedirectResponse("/mcp/", status_code=307)
+
+
 @app.middleware("http")
 async def session_cookie(request: Request, call_next):
     sid = request.cookies.get("qv_session")

queryview-0.0.3/backend/queryview/test_db_path.py

@@ -0,0 +1,58 @@
+"""Where the SQLite store lives.
+
+The default used to be package-relative (`Path(__file__).parent.parent`), which
+meant `backend/queryview.db` in a checkout but `<site-packages>/queryview.db`
+once the wheel shipped — under `uvx`, that is inside uv's *cache*, where a
+`uv cache clean` or a version bump silently takes the DB with it. The default
+is now the platform's user-data directory.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import platformdirs
+
+import queryview
+from queryview.connect import _db_path, _key_path
+
+
+def test_db_path_defaults_to_user_data_dir(monkeypatch):
+    monkeypatch.delenv("DB_PATH", raising=False)
+    expected = Path(platformdirs.user_data_dir("queryview")) / "queryview.db"
+    assert _db_path() == expected
+
+
+def test_db_path_is_not_inside_the_installed_package(monkeypatch):
+    """The regression: a package-relative default puts user data in
+    site-packages (and under uvx, in a disposable cache directory)."""
+    monkeypatch.delenv("DB_PATH", raising=False)
+    package_root = Path(queryview.__file__).resolve().parent.parent
+    assert package_root not in _db_path().resolve().parents
+
+
+def test_db_path_env_var_still_wins(monkeypatch, tmp_path):
+    monkeypatch.setenv("DB_PATH", str(tmp_path / "custom.db"))
+    assert _db_path() == tmp_path / "custom.db"
+    # The key file follows the DB unless DB_KEY_PATH says otherwise.
+    monkeypatch.delenv("DB_KEY_PATH", raising=False)
+    assert _key_path() == tmp_path / "custom.db.key"
+
+
+def test_ensure_schema_creates_a_missing_data_dir(monkeypatch, tmp_path):
+    """The user-data dir does not exist on a fresh install, so startup has to
+    create it — SQLite will not create a missing parent directory."""
+    import asyncio
+
+    import queryview.connect as c
+
+    target = tmp_path / "fresh" / "nested" / "queryview.db"
+    monkeypatch.setenv("DB_PATH", str(target))
+    monkeypatch.setenv("DB_KEY_PATH", str(target.with_suffix(".db.key")))
+    monkeypatch.setattr(c, "_engine", None)
+    monkeypatch.setattr(c, "_schema_ready", False)
+    assert not target.parent.exists()
+
+    asyncio.run(c._ensure_schema())
+
+    assert target.parent.is_dir()

queryview-0.0.3/backend/queryview/test_mcp_mount.py

@@ -0,0 +1,38 @@
+"""The MCP mount's slashless path.
+
+The FastMCP app is mounted at `/mcp` with its own path set to `/`, so the
+canonical endpoint is `/mcp/`. Starlette would normally redirect `/mcp` there,
+but the SPA catch-all (`@app.get("/{full_path:path}")`) matches the slashless
+path on GET only, which Starlette scores as a partial match — that suppresses
+the redirect and answers `405 allow: GET` instead, pointing a client at a path
+the MCP server never serves. These tests pin the redirect so the catch-all
+can't swallow it again.
+"""
+
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from queryview.main import app
+
+# Streamable HTTP uses POST (messages), GET (the SSE stream) and DELETE
+# (session termination) — all three must reach the mount.
+MCP_METHODS = ["POST", "GET", "DELETE"]
+
+
+@pytest.mark.parametrize("method", MCP_METHODS)
+def test_slashless_mcp_redirects_to_canonical_path(method):
+    c = TestClient(app, follow_redirects=False)
+    r = c.request(method, "/mcp")
+    assert r.status_code == 307, f"{method} /mcp returned {r.status_code}, not a redirect"
+    assert r.headers["location"].endswith("/mcp/")
+
+
+@pytest.mark.parametrize("method", MCP_METHODS)
+def test_canonical_mcp_path_is_not_redirected(method):
+    """The redirect must not shadow the mount itself."""
+    c = TestClient(app, follow_redirects=False, raise_server_exceptions=False)
+    r = c.request(method, "/mcp/")
+    assert r.status_code != 307
+    assert "location" not in r.headers

{queryview-0.0.2 → queryview-0.0.3}/docker/Dockerfile

@@ -18,9 +18,10 @@ RUN useradd --create-home --uid 1000 queryview
 WORKDIR /home/queryview
 USER queryview
 
-# The default DB path sits inside site-packages, which the non-root user can't
-# write; keep the SQLite file (and its sibling .key file) in the home dir so a
-# volume mounted at /home/queryview persists all state.
+# The default is the user-data dir (/home/queryview/.local/share/queryview);
+# pin the SQLite file (and its sibling .key file and git-sync clones) to the top
+# of the home dir instead, so a volume mounted at /home/queryview persists all
+# state at a flat, documented path.
 ENV DB_PATH=/home/queryview/queryview.db
 
 EXPOSE 8000

{queryview-0.0.2 → queryview-0.0.3}/docs/api.md

@@ -30,9 +30,10 @@ independently. Saved connections are shared (SQLite).
 | GET    | `/api/dashboards`           | `?workspace=`                          | List a workspace's dashboards (no payload): `{dashboards:[{name, connection, updated_at}]}`, ordered by name. |
 | GET    | `/api/dashboards/{name}`    | `?workspace=`                          | A saved dashboard `{name, connection, html, queries}` (`queries` parsed to a dict), or `404 {error:"not found"}`. |
 
-**MCP:** a FastMCP server is mounted at `/mcp` (Streamable HTTP) exposing
-`push_query` (push SQL to a session's query panel) and `upsert_dashboard`
-(persist a dashboard and push it to a session). Both delegate to the in-process
+**MCP:** a FastMCP server is mounted at `/mcp/` (Streamable HTTP) exposing
+`push_query` (push SQL to a session's query panel), `push_dashboard` (push a
+dashboard draft to a session), `run_query`, `list_queries` / `list_dashboards`
+and `git_store` / `git_history` / `git_restore`. They delegate to the in-process
 hubs the matching REST endpoints call. See [remote.md](./remote.md) and
 [dashboard.md](./dashboard.md).
 

{queryview-0.0.2 → queryview-0.0.3}/docs/remote.md

@@ -16,9 +16,17 @@ session's **id** and a copyable command, e.g.:
 Turning the toggle off (or closing the tab) disarms the session immediately —
 pushes to its id are then reported as not delivered.
 
+## Connecting a client
+
+The server runs inside the backend process — nothing extra to start — but the
+client registration is a separate one-time step: point it at
+`http://localhost:8000/mcp/` (the slashless `/mcp` redirects there; match the
+port QueryView listens on, and start it first). See
+[the README](../README.md#mcp-server).
+
 ## MCP tools
 
-The backend mounts a FastMCP server (Streamable HTTP) at `/mcp` exposing four
+The backend mounts a FastMCP server (Streamable HTTP) at `/mcp/` exposing four
 tools:
 
 - `push_query(session_id, query, limit?=100, offset?=0, order_by?, fields?, cell_view?, name?)` —

{queryview-0.0.2 → queryview-0.0.3}/pyproject.toml

@@ -18,6 +18,7 @@ dependencies = [
     "asyncpg>=0.29",
     "duckdb>=1.0",
     "pyyaml>=6",
+    "platformdirs>=4",
 ]
 
 [project.urls]

{queryview-0.0.2 → queryview-0.0.3}/uv.lock

@@ -1185,6 +1185,7 @@ dependencies = [
     { name = "fastapi" },
     { name = "httpx" },
     { name = "mcp" },
+    { name = "platformdirs" },
     { name = "pyyaml" },
     { name = "sqlalchemy", extra = ["asyncio"] },
     { name = "sqlmodel" },
@@ -1214,6 +1215,7 @@ requires-dist = [
     { name = "fastapi", specifier = ">=0.110" },
     { name = "httpx", specifier = ">=0.27" },
     { name = "mcp", specifier = ">=1.9,<2" },
+    { name = "platformdirs", specifier = ">=4" },
     { name = "pyyaml", specifier = ">=6" },
     { name = "sqlalchemy", extras = ["asyncio"], specifier = ">=2.0" },
     { name = "sqlmodel", specifier = ">=0.0.16" },