@gravitykit/block-mcp 2.0.0-beta

package/src/tools/discovery.ts

@@ -0,0 +1,251 @@
+/**
+ * Discovery / Lookup Tools
+ *
+ * Read-only tools for exploring the registry, browsing patterns, scanning
+ * inventory, and addressing posts (URL → ID, search, lookup). Always
+ * `readOnlyHint: true` except `scan_storage_modes` which writes a WP option.
+ */
+
+import type { WordPressBlockClient } from '../client.js';
+import { enrichBlockTypes, enrichPatternList } from '../preferences.js';
+
+const READ_ANNOT = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true } as const;
+
+export const DISCOVERY_TOOLS = [
+  {
+    name: 'list_block_types',
+    description:
+      'Registered block types with per-block `preference` (tier + replacement), `storage_mode` ("static"|"dynamic"|"dual"), `usage` (count + post_count), `attributes` (incl. `source` declarations), and a top-level `guidance` summary grouped by tier. Filters: namespace, category, tier, storage_mode, search (name/title substring), preferred_only, usage_only. Pagination: limit/offset → next_offset. Returns `{block_types[], count, total, offset, next_offset, guidance}`.',
+    annotations: { ...READ_ANNOT, title: 'List block types' },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        block_types: { type: 'array' },
+        count:       { type: 'number' },
+        total:       { type: 'number' },
+        offset:      { type: 'number' },
+        next_offset: { type: ['number', 'null'] },
+        guidance:    { type: 'string' },
+      },
+    },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        namespace:      { type: 'string',  description: 'Filter by namespace (e.g. "core", "filter").' },
+        category:       { type: 'string',  description: 'Filter by category (e.g. "text", "media").' },
+        tier:           { type: 'string',  enum: ['preferred', 'acceptable', 'avoid', 'legacy'], description: 'Exact tier match. Use for migration audits.' },
+        storage_mode:   { type: 'string',  enum: ['static', 'dynamic', 'dual'], description: 'Filter by storage mode. "dual" surfaces blocks needing both attrs+innerHTML on update.' },
+        search:         { type: 'string',  description: 'Case-insensitive substring match against name + title.' },
+        preferred_only: { type: 'boolean', description: 'Shorthand for `tier in {preferred,acceptable}` (score ≥ 50).' },
+        usage_only:     { type: 'boolean', description: 'Only blocks with usage.count > 0 on this site.' },
+        limit:          { type: 'number',  description: 'Max results. Default 50.' },
+        offset:         { type: 'number',  description: 'Skip this many. Default 0.' },
+      },
+    },
+  },
+  {
+    name: 'list_patterns',
+    description: 'Block patterns sorted by preference score. Check before building from scratch. Server respects `limit`; `offset` slices client-side. Reference counts are cached for 1 hour — pass `refresh:true` to rebuild.',
+    annotations: { ...READ_ANNOT, title: 'List patterns' },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        search:    { type: 'string',  description: 'Search by name or keyword.' },
+        synced:    { type: 'boolean', description: 'true = synced only, false = registered only, omit = all.' },
+        min_score: { type: 'number',  description: 'Min preference score; 0 excludes legacy.' },
+        limit:     { type: 'number',  description: 'Max results. Default 20.' },
+        offset:    { type: 'number',  description: 'Skip this many results. Default 0.' },
+        refresh:   { type: 'boolean', description: 'Bust the 1-hour reference-count cache before listing.' },
+      },
+    },
+  },
+  {
+    name: 'get_pattern',
+    description: "Single pattern's full block content + metadata. Use after list_patterns.",
+    annotations: { ...READ_ANNOT, title: 'Get pattern' },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        pattern_id: { type: ['number', 'string'], description: 'Numeric post ID (synced) or registered pattern name.' },
+      },
+      required: ['pattern_id'],
+    },
+  },
+  {
+    name: 'get_site_usage',
+    description: 'Site-wide block + pattern inventory: usage counts, namespace totals, pattern reference counts, legacy patterns.',
+    annotations: { ...READ_ANNOT, title: 'Get site usage' },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        refresh: { type: 'boolean', description: 'Bust the 1-hour cache and rebuild.' },
+      },
+    },
+  },
+  {
+    name: 'scan_storage_modes',
+    description:
+      'Walk every published post and persist a `block_name → "static"|"dynamic"|"dual"` map (option `gk_block_api_storage_modes`). Slow on large sites; rate-limited to 1/hr. After this runs, get_page_blocks `storage_mode` annotations and dual-storage write enforcement use the live classification. Returns `{scanned_posts, unique_blocks, classification, dual_count, dynamic_count, static_count}`.',
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true, title: 'Scan storage modes' },
+    inputSchema: { type: 'object' as const, properties: {} },
+  },
+  {
+    name: 'resolve_url',
+    description: 'URL or path → post ID. Accepts full URLs or site-relative paths. Run this before get_page_blocks / update_block / edit_block_tree when you only have a URL.',
+    annotations: { ...READ_ANNOT, title: 'Resolve URL to post' },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        url: { type: 'string', description: 'Full URL or path (e.g. "/some/page/").' },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'list_posts',
+    description: 'Search posts by title/content with pagination. Returns `{posts: [{post_id, title, slug, post_type, post_status, post_url, modified}], total, page, per_page, total_pages}`. Use instead of wp post list / wp-json.',
+    annotations: { ...READ_ANNOT, title: 'List/search posts' },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        search:      { type: 'string', description: 'Free-text across title + content. Omit to list.' },
+        post_type:   { type: 'string', description: 'Single or comma-separated. Default: public types.' },
+        post_status: { type: 'string', description: 'publish | draft | private | any | csv. Default: publish. (`any` is exclusive.)' },
+        per_page:    { type: 'number', description: 'Default 20, max 100.' },
+        page:        { type: 'number', description: 'Default 1.' },
+      },
+    },
+  },
+  {
+    name: 'get_post_info',
+    description: 'Post metadata by post_id, url, or slug+post_type. Returns `{post_id, title, status, post_url, edit_url, modified, created, parent_id, author, mime_type, comment_count}`. Replaces wp eval / get_permalink() shell-outs.',
+    annotations: { ...READ_ANNOT, title: 'Get post info' },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        post_id:   { type: 'number', description: 'One of post_id, url, or slug.' },
+        url:       { type: 'string', description: 'Full URL or path. Resolved via url_to_postid.' },
+        slug:      { type: 'string', description: 'post_name. Combine with post_type for uniqueness.' },
+        post_type: { type: 'string', description: 'Scope a slug lookup. Default: any.' },
+      },
+    },
+  },
+];
+
+export async function handleDiscoveryTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  client: WordPressBlockClient
+): Promise<unknown> {
+  switch (toolName) {
+    case 'list_block_types': {
+      const response = await client.getBlockTypes({
+        namespace:      args.namespace as string | undefined,
+        category:       args.category as string | undefined,
+        preferred_only: args.preferred_only as boolean | undefined,
+        tier:           args.tier as 'preferred' | 'acceptable' | 'avoid' | 'legacy' | undefined,
+        storage_mode:   args.storage_mode as 'static' | 'dynamic' | 'dual' | undefined,
+        search:         args.search as string | undefined,
+        usage_only:     args.usage_only as boolean | undefined,
+      });
+      const enriched = enrichBlockTypes(response.block_types);
+      const total  = enriched.block_types.length;
+      const limit  = (args.limit as number | undefined) ?? 50;
+      const offset = (args.offset as number | undefined) ?? 0;
+      const page   = enriched.block_types.slice(offset, offset + limit);
+      return {
+        block_types: page,
+        count: page.length,
+        total,
+        offset,
+        next_offset: offset + page.length < total ? offset + page.length : null,
+        guidance: enriched.guidance,
+      };
+    }
+
+    case 'list_patterns': {
+      const limit  = (args.limit as number | undefined) ?? 20;
+      const offset = (args.offset as number | undefined) ?? 0;
+      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);
+      const total = enriched.patterns.length;
+      const page  = enriched.patterns.slice(offset, offset + limit);
+      return {
+        patterns: page,
+        count: page.length,
+        total,
+        offset,
+        next_offset: offset + page.length < total ? offset + page.length : null,
+        summary: enriched.summary,
+      };
+    }
+
+    case 'get_pattern': {
+      const patternId = args.pattern_id;
+      if (patternId === undefined || patternId === null) throw new Error('pattern_id is required');
+      return await client.getPattern(patternId as number | string);
+    }
+
+    case 'get_site_usage':
+      return await client.getSiteUsage(args.refresh as boolean | undefined);
+
+    case 'scan_storage_modes':
+      return await client.scanStorageModes();
+
+    case 'resolve_url': {
+      const url = args.url;
+      if (typeof url !== 'string' || url.length === 0) throw new Error('url is required');
+      return await client.resolveUrl(url);
+    }
+
+    case 'list_posts':
+      return await client.findPosts({
+        search:      args.search as string | undefined,
+        post_type:   args.post_type as string | undefined,
+        post_status: args.post_status as string | undefined,
+        per_page:    args.per_page as number | undefined,
+        page:        args.page as number | undefined,
+      });
+
+    case 'get_post_info': {
+      const postId = args.post_id;
+      const url    = args.url;
+      const slug   = args.slug;
+      if (
+        (postId === undefined || postId === null) &&
+        (typeof url !== 'string' || url.length === 0) &&
+        (typeof slug !== 'string' || slug.length === 0)
+      ) {
+        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');
+      }
+      return await client.getPostInfo({
+        post_id:   normalizedPostId,
+        url:       typeof url === 'string' ? url : undefined,
+        slug:      typeof slug === 'string' ? slug : undefined,
+        post_type: args.post_type as string | undefined,
+      });
+    }
+
+    default:
+      throw new Error(`Unknown discovery tool: ${toolName}`);
+  }
+}

