flowpad-mcp 0.1.2 → 0.2.0

package/README.md

@@ -1,110 +1,91 @@
 # flowpad-mcp
 
-An [MCP](https://modelcontextprotocol.io) server that lets an external AI
-(Claude Desktop, Cursor, Claude Code) work with Flowpad: find a project, inspect
-and analyze its canvas, and edit nodes — all through flowpad-be's dedicated
-`/mcp/*` endpoints.
+Flowpad's [MCP](https://modelcontextprotocol.io) integration. One repo, **two
+servers** for two different jobs:
+
+|                          | **B — Hosted connector** (main)      | **A — Local validator** (this npm package)             |
+| ------------------------ | ------------------------------------ | ------------------------------------------------------ |
+| Transport                | Streamable HTTP at a URL             | stdio via `npx flowpad-mcp`                            |
+| Auth                     | OAuth sign-in (or an `fp_live_` key) | **none — keyless**                                     |
+| Canvas read/write (CRUD) | ✅ yes                               | ❌ never                                               |
+| Talks to flowpad-be      | ✅ (per-user, authed)                | ❌ (except one anonymous version check)                |
+| Tools                    | full toolset                         | `describe_engine`, `validate_design`, `preview_layout` |
+
+**Connect Claude to the hosted connector** to actually read and edit your canvas
+(Flowpad → **Settings → Integrations**). The **local validator** is an optional
+enhancer you add alongside it: it carries Flowpad's real layout engine
+(`flowpad-core`) on your machine so the AI can validate and preview a design
+locally — instantly, free, offline — before it writes anything through the
+connector. Fewer wrong edits, fewer round-trips.
 
-## How it works
-
-```
-Claude Desktop / Cursor / CLI ──MCP──▶ flowpad-mcp ──HTTP /mcp/*──▶ flowpad-be
-        (the AI / brain)              (this relay)              (your backend)
 ```
-
-This server is a thin relay. All canvas logic lives behind flowpad-be's
-`/mcp/*` facade: retrieval (outline/search/node) and analysis are computed
-server-side and returned as compact text, so the model's context stays bounded
-no matter how large the canvas is. Edits are saved via `PUT /mcp/projects/:id`
-with optimistic-concurrency `baseRevision`; AI-driven edits are delegated to the
-in-app AI (`POST /mcp/chat/message`), which computes node ids, bounds and layout.
-
-**Auth:** same user-auth (JWT) as the app, with its own entry point. Generate a
-per-user key from Flowpad (**Settings → Integrations**) and set it as
-`FLOWPAD_API_KEY` (looks like `fp_live_…`). The server exchanges it at
-`POST /mcp/auth/login` for a standard, expiring user JWT, then sends that as a
-Bearer token (re-logging in on expiry). flowpad-be resolves the key to your own
-account, so the agent acts as you. No account password lives in agent config; a
-key is revocable any time from the same screen.
-
-## Tools
-
-**Agentic tools** — let an external agent (Cursor / Claude / Antigravity) work on
-an arbitrarily large canvas the way it works on a big repo: navigate with cheap
-retrieval, read only what's relevant, make targeted edits. The MCP fetches the
-node list once (cached by revision) and returns only compact slices, so the
-model's context stays bounded no matter how big the project grows.
-
-| Tool              | Repo analogy | Purpose                                                                             |
-| ----------------- | ------------ | ----------------------------------------------------------------------------------- |
-| `get_outline`     | `ls -R`      | Depth-limited tree: ids, types, names, child counts.                                |
-| `search_nodes`    | `grep`       | Find nodes by name/description/type/parent (paginated).                             |
-| `get_node`        | `cat`        | One node's fields + subtree to a depth.                                             |
-| `analyze_project` | lint         | Canvas stats (counts, depth) + deterministic layout-overflow warnings.              |
-| `apply_edit`      | edit         | Targeted add/update/remove in one diff (OCC; conflicts surface, never force-write). |
-
-**Convenience tools**
-
-| Tool              | Purpose                                                  |
-| ----------------- | -------------------------------------------------------- |
-| `list_projects`   | List / search projects (id + name).                      |
-| `get_project`     | Show a project's revision and node summary.              |
-| `ai_edit_project` | One-shot natural-language edit → in-app AI → saved diff. |
-| `add_node`        | Deterministic single-node add (no AI).                   |
-
-## Setup
-
-No install needed — the config snippets below run the server via
-`npx -y @flowpad/mcp`. Just generate a key from **Settings → Integrations** and
-paste the snippet into your MCP host.
-
-For local development of this server:
-
-```bash
-cd flowpad-mcp
-npm install
-npm run build
-cp .env.example .env   # set FLOWPAD_API_URL + FLOWPAD_API_KEY
+                 ┌─ A: npx flowpad-mcp (local) ── flowpad-core engine, on your machine
+Claude / Cursor ─┤        validate · preview · describe   (keyless, no canvas access)
+                 └─ B: hosted URL connector ──HTTP──▶ flowpad-be  (auth + canvas CRUD)
 ```
 
-## Try it (local)
-
-1. Run flowpad-be locally (`yarn start:dev`, port 8080).
-2. `npm run inspect` — opens the MCP Inspector. Call `list_projects`, then
-   `analyze_project`, then `ai_edit_project`.
-
-## Use it in a client
+## A — the local validator (this package)
 
-The **same** stdio server works in all three. Pass env vars in the config.
-Point `FLOWPAD_API_URL` at your backend (`https://api.getflowpad.com` for the
-hosted app, or `http://localhost:8080` for local).
+Keyless. It never touches your account; it only runs the engine locally. Add it
+next to the hosted connector in your MCP host:
 
-### Claude Desktop — `claude_desktop_config.json`
+### Claude Desktop — `claude_desktop_config.json` / Cursor — `.cursor/mcp.json`
 
 ```json
 {
   "mcpServers": {
-    "flowpad": {
+    "flowpad-local": {
       "command": "npx",
-      "args": ["-y", "@flowpad/mcp"],
-      "env": {
-        "FLOWPAD_API_URL": "https://api.getflowpad.com",
-        "FLOWPAD_API_KEY": "fp_live_..."
-      }
+      "args": ["-y", "flowpad-mcp"]
     }
   }
 }
 ```
 
-### Cursor — `.cursor/mcp.json` (project) or global MCP settings
+### Claude Code (CLI)
+
+```bash
+claude mcp add flowpad-local -- npx -y flowpad-mcp
+```
+
+That's it — no key, no URL. (Advanced: set `FLOWPAD_API_URL` to point its
+best-effort "is my tool up to date?" check at a non-prod backend.)
 
