Imported from joachimBrindeau/budibase-mcp (.claude/skills/budibase/SKILL.md). Install upstream with npx skills add joachimBrindeau/budibase-mcp --skill budibase. Copyright stays with the author.

Budibase Data Management

Quick Start

Every operation follows: Knowledge → Route → Execute → Report → Learn.

0. Knowledge: Read knowledge files → resolve app/table/entity from cache
1. Route: Match intent to tool (see table below) → load domain reference
2. Execute: Call tool with correct IDs → confirm if destructive
3. Report: Return result → include rollback if needed
4. Learn: Persist any newly discovered structure to knowledge files

Phase 0: Knowledge

Before any tool call, load persistent knowledge to skip redundant discovery.

Read Path

1. Read .claude/skills/budibase/knowledge/_index.yaml
   - If missing → run Bootstrap (see below)
   - If budibase_url != BUDIBASE_URL from environment → delete all knowledge, run Bootstrap
2. Match user intent to an app + table:
   - By explicit app name ("in CRM") → direct lookup in _index.yaml
   - By entity name ("Elicit") → scan table files in app folder for entity match
   - By alias → check aliases in _index.yaml
   - By table name ("Clients table") → check tables map in _index.yaml
   - Ambiguous match → check defaults in _index.yaml, or ask user
3. Get appId + tableId directly from _index.yaml (tables map has IDs)
4. If app folder doesn't exist → run Hydrate App (creates all table files with schemas)
5. Read knowledge/{app-folder}/{table-name}.yaml for entities, workflows, schema details
6. Only call discovery tools for paths not in _index.yaml

Bootstrap

Triggered when _index.yaml doesn't exist, or user says "rebuild knowledge" / "forget everything":

1. Call discover_apps(includeTables: true)
2. Write _index.yaml:
   - bootstrapped date
   - Each app: name, folder slug, appId, aliases (empty), tables map (name → tableId)
   - No app folders or table files yet (created on first access via Hydrate)

Slugification: name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')

Hydrate App

