@gravitykit/block-mcp 2.0.0-beta

package/src/tools/posts.ts

@@ -0,0 +1,200 @@
+/**
+ * Post lifecycle tools.
+ *
+ * - `create_post`: create a new post or page (draft, publish, etc.) optionally
+ *    with structured blocks or raw content.
+ * - `update_post`: partial update of metadata, status, or terms. Status `trash`
+ *    trashes the post; any non-trash status untrashes a trashed post.
+ *
+ * Block content edits stay on the per-block tools.
+ */
+
+import type { WordPressBlockClient } from '../client.js';
+import type { CreatePostRequest, UpdatePostRequest } from '../types.js';
+import { BLOCK_INPUT_SCHEMA } from './write.js';
+
+const POST_STATUS_CREATE = ['draft', 'pending', 'private', 'publish', 'future'] as const;
+const POST_STATUS_UPDATE = ['draft', 'pending', 'private', 'publish', 'future', 'trash'] as const;
+
+export const POST_TOOLS = [
+  {
+    name: 'create_post',
+    description:
+      'Create a new post or page. Returns ID, slug, permalink, and edit link. Provide either `content` (raw HTML or block markup) OR `blocks` (structured), not both. Status defaults to draft. Use update_post for trash transitions.',
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, title: 'Create post' },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        title: { type: 'string', description: 'Post title (required, non-empty).' },
+        post_type: { type: 'string', description: 'Post type slug (default: post).' },
+        status: {
+          type: 'string',
+          enum: [...POST_STATUS_CREATE],
+          description: 'Initial status. Use update_post for trash transitions.',
+        },
+        content: {
+          type: 'string',
+          description: 'Raw post_content (HTML or block markup). Mutually exclusive with blocks.',
+        },
+        blocks: {
+          type: 'array',
+          description:
+            'Structured blocks. Validated against block registry and preference tier — legacy blocks are rejected.',
+          items: BLOCK_INPUT_SCHEMA,
+        },
+        slug: { type: 'string' },
+        parent: { type: 'number', description: 'Parent post ID (hierarchical post types only).' },
+        excerpt: { type: 'string' },
+        featured_media: {
+          type: 'number',
+          description: 'Attachment ID. Must be an image MIME. Send 0 to leave unset.',
+        },
+        categories: {
+          type: 'array',
+          items: { type: 'number' },
+          description: 'Term IDs in the `category` taxonomy.',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'number' },
+          description: 'Term IDs in the `post_tag` taxonomy.',
+        },
+        terms: {
+          type: 'object',
+          description: 'Map of taxonomy slug → term IDs. For non-built-in taxonomies on CPTs.',
+        },
+        date: { type: 'string', description: 'ISO 8601 publish date.' },
+        menu_order: { type: 'number' },
+        comment_status: { type: 'string', enum: ['open', 'closed'] },
+        ping_status: { type: 'string', enum: ['open', 'closed'] },
+        author: {
+          type: 'number',
+          description: 'User ID. Other-user authorship requires edit_others_posts cap.',
+        },
+      },
+      required: ['title'],
+    },
+  },
+  {
+    name: 'update_post',
+    description:
+      'Partial update of post metadata, status, or terms. Block content edits stay on the per-block tools. Use status: "trash" to trash; any non-trash status untrashes a trashed post. At least one mutating field besides post_id is required.',
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, title: 'Update post' },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        post_id: { type: 'number', description: 'WordPress post ID.' },
+        title: { type: 'string' },
+        status: { type: 'string', enum: [...POST_STATUS_UPDATE] },
+        slug: { type: 'string' },
+        parent: { type: 'number' },
+        excerpt: { type: 'string' },
+        featured_media: {
+          type: 'number',
+          description: 'Attachment ID. Send 0 to clear.',
+        },
+        categories: { type: 'array', items: { type: 'number' } },
+        tags: { type: 'array', items: { type: 'number' } },
+        terms: { type: 'object' },
+        date: { type: 'string' },
+        menu_order: { type: 'number' },
+        comment_status: { type: 'string', enum: ['open', 'closed'] },
+        ping_status: { type: 'string', enum: ['open', 'closed'] },
+        author: { type: 'number' },
+      },
+      required: ['post_id'],
+    },
+  },
+];
+
+export async function handlePostTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  client: WordPressBlockClient,
+): Promise<unknown> {
+  switch (toolName) {
+    case 'create_post': {
+      if (typeof args.title !== 'string' || args.title.trim() === '') {
+        throw new Error('create_post: a non-empty "title" is required');
+      }
+      if (args.content !== undefined && Array.isArray(args.blocks)) {
+        throw new Error('create_post: "content" and "blocks" are mutually exclusive');
+      }
+      // Narrow incoming args to the documented shape. The MCP SDK already
+      // validates against `inputSchema`, but `terms` (Record<string, number[]>)
+      // and nested block shapes aren't enforced — narrow defensively here.
+      const create = narrowCreatePost(args);
+      return client.createPost(create);
+    }
+
+    case 'update_post': {
+      if (typeof args.post_id !== 'number') {
+        throw new Error('update_post: "post_id" (number) is required');
+      }
+      const { post_id: postId, ...rest } = args;
+      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);
+    }
+
+    default:
+      throw new Error(`Unknown post tool: ${toolName}`);
+  }
+}
+
+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'];
+  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;
+}
+
+function narrowUpdatePost(input: Record<string, unknown>): UpdatePostRequest {
+  const out: UpdatePostRequest = {};
+  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;
+}
+
+function narrowTermsMap(input: Record<string, unknown>): Record<string, number[]> {
+  const out: Record<string, number[]> = {};
+  for (const [taxonomy, ids] of Object.entries(input)) {
+    if (Array.isArray(ids)) {
+      out[taxonomy] = (ids as unknown[]).filter((n) => typeof n === 'number') as number[];
+    }
+  }
+  return out;
+}

