@gravitykit/block-mcp 2.0.0-beta → 2.0.1

package/src/tools/mutate.ts

@@ -12,6 +12,7 @@
 import type { WordPressBlockClient } from '../client.js';
 import type { MutationOp, MutationRequest, MutationResponse, StaticBlockWarning } from '../types.js';
 import { formatPreferenceWarning } from '../preferences.js';
+import { BLOCK_INPUT_SCHEMA } from './write.js';
 
 const OPS: readonly MutationOp[] = [
   'update-attrs',
@@ -61,14 +62,8 @@ export const MUTATE_TOOLS = [{
       attributes:  { type: 'object',  description: 'update-attrs: attributes to merge.' },
       innerHTML:   { type: 'string',  description: 'update-html: replacement innerHTML.' },
       block: {
-        type: 'object',
-        description: 'replace-block / insert-child: { name, attributes?, innerHTML?, innerBlocks? }.',
-        properties: {
-          name:        { type: 'string', description: 'Fully-qualified block name.' },
-          attributes:  { type: 'object' },
-          innerHTML:   { type: 'string' },
-          innerBlocks: { type: 'array' },
-        },
+        ...BLOCK_INPUT_SCHEMA,
+        description: 'replace-block / insert-child: a block def. Nests recursively via `innerBlocks`; containers need their empty wrapper `innerHTML`.',
       },
       wrapper: {
         type: 'object',

package/src/tools/read.ts

@@ -71,6 +71,14 @@ export const READ_TOOLS = [
           type: 'boolean',
           description: 'Default true. When true, missing block refs (attrs.metadata.gk_ref) are assigned and persisted silently (no revision created). Set false for read-only callers that don\'t want write side effects — refs in the response will not resolve in subsequent mutation calls.',
         },
+        limit: {
+          type: 'number',
+          description: 'Page size: top-level blocks per response. When more remain, the response carries `pagination.next_cursor` — pass it back via `cursor` to fetch the next page.',
+        },
+        cursor: {
+          type: 'string',
+          description: "Opaque cursor from a previous response's `pagination.next_cursor`. Omit on the first request.",
+        },
       },
     },
   },
@@ -139,6 +147,8 @@ export async function handleReadTool(
       const summaryOnly = args.summary_only as boolean | undefined;
       const includeLegacyPaths = args.include_legacy_paths as boolean | undefined;
       const persistRefs = args.persist_refs as boolean | undefined;
+      const limit = args.limit as number | undefined;
+      const cursor = args.cursor as string | undefined;
 
       if ((postId === undefined || postId === null) && !url) {
         throw new Error('Either post_id or url is required');
@@ -154,6 +164,8 @@ export async function handleReadTool(
         summary_only: summaryOnly,
         include_legacy_paths: includeLegacyPaths,
         ...(persistRefs !== undefined ? { persist_refs: persistRefs } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+        ...(cursor !== undefined ? { cursor } : {}),
       });
 
       // summary_only mode: return server summary as-is.
@@ -166,12 +178,16 @@ export async function handleReadTool(
 
       const enriched = enrichBlockList(response.blocks || []);
 
+      // Surface pagination meta (incl. next_cursor) so the agent can page.
+      const pagination = (response as { pagination?: unknown }).pagination;
+
       return {
         post_id: postId,
         summary: (response as { summary?: unknown }).summary,
         blocks: enriched.blocks,
         block_count: enriched.blocks.length,
         warnings: enriched.warnings,
+        ...(pagination !== undefined ? { pagination } : {}),
       };
     }
 

package/src/tools/write.ts

@@ -192,7 +192,13 @@ export const WRITE_TOOLS = [
   {
     name: 'insert_blocks',
     description:
-      'Insert blocks at a top-level position. Anchoring options (use one): `after_ref`/`before_ref` (stable gk_ref — recommended), or `after_top_level`/`before_top_level` (top_level_counter). Omit anchors or set after_top_level:-1 to append; "start" prepends. Legacy-tier blocks rejected per the site policy. Blocks whose attribute schema is HTML-sourced (e.g. core/paragraph `content`, core/image `url`) must include `innerHTML` matching the attribute(s) — attribute-only inserts are rejected with `inner_html_required` to prevent the self-closing-block / "invalid content" failure mode. Response.inserted[] carries `ref`, `path`, and `top_level_counter` so you can chain edit_block_tree without re-reading.',
+      'Insert top-level blocks into a post.\n\n' +
+      'POSITIONING — use exactly ONE anchor (any other key, e.g. `after`, `before`, `position`, is rejected):\n' +
+      '- `before_ref` / `after_ref` — gk_ref from get_page_blocks. Recommended: refs survive sibling shifts.\n' +
+      '- `before_top_level` / `after_top_level` — top_level_counter position.\n' +
+      '- Prepend at the very top: `before_top_level: 0`. Append at the end: omit all anchors.\n\n' +
+      'CONTENT — legacy-tier blocks are rejected per the site policy. Blocks with HTML-sourced attributes (e.g. core/paragraph `content`, core/image `url`) must include matching `innerHTML`; attribute-only inserts fail with `inner_html_required`.\n\n' +
+      'VERIFY — the response\'s inserted[] returns `ref`, `path`, and `top_level_counter`: confirm the block landed where you intended before moving on. The refs let you chain edit_block_tree without re-reading.',
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, title: 'Insert blocks' },
     outputSchema: INSERTED_REFS_SCHEMA,
     inputSchema: {
@@ -201,7 +207,7 @@ export const WRITE_TOOLS = [
         post_id: { type: 'number', description: 'Post ID.' },
         after_top_level: {
           type: ['number', 'string'],
-          description: 'top_level_counter to insert AFTER. -1/omit = append, "start" = prepend.',
+          description: 'top_level_counter to insert AFTER (omit or -1 = append). To prepend at the very top, prefer `before_top_level: 0`.',
         },
         before_top_level: {
           type: 'number',
@@ -217,7 +223,7 @@ export const WRITE_TOOLS = [
         },
         blocks: {
           type: 'array',
-          description: 'Blocks to insert.',
+          description: 'Blocks to insert. Each def nests recursively via `innerBlocks` — build a whole container (group/columns/callout) with its children in this one call; give the container its empty wrapper `innerHTML` (e.g. \'<div class="wp-block-group"></div>\').',
           items: BLOCK_INPUT_SCHEMA,
         },
       },
@@ -260,7 +266,7 @@ export const WRITE_TOOLS = [
         post_id: { type: 'number', description: 'Post ID.' },
         start: { type: 'number', description: 'top_level_counter of first block to replace.' },
         count: { type: 'number', description: 'How many top-level blocks to remove. Pass 0 to insert without removing.' },
-        blocks: { type: 'array', description: 'Replacement blocks. May be empty (pure delete) or any length.', items: BLOCK_INPUT_SCHEMA },
+        blocks: { type: 'array', description: 'Replacement blocks. May be empty (pure delete) or any length. Each def nests recursively via `innerBlocks` for containers (group/columns/callout) — give the container its empty wrapper `innerHTML`.', items: BLOCK_INPUT_SCHEMA },
       },
       required: ['post_id', 'start', 'count', 'blocks'],
     },
@@ -297,7 +303,7 @@ export const WRITE_TOOLS = [
       type: 'object' as const,
       properties: {
         post_id: { type: 'number', description: 'Post ID.' },
-        blocks: { type: 'array', description: 'Complete blocks array (replaces all).', items: BLOCK_INPUT_SCHEMA },
+        blocks: { type: 'array', description: 'Complete blocks array (replaces all). Each def nests recursively via `innerBlocks` for containers (group/columns/callout) — give the container its empty wrapper `innerHTML`.', items: BLOCK_INPUT_SCHEMA },
       },
       required: ['post_id', 'blocks'],
     },

package/src/types.ts

@@ -275,8 +275,12 @@ export interface BlockWriteResponse {
 /** Response from block delete (DELETE) operations. */
 export interface BlockDeleteResponse {
   success: boolean;
+  /** Flat index of the first removed block */
+  deleted_index: number;
   /** Number of blocks removed */
-  removed: number;
+  deleted_count: number;
+  /** Non-fatal warnings emitted by the delete */
+  warnings: unknown[];
   /** WordPress revision ID of the pre-edit snapshot */
   before_revision_id: number;
   /** WordPress revision ID of the post-edit state */
@@ -566,16 +570,8 @@ export interface MutationRequest {
   ref?: string;
   attributes?: Record<string, unknown>;
   innerHTML?: string;
-  block?: {
-    name: string;
-    attributes?: Record<string, unknown>;
-    innerHTML?: string;
-    innerBlocks?: Array<{
-      name: string;
-      attributes?: Record<string, unknown>;
-      innerHTML?: string;
-    }>;
-  };
+  /** replace-block / insert-child payload. Nests recursively via innerBlocks. */
+  block?: BlockInput;
   wrapper?: {
     name?: string;
     attributes?: Record<string, unknown>;
@@ -584,12 +580,10 @@ export interface MutationRequest {
   destination?: number[];
   /** Alternative to `destination` — resolve from a ref instead of a path. */
   destination_ref?: string;
-  /** Alias for destination — path of block to insert BEFORE (pre-move indexing). */
-  before?: number[];
-  /** Alternative to `before` — resolve from a ref instead of a path. */
-  before_ref?: string;
   /** Number of consecutive blocks to move/operate on. Default: 1. */
   count?: number;
+  /** Preview the mutation without writing. */
+  dry_run?: boolean;
 }
 
 /** Warning about static block markup staleness. */
@@ -622,7 +616,11 @@ export interface MutationResponse {
 // v1.2 — Docs Lifecycle: Posts
 // ============================================
 
-/** A block in structured form, suitable for create_post's `blocks` input. */
+/**
+ * A block in structured form — the def shape accepted by every write that
+ * creates blocks (create_post `blocks`, insert_blocks, replace ranges/all,
+ * mutate replace-block / insert-child). Nests recursively via `innerBlocks`.
+ */
 export interface BlockInput {
   name: string;
   attributes?: Record<string, unknown>;
@@ -631,6 +629,12 @@ export interface BlockInput {
   innerContent?: unknown[];
 }
 
+/** Partial-update payload for a single existing block (update_block / by-ref / batch items). */
+export interface BlockPatch {
+  attributes?: Record<string, unknown>;
+  innerHTML?: string;
+}
+
 export type CreatePostStatus = 'draft' | 'pending' | 'private' | 'publish' | 'future';
 export type UpdatePostStatus = CreatePostStatus | 'trash';
 export type CommentPingStatus = 'open' | 'closed';
@@ -857,6 +861,6 @@ export interface YoastBulkUpdateItem extends YoastSEOFields {
 }
 
 export type YoastBulkUpdateResponse = Array<
-  | { post_id: number; success: true; seo: YoastSEOMeta }
-  | { post_id: number; success: false; error: string }
+  | YoastSEOMeta
+  | { post_id?: number; error: string }
 >;

package/src/validate-args.ts

@@ -0,0 +1,109 @@
+/**
+ * Tool-argument validation for the MCP dispatch.
+ *
+ * The MCP SDK does not validate CallTool arguments against a tool's
+ * `inputSchema`, so a misnamed parameter (e.g. `after` instead of
+ * `after_top_level`) was silently dropped and the handler ran with its
+ * defaults — turning a positioning mistake into a wrong-but-"successful" write.
+ *
+ * This rejects unknown top-level keys loudly — naming the valid ones with a
+ * "did you mean" suggestion — and flags missing required keys, before the
+ * handler runs.
+ */
+
+interface InputSchema {
+  properties?: Record<string, unknown>;
+  required?: string[];
+  additionalProperties?: unknown;
+}
+
+/**
+ * Throw a descriptive Error if `args` carries keys the tool doesn't declare, or
+ * omits a required key. No-op when the tool has no schema, or when the schema
+ * explicitly opts into additional properties.
+ */
+export function validateToolArgs(
+  toolName: string,
+  inputSchema: InputSchema | undefined,
+  args: Record<string, unknown>,
+): void {
+  const properties = inputSchema?.properties;
+  if (!properties) {
+    return; // No declared shape — nothing to validate against.
+  }
+
+  const known = Object.keys(properties);
+  const provided = Object.keys(args ?? {});
+
+  // Respect an explicit opt-in to extra props (a map-shaped schema sets
+  // `additionalProperties` to a schema object rather than leaving it absent).
+  const allowsExtra =
+    inputSchema?.additionalProperties !== undefined && inputSchema.additionalProperties !== false;
+
+  if (!allowsExtra) {
+    const unknown = provided.filter((k) => !known.includes(k));
+    if (unknown.length > 0) {
+      const parts = unknown.map((k) => {
+        const near = closestKey(k, known);
+        return near ? `'${k}' (did you mean '${near}'?)` : `'${k}'`;
+      });
+      throw new Error(
+        `Unknown parameter(s) for ${toolName}: ${parts.join(', ')}. ` +
+          `Valid parameters: ${known.join(', ')}.`,
+      );
+    }
+  }
+
+  const required = inputSchema?.required ?? [];
+  const missing = required.filter((r) => !(r in (args ?? {})));
+  if (missing.length > 0) {
+    throw new Error(`Missing required parameter(s) for ${toolName}: ${missing.join(', ')}.`);
+  }
+}
+
+/**
+ * Best-effort suggestion for a mistyped key. Prefers a known key that shares a
+ * prefix/substring with the input — the common agent mistake is a shortened
+ * name like `after` for `after_top_level` — then falls back to edit distance.
+ */
+function closestKey(input: string, candidates: string[]): string | null {
+  const lc = input.toLowerCase();
+  const affixed = candidates
+    .filter((c) => {
+      const cl = c.toLowerCase();
+      return cl.startsWith(lc) || lc.startsWith(cl) || cl.includes(lc) || lc.includes(cl);
+    })
+    .sort((a, b) => a.length - b.length);
+  if (affixed.length > 0) {
+    return affixed[0];
+  }
+
+  let best: string | null = null;
+  let bestDist = Infinity;
+  for (const c of candidates) {
+    const d = levenshtein(lc, c.toLowerCase());
+    if (d < bestDist) {
+      bestDist = d;
+      best = c;
+    }
+  }
+  return best !== null && bestDist <= Math.max(2, Math.ceil(input.length / 2)) ? best : null;
+}
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  let curr = new Array<number>(n + 1);
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}