@bettercms-ai/mcp 0.9.0

package/README.md

@@ -0,0 +1,85 @@
+# @bettercms-ai/mcp
+
+BetterCMS [Model Context Protocol](https://modelcontextprotocol.io) server. Lets an
+AI assistant author your content schema and entries through the BetterCMS Management
+API, authenticated with a short-lived, per-project `content:manage` key minted via
+the OAuth 2.0 Device Authorization Grant (RFC 8628) — no pasted long-lived key.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_model` | Create a content model (schema) with optional initial fields. |
+| `add_field` | Append a field to an existing model (read-modify-write; never removes fields). |
+| `create_entry` | Create a content entry; applies `data`/`status` via a follow-up update. |
+| `create_form` / `update_form` | Author a form (fields + settings) to embed with `<BcmsForm>`. |
+| `create_component` / `update_component` | Author a reusable component (blockJson tree + props) to render with `<BcmsBlocks>`. |
+| `list_forms` / `get_form` / `list_components` / `get_component` | Discover forms & components to wire into site code. |
+
+See [SKILL.md](./SKILL.md) for how an AI agent should author pages, forms, and components.
+
+All operations are **additive** — there are no destructive tools. Deleting models,
+fields, or entries is dashboard-only by design.
+
+## Usage
+
+Add to your MCP client config (e.g. Claude Desktop / Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "bettercms": {
+      "command": "npx",
+      "args": ["-y", "@bettercms-ai/mcp"],
+      "env": { "BETTERCMS_API_URL": "https://api.bettercms.ai" }
+    }
+  }
+}
+```
+
+### Registry auth (current)
+
+This package is published to **GitHub Packages**, which requires authentication
+**even for public scoped packages**. For `npx @bettercms-ai/mcp` to resolve, the
+host machine needs an `~/.npmrc` with:
+
+```
+@bettercms-ai:registry=https://npm.pkg.github.com/
+//npm.pkg.github.com/:_authToken=<a GitHub PAT with read:packages>
+```
+
+> **TODO (future):** publish `@bettercms-ai/mcp` (and `types`/`sdk`) to the public
+> **npmjs.org** registry so `npx @bettercms-ai/mcp` works with zero `.npmrc` setup
+> for any host/user. Until then the GitHub Packages auth above is required.
+
+On the first tool call the server prints an authorization prompt to **stderr**
+(visible in your MCP client's logs):
+
+```
+┌─ BetterCMS authorization required ─────────────────────────
+│ Visit: https://demo.bettercms.ai/activate
+│ Enter code: WDJB-MJHT
+│ Or open: https://demo.bettercms.ai/activate?code=WDJB-MJHT
+└────────────────────────────────────────────────────────────
+```
+
+Approve it in the dashboard (pick a workspace/project) and the server caches the
+minted token. It auto-refreshes on expiry; if the refresh token is revoked it
+re-runs the device flow.
+
+## Environment
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `BETTERCMS_API_URL` | `https://api.bettercms.ai` | API origin (device-auth + Management API). |
+| `BETTERCMS_MCP_CREDENTIALS` | `~/.bettercms/mcp-credentials.json` | Token cache path (0600). |
+| `BETTERCMS_MCP_CLIENT_NAME` | `BetterCMS MCP` | Label shown on the approval screen. |
+
+## Develop
+
+```bash
+bun install
+bun run --filter @bettercms-ai/mcp typecheck
+bun run --filter @bettercms-ai/mcp test
+bun run --filter @bettercms-ai/mcp build
+```

package/SKILL.md

@@ -0,0 +1,65 @@
+# BetterCMS MCP — authoring skill
+
+How an AI agent should author content, schema, **forms**, and **components** in
+BetterCMS through this MCP. The MCP is bound to ONE project (the API key's project);
+everything you create lands there.
+
+The guided prompts ship with the server — prefer them: `studio` (router),
+`propose_schema`, `new_page`, `new_form`, `new_component`. This file is the reference
+behind them.
+
+## Golden rules
+- **Confirm before creating.** Propose the shape (fields / block tree) and get the
+  user's approval (AskUserQuestion) before any create/update. Never silently guess.
+- **Read before you edit.** Use the `list_*` / `get_*` tools first so you keep existing
+  keys/blocks and don't duplicate.
+- **Additive where possible.** `add_field`/`add_page_field` append; passing `fields`
+  to `update_form` or `blockJson` to `update_component` REPLACES — include everything
+  you want to keep.
+
+## Pages & schema
+Design the project's schema from its code — the connected repo, or, for an uploaded
+project, its source in your working directory. Destructure each page into a tree:
+plain fields, **group** (one nested object), **repeater** (a repeatable array). Then
+`create_page` per page. (See the `propose_schema` prompt.) Pages created here show up
+in the dashboard Content tab.
+
+## Forms
+Tools: `list_forms`, `get_form`, `create_form`, `update_form`.
+
+1. Collect the fields with the user. Field: `{ key, label, type, required?, placeholder?,
+   options?, defaultValue?, showIf? }`. Types: `text, email, textarea, select` (needs
+   `options`), `checkbox, number, phone, date, url, consent, hidden`. `showIf:
+   { field, equals }` shows a field conditionally.
+2. Settings: `name` (the handle for `getForm('Name')`), `submitLabel?`, `successMessage?`,
+   `redirectUrl?`.
+3. Confirm → `create_form { name, fields, ... }` (returns the id) or
+   `update_form { formId, ... }`.
+4. **Wire it into the site**: in a `@bettercms-ai/next` site,
+   `import { getForm } from "@bettercms-ai/next"` then render
+   `<BcmsForm form={await getForm("Name")} />` where the user wants it.
+
+## Components (reusable Webflow-style symbols)
+Tools: `list_components`, `get_component`, `create_component`, `update_component`.
+
+1. Design the `blockJson` tree — an array of blocks `{ type, id, props }`. Types:
+   `heading {text, level}`, `text {text}`, `image {src, alt}`, `button {text, href}`,
+   `spacer {height}`, `video {url}`, and `columns {columns: block[][], gap}` which nests
+   child blocks. Every block needs a stable unique `id`.
+2. Optional `props` — overridable fields `{ key, label, target: { blockId, path }, type,
+   defaultValue? }` (type: `text|richtext|image|url|boolean`) so each instance can be
+   customized.
+3. Confirm the structure → `create_component { name, slug, category?, blockJson, props? }`
+   (returns the id) or `update_component { componentId, ... }`. **Updating a component
+   re-bakes every page that embeds it.**
+4. **Render it**: `<BcmsBlocks blocks={component.blockJson} components={...} />` from
+   `@bettercms-ai/next`.
+
+Authoring `blockJson` blind is error-prone — keep trees small, confirm with the user,
+and read back with `get_component` to verify.
+
+## Errors
+- `401/403` → the MCP key needs (re)authorizing (re-run "Connect your AI").
+- `409 slug_taken` → offer a different slug.
+- `create_form`/`create_component` missing → the host has a stale cached MCP; tell the
+  user to `rm -rf ~/.npm/_npx` and restart, or that their connector predates this skill.

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Resolved configuration for the BetterCMS MCP server.
+ *
+ * A single `BETTERCMS_API_URL` (origin, no path) drives both the device-auth
+ * endpoints and the Management API base the SDK targets:
+ *   device:     {apiUrl}/api/v1/auth/device/*
+ *   management: {apiUrl}/api/v1   (SDK appends /management/content/*)
+ */
+interface McpConfig {
+    apiUrl: string;
+    deviceBaseUrl: string;
+    managementBaseUrl: string;
+    credentialsPath: string;
+    clientName: string;
+}
+declare function loadConfig(env?: NodeJS.ProcessEnv): McpConfig;
+
+/** Credentials cached between runs so the device flow runs only once per env. */
+interface StoredCredentials {
+    accessToken: string;
+    refreshToken: string;
+    /** Epoch ms when the access token expires. */
+    accessTokenExpiresAt: number;
+    workspaceId: string | null;
+    projectId: string | null;
+}
+/**
+ * An authorization the user has been sent off to approve but hasn't yet.
+ * Persisted so a later tool call can *resume* polling that same code instead of
+ * minting a fresh one — this is what lets the flow survive across the
+ * "return the link → user approves → retry" round-trip in clients (VS Code)
+ * that never surface the server's stderr prompt.
+ */
+interface PendingDevice {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    /** verification_uri with `?code=` prefilled — the link we hand the user. */
+    verificationUriComplete: string;
+    intervalSeconds: number;
+    /** Epoch ms when the device code expires. */
+    expiresAt: number;
+}
+/** Persistence boundary for credentials (file-backed in prod, in-memory in tests). */
+interface TokenStore {
+    read(): Promise<StoredCredentials | null>;
+    write(creds: StoredCredentials): Promise<void>;
+    clear(): Promise<void>;
+    /** In-progress device authorization awaiting approval, if any. */
+    readPending(): Promise<PendingDevice | null>;
+    writePending(pending: PendingDevice): Promise<void>;
+    clearPending(): Promise<void>;
+}
+
+/** Injectable seams so tests can run without real timers / network / stderr. */
+interface DeviceAuthDeps {
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (message: string) => void;
+    now?: () => number;
+}
+/**
+ * Drives the OAuth 2.0 Device Authorization Grant (RFC 8628) against the
+ * BetterCMS backend and hands the SDK a valid `content:manage` access token.
+ *
+ * - `getAccessToken()` returns a usable token: cached if fresh, refreshed if
+ *   expired, or freshly minted via the full device flow if there's nothing valid.
+ * - All human-facing output goes to stderr — stdout is the MCP JSON-RPC channel.
+ */
+declare class DeviceAuthClient {
+    private readonly config;
+    private readonly store;
+    private readonly fetchImpl;
+    private readonly sleep;
+    private readonly log;
+    private readonly now;
+    private inFlight;
+    private refreshInFlight;
+    constructor(config: McpConfig, store: TokenStore, deps?: DeviceAuthDeps);
+    /** Return a valid access token, doing the least work necessary. Single-flighted. */
+    getAccessToken(): Promise<string>;
+    private resolveToken;
+    /**
+     * Resume a still-live authorization if one is persisted, otherwise start a
+     * fresh one; then grace-poll. Throws {@link DeviceAuthPendingError} (carrying
+     * the activation link) if the user hasn't approved within the grace window.
+     */
+    private runDeviceFlow;
+    /** Request a fresh device code, persist it as pending, and log a breadcrumb. */
+    private startDeviceFlow;
+    /**
+     * Poll the token endpoint until `deadline`. Returns the access token on
+     * approval, or null if the deadline passes while still pending. Throws
+     * {@link DeviceAuthError} on a terminal outcome (denied / expired).
+     */
+    private pollForApproval;
+    /**
+     * Exchange the stored refresh token for a new access token. Single-flighted:
+     * the device `/refresh` endpoint is single-use (it rotates the refresh token
+     * and revokes the prior access key), so a burst of concurrent 401s must NOT
+     * each fire their own refresh — the first would rotate, and the rest would
+     * send the now-stale token, get `invalid_grant`, and wipe the freshly-minted
+     * credentials. Collapsing them into one in-flight rotation keeps the session
+     * alive without a needless re-auth.
+     */
+    refresh(): Promise<string | null>;
+    /**
+     * Forget the cached credentials and start a fresh device flow. Called when the
+     * bound project was deleted server-side (a key bound to a dead project can never
+     * succeed again) — clearing lets the user re-authorize against a LIVE project.
+     * Returns a new token if approval is fast, else throws {@link DeviceAuthPendingError}
+     * carrying the activation link (the next tool call resumes into the new project).
+     */
+    resetAndReauthorize(): Promise<string>;
+    private doRefresh;
+    private persist;
+}
+
+interface BuildServerDeps {
+    auth: DeviceAuthClient;
+    managementBaseUrl: string;
+}
+/**
+ * Build the BetterCMS MCP server with its tools registered. Auth is lazy — the
+ * device flow runs on the first tool call, not at connect time, so the MCP
+ * handshake/tool-listing never blocks on user approval.
+ */
+declare function buildServer(deps: BuildServerDeps): McpServer;
+
+export { DeviceAuthClient, buildServer, loadConfig };