@se-studio/contentful-cms 2.6.0 → 2.7.0

package/docs/mcp/e2e-test-prompt.md

@@ -0,0 +1,159 @@
+# Hosted MCP end-to-end test prompts
+
+How to create and run **copy-paste QA prompts** for cms-edit hosted MCP (Claude Desktop Integrations + OAuth).
+
+**Example instance:** [Brightline `MCP-E2E-TEST.md`](https://github.com/Brightline-Marketing/brightline-sites/blob/develop/docs/cms-edit/MCP-E2E-TEST.md) in `brightline-sites/docs/cms-edit/`.
+
+---
+
+## When to run
+
+| Trigger | Action |
+|---------|--------|
+| Bumped `@se-studio/contentful-cms` in customer repo | Regen editor pack → push → run E2E prompt |
+| Regenerated `editor-pack/` | Push → run E2E prompt |
+| OAuth / Redis / session bugs reported | Run phases 0 + 4 + session tips in [hosted-guide.md](./hosted-guide.md) |
+| Major cms-edit CLI prune (e.g. 2.6.0) | Include **phase 9** negative tests for removed commands |
+
+---
+
+## Prerequisites
+
+1. Claude Desktop with the site's **custom connector** connected (Contentful OAuth complete).
+2. Editor has **AI Editor** role on the space.
+3. Hosted deployment healthy: `curl -s https://<host>/api/health | jq` — `config`, `redis`, `oauth` ok.
+4. Do **not** pass `--space` in `cms_edit` args on hosted MCP.
+
+---
+
+## Where to store site-specific prompts
+
+| Repo layout | Recommended path |
+|-------------|------------------|
+| Customer monorepo (Brightline, Pedestal, SE Studio) | `docs/cms-edit/MCP-E2E-TEST.md` |
+| Optional per-site in multi-site repo | `docs/cms-edit/<site>/MCP-E2E-TEST.md` |
+
+Link from:
+
+- Customer `cms-edit/README.md`
+- Customer `AGENTS.md` (under CMS editing section)
+- `docs/CMS_EDIT_SETUP.md` customer table (this monorepo)
+
+---
+
+## How to create a new site prompt
+
+### 1. Gather site facts
+
+Read the deployed editor pack (or regenerate locally):
+
+```bash
+cms-edit project doctor --project-config cms-edit/<site>/project.json
+```
+
+From `cms-edit://customer/routing` and `capabilities.json`, note:
+
+- Homepage CMS slug (`index` vs `home`)
+- Articles base path, tags enabled/disabled
+- Which tasks in `tasks-index` are enabled
+- Example page slug for peek/open (pick a stable page, not a campaign LP)
+- One real `componentType` for `preview showcase`
+
+### 2. Use the phase template
+
+Every E2E prompt should cover these phases (trim for smoke tests):
+
+| Phase | Purpose | Customize per site |
+|-------|---------|-------------------|
+| **0** Connector | version, health, guide, help | Expected version range |
+| **1** Customer resources | tasks-index, capabilities, routing, indexes | Confirm routing bullets |
+| **2** Discovery | index status, list, resolve, search | `index status` may show not built on a cold hosted instance before any sync; re-check after `list` or `open`. Article/tag types if enabled |
+| **3** Peek | Tree without session | Fallback slug if `/about` missing |
+| **4** Session | open → snapshot → read → diff | Homepage slug from routing |
+| **5** Schema | `schema colours`, `schema types`, `schema fields` | Any site-specific content types |
+| **6** Media | `asset review`, optional `--include-usage --usage-limit 5` | Skip if index empty; do not combine `--include-passing` + `--include-usage` without a limit on hosted MCP |
+| **7** Dry-run writes | set+discard, bulk-rtf dry-run, create from-json dry-run | Skip taxonomy if disabled |
+| **8** Preview | `preview url`, `preview showcase` | Real component type name |
+| **9** Negatives | Removed commands (sitemap, ensure, run, …) | Update when CLI changes |
+
+### 3. Safety rules (always include)
+
+```
+- Do NOT pass --space on hosted MCP.
+- Do NOT save or create without --dry-run.
+- If you set fields, run discard before finishing.
+- Report PASS / FAIL / SKIP per step.
+```
+
+### 4. Final report format
+
+Require a markdown results table and P0/P1/P2 fix list so runs are comparable across releases.
+
+### 5. Ship with the customer repo
+
+1. Add `docs/cms-edit/MCP-E2E-TEST.md` with site name, MCP URL, health URL, expected version.
+2. Link from `cms-edit/README.md` and `AGENTS.md`.
+3. Commit + push to deploy branch — **do not** `vercel deploy` manually (see `Agents.md`).
+
+---
+
+## Skeleton template
+
+Copy into a new customer doc and replace `{{…}}` placeholders:
+
+```markdown
+# Hosted MCP end-to-end test ({{SITE_NAME}})
+
+| MCP URL | {{MCP_URL}} |
+| Expected cms-edit | {{VERSION}} |
+| Deploy branch | {{BRANCH}} |
+
+## Prompt
+
+\`\`\`
+You are exercising the {{SITE_NAME}} cms-edit hosted MCP end-to-end.
+
+RULES
+- Do NOT pass --space …
+- Do NOT save …
+- discard after any set …
+
+PHASE 0 — …
+PHASE 1 — Confirm: homepage slug `{{HOMEPAGE_SLUG}}`, articles `{{ARTICLES_BASE}}`
+…
+PHASE 9 — Negatives: sitemap, ensure, run
+FINAL REPORT — table + P0/P1/P2
+\`\`\`
+```
+
+---
+
+## Shorter smoke variant
+
+Document a **5-minute** subset in the same file:
+
+- Phases **0, 1, 2, 4, 9** only — enough to catch connector, knowledge, discovery, session, and CLI regressions.
+
+---
+
+## Built-in MCP prompts (lighter alternative)
+
+For ad-hoc checks without the full E2E script:
+
+| Prompt | Covers |
+|--------|--------|
+| `cms_edit_verify` | version + health + customer resources load |
+| `cms_edit_explore` | list + open homepage + snapshot |
+
+The full E2E prompt is for **release QA** and **regression matrices** after CLI or editor-pack changes.
+
+---
+
+## Related docs
+
+| Doc | Purpose |
+|-----|---------|
+| [hosted-guide.md](./hosted-guide.md) | Editor + agent MCP reference |
+| [HOSTED.md](../../HOSTED.md) | Editor onboarding |
+| [../../docs/CMS_EDIT_SETUP.md](../../../../docs/CMS_EDIT_SETUP.md) | Customer deploy runbooks |
+| Skill `contentful-cms-regenerate-editor-pack` | Regen + push workflow |

package/docs/mcp/hosted-guide.md

@@ -67,6 +67,10 @@ When a site editor pack is deployed, these MCP resources provide **site-specific
 
 Read the full guide anytime via the `cms-edit://guide` resource or `cms_edit_help`.
 
+## End-to-end QA prompt
+
+For release QA after cms-edit or editor-pack upgrades, use a **copy-paste Claude Desktop test script** (phases: connector → customer resources → discovery → session → schema → media → dry-run writes → negatives). See [e2e-test-prompt.md](./e2e-test-prompt.md) to author one per customer site. Example: Brightline `docs/cms-edit/MCP-E2E-TEST.md`.
+
 ## Core workflow
 
 Standard editing flow: **open → snapshot → read → set/rtf → diff → save**
@@ -270,6 +274,8 @@ Then open: `["peek", "--article-slug", "<slug>"]` or `["open", "--id", "<entry-i
 
 After upgrading cms-edit, run `["index", "sync"]` once so the local index includes article `date` values (schema v4).
 
+**Index freshness on hosted MCP:** The catalog index is shared via Redis (gzipped SQLite blob). `index status` on a cold instance may show **not built** until `list`, `open`, or another index command runs — that is normal. Committed writes (`save`, `create page`, `asset upload`, …) mark the index dirty; the next discovery command refreshes it. In-session `set` edits do not trigger a sync.
+
 ## Command reference (cms_edit args)
 
 **Discovery:** `list --type <type>`, `search <query>`, `schema <contentType>`, `index sync`, `index status`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "CLI tool for AI agents to read and edit Contentful draft content without publish permissions",
   "repository": {
     "type": "git",