softr-vibe-coding 1.3.4 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to this skill are documented here. Versions follow [Semantic
 
 Entries from 1.3.1 onward are generated automatically from git commit subjects between version bumps (see `.github/workflows/publish.yml`). Entries before 1.3.1 were backfilled by hand from the existing commit history.
 
+## [1.4.0] - 2026-05-21
+- Document Softr Database MCP server — add references/softr-database-mcp.md (sibling to references/airtable-automations.md) covering connection, OAuth + PAT auth, Claude Code install, three permission scopes, 20 tools, why-it-matters for Vibe Coding, and the Softr-DB-only scope limitation; leave a short pointer in datasources/softr-database.md; promote MCP to option 1 for Softr DB field-ID discovery in datasources/fields.md; update SKILL.md Reference Guides table; add README TL;DR bullet, "What's Included" tree entry, and overview.md Key Concepts note; bump to 1.4.0
+
 ## [1.3.4] - 2026-05-21
 - Use dynamic shields.io npm badge for version; bump to 1.3.4
 

package/README.md

@@ -22,6 +22,7 @@ This Claude skill teaches Claude Code how to generate complete, polished Softr V
 - **Self-validation** — Claude checks for Softr bundler compatibility (no optional chaining, correct imports, container wrappers, `getFieldValue()` wrapping, hooks ordering) before delivering code
 - **Premium visual baseline** — Every block ships polished from v1: gradient backgrounds, card elevation, loading skeletons, empty states, error states
 - **Debug utilities** — Field Inspector, API Response Inspector, and User Inspector blocks for diagnosing data source and permissions issues
+- **Softr Database MCP integration** — when the [official Softr MCP server](https://docs.softr.io/mcp-server) is installed (`claude mcp add --transport http softr https://mcp.softr.io/mcp`), Claude reads Softr DB schema, field IDs, and dropdown option UUIDs directly — no more pasting `tablespace-with-tables` JSON. See `references/softr-database-mcp.md`.
 
 ---
 
@@ -177,6 +178,10 @@ softr-vibe-coding/
 │   │                                 # Scripting Extension, cross-table cascades,
 │   │                                 # batch update gotchas, field-ID discipline,
 │   │                                 # Airtable formulas
+│   ├── softr-database-mcp.md         # Softr Database MCP server (sibling to
+│   │                                 # datasources/softr-database.md; AI-assisted
+│   │                                 # schema discovery, field-ID lookup, OAuth
+│   │                                 # install, scope limitations)
 │   ├── advanced-integrations.md      # Shadow DOM CSS isolation (69 lines)
 │   │                                 # Leaflet, Mapbox, TinyMCE, Quill, FullCalendar
 │   ├── anti-patterns.md              # Categorized violation catalog (86 lines)

package/SKILL.md

@@ -84,7 +84,7 @@ When the user describes their block, figure out which of these areas apply and a
 
 - **Data source type**: Is it Airtable, Softr Database, REST API, or another source? This determines the data fetching approach. **Load the relevant data source guide** from the [datasources/](datasources/) directory before writing code.
 - **Data source fields**: For Airtable/Softr Database, you need actual field IDs. For REST APIs, you access the raw API response directly. If the user doesn't know field IDs:
-  - For **Softr Database**, ask the user to paste the `tablespace-with-tables` network response (DevTools -> Network -> filter that string while on Studio's Data tab). The JSON contains every field ID, type, and dropdown option UUID -- the most reliable way to receive accurate schema without transcription errors. See [datasources/fields.md](datasources/fields.md#field-inspector-block).
+  - For **Softr Database**, the cleanest path is the **Softr Database MCP server** — ask whether they have it installed (`claude mcp list` shows it as `softr` or similar). If yes, query schema directly with the MCP tools instead of asking for paste-ins. If no, fall back to asking them to paste the `tablespace-with-tables` network response (DevTools -> Network -> filter that string while on Studio's Data tab) — the JSON contains every field ID, type, and dropdown option UUID. Optionally tell them they can install the MCP once with `claude mcp add --transport http softr https://mcp.softr.io/mcp` for future sessions. Full MCP details in [references/softr-database-mcp.md](references/softr-database-mcp.md); fallback paste-in workflows in [datasources/fields.md](datasources/fields.md#field-inspector-block).
   - For **Airtable** and other sources where empty `q.select({})` works, suggest the Field Inspector block.
 - **Brand colors**: Already resolved in Step 1 (Detect the brand source). Don't re-ask. The brand source is one of:
   - **Project's `./DESIGN.md`** (recommended for client work — produced by the `building-design-md` skill)
@@ -154,6 +154,7 @@ For advanced patterns beyond data fetching, load the relevant reference when the
 | Quick syntax check — import paths, hook signatures, mutation call shapes, field mapping | [references/quick-reference.md](references/quick-reference.md) |
 | Small reusable patterns — `localStorage` cross-page state, clipboard copy button | [references/common-patterns.md](references/common-patterns.md) |
 | Writing Airtable Automation Scripts / Scripting Extension scripts / Airtable formulas — companion to Softr blocks for cross-table cascades and computed values | [references/airtable-automations.md](references/airtable-automations.md) |
+| AI-assisted Softr DB schema discovery / field-ID lookup / record reads via the official Softr MCP server (sibling to the in-block `useRecords` workflow) | [references/softr-database-mcp.md](references/softr-database-mcp.md) |
 
 ## Code Structure
 

package/datasources/fields.md

@@ -109,17 +109,17 @@ export default function Block() {
 
 **For Softr Database, find field IDs via:**
 
-1. **Inline in Studio (one field at a time)** -- in the Data tab, click a field's name to open its edit drawer. The field ID appears next to the "Field name" label (e.g. `ID: 37fts`). Fastest for spot-checking a single field.
+1. **Softr Database MCP server (recommended for AI-assisted workflows)** -- if you're collaborating with an AI assistant (Claude Code, Claude Desktop, Cursor, ChatGPT, Mistral) to write Vibe Coding blocks, the official Softr MCP server is the cleanest path. The AI calls schema/list-fields tools directly against your workspace and reads back every field's `id`, `name`, `type`, and dropdown option UUIDs -- no copy-paste, no transcription errors. Full setup, scopes, and scope limitations (Softr DB only -- does NOT cover Airtable / external sources) in [../references/softr-database-mcp.md](../references/softr-database-mcp.md).
 
-2. **Network inspector (full schema in one shot)** -- in Studio's Data tab with browser DevTools open, filter Network requests by `tablespace-with-tables`. The Response JSON contains every table's complete schema, including:
+2. **Network inspector (full schema in one shot, no MCP needed)** -- in Studio's Data tab with browser DevTools open, filter Network requests by `tablespace-with-tables`. The Response JSON contains every table's complete schema, including:
    - Each field's `id`, `name`, `type`, and `options`
    - For dropdown / SELECT fields: the full `choices` array with every option's `id` (UUID), `label`, and `color`
 
-   Use this when scaffolding a block that needs many field IDs at once, or to look up dropdown option UUIDs needed for write payloads.
+   Use this when scaffolding a block that needs many field IDs at once, or to look up dropdown option UUIDs needed for write payloads. **When working with an AI assistant without the MCP installed**, paste this JSON response into the chat -- second-best way to share accurate field IDs and dropdown UUIDs in one shot.
 
-   **Recommended for AI-assisted workflows:** when collaborating with an AI assistant (Claude, Cursor, ChatGPT, etc.) to write a Vibe Coding block, paste this JSON response into the chat. It is the most reliable way to share accurate field IDs and dropdown UUIDs -- it eliminates transcription errors and gives the AI everything it needs in one shot (field IDs, types, options, dropdown choices). Always prefer this over verbally describing fields or naming them by display label.
+3. **Inline in Studio (one field at a time)** -- in the Data tab, click a field's name to open its edit drawer. The field ID appears next to the "Field name" label (e.g. `ID: 37fts`). Fastest for spot-checking a single field.
 
-3. **Softr Database REST API with `fieldNames=true`** -- runtime inspection from inside a Vibe Coding block (internal-portal blocks only, since this exposes a PAT in client code):
+4. **Softr Database REST API with `fieldNames=true`** -- runtime inspection from inside a Vibe Coding block (internal-portal blocks only, since this exposes a PAT in client code):
 
 ```jsx
 import { useEffect, useState } from "react";

package/datasources/overview.md

@@ -32,6 +32,7 @@
 - Data is connected to **dynamic blocks** (List, Grid, Table, Kanban, Chart, Form, etc.) in the Softr Studio.
 - **Multiple data sources** can coexist in a single Softr app, even on the same page.
 - Softr IP addresses to whitelist for secured databases: `3.120.79.212`, `3.123.159.186`, `52.58.246.121`
+- **AI-assisted schema discovery via MCP:** Softr Database is the only source with a first-party MCP server (`https://mcp.softr.io/mcp`). When installed, the AI reads schema and field IDs directly from your workspace -- no manual paste-in. External sources still need the manual workflows in [fields.md](fields.md). See [softr-database.md](softr-database.md#ai-assisted-workflows-softr-database-mcp-server).
 
 ## User Sync Availability
 

package/datasources/softr-database.md

@@ -6,6 +6,10 @@ Softr's native built-in database. No external account or integration required. A
 ## Connection Setup
 No setup needed. Softr Database is available by default in every Softr app. Create tables directly from the Softr admin dashboard under the "Data" section. Import data via CSV, one-click migration from Airtable, or AI-assisted table generation.
 
+## AI-Assisted Workflows
+
+Softr publishes an official MCP server (`https://mcp.softr.io/mcp`) that lets the AI read Softr DB schema and field IDs directly — eliminating the manual "paste `tablespace-with-tables` JSON" step. For setup, scopes, the 20 tools, and the limitation that this only covers Softr DB (not external sources), see [../references/softr-database-mcp.md](../references/softr-database-mcp.md).
+
 ## Vibe Coding Field IDs
 Field IDs are short alphanumeric codes (e.g., `"xgETy"`, `"TLhWF"`). These codes are NOT human-readable names.
 
@@ -17,7 +21,13 @@ q.select({ name: "xgETy" })
 q.select({ name: "First Name" })
 ```
 
-Find field IDs by clicking a field's name in the Data tab (the ID is shown in the field-edit drawer), or via the network inspector technique (DevTools -> Network -> filter `tablespace-with-tables` for the full schema including dropdown option UUIDs). The network inspector method is recommended when working with an AI assistant -- pasting that JSON into the chat eliminates transcription errors. See [fields.md](fields.md#field-inspector-block) for both approaches plus a runtime REST API method. The generic Field Inspector pattern with empty `q.select({})` does NOT work for Softr Database.
+Find field IDs in this order of preference:
+
+1. **Softr Database MCP** (recommended when working with an AI assistant) — the AI calls schema/list-fields tools directly. See [../references/softr-database-mcp.md](../references/softr-database-mcp.md).
+2. **Network inspector** — DevTools -> Network -> filter `tablespace-with-tables` for the full schema including dropdown option UUIDs. Paste the JSON into chat to share with an AI when the MCP isn't installed.
+3. **Inline in Studio** — click a field's name in the Data tab; the ID appears in the field-edit drawer.
+
+The generic Field Inspector pattern with empty `q.select({})` does NOT work for Softr Database — see [fields.md](fields.md#field-inspector-block).
 
 ## Supported Fields
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "Claude Code skill for generating production-ready Softr Vibe Coding blocks (JSX). Installs into ~/.claude/skills/ and auto-updates on each Claude Code session.",
   "bin": {
     "softr-vibe-coding": "./bin/cli.js"

package/references/softr-database-mcp.md

@@ -0,0 +1,59 @@
+# Softr Database MCP Server
+
+Out-of-band integration for AI-assisted Vibe Coding workflows. The MCP server lets the AI assistant (Claude Code, Claude Desktop, Cursor, ChatGPT, Mistral) read schema, list field IDs, query records, and write data directly into Softr Databases — eliminating the manual "paste `tablespace-with-tables` JSON" step and removing transcription errors on field IDs and dropdown option UUIDs.
+
+**This file is a sibling concern to [../datasources/softr-database.md](../datasources/softr-database.md), which covers in-block data fetching (`useRecords` + `q.select()`).** The MCP runs at chat-build time, not inside the block. Same parallel as [airtable-automations.md](airtable-automations.md) sits next to [../datasources/airtable.md](../datasources/airtable.md).
+
+## Connection
+
+- **Server URL:** `https://mcp.softr.io/mcp`
+- **Transport:** streamable HTTP
+- **Auth:** OAuth (pre-configured for Claude / Cursor / ChatGPT / Mistral) or Personal API Token (`Settings → API Tokens` in Softr)
+- **Official docs:** https://docs.softr.io/mcp-server
+
+## Install (Claude Code)
+
+```bash
+claude mcp add --transport http softr https://mcp.softr.io/mcp
+```
+
+Then start a new Claude Code session and run `/mcp` to complete the OAuth authorization in the browser. See [the Softr docs](https://docs.softr.io/mcp-server) for Cursor / ChatGPT / Mistral / custom client setup.
+
+## Permissions (three granular scopes)
+
+Grant only what you need:
+
+| Scope                       | Use case for Vibe Coding                                              |
+|-----------------------------|-----------------------------------------------------------------------|
+| `databases.records:read`    | AI discovers field IDs, dropdown UUIDs, verifies value shapes         |
+| `databases.records:write`   | AI mutates live data (e.g. seeding test records, bulk updates)        |
+| `databases.schema:write`    | AI provisions databases / tables / fields for you                     |
+
+For block-writing workflows, **read scopes are the most valuable** — they cover the AI's schema-discovery needs (the bottleneck the MCP solves) without any blast-radius into live data. Add write scopes only when you want the AI to mutate records; schema-write only when you want it to provision tables.
+
+## Tools available (20 total)
+
+- **Databases (4):** list / get / create / update
+- **Tables (8):** list tables, list fields, list views, get table schema, create / update tables, create / update fields
+- **Records (8):** list / get / create (batch ≤ 100) / update / delete + filter-based and view-filtered search
+
+## Why this changes Vibe Coding workflows
+
+Without the MCP, the AI needs schema shared manually — either paste `tablespace-with-tables` network JSON or describe fields by name. Both are slow, and verbal-name approaches lose dropdown option UUIDs entirely without a second copy step.
+
+With the MCP installed, you can ask things like:
+
+- "List every field on the `Wigs` table with id, name, type, and dropdown options."
+- "What's the option id for `Wigs.Payment status` = 'Partially paid'?"
+- "Show me 3 sample records from `Wig Services` so we know the value shapes."
+- "Verify the field id I used for `q.select({ status: 'sel...' })` exists on this table."
+
+The AI then writes `q.select()` keys and write payloads against the live schema, eliminating an entire class of "field id typo" / "wrong option uuid" bugs.
+
+## Scope: Softr Database only
+
+The MCP server exposes Softr's **native** databases only. It does NOT proxy external sources (Airtable, Google Sheets, HubSpot, Notion, Xano, etc.) — those still need the schema-discovery workflows documented in [../datasources/fields.md](../datasources/fields.md#field-inspector-block) (Field Inspector block, vendor APIs, network inspector paste, etc.). If your Softr app blends Softr DB with external sources, the MCP helps only with the Softr DB tables.
+
+## When the MCP is not installed
+
+If the user hasn't installed the MCP (and doesn't want to right now), fall back to the schema-sharing methods documented in [../datasources/fields.md](../datasources/fields.md#field-inspector-block) — primarily the `tablespace-with-tables` network paste, which gives the AI everything it needs in one shot.