@gravitykit/block-mcp 2.0.1 → 2.1.0

package/src/client.ts

@@ -8,6 +8,8 @@
 
 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 {
@@ -181,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,
@@ -448,9 +451,11 @@ export class WordPressBlockClient {
       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;
@@ -540,7 +545,9 @@ export class WordPressBlockClient {
     index: number,
     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');
@@ -567,7 +574,9 @@ export class WordPressBlockClient {
     ref: 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');
@@ -601,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');
     }
@@ -633,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) {
@@ -666,7 +679,9 @@ export class WordPressBlockClient {
       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');
     }
@@ -691,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> = {};
@@ -716,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> = {};
@@ -747,7 +766,9 @@ export class WordPressBlockClient {
       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');
     }
@@ -779,7 +800,9 @@ export class WordPressBlockClient {
     postId: number,
     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');
     }
@@ -803,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`,
@@ -826,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;
   }
@@ -853,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>(
@@ -892,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;
   }
@@ -966,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,
+  };
+}

package/src/connect.ts

@@ -408,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();
@@ -434,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.`
         );

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;
 }
@@ -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';
@@ -58,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
@@ -152,7 +140,11 @@ const LEGACY_PREFERENCES_RESOURCE_URI = 'block-mcp://block-preferences';
 // `_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 };
@@ -166,6 +158,13 @@ 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) {
@@ -358,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,
     },
   });
 
@@ -382,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(
     {