@typeroll/mcp-server 0.45.64 → 0.45.66

package/dist/server.js

@@ -11,6 +11,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { ownerReviewTools } from './tools/owner-review.js';
 import { pageTools } from './tools/pages.js';
+import { structuredDataTools } from './tools/structured-data.js';
 import { partialTools } from './tools/partials.js';
 import { contentTypeTools } from './tools/content-types.js';
 import { pageTemplateTools } from './tools/page-templates.js';
@@ -94,6 +95,9 @@ function effectFor(name) {
         || name === 'revoke_site_share'
         || name === 'revoke_organization_api_key'
         || name === 'create_organization_invite'
+        || name === 'set_organization_ai_key'
+        || name === 'remove_organization_ai_key'
+        || name === 'set_organization_ai_site_access'
         || name === 'disconnect_organization_publishing_provider'
         || name === 'connect_organization_cloudflare'
         || name === 'prepare_organization_media_storage'
@@ -138,7 +142,9 @@ The full playbook ships with this server — use it:
 0. First confirm the site, organization and version with the user. Personal
    connections require select_site and its site_context on subsequent calls.
    Use list_skills and read_skill for only the relevant recipe. Use read_guide
-   sections when needed; do not load the whole manual by default.
+   sections when needed; do not load the whole manual by default. Everyday
+   edits (links, images, menus, site-wide changes, settings, analytics,
+   structured data) are in tr-edit-site.
 1. When the task is "build / migrate / redesign / brand a site", call
    list_skills FIRST, then read_skill <name> for the step-by-step recipe
    (tr-new-site, tr-migrate-wp, tr-brand, tr-blog, tr-responsive, …). These are
@@ -175,6 +181,10 @@ The full playbook ships with this server — use it:
    start from and then adapt is a block template (list_block_templates,
    insert_block_template copies it). Never duplicate shared content by hand.
 8. No site yet? With an org-scoped key, create_site bootstraps one.
+9. AI workflows (site_planning, content_generation, content_improvement,
+   schema_markup, create_site_and_plan) need the Organization's portal AI
+   key for the Site. On ai_not_enabled don't retry: do the work yourself
+   with the recipe named in start_workflow and tell the user you did.
 
 If anything here conflicts with what a tool returns, trust the tool. Every
 tool's own description carries its specifics.
@@ -191,6 +201,7 @@ export function buildServer(options) {
         ...skillTools,
         ...siteTools,
         ...pageTools,
+        ...structuredDataTools,
         ...ownerReviewTools,
         ...partialTools,
         ...blockTypeTools,

package/dist/structured-data.js

@@ -0,0 +1,217 @@
+// Schema.org JSON-LD builders for Page.json_ld: FAQPage, Recipe and Event.
+//
+// One implementation for every caller. The MCP tools (tools/structured-data.ts)
+// and the portal's built-in AI chat (portal/src/lib/anthropic.ts, imported as
+// @typeroll/mcp-server/structured-data) both validate input with these zod
+// shapes and build JSON-LD with these functions, so the two cannot drift. It
+// lives in this package rather than @typeroll/shared because the standalone
+// MCP package is published without @typeroll/shared, while the portal already
+// depends on this package.
+//
+// mergeJsonLd() adds the new node to whatever the page already carries: a node
+// of the same @type is replaced (re-running a tool updates it), other nodes are
+// kept in an @graph, so an FAQ added later does not erase a LocalBusiness.
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+/** Invalid input or an unusable existing json_ld; `issues` name the field. */
+export class StructuredDataError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid structured data: ${issues.join('; ')}`);
+        this.issues = issues;
+        this.name = 'StructuredDataError';
+    }
+}
+const text = (max) => z.string().trim().min(1, 'Must not be empty.').max(max);
+const httpUrl = z.string().trim().max(2048).url('Use an absolute http(s) URL.')
+    .refine((value) => /^https?:\/\//i.test(value), 'Use an absolute http(s) URL.');
+const ISO_DURATION = /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+(?:\.\d+)?S)?)?$/;
+const duration = z.string().trim().regex(ISO_DURATION, 'Use an ISO 8601 duration such as PT30M or PT1H15M.');
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:T([01]\d|2[0-3]):([0-5]\d)(?::([0-5]\d)(?:\.\d+)?)?(Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)?)?$/;
+function realDate(value) {
+    const m = ISO_DATE.exec(value);
+    if (!m)
+        return false;
+    const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const date = new Date(Date.UTC(y, mo - 1, d));
+    return date.getUTCFullYear() === y && date.getUTCMonth() === mo - 1 && date.getUTCDate() === d;
+}
+const isoDate = z.string().trim().refine(realDate, 'Use an ISO 8601 date or date-time, e.g. 2026-06-12 or 2026-06-12T19:00:00+02:00.');
+const hasTime = (value) => value.includes('T');
+const hasOffset = (value) => /(?:Z|[+-]\d{2}:\d{2})$/.test(value);
+/** Input fields of add_faq_schema (besides page_id). */
+export const faqSchemaShape = {
+    items: z.array(z.object({
+        question: text(500),
+        answer: text(5000).describe('Plain text or simple HTML, exactly as the page shows it.'),
+    }).strict()).min(1, 'Add at least one question.').max(100)
+        .describe('The questions and answers the page itself shows, in page order.'),
+};
+/** Input fields of add_recipe_schema (besides page_id). */
+export const recipeSchemaShape = {
+    name: text(200),
+    description: text(1000).optional(),
+    image_url: httpUrl.optional().describe('Absolute image URL, e.g. the page\'s CDN image. Google needs an image for recipe rich results.'),
+    author: text(200).optional(),
+    prep_time: duration.optional().describe('ISO 8601 duration, e.g. PT30M.'),
+    cook_time: duration.optional().describe('ISO 8601 duration, e.g. PT1H.'),
+    total_time: duration.optional().describe('ISO 8601 duration, e.g. PT1H30M.'),
+    recipe_yield: text(100).optional().describe('e.g. "4 servings".'),
+    ingredients: z.array(text(500)).min(1, 'Add at least one ingredient.').max(100),
+    instructions: z.array(text(2000)).min(1, 'Add at least one step.').max(100).describe('One entry per step, in order.'),
+};
+/** Input fields of add_event_schema (besides page_id). */
+export const eventSchemaShape = {
+    name: text(200),
+    description: text(1000).optional(),
+    start_date: isoDate.describe('ISO 8601, e.g. 2026-06-12T19:00:00+02:00. Include the UTC offset.'),
+    end_date: isoDate.optional().describe('ISO 8601; not before start_date.'),
+    location_name: text(200).optional(),
+    location_address: text(500).optional(),
+    image_url: httpUrl.optional(),
+    offers_url: httpUrl.optional().describe('Ticket URL.'),
+    offers_price: z.union([z.number().nonnegative(), z.string().trim().regex(/^\d+(?:\.\d+)?$/, 'Use a number such as 250 or 19.95.')])
+        .optional().describe('Ticket price as a number; 0 for a free event. Needs offers_currency.'),
+    offers_currency: z.string().trim().regex(/^[A-Za-z]{3}$/, 'Use an ISO 4217 code such as EUR or SEK.').optional()
+        .describe('ISO 4217, e.g. EUR.'),
+};
+function parse(schema, input) {
+    const result = schema.safeParse(input);
+    if (result.success)
+        return result.data;
+    throw new StructuredDataError(result.error.issues.map((i) => `${i.path.join('.') || 'input'}: ${i.message}`));
+}
+const CONTEXT = 'https://schema.org';
+export function buildFaqJsonLd(input) {
+    const { items } = parse(z.object(faqSchemaShape), input);
+    return {
+        node: {
+            '@context': CONTEXT,
+            '@type': 'FAQPage',
+            mainEntity: items.map((it) => ({
+                '@type': 'Question',
+                name: it.question,
+                acceptedAnswer: { '@type': 'Answer', text: it.answer },
+            })),
+        },
+        warnings: [],
+    };
+}
+export function buildRecipeJsonLd(input) {
+    const r = parse(z.object(recipeSchemaShape), input);
+    const node = { '@context': CONTEXT, '@type': 'Recipe', name: r.name };
+    if (r.description)
+        node.description = r.description;
+    if (r.image_url)
+        node.image = r.image_url;
+    if (r.author)
+        node.author = { '@type': 'Person', name: r.author };
+    if (r.prep_time)
+        node.prepTime = r.prep_time;
+    if (r.cook_time)
+        node.cookTime = r.cook_time;
+    if (r.total_time)
+        node.totalTime = r.total_time;
+    if (r.recipe_yield)
+        node.recipeYield = r.recipe_yield;
+    node.recipeIngredient = r.ingredients;
+    node.recipeInstructions = r.instructions.map((step, i) => ({ '@type': 'HowToStep', position: i + 1, text: step }));
+    const warnings = r.image_url ? [] : ['No image_url: Google shows recipe rich results only for recipes with an image.'];
+    return { node, warnings };
+}
+export function buildEventJsonLd(input) {
+    const e = parse(z.object(eventSchemaShape).superRefine((v, ctx) => {
+        if (v.offers_price !== undefined && !v.offers_currency) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['offers_currency'], message: 'Required with offers_price.' });
+        }
+        if (v.end_date && hasTime(v.start_date) === hasTime(v.end_date) && hasOffset(v.start_date) === hasOffset(v.end_date)
+            && Date.parse(v.end_date) < Date.parse(v.start_date)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['end_date'], message: 'Must not be before start_date.' });
+        }
+    }), input);
+    const node = { '@context': CONTEXT, '@type': 'Event', name: e.name, startDate: e.start_date };
+    if (e.end_date)
+        node.endDate = e.end_date;
+    if (e.description)
+        node.description = e.description;
+    if (e.image_url)
+        node.image = e.image_url;
+    if (e.location_name || e.location_address) {
+        node.location = {
+            '@type': 'Place',
+            ...(e.location_name ? { name: e.location_name } : {}),
+            ...(e.location_address ? { address: e.location_address } : {}),
+        };
+    }
+    if (e.offers_url || e.offers_price !== undefined) {
+        node.offers = {
+            '@type': 'Offer',
+            ...(e.offers_url ? { url: e.offers_url } : {}),
+            ...(e.offers_price !== undefined ? { price: String(e.offers_price) } : {}),
+            ...(e.offers_currency ? { priceCurrency: e.offers_currency.toUpperCase() } : {}),
+            availability: 'https://schema.org/InStock',
+        };
+    }
+    const warnings = [];
+    if (hasTime(e.start_date) && !hasOffset(e.start_date))
+        warnings.push('start_date has no UTC offset; add one (e.g. +02:00) so search engines show the right local time.');
+    if (!node.location)
+        warnings.push('No location: Google shows event rich results only for events with a location.');
+    return { node, warnings };
+}
+/** The three page structured-data helpers, keyed by kind. */
+export const STRUCTURED_DATA = {
+    faq: { tool: 'add_faq_schema', type: 'FAQPage', shape: faqSchemaShape, build: buildFaqJsonLd },
+    recipe: { tool: 'add_recipe_schema', type: 'Recipe', shape: recipeSchemaShape, build: buildRecipeJsonLd },
+    event: { tool: 'add_event_schema', type: 'Event', shape: eventSchemaShape, build: buildEventJsonLd },
+};
+/**
+ * JSON Schema of a helper's input including `page_id`, for tool definitions
+ * outside MCP (the portal chat passes it to the model as input_schema).
+ */
+export function structuredDataInputSchema(kind) {
+    const schema = zodToJsonSchema(z.object({ page_id: z.string().min(1), ...STRUCTURED_DATA[kind].shape }), { $refStrategy: 'none' });
+    const { $schema: _schema, ...rest } = schema;
+    return rest;
+}
+function typesOf(node) {
+    const t = node['@type'];
+    return Array.isArray(t) ? t.map(String) : t == null ? [] : [String(t)];
+}
+/**
+ * Combine a page's existing json_ld string with a new node. Nodes of the same
+ * @type are replaced; other nodes are kept. Returns the json_ld string to
+ * store. An existing value that is not a JSON object/array is refused rather
+ * than silently overwritten.
+ */
+export function mergeJsonLd(existing, node) {
+    const raw = typeof existing === 'string' ? existing.trim() : '';
+    let nodes = [];
+    if (raw) {
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch {
+            throw new StructuredDataError(['json_ld: the page\'s existing json_ld is not valid JSON. Read the page, then fix or clear json_ld with update_page before adding structured data.']);
+        }
+        const list = Array.isArray(data) ? data
+            : data && typeof data === 'object' && Array.isArray(data['@graph']) ? data['@graph']
+                : [data];
+        if (!list.every((n) => n && typeof n === 'object' && !Array.isArray(n))) {
+            throw new StructuredDataError(['json_ld: the page\'s existing json_ld is not a JSON-LD object or list of objects. Fix or clear it with update_page first.']);
+        }
+        nodes = list;
+    }
+    const newTypes = typesOf(node);
+    const kept = nodes.filter((n) => !typesOf(n).some((t) => newTypes.includes(t)));
+    const replaced = nodes.length - kept.length;
+    if (!kept.length)
+        return { json_ld: JSON.stringify(node), replaced, kept: 0 };
+    const strip = ({ '@context': _context, ...rest }) => rest;
+    return {
+        json_ld: JSON.stringify({ '@context': CONTEXT, '@graph': [...kept.map(strip), strip(node)] }),
+        replaced,
+        kept: kept.length,
+    };
+}

package/dist/tools/access.js

@@ -1,7 +1,8 @@
-// Access tools — API keys, cross-organization site sharing and organization
-// invites. Each wraps the authenticated public API with the same permission
-// checks as the portal: a key never mints a key or a grant that reaches
-// further than it does.
+// Access tools — API keys, cross-organization site sharing, organization
+// invites and the Organization's own AI key for the portal assistant. Each
+// wraps the authenticated public API with the same permission checks as the
+// portal: a key never mints a key or a grant that reaches further than it
+// does.
 import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
 const keyId = z.string().regex(/^[a-f0-9]{12}$/).describe('Key id (the 12-hex prefix) from list_api_keys / list_organization_api_keys.');
@@ -72,4 +73,35 @@ export const accessTools = [
         inputSchema: { ttl_days: z.number().int().min(1).max(30).optional() },
         handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('organization/invites', args))),
     },
+    {
+        name: 'read_organization_ai_settings',
+        noSite: true,
+        description: 'Read the Organization\'s built-in AI assistant settings: whether its own Anthropic API key is set (last four characters, verified_at, who set it and when — never the key), site_access ({ mode: "all" | "selected", site_ids }) and every Site of the Organization with ai_enabled. The portal AI chat appears only on Sites with ai_enabled. This setting never limits MCP or the API: you can edit every Site you have access to. Requires an organization API key, or a personal connection in an Organization where the person is an owner or admin.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client }) => ok(await client.rootGet('organization/ai'))),
+    },
+    {
+        name: 'set_organization_ai_key',
+        noSite: true,
+        description: 'Add or replace the Organization\'s own Anthropic API key for the portal\'s built-in AI assistant. Typeroll checks the key with Anthropic before saving: a rejected key returns 422 ai_key_rejected and an unreachable Anthropic 502 ai_key_unverified, and nothing is stored. The key is stored encrypted and never returned. A first key enables no Sites; replacing a key keeps the Site choice. Only call this with a key the user gave you for this purpose and their explicit go-ahead; prefer that an owner or admin enters it in the portal (Organization settings → AI assistant) so it does not pass through this conversation. Never repeat the key back. Requires an organization API key.',
+        inputSchema: { api_key: z.string().min(20).max(512).describe('The Anthropic API key (starts with sk-ant-).') },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPut('organization/ai/key', { api_key: args.api_key }))),
+    },
+    {
+        name: 'remove_organization_ai_key',
+        noSite: true,
+        description: 'Remove the Organization\'s Anthropic API key. The portal AI chat disappears from every Site and the Site choice starts over; MCP and the API are unaffected. Requires an organization API key and the user\'s explicit go-ahead.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client }) => ok(await client.rootDelete('organization/ai/key'))),
+    },
+    {
+        name: 'set_organization_ai_site_access',
+        noSite: true,
+        description: 'Choose which of the Organization\'s own Sites show the portal AI chat: mode "all" (every Site, including Sites created later) or mode "selected" with site_ids from read_organization_ai_settings (an empty list turns it off everywhere). A Site shared in from another Organization follows that owner\'s setting. Needs a key first (409 ai_key_required). Requires an organization API key.',
+        inputSchema: {
+            mode: z.enum(['all', 'selected']),
+            site_ids: z.array(z.string()).max(1000).optional().describe('Required when mode is "selected".'),
+        },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPut('organization/ai/site-access', args.mode === 'all' ? { mode: 'all' } : { mode: 'selected', site_ids: args.site_ids ?? [] }))),
+    },
 ];

package/dist/tools/apps.js

@@ -15,7 +15,8 @@ export const appTools = [
     },
     {
         name: 'read_app',
-        description: 'Read one Typeroll app by registry id, including its field schema and masked state. Use list_apps to discover ids and required config fields. Secret values are never returned. For setup guidance without admin access, use read_app_documentation. Admin permission required.',
+        description: 'Read one Typeroll app by registry id, including its field schema and masked state. Use list_apps to discover ids and required config fields. Secret values are never returned. For setup guidance without admin access, use read_app_documentation. Admin permission required. ' +
+            'For analytics, `setup` reports its Cloudflare Web Analytics site: status "ready" with the account it lives in (`account.owner` "organization" = the Cloudflare account of the site\'s Hosting Group, used for customer publishing; "installation" = the installation\'s own account, used for managed and self-hosted sites), or "action_required" with `code`, `message`, `next_step` and optional `settings_url`.',
         inputSchema: {
             app_id: z.string().min(1).describe('Registry id returned by list_apps, for example analytics or integrations.'),
         },
@@ -25,7 +26,9 @@ export const appTools = [
     },
     {
         name: 'update_app',
-        description: 'Enable, configure, or disable any registered Typeroll app through the same admin API key used for publishing. Read the app first and send config keys from its field schema. Omitted fields preserve existing values, including encrypted secrets; secret values are masked on reads and encrypted server-side on writes. Analytics provisioning runs server-side when enabled. If affects_build is true, trigger_deploy is required to publish the change. For setup guidance without admin access, use read_app_documentation. Admin permission required.',
+        description: 'Enable, configure, or disable any registered Typeroll app through the same admin API key used for publishing. Read the app first and send config keys from its field schema. Omitted fields preserve existing values, including encrypted secrets; secret values are masked on reads and encrypted server-side on writes. If affects_build is true, trigger_deploy is required to publish the change. For setup guidance without admin access, use read_app_documentation. Admin permission required. ' +
+            'Analytics: enabling creates the Cloudflare Web Analytics site in the account that hosts the site (customer publishing: the Hosting Group\'s Cloudflare connection, never the installation\'s account) and fills beacon_token and site_tag; a pasted beacon_token is resolved to its site_tag in that same account. ' +
+            'When no beacon could be set up, the call fails with HTTP 409, a stable `code` (for example analytics_cloudflare_access_required, analytics_cloudflare_connection_required, analytics_host_required, analytics_provider_error, analytics_token_not_in_account) and `details.next_step`; `details.saved` says whether the enabled state was stored. Relay the next step to the person (approving Analytics access needs an organization owner or admin in the browser), then call update_app again. A 200 response carries `setup` too.',
         inputSchema: {
             app_id: z.string().min(1).describe('Registry id returned by list_apps.'),
             enabled: z.boolean(),

package/dist/tools/domain.js

@@ -190,22 +190,26 @@ export const domainTools = [
     },
     {
         name: 'approve_publishing_domain_cutover',
-        description: 'Approve switching website traffic to the verified frozen deployment. Read publishing domains first and review DNS requirements and certificate readiness. Existing traffic is preserved until validation succeeds. External DNS management remains the caller’s responsibility.',
-        inputSchema: { revision: z.string(), candidate_id: z.string() },
+        description: 'Approve switching website traffic to the verified frozen deployment. Read publishing domains first and review DNS requirements, certificate readiness and redirect_preparations. Existing traffic is preserved until validation succeeds. With automatic DNS, redirect hosts switch after the website host: Typeroll ensures their zone redirect rule, then changes their reviewed record to a proxied placeholder. The publication goes live only after every redirect host answers 301 to the website host with the same path and query. When preparation.validation_blocker.resolution is accept_validation_window, Cloudflare can validate the website host only after its one existing record points at Pages: approving with accept_validation_window: true lets Typeroll change that record, and the host does not answer until Cloudflare validates it (Cloudflare does not document how long; previous_records holds the rollback). Get the user\'s explicit go-ahead for that window and choose a quiet time. External DNS management remains the caller’s responsibility.',
+        inputSchema: {
+            revision: z.string(), candidate_id: z.string(),
+            accept_validation_window: z.boolean().optional().describe('Accept the interruption until Cloudflare validates the website host after its single reviewed record changes. Only valid when preparation.validation_blocker.resolution is accept_validation_window.'),
+        },
         handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, 'publishing/cutover', args))),
     },
     {
         name: 'read_publishing_domains',
-        description: 'Read the desired and active website and media hosts, retained media aliases, DNS management mode and domain configuration revision. Saving intent does not switch traffic.',
+        description: 'Read the desired and active website, redirect and media hosts, retained media aliases, DNS management mode and domain configuration revision. host_checks lists each future host with its Cloudflare zone and structured blockers and warnings (code, host, message), for example apex_zone_required (an apex such as example.com needs an active Cloudflare zone in the hosting account), zone_not_active (the zone is pending until its nameservers change) or redirect_zone_required. Resolve blockers before preparing. preparation and redirect_preparations hold DNS records, the zone redirect rule and certificate state after preparation. Saving intent does not switch traffic.',
         inputSchema: {},
         handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'publishing/domains'))),
     },
     {
         name: 'set_publishing_domains',
-        description: 'Save future website and media hosts before preparing a deployment. Requires the current revision from read_publishing_domains. This does not publish content or change traffic DNS. Choose external DNS when your agent manages Cloudflare independently.',
+        description: 'Save future website, redirect and media hosts before preparing a deployment. Requires the current revision from read_publishing_domains. This does not publish content or change traffic DNS. Choose external DNS when your agent manages Cloudflare independently. redirect_hosts (for example www.example.com when example.com is the website host) answer 301 to the website host, keeping path and query, through a Single Redirect rule in the host\'s Cloudflare zone; they are switched and verified with the website. The response includes host_checks: resolve its blockers before preparing.',
         inputSchema: {
             revision: z.string(), website_host: z.string().nullable(), media_host: z.string().nullable(),
             media_path_prefix: z.string().optional().describe('Empty on a separate media host; /media when using the website host.'),
+            redirect_hosts: z.array(z.string()).max(4).optional().describe('Hostnames that redirect permanently to website_host, such as www.example.com. Omit or send [] for none.'),
             dns_mode: z.enum(['automatic', 'external']),
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.put(siteId, 'publishing/domains', args))),

package/dist/tools/migration.js

@@ -233,7 +233,7 @@ export const migrationTools = [
     },
     {
         name: 'get_migration_launch_report',
-        description: 'Return the launch decision report with separate inventory, exclusion-reason, internal-link, deployed URL parity, deploy freshness, reviewed SEO/content parity and migration fidelity requirements. launch_ready is false when any evidence is absent, incomplete, failed, targets an old origin, or predates the latest hosted deploy. Use this final gate instead of treating zero unhandled URLs as launch readiness.',
+        description: 'Return the launch decision report with separate inventory, exclusion-reason, internal-link, deployed URL parity, deploy freshness, reviewed SEO/content parity, migration fidelity and script requirements. scripts lists copied source-platform scripts (WordPress plugins, theme, jQuery, page builders, cookie plugins), tracking code outside the consent gate, and analytics/advertising integrations without the cookie banner; each blocks launch. launch_ready is false when any evidence is absent, incomplete, failed, targets an old origin, or predates the latest hosted deploy. Use this final gate instead of treating zero unhandled URLs as launch readiness.',
         handler: withErrorBoundary(async (_args, { client, siteId }) => {
             const res = await client.get(siteId, 'migration-report');
             return ok(res);

package/dist/tools/settings.js

@@ -64,8 +64,8 @@ export const settingsTools = [
             sitewide_nofollow: z.boolean().optional().describe('Ask search engines not to follow links. Defaults to false.'),
             image_sizes_default: z.string().optional().describe('Site-wide default `sizes` attribute for responsive-image <picture> output, e.g. "(max-width: 640px) 360px, 560px". Tells the browser how wide images actually render so it stops over-fetching the larger srcset variant. A page can override via its own image_sizes_default; a per-<img> `sizes` attribute wins over both. Leave unset for the generic "(max-width: 768px) 100vw, 800px".'),
             // Scriptable surfaces. Trusted because the caller has an API key.
-            scripts_head: z.string().optional().describe('Raw HTML injected into <head> on every page. Use for analytics, fonts, third-party CSS links.'),
-            scripts_body_end: z.string().optional().describe('Raw HTML injected just before </body> on every page. Use for chat widgets, deferred analytics.'),
+            scripts_head: z.string().optional().describe('Raw HTML injected into <head> on every page, before consent. Use for fonts and third-party CSS links. Not for analytics or advertising tags: set those by ID in the Integrations app with cookie_consent enabled (or, for a tag the catalog lacks, cookie_consent.scripts_optional). In a migration, never copy the source site\'s plugin, theme or WordPress scripts here.'),
+            scripts_body_end: z.string().optional().describe('Raw HTML injected just before </body> on every page, before consent. Use for small site-owned scripts. Not for analytics or advertising tags (Integrations app with cookie_consent enabled) or for scripts copied from the source site in a migration.'),
             custom_css: z.string().optional().describe('Global CSS in a <style> in <head>, after block CSS and before the page\'s own custom CSS and the template base stylesheet (reset + global). Base rules for :root tokens (spacing, radius, container widths), body font and line-height load after it, so override those with a more specific selector (for example html:root or body.page) rather than a bare :root/body rule. Preview uses the same order. Lets you define site-wide design tokens (CSS variables, @media queries, :hover states) without inlining on every element. Prefer named styles (create_style) for anything a style can express. Syntax errors (unbalanced braces, unclosed comments or strings, expression()/javascript:) refuse the write; selectors on platform markup ([data-block], .block-*) come back as warnings because they can change between render versions — target s-<style> classes or block custom_class instead.'),
             default_og_image: z.string().optional().describe('Site-wide fallback og:image URL for pages without their own social image. Empty string clears.'),
             twitter_handle: z.string().optional().describe('Twitter/X handle for twitter:site, with or without the leading @ (stored without it). Empty string clears.'),

package/dist/tools/sites.js

@@ -53,7 +53,7 @@ export const siteTools = [
     },
     {
         name: 'get_site_insights',
-        description: 'Read Analytics insights over the last 7, 30, or 90 days: traffic, AI-assistant referrals, and first-party conversion events grouped by event, destination, source, and campaign. Traffic is powered by Cloudflare Web Analytics; conversions come from validated attribution-funnel click events. The response carries a traffic `status`: "ok" with numbers, or "app_disabled" / "not_configured" / "no_site_tag" / "no_data". Conversion data can still be present when the traffic provider is unavailable.',
+        description: 'Read Analytics insights over the last 7, 30, or 90 days: traffic, AI-assistant referrals, and first-party conversion events grouped by event, destination, source, and campaign. Traffic is powered by Cloudflare Web Analytics; conversions come from validated attribution-funnel click events. The response carries a traffic `status`: "ok" with numbers, "no_data" for a linked site without traffic, or "app_disabled" / "not_configured" / "no_site_tag" / "connection_required" / "access_required" / "account_mismatch" / "provider_error" with a `reason` ({code, message, next_step, settings_url}). Traffic is read from the same Cloudflare account the beacon belongs to (`account`): the site\'s Hosting Group account for customer publishing, the installation\'s account otherwise. Conversion data can still be present when the traffic provider is unavailable.',
         inputSchema: {
             days: z.union([z.literal(7), z.literal(30), z.literal(90)]).optional().describe('Look-back window in days (default 30).'),
         },

package/dist/tools/structured-data.js

@@ -0,0 +1,64 @@
+// Structured-data tools: FAQPage, Recipe and Event JSON-LD on a page.
+//
+// The same inputs, validation and builders as the portal AI chat's tools of
+// the same names (../structured-data.ts). Each tool reads the page's draft
+// view, merges the new node into its json_ld (same @type replaced, others
+// kept) and writes json_ld back through update_page's route, so the change
+// follows the buffer model like any other content write.
+import { z } from 'zod';
+import { ok, versionParam, withErrorBoundary } from './helpers.js';
+import { mergeJsonLd, STRUCTURED_DATA, StructuredDataError } from '../structured-data.js';
+const DESCRIPTIONS = {
+    faq: 'Add FAQPage JSON-LD to a page that visibly presents these questions and answers (Google penalizes FAQ markup for content the page does not show). Copy the questions and answers from the page.',
+    recipe: 'Add Recipe JSON-LD to a recipe page: name, ingredients and steps (required), plus description, image, author, ISO 8601 durations (PT30M) and yield.',
+    event: 'Add Event JSON-LD to a page about one upcoming event: name and ISO 8601 start_date with UTC offset (required), end, place, image and ticket offer. A price needs offers_currency.',
+};
+const COMMON = ' Validates the input and builds the schema.org JSON-LD for you; prefer this to hand-writing json_ld. It is merged into the page\'s json_ld: an existing node of the same @type is replaced, other nodes (e.g. LocalBusiness) are kept in an @graph. Returns the stored JSON-LD and warnings about rich-result eligibility. BUFFER MODEL: lands in the page\'s unsaved draft; pass save:true or commit_working_copy after the user approves. Needs write permission.';
+function v(version) {
+    return version ? { version } : undefined;
+}
+function invalid(error) {
+    return { content: [{ type: 'text', text: JSON.stringify({ error: error.message, issues: error.issues }, null, 2) }], isError: true };
+}
+export const structuredDataTools = Object.keys(STRUCTURED_DATA).map((kind) => {
+    const spec = STRUCTURED_DATA[kind];
+    return {
+        name: spec.tool,
+        description: DESCRIPTIONS[kind] + COMMON,
+        inputSchema: {
+            page_id: z.string().min(1),
+            ...spec.shape,
+            save: z.boolean().optional().describe('Also save (commit) the draft in the same call, for a change the user already approved.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { page_id, save, version, ...input } = args;
+            let built;
+            let merged;
+            const path = `pages/${encodeURIComponent(page_id)}`;
+            try {
+                built = spec.build(input);
+                // The draft view, so an unsaved json_ld edit is merged, not lost.
+                const current = await client.get(siteId, path, v(version));
+                merged = mergeJsonLd(current.page?.json_ld, built.node);
+            }
+            catch (error) {
+                if (error instanceof StructuredDataError)
+                    return invalid(error);
+                throw error;
+            }
+            await client.patch(siteId, path, { json_ld: merged.json_ld, ...(save ? { save: true } : {}) }, v(version));
+            return ok({
+                ok: true,
+                page_id,
+                schema_type: spec.type,
+                replaced_same_type: merged.replaced,
+                kept_other_nodes: merged.kept,
+                saved: !!save,
+                warnings: built.warnings,
+                json_ld: JSON.parse(merged.json_ld),
+                next: save ? 'Saved. Deploy when the user wants it live.' : 'Unsaved draft: preview with get_preview_link include_working_copy:true, then save with commit_working_copy when approved.',
+            });
+        }),
+    };
+});

package/dist/tools/workflows.js

@@ -4,6 +4,10 @@
 // Site together with its first workflow.
 import { z } from 'zod';
 import { ok, versionParam, withErrorBoundary } from './helpers.js';
+// Run by the portal with the Organization's own AI key; without access for the
+// Site the run fails with failure_code ai_not_enabled. The agent then does the
+// work itself with the named recipe instead of retrying.
+const AI_WORKFLOWS = 'AI workflows — site_planning, content_generation, content_improvement and schema_markup — call the model with the Organization\'s own AI key and need AI access for this Site; without it the run fails with failure_code "ai_not_enabled" (failure_reason: the AI assistant is not enabled for this site). Do not retry or work around it: you are an AI agent, so do the same work yourself and tell the user you did — site_planning: tr-new-site (propose the page structure, get approval, then build); content_generation: tr-content-write (draft page); content_improvement: tr-content-write on the weakest published pages (thin text, missing seo_title/seo_description, stale), as unsaved drafts for review; schema_markup: tr-seo step 5 (add_faq_schema, add_recipe_schema, add_event_schema or json_ld). seo_audit still runs without AI and returns its issue list unprioritized. Enabling the portal AI is the Organization owner\'s or admin\'s choice, never a prerequisite for you.';
 const WORKFLOW_TYPES = [
     'migration', 'site_planning', 'seo_audit', 'content_improvement', 'link_check',
     'performance_audit', 'content_generation', 'schema_markup', 'url_parity', 'rebuild_deploy',
@@ -11,13 +15,13 @@ const WORKFLOW_TYPES = [
 export const workflowTools = [
     {
         name: 'list_workflows',
-        description: 'List the workflow types this Site can run (label, description, steps, required_permission) and its most recent runs with status. Read only. Migration, site planning and URL parity pause for review; check get_workflow for paused_for_review.',
+        description: 'List the workflow types this Site can run (label, description, steps, required_permission) and its most recent runs with status. Read only. Migration, site planning and URL parity pause for review; check get_workflow for paused_for_review. Site planning, content generation, content improvement and schema markup need the Organization\'s AI key for this Site (see start_workflow).',
         inputSchema: { limit: z.number().int().min(1).max(100).optional() },
         handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, 'workflows', args.limit ? { limit: args.limit } : undefined))),
     },
     {
         name: 'start_workflow',
-        description: 'Start a server-side workflow on this Site; it runs in the background and returns workflow_id. Poll get_workflow. Config per type (same fields as the portal form): migration { wp_url, helper_api_key? } (needs verified organization import storage); site_planning { business_description }; content_generation { topic, tone?, audience? }; content_improvement { limit? }; url_parity { target_origin?, source_origin?, check_source?, statuses? }; rebuild_deploy { environment: staging | production }; seo_audit, link_check, performance_audit and schema_markup take none. Needs write permission; rebuild_deploy publishes and needs admin. Workflows that change content write to the given version (default main) — get the user\'s agreement first.',
+        description: 'Start a server-side workflow on this Site; it runs in the background and returns workflow_id. Poll get_workflow. Config per type (same fields as the portal form): migration { wp_url, helper_api_key? } (needs verified organization import storage); site_planning { business_description }; content_generation { topic, tone?, audience? }; content_improvement { limit? }; url_parity { target_origin?, source_origin?, check_source?, statuses? }; rebuild_deploy { environment: staging | production }; seo_audit, link_check, performance_audit and schema_markup take none. Needs write permission; rebuild_deploy publishes and needs admin. Workflows that change content write to the given version (default main) — get the user\'s agreement first. ' + AI_WORKFLOWS,
         inputSchema: {
             type: z.enum(WORKFLOW_TYPES),
             config: z.record(z.unknown()).optional(),
@@ -27,7 +31,7 @@ export const workflowTools = [
     },
     {
         name: 'get_workflow',
-        description: 'Read one workflow run: status (pending | running | paused_for_review | completed | failed), current step, progress, log, review_message/review_data when paused, results and failure_reason. Credential config is masked.',
+        description: 'Read one workflow run: status (pending | running | paused_for_review | completed | failed), current step, progress, log, review_message/review_data when paused, results, failure_reason and failure_code (newer Core; older Core reports failure_reason only). Credential config is masked. failure_code "ai_not_enabled" (or a failure_reason saying the AI assistant is not enabled for this site) means the Site has no portal AI access: do the work yourself with the recipe named in start_workflow instead of retrying.',
         inputSchema: { workflow_id: z.string() },
         handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, `workflows/${encodeURIComponent(args.workflow_id)}`))),
     },
@@ -51,7 +55,7 @@ export const workflowTools = [
     {
         name: 'create_site_and_plan',
         noSite: true,
-        description: 'Create a new Site in the Organization and start AI site planning from a business description, like "Plan a new site with AI" on the New site page. Requires an organization API key. The plan pauses for review: read it with get_workflow and approve_workflow only after the user agrees.',
+        description: 'Create a new Site in the Organization and start AI site planning from a business description, like "Plan a new site with AI" on the New site page. Requires an organization API key. Needs the Organization\'s own AI key with site access "all" (read_organization_ai_settings); otherwise it answers 403 ai_not_enabled and creates nothing — then create_site a blank Site and plan it yourself with tr-new-site (propose the pages, get the user\'s approval, build), and say that you did; enabling the portal AI is the owner\'s or admin\'s choice, not a prerequisite. The plan pauses for review: read it with get_workflow and approve_workflow only after the user agrees.',
         inputSchema: {
             name: z.string().min(1),
             business_description: z.string().min(1).describe('What the business does, for whom, and what sets it apart.'),

package/dist/version.js

@@ -8,4 +8,4 @@
 //
 // Keep it in lockstep with package.json: tests/version.test.ts asserts
 // VERSION === package.json.version, so a bump that forgets this line fails CI.
-export const VERSION = '0.45.64';
+export const VERSION = '0.45.66';

package/dist/workspace.js

@@ -57,6 +57,17 @@ Public documentation: https://typeroll.com/docs/llms.txt
 - Never edit generated publishing source to change CMS content. Do not overwrite
   current CMS or owner answers from an old local snapshot.
 
+## Everyday requests
+
+- Links, images, menus, settings, analytics and site-wide changes: read the
+  tr-edit-site recipe. Shared content becomes one global block, not N edits.
+- FAQ, recipe and event pages: add_faq_schema, add_recipe_schema and
+  add_event_schema build validated JSON-LD (see tr-seo); don't hand-write it.
+- A blank site or the starter design: tr-starter-design lists its variables.
+- The portal's built-in AI is optional. When an AI workflow (site planning,
+  content generation or improvement, schema markup) reports ai_not_enabled,
+  do the work yourself with the recipe it names and say so; don't retry.
+
 Store credentials in the client's private settings or injected environment.
 Run the workspace doctor after setup and after changing the binding.
 `;
@@ -69,7 +80,7 @@ export const workspaceTemplates = {
     'decisions.md': '# Decisions\n\nRecord date, decision, reason, approved scope and alternatives when useful.\n',
     'sources/README.md': '# Sources\n\nStore research references and copy proposals. Record source URLs and dates.\nPrivate extracts belong in ignored private/ or an approved external store.\nDo not treat local drafts as current CMS content or commit media libraries.\n',
     'scripts/README.md': '# Project automation\n\nKeep repeatable imports and QA scripts here. Use the authenticated REST API\nfor scripted work; keep credentials outside files and inject them at runtime.\nMCP remains the interactive interface. Typeroll currently has no general site CRUD CLI.\n',
-    'qa/checklist.md': '# Verification\n\n- Confirm Site, Version and deployed/source identity.\n- Read back saved content and inspect desktop/mobile previews.\n- Exercise menus, keyboard focus, links and enabled app states.\n- Verify routes, metadata, media and publishing readiness before launch.\n- Record tested pages, viewports, results and unresolved issues.\n- Store screenshots and private runtime reports in ignored reports/.\n- Publishing validation does not prove visual or editorial completeness.\n',
+    'qa/checklist.md': '# Verification\n\n- Confirm Site, Version and deployed/source identity.\n- Read back saved content and inspect desktop/mobile previews.\n- Exercise menus, keyboard focus, links and enabled app states.\n- Verify routes, metadata, media and publishing readiness before launch.\n- Check that structured data (FAQ, recipe, event) matches what each page shows.\n- Record tested pages, viewports, results and unresolved issues.\n- Store screenshots and private runtime reports in ignored reports/.\n- Publishing validation does not prove visual or editorial completeness.\n',
 };
 export async function readWorkspace(dir) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.45.64",
+  "version": "0.45.66",
   "description": "Typeroll CMS MCP server – connect AI agents to the REST API to manage content and publish static websites.",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,9 @@
     "./server": "./src/server.ts",
     "./client": "./src/client.ts",
     "./version": "./src/version.ts",
-    "./tools/helpers": "./src/tools/helpers.ts"
+    "./tools/helpers": "./src/tools/helpers.ts",
+    "./structured-data": "./src/structured-data.ts",
+    "./bundled-content": "./src/bundled-content.ts"
   },
   "files": [
     "dist",
@@ -47,7 +49,7 @@
   },
   "devDependencies": {
     "typescript": "^5.6.0",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.12"
   },
   "publishConfig": {
     "access": "public"

package/skills/README.md

@@ -30,6 +30,8 @@ instructions. Read the relevant recipe when the task calls for it.
 
 | File | When it triggers | What it does |
 |---|---|---|
+| `tr-edit-site.md`      | "change this page", "add a link to the menu", "put our phone number on every page" | Confirm the site, find the page, everyday requests (links, images, menus, site-wide changes as global blocks, settings, analytics), preview and save. |
+| `tr-starter-design.md` | blank site, or one that still follows the starter design | The default CSS variables, spacing, radii, container and header/footer conventions to match. |
 | `tr-new-site.md`       | "create a new site", "bootstrap a site for…"        | Settings → header/footer partials → homepage → inner pages → deploy. Full setup recipe. |
 | `tr-brand.md`          | "create a brand", "choose colors", "design the look"| Palette recipes by mood, typography pairings, CSS variable setup, preview. |
 | `tr-redesign-branch.md`| "redesign", "modernize", anything site-wide-design   | Branch-isolated work with preview links, merge when approved. |
@@ -45,7 +47,7 @@ instructions. Read the relevant recipe when the task calls for it.
 | `tr-forms.md`             | "contact form", "add a form", "booking form"           | Form definition → embed HTML with signed token → inline JS feedback → deploy. |
 | `tr-custom-blocks.md` | "make a block for…", "icon list", a section shape the core blocks lack | Starter or composition from core blocks with fields and bindings → validate → preview → create → place. |
 | `tr-page-template.md` | Reusable Page templates: audio players, chapter lists, guest cards, image galleries — anything needing loops/nested data | Compose native blocks around `template_content_slot`; bind Page metadata, structured fields and references. |
-| `tr-seo.md`               | "SEO", "meta descriptions", "structured data"          | Audit → fix titles/descriptions → OG images → JSON-LD → robots.txt → deploy. |
+| `tr-seo.md`               | "SEO", "meta descriptions", "structured data", "FAQ schema" | Audit → fix titles/descriptions → URL conventions → OG images → JSON-LD (`add_faq_schema`, `add_recipe_schema`, `add_event_schema`) → robots.txt → deploy. |
 
 ### Import content