@se-studio/contentful-cms 0.0.0-next16-20260822103555

package/HOSTED.md

@@ -0,0 +1,152 @@
+# Hosted cms-edit for Claude Desktop and Grok Build
+
+Use this guide when your team hosts cms-edit on Vercel (one deployment per client). **You do not need Node.js, tokens, or config files** — only an MCP client (Claude Desktop or Grok Build) and a Contentful account.
+
+Edits you make appear in Contentful under **your name**, because you sign in with your own Contentful account. CMA requests also send `X-Contentful-User-Agent` identifying the app as `cms-edit/<version>` so API and observability logs can tell them apart from the Contentful web app.
+
+---
+
+## What SE sends you
+
+1. A link to your site's setup page (e.g. `https://dev.content.se.studio/cms-edit`)
+2. This guide
+
+You do **not** need to edit JSON, install Node.js, create API tokens, or configure connector URLs yourself.
+
+---
+
+## Before you start (SE team)
+
+For each editor:
+
+1. Invite them to the Contentful space.
+2. Assign the **AI Editor** role (draft edit only — no publish). See [README — Contentful Role Setup](./README.md#contentful-role-setup-required).
+3. Deploy `apps/cms-edit-host` to Vercel for this client (see [cms-edit-host README](../../apps/cms-edit-host/README.md)).
+4. Send them the setup page URL and this guide.
+
+---
+
+## Step 1 — Install Claude Desktop
+
+Install [Claude Desktop](https://claude.ai/download) if you have not already.
+
+---
+
+## Step 2 — Connect to Claude
+
+**Easiest:** Open the link SE sent you (e.g. `https://dev.content.se.studio/connect` or **Connect to Claude** on `/cms-edit`). This opens Claude with the connector name and URL prefilled — confirm, then sign in with Contentful.
+
+**Manual:** Claude Desktop → **Customize → Connectors** → **Add custom connector** → paste the MCP URL (e.g. `https://dev.content.se.studio/api/mcp`) → **Connect** → sign in with Contentful.
+
+No extension install, no personal access token, no command line.
+
+---
+
+## Grok Build
+
+Add the hosted MCP URL to `~/.grok/config.toml` (URL must end with `/api/mcp`):
+
+```toml
+[mcp_servers.cms-edit-<projectKey>]
+url = "https://<your-host>/api/mcp"
+enabled = true
+```
+
+In Grok: `/mcps` → select the server → press **`i`** to start OAuth → sign in with Contentful.
+
+Verify: `grok mcp doctor cms-edit-<projectKey>` or call the `cms_edit_version` tool in a session.
+
+See [hosted-guide.md](./docs/mcp/hosted-guide.md) for troubleshooting.
+
+---
+
+## Step 3 — Try it
+
+**Getting started:** Ask Claude to read the **cms-edit guide** (`cms-edit://guide` resource) or use the **`cms_edit_verify`** prompt to check version and connectivity.
+
+In a new Claude conversation:
+
+> Read the cms-edit guide and verify the connection.
+
+or:
+
+> Open the homepage and show me the content tree.
+
+If Claude returns JSON with page content or a snapshot with `@c0`, `@c1` refs, you are connected.
+
+**Homepage slug:** On SE Studio sites, Contentful stores the homepage as slug `index` (public URL `/`). Use `open --page-slug /` or `open --page-slug /index` — both work. Site-specific exceptions are in `cms-edit://customer/routing`.
+
+**Typical edit workflow:** `open --page-slug /` → `snapshot` → `read @c1` → `set @c1 heading "New title"` → `diff` → `save`.
+
+Remember: **save creates drafts only**. You or a colleague must **publish in Contentful** for changes to go live.
+
+**Do not pass `--space`** when using the hosted integration. The deployment is already configured for your site.
+
+### What to ask Claude
+
+Use natural language or these MCP prompts (slash commands / prompt picker in Claude):
+
+| I want to… | Prompt or example |
+|------------|-------------------|
+| Check the connection | `cms_edit_verify` or “Read the cms-edit guide and verify the connection” |
+| Explore the site | `cms_edit_explore` or “Show me the homepage content tree” |
+| Fix copy on a page | `cms_edit_edit_page` or “Update the heading on /pricing” |
+| Fix copy on an article | `cms_edit_edit_article` or “Update the article at /resources/blog/my-post” |
+| Create a new page | `cms_edit_create_page` |
+| Create a new article | `cms_edit_create_article` (every article needs an **article type**) |
+| Turn a document into a page | `cms_edit_create_from_doc` |
+| Turn a document into an article | `cms_edit_create_article_from_doc` |
+| Go live | **Publish the draft in Contentful** — cms-edit never publishes |
+
+**Claude drafts, Contentful publishes.** Use Contentful UI only to publish approved drafts and upload images — not to edit copy.
+
+---
+
+## Multiple cms-edit connectors (Cowork / Claude Desktop)
+
+If you connect more than one hosted cms-edit site (Brightline, SE Studio, Pedestal, etc.), each connector exposes **site-specific** MCP metadata:
+
+| Signal | Example (Brightline) |
+|--------|----------------------|
+| MCP server name | `cms-edit-brightline` |
+| Tool descriptions | `[Brightline cms-edit] …` |
+| `cms_edit_version` | `projectKey`, `displayName`, `spaceId` in JSON |
+
+**Routing:** When you say “use the **Brightline** cms-edit”, the agent should pick tools whose name or description includes **Brightline** or `cms-edit-brightline` — not probe every `mcp__<uuid>` connector.
+
+**One-shot verify:** Call `cms_edit_version` on the chosen connector and confirm `projectKey` is `brightline` (and `spaceId` is `96gdpqkm7elu` for Brightline).
+
+**Single-site tasks:** Disable other cms-edit connectors in Integrations when you only need one site (e.g. blog tag matrix export).
+
+---
+
+## Troubleshooting
+
+| Problem | What to do |
+|---------|------------|
+| **Connection stopped working** | Open Settings → Integrations and click **Connect** again — complete Contentful sign-in, not only the MCP token refresh. In Grok, `/mcps` → `i`. Hosts on cms-edit **3.5.3+** drop a cached CMA token that Contentful rejects (`invalid_token`) so Grok should re-run Contentful sign-in without a manual wipe. **3.6.1+** keep the same refresh token (no rotation) so Grok parallel sessions do not hit `invalid_refresh_token` after the 1-hour MCP JWT expires. If the browser flashes and tools still fail, delete that connector from `~/.grok/mcp_credentials.json` and press `i` again. |
+| **Wrong site / agent probes all connectors** | Use site name in your request; check `cms_edit_version` → `projectKey`. Disable unused cms-edit connectors. Start a new conversation after connector updates. |
+| **No cms_edit tool in Claude** | Confirm the integration is connected under Settings → Integrations. |
+| **No active session** (after `open` worked) | Do not pass `--space`. MCP uses session `_mcp` automatically. Run `["diagnose"]` to inspect state. |
+| **Wrong space** | Your Contentful account must have access to this site's space. Ask SE if unsure. |
+| **Check cms-edit version** | Ask Claude to use the `cms_edit_version` tool, or run `curl -s "https://YOUR-DEPLOYMENT.vercel.app/api/health" \| jq .cmsEdit`. |
+
+### Health check
+
+```bash
+curl -s "https://YOUR-DEPLOYMENT.vercel.app/api/health"
+```
+
+All checks should show `"ok": true`. If `redis` or `oauth` is not ok, contact SE to fix the deployment.
+
+---
+
+## Legacy: `.mcpb` extension (deprecated)
+
+Older deployments used a Claude Desktop **extension** (`.mcpb`) with a manual Contentful personal access token. New setups use **Integrations + OAuth** instead. If your extension stopped working, remove it (Settings → Extensions) and reconnect via your site's `/cms-edit` page.
+
+---
+
+## Developers
+
+Local stdio MCP is not supported. Use the hosted connector URL from `/cms-edit`, or run `cms-edit` CLI in a repo with `.contentful-cms.json`. See [INSTALL.md](./INSTALL.md).

package/INSTALL.md

@@ -0,0 +1,29 @@
+# Installing the Contentful CMS Editor for Claude
+
+Editors connect Claude to Contentful through **hosted cms-edit MCP** — no Node.js, terminal, or personal access token required.
+
+## Hosted setup
+
+If SE sent you an **onboarding link** (e.g. `https://your-site.content.se.studio/cms-edit`), follow [HOSTED.md](./HOSTED.md):
+
+1. Open the link and click **Connect to Claude**
+2. Confirm the connector in Claude Desktop or claude.ai
+3. Sign in with your Contentful account when prompted
+4. Verify by asking Claude to read the cms-edit **tasks-index**
+
+**Reconnect:** use `/cms-edit` on your site or Claude → Settings → Integrations.
+
+---
+
+## Developers
+
+Local stdio MCP and the setup wizard are **not supported**.
+
+- **Content editing via Claude:** use the hosted connector URL from your site's `/cms-edit` page (same as editors).
+- **CLI / agents in a repo:** configure `.contentful-cms.json`, install skills (`npx skills add @se-studio/skills`), and read the editor pack before editing. See [README.md](./README.md) and [docs/SKILLS.md](./docs/SKILLS.md).
+
+---
+
+## Something not working?
+
+Get in touch and we'll sort it out together.