# Clone and install
git clone https://github.com/DMDuFresne/questllens.git
cd questllens
npm install

# Configure
cp .env.example .env
cp context.md.example context.md
# Edit .env with your QUESTDB_URL

# Build and run
npm run build
npm start

docker run -p 3000:3000 \
  -e QUESTDB_URL="postgresql://admin:quest@host:8812/qdb" \
  ghcr.io/dmdufresne/questllens:1.0.0

{
  "mcpServers": {
    "questllens": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

{
  "mcpServers": {
    "questllens": {
      "url": "http://localhost:3000/mcp",
      "authorizationUrl": "http://localhost:3000/oauth/authorize",
      "tokenUrl": "http://localhost:3000/oauth/token",
      "registrationUrl": "http://localhost:3000/oauth/register"
    }
  }
}

{
  "mcpServers": {
    "questllens": {
      "type": "url",
      "url": "http://localhost:3000/mcp"
    }
  }
}

docker pull ghcr.io/dmdufresne/questllens:1.0.0

docker build -t questllens .

# Without OAuth (local development, trusted networks)
docker run -p 3000:3000 \
  -e QUESTDB_URL="postgresql://readonly:password@host:8812/qdb" \
  questllens

# With OAuth (production, Claude Desktop)
docker run -p 3000:3000 \
  -e QUESTDB_URL="postgresql://readonly:password@host:8812/qdb" \
  -e MCP_AUTH_PASSWORD="your-secure-password" \
  questllens node dist/index.js --oauth

# With custom domain context
docker run -p 3000:3000 \
  -e QUESTDB_URL="postgresql://readonly:password@host:8812/qdb" \
  -v ./my-context.md:/app/context.md \
  -e DOMAIN_CONTEXT_FILE="context.md" \
  questllens

services:
  questllens:
    image: ghcr.io/dmdufresne/questllens:1.0.0
    ports:
      - "3000:3000"
    environment:
      QUESTDB_URL: postgresql://readonly:password@questdb:8812/qdb
      MAX_ROWS: 500
    volumes:
      - ./context.md:/app/context.md
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

CREATE USER questllens_readonly WITH PASSWORD 'your-secure-password';
GRANT SELECT ON ALL TABLES TO questllens_readonly;

cp context.md.example context.md

# Via environment variable
DOMAIN_CONTEXT_FILE=context.md

# Or inline
DOMAIN_CONTEXT="This database stores sensor telemetry from industrial PLCs. Use SAMPLE BY for downsampled queries; never SELECT * across more than 1 hour of raw data."

# Industrial Telemetry Database

## Key Concepts
- Every table is partitioned by **DAY** with designated timestamp `ts`
- The `device_id` column is a SYMBOL — always filter on it before time ranges
- We use `LATEST ON ts PARTITION BY device_id` to get the most recent reading per device
- Hot data lives in the last 7 days; older partitions are detached to cold storage

## Common Queries
- 1-minute downsample: `SELECT ts, avg(value) FROM readings SAMPLE BY 1m`
- Latest per device: `SELECT * FROM readings LATEST ON ts PARTITION BY device_id`
- Aligned multi-sensor: `ASOF JOIN` on `ts`

## Gotchas
- The `value` column is in raw ADC counts, not engineering units — multiply by `scale` from `device_config`
- `ts` is always UTC; the device-local time is in `local_ts`
- Never run `SELECT *` on the `raw_packets` table — it's billions of rows

GET /health

{
  "status": "healthy",
  "server": "questllens",
  "version": "1.0.0"
}

POST /mcp          → JSON-RPC 2.0 request
GET  /mcp          → Server-Sent Events (SSE) stream
DELETE /mcp        → Session termination

GET  /.well-known/oauth-protected-resource  → Resource metadata
GET  /.well-known/oauth-authorization-server → Server metadata
POST /oauth/register                         → Dynamic client registration
GET  /oauth/authorize                        → Login form
POST /oauth/authorize                        → Authenticate
POST /oauth/token                            → Token exchange

# Install dependencies
npm install

# Run in dev mode (hot reload)
npm run dev

# Run with OAuth in dev mode
npm run dev:oauth

# Type check
npm run typecheck

# Run tests (read-only SQL boundary, config validation, identifier quoting)
npm test

# Build for production
npm run build

src/
├── index.ts                       # Entry point
├── config.ts                      # Environment config with Zod validation
├── server.ts                      # Express + MCP server, OAuth, session management
├── database/
│   ├── client.ts                  # PG-wire connection pool, query execution
│   ├── schema-loader.ts           # QuestDB introspection + cache (auto-refresh on miss)
│   └── sql-safety.ts              # Lexer + allowlist enforcing the read-only path
├── tools/
│   ├── index.ts                   # Executor re-exports
│   ├── _util.ts                   # Shared identifier quoting
│   ├── query.ts                   # Execute SELECT queries (markdown output)
│   ├── explain-query.ts           # QuestDB EXPLAIN
│   ├── suggest-sample-by.ts       # Pick a SAMPLE BY interval for a target bucket count
│   ├── list-tables.ts             # Tables with TS / partitioning / WAL flags
│   ├── describe-table.ts          # Table or MV detail (with optional time range / symbol stats)
│   ├── search-columns.ts          # Cross-table column search
│   ├── get-create-table.ts        # Round-trippable CREATE TABLE / CREATE MATERIALIZED VIEW
│   ├── get-table-params.ts        # Per-table ingestion knobs (o3MaxLag, maxUncommittedRows, ttl)
│   ├── refresh-schema.ts          # Manual cache reload (auto-refresh on miss is the default)
│   ├── get-partitions.ts          # Partition list with from/to filter and summary mode
│   ├── get-storage-summary.ts     # Top-N tables by disk (parquet vs native)
│   ├── get-sample-data.ts         # Sample rows with optional columns/where projection
│   ├── get-table-stats.ts         # Per-column null % + distinct (single batched SQL)
│   ├── get-wal-status.ts          # WAL apply state, lag, suspended tables
│   ├── get-ingestion-health.ts    # Composite WAL lag + latest-row staleness diagnostic
│   ├── get-running-queries.ts     # query_activity() wrapper
│   ├── get-mv-dependencies.ts     # Materialized view graph (forward + reverse)
│   └── server-info.ts             # Version, build, feature detection
├── descriptions/
│   ├── generator.ts               # Dynamic description builder
│   └── static.ts                  # Static description blocks
├── types/
│   └── index.ts                   # TypeScript interfaces
└── ...

tests/
├── sql-safety.test.ts             # Read-only boundary: verbs, literals, injection shapes
├── config.test.ts                 # Env parsing, limits, domain-context loading
└── identifiers.test.ts            # quoteIdent breakout attempts

skills/                            # Claude skills — copy into .claude/skills/
├── questllens-using/
├── questllens-explore-a-database/
├── questllens-health-check/
└── questllens-tune-a-query/

GRANT SELECT ON ALL TABLES TO questllens_readonly;