AppBI Workboard MCP

Build a working AppBI Workboard mini-app end to end — from raw data all the way to a shareable app — through one self-contained MCP server:

Source  ->  Dataset  ->  Data Model  ->  Workboard  ->  Share

Connect or pick a data source, create a dataset and its tables, lay down a relationship model, then author the mini-app (forms — incl. photo/OCR capture and a satellite map picker; editable tables that can render as a photo gallery; printable docs; embedded dashboards) with app users, doc webhooks, public links and a delivery workspace. Every mutating tool previews a plan and changes nothing until you confirm.

Charts, full BI semantic measures/explores, and DB-credential source connections stay in the AppBI UI / dashboard MCP. This server owns the Workboard journey.

Setup

Set-Location D:\Appv2\appbi-ai\Skill-AppBI\appbi-workboard-mcp
.\setup-mcp.ps1          # creates .venv, installs deps, seeds .env
.\bootstrap-pat.ps1      # mints your PAT and writes it into .env (see below)
.\run-mcp.ps1            # launches the server (profile=all)

macOS / Linux:

cd /path/to/appbi-workboard-mcp
cp .env.example .env     # set APPBI_BASE_URL if not http://localhost:8000
./bootstrap-pat.sh       # mints your PAT and writes it into .env
./run-mcp.sh             # bootstraps .venv on first run

Get your PAT (the token that connects the MCP)

The MCP authenticates to AppBI with a Personal Access Token (PAT). A PAT cannot mint itself (the call that creates it needs a logged-in account), so this is the one credential you supply once. Three ways, no hand-written code:

1. Shipped helper (recommended for first run). bootstrap-pat.ps1 / ./bootstrap-pat.sh (or python bootstrap_pat.py) asks for your AppBI base URL, email and password, mints the token, and writes APPBI_PAT + APPBI_BASE_URL into .env. Add --print-only to just print it.
2. From inside your MCP client. If the server is already registered, call the bootstrap_personal_access_token tool with an AppBI email + password — it mints the PAT, connects the running session immediately, and saves it to .env. (health_check returns needs_pat until you do.)
3. Manually. AppBI UI → Settings → Personal Access Tokens → create one, then paste it into .env as APPBI_PAT=....

The token needs these scopes (the helpers grant them for you):

• data_sources — discover and create Google Sheets / file sources.
• datasets — create datasets, tables, the relationship model.
• explore_charts + dashboards — embedded dashboard screens.
• workboards (full) — build workboards, app users, public links, and create/manage delivery workspaces.

Register in an MCP client

Add to your client's MCP config (Claude Desktop claude_desktop_config.json, or .mcp.json for Claude Code). Adjust paths for your OS:

{
  "mcpServers": {
    "appbi-workboard": {
      "command": "D:\\Appv2\\appbi-ai\\Skill-AppBI\\appbi-workboard-mcp\\.venv\\Scripts\\python.exe",
      "args": ["D:\\Appv2\\appbi-ai\\Skill-AppBI\\appbi-workboard-mcp\\appbi_workboard_mcp.py"],
      "env": {
        "APPBI_BASE_URL": "http://localhost:8000",
        "APPBI_PAT": "<your-token>",
        "APPBI_MCP_PROFILE": "all"
      }
    }
  }
}

Run setup-mcp.ps1 once first so .venv exists.

The journey (canonical workflow)

Stage	Do this
0 Source	list_data_sources; inspect with inspect_source_schema / list_gsheet_tabs + read_gsheet_rows. Create with create_google_sheets_source (run check_google_data_access first), create_manual_source_from_file, or create_manual_source.
1 Dataset	create_dataset -> add_table_to_dataset per table -> get_table_profile on each (this populates columns_cache). Date table via update_dataset settings. Optional update_table_description / update_dataset_dictionary.
2 Data Model	generate_dataset_model, then refine with suggest_dataset_model_join -> add_dataset_model_join. suggest_workboard_relationships gives lookup-shaped join hints for mini-app forms/tables.
3 Workboard	get_workboard_design_guide (full screen schema) -> author one bundle -> test_screen_js for computed columns -> validate_workboard_bundle -> apply_workboard_bundle(user_confirmed=true).
4 Share	audit_workboard; create_workboard_public_link (form/view URL) and/or deliver_workboard_to_workspace (full app behind app-user login); then run_workboard_runtime_smoke_test.

Profiles

Default APPBI_MCP_PROFILE=all exposes everything — testers need no config. Power users can shrink the surface (comma-combinable):

discover (read-only) · source · dataset · model · build · deliver

.\run-mcp.ps1 -Profile build          # author/validate/apply only
$env:APPBI_MCP_PROFILE = 'discover,build'; .\run-mcp.ps1

Bundle contract

get_workboard_design_guide() returns the live contract + the full current screen schema. The bundle:

{
  "workboard": {
    "name": "Inventory Demo",
    "slug": "inventory-demo",
    "dataset_id": 47,
    "primary_table_id": 101,
    "primary_key_columns": ["id"],
    "publish": true
  },
  "layout_json": { "screens": [], "mini_app_nav": { "items": [] } },
  "app_users": [],
  "webhooks": [],
  "workspace": {}
}

Screen kinds: form, table, doc, dashboard. A table screen uses its table spec (legacy list/grid are not valid). Screen schemas are strict — only the fields listed in the design guide are accepted.

Gotchas worth knowing (verified against the backend)

1. Google Sheets source_table_name is the tab name only — "DM_SanPham", never "<spreadsheet_id>.DM_SanPham".
2. columns_cache fills after profiling — call get_table_profile once on every newly added table before authoring model joins or screens against it.
3. Pass workboard.slug explicitly when delivering via a workspace — the backend does not auto-generate one, and workspace menus key by slug.
4. Public links require the owner PIN rotated off the default before create_workboard_public_link succeeds.

Hit an error while building? Want to extend the MCP?

See MAINTAINERS.md — the debug + upgrade guide:

• Mental model: the AppBI backend is the single gatekeeper; this MCP is thin tools + a design guide. Most "the MCP can't build X" issues are a design-guide gap, not missing code (because apply sends layout_json straight through).
• Which layer failed — MCP pre-check (validate_workboard_bundle) vs backend gate (the backend_error envelope with a Pydantic field path in detail) vs runtime (audit_workboard / smoke test) — and where each fix goes.
• The debugging loop (reproduce with validate, read the 422 detail, curl the backend with the same PAT, APPBI_MCP_LOG_LEVEL=DEBUG).
• The upgrade playbook — 3 cases (document a backend-supported field · relax a false pre-check · add a new tool) with exact edit locations, plus a test-before-ship checklist.
• A common-errors → cause → fix table.

Files

File	Role
appbi_workboard_mcp.py	Entry point — imports every stage module
appbi_wb_core.py	FastMCP, profiles, HTTP + multipart client, confirmation helpers
appbi_wb_source.py	Stage 0 — source discovery + Google Sheets/manual create
appbi_wb_dataset.py	Stage 1 — dataset, tables, profiling, descriptions
appbi_wb_model.py	Stage 2 — generate-model + relationships + lookup suggestions
appbi_wb_discovery.py	Dataset/Workboard/workspace reads + design-context aggregator
appbi_wb_build.py	Stage 3 — bundle guide, validation, one-confirm apply
appbi_wb_authoring.py	Stage 3 helpers — test-js, access audit, export, public links
appbi_wb_users.py	App-user maintenance
appbi_wb_webhooks.py	Doc-webhook maintenance + sync history
appbi_wb_workspace.py	Workspace delivery + runtime smoke test