@typeroll/mcp-server 0.45.65 → 0.45.67

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';
@@ -141,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
@@ -178,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.
@@ -194,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/apps.js

@@ -28,7 +28,7 @@ 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. 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.',
+            '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 Cloudflare permissions needs an organization owner or admin in the browser: one "Approve update" per Cloudflare account on the Publishing page, or on older deployments "Approve Analytics access" on the module), then call update_app again. A 200 response carries `setup` too. Check diagnose_organization_cloudflare_connection permissions first to see whether the hosting account may create Web Analytics sites. To choose several Sites at once use set_organization_analytics.',
         inputSchema: {
             app_id: z.string().min(1).describe('Registry id returned by list_apps.'),
             enabled: z.boolean(),
@@ -41,4 +41,18 @@ export const appTools = [
             }));
         }),
     },
+    {
+        name: 'list_organization_analytics', noSite: true,
+        description: 'List every active Site of the Organization with Analytics on or off, its Hosting Group and setup (ready, or code, message and next_step), plus cloudflare_permissions: per Hosting Group, whether its Cloudflare connection may create Web Analytics sites (analytics_provisioning), read reports (analytics_reports) and create redirect rules (redirect_rules), the exact missing scopes and the one permission update. Approving Cloudflare permissions enables Analytics for no Site. Requires an organization API key; never returns beacon tokens or credentials.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client }) => ok(await client.rootGet('organization/analytics'))),
+    },
+    {
+        name: 'set_organization_analytics', noSite: true,
+        description: 'Turn Analytics on or off for the chosen Sites of the Organization (at most 50 per call). Only listed Sites change. Each runs the same path as update_app: enabling creates the Site\'s Cloudflare Web Analytics site in its hosting account and fills beacon_token and site_tag; the beacon appears after the Site\'s next publication (trigger_deploy). Returns one result per Site: status ready, action_required (with code, message, next_step and settings_url; Analytics is saved as on), disabled, or error (nothing changed). Ask the person which Sites to measure before enabling. Requires an organization API key.',
+        inputSchema: {
+            sites: z.array(z.object({ site_id: z.string().min(1), enabled: z.boolean() })).min(1).max(50).describe('Sites to change, by site_id from list_organization_analytics.'),
+        },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('organization/analytics', { sites: args.sites }))),
+    },
 ];

package/dist/tools/domain.js

@@ -30,7 +30,7 @@ export const domainTools = [
     },
     {
         name: 'read_organization_publishing_connections', noSite: true,
-        description: 'Read the Organization\'s GitHub and Cloudflare publishing connections: status, revision (needed to change or disconnect), account identity, media_ready, media migration, github_setup (app_configured, encryption_available) and connect_urls. Requires an organization API key; never returns credentials. GitHub sign-in/App installation and Cloudflare OAuth need a person in a browser: give the user the matching connect_urls link (an organization owner or admin completes it), then read again. When GitHub is not connected, call diagnose_organization_github_connection to learn why and who must act; for Cloudflare, call diagnose_organization_cloudflare_connection.',
+        description: 'Read the Organization\'s GitHub and Cloudflare publishing connections: status, revision (needed to change or disconnect), account identity, media_ready, media migration, github_setup (app_configured, encryption_available) and connect_urls. Requires an organization API key; never returns credentials. GitHub sign-in/App installation and Cloudflare OAuth need a person in a browser: give the user the matching connect_urls link (an organization owner or admin completes it), then read again. When GitHub is not connected, call diagnose_organization_github_connection to learn why and who must act; for Cloudflare, call diagnose_organization_cloudflare_connection. cloudflare_permissions lists, per Hosting Group, the optional capabilities of its Cloudflare connection (analytics_provisioning, analytics_reports, redirect_rules) with status available, approval_required, not_offered, unknown (API token) or connection_required, the exact missing_scopes, and permission_update: one "Approve update" at connect_url that an owner or admin approves once for every connection of the Organization using that Cloudflare account. Read it before update_app (Analytics) or set_publishing_domains (redirect_hosts).',
         inputSchema: {},
         handler: withErrorBoundary(async (_args, { client }) => ok(await client.rootGet('publishing/connections'))),
     },
