@typeroll/mcp-server 0.19.0 → 0.21.0

package/AGENTS.md

@@ -7,6 +7,22 @@ what tools to reach for first.
 If anything below conflicts with what you observe in the tools, trust the
 tools — the platform may have moved since this was written.
 
+**Start here for site-shaped tasks.** When the user wants to build,
+migrate, redesign, or brand a site, call `list_skills` first — the server
+advertises its own step-by-step playbook (`tr-new-site`, `tr-migrate-wp`,
+`tr-brand`, …). Then `read_skill name=…` loads the full recipe. These are
+local reads; no API key or site context required.
+
+**Branch first for anything larger than a small edit.** Before a redesign,
+a multi-page change, or trying out a new design direction, run
+`create_branch name="…"` and pass the returned id as `version=<id>` on every
+subsequent read/write. The work stays off the live `main` version until you
+`merge_branch` it — nothing ships until you decide it should. Branches default
+`robots_blocked:true` and get their own deploy URL for stakeholder review.
+It's the cheapest insurance there is; when in doubt, branch. The
+`tr-redesign-branch` skill walks the whole flow. (Small, low-risk single edits
+can go straight to main.)
+
 ## What this is
 
 Typeroll is a static-site CMS: content lives in a database, the user
@@ -210,6 +226,13 @@ goes through the MCP:
 You usually want at least #1 + #2 + a sampling from #3 before
 proposing any design change, so you mirror the conventions in use.
 
+**Don't have a site yet?** With an org-scoped key you can `create_site
+name="Acme"` — it bootstraps settings + a draft Home page + a published
+header/footer and returns the new site id. Use that id as `site_id`
+(hosted) / `TYPEROLL_SITE_ID` (stdio) for follow-ups, then run
+`list_skills` → `read_skill tr-new-site` to design it. A site-scoped key
+can't create sites (it's bound to one) and gets a 403.
+
 ## Common operations
 
 ### "Replace this string across the whole site"
@@ -571,7 +594,8 @@ stakeholder review.
 
 | Family       | Tools |
 |---|---|
-| **Discovery** | `get_site`, `update_site`, `list_versions`, `read_site_settings` |
+| **Skills (playbook)** | `list_skills`, `read_skill` — the bundled `tr-*.md` recipes, advertised at runtime. Call `list_skills` first when a task looks like "build / migrate / redesign a site", then `read_skill name=…`. No API key or site context needed. |
+| **Discovery** | `get_site`, `create_site` (org-scoped key only — see below), `update_site`, `list_versions`, `read_site_settings` |
 | **Pages — reads** | `list_pages`, `read_page`, `batch_read_pages` |
 | **Pages — writes** | `create_page`, `update_page`, `replace_page`, `batch_update_pages`, `delete_page`, `clone_page` |
 | **Pages — blocks** | `get_page_blocks`, `add_block`, `update_block`, `move_block`, `remove_block`, `set_page_mode`, `convert_page_to_blocks` |

package/README.md

@@ -63,6 +63,12 @@ client using it stops working immediately.
    For a self-hosted portal, point `TYPEROLL_API_URL` at it (e.g.
    `https://cms.example.com`).
 
+   Prefer a scaffold? Run `npx @typeroll/mcp-server init` in your project
+   folder — it writes/merges this `.mcp.json`, copies the skills into
+   `.claude/skills/`, and adds an `AGENTS.md` pointer + imagegen-lab
+   files. Idempotent; `--force` to overwrite. (Skills only:
+   `npx @typeroll/mcp-server install-skills .claude/skills`.)
+
 3. **Tell the agent what kind of work you want.** A good first message:
 
    > "Connect to Typeroll and tell me what you find — site name,
@@ -93,7 +99,16 @@ which tool.
 Around 50 tools across these families. See [AGENTS.md](./AGENTS.md) for
 the full reference + concrete operation recipes.
 
