@gravitykit/block-mcp 2.0.0-beta

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@gravitykit/block-mcp",
+  "version": "2.0.0-beta",
+  "description": "MCP server for WordPress block-level content management with preference-aware editing",
+  "main": "dist/index.cjs",
+  "bin": {
+    "block-mcp": "dist/index.cjs"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist/index.cjs --external:supports-color --external:has-flag",
+    "postbuild": "bash scripts/copy-server-bundle.sh",
+    "start": "node dist/index.cjs",
+    "dev": "esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist/index.cjs --watch --external:supports-color --external:has-flag",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.cjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "eval": "tsx tests/evals/lib/runner.ts",
+    "eval:fixture-refresh": "tsx tests/evals/scripts/fetch-fixture.ts",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "mcp",
+    "wordpress",
+    "blocks",
+    "gutenberg",
+    "content-management",
+    "gravitykit"
+  ],
+  "author": "GravityKit",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GravityKit/block-mcp.git"
+  },
+  "homepage": "https://github.com/GravityKit/block-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/GravityKit/block-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.7.9"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.91.1",
+    "@shikijs/engine-javascript": "^4.0.2",
+    "@shikijs/langs": "^4.0.2",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.27.3",
+    "shiki": "^4.0.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "LICENSE",
+    "README.md",
+    ".env.example"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/__tests__/fixtures/block-trees.ts

