@gravitykit/block-mcp 2.0.1 → 2.1.0

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, {

package/src/preferences.ts

@@ -117,12 +117,13 @@ export function enrichPatternList(patterns: Pattern[]): {
     (a, b) => b.preference.score - a.preference.score
   );
 
-  // Classify by tier only — the server is the source of truth and already
-  // applied policy. Mixing in score-based fallbacks (the old logic) caused
-  // mis-bucketing: an `avoid`-tier pattern with score 5 leaked into the
-  // recommended bucket; a `recommended`-tier pattern with negative score
-  // was double-counted. Trust the tier.
-  const recommended = sorted.filter((p) => p.preference.tier === 'recommended');
+  // Classify by the tier the server emits (preferred/acceptable/avoid/legacy),
+  // which is the source of truth and has already applied policy. The
+  // "recommended" display bucket is the usable set (preferred + acceptable);
+  // avoid + legacy are the ones to steer away from.
+  const recommended = sorted.filter(
+    (p) => p.preference.tier === 'preferred' || p.preference.tier === 'acceptable'
+  );
   const avoid       = sorted.filter((p) => p.preference.tier === 'avoid' || p.preference.tier === 'legacy');
 
   const lines: string[] = [];
@@ -196,49 +197,41 @@ export function enrichBlockTypes(types: BlockType[]): {
   }
 
   const lines: string[] = [];
-
-  if (preferred.length > 0) {
-    const grouped = groupByNamespace(preferred);
-    for (const [ns, blocks] of Object.entries(grouped)) {
-      const names = blocks.map((t) => getShortName(t.name)).join(', ');
-      lines.push(`PREFERRED (${ns}/): ${names}`);
-    }
-  }
-  if (acceptable.length > 0) {
-    const grouped = groupByNamespace(acceptable);
-    for (const [ns, blocks] of Object.entries(grouped)) {
-      const names = blocks.map((t) => getShortName(t.name)).join(', ');
-      lines.push(`ACCEPTABLE (${ns}/): ${names}`);
-    }
-  }
-  if (avoid.length > 0) {
-    const grouped = groupByNamespace(avoid);
-    for (const [ns, blocks] of Object.entries(grouped)) {
-      const mappings = blocks.map((t) => {
-        const replacement = t.preference.replacement;
-        const shortName = getShortName(t.name);
-        return replacement ? `${shortName} -> use ${replacement}` : shortName;
-      });
-      lines.push(`AVOID (${ns}/): ${mappings.join(', ')}`);
-    }
-  }
-  if (legacy.length > 0) {
-    const grouped = groupByNamespace(legacy);
-    for (const [ns, blocks] of Object.entries(grouped)) {
-      const mappings = blocks.map((t) => {
-        const replacement = t.preference.replacement;
-        const shortName = getShortName(t.name);
-        return replacement ? `${shortName} -> use ${replacement}` : shortName;
-      });
-      lines.push(`LEGACY — DO NOT USE (${ns}/): ${mappings.join(', ')}`);
-    }
-  }
+  pushTierLines(lines, preferred, 'PREFERRED', false);
+  pushTierLines(lines, acceptable, 'ACCEPTABLE', false);
+  pushTierLines(lines, avoid, 'AVOID', true);
+  pushTierLines(lines, legacy, 'LEGACY — DO NOT USE', true);
 
   const guidance = lines.join('\n');
 
   return { block_types: types, guidance };
 }
 
