# Quickbase AI Toolkit

A small, safety-first toolkit for working with Quickbase using AI assistants
(Claude and Claude Code). It pairs the [`QuickBaseClient`](https://github.com/josemsantiago/QuickbaseClients)
wrapper with a few well-behaved scripts so your team can analyze data, export
reports, draft formulas, and run **bulk updates that are previewed and confirmed
before they ever change anything**.

> Companion to the talk *"Augmenting Quickbase with AI."* See `DEMO_RUNBOOK.md`
> for the live-demo script and `CLAUDE.md` for the context Claude Code reads.

## Two layers
- **Analyze & report** — Claude in chat via the kit's tiny **read-only MCP**
  (`quickbase_mcp.py`), which learns your app's schema and sample data on
  startup so you can ask in plain language — no terminal, no code, no field ids.
- **Build & operate** — Claude Code + this toolkit: read app structure, draft and
  test formulas, and run safe bulk updates from the command line.

## Setup (about 5 minutes)
```bash
# 1. Get the kit
git clone https://github.com/josemsantiago/qb-ai-toolkit
cd qb-ai-toolkit

# 2. One command: installs deps, creates .env, wires up your AI tools
python setup_mcp.py

# 3. Edit .env (QB_REALM, QB_USER_TOKEN, QB_APP_ID) - then restart your AI app

# 4. Optional code-path check (read-only)
python scripts/query_preview.py --table bqXXXX --where "{3.GT.'0'}"
```

Not comfortable with a terminal? Double-click **`setup_mac.command`** (macOS) or
**`setup_windows.bat`** (Windows) instead of typing the command. (Python must be
installed first — the launcher points you to the download if it's missing.)

### Chat with your data (no code) — the MCP
Want the no-code experience? One command installs everything and connects a
**read-only** MCP server to Claude Desktop:

```bash
cp .env.example .env        # add your token
python setup_mcp.py         # installs deps + registers the MCP with Claude
```

Restart Claude Desktop, then just ask in plain language — *"How many open
invoices are overdue?"* or *"List my customers in Massachusetts."* You don't
need to know table names or field ids: on startup the MCP **scans the app(s)
you point it at** (schemas, field names, choices, and sample values) and builds
a local "memory" of your data, so Claude can map your wording to the right
tables and fields. The MCP can only **read** — it lists, describes, queries,
exports, and runs saved reports. Every write stays on the code path below.

- **Which apps?** Quickbase's API can't list every app a token can reach, so
  name the one(s) to scan with `QB_APP_ID` (or `QB_APP_IDS=bxxxx,byyyy` for
  several).
- **Token access changed?** Ask Claude to **refresh access** (the
  `refresh_access` tool) — it re-scans from scratch. The scan also re-runs on
  every startup. The memory files live in `.qb_cache/` (git-ignored).
- **Wide tables?** Tune the scan in `.env`: `QB_CATALOG_SAMPLE_ROWS` (default 25)
  and `QB_CATALOG_MAX_FIELDS` (default 40).

> Using Claude Code instead of Claude Desktop? `setup_mcp.py` prints the
> `claude mcp add ...` command to use.

Prefer manual installs? Clone the wrapper and install it yourself:
`git clone https://github.com/josemsantiago/QuickbaseClients.git && pip install -e ./QuickbaseClients/python -r requirements.txt`

## Works with your AI tool (macOS & Windows)
The MCP server is a standard stdio server, so it works with any MCP client — not
just Claude. `setup_mcp.py` auto-configures each one it finds and prints the rest.

- **Local (no hosting):** Claude Desktop, Claude Code, Cursor, Windsurf, VS Code
  (GitHub Copilot, Agent mode), Gemini CLI, and other stdio clients. These are
  model-agnostic, so you can use GPT or Gemini through them and still use this server.
- **ChatGPT:** reaches servers only over HTTPS, so run it locally with
  `python quickbase_mcp.py --http` and expose the `/mcp` route through a tunnel
  (OpenAI Secure MCP Tunnel, ngrok, or cloudflared). Full steps in `CLIENTS.md`.

Run `python setup_mcp.py --print` for copy/paste configs, and see **`CLIENTS.md`**
for exact file locations on macOS and Windows plus the ChatGPT steps.

## Credentials — the right way
Your Quickbase **user token** goes in `.env` (which is git-ignored) and is read
from the environment by `config.py`. It never gets pasted into a chat, committed,
or hard-coded.

```
QB_REALM=yourcompany.quickbase.com
QB_USER_TOKEN=replace_with_your_user_token
QB_APP_ID=bxxxxxxxx
```

Habits that keep it safe:
- **Least privilege** — scope the token to only the app(s) you need.
- **Never commit it** — `.env` is already in `.gitignore`.
- **Rotate & revoke** — cycle tokens periodically; kill a leaked one immediately.
- **Keep it out of chat** — reference the variable name, not the value.

## The golden rule for writes
**Preview → Confirm → Commit.** Run a read-only preview, eyeball the count and a
sample, then commit in batches matching on Record ID# (so records are updated,
never created). Bulk updates **default to a dry run** — real changes require
`--commit`. Always test on a sandbox first.

## What's inside
| File | What it does |
|------|--------------|
| `config.py` | Builds the client from environment variables (single source of truth). |
| `quickbase_mcp.py` | Read-only MCP server — chat with your Quickbase in Claude (no code). |
| `setup_mcp.py` | One command: installs deps and registers the MCP with your AI tools. |
| `setup_mac.command` / `setup_windows.bat` | Double-click launchers (no terminal needed). |
| `CLIENTS.md` | Per-tool setup (Claude, Cursor, Windsurf, VS Code, Gemini, ChatGPT), macOS & Windows. |
| `CLAUDE.md` | Context Claude Code reads: how to connect, conventions, the golden rule. |
| `scripts/query_preview.py` | Read-only: how many records a query matches, plus a sample. |
| `scripts/safe_mass_update.py` | Set one field on matching records — preview → confirm → commit, dry-run by default. |
| `scripts/export_report.py` | Query a table and export to `.xlsx` with field-label headers. |
| `scripts/describe_app.py` | Print the app's tables, fields, and relationships. |
| `formulas/` | **Authoritative, source-cited Quickbase formula reference**: the language, the full function catalog, date/duration rules, and the Rich-Text/HTML + URL-button subset. |
| `codepages/` | How to build **code pages** (in-app HTML/JS widgets) and the **authentication** model (XML-as-the-logged-in-user by default; the elevated-token exception). |
| `.claude/` | Bundled Claude Code **skills** (`quickbase-codepage`, `quickbase-formulas`) and the **`quickbase-expert`** agent — auto-load when you open this folder in Claude Code (see below). |
| `DEMO_RUNBOOK.md` | Prep checklist and the three-act live-demo flow with fallbacks. |
| `.env.example` | Template for your credentials (copy to `.env`). |
| `SECURITY.md` | How the toolkit protects your token and data, and how to report an issue. |
| `CONTRIBUTING.md` | How to propose changes (and the safety rules that stay non-negotiable). |
| `LICENSE` | MIT. |

## Bundled Quickbase expertise for Claude Code (download → go)
Everything Claude Code needs to be a Quickbase expert ships **inside this repo**, so there is
nothing extra to install. When you open the `qb-ai-toolkit` folder in Claude Code, it auto-loads:

- **Skills** (`.claude/skills/`)
  - **`quickbase-formulas`** — write, correct, and test formulas grounded in the cited reference
    (surfaces automatically when you ask for a formula; or type `/quickbase-formulas`).
  - **`quickbase-codepage`** — turn a Python script (or a request) into an in-app **code-page
    widget** that reads data live as the logged-in user, with **no token in the page**.
- **Agent** (`.claude/agents/`)
  - **`quickbase-expert`** — a specialist subagent for any Quickbase question (formulas, rich-text
    HTML, code pages, auth, safe writes) that grounds answers in `formulas/` and `codepages/`
    instead of guessing.

Just ask in plain language — *"Write a Formula – Rich Text status badge,"* *"Make this script a
code page,"* *"Why won't this formula compile?"* — and the right skill/agent kicks in. The
authoritative references it reads live in **[`formulas/`](formulas/)** and
**[`codepages/`](codepages/)**, so they're useful on their own even in Claude Desktop or any editor.

> **Use it in every project (optional):** copy the skills and agent into your personal config —
> `cp -R .claude/skills/* ~/.claude/skills/ && cp .claude/agents/*.md ~/.claude/agents/` — and
> they'll be available in Claude Code everywhere, not just this folder.

## Quick examples
```bash
# Preview what a query matches (changes nothing)
python scripts/query_preview.py --table bqXXXX --where "{7.EX.'MA'}" --select 3 7 12

# Dry run a bulk update (changes nothing)
python scripts/safe_mass_update.py --table bqXXXX --where "{7.EX.'MA'}" --field 12 --value "NE"

# Apply it (asks you to type the match-count to confirm)
python scripts/safe_mass_update.py --table bqXXXX --where "{7.EX.'MA'}" --field 12 --value "NE" --commit

# Export a report
python scripts/export_report.py --table bqXXXX --where "{6.GT.'0'}" --select 3 6 7 12 --out open_items.xlsx

# Map the app's structure
python scripts/describe_app.py --app bxxxxxxx --fields
```

## Notes
- The wrapper is zero-dependency (standard library). `python-dotenv` and
  `openpyxl` are optional extras used for `.env` auto-loading and Excel export.
- This toolkit is intentionally small and readable — extend it for your team.
- Not affiliated with or endorsed by Quickbase.

## Security
Your token stays in `.env` (git-ignored), the MCP layer is read-only, and every
write is previewed and confirmed before it runs. Details — and how to report a
vulnerability privately — are in **[SECURITY.md](SECURITY.md)**.

## Contributing
Small, focused pull requests are welcome. Please read
**[CONTRIBUTING.md](CONTRIBUTING.md)** first — the safety rules (dry-run-by-default
writes, read-only MCP, no committed secrets) are non-negotiable. `main` is
protected, so changes land via pull request.

## License
Released under the [MIT License](LICENSE) — © 2026 Jose Santiago Echevarria.

## Author
Built by **Jose Santiago Echevarria** ([@josemsantiago](https://github.com/josemsantiago)),
companion to the talk *"Augmenting Quickbase with AI."* The `QuickBaseClient`
wrapper it builds on lives at
[josemsantiago/QuickbaseClients](https://github.com/josemsantiago/QuickbaseClients).