package/src/tools/media.ts

@@ -0,0 +1,75 @@
+/**
+ * Media tools — upload to the WordPress media library.
+ */
+
+import type { WordPressBlockClient } from '../client.js';
+import type { UploadMediaRequest } from '../types.js';
+
+export const MEDIA_TOOLS = [
+  {
+    name: 'upload_media',
+    description:
+      'Upload an item to the WordPress media library. Provide exactly one of: `path` (local filesystem on the MCP host, sent as multipart), `url` (server-side sideload, 25 MB cap), or `data_base64` (with `filename`). Returns the attachment ID and URL ready for core/image blocks.',
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, title: 'Upload media' },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute path on the MCP host. Will be read and POSTed as multipart.',
+        },
+        url: {
+          type: 'string',
+          description: 'Public URL the WordPress site can fetch.',
+        },
+        data_base64: {
+          type: 'string',
+          description: 'Base64-encoded file contents (requires filename).',
+        },
+        filename: {
+          type: 'string',
+          description: 'Override filename (required when using data_base64).',
+        },
+        title: { type: 'string' },
+        alt_text: {
+          type: 'string',
+          description: 'Saved as _wp_attachment_image_alt meta. Critical for accessibility.',
+        },
+        caption: { type: 'string' },
+        description: { type: 'string' },
+        post_id: {
+          type: 'number',
+          description: 'Attach to a parent post (sets post_parent).',
+        },
+      },
+    },
+  },
+];
+
+export async function handleMediaTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  client: WordPressBlockClient,
+): Promise<unknown> {
+  switch (toolName) {
+    case 'upload_media': {
+      const modes = (['path', 'url', 'data_base64'] as const).filter(
+        (k) => typeof args[k] === 'string' && (args[k] as string).length > 0,
+      );
+      if (modes.length === 0) {
+        throw new Error('upload_media: provide one of "path", "url", or "data_base64"');
+      }
+      if (modes.length > 1) {
+        throw new Error(
+          `upload_media: only one of path/url/data_base64 may be supplied (got ${modes.join(', ')})`,
+        );
+      }
+      if (args.data_base64 && !args.filename) {
+        throw new Error('upload_media: "filename" is required when using data_base64');
+      }
+      return client.uploadMedia(args as UploadMediaRequest);
+    }
+    default:
+      throw new Error(`Unknown media tool: ${toolName}`);
+  }
+}

