@timelesscms-com/mcp-server 0.1.0 → 0.3.0

package/AGENTS.md

@@ -23,16 +23,31 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
 ## The data model in 90 seconds
 
 - **Pages.** Title, slug, status (`draft | review | unlisted | published`),
-  HTML body (`html_content`), SEO fields. Slug can contain slashes, so
-  `2024/01/foo-bar` is a valid slug → `/2024/01/foo-bar` URL. Encode
-  hierarchy in the slug; the renderer doesn't use `parent` for routing.
+  body content + SEO fields. Two body shapes selectable per page via
+  `content_mode`:
+  - `blocks` (DEFAULT for new pages) — `blocks: Block[]` tree of typed
+    blocks (heading, prose, section, columns, image, button, plus any
+    user/third-party block types installed on the site). Use the
+    block-mutation tools (`add_block`, `update_block`, `move_block`,
+    `remove_block`) for structural changes.
+  - `html` — body lives in `html_content` as a single HTML string.
+    Useful when you have hand-written markup to drop in directly.
+
+  Slug can contain slashes, so `2024/01/foo-bar` is a valid slug →
+  `/2024/01/foo-bar` URL. Encode hierarchy in the slug; the renderer
+  doesn't use `parent` for routing.
 
 - **Partials = global blocks.** Three kinds:
   - `header` — auto-injected at the top of every page.
   - `footer` — auto-injected at the bottom of every page.
   - `free` — reusable HTML you drop into a page with
     `<x-include name="block-id" />`. Free blocks are how you avoid
-    duplicating HTML across pages.
+    duplicating HTML across HTML-mode pages.
+
+  Partials themselves also support `content_mode='blocks'` — pass a
+  `blocks: Block[]` tree to `update_partial` and the renderer composes
+  it the same way as a page. Useful for header/footer authored with
+  block types.
 
 - **Collections.** Repeatable content types (blog, team, events,
   products, restaurants for a directory site, etc.). Each has a schema
@@ -42,9 +57,22 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
   `route_template=""` to opt out and keep the collection listing-only.
 
 - **Settings.** Site name, tagline, logo, favicon, colors, fonts,
