@forhuman/flowmcp 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to flowmcp
+
+Thanks for helping improve flowmcp.
+
+## Layout
+
+```
+bin/flowmcp   dispatcher — resolves symlinks, sources lib/bootstrap.sh, routes to commands/
+lib/                     shared functions: paths, secrets, profiles, client-config merge, audit log, UI
+commands/                one script per verb, self-bootstrapping (works sourced or run standalone)
+```
+
+Every `commands/*.sh` starts with the same line so it works whether it's
+`source`d by the dispatcher or shelled out to directly (e.g. `debug.sh`
+calling `test.sh`):
+
+```bash
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../lib/bootstrap.sh"
+```
+
+## The one hard rule
+
+**No command may accept a token as a CLI argument or print one, ever.**
+`secret-set`/`rotate` are the only commands that touch a token, and both
+refuse to run without a real interactive TTY (`read -s`, hidden input). If a
+change makes a token cross that boundary — as a function argument that isn't
+a `local`/`nameref` passed by name, in a log line, in an error message — it
+doesn't get merged, no exceptions.
+
+## Development
+
+Requires `bash`, `jq`, `curl`, and Node/`npx`.
+
+```bash
+npm link          # or: ln -s "$(pwd)/bin/flowmcp" /usr/local/bin/flowmcp
+flowmcp --help
+```
+
+Link it globally before calling anything done — running `bash bin/flowmcp`
+directly skips the symlink-resolution path (`bin/flowmcp`'s
+`while [ -h "$SOURCE" ]` loop) and the `bin` field a real install goes
+through, so it verifies less than it looks like it does.
+
+## Testing changes
+
+There is no test suite yet — verification is manual, against an isolated
+environment:
+
+```bash
+export WFW_HOME=/tmp/wfw-test-$$
+export HOME=/tmp/wfw-test-home-$$
+mkdir -p "$HOME"
+flowmcp add zzz-test-1 --label "Test Co"
+# ... exercise the command you changed ...
+rm -rf "$WFW_HOME" "$HOME"
+```
+
+**Always use an obviously-fake org name (`zzz-test-*`), never a name that
+might collide with a real client.** `install`/`remove`/`rename` resolve
+client config paths through the real `$HOME` by design (see
+`lib/clients.sh:wfw_client_config_path`) unless `HOME` is overridden as
+above — a name collision with a real org can silently repoint or delete a
+real entry in someone's real Claude Code/Desktop/Cursor config. See
+`friction.md` for the incident that made this rule non-optional.
+
+Before opening a PR, run every changed `commands/*.sh` through `bash -n` at
+minimum, and exercise the `--json` and (for `install`/`remove`/`rename`)
+`--dry-run` paths, not just the human-output path — they're separate code
+paths in every command that has them.
+
+## Adding a command
+
+1. Add `commands/<verb>.sh`, self-bootstrapping as above.
+2. Add it to the whitelist `case` in `bin/flowmcp` and to
+   `usage()`.
+3. Add it to `commands/schema.sh` — usage, whether it mutates, whether it
+   requires a TTY, whether it's destructive, and its JSON output shape.
+   `schema` is how an agent discovers the surface without parsing
+   `--help`; a command missing from it is invisible to that path.
+4. If it prints structured output, include `next_steps: [string]` when
+   there's an obvious follow-up command — that's the convention every other
+   command's JSON output follows.
+5. If it's read-only, no gate is needed. If it mutates a client config file
+   or a stored secret, give it `--dry-run`; if it's irreversible without a
+   backup, require an explicit `--yes` with no non-interactive default.
+
+## Fold friction back in
+
+If something in this doc, or an existing pattern in the code, turns out
+wrong for a case you're working, write it down in `friction.md` before you
+move past it. It's what keeps this file honest.
+
+## License
+
+MIT — contributions are accepted under the same license as the project.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webflow-workspaces contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# flowmcp
+
+Connect every client's Webflow account to your AI agent — one at a time,
+safely, without a token ever touching the conversation.
+
+If you run an agency, you likely need a separate Webflow connection per
+client. `flowmcp` is a CLI (+ a Claude Code skill) that manages all of them
+side by side: add a client in seconds, the token lives only in your OS
+keychain, and your agent can add/list/test/install connections on your
+behalf — but can never see, hold, or print the token itself.
+
+## Install
+
+```bash
+npm install -g @forhuman/flowmcp
+```
+
+Installs both `flowmcp` and the short alias `fmcp`. Requires
+`bash`, `jq`, `curl`, and Node/`npx`. On macOS the `security` CLI (ships with
+the OS) is used for keychain access; on Linux install `libsecret-tools`
+(Debian/Ubuntu: `apt install libsecret-tools`) for keychain support, or
+accept the `chmod 600` file fallback.
+
+## Quick start
+
+```bash
+fmcp connect acme --label "Acme Corp"
+# opens your browser -> client approves access -> Ctrl+C once connected -> done
+
+fmcp test acme
+fmcp install acme claude-code --scope project
+```
+
+No OAuth App to create, no client ID/secret to manage — `connect` shells out
+to [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) against Webflow's
+own hosted MCP server. No browser available (headless environment)? Use a
+manually-pasted token instead:
+
+```bash
+fmcp add acme --label "Acme Corp"
+fmcp secret-set acme     # run this yourself, in your own terminal — TTY only
+fmcp test acme
+fmcp install acme claude-code --scope project
+# restart the target app to pick up the new MCP server
+```
+
+The first time a human runs `flowmcp` interactively, it asks once whether to
+show help text in English or Español, and remembers it
+(`flowmcp lang es` changes it later; JSON output is unaffected either way).
+
+## What it does
+
+- Registers one **profile** per client (label, metadata — no secret).
+- Stores the actual token in your **OS keychain**, never in a client config
+  file, never in an agent's context.
+- Lets an AI agent drive the whole workflow (add, list, test, install,
+  debug) except the two commands that touch a token — those require you,
+  in your own terminal, by design.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `add <org> [--label NAME]` | Register org metadata (no secret) |
+| `secret-set <org>` | Interactively paste a token (TTY only) |
+| `rotate <org>` | Interactively replace a stored token (TTY only) |
+| `connect <org> [--label NAME]` | Add/reconnect an org via browser OAuth — no setup, needs the user present |
+| `list [--json]` | List orgs + last test status (no secrets) |
+| `inspect <org> [--live] [--json]` | Show profile detail; `--live` re-runs `test` first |
+| `test <org> [--json]` | Validate the stored credentials |
+| `install <org> <client> [--scope user\|project] [--force] [--dry-run] [--json]` | Merge an `mcpServers` entry into a client config |
+| `remove <org> --yes [--from client:scope]... [--dry-run] [--json]` | Delete profile + credentials, optionally strip client entries |
+| `rename <old-org> <new-org> [--dry-run] [--json]` | Rename an org — no re-login needed |
+| `debug <org> [--json]` | Diagnose profile/credential/network/config issues |
+| `schema` | Machine-readable reference of every command's usage and JSON output shape |
+
+Supported clients for `install`: `claude-code`, `claude-desktop`, `cursor`.
+
+## For agents
+
+Symlink or copy this repo into `.claude/skills/flowmcp/` (project-level) or
+`~/.claude/skills/flowmcp/` (user-level) — [`SKILL.md`](SKILL.md) at the repo
+root is the skill definition an agent reads. In short: run `fmcp schema`
+once per session instead of parsing `--help`, everything already prints JSON
+when stdout isn't a TTY, and `install`/`remove`/`rename` support `--dry-run`
+for anything you're not certain about.
+
+---
+
+## Technical details
+
+The sections below are for anyone integrating, auditing, or extending
+`flowmcp` — skip them if you just want to use the CLI.
+
+### How credentials stay out of client configs
+
+For `connect` (`mcp-remote`) orgs, `install` writes:
+
+```json
+{
+  "mcpServers": {
+    "webflow-acme": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.webflow.com/mcp", "--resource", "https://mcp.webflow.com/mcp"],
+      "env": { "MCP_REMOTE_CONFIG_DIR": "/Users/you/.flowmcp/mcp-remote/acme" }
+    }
+  }
+}
+```
+
+No credential of any kind is in that file — just a directory path.
+`mcp-remote` reads its own isolated session from that directory (and
+refreshes it) when the MCP client actually launches the server.
+
+For `secret-set` (PAT) orgs, `install` instead writes:
+
+```json
+{
+  "mcpServers": {
+    "webflow-acme": {
+      "command": "/path/to/flowmcp/commands/run-mcp.sh",
+      "args": ["acme"]
+    }
+  }
+}
+```
+
+`run-mcp.sh` is invoked by the MCP client itself (Claude Code / Claude
+Desktop / Cursor) when it starts the server — not by you or by an agent. At
+that point it looks up the token for `acme` from the keychain, exports it as
+`WEBFLOW_TOKEN`, and `exec`s `npx -y webflow-mcp-server@latest`. The token
+exists only in that child process's environment, for the lifetime of the
+MCP session.
+
+### JSON contract
+
+`list`/`inspect`/`test`/`debug`/`install`/`remove`/`rename` print JSON
+automatically whenever stdout isn't a real TTY (piped, redirected, or
+invoked by an agent's tool call) — `--json` only matters when you want
+machine output in your own terminal. JSON responses include a `next_steps`
+array naming the follow-up command, when there is an obvious one.
+
+`install`, `remove`, and `rename` are the only commands that touch a real,
+shared client config file (Claude Code/Desktop/Cursor) — the one place here
+where a wrong call has a real blast radius — so all three support `--dry-run`
+to preview the change before it's written, and `remove` requires an explicit
+`--yes` with no interactive fallback.
+
+### Storage layout
+
+```
+~/.flowmcp/
+  profiles/<org>.json       # metadata only: label, created_at, auth_method, last test result
+  mcp-remote/<org>/         # mcp-remote orgs: isolated session storage, owned by mcp-remote itself
+  secrets/<org>.token       # pat orgs: chmod 600, ONLY used when no OS keychain is available
+  audit/<YYYY-MM>.jsonl     # append-only action log — no credential values
+```
+
+Metadata and secrets are physically separate files/stores, so profile data
+can be freely read, printed, or committed to a private dotfiles repo without
+any risk of exposing a token — never put `secrets/` under version control
+(see `.gitignore`).
+
+### Security model — what this does and doesn't protect against
+
+- Protects against: tokens leaking into an AI agent's conversation
+  transcript/logs, tokens sitting in plaintext in versioned config files,
+  one client's token being usable to access another client's workspace.
+- Does not protect against: a compromised local machine (keychain access
+  is scoped to your OS user, not sandboxed further), a user manually
+  pasting a token into chat despite the tool telling them not to, or
+  `ps`-level visibility of `security add-generic-password -w <token>`'s
+  argument for the brief instant `secret-set` invokes it on macOS (an
+  inherent limitation of that CLI, not of this tool — it never happens
+  through anything that logs).
+- `connect` specifics: verified directly against `mcp.webflow.com`'s OAuth
+  metadata (`.well-known/oauth-authorization-server`) that it supports PKCE
+  (`S256`) and Dynamic Client Registration (`/oauth/register`, no
+  approval required) — confirmed with a real registration + full PKCE
+  token exchange. That's *specific to Webflow's hosted MCP server*, not
+  Webflow's classic Data API OAuth (`api.webflow.com/oauth`), which still
+  requires a `client_secret` with no PKCE alternative — which is why the
+  PAT path exists rather than a client_secret-based OAuth flow for that API.
+  The actual OAuth flow (PKCE, browser, token storage, refresh) is handled
+  by the third-party [`mcp-remote`](https://www.npmjs.com/package/mcp-remote)
+  tool, not by code in this repo — we only isolate each org's session into
+  its own `MCP_REMOTE_CONFIG_DIR` and check for the presence of a
+  `*_tokens.json` file as a "connected" signal, never reading its contents.
+
+### Extending to other MCP servers
+
+The design isn't Webflow-specific by construction: `lib/secrets.sh`,
+`lib/profiles.sh`, and `lib/clients.sh` generalize to any provider. The
+`connect`/`mcp-remote` path generalizes to any remote MCP server with a
+spec-compliant OAuth server (PKCE + Dynamic Client Registration); the PAT
+path (`run-mcp.sh`) generalizes to any local MCP server that authenticates
+via a single bearer-token env var. `$WFW_MCP_URL` in `lib/common.sh` and
+the `webflow-mcp-server` reference in `run-mcp.sh` are the two places with
+Webflow hardcoded today.
+
+## Links
+
+- [SKILL.md](SKILL.md) — the agent-facing manual this CLI ships with
+- [CONTRIBUTING.md](CONTRIBUTING.md) — layout, the one hard rule, how to test safely
+- [cases/flowmcp.md](cases/flowmcp.md) — how this CLI was built, what broke, what got rejected
+- Webflow MCP server: https://www.npmjs.com/package/webflow-mcp-server
+- mcp-remote: https://www.npmjs.com/package/mcp-remote
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — layout, the one non-negotiable rule
+about tokens, and how to test against an isolated environment without ever
+touching a real client's config.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+Built by [forhuman](https://www.forhuman.studio/).

package/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: flowmcp
+description: Manage multiple Webflow MCP server connections (one per client/org — e.g. an agency's own workspace plus each customer's) without ever letting an API token pass through agent context. Use when the user wants to add, list, inspect, test, install, rotate, remove, or debug a Webflow MCP connection, or asks to set up webflow-mcp-server for a new client, or reports an MCP connection to Webflow that isn't working.
+license: MIT
+---
+
+# flowmcp
+
+A CLI (`bin/flowmcp`) for managing one `webflow-mcp-server` connection
+per client/org, so an agency can hold separate Webflow API tokens for its own
+workspace and for each customer's workspace at once — installed into Claude
+Code, Claude Desktop, and/or Cursor.
+
+## Start here: `flowmcp schema`
+
+Run this once per session instead of parsing `--help`. It returns
+machine-readable JSON: every command's usage, whether it mutates state,
+whether it requires a real TTY, whether it's destructive, and the shape of
+its JSON output. Use it to confirm a command's flags exist before calling
+it, rather than guessing from this doc if the two ever drift.
+
+## The one rule that matters
+
+**You (the agent) must never see, hold, echo, or transmit a real Webflow API
+token.** Not as a Bash argument, not in a variable you print, not by asking
+the user to paste it into chat. The tool is built so you never need to:
+
+- `secret-set` and `rotate` are the *only* commands that touch a token, and
+  both refuse to run unless invoked from a real interactive TTY (`read -s`
+  hidden prompt). They will hard-fail if piped or run non-interactively —
+  that's intentional, not a bug to work around.
+- Every other command (`add`, `list`, `inspect`, `test`, `install`, `remove`,
+  `debug`) only ever touches metadata or a keychain *reference*. Run these
+  freely via your Bash tool.
+- `list`, `inspect`, `test`, `debug`, `install`, `remove`, and `rename` print
+  structured JSON automatically whenever stdout isn't a real TTY — which
+  includes every call you make through your Bash tool. You don't need to
+  pass `--json` yourself; parse the output directly instead of scraping the
+  colored human-readable text (that text only appears when a human is
+  watching a real terminal). Where there's an obvious follow-up action, the
+  JSON includes `next_steps: [string]` — prefer that over inferring the next
+  command yourself.
+- `install`, `remove`, and `rename` are the only commands that write to a
+  real, shared client config file. Pass `--dry-run` first when you're not
+  certain what a call will change, and show the user the diff before
+  re-running for real — this matters more than it sounds: a test-org name
+  that collides with a real org's name can silently repoint or delete a real
+  entry (see `friction.md` in the repo for the incident that made this a
+  standing rule, not a suggestion).
+- `install` never writes a literal token into a client's config file. It
+  points the `command` field at `commands/run-mcp.sh <org>`, which looks the
+  token up from the OS keychain (or the chmod-600 file fallback) at the
+  moment the MCP client actually launches the server — long after your
+  session has ended.
+
+If a user asks you to "just paste the token in" or run `secret-set` for
+them, don't. Tell them to run it themselves, in their own terminal, and
+give them the exact command. Do not offer to run it "on their behalf" via
+your Bash tool even if they insist — the TTY guard will reject it anyway,
+but the point is to not try.
+
+## Two ways to connect an org — prefer `connect`
+
+There are two paths to get a client's Webflow credentials registered.
+**Prefer `connect` whenever a browser is available** — it's the one
+non-technical users can do themselves with zero copy/paste and zero setup.
+Fall back to the PAT path (`add` + `secret-set`) only for headless/remote
+environments where no browser can be opened.
+
+### `connect` (preferred, no setup required)
+
+```
+flowmcp connect <org> --label "Acme Corp"
+```
+
+You can run this yourself, but it needs the user physically present: it
+runs `npx mcp-remote` against Webflow's own hosted MCP server
+(`mcp.webflow.com`), which opens a real browser, the client logs into
+their own Webflow account and clicks approve, and the session is saved to
+disk automatically. There is **no one-time app-registration step anymore**
+— Webflow's hosted OAuth server supports Dynamic Client Registration, so
+`mcp-remote` registers itself on the fly. No token ever touches your Bash
+tool calls, stdout, or the conversation — you only see "connected" or
+"failed", never a credential.
+
+Because it needs a live Ctrl+C from the user once they see "connected" in
+the output, tell them to run it themselves in their own terminal if you're
+not driving an interactive session with them watching.
+
+### PAT path (fallback): `add` + `secret-set`
+
+1. `flowmcp add <org> --label "Acme Corp"` — you can run this.
+   Registers profile metadata only.
+2. Tell the user, verbatim, to run in their own terminal:
+   `flowmcp secret-set <org>`
+   Do not run this yourself. Do not ask them to paste the token into chat.
+
+### Then, either path:
+
+3. Verify with `flowmcp test <org>` — you can run this; it hits
+   the real Webflow API and reports back scopes/site count without ever
+   printing the token.
+4. Install into whichever client(s) the user wants:
+   `flowmcp install <org> claude-code --scope project`
+   (or `claude-desktop` / `cursor`, `--scope user`). This merges into the
+   existing config — it will not clobber other MCP servers already there,
+   and refuses to overwrite an existing `webflow-<org>` entry unless you
+   pass `--force` (confirm with the user before using `--force`).
+5. Tell the user to restart the target client to pick up the new server.
+
+## Workflow: something's not connecting
+
+Run `flowmcp debug <org>`. It branches on the org's
+`auth_method` (`mcp-remote` or `pat`) and checks the right things for each:
+profile exists, credentials exist (session file or keychain), the relevant
+npm package (`mcp-remote` or `webflow-mcp-server`) is resolvable, a
+credential check (reusing `test`), and whether known client config files
+are valid JSON and contain the `webflow-<org>` entry. Read its output back
+to the user — it never prints a token, so its full output is always safe
+to relay verbatim.
+
+Common causes:
+- `mcp-remote` orgs: no saved session → tell the user to run
+  `flowmcp connect <org>` themselves. `test`/`debug` only check
+  that a session was *saved*, not that it's still valid — an expired
+  session refreshes or re-prompts automatically the next time a real
+  client connects, so don't over-interpret an "ok" here as a guarantee.
+- `pat` orgs: HTTP 401 → token invalid/revoked/expired → tell user to run
+  `flowmcp rotate <org>` themselves. HTTP 403 → token valid but
+  missing scopes. HTTP 000 → network/DNS/proxy issue, not a token problem.
+- client config exists but has no `webflow-<org>` entry → `install` wasn't
+  run yet, or was run against a different scope/client than the user
+  expects (check `--scope user` vs `--scope project`, and which client).
+
+## Workflow: removing or rotating a client
+
+- Rotate: PAT orgs — tell the user to run `flowmcp rotate <org>`
+  themselves, same TTY-only rule as `secret-set`. `mcp-remote` orgs don't
+  need manual rotation — just re-run `connect <org>`, which overwrites the
+  saved session.
+- Remove: `flowmcp remove <org> --yes [--from client:scope]...`
+  is destructive (deletes the profile and the stored credentials — token
+  or saved session, whichever applies) — confirm with the user before
+  running it, and pass `--from claude-code:project` etc. for each client
+  config you should also strip the entry from.
+
+## Command reference
+
+```
+flowmcp add <org> [--label "Name"]
+flowmcp secret-set <org>                 # human-only, TTY required
+flowmcp rotate <org>                     # human-only, TTY required
+flowmcp connect <org> [--label "Name"]   # opens a browser, needs the user present
+flowmcp list [--json]
+flowmcp inspect <org> [--live] [--json]
+flowmcp test <org> [--json]
+flowmcp install <org> <client> [--scope user|project] [--force] [--dry-run] [--json]
+                                                     # client: claude-code | claude-desktop | cursor
+flowmcp remove <org> --yes [--from client:scope]... [--dry-run] [--json]
+flowmcp rename <old-org> <new-org> [--dry-run] [--json]
+flowmcp debug <org> [--json]
+flowmcp schema                           # always JSON — run this first
+flowmcp lang [en|es] [--json]            # view/change human --help language, never affects JSON
+```
+
+`--json` is implicit whenever stdout isn't a TTY, so you (the agent) get it by
+default — the flag exists for a human who wants machine output in their own
+terminal. `schema` is always JSON regardless of TTY, since it's meant to be
+run by an agent at session start.
+
+## Storage layout (for context, not something you normally touch directly)
+
+- `~/.flowmcp/profiles/<org>.json` — non-sensitive metadata only
+  (label, created_at, `auth_method`, secret backend, last test
+  result/scopes/error). Safe to `jq`/`cat`/show the user in full.
+- `mcp-remote` orgs: `~/.flowmcp/mcp-remote/<org>/` — an
+  isolated `MCP_REMOTE_CONFIG_DIR` per org, owned and read entirely by the
+  third-party `mcp-remote` tool. We only ever check whether a `*_tokens.json`
+  file exists in there (`wfw_mcp_remote_connected`) — never read its
+  contents.
+- `pat` orgs: OS keychain first (`security` on macOS, `secret-tool`/libsecret
+  on Linux), falling back to `~/.flowmcp/secrets/<org>.token` at
+  `chmod 600` only when no keychain is available (e.g. a headless
+  container). Never read this file directly — always go through `test`,
+  `inspect`, or `debug`, which are designed not to leak it.
+- `~/.flowmcp/audit/<YYYY-MM>.jsonl` — append-only log of actions
+  with timestamps and results, never credential values. Useful if the user
+  asks "when did we last touch the Acme connection."
+
+## Why there's no more manual OAuth App setup
+
+Earlier versions of this tool required creating a Webflow OAuth App by hand
+(client_id/client_secret) because the classic Data API OAuth
+(`api.webflow.com/oauth`) has no PKCE support — a shared secret couldn't be
+shipped safely in an open-source package. That's no longer needed: Webflow
+now hosts its own MCP server at `mcp.webflow.com` with a modern OAuth
+server (PKCE + Dynamic Client Registration + refresh tokens), verified
+directly against the real endpoint. `connect` uses that via `mcp-remote`
+instead, which eliminates the manual setup step entirely. The tradeoff:
+`mcp-remote` orgs only work with Webflow's *hosted* MCP server (its access
+tokens don't work against `api.webflow.com` directly) and tokens expire
+hourly (refreshed transparently by `mcp-remote`/the MCP client, not by us).
+The PAT path still exists for headless environments or if raw Data API
+access is ever needed outside of `mcp.webflow.com`'s tool surface.
+
+## Extending to other MCP servers
+
+The design isn't hardcoded to Webflow: `lib/secrets.sh`, `lib/profiles.sh`,
+`lib/clients.sh` generalize to any provider. The `mcp-remote` path
+generalizes to any remote MCP server with a spec-compliant OAuth server
+(PKCE + DCR); the PAT path (`run-mcp.sh`) generalizes to any local MCP
+server taking a single bearer-token env var. `$WFW_MCP_URL` in
+`lib/common.sh` and the `webflow-mcp-server` reference in `run-mcp.sh` are
+the two places with Webflow hardcoded today.

package/bin/flowmcp

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# flowmcp — manage multiple Webflow MCP server connections
+# (one per client/org) safely, keeping tokens out of agent context.
+set -euo pipefail
+
+# Resolve through symlinks (e.g. npm link / global npm bin) to the real file.
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+export WFW_LIB_DIR="$REPO_ROOT/lib"
+export WFW_COMMANDS_DIR="$REPO_ROOT/commands"
+
+# shellcheck source=../lib/bootstrap.sh
+source "$WFW_LIB_DIR/bootstrap.sh"
+
+# wfw_cmd_line <name> <description> — pads <name> to a fixed width BEFORE
+# adding color codes, so visible columns line up regardless of ANSI escapes.
+wfw_cmd_line() {
+  local name="$1" desc="$2" padded
+  padded="$(printf "%-11s" "$name")"
+  printf "  %s%s%s %s\n" "$WFW_C_BOLD" "$padded" "$WFW_C_RESET" "$desc"
+}
+
+usage() {
+  wfw_banner
+  echo
+  echo "${WFW_C_DIM}$(wfw_t usage)${WFW_C_RESET}"
+  echo "  flowmcp <command> [args]"
+  echo
+  echo "${WFW_C_DIM}$(wfw_t onboarding)${WFW_C_RESET}"
+  wfw_cmd_line "connect" "$(wfw_t cmd_connect)"
+  wfw_cmd_line "add" "$(wfw_t cmd_add)"
+  wfw_cmd_line "secret-set" "$(wfw_t cmd_secret_set)"
+  wfw_cmd_line "rotate" "$(wfw_t cmd_rotate)"
+  echo
+  echo "${WFW_C_DIM}$(wfw_t daily_use)${WFW_C_RESET}"
+  wfw_cmd_line "list" "$(wfw_t cmd_list)"
+  wfw_cmd_line "inspect" "$(wfw_t cmd_inspect)"
+  wfw_cmd_line "test" "$(wfw_t cmd_test)"
+  wfw_cmd_line "install" "$(wfw_t cmd_install)"
+  printf "  %-11s %s\n" "" "$(wfw_t cmd_install_clients)"
+  wfw_cmd_line "remove" "$(wfw_t cmd_remove)"
+  wfw_cmd_line "debug" "$(wfw_t cmd_debug)"
+  wfw_cmd_line "rename" "$(wfw_t cmd_rename)"
+  wfw_cmd_line "schema" "$(wfw_t cmd_schema)"
+  wfw_cmd_line "lang" "$(wfw_t cmd_lang)"
+  echo
+  echo "${WFW_C_DIM}$(wfw_t security_1)${WFW_C_RESET}"
+  echo "${WFW_C_DIM}$(wfw_t security_2)${WFW_C_RESET}"
+  echo "${WFW_C_DIM}$(wfw_t security_3)${WFW_C_RESET}"
+}
+
+wfw_prompt_lang_if_needed
+
+cmd="${1:-}"
+[[ -n "$cmd" ]] || { usage; exit 1; }
+shift || true
+
+case "$cmd" in
+  add|list|inspect|test|install|remove|rotate|debug|secret-set|connect|rename|schema|lang)
+    # shellcheck disable=SC1090
+    source "$WFW_COMMANDS_DIR/$cmd.sh" "$@"
+    ;;
+  run-mcp)
+    exec "$WFW_COMMANDS_DIR/run-mcp.sh" "$@"
+    ;;
+  -h|--help|help)
+    usage
+    ;;
+  *)
+    echo "error: unknown command '$cmd'" >&2
+    usage
+    exit 1
+    ;;
+esac