-Same `mcpServers` block as above.
+**Tools**
 
-### Claude Code (CLI)
+| Tool              | Purpose                                                                                                            |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `describe_engine` | The exact node types, layout values and limits to design within.                                                   |
+| `validate_design` | Run the SAME engine rules the backend enforces on a planned diff — catch a malformed node/edge before you send it. |
+| `preview_layout`  | Compute where an auto-layout container's children land + flag overflow, before you write.                          |
+
+All three run entirely on the bundled `flowpad-core` (no network), so a passing
+`validate_design` means the backend won't reject the shape.
+
+## B — the hosted connector
+
+The channel that actually reads and writes the canvas, behind per-user auth. It
+runs the full toolset (retrieval, analysis, CRUD, templates, tasks) plus the same
+three local engine tools. Served over Streamable HTTP from `src/index.ts` →
+`src/http.ts`; deployed (not published to npm). Get its URL and sign in from
+Flowpad → **Settings → Integrations**.
+
+## Development
 
 ```bash
-claude mcp add flowpad \
-  --env FLOWPAD_API_URL=https://api.getflowpad.com \
-  --env FLOWPAD_API_KEY=fp_live_... \
-  -- npx -y @flowpad/mcp
+cd flowpad-mcp
+yarn install
+yarn dev        # A: the local stdio validator (src/local-index.ts)
+yarn dev:http   # B: the hosted HTTP server  (src/index.ts)
+yarn inspect    # open the MCP Inspector against A
+yarn validate   # tsc + eslint + prettier + tool-parity + version-sync
 ```
+
+- **A** entry: `src/local-index.ts` → `createLocalServer` (`src/local-server.ts`),
+  which registers `src/local-tools.ts`. Published as the bundled bin `dist/local.js`
+  (esbuild inlines `flowpad-core`, so the npx tool installs nothing).
+- **B** entry: `src/index.ts` → `startHttpServer` (`src/http.ts`) →
+  `createServer` (`src/server.ts`), which folds in the same `local-tools.ts` trio.
+- The MCP tool surface is mirrored from flowpad-be's tool catalog
+  (`src/generated/tool-catalog.json`); `scripts/check-tool-parity.ts` asserts both
+  the full (B) and local (A) surfaces against it.