@timelesscms-com/mcp-server 0.3.0 → 0.4.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/package.json

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