+/**
+ * Append one guidance line per namespace group within a tier bucket.
+ * No-ops when the bucket is empty, so callers don't need their own length
+ * check. `withReplacement` switches between a plain name list (preferred /
+ * acceptable) and a `name -> use replacement` mapping (avoid / legacy).
+ */
+function pushTierLines(
+  lines: string[],
+  bucket: BlockType[],
+  label: string,
+  withReplacement: boolean
+): void {
+  if (bucket.length === 0) return;
+  const grouped = groupByNamespace(bucket);
+  for (const [ns, blocks] of Object.entries(grouped)) {
+    const names = blocks.map((t) => {
+      const shortName = getShortName(t.name);
+      if (!withReplacement) return shortName;
+      const replacement = t.preference.replacement;
+      return replacement ? `${shortName} -> use ${replacement}` : shortName;
+    });
+    lines.push(`${label} (${ns}/): ${names.join(', ')}`);
+  }
+}
+
 /**
  * Format a preference warning into a single human-readable line.
  *
@@ -252,6 +245,26 @@ export function formatPreferenceWarning(warning: PreferenceWarning): string {
   return `WARNING: ${warning.message}`;
 }
 
+/**
+ * Decorate a write-tool result with `formatted_warnings` when its `warnings`
+ * array is non-empty. Returns the result unchanged (no `formatted_warnings`
+ * key) when there are none, so callers don't leak an empty array into every
+ * clean response.
+ *
+ * @param result - A write-tool response shape carrying an optional `warnings` array
+ * @param formatWarning - Per-warning formatter (e.g. formatPreferenceWarning)
+ */
+export function withFormattedWarnings<T extends { warnings?: unknown[] }>(
+  result: T,
+  formatWarning: (warning: NonNullable<T['warnings']>[number]) => string
+): T & { formatted_warnings?: string[] } {
+  if (result.warnings && result.warnings.length > 0) {
+    const warnings = result.warnings as NonNullable<T['warnings']>;
+    return { ...result, formatted_warnings: warnings.map(formatWarning) };
+  }
+  return result;
+}
+
 // ============================================
 // Helpers
 // ============================================

package/src/rest-url.ts

@@ -0,0 +1,18 @@
+/**
+ * Build a REST URL on the permalink-independent `?rest_route=` form.
+ *
+ * Hardcoding `/wp-json/` breaks on plain-permalink sites (and any custom
+ * `rest_url_prefix`): the connector can complete the handshake, then every tool
+ * call 404s because the pretty REST route does not exist. The `?rest_route=`
+ * form works on every permalink configuration, matching the connector's own
+ * exchange URL (see src/connect.ts).
+ *
+ * @param siteUrl - WordPress site URL; trailing slashes are trimmed.
+ * @param routeSuffix - Route path after the namespace, e.g. `/instructions`.
+ *                      Empty (default) yields the axios base URL.
+ * @returns e.g. `https://site.test/?rest_route=/gk-block-api/v1/instructions`
+ */
+export function restRouteUrl(siteUrl: string, routeSuffix = ''): string {
+  const trimmed = siteUrl.replace(/\/+$/, '');
+  return `${trimmed}/?rest_route=/gk-block-api/v1${routeSuffix}`;
+}

package/src/tools/discovery.ts

@@ -8,6 +8,7 @@
 
 import type { WordPressBlockClient } from '../client.js';
 import { enrichBlockTypes, enrichPatternList } from '../preferences.js';
+import { coercePostId } from '../coerce.js';
 
 const READ_ANNOT = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true } as const;
 