package/src/tools/read.ts

@@ -0,0 +1,201 @@
+/**
+ * Read Tools
+ *
+ * MCP tools for reading block content from WordPress pages.
+ * Enriches raw block data with preference annotations so AI agents
+ * immediately see which blocks are legacy and what to use instead.
+ */
+
+import type { WordPressBlockClient } from '../client.js';
+import { enrichBlockList } from '../preferences.js';
+
+/**
+ * Tool definitions for the read category.
+ */
+export const READ_TOOLS = [
+  {
+    name: 'get_page_blocks',
+    description:
+      "Get a post's blocks. Pass post_id OR url (server resolves URL — don't shell out). Returns `{post_id, summary, blocks[], block_count, warnings}`. Each block: `{index (flat), top_level_counter? (top-level only), path, ref (stable gk_ref), name, attributes, innerHTML?, dynamic, storage_mode (\"static\"|\"dynamic\"|\"dual\"), preference? (when non-preferred)}`. Refs survive sibling shifts — pass them to update_block / delete_block / edit_block_tree to chain mutations without re-fetching. Use outline:true or summary_only:true for cheap inspection.",
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true, title: 'Get post blocks' },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        post_id:     { type: 'number' },
+        summary:     { type: 'object' },
+        blocks:      { type: 'array' },
+        block_count: { type: 'number' },
+        warnings:    { type: 'array' },
+      },
+    },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        post_id: {
+          type: 'number',
+          description: 'Post ID. Provide either this or url.',
+        },
+        url: {
+          type: 'string',
+          description: 'Full URL (https://site.com/path/) or site-relative path (/path/). Resolved via url_to_postid. Provide either this or post_id.',
+        },
+        fields: {
+          type: 'string',
+          description: 'Comma-separated fields (e.g. "path,name,text_preview"). Omit for all.',
+        },
+        render: {
+          type: 'boolean',
+          description: 'Expand shortcodes, resolve synced patterns, mark dynamic/static.',
+        },
+        search: {
+          type: 'string',
+          description: 'Filter by text in innerHTML. Returns flat matches.',
+        },
+        block_name: {
+          type: 'string',
+          description: 'Filter by block name (e.g. "core/button"). Returns flat matches.',
+        },
+        outline: {
+          type: 'boolean',
+          description: 'Return only headings and named sections as a flat outline. Fast page structure view.',
+        },
+        summary_only: {
+          type: 'boolean',
+          description: 'Return only the summary object (no blocks). Fastest page inspection.',
+        },
+        include_legacy_paths: {
+          type: 'boolean',
+          description: 'Add summary.legacy_blocks.paths (per-block path list). Off by default; turn on for migration audits.',
+        },
+        persist_refs: {
+          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.',
+        },
+      },
+    },
+  },
+  {
+    name: 'get_block',
+    description:
+      'Fetch one block by stable ref OR flat_index — returns the canonical `saved` snapshot (inner_html + attributes) from the database. Same shape that update_block / update_blocks (with `verbose:true`) echo back, so verification reads use the identical contract as the writes that produced them. Lighter than get_page_blocks when you only need to confirm one known block. For dynamic blocks (`saved.is_dynamic`), `inner_html` is the stored template, not rendered output.',
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true, title: 'Get one block' },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        success: { type: 'boolean' },
+        saved: {
+          type: 'object',
+          properties: {
+            flat_index: { type: 'number' },
+            block_name: { type: 'string' },
+            attributes: { type: 'object' },
+            inner_html: { type: 'string' },
+            is_dynamic: { type: 'boolean' },
+            ref:        { type: 'string' },
+          },
+        },
+      },
+    },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        post_id: { type: 'number', description: 'Post ID.' },
+        ref: {
+          type: 'string',
+          description: 'Stable gk_ref. Provide this OR flat_index.',
+        },
+        flat_index: {
+          type: 'number',
+          description: 'Flat block index. Provide this OR ref.',
+        },
+      },
+      required: ['post_id'],
+    },
+  },
+];
+
+/**
+ * Handle a read 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 handleReadTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  client: WordPressBlockClient
+): Promise<unknown> {
+  switch (toolName) {
+    case 'get_page_blocks': {
+      let postId = args.post_id as number | undefined;
+      const url = args.url as string | undefined;
+      const fields = args.fields as string | undefined;
+      const render = args.render as boolean | undefined;
+      const search = args.search as string | undefined;
+      const blockName = args.block_name as string | undefined;
+      const outline = args.outline as boolean | undefined;
+      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;
+
+      if ((postId === undefined || postId === null) && !url) {
+        throw new Error('Either post_id or url is required');
+      }
+
+      if (postId === undefined || postId === null) {
+        const resolved = await client.resolveUrl(url as string);
+        postId = resolved.post_id;
+      }
+
+      const response = await client.getPageBlocks(postId, {
+        fields, render, search, block_name: blockName, outline,
+        summary_only: summaryOnly,
+        include_legacy_paths: includeLegacyPaths,
+        ...(persistRefs !== undefined ? { persist_refs: persistRefs } : {}),
+      });
+
+      // summary_only mode: return server summary as-is.
+      if (summaryOnly) {
+        return {
+          post_id: postId,
+          summary: (response as { summary?: unknown }).summary,
+        };
+      }
+
+      const enriched = enrichBlockList(response.blocks || []);
+
+      return {
+        post_id: postId,
+        summary: (response as { summary?: unknown }).summary,
+        blocks: enriched.blocks,
+        block_count: enriched.blocks.length,
+        warnings: enriched.warnings,
+      };
+    }
+
+    case 'get_block': {
+      const postId = args.post_id as number;
+      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)
+          ? (args.flat_index as number)
+          : undefined;
+
+      if (postId === undefined || postId === null) {
+        throw new Error('post_id is required');
+      }
+      const hasRef = ref !== undefined;
+      const hasIdx = flatIndex !== undefined;
+      if (hasRef === hasIdx) {
+        throw new Error('Provide exactly one of ref or flat_index');
+      }
+
+      return await client.getBlock(postId, hasRef ? { ref } : { flatIndex });
+    }
+
+    default:
+      throw new Error(`Unknown read tool: ${toolName}`);
+  }
+}

package/src/tools/terms.ts

@@ -0,0 +1,44 @@
+/**
+ * Term tools — taxonomy term discovery (read-only).
+ */
+
+import type { WordPressBlockClient } from '../client.js';
+import type { ListTermsRequest } from '../types.js';
+
+export const TERM_TOOLS = [
+  {
+    name: 'list_terms',
+    description:
+      'List terms in a taxonomy (default: category). Useful for discovering category and tag IDs to pass to create_post or update_post.',
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true, title: 'List terms' },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        taxonomy: { type: 'string', description: 'Taxonomy slug. Default: category.' },
+        search: { type: 'string', description: 'LIKE match against term name.' },
+        parent: { type: 'number' },
+        hide_empty: { type: 'boolean', description: 'Default: false.' },
+        per_page: { type: 'number', description: 'Default 100, max 200.' },
+        page: { type: 'number', description: '1-indexed.' },
+        orderby: { type: 'string', enum: ['name', 'count', 'term_id', 'slug'] },
+        order: { type: 'string', enum: ['asc', 'desc'] },
+        include: { type: 'array', items: { type: 'number' } },
+        slug: { type: 'string' },
+      },
+    },
+  },
+];
+
+export async function handleTermTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  client: WordPressBlockClient,
+): Promise<unknown> {
+  switch (toolName) {
+    case 'list_terms': {
+      return client.listTerms(args as ListTermsRequest);
+    }
+    default:
+      throw new Error(`Unknown term tool: ${toolName}`);
+  }
+}