@gravitykit/block-mcp 2.0.0-beta → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravitykit/block-mcp",
-  "version": "2.0.0-beta",
+  "version": "2.1.0",
   "description": "MCP server for WordPress block-level content management with preference-aware editing",
   "main": "dist/index.cjs",
   "bin": {
@@ -16,6 +16,8 @@
     "test": "vitest run",
     "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",
@@ -41,18 +43,21 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "axios": "^1.7.9"
+    "axios": "^1.16.0",
+    "form-data": "^4.0.1"
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.91.1",
+    "@playwright/test": "^1.49.0",
     "@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"
@@ -66,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/dual-storage.test.ts

@@ -49,7 +49,7 @@ describe.skipIf(skip)('dual-storage enforcement (integration)', () => {
     }
   });
 
-  it('update with only attributes on a dual-storage block returns 400 or 200 (requires scan)', async () => {
+  it('innerHTML-only update on a dual-storage block is rejected; attributes-only is allowed', async () => {
     if (!yoastInstalled || !dualBlockName) {
       console.log('[integration] No dual-storage block found (Yoast not installed or no dual blocks) — skipping');
       return;
@@ -78,46 +78,42 @@ describe.skipIf(skip)('dual-storage enforcement (integration)', () => {
       const blockIndex = inserted.inserted[0]?.index;
       expect(blockIndex).toBeGreaterThanOrEqual(0);
 
-      // Try to update with ONLY attributes — dual enforcement should reject it.
+      // The enforced direction (BLOCK-14): innerHTML ALONE desyncs the
+      // structured attributes (questions[] et al.) and must be rejected with
+      // dual_storage_requires_both. Attributes-only is allowed by design —
+      // the documented contract is "innerHTML-only is rejected".
       const credentials = Buffer.from(
         `${LIVE_ENV.user}:${LIVE_ENV.password}`
       ).toString('base64');
       const url = `${LIVE_ENV.url.replace(/\/+$/, '')}/wp-json/gk-block-api/v1/posts/${postId}/blocks/${blockIndex}`;
-
-      const response = await axios.patch(
-        url,
-        { attributes: faqAttributes },
-        {
+      const patch = (body: unknown) =>
+        axios.patch(url, body, {
           headers: {
             Authorization: `Basic ${credentials}`,
             'Content-Type': 'application/json',
           },
           timeout: 15_000,
           validateStatus: () => true,
-        }
-      );
+        });
 
-      if (response.status === 400) {
-        // Dual-storage enforcement is active — verify the error code.
-        const body = response.data as Record<string, unknown>;
-        expect(body.code).toBe('dual_storage_requires_both');
-        expect(body.message).toBeTruthy();
-      } else if (response.status === 200) {
-        // The plugin returned a 200 because the storage-mode scan classifying
-        // this block as `dual` had not been run on this site. Silently
-        // logging-and-continuing turns the test green even though the
-        // enforcement path was never exercised — the same outcome a real
-        // regression that broke enforcement would produce. Fail loudly so
-        // CI surfaces the missing precondition instead of papering over it.
+      const htmlOnly = await patch({ innerHTML: faqInnerHtml });
+      if (htmlOnly.status === 200) {
+        // A 200 here means the block is not classified dual on this site —
+        // the enforcement path was never exercised. Fail loudly so CI
+        // surfaces the missing precondition instead of papering over it.
         throw new Error(
           `[integration] dual-storage not enforced for ${dualBlockName} ` +
-            '— call scan_storage_modes to classify the block as dual, then re-run this suite. ' +
-            'The 200 response means the precondition for this test is not met, not that the test passed.'
+            '— call scan_storage_modes (or add the block to the dual-storage list), then re-run.'
         );
-      } else {
-        // Any other status is unexpected.
-        throw new Error(`Unexpected status ${response.status} from dual-storage update`);
       }
+      expect(htmlOnly.status).toBe(400);
+      const body = htmlOnly.data as Record<string, unknown>;
+      expect(body.code).toBe('dual_storage_requires_both');
+      expect(body.message).toBeTruthy();
+
+      // The permitted direction: attributes-only succeeds.
+      const attrsOnly = await patch({ attributes: faqAttributes });
+      expect(attrsOnly.status).toBe(200);
     });
   }, 45_000);
 

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__/integration/posts-terms-media.test.ts

@@ -0,0 +1,271 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { skipUnlessLive, makeLiveClient, withTestPost, LIVE_ENV } from './setup.js';
+import type { CreatePostRequest, UpdatePostRequest } from '../../types.js';
+
+/**
+ * Edge-case coverage for the post-lifecycle, terms, and media surfaces
+ * against a live WordPress — every accepted argument plus the guard rails
+ * (allow-list, status enum, mutual exclusion, trash gate, SSRF, MIME
+ * allow-list, filename hygiene).
+ */
+
+interface WpErr {
+  message?: string;
+  wpCode?: string;
+  wpStatus?: number;
+}
+
+async function grab(promise: Promise<unknown>): Promise<WpErr> {
+  try {
+    await promise;
+    return {};
+  } catch (e) {
+    return e as WpErr;
+  }
+}
+
+// 1x1 transparent PNG.
+const PNG_B64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+
+describe.skipIf(skipUnlessLive())('integration: create_post argument surface', () => {
+  it('content and blocks are mutually exclusive', async () => {
+    const client = makeLiveClient();
+    const err = await grab(
+      client.createPost({
+        title: `${LIVE_ENV.prefix} conflict`,
+        content: '<p>html</p>',
+        blocks: [{ name: 'core/paragraph', innerHTML: '<p>blocks</p>' }],
+      } as CreatePostRequest),
+    );
+    expect(err.message).toMatch(/mutually exclusive|content.*blocks/i);
+  });
+
+  it('invalid status is rejected', async () => {
+    const client = makeLiveClient();
+    const err = await grab(
+      client.createPost({
+        title: `${LIVE_ENV.prefix} bad status`,
+        status: 'banana',
+      } as unknown as CreatePostRequest),
+    );
+    expect(err.wpStatus).toBeGreaterThanOrEqual(400);
+  });
+
+  it('a post type outside the allow-list is rejected', async () => {
+    const client = makeLiveClient();
+    const err = await grab(
+      client.createPost({
+        title: `${LIVE_ENV.prefix} bad type`,
+        post_type: 'gk_definitely_not_allowed',
+      } as CreatePostRequest),
+    );
+    expect(err.wpStatus).toBeGreaterThanOrEqual(400);
+  });
+
+  it('slug + excerpt persist on create', async () => {
+    const client = makeLiveClient();
+    const slug = `edge-slug-${process.pid}`;
+    const created = await client.createPost({
+      title: `${LIVE_ENV.prefix} slugged`,
+      status: 'draft',
+      slug,
+      excerpt: 'EDGE-EXCERPT',
+      blocks: [{ name: 'core/paragraph', innerHTML: '<p>x</p>' }],
+    } as CreatePostRequest);
+    try {
+      const info = (await client.getPostInfo({ post_id: created.id })) as { slug?: string };
+      expect(info.slug).toBe(slug);
+      // Slug+post_type lookup resolves back to the same post.
+      const bySlug = (await client.getPostInfo({ slug, post_type: 'post' })) as { post_id?: number };
+      expect(bySlug.post_id).toBe(created.id);
+    } finally {
+      // Trash may be gated; draft test content is swept by title prefix.
+      await grab(client.updatePost(created.id, { status: 'trash' } as UpdatePostRequest));
+    }
+  });
+});
+
+describe.skipIf(skipUnlessLive())('integration: update_post argument surface', () => {
+  it('title / slug / excerpt update together', async () => {
+    const client = makeLiveClient();
+    await withTestPost(client, async (postId) => {
+      const res = await client.updatePost(postId, {
+        title: `${LIVE_ENV.prefix} retitled`,
+        slug: `edge-retitle-${process.pid}`,
+        excerpt: 'EDGE-NEW-EXCERPT',
+      });
+      expect(res.success).toBe(true);
+      const info = (await client.getPostInfo({ post_id: postId })) as {
+        title?: string;
+        slug?: string;
+      };
+      expect(info.title).toContain('retitled');
+      expect(info.slug).toBe(`edge-retitle-${process.pid}`);
+    });
+  });
+
+  it('status transition draft → publish → draft round-trips', async () => {
+    const client = makeLiveClient();
+    await withTestPost(client, async (postId) => {
+      const publish = await client.updatePost(postId, { status: 'publish' });
+      expect(publish.success).toBe(true);
+
+      const back = await client.updatePost(postId, { status: 'draft' });
+      expect(back.success).toBe(true);
+    });
+  });
+
+  it('trash combined with other fields is rejected (mixed payload or gate)', async () => {
+    const client = makeLiveClient();
+    await withTestPost(client, async (postId) => {
+      const err = await grab(
+        client.updatePost(postId, { status: 'trash', title: 'sneaky' } as UpdatePostRequest),
+      );
+      // Whichever guard fires first — the trash gate (when disabled) or the
+      // mixed-payload guard — the write must NOT go through silently.
+      expect(err.wpStatus).toBeGreaterThanOrEqual(400);
+      const info = (await client.getPostInfo({ post_id: postId })) as { title?: string };
+      expect(info.title).not.toBe('sneaky');
+    });
+  });
+});
+
+describe.skipIf(skipUnlessLive())('integration: list_terms argument surface', () => {
+  it('invalid taxonomy fails loudly', async () => {
+    const client = makeLiveClient();
+    const err = await grab(client.listTerms({ taxonomy: 'gk_no_such_tax' }));
+    expect(err.wpStatus).toBeGreaterThanOrEqual(400);
+  });
+
+  it('per_page is honored and capped', async () => {
+    const client = makeLiveClient();
+    const res = (await client.listTerms({ taxonomy: 'category', per_page: 1 })) as {
+      terms?: unknown[];
+    };
+    expect((res.terms ?? []).length).toBeLessThanOrEqual(1);
+
+    const err = await grab(client.listTerms({ taxonomy: 'category', per_page: 500 }));
+    // Either rejected outright or clamped — never an unbounded dump.
+    if (!err.wpStatus) {
+      const all = (await client.listTerms({ taxonomy: 'category', per_page: 500 })) as {
+        terms?: unknown[];
+      };
+      expect((all.terms ?? []).length).toBeLessThanOrEqual(200);
+    }
+  });
+
+  it('orderby/order + search + slug filters apply', async () => {
+    const client = makeLiveClient();
+    const res = (await client.listTerms({
+      taxonomy: 'category',
+      orderby: 'name',
+      order: 'desc',
+      per_page: 5,
+    } as never)) as { terms?: Array<{ name: string; slug: string }> };
+    const names = (res.terms ?? []).map((t) => t.name.toLowerCase());
+    const sorted = [...names].sort().reverse();
+    expect(names).toEqual(sorted);
+
+    if (res.terms?.length) {
+      const target = res.terms[0];
+      const bySlug = (await client.listTerms({ taxonomy: 'category', slug: target.slug } as never)) as {
+        terms?: Array<{ slug: string }>;
+      };
+      expect(bySlug.terms?.every((t) => t.slug === target.slug)).toBe(true);
+    }
+  });
+});
+
+describe.skipIf(skipUnlessLive())('integration: upload_media guard rails', () => {
+  it('SSRF: url mode pointing at a private/reserved address is blocked', async () => {
+    const client = makeLiveClient();
+    for (const url of ['http://127.0.0.1:9/x.png', 'http://169.254.169.254/latest/meta-data.png']) {
+      const err = await grab(client.uploadMedia({ url, title: `${LIVE_ENV.prefix} ssrf` }));
+      expect(err.wpStatus, url).toBeGreaterThanOrEqual(400);
+      expect(`${err.wpCode}`, url).toMatch(/invalid_url|url_fetch_failed/);
+    }
+  });
+
+  it('disallowed MIME (a .php "image") is rejected', async () => {
+    const client = makeLiveClient();
+    const err = await grab(
+      client.uploadMedia({
+        data_base64: PNG_B64,
+        filename: 'evil.php',
+        title: `${LIVE_ENV.prefix} mime`,
+      }),
+    );
+    expect(err.wpStatus).toBeGreaterThanOrEqual(400);
+    expect(`${err.wpCode}`).toMatch(/disallowed_mime|invalid_filename|sideload_failed/);
+  });
+
+  it('path traversal in filename does not escape the uploads dir', async () => {
+    const client = makeLiveClient();
+    const result = await grab(
+      client.uploadMedia({
+        data_base64: PNG_B64,
+        filename: '../../traversal.png',
+        title: `${LIVE_ENV.prefix} traversal`,
+      }),
+    );
+    if (!result.wpStatus) {
+      // Accepted → the stored file must be sanitized to a basename.
+      const ok = (await client.uploadMedia({
+        data_base64: PNG_B64,
+        filename: '../../traversal.png',
+        title: `${LIVE_ENV.prefix} traversal2`,
+      })) as { source_url?: string; url?: string };
+      const storedUrl = String(ok.source_url ?? ok.url);
+      expect(storedUrl).not.toContain('..');
+      expect(storedUrl).toMatch(/traversal[^/]*\.png$/);
+    } else {
+      expect(`${result.wpCode}`).toMatch(/invalid_filename|disallowed_mime/);
+    }
+  });
+
+  it('invalid base64 payload fails loudly', async () => {
+    const client = makeLiveClient();
+    const err = await grab(
+      client.uploadMedia({
+        data_base64: '!!!not-base64!!!',
+        filename: 'bad.png',
+        title: `${LIVE_ENV.prefix} badb64`,
+      }),
+    );
+    expect(err.wpStatus).toBeGreaterThanOrEqual(400);
+  });
+
+  it('path mode with a nonexistent local file throws client-side (nothing sent)', async () => {
+    const client = makeLiveClient();
+    const err = await grab(
+      client.uploadMedia({ path: path.join(os.tmpdir(), 'gk-definitely-missing.png') }),
+    );
+    expect(err.message).toMatch(/ENOENT|no such file/i);
+  });
+
+  it('metadata args (title, alt_text, caption, description, post_id) ride along', async () => {
+    const client = makeLiveClient();
+    await withTestPost(client, async (postId) => {
+      const tmp = path.join(os.tmpdir(), `gk-edge-meta-${process.pid}.png`);
+      fs.writeFileSync(tmp, Buffer.from(PNG_B64, 'base64'));
+      try {
+        const res = (await client.uploadMedia({
+          path: tmp,
+          title: `${LIVE_ENV.prefix} meta upload`,
+          alt_text: 'EDGE-ALT',
+          caption: 'EDGE-CAPTION',
+          description: 'EDGE-DESC',
+          post_id: postId,
+        })) as { id?: number; source_url?: string; url?: string };
+        expect(res.id).toBeGreaterThan(0);
+        expect(String(res.source_url ?? res.url)).toMatch(/\.png$/);
+      } finally {
+        fs.rmSync(tmp, { force: true });
+      }
+    });
+  });
+});