package/src/tools/mutate.ts

@@ -0,0 +1,243 @@
+/**
+ * Edit Block Tree — path-based structural mutation engine.
+ *
+ * Single tool exposing 9 ops (update-attrs, update-html, replace-block,
+ * remove-block, wrap-in-group, unwrap-group, insert-child, duplicate,
+ * move). Path is an integer array from get_page_blocks (e.g. [0,2,1] =
+ * top-level block 0 → innerBlock 2 → innerBlock 1). Creates a revision.
+ *
+ * Renamed from `mutate_block_tree` in 1.4.0 (verb-noun consistency).
+ */
+
+import type { WordPressBlockClient } from '../client.js';
+import type { MutationOp, MutationRequest, MutationResponse, StaticBlockWarning } from '../types.js';
+import { formatPreferenceWarning } from '../preferences.js';
+
+const OPS: readonly MutationOp[] = [
+  'update-attrs',
+  'update-html',
+  'replace-block',
+  'remove-block',
+  'wrap-in-group',
+  'unwrap-group',
+  'insert-child',
+  'duplicate',
+  'move',
+] as const;
+
+export const MUTATE_TOOLS = [{
+  name: 'edit_block_tree',
+  description:
+    'Run one structural op on a nested block tree. Ops: update-attrs, update-html, replace-block, remove-block, wrap-in-group, unwrap-group, insert-child, duplicate, move. Target the block via `ref` (stable gk_ref — recommended, survives sibling shifts) OR `path` (integer array, e.g. [0,2,1]). For move, the destination can be a `destination_ref` instead of a path. Creates a revision.',
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, title: 'Edit block tree' },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      success:            { type: 'boolean' },
+      op:                 { type: 'string' },
+      path:               { type: 'array', items: { type: 'integer' } },
+      block:              {
+        type: 'object',
+        properties: {
+          name:       { type: 'string' },
+          attributes: { type: 'object' },
+          ref:        { type: 'string', description: 'New ref when the op produced a new block.' },
+          new_path:   { type: 'array', items: { type: 'integer' }, description: 'duplicate: path of the clone.' },
+        },
+      },
+      warnings:           { type: 'array' },
+      formatted_warnings: { type: 'array', items: { type: 'string' } },
+      before_revision_id: { type: 'number' },
+      revision_id:        { type: 'number' },
+    },
+  },
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      post_id:     { type: 'number',  description: 'Post ID.' },
+      op:          { type: 'string',  enum: [...OPS], description: 'Operation to perform.' },
+      path:        { type: 'array',   items: { type: 'integer' }, description: 'Target block path (e.g. [0,2,1]). Provide this OR `ref`.' },
+      ref:         { type: 'string',  description: 'Stable gk_ref of the target block. Survives sibling shifts. Provide this OR `path`.' },
+      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' },
+        },
+      },
+      wrapper: {
+        type: 'object',
+        description: 'wrap-in-group: optional wrapper block. Default core/group.',
+        properties: {
+          name:       { type: 'string', description: 'Wrapper name. Default "core/group".' },
+          attributes: { type: 'object' },
+        },
+      },
+      position:        { type: ['integer', 'string'], description: 'insert-child: index, "start", or "end" (default).' },
+      destination:     { type: 'array', items: { type: 'integer' }, description: 'move: destination path (pre-move indexing).' },
+      destination_ref: { type: 'string', description: 'move: destination block ref (alternative to destination).' },
+      count:           { type: 'integer', description: 'move: consecutive blocks to move. Default 1.' },
+    },
+    required: ['post_id', 'op'],
+  },
+}];
+
+function isIntegerArray(value: unknown, fieldName: string): value is number[] {
+  if (!Array.isArray(value)) {
+    throw new Error(`${fieldName} must be an array of integers`);
+  }
+  for (const item of value) {
+    if (typeof item !== 'number' || !Number.isInteger(item)) {
+      throw new Error(`${fieldName} must contain only integers, got: ${JSON.stringify(item)}`);
+    }
+  }
+  return true;
+}
+
+function isStaticBlockWarning(warning: unknown): warning is StaticBlockWarning {
+  return (
+    typeof warning === 'object' &&
+    warning !== null &&
+    (warning as Record<string, unknown>).type === 'static_markup_stale_risk'
+  );
+}
+
+function formatStaticBlockWarning(warning: StaticBlockWarning): string {
+  return `WARNING: Changing ${warning.changed_attrs.join(', ')} on static block ${warning.block_name} without updating innerHTML may leave markup stale.`;
+}
+
+export async function handleMutateTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  client: WordPressBlockClient
+): Promise<unknown> {
+  if (toolName !== 'edit_block_tree') {
+    throw new Error(`Unknown mutate tool: ${toolName}`);
+  }
+
+  const postId = args.post_id as number;
+  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');
+  // 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)) {
+    throw new Error(`op must be one of: ${OPS.join(', ')}. Got: ${JSON.stringify(op)}`);
+  }
+
+  const pathProvided = path !== undefined && path !== null;
+  const hasRef = typeof ref === 'string' && ref.length > 0;
+
+  if (pathProvided && hasRef) {
+    throw new Error('Provide "path" OR "ref", not both');
+  }
+  if (!pathProvided && !hasRef) {
+    throw new Error('Provide either "path" or "ref" to identify the target block');
+  }
+  if (pathProvided) {
+    // Validate shape — must be an integer array.
+    isIntegerArray(path, 'path');
+    if ((path as number[]).length === 0) {
+      throw new Error('path must not be empty');
+    }
+  }
+
+  const requestBody: MutationRequest = {
+    op: op as MutationOp,
+  };
+  if (pathProvided) {
+    requestBody.path = path as number[];
+  } else {
+    requestBody.ref = ref as string;
+  }
+
+  switch (op) {
+    case 'update-attrs': {
+      const attributes = args.attributes as Record<string, unknown> | undefined;
+      if (!attributes || typeof attributes !== 'object') throw new Error('update-attrs requires an "attributes" object');
+      requestBody.attributes = attributes;
+      break;
+    }
+    case 'update-html': {
+      const innerHTML = args.innerHTML as string | undefined;
+      if (innerHTML === undefined || innerHTML === null) throw new Error('update-html requires an "innerHTML" string');
+      requestBody.innerHTML = innerHTML;
+      break;
+    }
+    case 'replace-block':
+    case 'insert-child': {
+      const block = args.block as { name?: string } | undefined;
+      if (!block || typeof block !== 'object' || !block.name) {
+        throw new Error(`${op} requires a "block" object with a "name" property`);
+      }
+      requestBody.block = block as MutationRequest['block'];
+      if (op === 'insert-child' && args.position !== undefined) {
+        const position = args.position;
+        if (typeof position === 'number' && Number.isInteger(position)) {
+          requestBody.position = position;
+        } else if (position === 'start' || position === 'end') {
+          requestBody.position = position;
+        } else {
+          throw new Error('position must be an integer, "start", or "end"');
+        }
+      }
+      break;
+    }
+    case 'wrap-in-group': {
+      if (args.wrapper !== undefined) requestBody.wrapper = args.wrapper as MutationRequest['wrapper'];
+      break;
+    }
+    case 'remove-block':
+    case 'unwrap-group':
+    case 'duplicate':
+      break;
+    case 'move': {
+      const destination = args.destination;
+      const destRef = args.destination_ref as string | undefined;
+
+      const hasDestination = destination !== undefined && destination !== null;
+      const hasDestRef     = typeof destRef === 'string' && destRef.length > 0;
+
+      // XOR: a path and a ref for the same anchor is ambiguous — silently
+      // preferring one would make a stale path silently invalidate a fresh ref.
+      if (hasDestination && hasDestRef) {
+        throw new Error('move: provide "destination" path OR "destination_ref", not both');
+      }
+
+      if (hasDestination) {
+        isIntegerArray(destination, 'destination');
+        requestBody.destination = destination as number[];
+      } else if (hasDestRef) {
+        requestBody.destination_ref = destRef as string;
+      } else {
+        throw new Error('move requires "destination" path or "destination_ref"');
+      }
+      if (args.count !== undefined && args.count !== null) {
+        const count = args.count as number;
+        if (typeof count !== 'number' || !Number.isInteger(count) || count < 1) {
+          throw new Error('count must be a positive integer');
+        }
+        requestBody.count = count;
+      }
+      break;
+    }
+  }
+
+  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;
+}

