qb-ai-toolkit: Instructions file for Claude Code

CLAUDE.md — context for Claude Code

This file is read automatically by Claude Code. Keep it short, accurate, and specific to THIS project so suggestions are grounded in our real setup.

What this repo is

A small toolkit for working with our Quickbase app safely from the command line, built on the QuickBaseClient wrapper (Python). Use it for analysis, exports, formula drafting, and careful bulk updates.

There are two ways in: a read-only MCP server (quickbase_mcp.py) for asking questions in Claude chat, and this wrapper for building and for any writes. All create / update / delete work goes through the wrapper — never the MCP.

When using the MCP, users speak in plain language and won't know table names or field ids. The server scans the configured app(s) on startup and exposes a get_catalog() tool (apps, tables, fields, types, choices, example values) — call it first, map the user's wording to the right ids, then query. If access looks wrong or recently changed, call refresh_access() to re-scan.

How to connect (do this — don't invent another way)

• Never hard-code or paste the token. Credentials come from environment variables.
• Use config.get_client() — it reads QB_REALM, QB_USER_TOKEN, and QB_APP_ID from the environment (a local .env is loaded automatically in dev).
• Example:

  from config import get_client
  client = get_client()
  result = client.query_records(table_id="bxxxxxxx", where="{3.GT.'0'}", select=[3, 6, 7])
  

The wrapper's key methods

• query_records(table_id, select=[...], where="...", sort_by=[...], options={...}) → dict with data (list of { "<fieldId>": {"value": ...} }), fields, metadata.
• get_records_paginated(table_id, where=..., select=..., page_size=1000, max_records=None) → iterator over individual record dicts (use this for large pulls).
• upsert_records(table_id, records, merge_field_id, fields_to_return=None) → records is [{fieldId: value, ...}]. Use merge_field_id=3 (Record ID#) to UPDATE existing records only — this never creates new records.
• get_fields(table_id), get_tables(app_id), get_app(app_id), get_relationships(table_id).
• run_formula(table_id, formula, record_id=None) → test a formula via the API without changing the schema.
• delete_records(table_id, where) → permanent. Do not call without explicit human sign-off.