@@ -75,7 +75,7 @@ export const domainTools = [
     },
     {
         name: 'diagnose_organization_cloudflare_connection', noSite: true,
-        description: 'Explain why a Cloudflare hosting connection (the Organization\'s Default Hosting Group, or hosting_group_id from list_hosting_groups) is or is not working and who must do what next. Returns the Organization\'s state: diagnosis.outcome (connected, needs_attention, choose, action_required, sign_in_pending, sign_in_required, retryable_error or unavailable), blockers, and the saved account once connected. A person\'s unfinished sign-in and the Cloudflare accounts they authorized stay in their own browser session. Each blocker has a code (for example oauth_cancelled, permissions_missing with missing_permissions, pages_access_denied, account_choice_expired, locked_to_account), who must act (you = the person connecting, cloudflare_account_admin, organization_admin = owner or admin of the Organization that already uses a shared account, publisher = operator of this Typeroll installation, typeroll_admin), a message and one action: a dash.cloudflare.com or documentation link, or a browser step (sign_in, retry) completed at connect_url. Read only, except recheck: true re-verifies a saved connection (authorization renewal, account access, Cloudflare Pages access, granted permissions) with its own authorization. An API key cannot sign in to Cloudflare; relay the message and link to the user. Requires an organization API key; never returns credentials.',
+        description: 'Explain why a Cloudflare hosting connection (the Organization\'s Default Hosting Group, or hosting_group_id from list_hosting_groups) is or is not working and who must do what next. Returns the Organization\'s state: diagnosis.outcome (connected, needs_attention, choose, action_required, sign_in_pending, sign_in_required, retryable_error or unavailable), blockers, and the saved account once connected. A person\'s unfinished sign-in and the Cloudflare accounts they authorized stay in their own browser session. Each blocker has a code (for example oauth_cancelled, permissions_missing with missing_permissions, pages_access_denied, account_choice_expired, locked_to_account), who must act (you = the person connecting, cloudflare_account_admin, organization_admin = owner or admin of the Organization that already uses a shared account, publisher = operator of this Typeroll installation, typeroll_admin), a message and one action: a dash.cloudflare.com or documentation link, or a browser step (sign_in, retry) completed at connect_url. Read only, except recheck: true re-verifies a saved connection (authorization renewal, account access, Cloudflare Pages access, granted permissions) with its own authorization. An API key cannot sign in to Cloudflare; relay the message and link to the user. `permissions` reports the connection\'s optional capabilities (analytics_provisioning, analytics_reports, redirect_rules), their missing_scopes and the single permission_update next step; approving it enables Analytics for no Site. Requires an organization API key; never returns credentials.',
         inputSchema: {
             hosting_group_id: z.string().optional().describe('Omit for the organization (Default) connection.'),
             recheck: z.boolean().optional().describe('Re-verify a saved connection before answering.'),

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. 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 a blank Site and do the planning yourself, or ask an owner or admin to enable it. 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.65';
+export const VERSION = '0.45.67';

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.65",
+  "version": "0.45.67",
   "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",

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
 

package/skills/tr-content-write.md

@@ -115,6 +115,22 @@ shortening, adding a CTA, tweaking SEO description.
 Don't `update_page status:"published"` without an explicit "looks
 good, publish it" from the user. Same for `trigger_deploy`.
 
+## Instead of the content workflows
+
+`start_workflow` types `content_generation` and `content_improvement` run the
+model with the Organization's own AI key. On a Site without that access they
+fail with `failure_code: "ai_not_enabled"`; don't retry them. Do the work with
+this recipe and tell the user you did it yourself:
+
+- **Generate a page** (`content_generation { topic, tone?, audience? }`):
+  steps 1–5 for that topic, created as a draft.
+- **Improve content** (`content_improvement { limit? }`): `list_pages
+  status="published"` and `batch_read_pages`, rank the pages by thin text,
+  missing `seo_title`/`seo_description` and age (not updated for a year), and
+  rewrite the weakest few (five by default) in the site's voice. Keep facts,
+  URLs and structure; leave the rewrites as unsaved drafts and show previews
+  before anything is saved or published.
+
 ## SEO conventions worth knowing
 
 - **`kind: "article"`** for blog posts and news. Switches to

package/skills/tr-edit-site.md

@@ -1,6 +1,6 @@
 ---
 name: tr-edit-site
-description: Edit or create Typeroll pages with a person’s usual AI assistant. Confirm one site, find the right page, preview changes and save with permission.
+description: Edit or create Typeroll pages with a person’s usual AI assistant. Confirm one site, find the right page, handle everyday requests (page links, images, menus, site-wide changes, settings, analytics, structured data), preview changes and save with permission.
 ---
 
 # Work on one Typeroll site
@@ -33,6 +33,93 @@ description: Edit or create Typeroll pages with a person’s usual AI assistant.
    draft durable; saving and deploying are different actions. Publish only
    when authorized and readiness passes. Report the actual result and URL.
 
+## Everyday requests
+
+Read the page or global block first, change only what was asked, and keep
+everything else. When several pages fit the description, ask before editing.
+
+**Addresses and preview links.** `list_pages` and `read_page` return each
+page's `url` (its path). The public address is `get_site` → `urls.production`
+plus that path, and it serves the page only after it is published and
+deployed. Never invent a domain; when there is none, say why and offer a
+preview instead: `get_preview_link page_id=… include_working_copy:true` shows
+drafts and unpublished pages. Mint one link and reuse it while iterating.
+
+**Images the user provides.** Upload first: a URL with `upload_media_from_url`,
+a local file with `create_upload_url` (see `tr-images`); `list_media` finds
+existing ones. Use the returned CDN URL exactly. With a named target, place it
+there (`add_block` with `core/image` on a block page; an `<img>` with `alt` in
+`html_content` on an HTML page). Without one, ask what the image is for. Ask
+for alt text when none was given. Afterwards say in one sentence where it
+landed; to answer "has it been added?", read the page again rather than
+trusting the conversation.
+
+**Small edits and new pages.** Block pages: `get_page_blocks`, then
+`update_block` on the one block. HTML pages: `read_page`, then `update_page`
+with the complete `html_content`, never a fragment. New pages: `create_page`
+(draft by default) with a realistic start: heading, introduction and one
+section. A Page template is `update_page` `template` (an allowed ID, or null
+for the content type default). `discard_working_copy` throws an unsaved draft
+away. Publishing means saving the draft, `update_page` `status: "published"`
+(applies immediately) and, when the user wants it live now, `trigger_deploy`.
+
+**Site-wide changes are composition, not a series of page edits.** "Change
+every hero", "a CTA on every product page", "our phone number in every
+footer":
+
+1. `list_partials` shows what is already shared: header, footer and free
+   global blocks.
+2. If a fitting global block exists, edit it once. Run
+   `find_pages_using_block` first and tell the user the blast radius ("this
+   block is on 8 pages and one template — go ahead?"); a header or footer
+   among the results means every page.
+3. If nothing fits, propose a global block: `make_block_global` turns an
+   existing block into one, or `create_free_block` with a kebab-case ID. Place
+   it with `core/global_block` on block pages or `<x-include name="…" />` on
+   HTML pages. Layout that every Page of a type shares belongs in its Page
+   template (`tr-page-template`).
+4. Edit pages one by one only for content that really differs per page, such
+   as each page's SEO description. Confirm the page list first.
+
+"All 23 pages" or "every page" is a strong hint for a global block. Say what
+you will do and wait for confirmation before editing many pages.
+
+**Extract while you sweep.** Even when the user asked for per-page edits,
+pause when the same content is about to land on a third page and offer to
+make it a global block instead ("I'm adding the same CTA to several pages —
+make it a reusable `newsletter-cta` block so future edits happen once?").
+Check `list_partials` and `find_pages_using_block` first so you extend an
+existing block rather than create a duplicate.
+
+**Menu and footer.** `read_partial partial_id="header"`. In a block header,
+change the `core/navigation` block's `links` with `update_block`; in an HTML
+header, add the `<a href="/pricing">Pricing</a>` to the nav and write back the
+complete HTML with `update_partial`. The footer works the same way. Building
+either from scratch: `tr-header-footer`.
+
+**Settings, not page edits.** Brand colors, fonts, logo, icons and contact
+details are `update_site_settings` (admin), for example `colors.primary`. A new
+logo must be uploaded first. Analytics, advertising pixels and chat widgets
+are set by ID in the Integrations app (`read_app app_id="integrations"`, then
+`update_app`), not pasted as scripts; turn on the cookie banner
+(`update_site_settings` `cookie_consent: { enabled: true }`) so they wait for
+consent. Only a tag the Integrations catalog lacks goes in
+`cookie_consent.scripts_optional`. Both reach the site with the next deploy.
+
+**Redirects, forms, listings.** A renamed URL gets `create_redirect` (301
+unless the user says otherwise); changing a page's `path` creates one on save.
+Place forms with a `core/form` block or `<x-form id="…" />`, never a
+hand-written `<form>` (`tr-forms`). Lists of articles are a `core/page_list`
+block, never hand-written HTML (`tr-blog`).
+
+**Structured data.** For an FAQ, recipe or event page use `add_faq_schema`,
+`add_recipe_schema` or `add_event_schema` instead of hand-writing `json_ld`;
+see `tr-seo`.
+
+**When something is out of reach.** If a tool refuses, tell the user what they
+can do about it, not only the error. When no tool covers a request (billing,
+for example), say so plainly and point to the relevant portal page.
+
 ## Compact discovery
 
 Find tools with `search_tools`, inspect one schema with `describe_tool`, then