@gravitykit/block-mcp 2.0.0-beta → 2.1.0

package/src/client.ts

@@ -8,6 +8,23 @@
 
 import axios, { AxiosInstance, AxiosError, AxiosRequestConfig } from 'axios';
 import { translateWpError } from './error-translator.js';
+import { restRouteUrl } from './rest-url.js';
+import { coercePostId } from './coerce.js';
+
+/** Best-effort MIME type from a filename extension, for multipart uploads. */
+function mimeForFilename(filename: string): string {
+  const ext = filename.toLowerCase().split('.').pop() ?? '';
+  const map: Record<string, string> = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    pdf: 'application/pdf',
+  };
+  return map[ext] ?? 'application/octet-stream';
+}
 
 /** Max retry attempts for transient server / network errors. */
 const MAX_RETRIES = 2;
@@ -91,6 +108,8 @@ import type {
   MutationRequest,
   MutationResponse,
   ResolveUrlResponse,
+  BlockInput,
+  BlockPatch,
   CreatePostRequest,
   UpdatePostRequest,
   PostMutationResponse,
@@ -116,7 +135,17 @@ interface PatternsResponse {
 
 /** Response wrapper for page blocks. */
 interface PageBlocksResponse {
+  post_id?: number;
+  summary?: Record<string, unknown>;
   blocks: Block[];
+  /** Present when `limit` pagination is in play. */
+  pagination?: {
+    limit?: number;
+    offset?: number;
+    total?: number;
+    /** Pass back as `cursor` to fetch the next page; null on the last page. */
+    next_cursor?: string | null;
+  };
 }
 
 /**
@@ -154,8 +183,9 @@ export class WordPressBlockClient {
       `${auth.username}:${auth.application_password}`
     ).toString('base64');
 
-    const trimmed = wordpress_url.replace(/\/+$/, '');
-    const baseURL = `${trimmed}/wp-json/gk-block-api/v1`;
+    // Permalink-independent ?rest_route= form so tool calls don't 404 on a
+    // plain-permalink site after the connector completes.
+    const baseURL = restRouteUrl(wordpress_url);
 
     this.client = axios.create({
       baseURL,
@@ -415,11 +445,17 @@ export class WordPressBlockClient {
       include_legacy_paths?: boolean;
       /** When true (default), missing gk_refs are assigned and persisted. Pass false to skip the silent write side effect. */
       persist_refs?: boolean;
+      /** Page size: top-level blocks per response. Pairs with `cursor`. */
+      limit?: number;
+      /** Opaque pagination cursor from a prior response's `next_cursor`. */
+      cursor?: string;
     }
   ): Promise<PageBlocksResponse> {
-    if (postId === undefined || postId === null) {
+    const coercedPostId = coercePostId(postId, 'get_page_blocks');
+    if (coercedPostId === undefined) {
       throw new Error('Post ID is required');
     }
+    postId = coercedPostId;
 
     const queryParams: Record<string, string> = {};
     if (params?.fields) queryParams.fields = params.fields;
@@ -434,6 +470,8 @@ export class WordPressBlockClient {
     // when the param is omitted entirely.
     if (params?.persist_refs === false) queryParams.persist_refs = 'false';
     else if (params?.persist_refs === true) queryParams.persist_refs = 'true';
+    if (typeof params?.limit === 'number') queryParams.limit = String(params.limit);
+    if (params?.cursor) queryParams.cursor = params.cursor;
 
     const response = await this.client.get<PageBlocksResponse>(
       `/posts/${postId}/blocks`,
@@ -505,9 +543,11 @@ export class WordPressBlockClient {
   async updateBlock(
     postId: number,
     index: number,
-    data: { attributes?: Record<string, unknown>; innerHTML?: string }
+    data: BlockPatch
   ): Promise<BlockUpdateResponse> {
-    if (postId === undefined || postId === null) throw new Error('Post ID is required');
+    const coercedPostId = coercePostId(postId, 'update_block');
+    if (coercedPostId === undefined) throw new Error('Post ID is required');
+    postId = coercedPostId;
     if (index < 0) throw new Error('Block index must be non-negative');
     if (!data.attributes && !data.innerHTML) {
       throw new Error('At least one of attributes or innerHTML must be provided');
@@ -532,9 +572,11 @@ export class WordPressBlockClient {
   async updateBlockByRef(
     postId: number,
     ref: string,
-    data: { attributes?: Record<string, unknown>; innerHTML?: string }
+    data: BlockPatch
   ): Promise<BlockUpdateResponse> {
-    if (postId === undefined || postId === null) throw new Error('Post ID is required');
+    const coercedPostId = coercePostId(postId, 'update_block');
+    if (coercedPostId === undefined) throw new Error('Post ID is required');
+    postId = coercedPostId;
     if (!ref || typeof ref !== 'string') throw new Error('Ref is required');
     if (!data.attributes && !data.innerHTML) {
       throw new Error('At least one of attributes or innerHTML must be provided');
@@ -568,7 +610,9 @@ export class WordPressBlockClient {
     updates: BlockBatchUpdateItem[],
     options: { verbose?: boolean } = {}
   ): Promise<BlockBatchUpdateResponse> {
-    if (postId === undefined || postId === null) throw new Error('Post ID is required');
+    const coercedPostId = coercePostId(postId, 'update_blocks');
+    if (coercedPostId === undefined) throw new Error('Post ID is required');
+    postId = coercedPostId;
     if (!Array.isArray(updates) || updates.length === 0) {
       throw new Error('updates must be a non-empty array');
     }
@@ -600,7 +644,9 @@ export class WordPressBlockClient {
     postId: number,
     target: { ref?: string; flatIndex?: number }
   ): Promise<GetBlockResponse> {
-    if (postId === undefined || postId === null) throw new Error('Post ID is required');
+    const coercedPostId = coercePostId(postId, 'get_block');
+    if (coercedPostId === undefined) throw new Error('Post ID is required');
+    postId = coercedPostId;
     const hasRef = typeof target.ref === 'string' && target.ref !== '';
     const hasIdx = typeof target.flatIndex === 'number';
     if (hasRef === hasIdx) {
@@ -629,14 +675,13 @@ export class WordPressBlockClient {
       before?: number;
       after_ref?: string;
       before_ref?: string;
-      blocks: Array<{
-        name: string;
-        attributes?: Record<string, unknown>;
-        innerHTML?: string;
-      }>;
+      // Recursive: containers (groups/columns) nest children via innerBlocks.
+      blocks: BlockInput[];
     }
   ): Promise<BlockWriteResponse> {
-    if (postId === undefined || postId === null) throw new Error('Post ID is required');
+    const coercedPostId = coercePostId(postId, 'insert_blocks');
+    if (coercedPostId === undefined) throw new Error('Post ID is required');
+    postId = coercedPostId;
     if (!data.blocks || data.blocks.length === 0) {
       throw new Error('At least one block is required');
     }
@@ -661,7 +706,9 @@ export class WordPressBlockClient {
     index: number,
     count?: number
   ): Promise<BlockDeleteResponse> {
-    if (postId === undefined || postId === null) throw new Error('Post ID is required');
+    const coercedPostId = coercePostId(postId, 'delete_block');
+    if (coercedPostId === undefined) throw new Error('Post ID is required');
+    postId = coercedPostId;
     if (index < 0) throw new Error('Block index must be non-negative');
 
     const params: Record<string, string> = {};
@@ -686,7 +733,9 @@ export class WordPressBlockClient {
     ref: string,
     count?: number
   ): Promise<BlockDeleteResponse> {
-    if (postId === undefined || postId === null) throw new Error('Post ID is required');
+    const coercedPostId = coercePostId(postId, 'delete_block');
+    if (coercedPostId === undefined) throw new Error('Post ID is required');
+    postId = coercedPostId;
     if (!ref || typeof ref !== 'string') throw new Error('Ref is required');
 
     const params: Record<string, string> = {};
@@ -713,14 +762,13 @@ export class WordPressBlockClient {
     data: {
       start: number;
       count: number;
-      blocks: Array<{
-        name: string;
-        attributes?: Record<string, unknown>;
-        innerHTML?: string;
-      }>;
+      // Recursive: containers (groups/columns) nest children via innerBlocks.
+      blocks: BlockInput[];
     }
   ): Promise<BlockReplaceRangeResponse> {
-    if (postId === undefined || postId === null) throw new Error('Post ID is required');
+    const coercedPostId = coercePostId(postId, 'replace_block_range');
+    if (coercedPostId === undefined) throw new Error('Post ID is required');
+    postId = coercedPostId;
     if (typeof data.start !== 'number' || data.start < 0) {
       throw new Error('start must be a non-negative integer');
     }
@@ -750,13 +798,11 @@ export class WordPressBlockClient {
    */
   async replaceAllBlocks(
     postId: number,
-    blocks: Array<{
-      name: string;
-      attributes?: Record<string, unknown>;
-      innerHTML?: string;
-    }>
+    blocks: BlockInput[]
   ): Promise<BlockWriteResponse> {
-    if (postId === undefined || postId === null) throw new Error('Post ID is required');
+    const coercedPostId = coercePostId(postId, 'rewrite_post_blocks');
+    if (coercedPostId === undefined) throw new Error('Post ID is required');
+    postId = coercedPostId;
     if (!blocks || blocks.length === 0) {
       throw new Error('At least one block is required for a full rewrite');
     }
@@ -780,9 +826,11 @@ export class WordPressBlockClient {
    * @returns Mutation result with revision IDs and optional warnings
    */
   async mutateBlockTree(postId: number, data: MutationRequest): Promise<MutationResponse> {
-    if (postId === undefined || postId === null) {
+    const coercedPostId = coercePostId(postId, 'edit_block_tree');
+    if (coercedPostId === undefined) {
       throw new Error('Post ID is required');
     }
+    postId = coercedPostId;
 
     const response = await this.client.post<MutationResponse>(
       `/posts/${postId}/mutate`,
@@ -803,9 +851,11 @@ export class WordPressBlockClient {
    * @returns Revert result with revision IDs
    */
   async revertToRevision(postId: number, revisionId: number): Promise<unknown> {
-    if (postId === undefined || postId === null) {
+    const coercedPostId = coercePostId(postId, 'revert_to_revision');
+    if (coercedPostId === undefined) {
       throw new Error('Post ID is required');
     }
+    postId = coercedPostId;
     const response = await this.client.post(`/posts/${postId}/revert`, { revision_id: revisionId });
     return response.data;
   }
@@ -830,7 +880,9 @@ export class WordPressBlockClient {
       synced?: boolean;
     }
   ): Promise<PatternInsertResponse> {
-    if (postId === undefined || postId === null) throw new Error('Post ID is required');
+    const coercedPostId = coercePostId(postId, 'insert_pattern');
+    if (coercedPostId === undefined) throw new Error('Post ID is required');
+    postId = coercedPostId;
     if (data.pattern_id === undefined || data.pattern_id === null) throw new Error('Pattern ID is required');
 
     const response = await this.client.post<PatternInsertResponse>(
@@ -869,9 +921,11 @@ export class WordPressBlockClient {
    * Use `status: trash` to trash; any non-trash status untrashes a trashed post.
    */
   async updatePost(postId: number, data: UpdatePostRequest): Promise<PostMutationResponse> {
-    if (postId === undefined || postId === null) {
+    const coercedPostId = coercePostId(postId, 'update_post');
+    if (coercedPostId === undefined) {
       throw new Error('update_post: post_id is required');
     }
+    postId = coercedPostId;
     const response = await this.client.patch<PostMutationResponse>(`/posts/${postId}`, data);
     return response.data;
   }
@@ -907,19 +961,25 @@ export class WordPressBlockClient {
 
     if (args.path) {
       const fs = await import('node:fs/promises');
-      const path = await import('node:path');
+      const nodePath = await import('node:path');
+      const { default: FormData } = await import('form-data');
       const data = await fs.readFile(args.path);
-      const filename = args.filename ?? path.basename(args.path);
+      const filename = args.filename ?? nodePath.basename(args.path);
       const form = new FormData();
-      form.append('file', new Blob([new Uint8Array(data)]), filename);
+      form.append('file', data, { filename, contentType: mimeForFilename(filename) });
       if (args.title) form.append('title', args.title);
       if (args.alt_text) form.append('alt_text', args.alt_text);
       if (args.caption) form.append('caption', args.caption);
       if (args.description) form.append('description', args.description);
       if (typeof args.post_id === 'number') form.append('post_id', String(args.post_id));
 
-      // axios sets the multipart Content-Type and boundary automatically.
-      const response = await this.client.post<UploadMediaResponse>('/media', form);
+      // The shared axios instance defaults Content-Type to application/json,
+      // which makes axios JSON-serialize the form and send NO file. The
+      // form-data package's getHeaders() supplies multipart/form-data WITH the
+      // boundary, overriding that default so this is a real multipart upload.
+      const response = await this.client.post<UploadMediaResponse>('/media', form, {
+        headers: form.getHeaders(),
+      });
       return response.data;
     }
 
@@ -937,18 +997,22 @@ export class WordPressBlockClient {
 
   /** Read all Yoast SEO metadata for a post. */
   async getYoastSEO(postId: number): Promise<YoastSEOMeta> {
-    if (postId === undefined || postId === null) {
+    const coercedPostId = coercePostId(postId, 'yoast_get_seo');
+    if (coercedPostId === undefined) {
       throw new Error('yoast_get_seo: post_id is required');
     }
+    postId = coercedPostId;
     const response = await this.client.get<YoastSEOMeta>(`/yoast/${postId}`);
     return response.data;
   }
 
   /** Partial update of Yoast SEO fields on a single post. */
   async updateYoastSEO(postId: number, fields: YoastUpdateRequest): Promise<YoastSEOMeta> {
-    if (postId === undefined || postId === null) {
+    const coercedPostId = coercePostId(postId, 'yoast_update_seo');
+    if (coercedPostId === undefined) {
       throw new Error('yoast_update_seo: post_id is required');
     }
+    postId = coercedPostId;
     const response = await this.client.patch<YoastSEOMeta>(`/yoast/${postId}`, fields);
     return response.data;
   }

package/src/coerce.ts

@@ -0,0 +1,41 @@
+/**
+ * Input coercion helpers shared across the MCP tool handlers.
+ *
+ * MCP clients and untyped JSON transports vary in how they encode a post ID:
+ * some send the JSON number `123`, others the string `"123"`. The tool surface
+ * must behave identically for both, or the same post is editable through one
+ * tool and rejected by another in the same session.
+ */
+
+/**
+ * Coerce a caller-supplied post ID to a positive integer.
+ *
+ * Accepts a JSON number that is a positive integer, or a string of digits
+ * (`"123"`). Returns `undefined` when the value is absent (`undefined`/`null`),
+ * so callers with an alternate selector (url/slug) can allow that. Throws for a
+ * present-but-invalid value (float, negative, non-numeric string), with the
+ * `label:` prefix the calling tool uses in its other errors.
+ *
+ * @param value - Raw post_id from the tool arguments.
+ * @param label - Tool name used to prefix the thrown error message.
+ * @returns The positive integer, or undefined when the value is absent.
+ */
+export function coercePostId(value: unknown, label: string): number | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0) {
+    return value;
+  }
+  if (typeof value === 'string' && /^[0-9]+$/.test(value)) {
+    const parsed = parseInt(value, 10);
+    // Re-apply the positive check so a zero-valued string ("0", "00") is
+    // rejected exactly like the number 0, not silently accepted as 0.
+    // Number.isSafeInteger rejects values above 2^53-1, which parseInt would
+    // otherwise round to a different id — targeting the wrong post.
+    if (parsed > 0 && Number.isSafeInteger(parsed)) {
+      return parsed;
+    }
+  }
+  throw new Error(`${label}: post_id must be a positive integer`);
+}

package/src/config.ts

@@ -0,0 +1,96 @@
+/**
+ * WordPress connection config resolution for the MCP server.
+ *
+ * Kept side-effect free (no server construction, no process.exit) so the
+ * startup decision is unit-testable and so a missing/invalid config degrades
+ * the server gracefully instead of crashing it — a crash reaches the MCP client
+ * only as an opaque -32000 with the real reason stranded on stderr.
+ */
+
+export interface WordPressConfig {
+  url: string;
+  user: string;
+  password: string;
+}
+
+export type ConfigResult =
+  | { ok: true; config: WordPressConfig }
+  | { ok: false; missing: string[]; message: string };
+
+/**
+ * Read an env var by its primary name, falling back to a legacy alias. An
+ * empty/whitespace-only value counts as absent, not as a valid empty config.
+ */
+function readEnv(env: NodeJS.ProcessEnv, primary: string, legacy: string): string | undefined {
+  const fromPrimary = env[primary];
+  if (fromPrimary && fromPrimary.trim() !== '') {
+    return fromPrimary;
+  }
+  const fromLegacy = env[legacy];
+  if (fromLegacy && fromLegacy.trim() !== '') {
+    console.error(`[block-mcp] DEPRECATED: ${legacy} is deprecated; rename to ${primary} in your MCP client config.`);
+    return fromLegacy;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the WordPress connection config from the process environment.
+ *
+ * Returns `{ ok: false, missing, message }` when any of the three required
+ * values is absent — the caller starts the server in a degraded mode and
+ * surfaces `message` on tool calls, rather than exiting.
+ */
+export function resolveWordPressConfig(env: NodeJS.ProcessEnv): ConfigResult {
+  const url = readEnv(env, 'WORDPRESS_URL', 'GK_SITE_URL');
+  const user = readEnv(env, 'WORDPRESS_USER', 'GK_BLOCK_API_USER');
+  const password = readEnv(env, 'WORDPRESS_APP_PASSWORD', 'GK_BLOCK_API_APP_PASSWORD');
+
+  const missing: string[] = [];
+  if (!url) {
+    missing.push('WORDPRESS_URL');
+  }
+  if (!user) {
+    missing.push('WORDPRESS_USER');
+  }
+  if (!password) {
+    missing.push('WORDPRESS_APP_PASSWORD');
+  }
+
+  if (missing.length > 0) {
+    const message =
+      `Block MCP is not configured: ${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} missing. ` +
+      'Set them in the "env" block of the block-mcp server entry in your MCP client config. ' +
+      'Your site\'s Settings → Block MCP → Connect generates a ready-made config for you.';
+    return { ok: false, missing, message };
+  }
+
+  return { ok: true, config: { url: url as string, user: user as string, password: password as string } };
+}
+
+/**
+ * MCP tool-call result returned for every tool while the server is unconfigured.
+ * The index signature keeps it assignable to the SDK's ServerResult union.
+ */
+export interface NotConfiguredResult {
+  [key: string]: unknown;
+  content: Array<{ type: string; text: string }>;
+  isError: true;
+}
+
+/**
+ * Build the structured tool-call error returned when the server is running but
+ * has no valid WordPress config, so the client shows an actionable reason
+ * instead of an opaque connection failure.
+ */
+export function buildNotConfiguredResult(message: string): NotConfiguredResult {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify({ error: true, code: 'not_configured', message }, null, 2),
+      },
+    ],
+    isError: true,
+  };
+}