@typeroll/mcp-server 0.45.65 → 0.45.67

package/AGENTS.md

@@ -37,10 +37,15 @@ create the branch, then work on it with `version=<id>`.
 
 Typeroll is a static-site CMS: content lives in a database, the user
 edits it through an in-app editor, and a deploy step compiles everything
-to a fast static site hosted on Cloudflare Pages. The in-app chat handles
-single-page or single-block edits by the editor audience. You — through
-this MCP — handle the work that doesn't fit there: site-wide redesigns,
-bulk content updates, structural migrations, directory imports.
+to a fast static site hosted on Cloudflare Pages. The portal's built-in AI
+chat is optional: it needs the Organization's own AI key and appears only on
+the Sites chosen for it, so you are often the only AI working on the site.
+Everything the chat can do is available to you here — everyday edits
+(`tr-edit-site`, "Everyday requests"), structured data (`add_faq_schema`,
+`add_recipe_schema`, `add_event_schema`) and the starter design reference
+(`tr-starter-design`) — along with the work that doesn't fit a chat:
+site-wide redesigns, bulk content updates, structural migrations, directory
+imports.
 
 The MCP server is a thin wrapper around the public REST API. Each tool
 maps to one HTTP endpoint; the actual logic runs in the customer's portal
@@ -143,7 +148,12 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
   creates its Cloudflare Web Analytics site in the account that hosts the site;
   `read_app` and `update_app` return `setup` with the result. A 409 from
   `update_app` carries `code` and `details.next_step`: relay that step to the
-  person (for example approving Analytics access in Cloudflare) and retry.
+  person (for example approving the Cloudflare permission update) and retry.
+- **Analytics across Sites.** `list_organization_analytics` lists every Site
+  with Analytics on or off, its setup and each Hosting Group's Cloudflare
+  permissions; `set_organization_analytics` turns it on or off for chosen
+  Sites (one result each). A Cloudflare approval enables Analytics nowhere:
+  ask which Sites to measure, then enable those. Organization key only.
 
 - **Extension installations.** `list_extension_installations`,
   `read_extension_installation`, and `update_extension_installation_config`
@@ -574,6 +584,10 @@ can't create sites (it's bound to one) and gets a 403.
 
 ## Common operations
 
+Everyday requests — page links and preview links, images the user hands you,
+menu and footer edits, site-wide changes, settings, analytics, redirects,
+forms and structured data — are collected in `read_skill name="tr-edit-site"`.
+
 ### "Replace this string across the whole site"
 
 ```
@@ -637,7 +651,10 @@ update_page page_id=… patch={ html_content: "<…><x-include name=\"newsletter
 ```
 
 Edits to the block update every page that includes it. Use
-`find_pages_using_block` before changing it.
+`find_pages_using_block` before changing it. A request phrased as a bulk
+edit ("every page", "all hero sections") is usually this: check
+`list_partials` for a block that already fits before proposing a new one, and
+edit pages one by one only for content that really differs per page.
 
 ### "Build a page using blocks (the default for new pages)"
 
@@ -1018,6 +1035,26 @@ is created). An AI plan needs the Organization's own AI key with site access
 `all` (`403 ai_not_enabled` otherwise; nothing is created): you can instead
 create a blank site and plan it yourself.
 
