QueryView

Project skeleton: Python backend (FastAPI + SQLModel) + Vite + React + TypeScript SPA frontend with Tailwind CSS, plus Playwright end-to-end tests.

Quick start

Run the released package — API + bundled SPA on http://localhost:8000:

uvx queryview

--port (or the PORT env var) picks the listen port, default 8000: uvx queryview --port 9000.

Or run the container image — every release publishes ghcr.io/kolodkin/queryview to GHCR for linux/amd64 and linux/arm64, tagged vX.Y.Z and (for non-pre-releases) latest:

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

The command above keeps its state inside the container, so connections and workspaces are lost when the container is removed. See Run with Docker for a persistent setup.

Run with Docker

The image runs as the non-root user queryview (UID 1000) and sets DATA_DIR=/var/lib/queryview, so every piece of state lives directly under that one directory:

Mount a volume at /var/lib/queryview and all three persist across container restarts, removals and upgrades.

Persisting it

mkdir -p ~/.queryview
docker run -d --name queryview \
  -p 127.0.0.1:8000:8000 \
  -v ~/.queryview:/var/lib/queryview \
  ghcr.io/kolodkin/queryview:latest

Create the directory first so Docker doesn't create it owned by root. The container runs as UID 1000, the first user on most Linux distributions; if id -u prints something else, add --user "$(id -u):$(id -g)" so the container writes the files as you.

~/.queryview is also where a local uvx queryview keeps its state, so the container and a local run share one database, key and set of clones with no extra setup. Don't run both at once: each would serve the same SQLite file.

To let Docker own the location instead, swap the path for a named volume, -v queryview-data:/var/lib/queryview. Docker seeds it from the image, so ownership is already right and there is nothing to create up front, but the state no longer lines up with a local run.

Git sync

The image ships git, so workspace git sync works in the container, and its clones live under /var/lib/queryview/gitsync/, which the mount above already covers. Give the workspace an HTTPS remote carrying a scoped, expiring token — docs/gitsync.md has the URL form and what becomes of the credential.

SSH also works, but nothing in the container can answer a prompt: the key must be passphrase-free and known_hosts must already list the host. Mount one dedicated deploy key, not your whole .ssh, readable by UID 1000:

docker run -d --name queryview \
  -p 127.0.0.1:8000:8000 \
  -v ~/.queryview:/var/lib/queryview \
  -v ~/.ssh/queryview_deploy:/home/queryview/.ssh/id_ed25519:ro \
  -v ~/.ssh/known_hosts:/home/queryview/.ssh/known_hosts:ro \
  ghcr.io/kolodkin/queryview:latest

Layout

.
├── backend/         # Python FastAPI + SQLModel app exposing /api/* (queryview package)
├── frontend/        # Vite + React + TS + Tailwind v4 SPA (npm workspace)
├── e2e/             # Playwright (pytest) browser tests
├── pyproject.toml   # Backend deps + console script + e2e `test` group (uv)
└── package.json     # npm workspace root: dev orchestration + frontend build

Prerequisites

• uv — runs the Python backend and the Playwright (pytest) e2e suite (it manages the Python toolchain and dependencies for you).
• Node.js 20+ (with npm) — runs the root tasks and the Vite frontend.

npm runs the frontend and the root task scripts; uv handles the backend's and e2e suite's Python virtualenv and dependencies.

Install

Install the backend's Python dependencies (uv reads the root pyproject.toml; the package lives in backend/queryview):

uv sync

Install the JavaScript dependencies for the frontend workspace:

npm install

Install the e2e tooling (the test dependency group) and fetch the Playwright browser:

uv sync --group test
uv run --group test playwright install chromium

Run dev servers

Run backend and frontend together:

npm run dev

Or individually:

npm run backend    # uvicorn --reload on http://localhost:8000
npm run frontend   # http://localhost:5173

The Vite dev server proxies /api/* to the FastAPI backend, so the SPA can call the API on the same origin.

Build & preview production

npm run build      # produces frontend/dist/
npm run start      # SERVE_STATIC=1, FastAPI serves dist/ + /api on :8000
npm run preview    # build && start in one shot

In production there is no Vite — the FastAPI backend serves the bundled SPA from frontend/dist/ and falls back to index.html for any unknown non-/api path so client-side routing works. Override the dist location with STATIC_ROOT=/path/to/dist.

End-to-end tests

The e2e suite is pytest-playwright, installed via the test dependency group and run through uv.

Start the dev servers (npm run dev) in one terminal, then in another:

uv run --group test pytest

Override the target URL with BASE_URL=http://localhost:4173 uv run --group test pytest (e.g. to test a built preview). To run the full suite against a real ClickHouse the way CI does, use scripts/setup.sh.

Release to PyPI

The Publish to PyPI workflow (.github/workflows/publish.yaml, manual dispatch with a vX.Y.Z tag input) builds the SPA into the wheel (queryview/static/), then gates the release on the installed wheel: an HTTP smoke test, the packaged backend test suite (pytest --pyargs queryview), and the Playwright e2e suite driving the packaged server (skippable via the skip-e2e input for emergencies). It then publishes queryview via PyPI trusted publishing, pushes the tag, and creates the GitHub release. The package version comes from the tag (no version bump in pyproject.toml).

An installed wheel serves the bundled UI by default — see Quick start.

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, ...). 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.

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 git backups). The push tools target an armed browser session: enable "Allow remote control" from the agent icon next to the connection pill and use the session id it shows. See docs/remote.md for the full protocol.

API

See docs/api.md for the full endpoint reference.

The single-page prompt UI is described in docs/queryview.md; connecting (new <type> / connect <name>), SQLite persistence, and session auto-connect are specified in docs/connect.md.

All state lives in one data directory, ~/.queryview on every OS, relocated with DATA_DIR. Inside are the SQLite store db.sqlite, the local password-encryption key encryption.key, and the workspace git-sync clones under gitsync/.