@timelesscms-com/mcp-server 0.3.0 → 0.5.0

package/AGENTS.md

@@ -68,11 +68,17 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
   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.
+- **Block types.** A site has three sources of block types:
+  - **Core** (origin: 'core', ids like `core/section`) — shipped in
+    the platform, always available.
+  - **User** (origin: 'user') — created in the portal's block-types UI.
+  - **Third-party** (origin: 'third_party') — imported from .tcblocks
+    packages via `import_block_types`.
+
+  `list_block_types` returns ALL of them in one list, with each entry's
+  full schema (field names, types, defaults). Always call this FIRST
+  before working with blocks — never hardcode block ids or field names,
+  the available set is per-site.
 
 - **Redirects.** `from_path → to_path` with status code 301 / 302.
   Auto-created when you change a page's slug.
@@ -108,8 +114,11 @@ goes through the MCP:
    `include_content: true` if you actually need the bodies inline.
 5. `list_collections` — what content types exist + their schemas +
    `route_template` (so you know if items have URLs).
-6. `list_block_types` — registered block types (often empty today;
-   fills in once the block editor lands).
+6. `list_block_types` — every block type usable on this site: core
+   (always available, ids like `core/section`), custom (origin: 'user'),
+   and third-party (origin: 'third_party'). Each entry includes the
+   full schema so you know what `data.X` fields each block accepts.
+7. `list_page_templates` — PageTemplate docs that wrap pages.
 
 You usually want at least #1 + #2 + a sampling from #3 before
 proposing any design change, so you mirror the conventions in use.
@@ -182,13 +191,20 @@ Edits to the block update every page that includes it. Use
 ### "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:
+prose block. Discover-then-build:
 
 ```
+list_block_types
+# → [{ id: "core/section", category: "layout", container: true, schema: [{ name: "width", type: "select", options: ["narrow","normal","wide","full"] }, …] },
+#    { id: "core/columns", container: "slots", slot_count: 2, slot_labels: ["Left","Right"], schema: [...] },
+#    { id: "hero_bold", origin: "user", schema: [...] },   ← any custom blocks on this site
+#    …]
+
 get_page_blocks page_id=home
-# returns { content_mode: 'blocks', blocks: [...] }
+# → { content_mode: 'blocks', blocks: [...] }
+
 add_block page_id=home block={ type: 'core/section', data: { width: 'wide' } }
-# returns { added_id: 'blk_xyz', blocks: [...] }
+# → { added_id: 'blk_xyz', blocks: [...] }
 add_block page_id=home parent_id="blk_xyz" block={
   type: 'core/heading', data: { text: 'Pricing', level: 'h2' }
 }
@@ -197,6 +213,10 @@ add_block page_id=home parent_id="blk_xyz" block={
 }
 ```
 
+For an unfamiliar custom block, `read_block_type id="..."` gives the
+full field list (types, defaults, required) so you don't ship invalid
+`data`.
+
 Updating, moving, removing blocks: `update_block`, `move_block`,
 `remove_block` (all by `block_id`).
 

package/dist/tools/block-types.js

