@gravitykit/block-mcp 2.0.0-beta → 2.0.1

package/src/__tests__/tools/read/pagination.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Tool tests: get_page_blocks pagination (limit + cursor).
+ *
+ * The REST route and the client both support `limit`/`cursor` pagination,
+ * but the MCP tool never exposed them — agents had no way to page through a
+ * huge post. These pin the tool-layer contract:
+ *   - limit/cursor are declared on the inputSchema (dispatch validation
+ *     rejects undeclared keys, so omission = unusable);
+ *   - both forward to client.getPageBlocks;
+ *   - the response's `pagination` (incl. next_cursor) passes through so the
+ *     agent can fetch the next page.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { handleReadTool, READ_TOOLS } from '../../../tools/read.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+import { pageBlocksResponse } from '../../fixtures/rest-responses.js';
+
+describe('get_page_blocks — pagination', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+  });
+
+  it('declares limit and cursor on the inputSchema', () => {
+    const tool = READ_TOOLS.find((t) => t.name === 'get_page_blocks');
+    const props = (tool?.inputSchema as { properties?: Record<string, unknown> })?.properties ?? {};
+    expect(props.limit).toBeDefined();
+    expect(props.cursor).toBeDefined();
+  });
+
+  it('forwards limit and cursor to the client', async () => {
+    client.getPageBlocks.mockResolvedValue(pageBlocksResponse);
+    await handleReadTool(
+      'get_page_blocks',
+      { post_id: 42, limit: 2, cursor: 'idx_2' },
+      client as never,
+    );
+    expect(client.getPageBlocks).toHaveBeenCalledWith(
+      42,
+      expect.objectContaining({ limit: 2, cursor: 'idx_2' }),
+    );
+  });
+
+  it('passes the pagination meta (next_cursor) through to the agent', async () => {
+    client.getPageBlocks.mockResolvedValue({
+      ...pageBlocksResponse,
+      pagination: { limit: 2, offset: 0, total: 4, next_cursor: 'idx_2' },
+    });
+    const result = (await handleReadTool(
+      'get_page_blocks',
+      { post_id: 42, limit: 2 },
+      client as never,
+    )) as { pagination?: { next_cursor?: string | null } };
+    expect(result.pagination?.next_cursor).toBe('idx_2');
+  });
+
+  it('omits pagination from the response when not paginating', async () => {
+    client.getPageBlocks.mockResolvedValue(pageBlocksResponse);
+    const result = (await handleReadTool('get_page_blocks', { post_id: 42 }, client as never)) as {
+      pagination?: unknown;
+    };
+    expect(result.pagination).toBeUndefined();
+  });
+});

package/src/__tests__/unit/client/ref-endpoints.test.ts

@@ -191,12 +191,9 @@ describe('Client — mutateBlockTree ref/path body', () => {
     expect(body).not.toHaveProperty('ref');
   });
 
