@typeroll/mcp-server 0.20.0 → 0.21.0

package/AGENTS.md

@@ -13,6 +13,16 @@ 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
@@ -216,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"
@@ -578,7 +595,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` |
+| **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

@@ -107,7 +107,8 @@ the full reference + concrete operation recipes.
   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`,
+- **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

@@ -18,7 +18,7 @@ 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);

package/dist/server.js

@@ -48,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');
@@ -58,6 +88,7 @@ export function buildServer(options) {
     }
     const server = new McpServer(options.info ?? DEFAULT_INFO, {
         capabilities: { tools: {} },
+        instructions: SERVER_INSTRUCTIONS,
     });
     const allTools = [
         ...skillTools,

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/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.20.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": {