+**AI workflows without the portal's AI.** `site_planning`,
+`content_generation`, `content_improvement` and `schema_markup` run the
+model with the Organization's own AI key, and only on Sites an owner or admin
+allowed. Elsewhere the run fails: `get_workflow` shows `status: "failed"`
+with `failure_code: "ai_not_enabled"` (older Core: only a `failure_reason`
+saying the AI assistant is not enabled for this site). That is not an error
+to retry or escalate. You are an AI agent: do the same work yourself with the
+recipe and tell the user that you did, instead of the workflow:
+
+| Workflow | Do it yourself with |
+|---|---|
+| `site_planning` / `create_site_and_plan` | `create_site` if needed, then `tr-new-site`: propose the page structure, get approval, build |
+| `content_generation` | `tr-content-write`: a new page in the site's voice, as a draft |
+| `content_improvement` | `tr-content-write` on the weakest published pages (thin text, missing `seo_title`/`seo_description`, not updated for a year), left as unsaved drafts for review |
+| `schema_markup` | `tr-seo` step 5: `add_faq_schema`, `add_recipe_schema`, `add_event_schema` or `json_ld` per page |
+
+`seo_audit` needs no AI: without it the run returns the per-page issue list
+without prioritization. Turning on the portal AI is the Organization's
+choice; never ask for it as a prerequisite for your own work.
+
 ### "Give someone access" (keys, sharing, invites)
 
 - **API keys:** `list_api_keys` / `revoke_api_key` for this site (revoking
@@ -1083,6 +1120,17 @@ authorized and their account choice stay in their own Cloudflare card. Relay
 the message and link; `sign_in` and `retry` happen at `connect_url`. Pass
 `recheck: true` only to re-verify a saved connection.
 
+Before enabling Analytics (`update_app`) or saving `redirect_hosts`
+(`set_publishing_domains`), read `permissions` from
+`diagnose_organization_cloudflare_connection` (or `cloudflare_permissions`
+from `read_organization_publishing_connections`). Each capability
+(`analytics_provisioning`, `analytics_reports`, `redirect_rules`) has a
+`status`: `available`, `approval_required` (relay `permission_update.next_step`:
+an owner or admin selects **Approve update** at `connect_url` once per
+Cloudflare account), `not_offered` (this installation does not request the
+scope; use the fallback in `next_step`), `unknown` (API token, checked on use)
+or `connection_required`, with the exact `missing_scopes`.
+
 ## Safety boundaries
 
 - **HTML is sanitized at save.** No `<script>`, no `onclick`, no
@@ -1222,7 +1270,9 @@ preview.
   more work than asking "ok to proceed?" first.
 - **Match the site's design.** Read a partial or two before designing
   new components. CSS variables (`var(--color-primary)`) are common
-  but not universal — mirror what's already in use.
+  but not universal — mirror what's already in use. On a blank site, or one
+  that still follows the starter design, `read_skill name="tr-starter-design"`
+  lists the variables and header/footer conventions.
 
 ## Reference: tool families
 
@@ -1237,6 +1287,7 @@ preview.
 | **Insights** | `get_site_insights` — traffic, AI-assistant referrals, and first-party conversion events over 7/30/90 days. Read-only. Traffic is powered by Cloudflare Web Analytics in the account that hosts the site; a non-ok `status` carries a `reason` with the next step. Conversion rows come from validated Analytics attribution `click_event` targets and can be present even when the traffic provider is unavailable. |
 | **Pages — reads** | `list_pages`, `read_page`, `batch_read_pages` |
 | **Pages — writes** | `create_page`, `update_page`, `replace_page`, `batch_update_pages`, `delete_page`, `clone_page` |
+| **Pages — structured data** | `add_faq_schema`, `add_recipe_schema`, `add_event_schema`: validated FAQPage, Recipe and Event JSON-LD merged into the page's `json_ld` (same type replaced, other nodes kept), as a draft. Other types: `update_page` `json_ld`. See `tr-seo`. |
 | **Pages — blocks** | `get_page_blocks`, `add_block`, `update_block`, `move_block`, `remove_block`, `duplicate_block`, `set_block_responsive`, `set_page_mode` (never converts HTML into blocks) |
 | **Pages — meta** | `get_page_preview` |
 | **Global blocks (partials)** | `list_partials` (summary by default), `read_partial`, `create_free_block` (`blocks` or `html_content`), `update_partial`, `replace_partial`, `set_partial_mode`, `delete_partial`, `find_pages_using_block`, `make_block_global`, `detach_global_block`. Block pages reference a global block with `core/global_block` (`global_block_id`); HTML pages use `<x-include>`. |
@@ -1251,7 +1302,7 @@ preview.
 | **Forms** | `list_forms`, `read_form`, `create_form`, `update_form`, `delete_form`, `get_form_capabilities`, `list_form_submissions`, `read_form_submission`, `delete_form_submission` (removes one submission — e.g. cleaning up a test entry; `delete_form` with `delete_submissions` is the bulk path). **Steps (form/* block trees) are the ONLY stored model**: pass `steps` for funnels, or `fields` for simple forms — the server converts a flat field list to a single static step. Place with a `core/form` block on block-mode pages or `<x-form id="…" />` in HTML mode. Both expand server-side to the same complete signed shell and initial state. `read_form` shows the form's actions (email notifications, webhooks; secrets masked) and `create_form`/`update_form` set them with `actions`, with admin permission as in the portal; `get_form_capabilities` lists the action types (including app-provided ones) and their config fields. |
 | **Email (admin)** | `get_email_settings`, `set_email_settings`, `delete_email_settings`, `send_test_email` — the outgoing provider (Postmark, SMTP, SES) that form notifications send through, as in Settings → Email & notifications; secrets are write-only (reads show `{ set: true }`; omit a secret to keep it). Without a provider, form email actions are skipped. `get_incoming_email_settings`, `set_incoming_email_forwarding` (enable/disable a host-approved route by `route_id` + current `revision`; cannot create aliases or change targets), `read_incoming_email_receipt`. |
 | **Settings** | `update_site_settings` (admin; every field the portal Settings form accepts, including `sitewide_noindex`, `default_og_image`, `twitter_handle`, `organization`, `staging_url` and shallow-merged native `cookie_consent`), `check_site_indexing` (live fallback/production headers, meta robots, and robots.txt diagnostics) |
-| **Core modules** | `list_apps`, `read_app`, `update_app` (legacy API name; admin; schema-driven config, masked secrets, redeploy when `affects_build` is true) |
+| **Core modules** | `list_apps`, `read_app`, `update_app` (legacy API name; admin; schema-driven config, masked secrets, redeploy when `affects_build` is true); `list_organization_analytics`, `set_organization_analytics` (Analytics for chosen Sites; organization key) |
 | **Extension installations** | `list_extension_installations`, `read_extension_installation`, `update_extension_installation_config` (admin; schema-driven config, masked secrets preserved, production deploy queued by default) |
 | **Search + bulk** | `search_pages`, `check_internal_links`, `bulk_replace_text`. The link check is database-driven. Bulk replace defaults to pages but can target partials, Pages or all resources, always dry-run first. |
 | **Branches** | `create_branch`, `read_version`, `delete_branch`, `merge_branch` |

package/README.md

@@ -193,7 +193,8 @@ the full reference + concrete operation recipes.
   `diagnose_organization_github_connection` (why GitHub is not connected,
   every account with the App, and who must act with one fix each),
   `diagnose_organization_cloudflare_connection` (why a Hosting Group's
-  Cloudflare connection is not working, who must act and one fix each),
+  Cloudflare connection is not working, who must act and one fix each, and
+  which optional permissions for Analytics and redirect rules it is missing),
   `disconnect_organization_publishing_provider`,
   `connect_organization_cloudflare` (customer API token),
   `prepare_organization_media_storage`, `save_organization_media_access`.
@@ -284,7 +285,9 @@ the full reference + concrete operation recipes.
   state, and enable, configure, or disable any module with the same admin API key used for content
   and deploys. Secret fields are encrypted server-side and never returned;
   Analytics provisioning runs on the platform. Deploy after updates whose
-  response has `affects_build: true`.
+  response has `affects_build: true`. `list_organization_analytics` and
+  `set_organization_analytics` show and change Analytics for chosen Sites
+  across the Organization (organization key).
 - **Search + link integrity** — `search_pages` plus `check_internal_links`,
   which resolves saved database content against pages, Page/facet routes,
   media and redirect chains without crawling the public site.