@typeroll/mcp-server 0.45.65 → 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';
@@ -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/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.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.65",
+  "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",

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

package/skills/tr-new-site.md

@@ -34,7 +34,13 @@ read_app_documentation when needed; do not bundle private app guides locally.
 No Site yet? Use hosted MCP with an Organization key and create_site, or create it
 in the portal. To start from an AI site plan instead of a blank Site, use
 create_site_and_plan, poll get_workflow and approve its structure review only
-with the user's consent. Read back its ID before editing. Use one explicit Site/Version for
+with the user's consent. That AI plan needs the Organization's own portal AI
+key for new Sites; without it the call answers `403 ai_not_enabled` and the
+`site_planning` workflow fails with `failure_code: "ai_not_enabled"`. Then plan
+it yourself: `create_site`, propose the site name, tagline and page list (title,
+slug, purpose, target keywords) from the business description, get the
+user's approval, and build with this recipe. Tell the user you planned it
+yourself; don't retry the workflow. Read back its ID before editing. Use one explicit Site/Version for
 related operations. Larger changes to an existing site should use a branch.
 
 Before importing content or a media library, require get_import_readiness to pass.