@typeroll/mcp-server 0.18.0 → 0.20.0

package/AGENTS.md

@@ -7,6 +7,12 @@ 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.
+
 ## What this is
 
 Typeroll is a static-site CMS: content lives in a database, the user
@@ -571,6 +577,7 @@ stakeholder review.
 
 | Family       | Tools |
 |---|---|
+| **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`, `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` |

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,6 +99,14 @@ which tool.
 Around 50 tools across these families. See [AGENTS.md](./AGENTS.md) for
 the full reference + concrete operation recipes.
 
+- **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`, `update_site` (name/slug/domain), `list_versions`,
   `read_site_settings`, `update_site_settings`.
 - **Pages** — list, read, batch-read, create, update (PATCH), replace

package/dist/index.js

@@ -14,6 +14,7 @@
 //                   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';
@@ -24,6 +25,10 @@ function bail(message) {
 }
 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 };
 /**
@@ -59,6 +60,7 @@ export function buildServer(options) {
         capabilities: { tools: {} },
     });
     const allTools = [
+        ...skillTools,
         ...siteTools,
         ...pageTools,
         ...partialTools,
@@ -84,8 +86,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 +108,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 +126,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/forms.js

@@ -46,7 +46,6 @@ export const formTools = [
             fields: z.array(fieldSchema).min(1),
             submit_text: z.string().optional(),
             success_message: z.string().optional(),
-            actions: z.array(z.object({ type: z.string(), config: z.record(z.unknown()) })).optional(),
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.post(siteId, 'forms', args);
@@ -63,7 +62,6 @@ export const formTools = [
                 fields: z.array(fieldSchema).optional(),
                 submit_text: z.string().optional(),
                 success_message: z.string().optional(),
-                actions: z.array(z.object({ type: z.string(), config: z.record(z.unknown()) })).optional(),
             }),
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.18.0",
+  "version": "0.20.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": {

package/skills/tr-forms.md

@@ -291,6 +291,11 @@ portal at `/app/sites/{siteId}/forms/kontakt/submissions`.
   unique per site — use descriptive names: `kontakt`, `boka`, `nyhetsbrev`.
 - **Honeypot must be invisible.** `_hp` field must have `display:none`.
   If it's visible and a real user fills it, their submission is rejected.
-- **No email notifications yet.** Submissions are stored and visible in
-  the portal's Submissions inbox; the email action handler isn't wired
-  platform-side. Confirm with the customer that they'll check the inbox.
+- **Email notifications are admin-only — not settable via MCP.** Submissions
+  are stored and visible in the portal's Forms → Submissions inbox. A site
+  admin can also configure post-submission emails (admin notification +
+  autoresponder) under **Forms → <form> → Email**, after setting up an email
+  connector under **Settings → Email & notifications**. These carry recipient
+  addresses + templates over submission data, so they're deliberately off the
+  agent surface (`create_form`/`update_form` ignore `actions`). Point the
+  customer at those screens; you can't set them up for them.