@@ -166,12 +167,14 @@ export async function handleDiscoveryTool(
     case 'list_patterns': {
       const limit  = (args.limit as number | undefined) ?? 20;
       const offset = (args.offset as number | undefined) ?? 0;
+      // Fetch the full set (no server-side limit) and paginate locally, matching
+      // list_block_types. Passing limit: offset+limit truncated `total` to the
+      // fetched window and made next_offset always null on a full page — the
+      // agent then never saw that more patterns existed.
       const response = await client.getPatterns({
         q: args.search as string | undefined,
         synced: args.synced as boolean | undefined,
         min_score: args.min_score as number | undefined,
-        // Fetch enough to honor offset+limit. Server caps respond too.
-        limit: offset + limit,
         refresh: args.refresh as boolean | undefined,
       });
       const enriched = enrichPatternList(response.patterns);
@@ -225,18 +228,11 @@ export async function handleDiscoveryTool(
       ) {
         throw new Error('get_post_info requires one of: post_id, url, or slug');
       }
-      // Coerce well-formed integer strings (some MCP clients and untyped
-      // JSON send numeric IDs as strings) but reject everything else with
-      // the same "post_id must be a positive integer" error the schema
-      // documents. Floats are rejected because the contract is integer.
-      let normalizedPostId: number | undefined;
-      if (typeof postId === 'number' && Number.isInteger(postId) && postId > 0) {
-        normalizedPostId = postId;
-      } else if (typeof postId === 'string' && /^[0-9]+$/.test(postId)) {
-        normalizedPostId = parseInt(postId, 10);
-      } else if (postId !== undefined && postId !== null) {
-        throw new Error('get_post_info: post_id must be a positive integer');
-      }
+      // Coerce well-formed integer strings (some MCP clients and untyped JSON
+      // send numeric IDs as strings); undefined is allowed here because url/slug
+      // are alternate selectors. Shared with update_post / yoast_* so the whole
+      // tool surface accepts a post_id identically.
+      const normalizedPostId = coercePostId(postId, 'get_post_info');
       return await client.getPostInfo({
         post_id:   normalizedPostId,
         url:       typeof url === 'string' ? url : undefined,

package/src/tools/mutate.ts

@@ -11,8 +11,9 @@
 
 import type { WordPressBlockClient } from '../client.js';
 import type { MutationOp, MutationRequest, MutationResponse, StaticBlockWarning } from '../types.js';
-import { formatPreferenceWarning } from '../preferences.js';
+import { formatPreferenceWarning, withFormattedWarnings } from '../preferences.js';
 import { BLOCK_INPUT_SCHEMA } from './write.js';
+import { coercePostId } from '../coerce.js';
 
 const OPS: readonly MutationOp[] = [
   'update-attrs',
@@ -115,12 +116,12 @@ export async function handleMutateTool(
     throw new Error(`Unknown mutate tool: ${toolName}`);
   }
 
-  const postId = args.post_id as number;
+  const postId = coercePostId(args.post_id, 'edit_block_tree');
   const op = args.op as string;
   const path = args.path;
   const ref = args.ref as string | undefined;
 
-  if (postId === undefined || postId === null) throw new Error('post_id is required');
+  if (postId === undefined) throw new Error('post_id is required');
   // Op validation comes from the schema enum at request time; this guard
   // exists for direct programmatic callers that bypass the MCP transport.
   if (!op || !(OPS as readonly string[]).includes(op)) {
@@ -175,10 +176,20 @@ export async function handleMutateTool(
       requestBody.block = block as MutationRequest['block'];
       if (op === 'insert-child' && args.position !== undefined) {
         const position = args.position;
-        if (typeof position === 'number' && Number.isInteger(position)) {
+        if (typeof position === 'number' && Number.isInteger(position) && position >= -1) {
           requestBody.position = position;
         } else if (position === 'start' || position === 'end') {
           requestBody.position = position;
+        } else if (typeof position === 'string' && /^-?\d+$/.test(position)) {
+          // The schema advertises `position` as integer|string; accept a
+          // numeric string ("3", or the "-1" append sentinel) as the index it
+          // plainly denotes rather than rejecting a schema-conformant value.
+          // -1 appends; anything below -1 is out of contract.
+          const parsedPosition = parseInt(position, 10);
+          if (parsedPosition < -1) {
+            throw new Error('position must be an integer >= -1, "start", or "end"');
+          }
+          requestBody.position = parsedPosition;
         } else {
           throw new Error('position must be an integer, "start", or "end"');
         }
@@ -227,12 +238,7 @@ export async function handleMutateTool(
 
   const result: MutationResponse = await client.mutateBlockTree(postId, requestBody);
 
-  if (result.warnings && result.warnings.length > 0) {
-    const formattedWarnings = result.warnings.map((warning) => {
-      if (isStaticBlockWarning(warning)) return formatStaticBlockWarning(warning);
-      return formatPreferenceWarning(warning);
-    });
-    return { ...result, formatted_warnings: formattedWarnings };
-  }
-  return result;
+  return withFormattedWarnings(result, (warning) =>
+    isStaticBlockWarning(warning) ? formatStaticBlockWarning(warning) : formatPreferenceWarning(warning)
+  );
 }

package/src/tools/patterns.ts

@@ -7,6 +7,7 @@
  */
 
 import type { WordPressBlockClient } from '../client.js';
+import { coercePostId } from '../coerce.js';
 
 /**
  * Tool definitions for the pattern category.
@@ -61,13 +62,13 @@ export async function handlePatternTool(
 ): Promise<unknown> {
   switch (toolName) {
     case 'insert_pattern': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'insert_pattern');
       const patternId = args.pattern_id as number | string;
       const after = args.after_top_level as number | undefined;
       const before = args.before_top_level as number | undefined;
       const synced = args.synced as boolean | undefined;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       if (patternId === undefined || patternId === null) throw new Error('pattern_id is required');
 
       const result = await client.insertPattern(postId, {

package/src/tools/posts.ts

@@ -12,6 +12,7 @@
 import type { WordPressBlockClient } from '../client.js';
 import type { CreatePostRequest, UpdatePostRequest } from '../types.js';
 import { BLOCK_INPUT_SCHEMA } from './write.js';
+import { coercePostId } from '../coerce.js';
 
 const POST_STATUS_CREATE = ['draft', 'pending', 'private', 'publish', 'future'] as const;
 const POST_STATUS_UPDATE = ['draft', 'pending', 'private', 'publish', 'future', 'trash'] as const;
@@ -128,15 +129,17 @@ export async function handlePostTool(
     }
 
     case 'update_post': {
-      if (typeof args.post_id !== 'number') {
-        throw new Error('update_post: "post_id" (number) is required');
+      const postId = coercePostId(args.post_id, 'update_post');
+      if (postId === undefined) {
+        throw new Error('update_post: "post_id" is required');
       }
-      const { post_id: postId, ...rest } = args;
+      const { post_id: _omit, ...rest } = args;
+      void _omit;
       if (Object.keys(rest).length === 0) {
         throw new Error('update_post: provide at least one mutating field besides post_id');
       }
       const update = narrowUpdatePost(rest);
-      return client.updatePost(postId as number, update);
+      return client.updatePost(postId, update);
     }
 
     default:
@@ -144,13 +147,14 @@ export async function handlePostTool(
   }
 }
 
-function narrowCreatePost(input: Record<string, unknown>): CreatePostRequest {
-  // input.title is already validated as a non-empty string by the caller.
-  const out: CreatePostRequest = { title: input.title as string };
-  if (typeof input.post_type === 'string') out.post_type = input.post_type;
-  if (typeof input.status === 'string') out.status = input.status as CreatePostRequest['status'];
-  if (typeof input.content === 'string') out.content = input.content;
-  if (Array.isArray(input.blocks)) out.blocks = input.blocks as CreatePostRequest['blocks'];
+/** Fields narrowed identically for create_post and update_post (everything except title/status/content/blocks/post_type — those differ in requiredness or are create-only). */
+type CommonPostFields = Pick<
+  UpdatePostRequest,
+  'slug' | 'parent' | 'excerpt' | 'featured_media' | 'categories' | 'tags' | 'terms' | 'date' | 'menu_order' | 'comment_status' | 'ping_status' | 'author'
+>;
+
+function narrowCommonPostFields(input: Record<string, unknown>): CommonPostFields {
+  const out: CommonPostFields = {};
   if (typeof input.slug === 'string') out.slug = input.slug;
   if (typeof input.parent === 'number') out.parent = input.parent;
   if (typeof input.excerpt === 'string') out.excerpt = input.excerpt;
@@ -168,24 +172,20 @@ function narrowCreatePost(input: Record<string, unknown>): CreatePostRequest {
   return out;
 }
 
+function narrowCreatePost(input: Record<string, unknown>): CreatePostRequest {
+  // input.title is already validated as a non-empty string by the caller.
+  const out: CreatePostRequest = { title: input.title as string, ...narrowCommonPostFields(input) };
+  if (typeof input.post_type === 'string') out.post_type = input.post_type;
+  if (typeof input.status === 'string') out.status = input.status as CreatePostRequest['status'];
+  if (typeof input.content === 'string') out.content = input.content;
+  if (Array.isArray(input.blocks)) out.blocks = input.blocks as CreatePostRequest['blocks'];
+  return out;
+}
+
 function narrowUpdatePost(input: Record<string, unknown>): UpdatePostRequest {
-  const out: UpdatePostRequest = {};
+  const out: UpdatePostRequest = narrowCommonPostFields(input);
   if (typeof input.title === 'string') out.title = input.title;
   if (typeof input.status === 'string') out.status = input.status as UpdatePostRequest['status'];
-  if (typeof input.slug === 'string') out.slug = input.slug;
-  if (typeof input.parent === 'number') out.parent = input.parent;
-  if (typeof input.excerpt === 'string') out.excerpt = input.excerpt;
-  if (typeof input.featured_media === 'number') out.featured_media = input.featured_media;
-  if (Array.isArray(input.categories)) out.categories = (input.categories as unknown[]).filter((n) => typeof n === 'number') as number[];
-  if (Array.isArray(input.tags)) out.tags = (input.tags as unknown[]).filter((n) => typeof n === 'number') as number[];
-  if (input.terms && typeof input.terms === 'object' && !Array.isArray(input.terms)) {
-    out.terms = narrowTermsMap(input.terms as Record<string, unknown>);
-  }
-  if (typeof input.date === 'string') out.date = input.date;
-  if (typeof input.menu_order === 'number') out.menu_order = input.menu_order;
-  if (input.comment_status === 'open' || input.comment_status === 'closed') out.comment_status = input.comment_status;
-  if (input.ping_status === 'open' || input.ping_status === 'closed') out.ping_status = input.ping_status;
-  if (typeof input.author === 'number') out.author = input.author;
   return out;
 }
 

package/src/tools/read.ts

@@ -8,6 +8,7 @@
 
 import type { WordPressBlockClient } from '../client.js';
 import { enrichBlockList } from '../preferences.js';
+import { coercePostId } from '../coerce.js';
 
 /**
  * Tool definitions for the read category.
@@ -137,7 +138,7 @@ export async function handleReadTool(
 ): Promise<unknown> {
   switch (toolName) {
     case 'get_page_blocks': {
-      let postId = args.post_id as number | undefined;
+      let postId = coercePostId(args.post_id, 'get_page_blocks');
       const url = args.url as string | undefined;
       const fields = args.fields as string | undefined;
       const render = args.render as boolean | undefined;
@@ -150,11 +151,11 @@ export async function handleReadTool(
       const limit = args.limit as number | undefined;
       const cursor = args.cursor as string | undefined;
 
-      if ((postId === undefined || postId === null) && !url) {
+      if (postId === undefined && !url) {
         throw new Error('Either post_id or url is required');
       }
 
-      if (postId === undefined || postId === null) {
+      if (postId === undefined) {
         const resolved = await client.resolveUrl(url as string);
         postId = resolved.post_id;
       }
@@ -192,14 +193,14 @@ export async function handleReadTool(
     }
 
     case 'get_block': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'get_block');
       const ref = typeof args.ref === 'string' && args.ref.length > 0 ? (args.ref as string) : undefined;
       const flatIndex =
-        typeof args.flat_index === 'number' && Number.isFinite(args.flat_index)
+        typeof args.flat_index === 'number' && Number.isInteger(args.flat_index) && args.flat_index >= 0
           ? (args.flat_index as number)
           : undefined;
 
-      if (postId === undefined || postId === null) {
+      if (postId === undefined) {
         throw new Error('post_id is required');
       }
       const hasRef = ref !== undefined;

package/src/tools/write.ts

@@ -9,8 +9,9 @@
  */
 
 import type { WordPressBlockClient } from '../client.js';
-import { formatPreferenceWarning } from '../preferences.js';
+import { formatPreferenceWarning, withFormattedWarnings } from '../preferences.js';
 import { enrichBlock, enrichBlocks, type BlockDef } from '../enrichers.js';
+import { coercePostId } from '../coerce.js';
 
 /** Shape shared by every block-input arg in this module. */
 export const BLOCK_INPUT_SCHEMA = {
@@ -75,7 +76,9 @@ export const WRITE_TOOLS = [
     // idempotentHint is false: every call creates a new revision, and
     // revision history is observable to other readers. Same-input/same-state
     // is true at the block level but not at the post level.
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, title: 'Update one block' },
+    // destructiveHint is true: attributes/innerHTML overwrite the block's
+    // existing content rather than merging additively.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, title: 'Update one block' },
     outputSchema: {
       type: 'object',
       properties: {
@@ -123,7 +126,8 @@ export const WRITE_TOOLS = [
     name: 'update_blocks',
     description:
       'Update N independent blocks atomically in ONE revision. Each item targets one block by `ref` (recommended) or `flat_index`, with `attributes` and/or `innerHTML`. Validation is all-or-nothing: any stale ref / out-of-range index / dual-storage rejection / duplicate target aborts the batch with itemized errors — no partial writes hit disk. Max 50 items per call. Counts as ONE write against the per-post rate limit. Use this instead of looping update_block when fixing multiple blocks on the same post — keeps revision history clean. Pass `verbose: true` to include `saved.inner_html` + `saved.attributes` per result for per-item verification without a re-read.',
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, title: 'Batch-update blocks' },
+    // destructiveHint is true: same overwrite semantics as update_block, applied per item.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, title: 'Batch-update blocks' },
     outputSchema: {
       type: 'object',
       properties: {
@@ -333,14 +337,14 @@ export async function handleWriteTool(
 ): Promise<unknown> {
   switch (toolName) {
     case 'update_block': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'update_block');
       const flatIndex = args.flat_index as number | undefined;
       const ref = args.ref as string | undefined;
       const blockName = args.block_name as string | undefined;
       let attributes = args.attributes as Record<string, unknown> | undefined;
       let innerHTML = args.innerHTML as string | undefined;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       const hasIndex = typeof flatIndex === 'number' && Number.isFinite(flatIndex) && flatIndex >= 0;
       const hasRef = typeof ref === 'string' && ref.length > 0;
       if (!hasIndex && !hasRef) {
@@ -369,7 +373,7 @@ export async function handleWriteTool(
     }
 
     case 'update_blocks': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'update_blocks');
       const updates = args.updates as Array<{
         ref?: string;
         flat_index?: number;
@@ -378,7 +382,7 @@ export async function handleWriteTool(
         innerHTML?: string;
       }> | undefined;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       if (!Array.isArray(updates) || updates.length === 0) {
         throw new Error('updates must be a non-empty array');
       }
@@ -440,7 +444,7 @@ export async function handleWriteTool(
     }
 
     case 'insert_blocks': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'insert_blocks');
       const after = args.after_top_level as number | 'start' | undefined;
       const before = args.before_top_level as number | undefined;
       const afterRef = args.after_ref as string | undefined;
@@ -451,7 +455,7 @@ export async function handleWriteTool(
         innerHTML?: string;
       }>;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       if (!blocks || blocks.length === 0) throw new Error('At least one block is required in the blocks array');
 
       const result = await client.insertBlocks(postId, {
@@ -461,19 +465,16 @@ export async function handleWriteTool(
         ...(beforeRef ? { before_ref: beforeRef } : {}),
         blocks: await enrichBlocks(blocks as BlockDef[]),
       });
-      if (result.warnings && result.warnings.length > 0) {
-        return { ...result, formatted_warnings: result.warnings.map(formatPreferenceWarning) };
-      }
-      return result;
+      return withFormattedWarnings(result, formatPreferenceWarning);
     }
 
     case 'delete_block': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'delete_block');
       const topLevelCounter = args.top_level_counter as number | undefined;
       const ref = args.ref as string | undefined;
       const count = args.count as number | undefined;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       const hasCounter = typeof topLevelCounter === 'number' && Number.isFinite(topLevelCounter) && topLevelCounter >= 0;
       const hasRef = typeof ref === 'string' && ref.length > 0;
       if (!hasCounter && !hasRef) {
@@ -495,7 +496,7 @@ export async function handleWriteTool(
     }
 
     case 'replace_block_range': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'replace_block_range');
       const start = args.start as number;
       const count = args.count as number;
       const blocks = args.blocks as Array<{
@@ -504,40 +505,34 @@ export async function handleWriteTool(
         innerHTML?: string;
       }>;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
-      if (typeof start !== 'number' || start < 0) throw new Error('start must be a non-negative integer');
-      if (typeof count !== 'number' || count < 0) throw new Error('count must be a non-negative integer');
+      if (postId === undefined) throw new Error('post_id is required');
+      if (!Number.isSafeInteger(start) || start < 0) throw new Error('start must be a non-negative integer');
+      if (!Number.isSafeInteger(count) || count < 0) throw new Error('count must be a non-negative integer');
       if (!Array.isArray(blocks)) throw new Error('blocks must be an array (may be empty for a pure delete)');
 
       const result = await client.replaceBlocksRange(postId, { start, count, blocks: await enrichBlocks(blocks as BlockDef[]) });
-      if (result.warnings && result.warnings.length > 0) {
-        return { ...result, formatted_warnings: result.warnings.map(formatPreferenceWarning) };
-      }
-      return result;
+      return withFormattedWarnings(result, formatPreferenceWarning);
     }
 
     case 'rewrite_post_blocks': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'rewrite_post_blocks');
       const blocks = args.blocks as Array<{
         name: string;
         attributes?: Record<string, unknown>;
         innerHTML?: string;
       }>;
 
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       if (!blocks || blocks.length === 0) throw new Error('At least one block is required for a full page rewrite');
 
       const result = await client.replaceAllBlocks(postId, await enrichBlocks(blocks as BlockDef[]));
-      if (result.warnings && result.warnings.length > 0) {
-        return { ...result, formatted_warnings: result.warnings.map(formatPreferenceWarning) };
-      }
-      return result;
+      return withFormattedWarnings(result, formatPreferenceWarning);
     }
 
     case 'revert_to_revision': {
-      const postId = args.post_id as number;
+      const postId = coercePostId(args.post_id, 'revert_to_revision');
       const revisionId = args.revision_id as number;
-      if (postId === undefined || postId === null) throw new Error('post_id is required');
+      if (postId === undefined) throw new Error('post_id is required');
       if (revisionId === undefined || revisionId === null) throw new Error('revision_id is required');
       return await client.revertToRevision(postId, revisionId);
     }