-  contact info, social links, SEO suffix. Scripts and custom CSS exist
-  on the settings doc but the API does NOT expose them — the customer
-  edits those manually.
+  contact info, social links, SEO suffix, plus `scripts_head`,
+  `scripts_body_end`, `custom_css` (writable via the API — your bearer
+  token authorises shipping arbitrary CSS/JS to the live site, just
+  like editing a partial's HTML does).
+
+- **Page templates.** A `PageTemplate` is a Block[] tree that wraps a
+  page's body. The template contains exactly one block of type
+  `template_content_slot` — at render time that block gets replaced by
+  the page's own `blocks`. Set `Page.template = "<template-id>"` to
+  apply a template to a page.
+
+- **Block types.** Custom blocks (`origin: 'user'`) and installed
+  third-party blocks (`origin: 'third_party'`) live in a per-site
+  collection. Use `list_block_types` to see what's available. The
+  `core/*` types (section, columns, prose, heading, image, button) are
+  always available and don't appear in that list.
 
 - **Redirects.** `from_path → to_path` with status code 301 / 302.
   Auto-created when you change a page's slug.
@@ -144,13 +172,57 @@ duplicating it:
 
 ```
 create_free_block id="newsletter-cta" html_content="<form>…</form>"
-# Then on each page where it should appear:
+# Then on each page where it should appear (HTML-mode pages):
 update_page page_id=… patch={ html_content: "<…><x-include name=\"newsletter-cta\" />" }
 ```
 
 Edits to the block update every page that includes it. Use
 `find_pages_using_block` before changing it.
 
+### "Build a page using blocks (the default for new pages)"
+
+New pages default to `content_mode='blocks'` with a seeded heading +
+prose block. To add more:
+
+```
+get_page_blocks page_id=home
+# returns { content_mode: 'blocks', blocks: [...] }
+add_block page_id=home block={ type: 'core/section', data: { width: 'wide' } }
+# returns { added_id: 'blk_xyz', blocks: [...] }
+add_block page_id=home parent_id="blk_xyz" block={
+  type: 'core/heading', data: { text: 'Pricing', level: 'h2' }
+}
+add_block page_id=home parent_id="blk_xyz" block={
+  type: 'core/prose', data: { html: '<p>…</p>' }
+}
+```
+
+Updating, moving, removing blocks: `update_block`, `move_block`,
+`remove_block` (all by `block_id`).
+
+### "Switch a page between blocks and HTML"
+
+Use `set_page_mode` — it snapshots a revision before flipping, so the
+previous state is restorable:
+
+```
+# Convert an HTML-mode page to blocks with auto-heuristic conversion:
+set_page_mode page_id=about to=blocks convert=true
+
+# Or just switch the mode without converting (empty blocks):
+set_page_mode page_id=about to=blocks
+
+# Switch back to HTML (drops the block tree; revision retains it):
+set_page_mode page_id=about to=html
+```
+
+The heuristic converter recognises `<h1-4>` → heading, `<img>` → image,
+`<a.btn>` → button, `grid-cols-2` → two-column, `<section>` / hero divs
+→ section. Anything it can't classify becomes a `core/prose` block,
+which preserves the raw HTML losslessly. Run with `convert_page_to_blocks
+dry_run=true` first if you want to inspect the proposal before
+committing.
+
 ### "Build a directory site / import structured data"
 
 ```
@@ -236,14 +308,50 @@ update_page page_id=about patch={ slug: "om-oss" }
 
 The 301 fires automatically — you don't have to remember.
 
+### "Change the site's fallback URL (slug)"
+
+```
+update_site slug="acme"
+  → response includes:
+     urls.fallback: "https://acme.sites.timelesscms.com"
+     dns_note: "New fallback URL … attached to CF Pages. SSL provisioning
+                takes 1–10 minutes after DNS propagates. …"
+```
+
+The slug change triggers DNS + CF Pages reprovisioning behind the scenes.
+**Always check the response for `dns_note` vs `dns_warning`:**
+
+- `dns_note` present → the new fallback URL was wired up; warn the user it
+  may take 1–10 min for SSL to provision before the URL serves.
+- `dns_warning` present → the slug was saved but DNS / CF attach failed.
+  The `urls.fallback` field is still returned (it's just `{slug}.{base}`
+  string formatting) but the URL will NOT resolve until the issue is
+  fixed. Surface the warning verbatim to the user — don't tell them the
+  URL is ready.
+- Neither present → self-hosted portal without CF/SITES_BASE_DOMAIN
+  configured; URL behaviour is up to the operator.
+
+The old fallback URL keeps working (bookmarks + SEO survive). Customer
+can manually deprovision the old one via the portal.
+
 ## Safety boundaries
 
 - **HTML is sanitized at save.** No `<script>`, no `onclick`, no
-  `javascript:` URLs in page or partial bodies. Write responses include
-  a `sanitization_warnings: []` array listing what got stripped, so you
-  see when an input was modified.
-- **scripts_head, scripts_body_end, custom_css** are read-stripped on
-  `read_site_settings` and silently dropped on `update_site_settings`.
+  `javascript:` URLs in page or partial bodies. `<style>` blocks DO
+  survive — multi-page sites need authored CSS for `@media` queries,
+  `:hover`, theming, etc. Inside `<style>` we strip a small list of
+  legacy code-execution constructs (`expression()`, `behavior:url`,
+  `@import`, `url(javascript:)`) but leave normal CSS alone.
+- **Write responses include `sanitization_warnings: []` (strings) and
+  `sanitization_details: []`** (structured records `{ kind, label,
+  count, bytes? }`). Use the structured form to programmatically retry
+  with a fixed input.
+- **scripts_head, scripts_body_end, custom_css** are now writable via
+  `update_site_settings` and readable via `read_site_settings`. Same
+  trust model as user-authored block-type JS: an API caller with a valid
+  bearer token takes responsibility for what they ship. The chat AI
+  inside the portal continues to NOT expose these fields, so a
+  conversation-driven assistant can't smuggle scripts in.
 - **The API key is site-scoped.** Cross-site reach is impossible — a
   key on the wrong site returns 401, indistinguishable from "bad token".
 - **Audit log.** Every state-changing call (POST / PATCH / PUT /
@@ -301,9 +409,10 @@ stakeholder review.
 | **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` |
-| **Pages — meta** | `get_page_blocks`, `get_page_preview` |
-| **Global blocks** | `list_partials` (summary by default), `read_partial`, `create_free_block`, `update_partial`, `replace_partial`, `delete_partial`, `find_pages_using_block`, `list_blocks_with_usage` |
-| **Block types** | `list_block_types`, `read_block_type`, `find_pages_using_block_type` |
+| **Pages — blocks** | `get_page_blocks`, `add_block`, `update_block`, `move_block`, `remove_block`, `set_page_mode`, `convert_page_to_blocks` |
+| **Pages — meta** | `get_page_preview` |
+| **Global blocks (partials)** | `list_partials` (summary by default), `read_partial`, `create_free_block`, `update_partial`, `replace_partial`, `delete_partial`, `find_pages_using_block`, `list_blocks_with_usage` |
+| **Block types** | `list_block_types`, `read_block_type`, `find_pages_using_block_type`, `export_block_types`, `import_block_types` |
 | **Collections** | `create_collection`, `update_collection_schema`, `delete_collection`, `list_collections`, `read_collection`, `list_collection_items` (richtext hidden by default), `read_collection_item`, `batch_read_collection_items`, `create_collection_item`, `update_collection_item`, `delete_collection_item`, `regenerate_collection_listing` |
 | **Media** | `list_media`, `read_media`, `create_upload_url`, `upload_media_from_url`, `upload_media_inline`, `update_media`, `delete_media`, `generate_image_variants`, `suggest_alt_text_context` |
 | **Redirects** | `list_redirects`, `create_redirect`, `delete_redirect` |

package/dist/index.js

@@ -29,6 +29,7 @@ import { versionTools } from './tools/versions.js';
 import { deployTools } from './tools/deploy.js';
 import { previewTools } from './tools/preview.js';
 import { blockTypeTools } from './tools/block-types.js';
+import { pageBlockTools } from './tools/page-blocks.js';
 import { settingsTools } from './tools/settings.js';
 import { siteTools } from './tools/sites.js';
 const VERSION = '0.1.0';
@@ -76,6 +77,7 @@ async function main() {
         ...pageTools,
         ...partialTools,
         ...blockTypeTools,
+        ...pageBlockTools,
         ...collectionTools,
         ...mediaTools,
         ...redirectTools,

package/dist/tools/block-types.js

@@ -6,6 +6,42 @@ function v(version) {
     return version ? { version } : undefined;
 }
 export const blockTypeTools = [
+    {
+        name: 'export_block_types',
+        description: 'Pack custom block types into a .tcblocks zip (base64). When `ids` is omitted, every user-created block type is bundled. Useful for moving blocks between sites or backing them up — the returned zip is a portable package the import tool reads back.',
+        inputSchema: {
+            ids: z.array(z.string()).optional().describe('Specific block-type ids to include. Omit to export every user-created block.'),
+            name: z.string().optional().describe('Package name (default: {site}-blocks).'),
+            version: z.string().optional().describe('Package version (default: 1.0.0).'),
+            version_branch: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const query = {};
+            if (args.ids?.length)
+                query.ids = args.ids.join(',');
+            if (args.name)
+                query.name = args.name;
+            if (args.version)
+                query.version = args.version;
+            if (args.version_branch)
+                query.version = args.version_branch;
+            const res = await client.get(siteId, 'blocks/export', query);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'import_block_types',
+        description: 'Install block types from a .tcblocks package. Provide the zip as base64. Re-importing the same package overwrites existing blocks with the same id (package_name/block_name). Each imported BlockType may include arbitrary CSS and JS — the caller is responsible for trusting the source. Returns counts of created vs updated docs.',
+        inputSchema: {
+            zip_base64: z.string().describe('Base64-encoded .tcblocks zip.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const v = args.version ? { version: args.version } : undefined;
+            const res = await client.post(siteId, 'blocks/import', { zip_base64: args.zip_base64 }, v);
+            return ok(res);
+        }),
+    },
     {
         name: 'list_block_types',
         description: 'List registered block types with their schemas. Most sites have none today; this fills in when the block editor ships.',

package/dist/tools/page-blocks.js

@@ -0,0 +1,155 @@
+// Page-block mutation tools. Five primitives (get/add/update/move/remove)
+// plus a one-shot HTML→blocks converter. All target the active version
+// (override with `version`).
+//
+// The AI agent uses these to author block-mode pages directly. For
+// HTML-mode pages, `convert_page_to_blocks` is the bridge — call with
+// `dry_run: true` first to preview, then `dry_run: false, switch_mode:
+// true` to commit.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+const blockSchema = z.object({
+    id: z.string().optional().describe('Stable id. Omit to let the server generate one.'),
+    type: z.string().describe('Block type id, e.g. "core/heading", "core/section", or a custom "user/banner".'),
+    data: z.record(z.unknown()).optional().describe('Field values matching the block-type schema.'),
+    children: z.array(z.any()).optional().describe('Nested blocks for container types.'),
+    slots: z.array(z.array(z.any())).optional().describe('Slot contents for slot-container types.'),
+    style_overrides: z.object({
+        spacing_before: z.string().optional(),
+        spacing_after: z.string().optional(),
+        custom_css: z.string().optional(),
+        custom_class: z.string().optional(),
+        html_id: z.string().optional(),
+    }).optional(),
+}).passthrough();
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const pageBlockTools = [
+    {
+        name: 'get_page_blocks',
+        description: 'Read a page\'s block tree. Returns content_mode (html or blocks) and the blocks array. Empty array for HTML-mode pages — those store body content in html_content instead. Use this before any block mutation so you know what you\'re modifying.',
+        inputSchema: {
+            page_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'add_block',
+        description: 'Insert a block into a page. With no parent_id, inserts at top level. Otherwise inserts as a child (or into the named slot for slot-containers). Position defaults to "end". For slot containers, slot_index picks the slot; for regular containers it\'s ignored.',
+        inputSchema: {
+            page_id: z.string(),
+            block: blockSchema,
+            parent_id: z.string().optional().nullable(),
+            slot_index: z.number().int().min(0).optional(),
+            position: z.number().int().min(0).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, {
+                block: args.block,
+                parent_id: args.parent_id,
+                slot_index: args.slot_index,
+                position: args.position,
+            }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_block',
+        description: 'Update a block\'s data fields (shallow merge), style overrides, or responsive settings. Does not modify children or slots — use move/add/remove for structural changes.',
+        inputSchema: {
+            page_id: z.string(),
+            block_id: z.string(),
+            data: z.record(z.unknown()).optional(),
+            style_overrides: z.object({
+                spacing_before: z.string().optional(),
+                spacing_after: z.string().optional(),
+                custom_css: z.string().optional(),
+                custom_class: z.string().optional(),
+                html_id: z.string().optional(),
+            }).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, {
+                block_id: args.block_id,
+                data: args.data,
+                style_overrides: args.style_overrides,
+            }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'move_block',
+        description: 'Reparent or reorder a block. target_parent_id=null moves to top level. For slot containers, target_slot_index picks the slot. Cycles (moving a block into its own descendant) are rejected.',
+        inputSchema: {
+            page_id: z.string(),
+            block_id: z.string(),
+            target_parent_id: z.string().optional().nullable(),
+            target_slot_index: z.number().int().min(0).optional(),
+            target_position: z.number().int().min(0).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.put(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, {
+                block_id: args.block_id,
+                target_parent_id: args.target_parent_id,
+                target_slot_index: args.target_slot_index,
+                target_position: args.target_position,
+            }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'remove_block',
+        description: 'Remove a block and everything inside it from a page.',
+        inputSchema: {
+            page_id: z.string(),
+            block_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const query = { block_id: args.block_id };
+            if (args.version)
+                query.version = args.version;
+            const res = await client.del(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, query);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'set_page_mode',
+        description: 'Safely switch a page\'s content_mode between "blocks" and "html". Always snapshots a revision before the flip so the previous state is restorable. HTML → blocks with `convert: true` also runs the heuristic converter so the page starts with a populated tree. Blocks → HTML drops the block tree (the revision retains it). Prefer this over `update_page patch={content_mode}` because that bypasses snapshotting.',
+        inputSchema: {
+            page_id: z.string(),
+            to: z.enum(['blocks', 'html']).describe('Target mode.'),
+            convert: z.boolean().optional().describe('When going to blocks: run the htmlToBlocks heuristic on html_content. Ignored for blocks → html.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/mode`, { to: args.to, convert: args.convert ?? false }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'convert_page_to_blocks',
+        description: 'Heuristically convert a page\'s html_content into a block tree. By default runs as dry_run and returns the proposed blocks without writing. Pass dry_run: false to apply, and switch_mode: true to flip content_mode to "blocks" so the renderer uses the new tree. For a safer one-call switch with revision snapshot, use `set_page_mode` with `convert: true` instead.',
+        inputSchema: {
+            page_id: z.string(),
+            dry_run: z.boolean().optional().describe('Default true. When true, returns the proposed tree without writing.'),
+            switch_mode: z.boolean().optional().describe('When applying (dry_run=false), flip content_mode to "blocks". Default false.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks/convert`, {
+                dry_run: args.dry_run ?? true,
+                switch_mode: args.switch_mode ?? false,
+            }, v(args.version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/pages.js

@@ -50,17 +50,20 @@ export const pageTools = [
     },
     {
         name: 'create_page',
-        description: 'Create a new HTML-mode page. Slug is derived from title if omitted; default status is "draft". Returns the created page.',
+        description: 'Create a new page. Defaults to blocks-mode (recommended) — the new page seeds with a heading + prose block built from the title. Pass content_mode="html" to opt out. Slug is derived from title when omitted; default status is "draft". Returns the created page.',
         inputSchema: {
             title: z.string().min(1),
             slug: z.string().optional(),
-            html_content: z.string().optional(),
+            content_mode: z.enum(['blocks', 'html']).optional().describe('Default "blocks". "html" stores body in html_content; "blocks" stores a Block[] tree.'),
+            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(),
             seo_title: z.string().optional(),
             seo_description: z.string().optional(),
             kind: z.enum(['page', 'article']).optional(),
             author: z.string().optional(),
             language: z.string().optional().describe('BCP-47 tag overriding the site default (e.g. "en" on an otherwise Swedish site).'),
+            template: z.string().optional().describe('Page template id (PageTemplate). Wraps the body in the template tree at render time.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -71,14 +74,16 @@ export const pageTools = [
     },
     {
         name: 'update_page',
-        description: 'Shallow-merge update on a page (only the fields you pass change). Returns the updated page. For "replace this page entirely", use replace_page instead.',
+        description: 'Shallow-merge update on a page (only the fields you pass change). Returns the updated page. For "replace this page entirely", use replace_page instead. To switch content_mode safely with a revision snapshot + optional auto-conversion, prefer `set_page_mode`.',
         inputSchema: {
             page_id: z.string(),
             patch: z
                 .object({
                 title: z.string().optional(),
                 slug: z.string().optional(),
+                content_mode: z.enum(['blocks', 'html']).optional().describe('Changing this raw skips revision snapshotting — for safe switches use set_page_mode.'),
                 html_content: z.string().optional(),
+                blocks: z.array(z.any()).optional().describe('Block tree, only used when content_mode="blocks".'),
                 status: z.enum(['draft', 'review', 'unlisted', 'published']).optional(),
                 kind: z.enum(['page', 'article']).optional(),
                 author: z.string().optional(),
@@ -179,18 +184,8 @@ export const pageTools = [
             return ok(res);
         }),
     },
-    {
-        name: 'get_page_blocks',
-        description: 'Get the block hierarchy for a page. For today\'s HTML-mode pages returns { content_mode: "html", html_content }; once the block editor lands, block-mode pages return { content_mode: "blocks", blocks: [...] }.',
-        inputSchema: {
-            page_id: z.string(),
-            version: versionParam,
-        },
-        handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, v(args.version));
-            return ok(res);
-        }),
-    },
+    // get_page_blocks lives in tools/page-blocks.ts alongside the rest of
+    // the block-tree mutation tools (add/update/move/remove/convert).
     {
         name: 'get_page_preview',
         description: 'Get rendered HTML for one page (header-authed read). Returns { rendered_html, internal_links[] }. For a clickable preview URL use get_preview_link instead.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timelesscms-com/mcp-server",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Model Context Protocol server for the TimelessCMS public API. Use with Claude Code or any MCP-compatible client to manage a TimelessCMS site.",
   "license": "MIT",
   "type": "module",