Triggered the first time an app is referenced (app folder doesn't exist):

1. Call get_table_schema for EACH table in the app (use tableIds from _index.yaml)
2. Create app folder: knowledge/{app-slug}/
3. Write per-table YAML files: knowledge/{app-slug}/{table-name}.yaml
   - table section: name, tableId, primaryDisplay (from schema response)
   - schema section: all fields with name, type, link target
   - entities, workflows sections: empty (filled incrementally)

Cost: N API calls (one per table). Done once per app, on first access.

Knowledge File Structure

knowledge/
  _index.yaml                    # App router + table lists
  {app-slug}/                    # One folder per app
    {table-name}.yaml            # One file per table

_index.yaml:

bootstrapped: "2026-02-03"

apps:
  klarc:
    folder: klarc
    appId: app_abc123
    aliases: []
    tables:
      comptes: ta_xyz789
      contacts: ta_abc123
      dossiers: ta_def456

defaults:
  Contacts: klarc

Per-table file (e.g., klarc/comptes.yaml):

table:
  name: comptes
  tableId: ta_xyz789
  primaryDisplay: nom

schema:
  fields:
    nom: { type: string, primary: true }
    notes: { type: longform }
    status: { type: options }
    contacts: { type: link, target: contacts }

entities:
  ELICIT PLANT:
    rowId: ro_def456
    matchField: nom
    matchValue: ELICIT PLANT
    _lastSeen: "2026-02-03"

workflows:
  add_comment:
    trigger: "add comment/note on [entity]"
    steps: "resolve entity → update_record, append to notes field"
    field: notes

Size budget (~3KB soft cap per table file):

Entity Resolution

When operating on a named entity (e.g., "update Elicit's notes"):

1. Check knowledge entities section
   ├── Found → use rowId directly (0 API calls)
   │   ├── Success → done
   │   └── 404 → go to step 2
   └── Not found → go to step 2

2. Query by primaryDisplay field
   → query_records with filter: { equal: { [primaryDisplay]: "Elicit" } }
   ├── 1 result → use it, save to knowledge entities section
   ├── 0 results → remove stale entry if existed, report "not found"
   └── N results → present options to user, save chosen one

Ambiguity Resolution

When an entity or table name exists in multiple apps:

1. User mentions app explicitly ("in CRM") → use that app
2. Check _index.yaml defaults → use stored preference
3. Only one app has it → no ambiguity
4. Multiple apps, no default → ask user, store choice in defaults

MCP Resources

Read these resources for context when knowledge files are insufficient:

Intent Router

Match user intent directly to tool. Read the domain reference before calling.

For multiple records, always prefer batch tools over looping single-record tools.

Field Selection Rule

Always pass fields to query_records. Check the table's knowledge file for available columns and only request those relevant to the task. This drastically reduces token usage.

1. Read knowledge/{app}/{table}.yaml → get schema fields
2. Pick only fields the user needs (+ primaryDisplay for display)
3. Pass fields: ["field1", "field2"] — _id is always included automatically
4. Use fetchAll: true when the task needs complete data (analytics, exports, bulk ops)
5. Use default pagination (no fetchAll) when browsing/previewing

Example — user asks "list all active dossiers":

{
  "appId": "klarc",
  "tableId": "dossiers",
  "query": { "equal": { "statut": "Actif" } },
  "fields": ["nom", "statut"],
  "fetchAll": true
}

Domains (MECE)

Safety Protocol

Safe (execute immediately): All reads, creates, transforms, queries.

Confirm required (preview first): Updates, deletes, bulk mutations, publish/unpublish.

1. Preview: Show what changes (current → new, or records to delete)
2. Ask: "This will [action] [N] records in [Table]. Proceed?"
3. Execute: Only after explicit "yes"
4. Report: Summary + rollback guidance

Phase 5: Learn

After executing a tool, persist newly discovered structural data to knowledge files.

Write Triggers

NOT triggered by: query_records, get_row, aggregate_data, transform_records, batch ops. These return record data, not structural data.

Write Procedure

1. Read the target table YAML file
2. Merge new data into the relevant section
3. If entities section exceeds ~20 entries, drop the oldest by _lastSeen
4. Write the full file back (not append — prevents corruption)
5. If new app/table encountered, update _index.yaml and create files

Self-Healing

When a tool call fails due to stale knowledge:

Knowledge Management

Workflow Recipes

Import CSV Data

1. Knowledge: resolve appId + tableId from knowledge
2. get_table_schema → validate CSV columns match fields (Learn: save schema)
3. batch_create_records → import with continueOnError: true
4. Report: created count, any failures

Clean and Export Data

1. Knowledge: resolve appId + tableId from knowledge
2. query_records → fetchAll: true, fields: [relevant columns]
3. transform_records → apply formatting (trim, uppercase, dates)
4. convert_data_format → export to csv/json/markdown

Bulk Update with Conditions

1. Knowledge: resolve appId + tableId from knowledge
2. query_records → fields: [primaryDisplay], fetchAll: true (preview count)
3. Show user: "[N] records match. Will set [field] to [value]."
4. bulk_query_and_process → operation: "update", updateData: {...}

Migrate Records Between Tables

1. Knowledge: resolve source + target appId/tableId
2. query_records → fetchAll: true, fields: [columns needed for target]
3. transform_records → reshape fields if schemas differ
4. batch_create_records → insert into target table
5. (optional) batch_delete_records → remove from source after confirm

ID Formats

Table names auto-resolve: pass "Customers" or "ta_abc123" interchangeably.

Relationships

Link fields store row ID arrays: ["ro_xxx", "ro_yyy"].

• Field type link with relationshipType: one-to-many, many-to-one, many-to-many
• tableId on link field = related table
• Pass { "linkField": ["ro_id1", "ro_id2"] } in record data

Error Handling

All responses: { success, data, message }.

Batch responses: { success, partialSuccess, totalRequested, totalSuccessful, totalFailed, errors[] }.

• success=true only when ALL items succeed
• partialSuccess=true when some succeed and some fail

Errors include recovery hints suggesting next tools:

• 401/403 → "Try: check_connection"
• 404 → "Try: list_applications or list_tables to find valid IDs"
• 429 → "Reduce batch size/concurrency"
• 5xx → "Try: check_connection"

On failure: check knowledge files for stale IDs, validate field names via get_table_schema, report partial successes for batch ops.