@@ -0,0 +1,199 @@
+/**
+ * Canonical block tree fixtures.
+ *
+ * Plain data objects only — no logic, no imports from src.
+ * Shape matches the Block interface from src/types.ts.
+ * Import these in any test that needs realistic block data.
+ */
+
+// ---------------------------------------------------------------------------
+// Leaf block types
+// ---------------------------------------------------------------------------
+
+export const paragraphBlock = {
+  index: 0,
+  top_level_counter: 0,
+  path: [0],
+  ref: 'blk_para0001',
+  name: 'core/paragraph',
+  attributes: { content: 'Hello world.' },
+  innerHTML: '<p>Hello world.</p>',
+  storage_mode: 'static' as const,
+};
+
+export const headingBlock = {
+  index: 1,
+  top_level_counter: 1,
+  path: [1],
+  ref: 'blk_head0001',
+  name: 'core/heading',
+  attributes: { level: 2, content: 'Section Title' },
+  innerHTML: '<h2 class="wp-block-heading">Section Title</h2>',
+  storage_mode: 'static' as const,
+};
+
+export const imageBlock = {
+  index: 2,
+  top_level_counter: 2,
+  path: [2],
+  ref: 'blk_img00001',
+  name: 'core/image',
+  attributes: { url: 'https://example.test/wp-content/uploads/photo.jpg', alt: 'A photo' },
+  innerHTML: '<figure class="wp-block-image"><img src="https://example.test/wp-content/uploads/photo.jpg" alt="A photo"/></figure>',
+  storage_mode: 'static' as const,
+};
+
+export const listBlock = {
+  index: 3,
+  top_level_counter: 3,
+  path: [3],
+  ref: 'blk_list0001',
+  name: 'core/list',
+  attributes: { ordered: false },
+  innerHTML: '<ul><li>Item A</li><li>Item B</li></ul>',
+  storage_mode: 'static' as const,
+};
+
+// ---------------------------------------------------------------------------
+// Dynamic block (server-rendered)
+// ---------------------------------------------------------------------------
+
+export const queryLoopBlock = {
+  index: 4,
+  top_level_counter: 4,
+  path: [4],
+  ref: 'blk_qlop0001',
+  name: 'core/query',
+  attributes: { queryId: 1, query: { perPage: 10, postType: 'post' } },
+  innerHTML: '',
+  dynamic: true,
+  storage_mode: 'dynamic' as const,
+};
+
+// ---------------------------------------------------------------------------
+// Legacy / non-preferred blocks (server attaches preference field)
+// ---------------------------------------------------------------------------
+
+export const legacyHeadingBlock = {
+  index: 5,
+  top_level_counter: 5,
+  path: [5],
+  name: 'ugb/heading',
+  attributes: { text: 'Old Heading' },
+  innerHTML: '<div class="ugb-heading"><h2>Old Heading</h2></div>',
+  preference: {
+    tier: 'legacy' as const,
+    suggested_replacement: 'core/heading',
+  },
+};
+
+export const avoidBlock = {
+  index: 6,
+  top_level_counter: 6,
+  path: [6],
+  name: 'stackable/heading',
+  attributes: { text: 'Stack Heading' },
+  preference: {
+    tier: 'avoid' as const,
+    suggested_replacement: 'core/heading',
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Container blocks (with innerBlocks)
+// ---------------------------------------------------------------------------
+
+export const groupBlock = {
+  index: 7,
+  top_level_counter: 7,
+  path: [7],
+  ref: 'blk_grp00001',
+  name: 'core/group',
+  attributes: { tagName: 'section' },
+  innerHTML: '<section class="wp-block-group"></section>',
+  storage_mode: 'static' as const,
+  innerBlocks: [
+    {
+      index: 8,
+      path: [7, 0],
+      ref: 'blk_grpch001',
+      name: 'core/heading',
+      attributes: { level: 3, content: 'Inside Group' },
+      innerHTML: '<h3>Inside Group</h3>',
+    },
+    {
+      index: 9,
+      path: [7, 1],
+      ref: 'blk_grpch002',
+      name: 'core/paragraph',
+      attributes: { content: 'Group paragraph.' },
+      innerHTML: '<p>Group paragraph.</p>',
+    },
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// Dual-storage block (yoast/faq-block example)
+// ---------------------------------------------------------------------------
+
+export const dualStorageBlock = {
+  index: 10,
+  top_level_counter: 8,
+  path: [10],
+  ref: 'blk_dual0001',
+  name: 'yoast/faq-block',
+  attributes: {
+    questions: [
+      { id: 'faq-q1', question: ['What is GravityKit?'], answer: ['A plugin suite.'] },
+    ],
+  },
+  innerHTML: '<div class="schema-faq"><div class="schema-faq-section"><strong>What is GravityKit?</strong><p>A plugin suite.</p></div></div>',
+  storage_mode: 'dual' as const,
+};
+
+// ---------------------------------------------------------------------------
+// Flat page: a realistic mix for get_page_blocks responses
+// ---------------------------------------------------------------------------
+
+export const mixedPageBlocks = [
+  paragraphBlock,
+  headingBlock,
+  imageBlock,
+  groupBlock,
+];
+
+export const legacyPageBlocks = [
+  paragraphBlock,
+  legacyHeadingBlock,
+  avoidBlock,
+];
+
+// ---------------------------------------------------------------------------
+// SavedBlock snapshots (echoed by write operations)
+// ---------------------------------------------------------------------------
+
+export const savedParagraph = {
+  flat_index: 0,
+  block_name: 'core/paragraph',
+  attributes: { content: 'Hello world.' },
+  inner_html: '<p>Hello world.</p>',
+  is_dynamic: false,
+  ref: 'blk_para0001',
+};
+
+export const savedHeading = {
+  flat_index: 1,
+  block_name: 'core/heading',
+  attributes: { level: 2, content: 'Section Title' },
+  inner_html: '<h2 class="wp-block-heading">Section Title</h2>',
+  is_dynamic: false,
+  ref: 'blk_head0001',
+};
+
+export const savedDynamic = {
+  flat_index: 4,
+  block_name: 'core/query',
+  attributes: { queryId: 1 },
+  inner_html: '',
+  is_dynamic: true,
+};

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

@@ -0,0 +1,115 @@
+/**
+ * Error envelope fixtures for every documented error code.
+ *
+ * Each entry maps a WP REST error code to a realistic data payload the
+ * plugin might return in the `data` field of the error envelope.
+ *
+ * Shape: { code: string, status: number, data: Record<string,unknown> | null }
+ *
+ * Used primarily in the error-translator coverage matrix tests.
+ */
+
+export interface ErrorEnvelope {
+  code: string;
+  /** HTTP status the plugin returns for this code */
+  httpStatus: number;
+  /** Content of the `data` property in the WP error envelope */
+  data: Record<string, unknown> | null;
+}
+
+export const ERROR_ENVELOPES: ErrorEnvelope[] = [
+  // ── Auth & permissions (403) ────────────────────────────────────────────
+  { code: 'rest_forbidden',            httpStatus: 403, data: null },
+  { code: 'rest_cannot_edit',          httpStatus: 403, data: { post_id: 42 } },
+  { code: 'rest_cannot_create',        httpStatus: 403, data: null },
+  { code: 'rest_cannot_publish',       httpStatus: 403, data: null },
+  { code: 'rest_cannot_upload',        httpStatus: 403, data: null },
+  { code: 'rest_cannot_assign_author', httpStatus: 403, data: null },
+  { code: 'uploads_disabled',          httpStatus: 403, data: null },
+
+  // ── Auth (401) ──────────────────────────────────────────────────────────
+  { code: 'rest_cookie_invalid_nonce',     httpStatus: 401, data: null },
+  { code: 'rest_authentication_required',  httpStatus: 401, data: null },
+
+  // ── Routing (404) ───────────────────────────────────────────────────────
+  { code: 'rest_no_route', httpStatus: 404, data: null },
+
+  // ── Not found (404) ────────────────────────────────────────────────────
+  { code: 'post_not_found',      httpStatus: 404, data: { post_id: 42 } },
+  { code: 'block_not_found',     httpStatus: 404, data: { post_id: 42 } },
+  { code: 'ref_stale',           httpStatus: 404, data: { ref: 'blk_gone0001', post_id: 42 } },
+  { code: 'pattern_not_found',   httpStatus: 404, data: null },
+  { code: 'revision_not_found',  httpStatus: 404, data: null },
+  { 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 },
+
+  // ── Validation (400) ────────────────────────────────────────────────────
+  { code: 'legacy_block',              httpStatus: 400, data: { block: 'ugb/text', suggested_replacement: 'core/paragraph' } },
+  { 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: 'invalid_path',              httpStatus: 400, data: { path: [0, 99] } },
+  { code: 'invalid_ref',               httpStatus: 400, data: null },
+  { 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 },
+  { code: 'missing_attributes',        httpStatus: 400, data: null },
+  { code: 'invalid_post_type',         httpStatus: 400, data: null },
+  { code: 'invalid_status',            httpStatus: 400, data: null },
+  { code: 'mixed_trash_payload',       httpStatus: 400, data: null },
+  { code: 'invalid_if_match',          httpStatus: 400, data: null },
+  { code: 'no_inner_blocks',           httpStatus: 400, data: null },
+  { code: 'multiple_inputs',           httpStatus: 400, data: null },
+  { code: 'disallowed_mime',           httpStatus: 400, data: null },
+  { code: 'file_too_large',            httpStatus: 400, data: null },
+  { code: 'invalid_url',               httpStatus: 400, data: null },
+  { code: 'empty_pattern',             httpStatus: 400, data: null },
+
+  // ── Rate limit (429) ────────────────────────────────────────────────────
+  { code: 'rate_limit_exceeded', httpStatus: 429, data: { post_id: 42 } },
+  { code: 'scan_rate_limited',   httpStatus: 429, data: null },
+
+  // ── Upstream (502) ──────────────────────────────────────────────────────
+  { code: 'url_fetch_failed', httpStatus: 502, data: null },
+
+  // ── Server error (500) ──────────────────────────────────────────────────
+  { code: 'internal_error',       httpStatus: 500, data: null },
+  { code: 'wp_insert_post_failed', httpStatus: 500, data: null },
+  { code: 'sideload_failed',      httpStatus: 500, data: null },
+  { code: 'trash_failed',         httpStatus: 500, data: null },
+];
+
+/**
+ * Subset: codes that translateWpError() has an explicit translation for.
+ * Keep in sync with the switch in src/error-translator.ts.
+ */
+export const TRANSLATED_CODES = new Set([
+  'rest_no_route',
+  'rest_forbidden',
+  'rest_cannot_edit',
+  'rest_cannot_create',
+  'rest_cookie_invalid_nonce',
+  'rest_authentication_required',
+  'rest_post_invalid_id',
+  'invalid_post_id',
+  'not_found',
+  'gk_block_api_invalid_ref',
+  'invalid_ref',
+  'path_not_found',
+  'invalid_path',
+  'path_out_of_bounds',
+  'legacy_block',
+  'static_markup_stale_risk',
+  'rate_limit_exceeded',
+  'mixed_trash_payload',
+  'invalid_post_type',
+  'invalid_status',
+  'invalid_url',
+  'disallowed_mime',
+]);

package/src/__tests__/fixtures/rest-responses.ts

@@ -0,0 +1,280 @@
+/**
+ * Canonical REST response envelopes.
+ *
+ * Plain data — shapes match the TypeScript interfaces in src/types.ts.
+ * Use these as mock return values in tool-layer and client-layer tests.
+ */
+
+import {
+  savedParagraph,
+  savedHeading,
+  mixedPageBlocks,
+} from './block-trees.js';
+
+// ---------------------------------------------------------------------------
+// Discovery responses
+// ---------------------------------------------------------------------------
+
+export const blockTypesResponse = {
+  block_types: [
+    {
+      name: 'core/paragraph',
+      title: 'Paragraph',
+      category: 'text',
+      description: 'Start with the basic building block.',
+      preference: { score: 90, tier: 'preferred' as const },
+      storage_mode: 'static' as const,
+    },
+    {
+      name: 'core/heading',
+      title: 'Heading',
+      category: 'text',
+      preference: { score: 90, tier: 'preferred' as const },
+      storage_mode: 'static' as const,
+    },
+    {
+      name: 'stackable/heading',
+      title: 'Stackable Heading',
+      category: 'text',
+      preference: { score: 10, tier: 'avoid' as const, namespace_policy: 'migrate_away' },
+    },
+    {
+      name: 'ugb/text',
+      title: 'UGB Text',
+      category: 'text',
+      preference: { score: 0, tier: 'legacy' as const, namespace_policy: 'never_use' },
+    },
+  ],
+};
+
+export const patternsResponse = {
+  patterns: [
+    {
+      id: 1,
+      name: 'Hero Section',
+      type: 'synced' as const,
+      created: '2026-01-01',
+      modified: '2026-04-15',
+      reference_count: 12,
+      preference: { score: 85, tier: 'recommended' as const, reasons: ['recent', 'widely-used'] },
+      contains_blocks: ['core/heading', 'core/paragraph', 'core/image'],
+      has_legacy_blocks: false,
+    },
+    {
+      id: 2,
+      name: 'Old Legacy Pattern',
+      type: 'synced' as const,
+      created: '2023-01-01',
+      modified: '2023-06-01',
+      reference_count: 2,
+      preference: { score: -80, tier: 'legacy' as const, reasons: ['has_legacy_blocks'] },
+      contains_blocks: ['ugb/text', 'ugb/heading'],
+      has_legacy_blocks: true,
+      legacy_blocks: ['ugb/text', 'ugb/heading'],
+    },
+  ],
+};
+
+export const siteUsageResponse = {
+  block_usage: {
+    'core/paragraph': { count: 450, post_count: 120 },
+    'core/heading': { count: 200, post_count: 95 },
+    'stackable/heading': { count: 30, post_count: 15 },
+  },
+  namespace_totals: { core: 650, stackable: 30 },
+  pattern_references: {
+    '1': { name: 'Hero Section', refs: 12 },
+  },
+  legacy_patterns: [],
+};
+
+export const resolveUrlResponse = {
+  post_id: 532208,
+  post_type: 'download',
+  title: 'GravityEdit',
+  status: 'publish',
+  slug: 'gravityedit',
+  edit_url: 'https://example.test/wp-admin/post.php?post=532208&action=edit',
+};
+
+// ---------------------------------------------------------------------------
+// Read responses
+// ---------------------------------------------------------------------------
+
+export const pageBlocksResponse = {
+  blocks: mixedPageBlocks,
+  summary: {
+    total_blocks: 4,
+    top_level_blocks: 4,
+    block_types: { 'core/paragraph': 1, 'core/heading': 1, 'core/image': 1, 'core/group': 1 },
+    sections: [],
+    headings: [{ path: [1], level: 2, text: 'Section Title' }],
+    legacy_blocks: [],
+    max_path_depth: 2,
+  },
+};
+
+export const getBlockResponse = {
+  success: true,
+  saved: savedParagraph,
+};
+
+// ---------------------------------------------------------------------------
+// Write responses
+// ---------------------------------------------------------------------------
+
+export const updateBlockResponse = {
+  success: true,
+  block: {
+    index: 1,
+    name: 'core/heading',
+    attributes: { level: 3, content: 'Updated' },
+    ref: 'blk_head0001',
+  },
+  saved: savedHeading,
+  before_revision_id: 100,
+  revision_id: 101,
+};
+
+export const insertBlocksResponse = {
+  success: true,
+  inserted: [
+    { index: 5, top_level_counter: 5, path: [5], ref: 'blk_new00001', name: 'core/paragraph' },
+  ],
+  warnings: [],
+  before_revision_id: 100,
+  revision_id: 101,
+};
+
+export const insertBlocksWithWarningsResponse = {
+  success: true,
+  inserted: [{ index: 5, name: 'stackable/heading' }],
+  warnings: [
+    { block: 'stackable/heading', message: 'Block 5: stackable/heading (AVOID)', suggested_replacement: 'core/heading' },
+  ],
+  before_revision_id: 100,
+  revision_id: 101,
+};
+
+export const deleteBlockResponse = {
+  success: true,
+  removed: 1,
+  before_revision_id: 100,
+  revision_id: 101,
+};
+
+export const batchUpdateResponse = {
+  success: true,
+  count: 2,
+  results: [
+    {
+      batch_index: 0,
+      block: { index: 0, name: 'core/paragraph', attributes: { content: 'Updated 1' }, ref: 'blk_para0001' },
+    },
+    {
+      batch_index: 1,
+      block: { index: 1, name: 'core/heading', attributes: { level: 3 }, ref: 'blk_head0001' },
+    },
+  ],
+  before_revision_id: 100,
+  revision_id: 101,
+};
+
+export const replaceRangeResponse = {
+  success: true,
+  removed: 2,
+  inserted: [
+    { index: 1, name: 'core/paragraph', ref: 'blk_rpl00001' },
+  ],
+  warnings: [],
+  before_revision_id: 100,
+  revision_id: 101,
+};
+
+// ---------------------------------------------------------------------------
+// Mutation responses
+// ---------------------------------------------------------------------------
+
+export const mutationUpdateAttrsResponse = {
+  success: true,
+  op: 'update-attrs' as const,
+  path: [1],
+  block: {
+    name: 'core/heading',
+    attributes: { level: 3 },
+  },
+  warnings: [],
+  before_revision_id: 100,
+  revision_id: 101,
+};
+
+export const mutationWithStaticWarning = {
+  success: true,
+  op: 'update-attrs' as const,
+  path: [0],
+  block: { name: 'core/paragraph', attributes: { content: 'New' } },
+  warnings: [
+    {
+      type: 'static_markup_stale_risk' as const,
+      block_name: 'core/paragraph',
+      changed_attrs: ['content'],
+      message: 'Updating content on a static block without new innerHTML may leave markup stale.',
+    },
+  ],
+  before_revision_id: 100,
+  revision_id: 101,
+};
+
+// ---------------------------------------------------------------------------
+// Pattern responses
+// ---------------------------------------------------------------------------
+
+export const patternInsertResponse = {
+  success: true,
+  inserted: { index: 5, name: 'core/block', attributes: { ref: 1 }, synced: true },
+  pattern_name: 'Hero Section',
+  synced: true,
+  before_revision_id: 100,
+  revision_id: 101,
+};
+
+// ---------------------------------------------------------------------------
+// Post lifecycle responses
+// ---------------------------------------------------------------------------
+
+export const createPostResponse = {
+  success: true,
+  id: 9999,
+  post_type: 'post',
+  status: 'draft',
+  title: 'New Post',
+  slug: 'new-post',
+  permalink: 'https://example.test/new-post/',
+  edit_link: 'https://example.test/wp-admin/post.php?post=9999&action=edit',
+  before_revision_id: null,
+  revision_id: null,
+  warnings: [],
+};
+
+export const updatePostResponse = {
+  ...createPostResponse,
+  status: 'publish',
+  transitioned_to_publish: true,
+};
+
+// ---------------------------------------------------------------------------
+// Yoast responses
+// ---------------------------------------------------------------------------
+
+export const yoastSEOResponse = {
+  post_id: 9999,
+  title: 'SEO Title',
+  description: 'Meta description.',
+  canonical: '',
+  focus_keyword: 'gravitykit',
+  noindex: null,
+  nofollow: false,
+  seo_score: 78,
+  readability_score: 65,
+  inclusive_language_score: null,
+};