@typeroll/mcp-server 0.45.64 → 0.45.66

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
@@ -139,7 +144,11 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
   compatibility) through the same admin API key used for content
   and deploys. Read the schema before writing. Secret fields stay masked on
   reads and encrypted at rest; omitted fields preserve their current values.
-  When `affects_build` is true, deploy after the update.
+  When `affects_build` is true, deploy after the update. Enabling Analytics
+  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.
 
 - **Extension installations.** `list_extension_installations`,
   `read_extension_installation`, and `update_extension_installation_config`
@@ -570,6 +579,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"
 
 ```
@@ -633,7 +646,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)"
 
@@ -842,7 +858,7 @@ something is quietly wrong:
   page breaks at once.
 - **hosting adapter** (blocker) — without credentials, deploys return a job id
   and publish nothing, while reporting success.
-- verification origin, AI reconstruction, form notification email, and whether
+- verification origin, content preservation, form notification email, and whether
   the target actually has a design to rebuild INTO (warnings).
 
 `ready: false` means STOP and report the blockers, each of which carries a
@@ -1010,7 +1026,29 @@ site that starts with a WordPress migration or an AI plan is one call with an
 organization key: `create_site_and_migrate` or `create_site_and_plan` (the two
 non-blank options on the portal's New site page). Migration needs verified
 organization import storage (`409 import_storage_required` otherwise; nothing
-is created).
+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)
 
@@ -1028,6 +1066,19 @@ is created).
   a link; the person signs in and joins as an editor. Creating Organizations,
   switching Organization and redeeming invites remain signed-in portal actions.
 
+### "Turn on the portal's AI assistant" (and why you don't need it)
+
+You are the user's own agent: MCP and the API work on every Site you can
+reach, whatever this setting says. The built-in AI chat in the portal is
+separate. It uses the Organization's own Anthropic API key and appears only
+on the Sites an owner or admin chooses. `read_organization_ai_settings` shows
+whether a key is set (last four characters only) and `ai_enabled` per Site;
+`set_organization_ai_site_access` (`mode: "all"` or `"selected"` with
+`site_ids`), `set_organization_ai_key` and `remove_organization_ai_key` change
+it (organization key, owner/admin). Prefer that the person enters the key in
+the portal (Organization settings → AI assistant) so it never passes through
+your conversation; never repeat a key back.
+
 ### "Connect GitHub or Cloudflare"
 
 `read_organization_publishing_connections` (organization key) reports both
@@ -1203,7 +1254,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
 
@@ -1213,11 +1266,12 @@ preview.
 | **Discovery** | `get_site`, `create_site`, `create_site_and_migrate`, `create_site_and_plan` (org-scoped key only — see below), `update_site` (incl. `ai_scripts_enabled`, admin), `list_versions`, `read_site_settings` |
 | **Site lifecycle** | `archive_site`, `restore_site`, `purge_site_media` (archived sites only, irreversible). Owner-organization admin, as in the portal. |
 | **Workflows** | `list_workflows`, `start_workflow` (write; `rebuild_deploy` admin), `get_workflow`, `approve_workflow` (only `paused_for_review`, with the user's consent) |
-| **Access** | `list_api_keys`, `revoke_api_key` (site admin), `list_organization_api_keys`, `revoke_organization_api_key` (organization key; new keys are created only in the portal), `list_site_shares`, `share_site`, `update_site_share`, `revoke_site_share` (site admin), `create_organization_invite` (organization key) |
+| **Access** | `list_api_keys`, `revoke_api_key` (site admin), `list_organization_api_keys`, `revoke_organization_api_key` (organization key; new keys are created only in the portal), `list_site_shares`, `share_site`, `update_site_share`, `revoke_site_share` (site admin), `create_organization_invite` (organization key), `read_organization_ai_settings`, `set_organization_ai_key`, `remove_organization_ai_key`, `set_organization_ai_site_access` (the portal AI chat's own key and Sites; organization key) |
 | **Organization publishing** | `read_organization_publishing_connections`, `diagnose_organization_github_connection`, `diagnose_organization_cloudflare_connection`, `disconnect_organization_publishing_provider`, `connect_organization_cloudflare`, `prepare_organization_media_storage`, `save_organization_media_access`, plus builds, Hosting Groups, domains and media migration tools (organization key) |
-| **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; conversion rows come from validated Analytics attribution `click_event` targets and can be present even when the traffic provider is unavailable. |
+| **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>`. |

package/README.md

@@ -177,6 +177,11 @@ the full reference + concrete operation recipes.
   `create_organization_invite` (editor invite link). A share never reaches
   further than the caller. New API keys are created only in the portal, so the
   secret never passes through an agent conversation.
+- **Portal AI assistant** — `read_organization_ai_settings`,
+  `set_organization_ai_key`, `remove_organization_ai_key` and
+  `set_organization_ai_site_access`: the Organization's own Anthropic key
+  (verified, encrypted, never returned) and the Sites that show the built-in
+  AI chat. Organization key, owner/admin. MCP itself never depends on it.
 - **Workflows** — `list_workflows`, `start_workflow` (migration, site planning,
   SEO/link/performance audits, content generation and improvement, schema
   markup, URL parity, rebuild & deploy), `get_workflow`, `approve_workflow`.