-- **Discovery** — `get_site`, `update_site` (name/slug/domain), `list_versions`,
+- **Skills (self-describing playbook)** — `list_skills` and
+  `read_skill`. The server advertises its own bundled recipes at runtime,
+  so an agent discovers the platform's playbook (`tr-new-site`,
+  `tr-migrate-wp`, `tr-brand`, …) on connection without any files copied
+  locally. Call `list_skills` early when the user wants to build /
+  migrate / redesign a site, then `read_skill name=tr-new-site` for the
+  full markdown. Pure local reads — no API key or site context needed, so
+  they work identically on the hosted connector and over stdio.
+- **Discovery** — `get_site`, `create_site` (bootstrap a new site — org-scoped
+  key only), `update_site` (name/slug/domain), `list_versions`,
   `read_site_settings`, `update_site_settings`.
 - **Pages** — list, read, batch-read, create, update (PATCH), replace
   (PUT), batch-update, delete, clone, get-preview, `set_page_mode`

package/dist/client.js

@@ -100,4 +100,7 @@ export class TyperollClient {
     rootGet(path) {
         return this.request('GET', this.rootUrl(path));
     }
+    rootPost(path, body) {
+        return this.request('POST', this.rootUrl(path), body);
+    }
 }

package/dist/index.js

@@ -14,16 +14,21 @@
 //                   so this stdio invocation maps onto one specific site.
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { TyperollClient } from './client.js';
+import { runInitCli } from './init.js';
 import { runInstallSkillsCli } from './install-skills.js';
 import { resolveSiteId } from './resolve-site-id.js';
 import { buildServer } from './server.js';
