@gravitykit/block-mcp 2.0.1 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravitykit/block-mcp",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "MCP server for WordPress block-level content management with preference-aware editing",
   "main": "dist/index.cjs",
   "bin": {
@@ -17,6 +17,7 @@
     "test:watch": "vitest",
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "test:docs": "playwright test --config tests/docs/playwright.config.ts",
+    "test:e2e": "playwright test --config tests/e2e/playwright.config.ts",
     "eval": "tsx tests/evals/lib/runner.ts",
     "eval:fixture-refresh": "tsx tests/evals/scripts/fetch-fixture.ts",
     "prepare": "npm run build",
@@ -42,7 +43,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "axios": "^1.7.9",
+    "axios": "^1.16.0",
     "form-data": "^4.0.1"
   },
   "devDependencies": {
@@ -51,12 +52,12 @@
     "@shikijs/engine-javascript": "^4.0.2",
     "@shikijs/langs": "^4.0.2",
     "@types/node": "^22.0.0",
-    "esbuild": "^0.27.3",
+    "esbuild": "^0.28.1",
     "sharp": "^0.33.5",
     "shiki": "^4.0.2",
     "tsx": "^4.21.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.6"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -70,5 +71,8 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "overrides": {
+    "esbuild": "$esbuild"
   }
 }

package/src/__tests__/coerce.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { coercePostId } from '../coerce.js';
+
+/**
+ * Unit tests for the shared coercePostId() helper.
+ *
+ * Every post_id tool (get_post_info, update_post, yoast_*) inherits this
+ * helper, so its "positive integer" contract must hold uniformly — a numeric
+ * string is accepted identically to the number, and a zero/negative/non-numeric
+ * value is rejected identically. The zero-string cases pin the fix for the gap
+ * where "0"/"00" parsed to 0 while the number 0 threw.
+ */
+describe('coercePostId', () => {
+  it('returns undefined for absent values', () => {
+    expect(coercePostId(undefined, 't')).toBeUndefined();
+    expect(coercePostId(null, 't')).toBeUndefined();
+  });
+
+  it('accepts a positive integer number', () => {
+    expect(coercePostId(123, 't')).toBe(123);
+  });
+
+  it('coerces a positive numeric string', () => {
+    expect(coercePostId('123', 't')).toBe(123);
+    expect(coercePostId('042', 't')).toBe(42);
+  });
+
+  it('rejects the number 0 and negatives', () => {
+    expect(() => coercePostId(0, 't')).toThrow('post_id must be a positive integer');
+    expect(() => coercePostId(-1, 't')).toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects zero-valued strings identically to the number 0', () => {
+    expect(() => coercePostId('0', 't')).toThrow('post_id must be a positive integer');
+    expect(() => coercePostId('00', 't')).toThrow('post_id must be a positive integer');
+    expect(() => coercePostId('000', 't')).toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects floats and non-numeric strings', () => {
+    expect(() => coercePostId(1.5, 't')).toThrow('post_id must be a positive integer');
+    expect(() => coercePostId('12.5', 't')).toThrow('post_id must be a positive integer');
+    expect(() => coercePostId('abc', 't')).toThrow('post_id must be a positive integer');
+    expect(() => coercePostId('12abc', 't')).toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects integers above Number.MAX_SAFE_INTEGER', () => {
+    // Beyond 2^53-1 the number can no longer represent the exact id, so a
+    // parsed/rounded value would target the wrong post.
+    expect(() => coercePostId(Number.MAX_SAFE_INTEGER + 1, 't')).toThrow('post_id must be a positive integer');
+    expect(() => coercePostId('9007199254740993', 't')).toThrow('post_id must be a positive integer');
+    expect(() => coercePostId('99999999999999999999', 't')).toThrow('post_id must be a positive integer');
+  });
+
+  it('prefixes the thrown error with the caller label', () => {
+    expect(() => coercePostId('x', 'update_post')).toThrow('update_post: post_id must be a positive integer');
+  });
+});

package/src/__tests__/fixtures/error-envelopes.ts

