@prenta/mcp-server 0.23.0

package/CHANGELOG.md

@@ -0,0 +1,583 @@
+# @actuate-media/mcp-server
+
+## 0.23.0
+
+### Minor Changes
+
+- 5eea995: Product rename: ActuateCMS is now **Prenta**. Every package moves from the
+  `@actuate-media/*` scope to `@prenta/*` with simplified names (`@prenta/core`,
+  `@prenta/admin`, `create-prenta`), and version numbers continue from where the
+  old scope left off.
+
+  This is a clean break — no backwards-compat aliases:
+  - **npm packages**: `@actuate-media/cms-core` → `@prenta/core`,
+    `@actuate-media/cms-admin` → `@prenta/admin`, all other packages keep their
+    suffix under `@prenta/*`. `create-actuate-cms` → `create-prenta`
+    (`npm create prenta`), `create-actuate-astro` → `create-prenta-astro`.
+    CLI bins: `actuate`/`actuate-cms` → `prenta`/`prenta-cms`; `actuate-mcp` →
+    `prenta-mcp`.
+  - **Database**: migration `0012_rename_to_prenta` renames all 36 `actuate_*`
+    tables to `prenta_*` in place (plus prefixed constraints, indexes, and
+    sequences). Run `prisma migrate deploy` when upgrading.
+  - **Runtime identifiers**: `getActuateConfig` → `getPrentaConfig`,
+    `handleActuateAPI` → `handlePrentaAPI`, `ActuateClient` → `PrentaClient`,
+    `ActuateDB` → `PrentaDB`, config file `actuate.config.ts` →
+    `prenta.config.ts`, CSS scopes `.actuate-admin`/`.actuate-canvas` →
+    `.prenta-admin`/`.prenta-canvas`, preview protocol `actuate-preview:*` →
+    `prenta-preview:*`, webhook headers `X-Actuate-*` → `X-Prenta-*`, session
+    cookie `actuate_session` → `prenta_session`, env vars `ACTUATE_*` →
+    `PRENTA_*`, purge route `/api/actuate/purge` → `/api/prenta/purge`.
+  - **Sessions and webhooks**: all sessions reset on upgrade (cookie + JWT issuer
+    changed); webhook consumers must re-verify signatures against the new
+    `X-Prenta-*` headers.
+
+  The old `@actuate-media/*` packages are deprecated on npm and will receive no
+  further releases.
+
+## 0.22.2
+
+### Patch Changes
+
+- cf97a40: Launch-critical Astro SEO + freshness: `documentPublicPath` / `rewritePublicOrigin`, first-class `AstroPageMeta.robots`, admin/MCP path builders (#739), Yoast child sitemap + XSL proxies with origin rewrite, production purge 503 without CDN credentials, globals purge webhooks, and Launch Gate docs.
+
+## 0.22.1
+
+### Patch Changes
+
+- 46ea4a7: Hash final stored media bytes (SHA-256) on upload and return the existing record with `deduplicated` / `duplicateOf` when a match exists, so seed re-runs and byte-identical twins no longer accumulate. Opt out with `forceUpload`.
+
+## 0.22.0
+
+### Minor Changes
+
+- e4e55de: Add `POST /media/bulk-update` and `POST /media/bulk-delete` with per-id results (max 50), plus MCP tools `bulk_update_media` and `bulk_delete_media` for library-wide metadata backfills without one round trip per asset.
+
+## 0.21.2
+
+### Patch Changes
+
+- 6eaffa5: Treat decorative media (`isDecorative` + empty alt) as alt-complete in the media SEO scorer, add a non-scoring `low-quality-alt` advisory, deep-merge media fields on document update so partial `featuredImage` patches keep `url`/`id`, and expose `isDecorative` on `update_media`.
+
+## 0.21.1
+
+### Patch Changes
+
+- 0d0c5c4: Expose `description`, `caption`, and `focusKeyword` on the `update_media` MCP tool. The media API already accepted all three, but the tool omitted them, so an agent could only reach 60 of 100 on `calculateMediaSeoScore` (alt 30 + title 20 + descriptive filename 10) and every asset it touched was stuck at a "needs-work" grade. The description alone is worth the 20 points that lift an asset to a passing "good".
+
+## 0.21.0
+
+### Minor Changes
+
+- 258cbc3: Warn when navigation items link to unpublished or missing internal pages (soft warnings in MCP `validate_navigation_tree`, admin nav builder, and `POST /navigations/validate-targets`).
+
+## 0.20.2
+
+### Patch Changes
+
+- cc6ad93: Split-deploy SEO redirects: ship `applyPublicRedirect` / `createAstroRedirectMiddleware`, wire Astro starters and Next scaffold to the shared engine, clarify Never hit vs Stale, and return 409 on duplicate source updates.
+
+## 0.20.1
+
+### Patch Changes
+
+- 041a228: Add the MIT `license` field to every published package (previously missing) and correct `repository.url` to `github.com/actuate-media/actuatecms` (13 packages carried the wrong org).
+
+## 0.20.0
+
+### Minor Changes
+
+- 55f52ed: Add Phase 1 SEO MCP parity tools: Links dashboard (snapshot, health, suggest, AI index), technical settings (crawl, robots, sitemap), redirect advanced ops (flatten, recovery, import/export), content SEO CRUD, and `/ai/seo/*` assistant endpoints.
+
+## 0.19.0
+
+### Minor Changes
+
+- 4afb589: WCAG-aligned AI alt text: improved vision prompts, feature-gated `/ai/media-metadata` with `aiAltText` suggestions, post-upload auto-suggest in Media, MCP `generate_media_alt` tool, and validation warnings for static image paths outside the media library.
+
+### Patch Changes
+
+- 4afb589: Media upload optimization: high-quality **lossy WebP** by default (q82 / q86 for transparent PNGs) for strong compression with minimal visible quality loss. Lossless WebP available via `optimizeImage({ lossless: true })`. Original bytes kept when WebP would not reduce file size.
+
+## 0.18.0
+
+### Minor Changes
+
+- 39e2419: Phase 1–2: inline SEO audit fixes (deterministic + AI approve). Phase A: markdown export of manual/content fixes for dev-team handoff. Phase B: AI content briefs for thin content, heading, and alt-text issues. Phase C: topic research subagent, research-and-brief flow, and batch brief pre-generation. MCP: seven new tools for the audit fix workflow (`export_seo_fix_brief`, suggest/apply fix, content briefs, research-and-brief, batch generate) plus server instructions.
+
+## 0.17.1
+
+### Patch Changes
+
+- c656ddc: Add an `embed` (video) section type for YouTube, Vimeo, and Loom.
+  - **cms-core:** new `embed` section in the registry (`url`, `title`, `ratio`, `caption`) plus a shared, deterministic `parseEmbed()` provider allowlist (`@actuate-media/cms-core/page-sections`). Section validation rejects any URL that isn't a recognised YouTube/Vimeo/Loom link, so an arbitrary URL can never reach an iframe.
+  - **sections-react:** `EmbedSection` renderer — a lazy-loaded provider iframe inside a fixed aspect-ratio box (16:9 / 4:3 / 1:1 / 9:16) so the embed reserves its space and never causes layout shift (CLS). The URL is re-parsed through the same allowlist at render time.
+  - **cms-admin:** matching editor-canvas body for `embed` (provider + ratio placeholder) so the page/post editors preview the section instead of showing a generic "custom section" placeholder.
+  - **mcp-server:** `list_section_types` description now lists `embed`.
+
+## 0.17.0
+
+### Minor Changes
+
+- e45b9cd: Teach AI agents to build fast, Core Web Vitals-friendly pages over MCP.
+
+  The server `instructions` and the `actuate://guide` resource now include an "Images & performance" section: put a page's main banner on the `hero` section's `imageUrl` (or a post's `featuredImage`) so it becomes the page's single LCP image, always set `imageAlt`, and rely on the pipeline (WebP/AVIF via `next/image`, dimension backfill for zero CLS, responsive `sizes`) instead of hand-optimising. The live `actuate://section-types` resource already exposes the new hero image fields. Docs (`mcp.md`, `media.md`) updated to match.
+
+  Also corrects the server `instructions` safety rail to list the full set of tools that require `confirm: true` (adds `export_form_entries` and `seo_scan_run` alongside the destructive `delete_*` tools).
+
+## 0.16.2
+
+### Patch Changes
+
+- 854152d: Developer experience improvements from external-consumer feedback:
+  - Every published package now ships its `CHANGELOG.md` in the npm tarball, and packages that were missing a `README.md` (cli, cms-admin, cms-core, import, platform-vercel, all plugins, sections-react) now have one — so release notes and usage docs are visible on npmjs.com and in `node_modules`.
+  - New client-safe form validation entry point: `@actuate-media/cms-core/forms/client` exports `validateFormFieldClient()`, `validateFormValuesClient()`, visibility/conditional helpers, and the exact `FORM_EMAIL_RE` / `FORM_PHONE_RE` regexes the server enforces — zero Node dependencies, so public-site forms can mirror server rules without reimplementing them. The server validator now imports the same primitives, so client and server can never drift.
+
+## 0.16.1
+
+### Patch Changes
+
+- aa4bd1a: Teach agents the page-ownership rule (ADR 0002): server `instructions` and the `actuate://guide` resource now explain that a page with a `_layout` is Page-Builder-owned — its `sections` are compiled from the layout and the section write tools refuse it with a 409, so agents should read the compiled sections via `get_document` rather than retrying.
+
+## 0.16.0
+
+### Minor Changes
+
+- 127f91a: Make the MCP server self-teaching so agents can drive the CMS out of the box.
+  - **Server `instructions`** — the server now returns onboarding guidance during
+    MCP `initialize` (the discovery-first workflow, the canonical `sections[]`
+    page-content model, the publish lifecycle, and the destructive-tool safety
+    rails). Most MCP clients inject this into the model's system context.
+  - **MCP resources** — three pull-on-demand resources: `actuate://guide`
+    (authoring guide, markdown), `actuate://collections` (the **live** content
+    model for the connected instance), and `actuate://section-types` (the **live**
+    registered section types and schemas). Resource reads never throw — a failed
+    discovery returns an actionable payload.
+
+  New exports: `buildResources`, `AUTHORING_GUIDE`, `SERVER_INSTRUCTIONS`, and the
+  `McpResource` type. `createActuateMcpServer` now also returns `resources`.
+
+## 0.15.0
+
+### Minor Changes
+
+- 01eef99: Require explicit confirmation for destructive delete tools.
+
+  `delete_document`, `delete_media`, `delete_form`, and `delete_form_entry` now
+  require `confirm: true` in their arguments. The Zod schema rejects the call
+  before any HTTP request is made, so an agent cannot delete content (or
+  irreversibly destroy form-submission PII) without first acknowledging the
+  destructive action. **Behavioral change:** existing callers must add
+  `confirm: true` to these tool invocations.
+
+## 0.14.0
+
+### Minor Changes
+
+- af555c5: Add MCP form-authoring tools and correct the transport claim (WS-C C1 + C4).
+
+  Form authoring (C1): the MCP server could previously only READ form submissions. New tools let an agent build and maintain a form end-to-end over MCP: `list_forms`, `get_form`, `create_form`, `update_form`, `delete_form`, `duplicate_form`, `get_form_schema`, `save_form_schema`, plus submissions-inbox management (`set_form_entry_status`, `bulk_set_form_entry_status`, `delete_form_entry`) and `export_form_entries`. CSV export is gated behind `confirm: true` because it is a bulk PII egress, and the underlying client reads the raw `text/csv` body (the success response is not a JSON envelope).
+
+  Transport + docs truth (C4): the package description advertised "stdio or HTTP" but the server is stdio-only — corrected to "over stdio". Fixed the `repository.url` to the canonical `actuate-media/actuatecms`. Refreshed the README to drop the removed `create_service` / `create_location` / `create_team_member` tools (use `create_in_collection({ template })`) and document the form-authoring and page-section tool families.
+
+- 2eac1b5: Add MCP navigation-menu helpers (WS-C C3) so agents can build and wire up site menus.
+
+  Menus are documents in the `navigations` collection with a recursive link tree on `data.items` (the same shape the admin Nav builder uses). Nine new tree-aware tools wrap the document API:
+  - `list_navigations` / `get_navigation` — list menus (`{ id, name, slug, location, itemCount }`) or read one with its full tree.
+  - `create_navigation` / `update_navigation` / `delete_navigation` — menu CRUD (slug derived from name; trees validated before save).
+  - `add_navigation_item` — add a link by explicit `{ label, url }` or by a `page` reference (`{ collection?, slug? | id? }`), which resolves the page's public URL and label automatically ("link page X into menu Y"); optional `parentId` nests it.
+  - `remove_navigation_item` / `reorder_navigation_items` — remove one item (and its sub-tree) or reorder one level by an exact id permutation.
+  - `validate_navigation_tree` — validate a stored menu or a candidate `items` array without saving (`{ valid, errors, warnings, stats }`).
+
+  All writes go through `update_document` semantics, preserving versioning, access control, hooks, and cache invalidation. New items get admin-compatible ids generated so menus authored over MCP stay editable in the UI.
+
+- a413616: Add MCP relationship-resolver tools (WS-C C2) so agents stop guessing document IDs.
+  - **cms-core (additive, backward-compatible):**
+    - `listDocuments` / `GET /collections/:slug` now accept an exact `slug` filter. Because `slug` is `@@unique([collection, slug])`, this is the canonical single-query slug→id lookup.
+    - The `GET /collections` discovery endpoint now surfaces `relationTo` (for relationship fields), `hasMany`, and select `options` in each field summary, so an agent can learn where a relationship field points. (Overlaps the WS-B4 schema-surfacing work.)
+  - **mcp-server:** three new tools — `get_relationship_fields` (list relationship/media/select fields + their `relationTo`), `resolve_relationship` (exact slug → `{ id, slug, title, status }`), and `list_relationship_targets` (browse candidate documents when the slug is unknown). README updated with a "Resolving relationships" section.
+
+## 0.13.1
+
+### Patch Changes
+
+- ae1af8f: Authoring correctness fixes for the AI site-building workflow (roadmap WS-B/E quick wins).
+  - **cms-core**: `createDocument` now honors a requested `status` (`DRAFT` or
+    `PUBLISHED`) instead of always forcing `DRAFT`. Publishing on create is gated
+    to EDITOR/ADMIN, stamps `publishedAt`, and emits the `document.published`
+    webhook + sitemap notify. This fixes `POST /page-builder/create?publish=true`
+    (and `status: 'PUBLISHED'`), which previously created a draft silently.
+    Statuses other than `DRAFT`/`PUBLISHED` on create are rejected with guidance
+    to schedule/archive via update.
+  - **client**: `listMedia()` now returns the canonical
+    `{ docs, total, page, pageSize, totalPages }` (`MediaList`) envelope. The
+    server returns the asset array under `items`/`data` (never `docs`), so the
+    previous typing made `listMedia().docs` always `undefined`. Adds exported
+    `MediaAsset` and `MediaList` types and an optional `init` (signal/cache) arg.
+  - **mcp-server**: the `list_media` tool now normalizes the same `items`→`docs`
+    shape so its output matches `list_documents`.
+  - **create-actuate-cms**: generated `TextBlock`/`ImageTextBlock` now sanitize
+    author-supplied HTML with `sanitizeHtml` before `dangerouslySetInnerHTML`
+    (was an XSS vector on hostile content).
+
+## 0.13.0
+
+### Minor Changes
+
+- a6d6674: Forms PII/encryption, retention, audit, export, and MCP tools (PR8).
+
+  **cms-core**
+  - **Field-level encryption at rest**: submission values for fields flagged `encrypted` (or high-PII fields when `forms.encryptSensitiveFields` is enabled) are now encrypted with the `enc:v1:` AES-256-GCM envelope before persistence and transparently decrypted on every read path. Plaintext/legacy rows pass through unchanged; missing key on read fails closed.
+  - **PII retention**: `forms.retentionDays` is now wired into the cleanup cron, hard-deleting form submissions (and cascading their files) older than the window. Opt-in — disabled by default.
+  - **Audit logging**: viewing a single entry now logs `form.entry.viewed` and CSV export logs `form.entries.exported`, both with user id and IP, for PII-access traceability.
+  - **CSV export endpoint**: `GET /forms/entries/export?formId=…` streams a decrypted CSV of a form's submissions (bounded to 5000 rows) with formula-injection-safe cells. New exported helpers `exportFormEntries`, `encryptSubmissionData`, `decryptSubmissionData`, `fieldShouldEncrypt`.
+
+  **mcp-server**
+  - New `list_form_entries` and `get_form_entry` tools over the decrypted submissions inbox, both requiring an explicit `formId`/`entryId` (no enumeration) and documented as PII-sensitive. `get_form_entry` reads are audited server-side.
+
+## 0.12.0
+
+### Minor Changes
+
+- 5fa84d3: SEO Operations Center — a full detect → prioritize → explain → route → fix → audit → generate workflow.
+
+  **cms-core**
+  - Additive `0009_seo` migration (mirrored to `apps/dev`): `SEOAuditRun`, `SEOIssue` (+ severity/status/category enums), `Redirect` extensions (`hits`, `lastHitAt`, `enabled`, `priority`, `preserveQuery`, `source`), `Redirect404Hit`, and `RedirectSuggestion`. All columns are nullable or defaulted, so it is safe to apply to an existing database.
+  - Pure, explainable scoring model (`seo/score.ts`): `calculatePageSeoScore` / `calculateSiteSeoScore` with documented weights and breakdowns.
+  - Persistent audit engine (`seo/audit-engine.ts`) with cross-run issue lifecycle (open / resolved / ignored / recurring) and a redirect engine (chain/loop detection, safe flatten, hit tracking, 404 logging, gated AI 404 recovery).
+  - New endpoints: `POST /seo/audit`, `GET /seo/audits[/:id]`, `GET /seo/issues[/:id]`, issue `resolve`/`ignore`/`reopen`/`fix`, `GET /seo/overview`, redirect CRUD + import/export + chains/loops/flatten/suggest, technical settings (`/seo/sitemap/*`, `/seo/crawl-settings`, `/seo/robots`), and approval-gated `/ai/seo/*` (generate-field, explain-issue, generate-schema, summarize) that degrade gracefully with 501 when `plugin-ai` is unconfigured.
+  - `/resolve` now returns Next.js-ready `metadata` plus validated JSON-LD; public `robots.txt` honors the admin-edited body.
+
+  **cms-admin**
+  - Rebuilt `SEO.tsx` into a five-tab Operations Center (Overview / Content / Technical / Redirects / Audit) with `?tab=` deep-link routing, dynamic badge counts, a typed `seo-service.ts` client, reusable token-only primitives and a focus-trapped drawer, editor/fix/copilot drawers, and full loading / empty / error / permission states.
+
+  **mcp-server**
+  - New SEO tools: `seo_overview`, `run_seo_audit`, `list_seo_audit_runs`, `list_seo_issues`, `get_seo_issue`, `set_seo_issue_status`, `list_redirect_rules`, `seo_redirect_overview`, `seo_redirect_chains`.
+
+  **create-actuate-cms**
+  - Scaffolded projects now ship a redirect-resolving `middleware.ts` backed by the database redirect table.
+
+## 0.11.0
+
+### Minor Changes
+
+- 91885de: Add a section-aware bridge so AI agents (e.g. in Cursor / VS Code) can build pages section-by-section through MCP, producing real, editable, publishable Page Editor sections rather than disposable markup.
+  - **cms-core**: new `@actuate-media/cms-core/page-sections` subpath exporting the flat Page Editor section registry, pure section-array helpers, and a deterministic `validateSectionContent`. This is now the single source of truth shared by the admin editor, the REST API, and MCP. Adds REST routes: `GET /page-sections/types`, `POST /page-sections/validate`, and section CRUD over a page document's `data.sections` (`GET|POST /page-sections/:collection/:id`, `PATCH|DELETE /page-sections/:collection/:id/:sectionId`, `POST /page-sections/:collection/:id/reorder`). Mutations go through the audited `updateDocument` path (versions, hooks, cache invalidation, live-preview push) and reuse collection scope checks. Writes are rejected on collections that don't declare a `sections` JSON field.
+  - **mcp-server**: nine new tools — `list_section_types`, `get_section_schema`, `validate_section_content`, `list_page_sections`, `add_page_section`, `update_page_section`, `reorder_page_sections`, `remove_page_section`, `toggle_page_section_visibility`.
+  - **cms-admin**: the Page Editor section registry and section helpers now re-export from `@actuate-media/cms-core/page-sections`; per-section publish validation is delegated to the shared `validateSectionContent`. No behavior change — internal refactor for a single source of truth.
+
+- 91885de: Add a design-driven Posts template system that mirrors the Pages section editor.
+  - **cms-core**: tag section types with a `scope` (`page` | `post`), add post-oriented section types (`article-body`, `quote`, `author-bio`, `related-posts`, `gallery`), `PostHeaderConfig` / `PostTemplate` types, the `getSectionTypesForScope` helper, and new field types (`richText`, `boolean`, `relationship`, `gallery`). Adds `GET/PUT /post-templates/:type` API routes and a `?scope=` filter on `GET /page-sections/types`.
+  - **cms-admin**: new `PostSectionEditor`, `PostTemplateEditor` (with header panel), `PostPreview`, post section renderers, and a `post-editor-service` data layer. The Add Section gallery now filters by scope, and post type cards expose an "Edit template" action.
+  - **mcp-server**: scope-aware `list_section_types`, plus `get_post_template` and `save_post_template` tools so an external AI agent can read and build a post type's template.
+
+## 0.10.0
+
+### Minor Changes
+
+- a0f6eba: Rich `@`-mention picker for comments (last Phase 7 carry-over).
+
+  **`cms-core`**: New `GET /api/cms/users/search?q=<query>` endpoint —
+  authenticated (any role), case-insensitive `contains` matching against
+  `name` + `email`, capped at 10 results, returns only `{ id, name,
+email }` (no role / hash / audit metadata). Empty / whitespace
+  queries return an empty array so the endpoint can't be used as a
+  directory-enumeration tool.
+
+  **`cms-admin`**: New `<MentionableTextarea>` component plus pure
+  helpers in `lib/mention-picker.ts` (`detectMentionContext`,
+  `insertMentionToken`, `searchMentionUsers`). Wired into the three
+  comment composer surfaces in `CommentSidePanel`: the new-thread
+  textarea, the reply input, and the in-place edit textarea. The
+  picker is keyboard-driven (Arrow Up / Down, Enter / Tab to commit,
+  Escape to close) with a Radix-style listbox + ARIA roles, and
+  gracefully handles slow responses (drops stale requests when typing
+  quickly).
+
+  **`mcp-server`**: New `search_users(query)` tool exposes the same
+  lookup so AI agents can resolve teammates by name fragment before
+  drafting a comment. Wire format is unchanged — the picker writes
+  `@<userId>` tokens that the existing `extractMentionedUserIds`
+  parser already understands, so no notification schema migration is
+  required.
+
+  No breaking changes.
+
+## 0.9.0
+
+### Minor Changes
+
+- 21db54b: Phase 7 PR F — MCP-parity audit stylistic cleanup.
+
+  This is the final follow-up to `docs/mcp-parity-audit.md`. After this
+  PR the audit is fully retired — P0, P1, and stylistic notes are all
+  addressed.
+
+  ### `@actuate-media/cms-core`
+
+  Adds `GET /api/cms/collections`: a lightweight discovery endpoint
+  sourced directly from `getActuateConfig()`. Returns
+  `{ data: CollectionMeta[] }` with one entry per configured collection
+  (`slug`, `labels`, `type`, `urlPrefix`, `hidden`, `fieldCount`,
+  `fields[{name,type,required}]`). Unauthenticated by design — the
+  response only exposes schema-shape metadata that is already public via
+  `/openapi.json` — and the contract is intentionally tight (only
+  `name` / `type` / `required` per field, no validators, hooks, or
+  access closures leak).
+
+  ### `@actuate-media/mcp-server`
+
+  Three audit-mandated stylistic cleanups:
+  1. **AI-create-X collapse (6 tools → 3).** Removed `create_service`,
+     `create_location`, `create_team_member`. Their behaviour is folded
+     into `create_in_collection` via an optional `template` arg
+     (`'service' | 'location' | 'team_member' | 'generic'`) that
+     selects a built-in prompt-enrichment recipe plus a default
+     collection slug. Kept `create_blog_post` and `create_case_study`
+     as type-specific tools because their field-sets are distinctive
+     enough to be standalone agent intents.
+
+     **Breaking change** (acknowledged — pre-1.0, audit-recommended):
+     the three removed tool names will return "tool not found" on next
+     release. Migration is mechanical:
+     - `create_service({ category, ... })`
+       → `create_in_collection({ template: 'service', category, ... })`
+     - `create_location({ cityState, ... })`
+       → `create_in_collection({ template: 'location', cityState, ... })`
+     - `create_team_member({ name, role, ... })`
+       → `create_in_collection({ template: 'team_member', name, role, ... })`
+
+  2. **`audit_document` split.** Replaced with `audit_document_by_id`
+     (requires `collection` + `id`) and `audit_inline_content` (requires
+     `title` + `body`). Both forward to the same `/ai/audit-document`
+     endpoint; the split exists so agents pick the right mode at the
+     tool boundary instead of constructing a half-filled blob and
+     discovering the "must provide either (collection,id) or body" rule
+     via a server-side error.
+
+     **Breaking change** (audit-recommended): `audit_document` is
+     removed. Migration: pick the explicit tool that matches the
+     intent — `audit_document_by_id` for stored docs,
+     `audit_inline_content` for ad-hoc text.
+
+  3. **`list_collections` reliability.** Now prefers the new
+     `/api/cms/collections` endpoint as the primary source so the tool
+     stays accurate when the OpenAPI generator drifts. Falls back to
+     OpenAPI only on a real HTTP 404 (older CMS server) — the decision
+     uses `ActuateClientError.status` (newly exported from the client),
+     not a regex against the error message, so an unrelated server
+     error that happens to contain "not found" in its body no longer
+     triggers the fallback. Non-404 errors propagate.
+
+     **Return-shape change** (consistent contract): `data` is now
+     ALWAYS a `CollectionSummary[]` array regardless of which path
+     responded. The OpenAPI fallback path normalises into the same
+     array shape that the new `/collections` endpoint emits, so
+     callers no longer need to branch on `source` to know whether they
+     got an array or an object map. The returned envelope is
+     `{ data: CollectionSummary[], source: 'collections' | 'openapi' }`.
+
+     **Newly exported:** `ActuateClientError` (subclass of `Error`
+     carrying `status: number`). Useful for any consumer that needs
+     to branch on the HTTP status from a `request()` failure.
+
+  ### Tests
+  - mcp-server: 113 tests total (was 97 in PR E). 16 new — template
+    routing for each of service / location / team_member, audit split
+    validation, list_collections primary + fallback + 500-propagation.
+  - cms-core: 4 new tests for the discovery endpoint covering field
+    summaries, `hidden` flag, missing-config 500, and the
+    no-leak-of-validators-or-hooks contract.
+
+## 0.8.0
+
+### Minor Changes
+
+- e0ac7f1: Add 4 comment + page-builder accessibility MCP tools (Phase 7 MCP-parity PR D). Combined with PRs A (10 media/folder), B (6 versions/scheduling/workflow), and C (5 SEO), this closes the remaining P0 gaps from [`docs/mcp-parity-audit.md`](https://github.com/actuate-media/actuatecms/blob/main/docs/mcp-parity-audit.md) and brings the MCP server to **100% P0 coverage**.
+
+  **Comments (2):**
+  - `list_comments` — returns the comment thread for a document. Default scope is unresolved + non-deleted; `includeResolved: true` widens to resolved threads; `includeDeleted: true` is admin-only and surfaces soft-deleted moderation history (non-admin keys get HTTP 403).
+  - `create_comment` — create a top-level comment, a thread reply (`parentId`), or a text-pinned comment (`anchor: { from, to }`). The wrapper rejects empty `body` strings at the Zod layer (server also rejects, but failing fast saves a round-trip). The server emits a `comment_created` audit event and fires a best-effort notification dispatch for any mentioned users.
+
+  **Page-builder accessibility (2):**
+  - `audit_page_a11y` — deterministic accessibility audit over a page-builder tree. Detects missing alt text, heading-level skips, missing form labels, missing ARIA attributes, and undersized touch targets. Each issue carries `autoFixable: boolean` so the caller can decide between automated cleanup vs human review.
+  - `fix_page_a11y` — auto-fix every `autoFixable: true` issue and return the mutated tree plus a report (`fixedCount` / `remainingCount` plus the unfixable remainder for human follow-up). Emits a `settings_changed` audit event.
+
+  **Schema design notes:**
+  - Both `list_comments` and `create_comment` use `id` (not `documentId`) for the document ID — matches the PR B convention and the pre-existing `audit_document` / `get_document` / `update_document` family. The collection slug is intentionally absent because comments attach to documents by ID alone.
+  - `create_comment.anchor` and `create_comment.parentId` are both `.nullable().optional()`. Publishing `["object", "null"]` and `["string", "null"]` in the JSON Schema preserves the server semantics where `null` is meaningful ("thread-level comment" / "no anchor"), not an MCP-client artefact.
+  - A11y tools take `tree: z.record(z.unknown())` — the page-builder schema is large and evolving so we accept any object and let the server enforce the top-level `tree.type === 'page'` check. Strings / numbers / arrays still fail at the Zod layer.
+
+  **Tests:** mcp-server suite 56 → 70 (+14). Covers per-method URL / method / body shape, boolean → string query encoding for `listComments`, URL encoding for awkward IDs, 403 propagation for read-only keys hitting `create_comment`, 400 propagation for malformed page trees, anchor / parentId nullable JSON Schema emission, and empty-body rejection at the wrapper layer.
+
+  This PR closes the audit's last P0 acceptance criterion. PR E (~14 P1 mop-up tools) and PR F (stylistic cleanup — collapse the `ai_create_*` family, fix the `audit_document` schema drift, OpenAPI fallback) remain as demand-driven cherry-picks.
+
+- 942ad41: Add 14 MCP tools — P1 mop-up from the MCP-parity audit. Phase 7, PR E.
+
+  Tools shipped:
+
+  Comment thread management (4):
+  - `edit_comment` — `PATCH /comments/:id`
+  - `resolve_comment` — `POST /comments/:id/resolve`
+  - `reopen_comment` — `POST /comments/:id/reopen`
+  - `delete_comment` — `DELETE /comments/:id`
+
+  Redirects (3) — admin-only on the server, open-redirect defence preserved:
+  - `list_redirects` — `GET /redirects`
+  - `create_redirect` — `POST /redirects` (statusCode constrained to 301/302/307/308 via schema enum)
+  - `delete_redirect` — `DELETE /redirects/:id`
+
+  Page templates + saved sections (3) — admin-only discovery for the page builder:
+  - `list_page_templates` — `GET /page-templates` (optional category + collection filters)
+  - `get_page_template` — `GET /page-templates/:id`
+  - `list_saved_sections` — `GET /saved-sections`
+
+  SEO aggregate (2):
+  - `seo_summary` — cheap dashboard aggregate (`GET /seo/summary`)
+  - `seo_scan_run` — expensive site-wide scan (`POST /seo/scan`); wrapper enforces a `confirm: true` literal per the audit's gate-behind-confirmation recommendation
+
+  Forms + health (2):
+  - `list_form_submissions` — PII-sensitive; requires explicit `formId` arg, no enumeration (`GET /forms/:formId/submissions`)
+  - `health_check` — `GET /health` (unauthenticated on the server; safe first-call probe)
+
+  Notes:
+  - Comment-thread tools follow the `id` naming convention established in
+    PR B / PR D for resource-scoped tools.
+  - `list_form_submissions` uses `formId` (not `id`) because the audit
+    explicitly called out "gate behind explicit form-id arg" — the more
+    specific name makes the PII gate self-documenting in agent prompts.
+  - `seo_scan_run` rejects calls without `confirm: true` before issuing
+    the HTTP request. Defence-in-depth: Zod `.literal(true)` rejects at
+    the schema layer and the handler re-asserts so a schema regression
+    still fails closed.
+  - All 14 tools forward server errors verbatim (403 admin gate, 400
+    open-redirect defence, 403 author-only delete/edit) so agents see the
+    same affordances the admin UI does.
+  - 24 new tests (15 client + 9 tool-level wrappers, including
+    confirmation-gate, PII-naming, and enum-validation regressions).
+    Brings the mcp-server test suite to 94 tests total.
+
+  This closes out the P1 list from `docs/mcp-parity-audit.md`. After
+  PR E, every admin action the audit flagged as user-visible (P0 + P1) is
+  reachable via MCP. Only PR F (stylistic cleanup — collapsing
+  `ai-create-X`, fixing `audit_document` schema, OpenAPI fallback)
+  remains as demand-driven follow-up.
+
+## 0.7.0
+
+### Minor Changes
+
+- 9517da2: Add 6 versions + scheduling + workflow MCP tools (Phase 7 MCP-parity PR B). Combined with PRs A (10 media/folder tools) and C (5 SEO tools), this retires **21 of the 24 P0 gaps** identified in [`docs/mcp-parity-audit.md`](https://github.com/actuate-media/actuatecms/blob/main/docs/mcp-parity-audit.md). The remaining 3 P0 items are comments + page-builder accessibility, queued as PR D.
+
+  **Version history (2):**
+  - `list_versions` — immutable change history of a document, newest first. Each version carries the full `data` payload at write time plus the user who made the change. Paged (default 20 / max 50).
+  - `restore_version` — roll a document back to a prior version. Goes through the normal `updateDocument` path: hooks fire, a NEW version row is created (history is never rewritten), and an audit log entry is emitted.
+
+  **Scheduling (2):**
+  - `schedule_publish` — schedule a document to publish (`scheduledAt`) and/or unpublish (`scheduledUnpublishAt`) at a future ISO 8601 timestamp. The server requires at least one of the two, both must be in the future, and `scheduledUnpublishAt` must be after `scheduledAt` when both are set. Publishing forces `status` → `SCHEDULED` so the `/cron/publish` cron picks it up; the cron does the actual status flip (decoupled so a missed tick just delays publish — it can never double-publish or skip a doc).
+  - `unschedule_publish` — cancel pending publish + unpublish. If the document was in `SCHEDULED` (not yet published) it drops back to `DRAFT`. Already-published docs stay live.
+
+  **Editorial workflow (2):**
+  - `get_workflow_state` — returns `{ stage, transitions, reviewerId, reviewNote }`. `transitions` is the list of next stages the _calling API key holder_ is allowed to move to, already role-filtered server-side. Workflow: `DRAFT → IN_REVIEW → APPROVED → PUBLISHED → ARCHIVED`.
+  - `transition_workflow` — move a document to a new stage. Server validates both that the from→to edge is legal AND that the caller's role permits it; either failure returns HTTP 400 with the reason in the error body. The `stage` arg is a Zod enum, so unknown stages are rejected at the wrapper layer before the HTTP call (clear schema error, no wasted round-trip).
+
+  **Tests:** mcp-server suite 40 → 53 (+13). Coverage includes per-method URL / method / body shape, optional-field independence on `schedule_publish`, enum validation on `transition_workflow.stage`, error propagation for both 400 paths (illegal transitions, past timestamps), and URL encoding of awkward collection slugs + document IDs.
+
+## 0.6.0
+
+### Minor Changes
+
+- a142310: Add 10 media + folder MCP tools (Phase 7 MCP-parity PR A). Combined with PR C (5 SEO tools, shipped in PR #145), this retires 15 of the 24 P0 gaps identified in [`docs/mcp-parity-audit.md`](https://github.com/actuate-media/actuatecms/blob/main/docs/mcp-parity-audit.md).
+
+  **Media write tools (5):**
+  - `upload_media` — uploads a file to the media library. Bytes pass through MCP as base64 (JSON-RPC has no binary type), the tool wrapper decodes them, and the client emits a real `multipart/form-data` request. The server enforces a 50 MB hard cap, validates magic bytes against the declared `mimeType`, and sanitises SVGs.
+  - `update_media` — set alt text (accessibility), title, filename, or focal points (smart-crop hints in 0..1 normalised coords).
+  - `delete_media` — removes the DB row AND deletes the underlying blob storage object (best-effort).
+  - `optimize_media` — recompress an existing image to WebP. Returns the updated row plus an `optimization` summary. Already-WebP files short-circuit.
+  - `move_media_to_folder` — `folderId: string | null`; the server validates the target folder is in the `media` scope.
+
+  **Folder tools (5):**
+  - `list_folders` — returns a nested tree (`children[]`) for a given scope. Scopes today: `"media"`, `"documents"`, `"collections"`. The `scope` arg is required.
+  - `create_folder` — `{ name, scope, parentId? }`. Parents must already exist in the same scope.
+  - `update_folder` — rename / reparent / reorder; pass any subset of `{ name, parentId, position }`. `parentId: null` promotes a folder to root. The server prevents self-parenting and cross-scope reparenting.
+  - `delete_folder` — returns HTTP 409 if the folder still contains documents, media, or sub-folders. The caller must move or delete the contents first.
+  - `move_document_to_folder` — same shape as `move_media_to_folder`, scoped to documents/collections folders.
+
+  **Tooling improvements:**
+  - Added a `requestMultipart()` helper to `ActuateClient` for endpoints that need `multipart/form-data`. It deliberately omits the `Content-Type` header so the fetch runtime can append the multipart boundary (overriding it breaks server-side parsing).
+  - Extended the Zod → JSON Schema converter to handle `ZodNullable`. Nullable fields now publish `type: ["string", "null"]` (etc.), so MCP-aware clients accept explicit `null` from agents. The `move_*_to_folder` and `update_folder` tools rely on this.
+
+  37 new unit tests (mcp-server suite: 21 → 38). Includes regression tests for: multipart body shape, missing `Content-Type` override, base64 with data-URL prefix + whitespace, empty-bytes rejection, null `folderId` round-trip on both move tools, and URL encoding of awkward IDs.
+
+## 0.5.0
+
+### Minor Changes
+
+- 8d105c3: Add five per-document SEO MCP tools (Phase 7 MCP-parity PR C):
+  - `seo_analyze_document` — runs the deterministic SEO content analysis (title, meta, headings, focus keyphrase, link counts, score) against a stored document.
+  - `seo_readability_score` — Flesch-Kincaid reading-ease + grade-level for a document body.
+  - `seo_internal_link_targets` — suggests up to 10 published documents to link TO, rooted in a specific stored document (title-keyword-based). Distinct from the existing `suggest_internal_links` tool, which is content-based and freeform.
+  - `seo_meta_preview` — resolved meta-tag preview (title, description, canonical, OG, Twitter, robots) for a document, with per-page overrides and site-level defaults applied.
+  - `seo_schema_graph` — Schema.org JSON-LD graph (`@context` + `@graph` with WebSite / WebPage / Article nodes) for a document.
+
+  All five are read-only deterministic wrappers around the existing `GET /api/cms/seo/<scope>/:documentId` endpoints — no LLM calls, no DB writes, cheap enough for an agent to invoke as part of a publish-readiness pipeline. Each requires only a `documentId` arg.
+
+  This is the first follow-up PR from the [MCP-parity audit](https://github.com/actuate-media/actuatecms/blob/main/docs/mcp-parity-audit.md) (PR #144), retiring 5 of the 24 P0 gaps identified there.
+
+## 0.4.0
+
+### Minor Changes
+
+- 0ac9024: Inline AI co-author HTTP endpoint + MCP tool (Phase 2).
+
+  Adds `POST /api/cms/ai/coauthor` with four sub-actions (`rewrite`,
+  `expand`, `compress`, `proofread`) that wrap the plugin-ai writing
+  primitives behind a single endpoint. Rate-limited under the same
+  bucket as content generation (20 calls/hour/user). Missing provider
+  configuration surfaces as HTTP 501 instead of 500.
+
+  Exposed to AI agents via the MCP tool `coauthor_text` with the same
+  input shape, so the admin UI and AI agents can drive identical
+  text-transformation workflows.
+
+  Tests: 5 endpoint tests covering each action + validation errors.
+
+- 313a23f: Add Slice F — AI quality pass.
+
+  `plugin-ai` exposes a new `auditDocument()` composer that combines SEO,
+  readability (Flesch-Kincaid / Gunning Fog / SMOG averaged + remapped to a
+  0-100 score), accessibility, and freshness scoring into a single
+  composite grade with prioritized actionable issues. The composer is
+  deterministic — it never calls an LLM — so it's cheap enough to invoke
+  on every save or debounced keystroke.
+
+  `cms-core` adds two HTTP endpoints:
+  - `POST /ai/audit-document` — runs the composite audit against a stored
+    document (`{ collection, id }`) or ad-hoc content. Honors field-level
+    access control when loading from the DB.
+  - `POST /ai/suggest-internal-links` — scans published documents for
+    phrases the supplied content could link to, returning ranked
+    anchor-text + target-URL suggestions. Optionally scopes to a single
+    collection.
+
+  `mcp-server` exposes both endpoints as MCP tools (`audit_document` and
+  `suggest_internal_links`) so AI agents can grade drafts and propose
+  internal links before publish.
+
+  Docs: `docs/ai-quality-audit.md`.
+
+## 0.3.0
+
+### Minor Changes
+
+- e6a18b5: Phase 2 Slice C — AI Content Authoring for any collection.
+  - **plugin-ai**: new `generateDocumentContent()` helper that maps a prompt onto a collection's field schema and returns structured field data ready to persist. Supports tone, target audience, brand voice profile, and existing-content context. Coerces LLM output to declared field types (numbers, booleans, dates, select options, array items) and drops fields the schema doesn't declare.
+  - **cms-core**: new `POST /collections/:slug/ai-create` endpoint — the non-page counterpart to `/page-builder/create`. Generates a complete document for any collection, persists as draft, optionally publishes via a follow-up update when the caller has admin scope. Refuses page-builder collections (use `/page-builder/create` instead). Hard caps prompt at 4000 chars and shares the per-user 20/hour AI rate-limit bucket. Returns a `warning` field when create succeeds but publish is denied.
+  - **mcp-server**: six new tools — `create_in_collection` (generic) plus per-type sugar tools `create_blog_post`, `create_case_study` (with `clientName` / `industry` hints), `create_service` (`category` hint), `create_location` (`cityState` hint), and `create_team_member` (`name` / `role` hints). Each per-type tool targets the conventional collection slug shipped by the cms-core collection presets, with an explicit `collection` override for sites using custom slugs.
+  - 19 new tests (10 unit tests in plugin-ai for the content generator, 9 integration tests in cms-core for the API endpoint covering auth, validation, persistence, publish flow, and the page-builder refusal path).
+  - Docs: updated `docs/api-reference.md` with the new endpoint, `docs/mcp.md` and `packages/mcp-server/README.md` with the new tools and example agent prompts.
+
+## 0.2.0
+
+### Minor Changes
+
+- e87471d: Phase 1: AI access. API key authentication (act*sk*\* bearer tokens) with scope-based authorization across collections, globals, media, and the page builder. New /api-keys admin endpoints + UI for creating, listing, and revoking keys with password reauth. CSRF is skipped for API-key requests. New /page-builder/create one-shot endpoint that generates an AI page and persists it as a document in a single call. New @actuate-media/mcp-server package exposes the CMS to AI agents (Claude, Cursor, ChatGPT, etc.) via the Model Context Protocol — full CRUD, globals, media, page generation, and one-shot create tools. Adds 44 new tests covering the API key auth path, scope enforcement, CSRF skip, and MCP client/tools.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Actuate Media
+
+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.