@gravitykit/block-mcp 2.0.0-beta → 2.1.0

package/src/preferences.ts

@@ -117,12 +117,13 @@ export function enrichPatternList(patterns: Pattern[]): {
     (a, b) => b.preference.score - a.preference.score
   );
 
-  // Classify by tier only — the server is the source of truth and already
-  // applied policy. Mixing in score-based fallbacks (the old logic) caused
-  // mis-bucketing: an `avoid`-tier pattern with score 5 leaked into the
-  // recommended bucket; a `recommended`-tier pattern with negative score
-  // was double-counted. Trust the tier.
-  const recommended = sorted.filter((p) => p.preference.tier === 'recommended');
+  // Classify by the tier the server emits (preferred/acceptable/avoid/legacy),
+  // which is the source of truth and has already applied policy. The
+  // "recommended" display bucket is the usable set (preferred + acceptable);
+  // avoid + legacy are the ones to steer away from.
+  const recommended = sorted.filter(
+    (p) => p.preference.tier === 'preferred' || p.preference.tier === 'acceptable'
+  );
   const avoid       = sorted.filter((p) => p.preference.tier === 'avoid' || p.preference.tier === 'legacy');
 
   const lines: string[] = [];
@@ -196,49 +197,41 @@ export function enrichBlockTypes(types: BlockType[]): {
   }
 
   const lines: string[] = [];
-
-  if (preferred.length > 0) {
-    const grouped = groupByNamespace(preferred);
-    for (const [ns, blocks] of Object.entries(grouped)) {
-      const names = blocks.map((t) => getShortName(t.name)).join(', ');
-      lines.push(`PREFERRED (${ns}/): ${names}`);
-    }
-  }
-  if (acceptable.length > 0) {
-    const grouped = groupByNamespace(acceptable);
-    for (const [ns, blocks] of Object.entries(grouped)) {
-      const names = blocks.map((t) => getShortName(t.name)).join(', ');
-      lines.push(`ACCEPTABLE (${ns}/): ${names}`);
-    }
-  }
-  if (avoid.length > 0) {
-    const grouped = groupByNamespace(avoid);
-    for (const [ns, blocks] of Object.entries(grouped)) {
-      const mappings = blocks.map((t) => {
-        const replacement = t.preference.replacement;
-        const shortName = getShortName(t.name);
-        return replacement ? `${shortName} -> use ${replacement}` : shortName;
-      });
-      lines.push(`AVOID (${ns}/): ${mappings.join(', ')}`);
-    }
-  }
-  if (legacy.length > 0) {
-    const grouped = groupByNamespace(legacy);
-    for (const [ns, blocks] of Object.entries(grouped)) {
-      const mappings = blocks.map((t) => {
-        const replacement = t.preference.replacement;
-        const shortName = getShortName(t.name);
-        return replacement ? `${shortName} -> use ${replacement}` : shortName;
-      });
-      lines.push(`LEGACY — DO NOT USE (${ns}/): ${mappings.join(', ')}`);
-    }
-  }
+  pushTierLines(lines, preferred, 'PREFERRED', false);
+  pushTierLines(lines, acceptable, 'ACCEPTABLE', false);
+  pushTierLines(lines, avoid, 'AVOID', true);
+  pushTierLines(lines, legacy, 'LEGACY — DO NOT USE', true);
 
   const guidance = lines.join('\n');
 
   return { block_types: types, guidance };
 }
 