@@ -43,19 +43,23 @@ export const ERROR_ENVELOPES: ErrorEnvelope[] = [
   { code: 'not_found',           httpStatus: 404, data: null },
   { code: 'not_found_with_post', httpStatus: 404, data: { post_id: 77 } },
 
-  // ── Precondition / concurrency (412) ────────────────────────────────────
-  { code: 'stale_revision', httpStatus: 412, data: null },
+  // ── Precondition / concurrency (409/412) ────────────────────────────────
+  { code: 'stale_revision', httpStatus: 412, data: { current_revision: 88 } },
+  { code: 'edit_conflict',  httpStatus: 409, data: null },
 
   // ── Validation (400) ────────────────────────────────────────────────────
   { code: 'legacy_block',              httpStatus: 400, data: { block: 'ugb/text', suggested_replacement: 'core/paragraph' } },
+  { code: 'inner_html_required',       httpStatus: 400, data: { block: 'core/paragraph', source_bound_attributes: ['content'] } },
+  { code: 'static_markup_stale_risk',  httpStatus: 400, data: null },
   { code: 'dual_storage_requires_both', httpStatus: 400, data: { block_name: 'yoast/faq-block' } },
   { code: 'bound_attribute',           httpStatus: 400, data: null },
   { code: 'batch_too_large',           httpStatus: 400, data: null },
   { code: 'batch_validation_failed',   httpStatus: 400, data: { errors: [{ index: 0, code: 'ref_stale' }] } },
   { code: 'empty_batch',               httpStatus: 400, data: null },
-  { code: 'block_depth_exceeded',      httpStatus: 400, data: null },
+  { code: 'block_depth_exceeded',      httpStatus: 400, data: { max_depth: 32, actual_depth: 33 } },
   { code: 'invalid_path',              httpStatus: 400, data: { path: [0, 99] } },
   { code: 'invalid_ref',               httpStatus: 400, data: null },
+  { code: 'invalid_index',             httpStatus: 400, data: { flat_index: 12 } },
   { code: 'ref_not_top_level',         httpStatus: 400, data: { ref: 'blk_nested' } },
   { code: 'invalid_op',                httpStatus: 400, data: null },
   { code: 'invalid_block',             httpStatus: 400, data: null },
@@ -70,9 +74,11 @@ export const ERROR_ENVELOPES: ErrorEnvelope[] = [
   { code: 'file_too_large',            httpStatus: 400, data: null },
   { code: 'invalid_url',               httpStatus: 400, data: null },
   { code: 'empty_pattern',             httpStatus: 400, data: null },
+  { code: 'trash_disabled',            httpStatus: 403, data: null },
 
   // ── Rate limit (429) ────────────────────────────────────────────────────
   { code: 'rate_limit_exceeded', httpStatus: 429, data: { post_id: 42 } },
+  { code: 'rate_limit_locked',   httpStatus: 429, data: { post_id: 42 } },
   { code: 'scan_rate_limited',   httpStatus: 429, data: null },
 
   // ── Upstream (502) ──────────────────────────────────────────────────────
@@ -97,19 +103,25 @@ export const TRANSLATED_CODES = new Set([
   'rest_cookie_invalid_nonce',
   'rest_authentication_required',
   'rest_post_invalid_id',
-  'invalid_post_id',
+  'post_not_found',
   'not_found',
-  'gk_block_api_invalid_ref',
   'invalid_ref',
-  'path_not_found',
+  'ref_stale',
   'invalid_path',
-  'path_out_of_bounds',
+  'invalid_index',
   'legacy_block',
+  'inner_html_required',
   'static_markup_stale_risk',
+  'dual_storage_requires_both',
+  'block_depth_exceeded',
+  'edit_conflict',
+  'stale_revision',
   'rate_limit_exceeded',
+  'rate_limit_locked',
   'mixed_trash_payload',
   'invalid_post_type',
   'invalid_status',
+  'trash_disabled',
   'invalid_url',
   'disallowed_mime',
 ]);

package/src/__tests__/integration/error-envelopes.test.ts

@@ -125,14 +125,14 @@ describe.skipIf(skip)('real REST error envelopes (integration)', () => {
     expect(result.message).toBeTruthy();
   });
 
-  it('invalid_path: mutate with out-of-range path returns 400 + path error code', async () => {
+  it('invalid_path: mutate with out-of-range path returns 400 + invalid_path', async () => {
     const result = await rawRequest('post', `/posts/${livePostId}/mutate`, {
       op: 'update-attrs',
       path: [999, 999, 999],
       attributes: { content: 'never land' },
     });
     expect(result.status).toBe(400);
-    expect(['invalid_path', 'path_not_found', 'path_out_of_bounds']).toContain(result.code);
+    expect(result.code).toBe('invalid_path');
     expect(result.message).toBeTruthy();
   });
 

package/src/__tests__/tools/discovery/list_patterns.test.ts

@@ -3,7 +3,8 @@
  *
  * Covers:
  *   - Filter forwarding (search → q, synced, min_score)
- *   - Server-side limit = offset + limit (so client slice still works)
+ *   - Full fetch (no server-side limit) + client-side pagination, so `total`
+ *     and `next_offset` reflect the true count (matches list_block_types)
  *   - Client-side slicing via offset
  *   - Defaults: limit 20, offset 0
  *   - Response shape: patterns, count, total, offset, next_offset, summary
@@ -46,15 +47,33 @@ describe('list_patterns — pagination', () => {
     client.getPatterns.mockResolvedValue(patternsResponse);
   });
 
-  it('defaults to limit 20, offset 0', async () => {
+  it('fetches the full set (no truncating server-side limit)', async () => {
     await handleDiscoveryTool('list_patterns', {}, client as any);
-    // server limit is offset + limit = 0 + 20 = 20
-    expect(client.getPatterns).toHaveBeenCalledWith(expect.objectContaining({ limit: 20 }));
+    // No `limit` is sent: the handler paginates locally so `total` and
+    // `next_offset` reflect the true count instead of the fetched window.
+    const args = client.getPatterns.mock.calls[0][0];
+    expect(args?.limit).toBeUndefined();
   });
 
-  it('server limit accounts for offset (offset+limit)', async () => {
+  it('does not cap the fetch by offset+limit', async () => {
     await handleDiscoveryTool('list_patterns', { limit: 10, offset: 30 }, client as any);
-    expect(client.getPatterns).toHaveBeenCalledWith(expect.objectContaining({ limit: 40 }));
+    const args = client.getPatterns.mock.calls[0][0];
+    expect(args?.limit).toBeUndefined();
+  });
+
+  it('reports true total and non-null next_offset when more remain', async () => {
+    const many = Array.from({ length: 30 }, (_, i) => ({
+      id: i + 1, name: `pattern-${i}`,
+      type: 'registered' as const,
+      created: '2026-01-01', modified: '2026-01-01',
+      reference_count: 0,
+      preference: { score: 80, tier: 'recommended' as const, reasons: [] },
+      contains_blocks: [], has_legacy_blocks: false,
+    }));
+    client.getPatterns.mockResolvedValueOnce({ patterns: many } as any);
+    const result = await handleDiscoveryTool('list_patterns', { limit: 20, offset: 0 }, client as any) as Record<string, unknown>;
+    expect(result.total).toBe(30);
+    expect(result.next_offset).toBe(20);
   });
 
   it('client-side slice honors offset', async () => {

package/src/__tests__/tools/mutate/edit_block_tree.test.ts

@@ -40,6 +40,26 @@ describe('edit_block_tree — common validation', () => {
     ).rejects.toThrow(/post_id is required/);
   });
 
+  it('rejects a float post_id', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: 1.5, op: 'update-attrs', path: [0], attributes: {} }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects a negative post_id', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: -1, op: 'update-attrs', path: [0], attributes: {} }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects an overflow post_id', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: Number.MAX_SAFE_INTEGER + 1, op: 'update-attrs', path: [0], attributes: {},
+      }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
   it('rejects unknown op', async () => {
     await expect(
       handleMutateTool('edit_block_tree', { post_id: 1, op: 'frobnicate', path: [0] }, client as any)
@@ -247,6 +267,39 @@ describe('edit_block_tree — insert-child', () => {
     }));
   });
 
+  it('coerces a numeric-string position to an integer', async () => {
+    // The inputSchema advertises position as integer|string, so a numeric
+    // string ("3") is schema-conformant and must be accepted as the index.
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'insert-child', path: [0],
+      block: { name: 'core/paragraph' }, position: '3',
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      position: 3,
+    }));
+  });
+
+  it('accepts the "-1" append sentinel as a string', async () => {
+    // -1 is the documented append sentinel; its string form must behave like
+    // the number -1, not be rejected as a non-numeric position.
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'insert-child', path: [0],
+      block: { name: 'core/paragraph' }, position: '-1',
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      position: -1,
+    }));
+  });
+
+  it('rejects positions below the -1 append sentinel', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'insert-child', path: [0],
+        block: { name: 'core/paragraph' }, position: '-2',
+      }, client as any)
+    ).rejects.toThrow(/position must be/);
+  });
+
   it('rejects invalid position string', async () => {
     await expect(
       handleMutateTool('edit_block_tree', {

package/src/__tests__/tools/patterns/insert_pattern.test.ts

@@ -27,6 +27,22 @@ describe('insert_pattern — validation', () => {
       .rejects.toThrow('post_id');
   });
 
+  it('rejects a float post_id', async () => {
+    await expect(handlePatternTool('insert_pattern', { post_id: 1.5, pattern_id: 1 }, client as any))
+      .rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects a negative post_id', async () => {
+    await expect(handlePatternTool('insert_pattern', { post_id: -1, pattern_id: 1 }, client as any))
+      .rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects an overflow post_id', async () => {
+    await expect(
+      handlePatternTool('insert_pattern', { post_id: Number.MAX_SAFE_INTEGER + 1, pattern_id: 1 }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
   it('requires pattern_id', async () => {
     await expect(handlePatternTool('insert_pattern', { post_id: 1 }, client as any))
       .rejects.toThrow('pattern_id');

package/src/__tests__/tools/posts/update_post.test.ts

@@ -61,6 +61,20 @@ describe('update_post — request shape', () => {
     const body = client.updatePost.mock.calls[0]![1] as Record<string, unknown>;
     expect(body).not.toHaveProperty('post_id');
   });
+
+  // Some MCP clients / untyped JSON send numeric IDs as strings. get_post_info
+  // already coerces them; update_post must accept the same, or the same post is
+  // editable via one tool and rejected by another in one session.
+  it('coerces a numeric-string post_id to a number', async () => {
+    await handlePostTool('update_post', { post_id: '42', status: 'draft' }, client as any);
+    expect(client.updatePost).toHaveBeenCalledWith(42, { status: 'draft' });
+  });
+
+  it('rejects a non-numeric post_id string', async () => {
+    await expect(handlePostTool('update_post', { post_id: 'abc', status: 'draft' }, client as any))
+      .rejects.toThrow('post_id must be a positive integer');
+    expect(client.updatePost).not.toHaveBeenCalled();
+  });
 });
 
 describe('update_post — response shape', () => {

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

@@ -31,6 +31,24 @@ describe('get_block — input validation', () => {
     ).rejects.toThrow(/post_id is required/);
   });
 
+  it('rejects a float post_id', async () => {
+    await expect(
+      handleReadTool('get_block', { post_id: 1.5, ref: 'blk_a' }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects a negative post_id', async () => {
+    await expect(
+      handleReadTool('get_block', { post_id: -1, ref: 'blk_a' }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects an overflow post_id', async () => {
+    await expect(
+      handleReadTool('get_block', { post_id: Number.MAX_SAFE_INTEGER + 1, ref: 'blk_a' }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
   it('requires exactly one of ref or flat_index (rejects neither)', async () => {
     await expect(
       handleReadTool('get_block', { post_id: 1 }, client as any)
@@ -54,6 +72,23 @@ describe('get_block — input validation', () => {
       handleReadTool('get_block', { post_id: 1, flat_index: NaN }, client as any)
     ).rejects.toThrow(/exactly one of ref or flat_index/);
   });
+
+  it('treats a fractional flat_index as missing (must be an integer)', async () => {
+    await expect(
+      handleReadTool('get_block', { post_id: 1, flat_index: 1.5 }, client as any)
+    ).rejects.toThrow(/exactly one of ref or flat_index/);
+    expect(client.getBlock).not.toHaveBeenCalled();
+  });
+
+  // update_block / delete_block reject a negative flat_index client-side;
+  // get_block must match so a negative index is treated as absent, not sent
+  // to the server as a valid target.
+  it('treats a negative flat_index as missing (still requires ref)', async () => {
+    await expect(
+      handleReadTool('get_block', { post_id: 1, flat_index: -1 }, client as any)
+    ).rejects.toThrow(/exactly one of ref or flat_index/);
+    expect(client.getBlock).not.toHaveBeenCalled();
+  });
 });
 
 describe('get_block — routing', () => {

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

@@ -32,6 +32,24 @@ describe('get_page_blocks — input validation', () => {
     ).rejects.toThrow(/post_id or url/);
   });
 
+  it('rejects a float post_id (does not silently fall through to url resolution)', async () => {
+    await expect(
+      handleReadTool('get_page_blocks', { post_id: 1.5 }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects a negative post_id', async () => {
+    await expect(
+      handleReadTool('get_page_blocks', { post_id: -1 }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects an overflow post_id', async () => {
+    await expect(
+      handleReadTool('get_page_blocks', { post_id: Number.MAX_SAFE_INTEGER + 1 }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
   it('accepts post_id alone', async () => {
     await expect(
       handleReadTool('get_page_blocks', { post_id: 42 }, client as any)

package/src/__tests__/tools/write/delete_block.test.ts

@@ -23,6 +23,24 @@ describe('delete_block — validation', () => {
     ).rejects.toThrow('post_id');
   });
 
+  it('rejects a float post_id', async () => {
+    await expect(
+      handleWriteTool('delete_block', { post_id: 1.5, top_level_counter: 0 }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects a negative post_id', async () => {
+    await expect(
+      handleWriteTool('delete_block', { post_id: -1, top_level_counter: 0 }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects an overflow post_id', async () => {
+    await expect(
+      handleWriteTool('delete_block', { post_id: Number.MAX_SAFE_INTEGER + 1, top_level_counter: 0 }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
   it('requires top_level_counter OR ref (not neither)', async () => {
     await expect(
       handleWriteTool('delete_block', { post_id: 1 }, client as any)

package/src/__tests__/tools/write/insert_blocks.test.ts

@@ -32,6 +32,27 @@ describe('insert_blocks — validation', () => {
     ).rejects.toThrow('post_id');
   });
 
+  it('rejects a float post_id', async () => {
+    await expect(
+      handleWriteTool('insert_blocks', { post_id: 1.5, blocks: [{ name: 'core/paragraph' }] }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects a negative post_id', async () => {
+    await expect(
+      handleWriteTool('insert_blocks', { post_id: -1, blocks: [{ name: 'core/paragraph' }] }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects an overflow post_id', async () => {
+    await expect(
+      handleWriteTool('insert_blocks', {
+        post_id: Number.MAX_SAFE_INTEGER + 1,
+        blocks: [{ name: 'core/paragraph' }],
+      }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
   it('requires at least one block', async () => {
     await expect(
       handleWriteTool('insert_blocks', { post_id: 1 }, client as any)

package/src/__tests__/tools/write/replace_block_range.test.ts

@@ -11,6 +11,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { handleWriteTool } from '../../../tools/write.js';
 import { makeMockClient } from '../../helpers/mock-client.js';
+import { assertHasFormattedWarning, assertNoFormattedWarnings } from '../../helpers/request-matchers.js';
 
 vi.mock('../../../enrichers.js', () => ({
   enrichBlock: vi.fn(async (block: any) => block),
@@ -29,6 +30,26 @@ describe('replace_block_range — validation', () => {
     ).rejects.toThrow('post_id');
   });
 
+  it('rejects a float post_id', async () => {
+    await expect(
+      handleWriteTool('replace_block_range', { post_id: 1.5, start: 0, count: 1, blocks: [] }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects a negative post_id', async () => {
+    await expect(
+      handleWriteTool('replace_block_range', { post_id: -1, start: 0, count: 1, blocks: [] }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects an overflow post_id', async () => {
+    await expect(
+      handleWriteTool('replace_block_range', {
+        post_id: Number.MAX_SAFE_INTEGER + 1, start: 0, count: 1, blocks: [],
+      }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
   it('requires start', async () => {
     await expect(
       handleWriteTool('replace_block_range', { post_id: 1, count: 1, blocks: [] }, client as any)
@@ -46,6 +67,24 @@ describe('replace_block_range — validation', () => {
       handleWriteTool('replace_block_range', { post_id: 1, start: 0, count: 1 }, client as any)
     ).rejects.toThrow('block');
   });
+
+  it('rejects a fractional start', async () => {
+    await expect(
+      handleWriteTool('replace_block_range', { post_id: 1, start: 1.5, count: 1, blocks: [] }, client as any)
+    ).rejects.toThrow('start must be a non-negative integer');
+  });
+
+  it('rejects a NaN count', async () => {
+    await expect(
+      handleWriteTool('replace_block_range', { post_id: 1, start: 0, count: NaN, blocks: [] }, client as any)
+    ).rejects.toThrow('count must be a non-negative integer');
+  });
+
+  it('rejects an Infinity start', async () => {
+    await expect(
+      handleWriteTool('replace_block_range', { post_id: 1, start: Infinity, count: 1, blocks: [] }, client as any)
+    ).rejects.toThrow('start must be a non-negative integer');
+  });
 });
 
 describe('replace_block_range — forwarding', () => {
@@ -88,3 +127,35 @@ describe('replace_block_range — forwarding', () => {
     expect(client.replaceBlocksRange).toHaveBeenCalled();
   });
 });
+
+describe('replace_block_range — warning enrichment', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('adds formatted_warnings when response has warnings', async () => {
+    client.replaceBlocksRange = vi.fn().mockResolvedValue({
+      success: true, removed: 1,
+      inserted: [{ index: 0, name: 'oldns/heading' }],
+      warnings: [{ block: 'oldns/heading', message: 'AVOID', suggested_replacement: 'core/heading' }],
+      before_revision_id: 1, revision_id: 2,
+    }) as any;
+    const result = await handleWriteTool('replace_block_range', {
+      post_id: 1, start: 0, count: 1, blocks: [{ name: 'oldns/heading' }],
+    }, client as any);
+    assertHasFormattedWarning(result, 'WARNING');
+    assertHasFormattedWarning(result, 'oldns/heading');
+  });
+
+  it('no formatted_warnings when response has none', async () => {
+    client.replaceBlocksRange = vi.fn().mockResolvedValue({
+      success: true, removed: 1,
+      inserted: [{ index: 0, name: 'core/heading' }],
+      warnings: [],
+      before_revision_id: 1, revision_id: 2,
+    }) as any;
+    const result = await handleWriteTool('replace_block_range', {
+      post_id: 1, start: 0, count: 1, blocks: [{ name: 'core/heading' }],
+    }, client as any);
+    assertNoFormattedWarnings(result);
+  });
+});

package/src/__tests__/tools/write/rewrite_post_blocks.test.ts

@@ -29,6 +29,27 @@ describe('rewrite_post_blocks — validation', () => {
     ).rejects.toThrow('post_id');
   });
 
+  it('rejects a float post_id', async () => {
+    await expect(
+      handleWriteTool('rewrite_post_blocks', { post_id: 1.5, blocks: [{ name: 'core/paragraph' }] }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects a negative post_id', async () => {
+    await expect(
+      handleWriteTool('rewrite_post_blocks', { post_id: -1, blocks: [{ name: 'core/paragraph' }] }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects an overflow post_id', async () => {
+    await expect(
+      handleWriteTool('rewrite_post_blocks', {
+        post_id: Number.MAX_SAFE_INTEGER + 1,
+        blocks: [{ name: 'core/paragraph' }],
+      }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
   it('requires at least one block', async () => {
     await expect(
       handleWriteTool('rewrite_post_blocks', { post_id: 1 }, client as any)
@@ -108,6 +129,24 @@ describe('revert_to_revision — validation', () => {
     ).rejects.toThrow('post_id');
   });
 
+  it('rejects a float post_id', async () => {
+    await expect(
+      handleWriteTool('revert_to_revision', { post_id: 1.5, revision_id: 1 }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects a negative post_id', async () => {
+    await expect(
+      handleWriteTool('revert_to_revision', { post_id: -1, revision_id: 1 }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects an overflow post_id', async () => {
+    await expect(
+      handleWriteTool('revert_to_revision', { post_id: Number.MAX_SAFE_INTEGER + 1, revision_id: 1 }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
   it('requires revision_id', async () => {
     await expect(
       handleWriteTool('revert_to_revision', { post_id: 1 }, client as any)

package/src/__tests__/tools/write/update_block.test.ts

@@ -48,6 +48,22 @@ describe('update_block — validation', () => {
       .rejects.toThrow('post_id');
   });
 
+  it('rejects a float post_id', async () => {
+    await expect(handleWriteTool('update_block', { post_id: 1.5, flat_index: 0, attributes: {} }, client as any))
+      .rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects a negative post_id', async () => {
+    await expect(handleWriteTool('update_block', { post_id: -1, flat_index: 0, attributes: {} }, client as any))
+      .rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects an overflow post_id', async () => {
+    await expect(
+      handleWriteTool('update_block', { post_id: Number.MAX_SAFE_INTEGER + 1, flat_index: 0, attributes: {} }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
   it('requires flat_index OR ref (not neither)', async () => {
     await expect(handleWriteTool('update_block', { post_id: 1, attributes: {} }, client as any))
       .rejects.toThrow(/Provide either flat_index/);