@gravitykit/block-mcp 2.0.0-beta → 2.1.0

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.
  *
@@ -366,7 +408,6 @@ export async function exchangeCode(
   fetchFn: typeof fetch = fetch,
   timeoutMs: number = EXCHANGE_FETCH_TIMEOUT_MS
 ): Promise<Credentials> {
-  const origin = new URL(site).origin;
   let url = `${site}/?rest_route=/gk-block-api/v1/connect/exchange`;
 
   const controller = new AbortController();
@@ -384,7 +425,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.
@@ -392,15 +433,30 @@ export async function exchangeCode(
         break;
       }
 
-      // Follow only same-origin redirects, re-POSTing the body.
+      // Follow same-origin redirects, re-POSTing the body. Also follow a
+      // same-host http->https upgrade: a site that forces HTTPS is a security
+      // upgrade to the same site, not an off-site leak, and refusing it bombed
+      // the connector for anyone who passed --site http://. Any other
+      // cross-origin redirect (different host, or an https->http downgrade) is
+      // still refused so the credential is never sent off the target site.
       const location = res.headers.get('location');
       if (!location || hops >= 3) {
         throw new Error(
           `Exchange failed: the site redirected the request (HTTP ${res.status}); ensure --site is the canonical site URL.`
         );
       }
+      const current = new URL(url);
       const next = new URL(location, url);
-      if (next.origin !== origin) {
+      // Only the standard HTTPS port counts as a "force HTTPS" upgrade. A
+      // redirect to https on a non-standard port is not ordinary HSTS behavior,
+      // so the credential must not follow it even when the host matches.
+      const upgradesToStandardHttpsPort = next.port === '' || next.port === '443';
+      const sameHostHttpsUpgrade =
+        current.protocol === 'http:' &&
+        next.protocol === 'https:' &&
+        next.hostname === current.hostname &&
+        upgradesToStandardHttpsPort;
+      if (next.origin !== current.origin && !sameHostHttpsUpgrade) {
         throw new Error(
           `Exchange failed: the site redirected to a different origin (${next.origin}); refusing to send the credential off-site.`
         );
@@ -423,16 +479,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 +578,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 +950,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/enrichers.ts

@@ -180,7 +180,8 @@ export async function shikiHighlight(code: string, language: string, themeName?:
     .replace(/var\(--shiki-foreground\)/g, 'var(--shiki-color-text)')
     .replace(/var\(--shiki-background\)/g, 'var(--shiki-color-background)');
   if (themeName && themeName !== 'css-variables') {
-    html = html.replace(/(<pre[^>]*class="shiki) css-variables(")/, `$1 ${themeName}$2`);
+    // Replacer function so a `$` in themeName is not read as a replacement token.
+    html = html.replace(/(<pre[^>]*class="shiki) css-variables(")/, (_m, p1, p2) => `${p1} ${themeName}${p2}`);
   }
   return html;
 }
@@ -305,9 +306,12 @@ registerBlockEnricher('kevinbatdorf/code-block-pro', async (block) => {
   //     post renders a blank gap where the code should be.
   let updatedInnerHTML: string;
   if (incomingInnerHTML !== '') {
+    // Replacer function, not a string: codeHTML is arbitrary content and a
+    // `$`-sequence in it ($$, $&, $`) would otherwise be interpreted as a
+    // String.replace pattern and corrupt the rendered code.
     updatedInnerHTML = incomingInnerHTML.replace(
       /<pre class="shiki[\s\S]*?<\/pre>/,
-      codeHTML,
+      () => codeHTML,
     );
     updatedInnerHTML = updatedInnerHTML.replace(
       /(<textarea[^>]*>)([\s\S]*?)(<\/textarea>)/,

package/src/error-translator.ts

@@ -18,14 +18,24 @@ interface ErrorContextHints {
   ref?: string;
   /** Block path (e.g. [0, 2, 1]) that was rejected, when applicable. */
   path?: number[];
-  /** Block name involved in a legacy/avoid rejection. */
+  /** Block name involved in a legacy/avoid/dual-storage rejection. */
   block?: string;
-  /** Replacement block name suggested by the preference engine. */
+  /** Suggested replacement block name suggested by the preference engine. */
   suggested_replacement?: string;
   /** Status from the data envelope, sometimes present even on success. */
   status?: number;
   /** Some endpoints return `block_name` instead of `block`. */
   block_name?: string;
+  /** flat_index that was rejected as out of range (invalid_index). */
+  flat_index?: number;
+  /** Revision ID the caller's If-Match expected (stale_revision). */
+  expected_revision?: number;
+  /** Revision ID currently stored (stale_revision). */
+  current_revision?: number;
+  /** Configured max nesting depth (block_depth_exceeded). */
+  max_depth?: number;
+  /** Actual nesting depth that exceeded max_depth (block_depth_exceeded). */
+  actual_depth?: number;
   /** Allow extra fields without typing every one. */
   [key: string]: unknown;
 }
@@ -49,6 +59,11 @@ function extractHints(data: unknown): ErrorContextHints {
   if (typeof d.block_name === 'string')          hints.block_name = d.block_name;
   if (typeof d.suggested_replacement === 'string') hints.suggested_replacement = d.suggested_replacement;
   if (typeof d.status === 'number')              hints.status = d.status;
+  if (typeof d.flat_index === 'number')          hints.flat_index = d.flat_index;
+  if (typeof d.expected_revision === 'number')   hints.expected_revision = d.expected_revision;
+  if (typeof d.current_revision === 'number')    hints.current_revision = d.current_revision;
+  if (typeof d.max_depth === 'number')           hints.max_depth = d.max_depth;
+  if (typeof d.actual_depth === 'number')        hints.actual_depth = d.actual_depth;
 
   return hints;
 }
@@ -67,7 +82,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':
@@ -79,8 +94,11 @@ export function translateWpError(code: string | undefined, data: unknown): strin
       return 'Authentication failed. Confirm WORDPRESS_USER and WORDPRESS_APP_PASSWORD are set to a valid Application Password (not a regular login password).';
 
     // ── Post lookup ────────────────────────────────────────────────
+    // `post_not_found` is the code the plugin actually emits;
+    // `rest_post_invalid_id` is WordPress core's equivalent, kept as an
+    // alias in case a core route ever surfaces it.
     case 'rest_post_invalid_id':
-    case 'invalid_post_id': {
+    case 'post_not_found': {
       const target = hints.post_id !== undefined ? `Post ${hints.post_id}` : 'Post';
       return `${target} not found. List pages with \`list_posts\` to find the right ID.`;
     }
@@ -92,18 +110,23 @@ export function translateWpError(code: string | undefined, data: unknown): strin
         : 'Resource not found. It may have been deleted, or the ID is wrong.';
 
     // ── Block ref / path resolution ────────────────────────────────
-    case 'gk_block_api_invalid_ref':
     case 'invalid_ref':
-      return `Block ref \`${hints.ref ?? '?'}\` not found in post ${hints.post_id ?? '?'}. The post may have been edited since you last fetched it — call \`get_page_blocks\` again to get the current refs.`;
+      return 'Ref must be a non-empty string. Use the `ref` value returned by `get_page_blocks` — not a made-up ID.';
+
+    case 'ref_stale': {
+      const where = hints.post_id !== undefined ? ` in post ${hints.post_id}` : '';
+      return `Block ref \`${hints.ref ?? '?'}\`${where} no longer resolves to a block. It may have been deleted, or the ref is from an older snapshot — call \`get_page_blocks\` again to get current refs.`;
+    }
 
-    case 'path_not_found':
     case 'invalid_path':
-      return `Block path ${formatPath(hints.path)} doesn't address an existing block. Re-fetch the post with \`get_page_blocks\` to get current paths — paths shift when blocks are added or removed.`;
+      return `Block path ${formatPath(hints.path)} doesn't address an existing block (or isn't a valid array of non-negative integers). Re-fetch the post with \`get_page_blocks\` to get current paths — paths shift when blocks are added or removed.`;
 
-    case 'path_out_of_bounds':
-      return `Block path ${formatPath(hints.path)} is out of bounds. The post has fewer blocks than expected — re-fetch with \`get_page_blocks\` for current state.`;
+    case 'invalid_index': {
+      const idx = typeof hints.flat_index === 'number' ? ` ${hints.flat_index}` : '';
+      return `Block index${idx} out of range. Re-fetch the post with \`get_page_blocks\` to get current indices — they shift when blocks are added or removed.`;
+    }
 
-    // ── Block tier / preference enforcement ────────────────────────
+    // ── Block tier / preference / storage enforcement ───────────────
     case 'legacy_block':
       return blockName
         ? `${blockName} is in a namespace this site has configured as legacy. Use ${hints.suggested_replacement ?? 'a core block instead'}.`
@@ -121,12 +144,38 @@ export function translateWpError(code: string | undefined, data: unknown): strin
     case 'static_markup_stale_risk':
       return 'Updating attributes on a static block without new innerHTML may leave its rendered markup stale. Pass `innerHTML` alongside `attributes`, or use a dynamic block.';
 
+    case 'dual_storage_requires_both':
+      return blockName
+        ? `${blockName} is dual-storage: \`attributes\` and \`innerHTML\` carry the same data and must be sent together — sending only one silently desyncs the other. Pass both fields in the same call.`
+        : 'This block is dual-storage: `attributes` and `innerHTML` carry the same data and must be sent together — sending only one silently desyncs the other. Pass both fields in the same call.';
+
+    case 'block_depth_exceeded': {
+      const depth = typeof hints.max_depth === 'number' && typeof hints.actual_depth === 'number'
+        ? ` (max ${hints.max_depth}, got ${hints.actual_depth})`
+        : '';
+      return `Block tree exceeds the maximum nesting depth${depth}. Flatten the structure — split deeply nested groups into separate top-level blocks.`;
+    }
+
+    // ── Concurrency / staleness ──────────────────────────────────────
+    case 'edit_conflict':
+      return 'The post content changed since it was read (a concurrent write raced this one). Re-fetch the page with `get_page_blocks` and retry your edit against the current content.';
+
+    case 'stale_revision': {
+      const rev = typeof hints.current_revision === 'number' ? ` (current revision: ${hints.current_revision})` : '';
+      return `The post has changed since you fetched it${rev}. Re-fetch with \`get_page_blocks\` and retry.`;
+    }
+
     // ── Rate limiting ──────────────────────────────────────────────
     case 'rate_limit_exceeded': {
       const where = hints.post_id !== undefined ? `on post ${hints.post_id} ` : '';
       return `Too many writes ${where}in the last minute. Wait ~60s before retrying, or batch your edits into a single \`edit_block_tree\` call.`;
     }
 
+    case 'rate_limit_locked': {
+      const where = hints.post_id !== undefined ? ` on post ${hints.post_id}` : '';
+      return `Another write${where} is in progress. Retry in a moment; the lock clears within a second. To avoid contention, batch edits into a single \`edit_block_tree\` call.`;
+    }
+
     // ── v1.2 post lifecycle ────────────────────────────────────────
     case 'mixed_trash_payload':
       return '`status: "trash"` cannot be combined with other fields. Trash the post in one call, then update other fields after.';
@@ -137,6 +186,9 @@ export function translateWpError(code: string | undefined, data: unknown): strin
     case 'invalid_status':
       return 'Post status not allowed. Valid values: draft, pending, publish, future, private. To trash, call update_post with status:"trash" (on its own, not combined with other fields).';
 
+    case 'trash_disabled':
+      return 'Moving posts to trash is turned off for this site. A site administrator can enable it under Block MCP → Settings, or use update_post with a different status.';
+
     // ── Media uploads ──────────────────────────────────────────────
     case 'invalid_url':
       return 'URL rejected by SSRF guard. Hostnames pointing at private/loopback/cloud-metadata IPs are blocked. Use a publicly reachable URL.';

package/src/index.ts

@@ -38,6 +38,7 @@ import {
   GetPromptRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { WordPressBlockClient } from './client.js';
+import { resolveWordPressConfig, buildNotConfiguredResult } from './config.js';
 import { getInstructions } from './instructions.js';
 import { DISCOVERY_TOOLS, handleDiscoveryTool } from './tools/discovery.js';
 import { READ_TOOLS, handleReadTool } from './tools/read.js';
@@ -48,6 +49,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.)
@@ -56,21 +59,8 @@ import { runConnect } from './connect.js';
 // ============================================
 // Initialize WordPress client
 // ============================================
-
-// Primary names (recommended): WORDPRESS_URL / WORDPRESS_USER / WORDPRESS_APP_PASSWORD.
-// Fall back to the legacy GK_-prefixed names so existing configs keep working;
-// emit a deprecation notice to stderr when they're used. The legacy names will
-// be removed in a future minor release.
-function readEnv(primary: string, legacy: string): string | undefined {
-  const fromPrimary = process.env[primary];
-  if (fromPrimary) return fromPrimary;
-  const fromLegacy = process.env[legacy];
-  if (fromLegacy) {
-    console.error(`[block-mcp] DEPRECATED: ${legacy} is deprecated; rename to ${primary} in your MCP client config.`);
-    return fromLegacy;
-  }
-  return undefined;
-}
+// Config resolution (WORDPRESS_* with legacy GK_* fallback) lives in
+// ./config.ts so it stays side-effect free and unit-testable.
 
 // ============================================
 // Aggregate all tool definitions
@@ -137,58 +127,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
@@ -200,7 +140,11 @@ How to behave:
 // `_instructions` field — see the construction note above).
 // ============================================
 
-function registerHandlers(server: McpServer, client: WordPressBlockClient): void {
+function registerHandlers(
+  server: McpServer,
+  client: WordPressBlockClient | null,
+  notConfiguredMessage?: string
+): void {
 
 server.server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools: ALL_TOOLS };
@@ -214,11 +158,28 @@ server.server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   const toolArgs = (args ?? {}) as Record<string, unknown>;
 
+  // Degraded mode: the server started without a valid WordPress config, so it
+  // can list tools (the client connects and sees them) but cannot run any —
+  // return a clear reason instead of a crash the client shows as -32000.
+  if (!client) {
+    return buildNotConfiguredResult(notConfiguredMessage ?? 'Block MCP is not configured.');
+  }
+
   try {
     const handle = TOOL_DISPATCH.get(name);
     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
@@ -396,22 +357,31 @@ async function main(): Promise<void> {
   }
 
   // ── env-var validation ──────────────────────────────────────────────────
-  const WORDPRESS_URL = readEnv('WORDPRESS_URL', 'GK_SITE_URL');
-  const WORDPRESS_USER = readEnv('WORDPRESS_USER', 'GK_BLOCK_API_USER');
-  const WORDPRESS_APP_PASSWORD = readEnv('WORDPRESS_APP_PASSWORD', 'GK_BLOCK_API_APP_PASSWORD');
-
-  if (!WORDPRESS_URL || !WORDPRESS_USER || !WORDPRESS_APP_PASSWORD) {
+  const cfg = resolveWordPressConfig(process.env);
+
+  // Start degraded rather than exiting on a missing/invalid config: exiting
+  // kills the stdio session before the handshake, so the MCP client only shows
+  // an opaque -32000. A running server lists its tools and returns cfg.message
+  // (which names the missing vars) on any tool call — a diagnosable error.
+  if (!cfg.ok) {
+    console.error(`Block MCP: ${cfg.message}`);
+    const degraded = new McpServer(
+      { name: 'block-mcp', version: pkg.version },
+      { capabilities: { tools: {}, resources: {}, prompts: {} } }
+    );
+    registerHandlers(degraded, null, cfg.message);
+    await degraded.connect(new StdioServerTransport());
     console.error(
-      'Missing required environment variables: WORDPRESS_URL, WORDPRESS_USER, WORDPRESS_APP_PASSWORD'
+      'Block MCP Server running on stdio (unconfigured — tool calls return a configuration error)'
     );
-    process.exit(1);
+    return;
   }
 
   const client = new WordPressBlockClient({
-    wordpress_url: WORDPRESS_URL,
+    wordpress_url: cfg.config.url,
     auth: {
-      username: WORDPRESS_USER,
-      application_password: WORDPRESS_APP_PASSWORD,
+      username: cfg.config.user,
+      application_password: cfg.config.password,
     },
   });
 
@@ -420,7 +390,7 @@ async function main(): Promise<void> {
   // from the start — no post-construction mutation of SDK internals.
   // `getInstructions` never throws: on any failure it logs to stderr
   // and returns the baseline only.
-  const instructions = await getInstructions(WORDPRESS_URL);
+  const instructions = await getInstructions(cfg.config.url);
 
   const server = new McpServer(
     {

package/src/instructions.ts

@@ -25,6 +25,7 @@
  */
 
 import axios, { AxiosError } from 'axios';
+import { restRouteUrl } from './rest-url.js';
 
 /**
  * The baseline instructions string.
@@ -188,9 +189,8 @@ export async function fetchAddendum(wordpressUrl: string): Promise<string> {
     return '';
   }
 
-  // Normalize trailing slash and resolve relative to wp-json.
-  const base = wordpressUrl.replace(/\/+$/, '');
-  const url = `${base}/wp-json/gk-block-api/v1/instructions`;
+  // Permalink-independent ?rest_route= form: /wp-json/ 404s on plain permalinks.
+  const url = restRouteUrl(wordpressUrl, '/instructions');
 
   try {
     const response = await axios.get<InstructionsResponse>(url, {