querywise-mcp CLAUDE.md

CLAUDE.md

Project Overview

querywise-mcp — an MCP server + CLI for querying databases in natural language through a semantic metadata layer. Refactored from the QueryWise full-stack app (../querywise): the FastAPI web layer and React frontend are gone; the metadata store moved from Postgres+pgvector to embedded SQLite + sqlite-vec. The semantic layer, LLM agents, and connectors are ported largely unchanged.

Tech Stack

• Python 3.11+, MCP Python SDK (FastMCP), Typer (CLI)
• SQLAlchemy (async) + aiosqlite + sqlite-vec for the metadata store
• Target connectors: SQLite (read-only), PostgreSQL (asyncpg), BigQuery, Databricks
• LLM: provider-agnostic (Anthropic, OpenAI, Ollama) — only needed for ask/generate_sql and cloud embeddings

How to Run

pip install -e ".[llm]"           # install (drop [llm] for keyword-only)
querywise init                    # create the SQLite store
querywise serve                   # MCP server over stdio (--http for Streamable HTTP)
querywise ask <conn> "<question>" # full pipeline via CLI

Entry points (pyproject.toml): querywise → cli:app, querywise-mcp → server:main.

Layout

src/querywise_mcp/
├── config.py          # pydantic-settings; resolved_database_url() -> sqlite path
├── server.py          # FastMCP: 25 tools + schema resource + text_to_sql prompt; stdio/http
├── cli.py             # Typer CLI (ask, sql, context, connections, serve, seed-sample)
├── db/                # SQLite metadata store
│   ├── session.py     # async engine; loads sqlite-vec via await_only in connect event; WAL
│   ├── types.py       # Embedding TypeDecorator (list[float] <-> float32 BLOB)
│   ├── vectors.py     # knn(): vec_distance_cosine when loaded, else in-process cosine
│   ├── init.py        # init_db() create_all + embedding-dimension reconciliation (no Alembic)
│   └── models/        # ORM models (generic types: Uuid, JSON, Embedding)
├── semantic/          # context_builder, schema_linker, glossary_resolver, prompt_assembler
├── llm/               # providers (anthropic/openai/ollama), agents, router, prompts
├── services/          # query_service, connection_service, schema_service,
│                      #   embedding_service, knowledge_service, semantic_service, setup_service
├── connectors/        # base + sqlite/postgresql/bigquery/databricks + registry
├── core/exceptions.py
└── utils/sql_sanitizer.py