# 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 | Read `task-media-review`; `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 |