-const VERSION = '0.7.12';
+const VERSION = '0.21.0';
 function bail(message) {
     console.error(`typeroll-mcp: ${message}`);
     process.exit(1);
 }
 async function main() {
     const argv = process.argv.slice(2);
+    if (argv[0] === 'init') {
+        const code = await runInitCli(argv.slice(1));
+        process.exit(code);
+    }
     if (argv[0] === 'install-skills') {
         const code = await runInstallSkillsCli(argv.slice(1));
         process.exit(code);
@@ -31,6 +36,7 @@ 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 install-skills <dir> [-f]    Copy bundled skill files to <dir>');
         console.error('  typeroll-mcp --help                       Show this help');
         process.exit(0);

package/dist/init.js

@@ -0,0 +1,235 @@
+// `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\`.
+- **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.
+- **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 };
+}
+/**
+ * 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();
+            return 0;
+        }
+        else if (!dir && !arg.startsWith('-')) {
+            dir = arg;
+        }
+        else {
+            console.error(`typeroll-mcp init: unrecognised argument: ${arg}`);
+            printHelp();
+            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.');
+        }
+        return 0;
+    }
+    catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        console.error(`typeroll-mcp init: ${reason}`);
+        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

@@ -14,7 +14,9 @@ import { fileURLToPath } from 'node:url';
 // Resolve the bundled skills directory. At runtime this file lives at
 // <package>/dist/install-skills.js (after tsc); skills/ is a sibling of dist/.
 // fileURLToPath gives us a real OS path that works on every platform.
-function skillsDir() {
+// Exported so the skill-discovery tools (tools/skills.ts) resolve the exact
+// same directory without duplicating the `..`/`skills` dance.
+export function skillsDir() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     return path.resolve(here, '..', 'skills');
 }

package/dist/server.js

@@ -25,6 +25,7 @@ import { pageBlockTools } from './tools/page-blocks.js';
 import { settingsTools } from './tools/settings.js';
 import { siteTools } from './tools/sites.js';
 import { domainTools } from './tools/domain.js';
+import { skillTools } from './tools/skills.js';
 import { fail } from './tools/helpers.js';
 const PERM_RANK = { read: 0, write: 1, admin: 2 };
 /**
@@ -47,7 +48,37 @@ function effectFor(name) {
     }
     return 'write';
 }
-const DEFAULT_INFO = { name: 'typeroll', version: '0.7.12' };
+const DEFAULT_INFO = { name: 'typeroll', version: '0.21.0' };
+/**
+ * Server-level instructions — returned in the MCP `initialize` response and
+ * surfaced to the model by every client (Claude Code stdio AND the hosted
+ * Desktop/claude.ai connector) with zero user setup. This is the one channel
+ * that reaches every consumer automatically, so it carries the highest-value
+ * conventions and POINTS at the deeper, on-demand content (the bundled skills,
+ * reachable via list_skills/read_skill) rather than duplicating it.
+ */
+export const SERVER_INSTRUCTIONS = `
+Typeroll MCP — operating manual. You're managing a Typeroll site (a static-site
+CMS: database content compiles to a fast static site on a deploy). The full
+playbook ships with this server — use it:
+
+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, …). These are the canonical
+   how-to; don't improvise what a skill already covers.
+2. Discover before you write: get_site, read_site_settings, list_pages,
+   list_block_types. Never hardcode block ids or field names — they're per-site.
+3. Branch first for anything larger than a small edit: create_branch, pass
+   version=<id> on every subsequent call, merge_branch once approved. Nothing
+   touches the live site until then.
+4. Pages default to block mode. Build with add_block/update_block; make layouts
+   responsive per breakpoint with set_block_responsive (grid columns, icon-box
+   layout, … take { mobile, tablet, laptop, desktop, wide } values).
+5. No site yet? With an org-scoped key, create_site bootstraps one.
+
+If anything here conflicts with what a tool returns, trust the tool. Every
+tool's own description carries its specifics.
+`.trim();
 export function buildServer(options) {
     if (!options.fixedSiteId && !options.allowedSites) {
         throw new Error('buildServer: either fixedSiteId or allowedSites must be provided');
@@ -57,8 +88,10 @@ export function buildServer(options) {
     }
     const server = new McpServer(options.info ?? DEFAULT_INFO, {
         capabilities: { tools: {} },
+        instructions: SERVER_INSTRUCTIONS,
     });
     const allTools = [
+        ...skillTools,
         ...siteTools,
         ...pageTools,
         ...partialTools,
@@ -84,8 +117,11 @@ export function buildServer(options) {
     const allowedById = new Map((options.allowedSites ?? []).map((s) => [s.siteId, s]));
     for (const tool of allTools) {
         const effect = effectFor(tool.name);
+        // Skill-discovery tools (and any future site-less tool) operate without a
+        // site context: don't inject or validate a `site_id` arg for them.
+        const needsSite = !tool.noSite;
         let schema = tool.inputSchema;
-        if (isMultiSite) {
+        if (isMultiSite && needsSite) {
             // Append site_id to the tool's existing input schema. We mutate a copy
             // so we don't pollute the imported ToolDef.
             const siteIdField = {
@@ -103,7 +139,7 @@ export function buildServer(options) {
         async (args) => {
             const rawArgs = args ?? {};
             let siteId;
-            if (isMultiSite) {
+            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.'));
@@ -121,7 +157,9 @@ export function buildServer(options) {
                 delete rawArgs.site_id;
             }
             else {
-                siteId = options.fixedSiteId;
+                // 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);

package/dist/tools/block-types.js

@@ -92,7 +92,7 @@ export const blockTypeTools = [
     // audit + UI distinguish agent-authored types.
     {
         name: 'create_block_type',
-        description: "Create a new custom block type usable on this site. Origin is stamped 'ai' automatically. The block ships immediately to every page editor + the renderer's registry. Custom JS via `script` is accepted under your API key's authority (audit-logged; the response carries a notice) — review before deploy. Returns the created BlockType.",
+        description: "Create a new custom block type usable on this site. Origin is stamped 'ai' automatically. The block ships immediately to every page editor + the renderer's registry. Custom JS via `script` is accepted under your API key's authority (audit-logged; the response carries a notice) — review before deploy. Returns the created BlockType. Responsive fields: mark a schema field `responsive: true` and expose it as style=\"--{field}:{{field}}\" on the outermost element so it can vary per breakpoint. If the value is directly usable CSS, read var(--{field}); if it's a token that maps to CSS (e.g. layout 'icon-left' → flex-direction:row) add a `responsive_css` map on the field ({ 'icon-left': '--dir: row;' }), otherwise per-breakpoint overrides won't take effect.",
         inputSchema: {
             name: z.string().describe('Machine name (lowercase kebab/underscore, 1-64 chars). Becomes the id.'),
             label: z.string().optional().describe('Display label (defaults to name).'),

package/dist/tools/sites.js

@@ -2,6 +2,22 @@
 import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
 export const siteTools = [
+    {
+        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.",
+        noSite: true,
+        inputSchema: {
+            name: z.string().min(1).describe('Display name. Slugified into the site id.'),
+            domain: z
+                .string()
+                .optional()
+                .describe('Optional real hostname e.g. "example.com". Starts DNS setup; not set live until DNS verifies.'),
+        },
+        handler: withErrorBoundary(async (args, { client }) => {
+            const res = await client.rootPost('sites', { name: args.name, domain: args.domain });
+            return ok(res);
+        }),
+    },
     {
         name: 'get_site',
         description: 'Read this site\'s metadata (id, name, slug, domain, active version) + a urls object covering the production / fallback / preview_base URLs. Useful as a first call to confirm the key is wired up and to learn what URLs the site is reachable at.',

package/dist/tools/skills.js

@@ -0,0 +1,104 @@
+// Skill-discovery tools — the self-describing playbook layer.
+//
+// The package bundles a set of `tr-*.md` skill recipes under `skills/`. Until
+// now they were only useful if the operator happened to copy them into
+// `.claude/skills/` (see install-skills.ts) — the running MCP server never
+// advertised them, so an agent had no way to learn that e.g. `tr-new-site`
+// exists. These two tools fix that by exposing the bundled skills directly
+// on the tool surface, identically over stdio and the hosted HTTP transport.
+//
+// Both are pure LOCAL file reads: they do NOT touch the REST API and need
+// neither TYPEROLL_API_KEY nor TYPEROLL_API_URL nor a site context. That's
+// why they're flagged `noSite: true` — in multi-site (hosted) mode the
+// server skips the usual `site_id` injection/validation for them.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { skillsDir } from '../install-skills.js';
+import { ok, withErrorBoundary } from './helpers.js';
+/** The only basenames `read_skill` will resolve. Matches the install-skills
+ *  copy filter (`tr-*.md`) and, because it forbids slashes and dots, is also
+ *  the primary defence against path traversal. */
+export const SKILL_NAME_RE = /^tr-[a-z0-9-]+$/;
+/**
+ * Pull `name:` / `description:` out of a skill file's YAML frontmatter.
+ *
+ * The frontmatter is a flat block we author by hand (two single-line keys),
+ * so a deliberately tiny regex parse beats pulling in a YAML dependency.
+ * Falls back to the filename-derived name when `name:` is absent and to an
+ * empty description when `description:` is.
+ */
+export function parseSkillFrontmatter(markdown, fallbackName) {
+    let name = fallbackName;
+    let description = '';
+    const fm = markdown.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
+    if (fm) {
+        const body = fm[1];
+        const nameLine = body.match(/^name:\s*(.+?)\s*$/m);
+        const descLine = body.match(/^description:\s*(.+?)\s*$/m);
+        if (nameLine)
+            name = nameLine[1].trim();
+        if (descLine)
+            description = descLine[1].trim();
+    }
+    return { name, description };
+}
+/** List the bundled skills (name + description) from `sourceDir`. Pure read;
+ *  `sourceDir` defaults to the bundled `skills/` dir but is injectable for
+ *  tests. */
+export async function listBundledSkills(sourceDir = skillsDir()) {
+    const entries = await fs.readdir(sourceDir);
+    const files = entries.filter((f) => f.startsWith('tr-') && f.endsWith('.md')).sort();
+    const skills = [];
+    for (const file of files) {
+        const raw = await fs.readFile(path.join(sourceDir, file), 'utf8');
+        skills.push(parseSkillFrontmatter(raw, file.replace(/\.md$/, '')));
+    }
+    return skills;
+}
+/** Read one bundled skill's markdown by name. Rejects anything that isn't a
+ *  `tr-<kebab>` basename and, belt-and-suspenders, verifies the resolved path
+ *  stays inside `sourceDir`. */
+export async function readBundledSkill(name, sourceDir = skillsDir()) {
+    if (!SKILL_NAME_RE.test(name)) {
+        throw new Error(`invalid skill name "${name}" — expected tr-<kebab-case>, e.g. tr-new-site. Use list_skills to see available skills.`);
+    }
+    const root = path.resolve(sourceDir);
+    const target = path.resolve(root, `${name}.md`);
+    // The regex already blocks `/` and `.`, so traversal can't get here — but
+    // confirm the join landed exactly where we expect before touching disk.
+    if (path.dirname(target) !== root) {
+        throw new Error(`refusing to read outside the skills directory: ${name}`);
+    }
+    try {
+        return await fs.readFile(target, 'utf8');
+    }
+    catch {
+        throw new Error(`skill "${name}" not found. Use list_skills to see available skills.`);
+    }
+}
+export const skillTools = [
+    {
+        name: 'list_skills',
+        description: 'List the bundled Typeroll playbook skills (name + description). Call this EARLY — the moment the user wants to build, migrate, redesign, brand, or otherwise design a site — to discover the step-by-step recipe that fits (e.g. tr-new-site, tr-migrate-wp, tr-brand, tr-blog), then read_skill the most relevant one before acting. Pure local read: no API key and no site required, so it works on the hosted connector and stdio alike.',
+        noSite: true,
+        handler: withErrorBoundary(async () => {
+            const skills = await listBundledSkills();
+            return ok({ skills, count: skills.length });
+        }),
+    },
+    {
+        name: 'read_skill',
+        description: 'Return the full markdown of one bundled skill by name (e.g. "tr-new-site"). Use it after list_skills to load the playbook for the task at hand. Pure local read: no API key and no site required.',
+        inputSchema: {
+            name: z
+                .string()
+                .describe('Skill name without the .md extension, e.g. "tr-new-site". Must match /^tr-[a-z0-9-]+$/.'),
+        },
+        noSite: true,
+        handler: withErrorBoundary(async (args) => {
+            const content = await readBundledSkill(args.name);
+            return ok(content);
+        }),
+    },
+];

package/dist/tools/versions.js

@@ -12,7 +12,7 @@ export const versionTools = [
     },
     {
         name: 'create_branch',
-        description: 'Create a copy-on-write branch from main (or the version passed in `base`). New branches default to robots_blocked:true. Pass the new branch\'s id as ?version= on subsequent calls to read/write against it.',
+        description: "Create a copy-on-write branch from main (or the version passed in `base`) — the RECOMMENDED first step for any larger or experimental change (redesigns, multi-page edits, trying a new design direction). Work lands on the branch, never on the live main version, until you merge_branch it. New branches default to robots_blocked:true (a half-finished design can't be indexed) and get their own deploy URL ({branch}.{project}.pages.dev) for stakeholder review. Pass the returned id as ?version= on every subsequent read/write. When in doubt, branch — it's cheap and keeps the live site safe. The tr-redesign-branch skill (read_skill) walks the full flow.",
         inputSchema: {
             name: z.string().min(1),
             base: z.string().optional().describe('Source version id; defaults to main.'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Model Context Protocol server for the Typeroll public API. Use with Claude Code or any MCP-compatible client to manage a Typeroll site.",
   "license": "MIT",
   "repository": {