-  it('forwards before_ref in move body', async () => {
-    const client = makeClient();
-    await client.mutateBlockTree(42, { op: 'move', ref: 'blk_source', before_ref: 'blk_anchor' });
-    const req = captured.find((r) => r.method === 'POST' && r.url === '/posts/42/mutate');
-    expect((req!.data as Record<string, unknown>).before_ref).toBe('blk_anchor');
-  });
+  // NOTE: `before_ref`/`before` were removed from MutationRequest — the REST
+  // route only accepts `destination`/`destination_ref`, so forwarding the
+  // aliases pinned a param the server silently dropped.
 
   it('forwards destination_ref in move body', async () => {
     const client = makeClient();

package/src/__tests__/unit/error-translator/translate-wp-error.test.ts

@@ -44,7 +44,7 @@ describe('translateWpError — null contract', () => {
 describe('translateWpError — routing & auth', () => {
   it('rest_no_route mentions the plugin name', () => {
     const msg = translateWpError('rest_no_route', null)!;
-    expect(msg).toMatch(/gk-block-api/);
+    expect(msg).toMatch(/Block MCP/);
     expect(msg).toMatch(/WORDPRESS_URL/);
   });
 

package/src/agent-guide.ts

@@ -0,0 +1,85 @@
+/**
+ * The agent-guide resource content (block-mcp://agent-guide).
+ *
+ * Workflow guidance served to MCP clients as a resource and prompt seed.
+ * Lives in its own module (not index.ts, which boots the server on import)
+ * so the discoverability contract is testable: everything an agent needs to
+ * author content — including container nesting — must be learnable from the
+ * tool surface + this guide, never from reading this repo's source.
+ */
+
+export const AGENT_GUIDE_CONTENT = `# Block MCP — Agent Guide
+
+## URL → post ID resolution
+
+NEVER run curl, wget, or any bash/shell command to hit wp-json or resolve a URL to a post ID.
+The MCP does this for you:
+
+- \`get_page_blocks\` accepts \`url\` as an alternative to \`post_id\`. Pass the full URL or path; the server resolves it via \`url_to_postid\`.
+- For explicit resolution (title, post_type, edit_url before editing), call \`resolve_url\`.
+
+If the user says "change X on https://example.com/some-page/", your first tool call should be \`get_page_blocks({ url: "...", search: "keyword" })\` or \`resolve_url({ url: "..." })\` — not a shell command.
+
+## Moving / reordering blocks
+
+NEVER do a move as separate \`insert_blocks\` + \`delete_block\` calls — if the delete is skipped or fails, the page ends up with an orphaned clone of the original. The atomic primitive is the \`move\` op on \`edit_block_tree\`:
+
+- Target the source with \`ref\` (the \`gk_ref\` from \`get_page_blocks\`) or \`path\`. Prefer \`ref\` — it survives sibling shifts; paths go stale the moment any earlier block is inserted or removed.
+- Express the destination with \`destination_ref\` or \`destination\` (path). For path destinations, use **pre-move** indexing — write the path as if the source were still in place; the server adjusts indices after the removal.
+- Use \`count\` to move N consecutive siblings in a single op.
+- The server rejects moves into the source itself or any of its descendants.
+- The whole \`edit_block_tree\` call is one revision, reversible via \`revert_to_revision\`.
+
+If you must fall back to the flat-index tools, do \`insert_blocks\` + \`delete_block\` in the same turn and re-fetch \`get_page_blocks\` afterward to confirm exactly one copy remains.
+
+## Building container blocks (groups, columns, callouts)
+
+Every block def accepted by \`insert_blocks\`, \`replace_block_range\`, and \`rewrite_post_blocks\` nests recursively via \`innerBlocks\` — build a whole container (and its children) in ONE call instead of inserting pieces and moving them around.
+
+- The container's \`innerHTML\` is its wrapper element only — an empty wrapper; children render inside it. E.g. \`core/group\` → \`<div class="wp-block-group"></div>\`, \`core/list\` → \`<ul class="wp-block-list"></ul>\`.
+- Each entry in \`innerBlocks\` is a full block def and may nest further (columns → column → content).
+- Include any style class in BOTH the \`className\` attribute and the wrapper \`innerHTML\`.
+
+Example — a styled callout (a \`core/group\` wrapping a paragraph):
+
+\`\`\`json
+{
+  "name": "core/group",
+  "attributes": { "className": "is-style-callout-info", "layout": { "type": "constrained" } },
+  "innerHTML": "<div class=\\"wp-block-group is-style-callout-info\\"></div>",
+  "innerBlocks": [
+    { "name": "core/paragraph", "innerHTML": "<p>Tip text here.</p>" }
+  ]
+}
+\`\`\`
+
+Site-specific style conventions (e.g. callout class names) come from this site's instructions addendum — prefer those over inventing classes.
+
+## Verifying writes
+
+Every write echoes the canonical post-save snapshot. Use it. Do not fetch the public page to verify what saved.
+
+- \`update_block\` always returns \`saved.inner_html\` + \`saved.attributes\` — the exact content that just landed in post_content. The write call IS the verification round-trip.
+- \`update_blocks\` returns per-result \`saved\` only when called with \`verbose: true\` (default false to keep batch responses compact). Pass \`verbose: true\` if you need to confirm each item without a re-read.
+- For after-the-fact re-reads of a single known block, use \`get_block({ post_id, ref })\` — returns the same \`saved\` shape, lighter than \`get_page_blocks\`.
+
+For dynamic blocks (\`saved.is_dynamic: true\`, e.g. shortcodes, query loops, latest-posts), \`saved.inner_html\` is the stored template that runs at render time — not the rendered HTML the visitor sees. That's expected; the canonical state is the template.
+
+## Block preferences (site-defined)
+
+Block preference policy is configured per-site in the WordPress admin (the
+gk-block-api Preferences option) and exposed dynamically. There is no
+client-side hardcoded list of "good" vs "bad" namespaces.
+
+How to discover the policy at runtime:
+
+1. \`list_block_types\` returns blocks grouped by tier (PREFERRED / ACCEPTABLE / AVOID / LEGACY) for the current site. Use this when you need the full picture.
+2. \`get_page_blocks\` annotates non-preferred blocks inline with \`preference.tier\` and (when configured) \`preference.suggested_replacement\`. Trust those fields — they reflect the live config.
+3. \`insert_blocks\` rejects legacy-tier blocks with a \`legacy_block\` error that includes the rejected namespace, the suggested replacement, and a pointer back to this resource.
+
+How to behave:
+
+- Prefer the highest-tier blocks for new content. Defer to the server's classification rather than guessing from a namespace prefix.
+- Reuse existing patterns before building from scratch — call \`list_patterns\` first.
+- For patterns that need per-page customization, use \`synced: false\` to inline them.
+- When you encounter legacy blocks on a page during a read, note them but do not replace unless asked.`;

package/src/client.ts

@@ -9,6 +9,21 @@
 import axios, { AxiosInstance, AxiosError, AxiosRequestConfig } from 'axios';
 import { translateWpError } from './error-translator.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 +106,8 @@ import type {
   MutationRequest,
   MutationResponse,
   ResolveUrlResponse,
+  BlockInput,
+  BlockPatch,
   CreatePostRequest,
   UpdatePostRequest,
   PostMutationResponse,
@@ -116,7 +133,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;
+  };
 }
 
 /**
@@ -415,6 +442,10 @@ 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) {
@@ -434,6 +465,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,7 +538,7 @@ 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');
     if (index < 0) throw new Error('Block index must be non-negative');
@@ -532,7 +565,7 @@ 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');
     if (!ref || typeof ref !== 'string') throw new Error('Ref is required');
@@ -629,11 +662,8 @@ 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');
@@ -713,11 +743,8 @@ 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');
@@ -750,11 +777,7 @@ 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');
     if (!blocks || blocks.length === 0) {
@@ -907,19 +930,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;
     }
 

package/src/connect.ts

@@ -27,7 +27,6 @@ import * as cp from 'node:child_process';
 export type ClientTarget =
   | 'claude-code'
   | 'cursor'
-  | 'chatgpt-desktop'
   | 'claude-desktop'
   | 'print';
 
@@ -35,7 +34,6 @@ export type ClientTarget =
 const VALID_CLIENTS: ClientTarget[] = [
   'claude-code',
   'cursor',
-  'chatgpt-desktop',
   'claude-desktop',
   'print',
 ];
@@ -256,7 +254,7 @@ export function buildAuthorizeUrl(params: AuthorizeUrlParams): string {
   const { site, callback, state, client } = params;
   const base = `${site}/wp-admin/options-general.php`;
   const query = new URLSearchParams({
-    page: 'gk-block-api-settings',
+    page: 'gk-block-mcp-settings',
     tab: 'connect',
     gk_authorize: '1',
     callback,
@@ -337,6 +335,50 @@ export function parseExchangeResponse(json: unknown): Credentials {
 /** Default timeout (ms) for the credential-exchange request. */
 export const EXCHANGE_FETCH_TIMEOUT_MS = 15_000;
 
+/**
+ * TLS failure codes meaning the site's certificate chain is not trusted by
+ * Node's bundled CA store. Node ignores the operating system's trust store
+ * (macOS Keychain / Windows certificate store), so a local dev site whose CA
+ * the browser trusts — Laravel Herd/Valet, Local, OrbStack, mkcert — still
+ * fails here unless NODE_EXTRA_CA_CERTS points at that CA's .pem.
+ */
+const TLS_TRUST_ERROR_CODES = new Set([
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'SELF_SIGNED_CERT_IN_CHAIN',
+  'UNABLE_TO_GET_ISSUER_CERT',
+  'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+  'CERT_UNTRUSTED',
+]);
+
+/** Actionable guidance appended when the exchange fails on an untrusted certificate. */
+const CA_TRUST_HINT =
+  "The site's TLS certificate is not trusted by Node.js, which uses its own CA bundle rather than " +
+  "the operating system's trust store. If this is a local development site, re-run with " +
+  'NODE_EXTRA_CA_CERTS=<path to the root CA certificate (.pem) of the tool serving the site> — ' +
+  'Laravel Herd/Valet, Local, OrbStack, and mkcert each keep one in their config directory. ' +
+  'The variable is also copied into the generated MCP config so the server can reach the site too.';
+
+/**
+ * Render a network-level fetch failure as an actionable error message.
+ *
+ * `fetch` reports every network failure as a bare "fetch failed" TypeError and
+ * hides the real reason (TLS, DNS, refused connection) in `cause`. Surface the
+ * cause's code so the failure is diagnosable, and append the CA-trust hint when
+ * the code means Node rejected the site's certificate.
+ */
+function describeExchangeFetchError(url: string, err: unknown): string {
+  const error = err as Error & { cause?: { code?: unknown; message?: unknown } };
+  const causeCode = typeof error.cause?.code === 'string' ? error.cause.code : '';
+  const causeMessage = typeof error.cause?.message === 'string' ? error.cause.message : '';
+  const detail = causeCode || causeMessage;
+  const reason = detail ? `${error.message}: ${detail}` : error.message;
+
+  const isTrustFailure = TLS_TRUST_ERROR_CODES.has(causeCode);
+  const hint = isTrustFailure ? ` ${CA_TRUST_HINT}` : '';
+  return `Exchange failed: could not reach ${url} (${reason}).${hint}`;
+}
+
 /**
  * Exchange a single-use code for the credential set.
  *
@@ -384,7 +426,7 @@ export async function exchangeCode(
           signal: controller.signal,
         });
       } catch (err) {
-        throw new Error(`Exchange failed: could not reach ${url} (${(err as Error).message}).`);
+        throw new Error(describeExchangeFetchError(url, err));
       }
 
       // 2xx (or any non-redirect) → done.
@@ -423,16 +465,31 @@ export async function exchangeCode(
 
 // ── MCP config builders ───────────────────────────────────────────────────────
 
-/** Build the mcpServers entry for @gravitykit/block-mcp. */
-export function buildMcpEntry(creds: Credentials): McpServerEntry {
+/**
+ * Build the mcpServers entry for @gravitykit/block-mcp.
+ *
+ * When NODE_EXTRA_CA_CERTS is set (required to reach a local dev site whose
+ * certificate Node's bundled CA store rejects), it is copied into the entry's
+ * env: the MCP server talks to the same site over the same Node TLS stack, so
+ * it needs the same trust anchor the connector did.
+ */
+export function buildMcpEntry(
+  creds: Credentials,
+  extraCaCerts: string | undefined = process.env.NODE_EXTRA_CA_CERTS
+): McpServerEntry {
+  const env: Record<string, string> = {
+    WORDPRESS_URL: creds.site,
+    WORDPRESS_USER: creds.user,
+    WORDPRESS_APP_PASSWORD: creds.password,
+  };
+  const hasCaCerts = typeof extraCaCerts === 'string' && extraCaCerts.trim() !== '';
+  if (hasCaCerts) {
+    env.NODE_EXTRA_CA_CERTS = extraCaCerts;
+  }
   return {
     command: 'npx',
     args: ['-y', '@gravitykit/block-mcp'],
-    env: {
-      WORDPRESS_URL: creds.site,
-      WORDPRESS_USER: creds.user,
-      WORDPRESS_APP_PASSWORD: creds.password,
-    },
+    env,
   };
 }
 
@@ -507,35 +564,57 @@ export function cursorConfigPath(): string {
  * That residual exposure is inherent to the `claude mcp add` interface; the
  * config it then writes is owned and protected by Claude Code.
  */
-export function claudeCodeAddArgs(creds: Credentials, name: string = 'block-mcp'): string[] {
-  return [
-    'mcp',
-    'add',
-    name,
-    '--scope',
-    'user',
+export function claudeCodeAddArgs(
+  creds: Credentials,
+  name: string = 'block-mcp',
+  extraCaCerts: string | undefined = process.env.NODE_EXTRA_CA_CERTS
+): string[] {
+  const envArgs = [
     '--env',
     `WORDPRESS_URL=${creds.site}`,
     '--env',
     `WORDPRESS_USER=${creds.user}`,
     '--env',
     `WORDPRESS_APP_PASSWORD=${creds.password}`,
-    '--',
-    'npx',
-    '-y',
-    '@gravitykit/block-mcp',
   ];
+  // Same propagation as buildMcpEntry: the server needs the CA bundle that the
+  // connector needed to reach the site.
+  const hasCaCerts = typeof extraCaCerts === 'string' && extraCaCerts.trim() !== '';
+  if (hasCaCerts) {
+    envArgs.push('--env', `NODE_EXTRA_CA_CERTS=${extraCaCerts}`);
+  }
+  return ['mcp', 'add', name, '--scope', 'user', ...envArgs, '--', 'npx', '-y', '@gravitykit/block-mcp'];
 }
 
 // ── Config file writers ───────────────────────────────────────────────────────
 
-/** Read a JSON file, return default if missing or unparseable. */
-function readJsonFile(filePath: string, defaultValue: McpConfig): McpConfig {
+/**
+ * Read a JSON file, returning the default ONLY when the file does not exist.
+ *
+ * A missing config (ENOENT) is the normal first-run case, so fall back to the
+ * default. Any other failure — an unreadable file or, critically, malformed
+ * JSON — is rethrown so the caller surfaces it instead of silently treating a
+ * corrupt config as empty and overwriting it (which would clobber every other
+ * MCP server the user had configured).
+ */
+export function readJsonFile(filePath: string, defaultValue: McpConfig): McpConfig {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return defaultValue;
+    }
+    throw err;
+  }
+
   try {
-    const raw = fs.readFileSync(filePath, 'utf8');
     return JSON.parse(raw) as McpConfig;
-  } catch {
-    return defaultValue;
+  } catch (err) {
+    throw new Error(
+      `Could not parse the existing MCP config at ${filePath}: ${(err as Error).message}. ` +
+        'Fix or remove the file, then re-run connect — refusing to overwrite it.'
+    );
   }
 }
 
@@ -857,14 +936,6 @@ export async function runConnect(
         break;
       }
 
-      case 'chatgpt-desktop': {
-        // ChatGPT Desktop does not have a standardised config path yet.
-        // Print the JSON block so the user can paste it (secret needed here).
-        console.log(`\n✓ Authorized! Paste the following into ChatGPT Desktop's MCP config:\n`);
-        printConfig(creds, true, args.name);
-        break;
-      }
-
       case 'print':
       default:
         printConfig(creds, args.reveal, args.name);

package/src/error-translator.ts

@@ -67,7 +67,7 @@ export function translateWpError(code: string | undefined, data: unknown): strin
   switch (code) {
     // ── Routing / auth ─────────────────────────────────────────────
     case 'rest_no_route':
-      return 'REST route not found at this site. Confirm the gk-block-api plugin is active and the WORDPRESS_URL is correct.';
+      return 'REST route not found at this site. Confirm the Block MCP plugin is active and the WORDPRESS_URL is correct.';
 
     case 'rest_forbidden':
     case 'rest_cannot_edit':

package/src/index.ts

@@ -48,6 +48,8 @@ import { POST_TOOLS, handlePostTool } from './tools/posts.js';
 import { TERM_TOOLS, handleTermTool } from './tools/terms.js';
 import { MEDIA_TOOLS, handleMediaTool } from './tools/media.js';
 import { YOAST_TOOLS, handleYoastTool } from './tools/yoast.js';
+import { validateToolArgs } from './validate-args.js';
+import { AGENT_GUIDE_CONTENT } from './agent-guide.js';
 import { runConnect } from './connect.js';
 
 // Environment variables are passed by the parent process (Claude Code, Hermes, etc.)
@@ -137,58 +139,8 @@ const AGENT_GUIDE_RESOURCE_URI = 'block-mcp://agent-guide';
 // integrations resolving the old URI don't 404.
 const LEGACY_PREFERENCES_RESOURCE_URI = 'block-mcp://block-preferences';
 
-const AGENT_GUIDE_CONTENT = `# Block MCP — Agent Guide
-
-## URL → post ID resolution
-
-NEVER run curl, wget, or any bash/shell command to hit wp-json or resolve a URL to a post ID.
-The MCP does this for you:
-
-- \`get_page_blocks\` accepts \`url\` as an alternative to \`post_id\`. Pass the full URL or path; the server resolves it via \`url_to_postid\`.
-- For explicit resolution (title, post_type, edit_url before editing), call \`resolve_url\`.
-
-If the user says "change X on https://example.com/some-page/", your first tool call should be \`get_page_blocks({ url: "...", search: "keyword" })\` or \`resolve_url({ url: "..." })\` — not a shell command.
-
-## Moving / reordering blocks
-
-NEVER do a move as separate \`insert_blocks\` + \`delete_block\` calls — if the delete is skipped or fails, the page ends up with an orphaned clone of the original. The atomic primitive is the \`move\` op on \`edit_block_tree\`:
-
-- Target the source with \`ref\` (the \`gk_ref\` from \`get_page_blocks\`) or \`path\`. Prefer \`ref\` — it survives sibling shifts; paths go stale the moment any earlier block is inserted or removed.
-- Express the destination with \`destination_ref\` or \`destination\` (path). For path destinations, use **pre-move** indexing — write the path as if the source were still in place; the server adjusts indices after the removal.
-- Use \`count\` to move N consecutive siblings in a single op.
-- The server rejects moves into the source itself or any of its descendants.
-- The whole \`edit_block_tree\` call is one revision, reversible via \`revert_to_revision\`.
-
-If you must fall back to the flat-index tools, do \`insert_blocks\` + \`delete_block\` in the same turn and re-fetch \`get_page_blocks\` afterward to confirm exactly one copy remains.
-
-## Verifying writes
-
-Every write echoes the canonical post-save snapshot. Use it. Do not fetch the public page to verify what saved.
-
-- \`update_block\` always returns \`saved.inner_html\` + \`saved.attributes\` — the exact content that just landed in post_content. The write call IS the verification round-trip.
-- \`update_blocks\` returns per-result \`saved\` only when called with \`verbose: true\` (default false to keep batch responses compact). Pass \`verbose: true\` if you need to confirm each item without a re-read.
-- For after-the-fact re-reads of a single known block, use \`get_block({ post_id, ref })\` — returns the same \`saved\` shape, lighter than \`get_page_blocks\`.
-
-For dynamic blocks (\`saved.is_dynamic: true\`, e.g. shortcodes, query loops, latest-posts), \`saved.inner_html\` is the stored template that runs at render time — not the rendered HTML the visitor sees. That's expected; the canonical state is the template.
-
-## Block preferences (site-defined)
-
-Block preference policy is configured per-site in the WordPress admin (the
-gk-block-api Preferences option) and exposed dynamically. There is no
-client-side hardcoded list of "good" vs "bad" namespaces.
-
-How to discover the policy at runtime:
-
-1. \`list_block_types\` returns blocks grouped by tier (PREFERRED / ACCEPTABLE / AVOID / LEGACY) for the current site. Use this when you need the full picture.
-2. \`get_page_blocks\` annotates non-preferred blocks inline with \`preference.tier\` and (when configured) \`preference.suggested_replacement\`. Trust those fields — they reflect the live config.
-3. \`insert_blocks\` rejects legacy-tier blocks with a \`legacy_block\` error that includes the rejected namespace, the suggested replacement, and a pointer back to this resource.
-
-How to behave:
-
-- Prefer the highest-tier blocks for new content. Defer to the server's classification rather than guessing from a namespace prefix.
-- Reuse existing patterns before building from scratch — call \`list_patterns\` first.
-- For patterns that need per-page customization, use \`synced: false\` to inline them.
-- When you encounter legacy blocks on a page during a read, note them but do not replace unless asked.`;
+// AGENT_GUIDE_CONTENT lives in src/agent-guide.ts so the discoverability
+// contract is testable (index.ts boots the server on import).
 
 // ============================================
 // Handler registration
@@ -219,6 +171,16 @@ server.server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (!handle) {
       throw new Error(`Unknown tool: ${name}`);
     }
+
+    // Reject unknown / misnamed arguments before the handler runs. The MCP SDK
+    // does not validate against inputSchema, so without this an unrecognized key
+    // (e.g. `after` instead of `after_top_level`) is silently dropped and the
+    // tool runs with defaults — a silent wrong-place write rather than an error.
+    const def = ALL_TOOLS.find((t) => t.name === name) as
+      | { inputSchema?: { properties?: Record<string, unknown>; required?: string[]; additionalProperties?: unknown } }
+      | undefined;
+    validateToolArgs(name, def?.inputSchema, toolArgs);
+
     const result = await handle(name, toolArgs, client);
 
     // Emit `structuredContent` alongside the text fallback when the tool