package/src/tools/patterns.ts

@@ -0,0 +1,94 @@
+/**
+ * Pattern Tools
+ *
+ * MCP tools for inserting WordPress block patterns into pages.
+ * Supports both synced patterns (core/block references that stay linked)
+ * and inline insertion (independent copy for per-page customization).
+ */
+
+import type { WordPressBlockClient } from '../client.js';
+
+/**
+ * Tool definitions for the pattern category.
+ */
+export const PATTERN_TOOLS = [
+  {
+    name: 'insert_pattern',
+    description:
+      'Insert a pattern. Default synced=true inserts a core/block reference (edits to source update all pages); synced=false inlines blocks for per-page edits. NOTE: registered (non-numeric) patterns cannot be synced — server forces synced=false. Response includes `synced` (actual mode used) so you can detect the override.',
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, title: 'Insert pattern' },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        post_id: {
+          type: 'number',
+          description: 'Post ID.',
+        },
+        pattern_id: {
+          type: ['number', 'string'],
+          description: 'Numeric post ID (synced) or registered pattern name.',
+        },
+        after_top_level: {
+          type: 'number',
+          description: 'top_level_counter to insert AFTER. -1/omit = append. Matches insert_blocks naming.',
+        },
+        before_top_level: {
+          type: 'number',
+          description: 'top_level_counter to insert BEFORE. Matches insert_blocks naming.',
+        },
+        synced: {
+          type: 'boolean',
+          description: 'true (default) = synced reference; false = inline copy.',
+        },
+      },
+      required: ['post_id', 'pattern_id'],
+    },
+  },
+];
+
+/**
+ * Handle a pattern tool call.
+ *
+ * @param toolName - The name of the tool being called
+ * @param args - Tool arguments from the AI agent
+ * @param client - WordPress Block API client instance
+ * @returns Tool result ready for MCP response
+ */
+export async function handlePatternTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  client: WordPressBlockClient
+): Promise<unknown> {
+  switch (toolName) {
+    case 'insert_pattern': {
+      const postId = args.post_id as number;
+      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 (patternId === undefined || patternId === null) throw new Error('pattern_id is required');
+
+      const result = await client.insertPattern(postId, {
+        pattern_id: patternId,
+        after,
+        before,
+        synced: synced ?? true,
+      });
+
+      // Add a hint about sync behavior
+      const syncNote = result.synced
+        ? 'Pattern inserted as synced reference. Changes to the source pattern will update this page.'
+        : 'Pattern blocks inserted inline. This copy is independent and can be edited per-page.';
+
+      return {
+        ...result,
+        note: syncNote,
+      };
+    }
+
+    default:
+      throw new Error(`Unknown pattern tool: ${toolName}`);
+  }
+}