+/**
+ * Append one guidance line per namespace group within a tier bucket.
+ * No-ops when the bucket is empty, so callers don't need their own length
+ * check. `withReplacement` switches between a plain name list (preferred /
+ * acceptable) and a `name -> use replacement` mapping (avoid / legacy).
+ */
+function pushTierLines(
+  lines: string[],
+  bucket: BlockType[],
+  label: string,
+  withReplacement: boolean
+): void {
+  if (bucket.length === 0) return;
+  const grouped = groupByNamespace(bucket);
+  for (const [ns, blocks] of Object.entries(grouped)) {
+    const names = blocks.map((t) => {
+      const shortName = getShortName(t.name);
+      if (!withReplacement) return shortName;
+      const replacement = t.preference.replacement;
+      return replacement ? `${shortName} -> use ${replacement}` : shortName;
+    });
+    lines.push(`${label} (${ns}/): ${names.join(', ')}`);
+  }
+}
+
 /**
  * Format a preference warning into a single human-readable line.
  *
@@ -252,6 +245,26 @@ export function formatPreferenceWarning(warning: PreferenceWarning): string {
   return `WARNING: ${warning.message}`;
 }
 
+/**
+ * Decorate a write-tool result with `formatted_warnings` when its `warnings`
+ * array is non-empty. Returns the result unchanged (no `formatted_warnings`
+ * key) when there are none, so callers don't leak an empty array into every
+ * clean response.
+ *
+ * @param result - A write-tool response shape carrying an optional `warnings` array
+ * @param formatWarning - Per-warning formatter (e.g. formatPreferenceWarning)
+ */
+export function withFormattedWarnings<T extends { warnings?: unknown[] }>(
+  result: T,
+  formatWarning: (warning: NonNullable<T['warnings']>[number]) => string
+): T & { formatted_warnings?: string[] } {
+  if (result.warnings && result.warnings.length > 0) {
+    const warnings = result.warnings as NonNullable<T['warnings']>;
+    return { ...result, formatted_warnings: warnings.map(formatWarning) };
+  }
+  return result;
+}
+
 // ============================================
 // Helpers
 // ============================================

package/src/rest-url.ts

@@ -0,0 +1,18 @@
+/**
+ * Build a REST URL on the permalink-independent `?rest_route=` form.
+ *
+ * Hardcoding `/wp-json/` breaks on plain-permalink sites (and any custom
+ * `rest_url_prefix`): the connector can complete the handshake, then every tool
+ * call 404s because the pretty REST route does not exist. The `?rest_route=`
+ * form works on every permalink configuration, matching the connector's own
+ * exchange URL (see src/connect.ts).
+ *
+ * @param siteUrl - WordPress site URL; trailing slashes are trimmed.
+ * @param routeSuffix - Route path after the namespace, e.g. `/instructions`.
+ *                      Empty (default) yields the axios base URL.
+ * @returns e.g. `https://site.test/?rest_route=/gk-block-api/v1/instructions`
+ */
+export function restRouteUrl(siteUrl: string, routeSuffix = ''): string {
+  const trimmed = siteUrl.replace(/\/+$/, '');
+  return `${trimmed}/?rest_route=/gk-block-api/v1${routeSuffix}`;
+}

package/src/tools/discovery.ts

@@ -8,6 +8,7 @@
 
 import type { WordPressBlockClient } from '../client.js';
 import { enrichBlockTypes, enrichPatternList } from '../preferences.js';
+import { coercePostId } from '../coerce.js';
 
 const READ_ANNOT = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true } as const;
 
