@typeroll/mcp-server 0.45.22 → 0.45.24

package/dist/client.js

@@ -16,6 +16,7 @@ export class ApiError extends Error {
     }
 }
 export class TyperollClient {
+    defaultVersion;
     baseUrl;
     apiKey;
     fetchImpl;
@@ -26,12 +27,15 @@ export class TyperollClient {
             throw new Error('apiKey is required');
         this.baseUrl = config.baseUrl.replace(/\/+$/, '');
         this.apiKey = config.apiKey;
+        this.defaultVersion = config.defaultVersion;
         this.fetchImpl = config.fetchImpl ?? globalThis.fetch.bind(globalThis);
     }
     /** Build the full URL for a path (relative to /api/v1/sites/{siteId}/...) */
     url(siteId, path, query) {
         const cleanPath = path.replace(/^\/+/, '');
         const url = new URL(`${this.baseUrl}/api/v1/sites/${encodeURIComponent(siteId)}/${cleanPath}`);
+        if (this.defaultVersion)
+            url.searchParams.set('version', this.defaultVersion);
         if (query) {
             for (const [k, v] of Object.entries(query)) {
                 if (v !== undefined && v !== null)

package/dist/compact-tools.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { fail, ok } from './tools/helpers.js';
+export const COMPACT_INSTRUCTIONS = `Typeroll CMS. Use search_tools to find a task's tools, describe_tool to read one exact schema, then call_read_tool, call_write_tool or call_admin_tool. Discover before you write: identify Site/Version, capabilities and enabled app documentation. Read only the relevant skill or guide section; do not load the full manual by default. Larger changes: create_branch and keep the same version. Working copy, saved content and live output differ. Publishing and other external effects require the user's authorization; tool access alone is not approval.`;
+/** Stable discovery surface: no dynamic registration or client list-change support needed. */
+export function compactTools(catalog) {
+    const byName = new Map(catalog.map(tool => [tool.name, tool]));
+    const local = (name, description, schema, invoke) => ({ name, description, schema, effect: 'read', invoke });
+    return [
+        local('search_tools', 'Find tools by name or task. Returns brief matches without schemas; use describe_tool next. Empty query lists names in pages.', {
+            query: z.string().max(200).default(''), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(12).default(8),
+        }, async (args) => {
+            const words = String(args.query).toLowerCase().split(/\s+/).filter(Boolean);
+            const matches = catalog.map(tool => ({ tool, score: words.reduce((sum, word) => sum + (tool.name === word ? 10 : tool.name.includes(word) ? 3 : tool.description.toLowerCase().includes(word) ? 1 : 0), 0) }))
+                .filter(item => !words.length || item.score > 0).sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name));
+            const offset = Number(args.offset), limit = Number(args.limit);
+            return ok({ tools: matches.slice(offset, offset + limit).map(({ tool }) => ({ name: tool.name, effect: tool.effect, description: tool.description.slice(0, 180) })), total: matches.length, next_offset: offset + limit < matches.length ? offset + limit : null });
+        }),
+        local('describe_tool', 'Read one tool’s complete description, effect and JSON input schema before calling it.', { name: z.string().max(100) }, async (args) => {
+            const tool = byName.get(String(args.name));
+            return tool ? ok({ name: tool.name, effect: tool.effect, description: tool.description, inputSchema: zodToJsonSchema(z.object(tool.schema), { $refStrategy: 'none' }) }) : fail(new Error('Unknown tool. Use search_tools.'));
+        }),
+        ...['read', 'write', 'admin'].map(effect => ({
+            name: `call_${effect}_tool`, effect,
+            description: effect === 'read' ? 'Call a discovered read-only tool with its exact arguments. Does not accept write/admin tools.' : `Call a discovered ${effect} tool. May ${effect === 'admin' ? 'change app configuration or activate releases' : 'save, delete, publish or otherwise change state'}. Inspect describe_tool first and follow the user’s authorization.`,
+            schema: { name: z.string().max(100), arguments: z.record(z.unknown()).default({}) },
+            invoke: async (args) => {
+                const tool = byName.get(String(args.name));
+                if (!tool || tool.effect !== effect)
+                    return fail(new Error(`This endpoint accepts only ${effect} tools. Use describe_tool to check the required effect.`));
+                try {
+                    return await tool.invoke(z.object(tool.schema).parse(args.arguments));
+                }
+                catch (error) {
+                    return fail(error);
+                }
+            },
+        })),
+    ];
+}

package/dist/index.js

@@ -20,12 +20,39 @@ import { resolveSiteId } from './resolve-site-id.js';
 import { buildServer } from './server.js';
 import { VERSION } from './version.js';
 import { runExtensionCli } from './extension-cli.js';
+import { doctor, readWorkspace, workspaceClient, verifyWorkspaceBinding } from './workspace.js';
 function bail(message) {
     console.error(`typeroll-mcp: ${message}`);
     process.exit(1);
 }
 async function main() {
     const argv = process.argv.slice(2);
+    if (argv[0] === 'doctor') {
+        const args = argv.slice(1);
+        if (args.includes('--help')) {
+            console.log('Usage: typeroll doctor [directory] [--offline] [--json]');
+            return;
+        }
+        if (args.some(arg => arg.startsWith('-') && !['--offline', '--json'].includes(arg)) || args.filter(arg => !arg.startsWith('-')).length > 1)
+            bail('Usage: doctor [directory] [--offline] [--json]');
+        const result = await doctor(args.find(arg => !arg.startsWith('-')) ?? '.', args.includes('--offline'));
+        console.log(args.includes('--json') ? JSON.stringify(result, null, 2) : result.checks.map(check => `${check.status}: ${check.check} — ${check.message}`).join('\n'));
+        process.exitCode = result.passed ? 0 : 1;
+        return;
+    }
+    if (argv[0] === 'workspace-mcp') {
+        if (argv.length > 2)
+            bail('Usage: workspace-mcp [directory]');
+        const config = await readWorkspace(argv[1] ?? '.');
+        const client = workspaceClient(config, process.env);
+        if (config.site_id)
+            await verifyWorkspaceBinding(config, client);
+        // An unbound workspace permits discovery/site creation only. Save the Site
+        // binding and reconnect before content operations; never guess a target.
+        const server = buildServer({ client, ...(config.site_id ? { fixedSiteId: config.site_id } : { allowedSites: [] }), toolMode: config.tool_mode, info: { name: 'typeroll', version: VERSION } });
+        await server.connect(new StdioServerTransport());
+        return;
+    }
     if (argv[0] === 'init') {
         const code = await runInitCli(argv.slice(1));
         process.exit(code);
@@ -41,12 +68,19 @@ async function main() {
     if (argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
         console.error('Usage:');
         console.error('  typeroll-mcp                              Start the MCP server (reads TYPEROLL_API_URL and TYPEROLL_API_KEY)');
-        console.error('  typeroll-mcp init [dir] [-f]              Bootstrap a project: skills + .mcp.json + AGENTS.md + imagegen lab');
+        console.error('  typeroll-mcp init [dir] [--update]              Create/update an agent-neutral workspace (see init --help)');
         console.error('  typeroll-mcp install-skills <dir> [-f]    Copy bundled skill files to <dir>');
+        console.error('  typeroll-mcp doctor [dir] [--offline]     Read-only workspace/connection checks');
+        console.error('  typeroll-mcp workspace-mcp [dir]          MCP bound to typeroll.json (compact by default)');
         console.error('  typeroll extension <command>              Validate, push, install, configure or promote an Extension');
         console.error('  typeroll-mcp --help                       Show this help');
         process.exit(0);
     }
+    if (argv.length)
+        bail('Unknown command. Use --help.');
+    const mode = process.env.TYPEROLL_MCP_TOOL_MODE ?? 'full';
+    if (!['full', 'compact'].includes(mode))
+        bail('TYPEROLL_MCP_TOOL_MODE must be full or compact.');
     const apiUrl = process.env.TYPEROLL_API_URL?.trim();
     const apiKey = process.env.TYPEROLL_API_KEY?.trim();
     if (!apiUrl)
@@ -67,6 +101,7 @@ async function main() {
     const server = buildServer({
         client,
         fixedSiteId: siteId,
+        toolMode: mode,
         info: { name: 'typeroll', version: VERSION },
     });
     const transport = new StdioServerTransport();

package/dist/init.js

@@ -1,257 +1,58 @@
-// `init` subcommand for the typeroll-mcp CLI.
-//
-// A superset of `install-skills`: it bootstraps a LOCAL project directory for
-// agent-driven Typeroll work. On top of copying the bundled skills it writes
-// the connection config (.mcp.json), an AGENTS.md pointer, and the scaffolding
-// the imagegen lab expects (.env.example + images/lab/.gitignore).
-//
-// Like install-skills it's a pure filesystem operation — no network, no API
-// key needed — which is why index.ts dispatches it BEFORE env-var validation.
-//
-// Everything is idempotent: rerunning never clobbers a file the user has
-// edited. `--force` opts into overwriting. Existing values inside .mcp.json
-// are always preserved (we only fill in the keys we own that are missing),
-// even without --force, so re-running can't wipe a key the user pasted in.
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { installSkills } from './install-skills.js';
-const API_URL_DEFAULT = 'https://app.typeroll.com';
-const API_KEY_PLACEHOLDER = 'typeroll_live_REPLACE_WITH_YOUR_KEY';
-const SITE_ID_PLACEHOLDER = 'REPLACE_WITH_YOUR_SITE_ID';
-/** Write `contents` to `file` unless it already exists (idempotent). With
- *  `force` it always writes. Returns whether it created or skipped. */
-async function writeIfMissing(file, contents, force) {
-    await fs.mkdir(path.dirname(file), { recursive: true });
-    if (!force) {
-        try {
-            await fs.access(file);
-            return 'skipped';
-        }
-        catch {
-            // Doesn't exist — fall through to write.
-        }
-    }
-    await fs.writeFile(file, contents, 'utf8');
-    return 'created';
-}
-function typerollServerEntry() {
-    return {
-        command: 'npx',
-        args: ['-y', '@typeroll/mcp-server'],
-        env: {
-            TYPEROLL_API_URL: API_URL_DEFAULT,
-            TYPEROLL_API_KEY: API_KEY_PLACEHOLDER,
-            TYPEROLL_SITE_ID: SITE_ID_PLACEHOLDER,
-        },
-    };
-}
-/**
- * Create or merge the `typeroll` entry in `<dir>/.mcp.json`.
- *
- * - No file → create it with just the typeroll server.
- * - File without a typeroll entry → add it, preserving every other server.
- * - File WITH a typeroll entry → fill in only the env keys we own that are
- *   missing; never overwrite a value the user already set (unless --force,
- *   which replaces the whole entry).
- * - Malformed JSON → left untouched, reported as `skipped` (we refuse to
- *   stomp on something we can't safely parse).
- */
-async function writeMcpConfig(dir, force) {
-    const file = path.join(dir, '.mcp.json');
-    let existing = null;
-    try {
-        existing = JSON.parse(await fs.readFile(file, 'utf8'));
-    }
-    catch (e) {
-        // ENOENT → brand new file. Any other parse error → don't touch it.
-        if (e?.code !== 'ENOENT') {
-            return 'skipped';
-        }
-    }
-    if (!existing) {
-        const config = { mcpServers: { typeroll: typerollServerEntry() } };
-        await fs.mkdir(dir, { recursive: true });
-        await fs.writeFile(file, JSON.stringify(config, null, 2) + '\n', 'utf8');
-        return 'created';
-    }
-    const servers = existing.mcpServers ?? {};
-    const had = !!servers.typeroll;
-    if (!had || force) {
-        servers.typeroll = typerollServerEntry();
-    }
-    else {
-        // Merge: keep the user's command/args/env, only add env keys we own that
-        // are absent. Never overwrite a value they already pasted in.
-        const entry = servers.typeroll;
-        entry.env = entry.env ?? {};
-        const defaults = typerollServerEntry().env;
-        for (const [k, v] of Object.entries(defaults)) {
-            if (entry.env[k] === undefined)
-                entry.env[k] = v;
-        }
-    }
-    existing.mcpServers = servers;
-    await fs.writeFile(file, JSON.stringify(existing, null, 2) + '\n', 'utf8');
-    return had && !force ? 'merged' : had ? 'created' : 'merged';
-}
-const AGENTS_POINTER = `# Working on a Typeroll site
-
-This project is wired to a Typeroll site through \`@typeroll/mcp-server\`.
-
-- **Skills** live in \`.claude/skills/\` (the \`tr-*.md\` recipes). Your agent
-  loads them automatically; start by skimming \`tr-new-site\` for the
-  bootstrap flow, or run the MCP tool \`list_skills\` to see them all.
-- **Connection** is configured in \`.mcp.json\`. Fill in \`TYPEROLL_API_KEY\`
-  (create one in the portal under Settings → API keys) and
-  \`TYPEROLL_SITE_ID\`.
-- **One Page model (Core 0.2.0 / MCP 0.45.0).** Every article, checklist,
-  directory entry and ordinary page is a Page. A \`content_type\` supplies its
-  schema, URL pattern and default Page template; custom values live in \`fields\`.
-  Use \`create_page\`, \`list_pages content_type=...\` and Page IDs everywhere.
-  Use the same \`version\` for Pages, types, templates and previews. Existing
-  installations require the schema 2 migration before using this model.
-- **Discover before you write.** Call \`get_site\`, \`read_site_settings\`,
-  \`list_pages\`, and \`list_block_types\` before proposing changes so you
-  mirror the site's conventions.
-- **Source of truth = the live site (the API), by default.** What you read
-  back through the MCP (\`read_page\`, \`read_partial\`, \`read_site_settings\`)
-  is canonical. Files in this folder — \`sources/*.md\` copy drafts, briefs —
-  are PROPOSALS; treat them as authoritative only when explicitly told "use
-  the copy in \`<file>\`". When rebuilding/redesigning, derive copy from the
-  live page, not a local draft. If you edit copy on the live site, sync it
-  back to the draft file in the same pass so they don't diverge.
-- **A design review covers appearance AND readability, not just structure.**
-  Before calling a build/redesign done, screenshot it at desktop (~1440px) and
-  mobile (~390px) and judge the visuals: logo fully visible (not clipped by a
-  header's overflow:hidden) + legible + brand-compliant against its real background
-  — screenshot the header in context, not the logo element in isolation (that hides
-  layout clipping); a light wordmark must not sit bare on a light surface. Text
-  contrast, no horizontal scroll or mid-word breaks, all images rendered, mobile
-  layout collapsed. "Copy present + no overflow" is not a design review — never
-  call a design perfect/approved off structural metrics alone.
-- **Image generation** runs locally in \`images/lab/\` — copy
-  \`.env.example\` to \`.env\` and add provider keys (see the \`tr-imagegen\`
-  skill). Only picked winners get uploaded to the media library.
-
-The bundled MCP tools \`list_skills\` / \`read_skill\` expose the full
-playbook at runtime — reach for them first when a task looks like
-"build / migrate / redesign a site".
-`;
-const ENV_EXAMPLE = `# Image-generation lab — local provider keys for the tr-imagegen skill.
-# Copy this file to .env and fill in whichever providers you use. The lab
-# writes candidates to images/lab/ (gitignored); only picked winners are
-# uploaded to the Typeroll media library.
-
-# Google Gemini (image generation)
-GEMINI_API_KEY=
-
-# OpenAI (image generation)
-OPENAI_API_KEY=
-
-# Higgsfield (image / video generation)
-HIGGSFIELD_API_KEY=
-`;
-const LAB_GITIGNORE = `# Generated image candidates — local scratch, never committed.
-# Only winners picked into the media library belong in version control.
-*
-!.gitignore
-`;
-/**
- * Bootstrap `dir` for agent-driven Typeroll work. Idempotent; pass
- * `force` to overwrite existing files.
- */
-export async function runInit(opts) {
-    const dir = path.resolve(opts.dir);
-    const force = opts.force ?? false;
-    await fs.mkdir(dir, { recursive: true });
-    const skills = await installSkills({
-        dest: path.join(dir, '.claude', 'skills'),
-        force,
-        sourceDir: opts.sourceDir,
-    });
-    const files = [];
-    files.push({ path: '.mcp.json', action: await writeMcpConfig(dir, force) });
-    files.push({
-        path: 'AGENTS.md',
-        action: await writeIfMissing(path.join(dir, 'AGENTS.md'), AGENTS_POINTER, force),
-    });
-    files.push({
-        path: '.env.example',
-        action: await writeIfMissing(path.join(dir, '.env.example'), ENV_EXAMPLE, force),
-    });
-    files.push({
-        path: 'images/lab/.gitignore',
-        action: await writeIfMissing(path.join(dir, 'images', 'lab', '.gitignore'), LAB_GITIGNORE, force),
-    });
-    return { dir, skills, files };
+import { skillsDir } from './install-skills.js';
+import { VERSION } from './version.js';
+import { defaultWorkspace, workspaceTemplates, writeWorkspaceFiles } from './workspace.js';
+export async function runInit(options) {
+    const dir = path.resolve(options.dir);
+    const templates = { ...workspaceTemplates, 'typeroll.json': JSON.stringify(defaultWorkspace, null, 2) + '\n' };
+    if (options.recipes) {
+        const source = options.sourceDir ?? skillsDir();
+        for (const file of (await fs.readdir(source)).filter(file => /^tr-[a-z0-9-]+\.md$/.test(file)))
+            templates[`typeroll-skills/${file}`] = await fs.readFile(path.join(source, file), 'utf8');
+    }
+    const client = options.client ?? 'none';
+    if (client !== 'none') {
+        const entry = { command: 'npx', args: ['-y', `@typeroll/mcp-server@${VERSION}`, 'workspace-mcp', dir] };
+        const file = client === 'claude' ? '.mcp.json' : client === 'cursor' ? '.cursor/mcp.json' : '.vscode/mcp.json';
+        // The hash-based updater replaces only an unchanged generated file. It never
+        // merges a user-owned configuration, credentials or another server entry.
+        templates[file] = JSON.stringify(client === 'vscode' ? { servers: { typeroll: { type: 'stdio', ...entry } } } : { mcpServers: { typeroll: entry } }, null, 2) + '\n';
+    }
+    const files = await writeWorkspaceFiles(dir, templates, options.update ?? false);
+    return { dir, generator_version: VERSION, files, client, recipes: options.recipes ?? false };
 }
-/**
- * CLI entry point — parses argv (after the `init` token has been removed)
- * and prints human-readable output. Returns an exit code.
- */
 export async function runInitCli(args) {
-    let dir;
-    let force = false;
-    for (const arg of args) {
-        if (arg === '--force' || arg === '-f') {
-            force = true;
-        }
-        else if (arg === '--help' || arg === '-h') {
-            printHelp();
+    let dir = '.', update = false, recipes = false, client = 'none', hadDir = false;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === '--help' || arg === '-h') {
+            console.log('Usage: typeroll init [directory] [--update] [--recipes] [--client none|claude|cursor|vscode]\nCreates an agent-neutral workspace. No network calls or remote writes. Updates preserve edited files.');
             return 0;
         }
-        else if (!dir && !arg.startsWith('-')) {
+        if (arg === '--update')
+            update = true;
+        else if (arg === '--recipes')
+            recipes = true;
+        else if (arg === '--client' && ['none', 'claude', 'cursor', 'vscode'].includes(args[index + 1] ?? ''))
+            client = args[++index];
+        else if (!arg.startsWith('-') && !hadDir) {
             dir = arg;
+            hadDir = true;
         }
         else {
-            console.error(`typeroll-mcp init: unrecognised argument: ${arg}`);
-            printHelp();
+            console.error(`Unsupported init argument: ${arg}. Use --help. --force is not supported; reconcile edited files explicitly.`);
             return 1;
         }
     }
-    const target = dir ?? '.';
     try {
-        const result = await runInit({ dir: target, force });
-        const skillsTotal = result.skills.copied.length + result.skills.skipped.length;
-        console.log(`typeroll-mcp: initialised project at ${result.dir}`);
-        console.log('');
-        console.log(`  skills    .claude/skills/  (${result.skills.copied.length} copied, ${result.skills.skipped.length} kept of ${skillsTotal})`);
-        for (const f of result.files) {
-            const verb = f.action === 'created' ? 'wrote' : f.action === 'merged' ? 'merged' : 'kept';
-            console.log(`  ${verb.padEnd(9)} ${f.path}`);
-        }
-        console.log('');
-        console.log('Next steps:');
-        console.log('  1. Create an API key in the Typeroll portal (Settings → API keys).');
-        console.log('  2. Edit .mcp.json: set TYPEROLL_API_KEY and TYPEROLL_SITE_ID.');
-        console.log('  3. (Optional) cp .env.example .env and add image-provider keys.');
-        console.log('  4. Open this folder in Claude Code — it picks up .mcp.json + .claude/skills/.');
-        console.log('  5. Ask the agent to "connect to Typeroll and confirm the key works".');
-        if (result.files.some((f) => f.action === 'skipped')) {
-            console.log('');
-            console.log('Some files already existed and were kept — rerun with --force to overwrite.');
-        }
+        const result = await runInit({ dir, update, recipes, client });
+        console.log(JSON.stringify(result, null, 2));
+        console.log('Next: fill brief/, connect hosted MCP at https://app.typeroll.com/api/mcp?tools=compact, create/select your Site, record its IDs/Version in typeroll.json, then run typeroll doctor. Local MCP uses an injected TYPEROLL_API_KEY; no key is stored by init. See README.md.');
         return 0;
     }
-    catch (e) {
-        const reason = e instanceof Error ? e.message : String(e);
-        console.error(`typeroll-mcp init: ${reason}`);
+    catch {
+        console.error('Workspace could not be created/updated. Check file permissions, symlinks and typeroll.lock.json. Existing edited files are not overwritten.');
         return 1;
     }
 }
-function printHelp() {
-    console.error('');
-    console.error('Usage: npx @typeroll/mcp-server init [directory] [--force]');
-    console.error('');
-    console.error('Bootstraps a local project for agent-driven Typeroll work:');
-    console.error('  - copies the bundled skills to .claude/skills/');
-    console.error('  - writes/merges .mcp.json with a typeroll server entry');
-    console.error('  - writes an AGENTS.md pointer, .env.example, images/lab/.gitignore');
-    console.error('');
-    console.error('Directory defaults to the current folder. Idempotent: rerunning');
-    console.error('never clobbers your edits, and existing .mcp.json values are kept.');
-    console.error('');
-    console.error('Options:');
-    console.error('  --force, -f             Overwrite existing files (replaces the typeroll .mcp.json entry)');
-    console.error('  --help,  -h             Show this help');
-}

package/dist/install-skills.js

@@ -123,8 +123,8 @@ function printHelp() {
     console.error('Copies bundled Typeroll skill markdown files to the destination directory.');
     console.error('');
     console.error('Common destinations:');
-    console.error('  .claude/skills          Project-scoped (recommended)');
-    console.error('  ~/.claude/skills        User-scoped (available in every project)');
+    console.error('  ./typeroll-skills       Neutral recipe directory');
+    console.error('For managed updates use: typeroll init . --recipes --update');
     console.error('');
     console.error('Options:');
     console.error('  --force, -f             Overwrite files that already exist');

package/dist/server.js

@@ -34,6 +34,10 @@ import { extensionTools } from './tools/extensions.js';
 import { skillTools } from './tools/skills.js';
 import { fail } from './tools/helpers.js';
 import { VERSION } from './version.js';
+import { compactTools, COMPACT_INSTRUCTIONS } from './compact-tools.js';
+/** What permission a tool needs to run. Maps onto the share model: a
+ *  read-shared site can `read`-list but cannot mutate. Mode `write` is the
+ *  default — applied to anything that isn't trivially side-effect-free. */
 const PERM_RANK = { read: 0, write: 1, admin: 2 };
 /**
  * Classify a tool by name into the minimum permission needed. We keep this
@@ -122,7 +126,7 @@ export function buildServer(options) {
     }
     const server = new McpServer(options.info ?? DEFAULT_INFO, {
         capabilities: { tools: {} },
-        instructions: SERVER_INSTRUCTIONS,
+        instructions: options.toolMode === 'compact' ? COMPACT_INSTRUCTIONS : SERVER_INSTRUCTIONS,
     });
     const allTools = [
         ...skillTools,
@@ -155,6 +159,7 @@ export function buildServer(options) {
     const register = server.registerTool.bind(server);
     const isMultiSite = !!options.allowedSites;
     const allowedById = new Map((options.allowedSites ?? []).map((s) => [s.siteId, s]));
+    const catalog = [];
     for (const tool of allTools) {
         const effect = effectFor(tool.name);
         // Skill-discovery tools (and any future site-less tool) operate without a
@@ -167,43 +172,47 @@ export function buildServer(options) {
             const siteIdField = {
                 site_id: z
                     .string()
-                    .describe(`Required. The id of the site this call targets. Use list_sites to discover ids; available sites for this connection: ${(options.allowedSites ?? []).map((s) => s.siteId).join(', ') || '(none)'}.`),
+                    .describe('Required. The Site ID this call targets. Use list_sites to discover accessible sites.'),
             };
             schema = { ...(tool.inputSchema ?? {}), ...siteIdField };
         }
-        register(tool.name, {
-            description: tool.description,
-            ...(schema ? { inputSchema: schema } : {}),
-        }, 
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        async (args) => {
-            const rawArgs = args ?? {};
-            let siteId;
-            if (isMultiSite && needsSite) {
-                const provided = typeof rawArgs.site_id === 'string' ? rawArgs.site_id.trim() : '';
-                if (!provided) {
-                    return fail(new Error('site_id is required. This connector covers multiple sites; pick one from list_sites.'));
-                }
-                const match = allowedById.get(provided);
-                if (!match) {
-                    return fail(new Error(`site_id "${provided}" is not accessible by this connection. Use list_sites to see allowed ids.`));
+        catalog.push({ name: tool.name, description: tool.description, effect, schema: schema ?? {}, invoke: 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            async (args) => {
+                const rawArgs = { ...(args ?? {}) };
+                let siteId;
+                if (isMultiSite && needsSite) {
+                    const provided = typeof rawArgs.site_id === 'string' ? rawArgs.site_id.trim() : '';
+                    if (!provided) {
+                        return fail(new Error('site_id is required. This connector covers multiple sites; pick one from list_sites.'));
+                    }
+                    const match = allowedById.get(provided);
+                    if (!match) {
+                        return fail(new Error(`site_id "${provided}" is not accessible by this connection. Use list_sites to see allowed ids.`));
+                    }
+                    if (PERM_RANK[match.permission] < PERM_RANK[effect]) {
+                        return fail(new Error(`Tool "${tool.name}" requires ${effect} permission on site "${provided}"; this connection has ${match.permission}.`));
+                    }
+                    siteId = provided;
+                    // Strip site_id from the args we pass downstream so individual
+                    // tool schemas (which don't declare it) don't reject the call.
+                    delete rawArgs.site_id;
                 }
-                if (PERM_RANK[match.permission] < PERM_RANK[effect]) {
-                    return fail(new Error(`Tool "${tool.name}" requires ${effect} permission on site "${provided}"; this connection has ${match.permission}.`));
+                else {
+                    // Single-site mode, or a site-less tool in multi-site mode (no
+                    // fixedSiteId) — the latter's handler ignores siteId entirely.
+                    siteId = options.fixedSiteId ?? '';
                 }
-                siteId = provided;
-                // Strip site_id from the args we pass downstream so individual
-                // tool schemas (which don't declare it) don't reject the call.
-                delete rawArgs.site_id;
-            }
-            else {
-                // Single-site mode, or a site-less tool in multi-site mode (no
-                // fixedSiteId) — the latter's handler ignores siteId entirely.
-                siteId = options.fixedSiteId ?? '';
-            }
-            const deps = { client: options.client, siteId };
-            return tool.handler(rawArgs, deps);
+                const deps = { client: options.client, siteId };
+                return tool.handler(rawArgs, deps);
+            },
         });
     }
+    for (const tool of options.toolMode === 'compact' ? compactTools(catalog) : catalog) {
+        register(tool.name, {
+            description: tool.description, inputSchema: tool.schema,
+            annotations: { readOnlyHint: tool.effect === 'read', destructiveHint: tool.effect !== 'read', openWorldHint: true },
+        }, tool.invoke);
+    }
     return server;
 }

package/dist/tools/pages.js

@@ -91,6 +91,7 @@ export const pageTools = [
             html_content: z.string().optional().describe('Body HTML — only used when content_mode="html".'),
             blocks: z.array(z.any()).optional().describe('Block tree — only used when content_mode="blocks". Omit to get the default heading+prose seed.'),
             status: z.enum(['draft', 'review', 'unlisted', 'published']).optional(),
+            breadcrumb_label: z.string().max(200).nullable().optional().describe('Optional short breadcrumb label. Leaves Page title, SEO title and route unchanged; null/empty uses the title.'),
             seo_title: z.string().optional(),
             append_seo_suffix: z.boolean().optional().describe('Set false to omit the site default SEO suffix on this page.'),
             seo_description: z.string().optional(),
@@ -117,7 +118,7 @@ export const pageTools = [
     },
     {
         name: 'update_page',
-        description: 'Shallow-merge update on a page (only the fields you pass change). BUFFER MODEL: content fields land in the page\'s unsaved DRAFT (working copy) — invisible to deploys and default previews until saved; `status`/`date_published` apply immediately. Pass save:true to commit in the same call, or commit_working_copy later after the user approves. Returns the draft view of the page. For "replace this page entirely", use replace_page. This tool does not accept content_mode; switch modes with `set_page_mode`.',
+        description: 'Shallow-merge update on a page, including its short breadcrumb label (only the fields you pass change). BUFFER MODEL: content fields land in the page\'s unsaved DRAFT (working copy) — invisible to deploys and default previews until saved; `status`/`date_published` apply immediately. Pass save:true to commit in the same call, or commit_working_copy later after the user approves. Returns the draft view of the page. For "replace this page entirely", use replace_page. This tool does not accept content_mode; switch modes with `set_page_mode`.',
         inputSchema: {
             page_id: z.string(),
             patch: z
@@ -133,6 +134,7 @@ export const pageTools = [
                 kind: z.enum(['page', 'article']).optional(),
                 author: z.string().optional(),
                 language: z.string().optional(),
+                breadcrumb_label: z.string().max(200).nullable().optional().describe('Optional short breadcrumb label. Leaves Page title, SEO title and route unchanged; null/empty uses the title.'),
                 seo_title: z.string().optional(),
                 append_seo_suffix: z.boolean().optional().describe('Set false to use seo_title/page title verbatim without the site suffix.'),
                 seo_description: z.string().optional(),

package/dist/tools/settings.js

@@ -24,7 +24,7 @@ export const settingsTools = [
     },
     {
         name: 'update_site_settings',
-        description: 'Patch site settings. Only the fields you pass change. ' +
+        description: 'Patch site settings, including responsive breakpoints for block layouts and visibility. Only the fields you pass change. ' +
             'Pass fields at the TOP LEVEL of the object — do NOT wrap in a "settings" key. ' +
             'Example: {"site_name": "Acme", "colors": {"primary": "#ff0"}} not {"settings": {...}}. ' +
             'Nested objects (colors, fonts, contact, social) are shallow-merged into the existing value. ' +
@@ -33,6 +33,7 @@ export const settingsTools = [
             'Pass `version` to scope the write to a branch (copy-on-write) instead of main — the right way to brand/recolor a site inside a redesign branch (colors, fonts, logo, custom_css) without touching the live settings. Omit it to write main.',
         inputSchema: {
             version: versionParam,
+            responsive_breakpoints: z.object({ tablet: z.number().int().min(320).max(2560), laptop: z.number().int().min(320).max(2560), desktop: z.number().int().min(320).max(2560), wide: z.number().int().min(320).max(2560) }).strict().nullable().optional().describe('Increasing viewport widths for authored responsive block fields and hidden_on. All four required; null restores defaults. Menu collapse remains explicit.'),
             site_name: z.string().optional(),
             tagline: z.string().optional(),
             logo: z.string().optional(),

package/dist/tools/sites.js

@@ -2,6 +2,16 @@
 import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
 export const siteTools = [
+    {
+        name: 'list_sites', noSite: true,
+        description: 'List accessible Sites without changing them. Use the returned IDs for site_id or your workspace binding. Results are paginated locally.',
+        inputSchema: { offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(50).default(20) },
+        handler: withErrorBoundary(async (args, { client }) => {
+            const response = await client.rootGet('sites');
+            const sites = response.sites ?? [];
+            return ok({ sites: sites.slice(args.offset, args.offset + args.limit), total: sites.length, next_offset: args.offset + args.limit < sites.length ? args.offset + args.limit : null });
+        }),
+    },
     {
         name: 'create_site',
         description: "Create + bootstrap a NEW site in your org. Seeds default settings, a draft Home page, and a published header/footer so it renders immediately. Requires an ORG-scoped key (a site-scoped key is bound to one existing site and can't mint new ones; you'll get a 403). `name` drives a kebab-case site id; pass `domain` to kick off the \"point your DNS\" flow (never written as a live domain). Returns the new site's id + urls — use that id as `site_id`/`TYPEROLL_SITE_ID` for follow-up calls. After creating, run list_skills → read_skill tr-new-site to bootstrap the design.",