@@ -44,16 +44,24 @@ export const blockTypeTools = [
     },
     {
         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.',
-        inputSchema: { version: versionParam },
+        description: 'Discover every block type usable on this site. Returns ALL of them in one list: core blocks (id like "core/section", always available), custom blocks (origin: "user", created in the portal), and third-party blocks (origin: "third_party", imported from .tcblocks packages). Each entry includes id, label, category, container/slot info, origin, and the full schema (fields with name/type/label/required/options/default). Call this FIRST when starting block-mode work — never hardcode block ids; the available set is per-site.',
+        inputSchema: {
+            include_core: z.boolean().optional().describe('Default true. Set false to get only custom + third-party (rarely needed).'),
+            version: versionParam,
+        },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.get(siteId, 'block-types', v(args.version));
+            const query = {};
+            if (args.version)
+                query.version = args.version;
+            if (args.include_core === false)
+                query.include_core = 'false';
+            const res = await client.get(siteId, 'block-types', query);
             return ok(res);
         }),
     },
     {
         name: 'read_block_type',
-        description: 'Read one block type\'s schema.',
+        description: "Full schema for one block type. Returns the BlockType doc with template, styles, optional script, and the field-definitions array. Use this when list_block_types' summary isn't enough — e.g. before add_block on a custom block whose data fields you haven't seen.",
         inputSchema: {
             type_id: z.string(),
             version: versionParam,

package/dist/tools/pages.js

@@ -151,9 +151,17 @@ export const pageTools = [
             // 2. Build the new page body. Title + slug from args, everything else
             //    copied — except the new page always starts as a draft so cloning
             //    a published page doesn't accidentally publish a half-edited copy.
+            // Critical: preserve the source's content_mode exactly. Without
+            // this, create_page falls back to its blocks-default and seeds a
+            // fresh heading+prose tree, leaving the clone with TWO content
+            // sources (the copied html_content AND a default blocks[]). Bug
+            // surfaced in MCP-FEEDBACK-2.md from the Sundsvallsflytt demo build.
+            const srcMode = src.content_mode ?? 'html';
             const body = {
                 title: args.title,
-                html_content: src.html_content,
+                content_mode: srcMode,
+                html_content: srcMode === 'html' ? src.html_content : '',
+                blocks: srcMode === 'blocks' ? (src.blocks ?? []) : undefined,
                 seo_title: src.seo_title,
                 seo_description: src.seo_description,
                 og_image: src.og_image,

package/dist/tools/settings.js

@@ -1,12 +1,16 @@
-// Settings tools. scripts_head, scripts_body_end, and custom_css are NOT
-// exposed — the server omits them on read and silently drops them on
-// write. Customers edit those manually in /app/sites/{id}/settings.
+// Settings tools. scripts_head, scripts_body_end, and custom_css ARE
+// writable via the public API (as of mcp-server 0.4.x) — the v1 route
+// accepts them and they round-trip through read_site_settings. Same
+// trust model as user-authored block-type JS: a bearer-token caller
+// takes responsibility for what they ship. The portal chat AI still
+// doesn't expose these fields, so conversation-driven assistants can't
+// smuggle scripts in.
 import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
 export const settingsTools = [
     {
         name: 'read_site_settings',
-        description: 'Read the site\'s name, tagline, logo, favicon, colors, fonts, contact info, social links, default SEO suffix.',
+        description: "Read every site setting: name, tagline, logo, favicon, colors, fonts, contact info, social links, default SEO suffix, language, robots_txt, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css.",
         handler: withErrorBoundary(async (_args, { client, siteId }) => {
             const res = await client.get(siteId, 'settings');
             return ok(res);
@@ -14,7 +18,7 @@ export const settingsTools = [
     },
     {
         name: 'update_site_settings',
-        description: 'Patch site settings. Only the fields you pass change. Nested objects (colors, fonts, contact, social) are shallow-merged. scripts_* and custom_css are not writable.',
+        description: 'Patch site settings. Only the fields you pass change. Nested objects (colors, fonts, contact, social) are shallow-merged. scripts_head / scripts_body_end / custom_css ARE writable here — useful for a global stylesheet across all pages. Whatever you ship in those fields runs verbatim on the rendered site, so treat them as code, not data.',
         inputSchema: {
             site_name: z.string().optional(),
             tagline: z.string().optional(),
@@ -23,6 +27,10 @@ export const settingsTools = [
             default_seo_suffix: z.string().optional(),
             language: z.string().optional().describe('BCP-47 tag (e.g. "en", "sv", "en-GB"). Drives <html lang> on the rendered site.'),
             robots_txt: z.string().optional(),
+            // Scriptable surfaces. Trusted because the caller has an API key.
+            scripts_head: z.string().optional().describe('Raw HTML injected into <head> on every page. Use for analytics, fonts, third-party CSS links.'),
+            scripts_body_end: z.string().optional().describe('Raw HTML injected just before </body> on every page. Use for chat widgets, deferred analytics.'),
+            custom_css: z.string().optional().describe('Global CSS shipped in <style> at the end of <head>. Lets you define site-wide design tokens (CSS variables, @media queries, :hover states) without inlining on every element.'),
             colors: z.record(z.string()).optional(),
             fonts: z.record(z.unknown()).optional(),
             contact: z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timelesscms-com/mcp-server",
-  "version": "0.3.0",
+  "version": "0.5.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",