@@ -166,12 +167,14 @@ export async function handleDiscoveryTool(
     case 'list_patterns': {
       const limit  = (args.limit as number | undefined) ?? 20;
       const offset = (args.offset as number | undefined) ?? 0;
+      // Fetch the full set (no server-side limit) and paginate locally, matching
+      // list_block_types. Passing limit: offset+limit truncated `total` to the
+      // fetched window and made next_offset always null on a full page — the
+      // agent then never saw that more patterns existed.
       const response = await client.getPatterns({
         q: args.search as string | undefined,
         synced: args.synced as boolean | undefined,
         min_score: args.min_score as number | undefined,
-        // Fetch enough to honor offset+limit. Server caps respond too.
-        limit: offset + limit,
         refresh: args.refresh as boolean | undefined,
       });
       const enriched = enrichPatternList(response.patterns);
@@ -225,18 +228,11 @@ export async function handleDiscoveryTool(
       ) {
         throw new Error('get_post_info requires one of: post_id, url, or slug');
       }
-      // Coerce well-formed integer strings (some MCP clients and untyped
-      // JSON send numeric IDs as strings) but reject everything else with
-      // the same "post_id must be a positive integer" error the schema
-      // documents. Floats are rejected because the contract is integer.
-      let normalizedPostId: number | undefined;
-      if (typeof postId === 'number' && Number.isInteger(postId) && postId > 0) {
-        normalizedPostId = postId;
-      } else if (typeof postId === 'string' && /^[0-9]+$/.test(postId)) {
-        normalizedPostId = parseInt(postId, 10);
-      } else if (postId !== undefined && postId !== null) {
-        throw new Error('get_post_info: post_id must be a positive integer');
-      }
+      // Coerce well-formed integer strings (some MCP clients and untyped JSON
+      // send numeric IDs as strings); undefined is allowed here because url/slug
+      // are alternate selectors. Shared with update_post / yoast_* so the whole
+      // tool surface accepts a post_id identically.
+      const normalizedPostId = coercePostId(postId, 'get_post_info');
       return await client.getPostInfo({
         post_id:   normalizedPostId,
         url:       typeof url === 'string' ? url : undefined,

package/src/tools/mutate.ts

@@ -11,7 +11,9 @@
 
 import type { WordPressBlockClient } from '../client.js';
 import type { MutationOp, MutationRequest, MutationResponse, StaticBlockWarning } from '../types.js';
-import { formatPreferenceWarning } from '../preferences.js';
+import { formatPreferenceWarning, withFormattedWarnings } from '../preferences.js';
+import { BLOCK_INPUT_SCHEMA } from './write.js';
+import { coercePostId } from '../coerce.js';
 
 const OPS: readonly MutationOp[] = [
   'update-attrs',
@@ -61,14 +63,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',
@@ -120,12 +116,12 @@ export async function handleMutateTool(
     throw new Error(`Unknown mutate tool: ${toolName}`);
   }
 
-  const postId = args.post_id as number;
+  const postId = coercePostId(args.post_id, 'edit_block_tree');
   const op = args.op as string;
   const path = args.path;
   const ref = args.ref as string | undefined;
 
-  if (postId === undefined || postId === null) throw new Error('post_id is required');
+  if (postId === undefined) throw new Error('post_id is required');
   // Op validation comes from the schema enum at request time; this guard
   // exists for direct programmatic callers that bypass the MCP transport.
   if (!op || !(OPS as readonly string[]).includes(op)) {
@@ -180,10 +176,20 @@ export async function handleMutateTool(
       requestBody.block = block as MutationRequest['block'];
       if (op === 'insert-child' && args.position !== undefined) {
         const position = args.position;
-        if (typeof position === 'number' && Number.isInteger(position)) {
+        if (typeof position === 'number' && Number.isInteger(position) && position >= -1) {
           requestBody.position = position;
         } else if (position === 'start' || position === 'end') {
           requestBody.position = position;
+        } else if (typeof position === 'string' && /^-?\d+$/.test(position)) {
+          // The schema advertises `position` as integer|string; accept a
+          // numeric string ("3", or the "-1" append sentinel) as the index it
+          // plainly denotes rather than rejecting a schema-conformant value.
+          // -1 appends; anything below -1 is out of contract.
+          const parsedPosition = parseInt(position, 10);
+          if (parsedPosition < -1) {
+            throw new Error('position must be an integer >= -1, "start", or "end"');
+          }
+          requestBody.position = parsedPosition;
         } else {
           throw new Error('position must be an integer, "start", or "end"');
         }
@@ -232,12 +238,7 @@ export async function handleMutateTool(
 
   const result: MutationResponse = await client.mutateBlockTree(postId, requestBody);
 
-  if (result.warnings && result.warnings.length > 0) {
-    const formattedWarnings = result.warnings.map((warning) => {
-      if (isStaticBlockWarning(warning)) return formatStaticBlockWarning(warning);
-      return formatPreferenceWarning(warning);
-    });
-    return { ...result, formatted_warnings: formattedWarnings };
-  }
-  return result;
+  return withFormattedWarnings(result, (warning) =>
+    isStaticBlockWarning(warning) ? formatStaticBlockWarning(warning) : formatPreferenceWarning(warning)
+  );
 }

package/src/tools/patterns.ts

@@ -7,6 +7,7 @@
  */
 
 import type { WordPressBlockClient } from '../client.js';
+import { coercePostId } from '../coerce.js';
 
 /**
  * Tool definitions for the pattern category.
@@ -61,13 +62,13 @@ export async function handlePatternTool(
 ): Promise<unknown> {
   switch (toolName) {
     case 'insert_pattern': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'insert_pattern');
       const patternId = args.pattern_id as number | string;
       const after = args.after_top_level as number | undefined;
       const before = args.before_top_level as number | undefined;
       const synced = args.synced as boolean | undefined;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       if (patternId === undefined || patternId === null) throw new Error('pattern_id is required');
 
       const result = await client.insertPattern(postId, {

package/src/tools/posts.ts

@@ -12,6 +12,7 @@
 import type { WordPressBlockClient } from '../client.js';
 import type { CreatePostRequest, UpdatePostRequest } from '../types.js';
 import { BLOCK_INPUT_SCHEMA } from './write.js';
+import { coercePostId } from '../coerce.js';
 
 const POST_STATUS_CREATE = ['draft', 'pending', 'private', 'publish', 'future'] as const;
 const POST_STATUS_UPDATE = ['draft', 'pending', 'private', 'publish', 'future', 'trash'] as const;
@@ -128,15 +129,17 @@ export async function handlePostTool(
     }
 
     case 'update_post': {
-      if (typeof args.post_id !== 'number') {
-        throw new Error('update_post: "post_id" (number) is required');
+      const postId = coercePostId(args.post_id, 'update_post');
+      if (postId === undefined) {
+        throw new Error('update_post: "post_id" is required');
       }
-      const { post_id: postId, ...rest } = args;
+      const { post_id: _omit, ...rest } = args;
+      void _omit;
       if (Object.keys(rest).length === 0) {
         throw new Error('update_post: provide at least one mutating field besides post_id');
       }
       const update = narrowUpdatePost(rest);
-      return client.updatePost(postId as number, update);
+      return client.updatePost(postId, update);
     }
 
     default:
@@ -144,13 +147,14 @@ export async function handlePostTool(
   }
 }
 
-function narrowCreatePost(input: Record<string, unknown>): CreatePostRequest {
-  // input.title is already validated as a non-empty string by the caller.
-  const out: CreatePostRequest = { title: input.title as string };
-  if (typeof input.post_type === 'string') out.post_type = input.post_type;
-  if (typeof input.status === 'string') out.status = input.status as CreatePostRequest['status'];
-  if (typeof input.content === 'string') out.content = input.content;
-  if (Array.isArray(input.blocks)) out.blocks = input.blocks as CreatePostRequest['blocks'];
+/** Fields narrowed identically for create_post and update_post (everything except title/status/content/blocks/post_type — those differ in requiredness or are create-only). */
+type CommonPostFields = Pick<
+  UpdatePostRequest,
+  'slug' | 'parent' | 'excerpt' | 'featured_media' | 'categories' | 'tags' | 'terms' | 'date' | 'menu_order' | 'comment_status' | 'ping_status' | 'author'
+>;
+
+function narrowCommonPostFields(input: Record<string, unknown>): CommonPostFields {
+  const out: CommonPostFields = {};
   if (typeof input.slug === 'string') out.slug = input.slug;
   if (typeof input.parent === 'number') out.parent = input.parent;
   if (typeof input.excerpt === 'string') out.excerpt = input.excerpt;
@@ -168,24 +172,20 @@ function narrowCreatePost(input: Record<string, unknown>): CreatePostRequest {
   return out;
 }
 
+function narrowCreatePost(input: Record<string, unknown>): CreatePostRequest {
+  // input.title is already validated as a non-empty string by the caller.
+  const out: CreatePostRequest = { title: input.title as string, ...narrowCommonPostFields(input) };
+  if (typeof input.post_type === 'string') out.post_type = input.post_type;
+  if (typeof input.status === 'string') out.status = input.status as CreatePostRequest['status'];
+  if (typeof input.content === 'string') out.content = input.content;
+  if (Array.isArray(input.blocks)) out.blocks = input.blocks as CreatePostRequest['blocks'];
+  return out;
+}
+
 function narrowUpdatePost(input: Record<string, unknown>): UpdatePostRequest {
-  const out: UpdatePostRequest = {};
+  const out: UpdatePostRequest = narrowCommonPostFields(input);
   if (typeof input.title === 'string') out.title = input.title;
   if (typeof input.status === 'string') out.status = input.status as UpdatePostRequest['status'];
-  if (typeof input.slug === 'string') out.slug = input.slug;
-  if (typeof input.parent === 'number') out.parent = input.parent;
-  if (typeof input.excerpt === 'string') out.excerpt = input.excerpt;
-  if (typeof input.featured_media === 'number') out.featured_media = input.featured_media;
-  if (Array.isArray(input.categories)) out.categories = (input.categories as unknown[]).filter((n) => typeof n === 'number') as number[];
-  if (Array.isArray(input.tags)) out.tags = (input.tags as unknown[]).filter((n) => typeof n === 'number') as number[];
-  if (input.terms && typeof input.terms === 'object' && !Array.isArray(input.terms)) {
-    out.terms = narrowTermsMap(input.terms as Record<string, unknown>);
-  }
-  if (typeof input.date === 'string') out.date = input.date;
-  if (typeof input.menu_order === 'number') out.menu_order = input.menu_order;
-  if (input.comment_status === 'open' || input.comment_status === 'closed') out.comment_status = input.comment_status;
-  if (input.ping_status === 'open' || input.ping_status === 'closed') out.ping_status = input.ping_status;
-  if (typeof input.author === 'number') out.author = input.author;
   return out;
 }
 

package/src/tools/read.ts

@@ -8,6 +8,7 @@
 
 import type { WordPressBlockClient } from '../client.js';
 import { enrichBlockList } from '../preferences.js';
+import { coercePostId } from '../coerce.js';
 
 /**
  * Tool definitions for the read category.
@@ -71,6 +72,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.",
+        },
       },
     },
   },
@@ -129,7 +138,7 @@ export async function handleReadTool(
 ): Promise<unknown> {
   switch (toolName) {
     case 'get_page_blocks': {
-      let postId = args.post_id as number | undefined;
+      let postId = coercePostId(args.post_id, 'get_page_blocks');
       const url = args.url as string | undefined;
       const fields = args.fields as string | undefined;
       const render = args.render as boolean | undefined;
@@ -139,12 +148,14 @@ 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) {
+      if (postId === undefined && !url) {
         throw new Error('Either post_id or url is required');
       }
 
-      if (postId === undefined || postId === null) {
+      if (postId === undefined) {
         const resolved = await client.resolveUrl(url as string);
         postId = resolved.post_id;
       }
@@ -154,6 +165,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,24 +179,28 @@ 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 } : {}),
       };
     }
 
     case 'get_block': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'get_block');
       const ref = typeof args.ref === 'string' && args.ref.length > 0 ? (args.ref as string) : undefined;
       const flatIndex =
-        typeof args.flat_index === 'number' && Number.isFinite(args.flat_index)
+        typeof args.flat_index === 'number' && Number.isInteger(args.flat_index) && args.flat_index >= 0
           ? (args.flat_index as number)
           : undefined;
 
-      if (postId === undefined || postId === null) {
+      if (postId === undefined) {
         throw new Error('post_id is required');
       }
       const hasRef = ref !== undefined;