@gravitykit/block-mcp 2.0.0-beta

package/src/__tests__/integration/ref-stability.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Integration: ref stability across sibling mutations
+ *
+ * Verifies that stable gk_refs survive the two most disruptive sibling
+ * operations:
+ *   1. Inserting a new block BEFORE a known ref — ref must still resolve.
+ *   2. Deleting a block ABOVE another known ref — ref must still resolve.
+ *
+ * These are the exact scenarios that motivate refs over flat indices.
+ *
+ * If the live plugin build does not assign refs (older versions), these tests
+ * fall back to verifying the simpler property that flat indices shift correctly
+ * (the observable behaviour that refs are designed to hide).
+ *
+ * Batch-update tests require the /batch-update route — they skip gracefully
+ * when it is absent.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { makeLiveClient, skipUnlessLive, withTestPost, hasRoute } from './setup.js';
+
+const skip = skipUnlessLive();
+
+describe.skipIf(skip)('ref stability across sibling mutations (integration)', () => {
+  it('block at a given position is addressable after a block is inserted before it', async () => {
+    const client = makeLiveClient();
+
+    await withTestPost(client, async (postId) => {
+      // Read initial state: heading (0) + paragraph (1)
+      const initial = await client.getPageBlocks(postId);
+      const para = initial.blocks.find((b) => b.name === 'core/paragraph');
+      expect(para).toBeDefined();
+      const paraIndexBefore = para!.index;
+      const paraRef = para!.ref; // undefined on older plugin builds
+
+      // Insert a new block after the heading (before the paragraph).
+      const heading = initial.blocks.find((b) => b.name === 'core/heading');
+      expect(heading).toBeDefined();
+
+      const insertData = heading!.ref
+        ? { after_ref: heading!.ref }
+        : { after: heading!.top_level_counter ?? heading!.index };
+
+      await client.insertBlocks(postId, {
+        ...insertData,
+        blocks: [
+          {
+            name: 'core/paragraph',
+            attributes: { content: 'Inserted between heading and paragraph.' },
+            innerHTML: '<p>Inserted between heading and paragraph.</p>',
+          },
+        ],
+      });
+
+      // Re-read and confirm the original paragraph has shifted.
+      const after = await client.getPageBlocks(postId);
+
+      if (paraRef) {
+        // Ref-capable plugin: find by ref and verify the index shifted.
+        const paraAfter = after.blocks.find((b) => b.ref === paraRef);
+        expect(paraAfter).toBeDefined();
+        expect(paraAfter!.index).toBeGreaterThan(paraIndexBefore);
+
+        // Confirm the ref is still directly resolvable via getBlock.
+        const singleBlockAvailable = await hasRoute('/block$');
+        if (singleBlockAvailable) {
+          const single = await client.getBlock(postId, { ref: paraRef });
+          expect(single.success).toBe(true);
+          expect(single.saved.ref).toBe(paraRef);
+        }
+      } else {
+        // Older plugin without refs: verify there are now 3 blocks (heading +
+        // inserted + original paragraph) and the paragraph content is still
+        // present at a higher flat index.
+        const nonHeadingParas = after.blocks.filter((b) => b.name === 'core/paragraph');
+        expect(nonHeadingParas.length).toBeGreaterThanOrEqual(2);
+        // One of them must still have the original content.
+        const original = nonHeadingParas.find(
+          (b) => (b.attributes.content as string | undefined)?.includes('Integration test paragraph')
+        );
+        expect(original).toBeDefined();
+        // Its index must be higher than the inserted block (inserted block took
+        // the position right after the heading).
+        const inserted = nonHeadingParas.find(
+          (b) => (b.attributes.content as string | undefined)?.includes('Inserted between')
+        );
+        expect(inserted).toBeDefined();
+        expect(original!.index).toBeGreaterThan(inserted!.index);
+      }
+    });
+  }, 45_000);
+
+  it('block at a given position survives deletion of a block above it', async () => {
+    const client = makeLiveClient();
+
+    await withTestPost(client, async (postId) => {
+      // Initial: heading (0) + paragraph (1).
+      const initial = await client.getPageBlocks(postId);
+      const heading = initial.blocks.find((b) => b.name === 'core/heading');
+      const para = initial.blocks.find((b) => b.name === 'core/paragraph');
+      expect(heading).toBeDefined();
+      expect(para).toBeDefined();
+      const paraRef = para!.ref;
+
+      // Delete the heading.
+      await client.deleteBlock(postId, heading!.index);
+
+      // After deletion, the paragraph should be the first block.
+      const after = await client.getPageBlocks(postId);
+
+      if (paraRef) {
+        const paraAfter = after.blocks.find((b) => b.ref === paraRef);
+        expect(paraAfter).toBeDefined();
+        // Flat index must be lower (heading is gone).
+        expect(paraAfter!.index).toBeLessThan(para!.index);
+
+        const singleBlockAvailable = await hasRoute('/block$');
+        if (singleBlockAvailable) {
+          const single = await client.getBlock(postId, { ref: paraRef });
+          expect(single.success).toBe(true);
+          expect(single.saved.ref).toBe(paraRef);
+        }
+      } else {
+        // Older plugin: heading must be gone, paragraph still present.
+        const headingAfter = after.blocks.find((b) => b.name === 'core/heading');
+        expect(headingAfter).toBeUndefined();
+        const paraAfter = after.blocks.find((b) => b.name === 'core/paragraph');
+        expect(paraAfter).toBeDefined();
+      }
+    });
+  }, 45_000);
+
+  it('batch update applies two writes in a single revision', async () => {
+    const batchRouteExists = await hasRoute('batch-update');
+    if (!batchRouteExists) {
+      console.log('[integration] batch-update route not present — skipping batch test');
+      return;
+    }
+
+    const client = makeLiveClient();
+
+    await withTestPost(client, async (postId) => {
+      const initial = await client.getPageBlocks(postId);
+      const heading = initial.blocks.find((b) => b.name === 'core/heading');
+      const para = initial.blocks.find((b) => b.name === 'core/paragraph');
+      expect(heading?.ref).toBeDefined();
+      expect(para?.ref).toBeDefined();
+
+      const batchResult = await client.updateBlocksBatch(postId, [
+        {
+          ref: heading!.ref,
+          attributes: { content: 'Batch heading', level: 2 },
+          innerHTML: '<h2 class="wp-block-heading">Batch heading</h2>',
+        },
+        {
+          ref: para!.ref,
+          attributes: { content: 'Batch paragraph.' },
+          innerHTML: '<p>Batch paragraph.</p>',
+        },
+      ], { verbose: true });
+
+      expect(batchResult.success).toBe(true);
+      expect(batchResult.count).toBe(2);
+      // ONE revision for both changes.
+      expect(batchResult.revision_id).toBeGreaterThan(0);
+
+      // Verify on disk.
+      const after = await client.getPageBlocks(postId);
+      const h = after.blocks.find((b) => b.ref === heading!.ref);
+      const p = after.blocks.find((b) => b.ref === para!.ref);
+      expect(h?.attributes.content).toBe('Batch heading');
+      expect(p?.attributes.content).toBe('Batch paragraph.');
+    });
+  }, 45_000);
+});

package/src/__tests__/integration/setup.ts

@@ -0,0 +1,201 @@
+/**
+ * Integration test setup helpers.
+ *
+ * Everything in this file is tree-shaken at unit-test time — nothing here
+ * imports from the test-runner directly, so it is safe to import in any
+ * integration test file even before `skipUnlessLive()` gates the describe
+ * block.
+ *
+ * Required env vars (all absent → every integration test skips cleanly):
+ *   WORDPRESS_URL           — e.g. http://localhost:7701
+ *   WORDPRESS_USER          — e.g. admin
+ *   WORDPRESS_APP_PASSWORD  — Application Password (spaces OK)
+ *
+ * Optional:
+ *   INTEGRATION_POST_TITLE_PREFIX  — defaults to "[integration-test]"
+ *     Used to namespace throwaway posts for cleanup safety.
+ */
+
+import { WordPressBlockClient } from '../../client.js';
+import type { BlockMCPConfig } from '../../types.js';
+import axios from 'axios';
+
+// ── Environment probe ──────────────────────────────────────────────────────
+
+export const LIVE_ENV = {
+  url: process.env.WORDPRESS_URL ?? '',
+  user: process.env.WORDPRESS_USER ?? '',
+  password: process.env.WORDPRESS_APP_PASSWORD ?? '',
+  prefix: process.env.INTEGRATION_POST_TITLE_PREFIX ?? '[integration-test]',
+};
+
+/** True when all required env vars are present. */
+export const isLive: boolean =
+  Boolean(LIVE_ENV.url) && Boolean(LIVE_ENV.user) && Boolean(LIVE_ENV.password);
+
+/**
+ * Returns the boolean skip flag for `describe.skipIf(skip)(...)`.
+ *
+ * Usage in every integration test file:
+ *
+ *   const skip = skipUnlessLive();
+ *   describe.skipIf(skip)('my suite', () => { ... });
+ */
+export function skipUnlessLive(): boolean {
+  return !isLive;
+}
+
+// ── Plugin capability detection ───────────────────────────────────────────
+
+/**
+ * Cached set of route prefixes registered on the live plugin.
+ * Populated lazily on first call to `getRegisteredRoutes()`.
+ */
+let _routeCache: string[] | null = null;
+
+/**
+ * Fetch the route list from the live WP instance (cached for the process).
+ * Returns an empty array when the site is unreachable.
+ */
+export async function getRegisteredRoutes(): Promise<string[]> {
+  if (_routeCache !== null) return _routeCache;
+  if (!isLive) return (_routeCache = []);
+
+  try {
+    const creds = Buffer.from(`${LIVE_ENV.user}:${LIVE_ENV.password}`).toString('base64');
+    const base = LIVE_ENV.url.replace(/\/+$/, '');
+    const resp = await axios.get(`${base}/wp-json/gk-block-api/v1`, {
+      headers: { Authorization: `Basic ${creds}` },
+      timeout: 8000,
+    });
+    _routeCache = Object.keys((resp.data as { routes?: Record<string, unknown> }).routes ?? {});
+  } catch {
+    _routeCache = [];
+  }
+  return _routeCache;
+}
+
+/**
+ * True when the live plugin has a specific route.
+ * `pattern` is treated as a substring when it's a plain string, or
+ * as a regex when it starts with `/`.  Pass a regex string like `'/block$'`
+ * to avoid false positives where 'block' matches 'blocks'.
+ */
+export async function hasRoute(pattern: string): Promise<boolean> {
+  const routes = await getRegisteredRoutes();
+  if (pattern.startsWith('/') && pattern.endsWith('$')) {
+    // Treat as a regex anchored at the end of the route segment.
+    const re = new RegExp(pattern.slice(1)); // remove leading /
+    return routes.some((r) => re.test(r));
+  }
+  return routes.some((r) => r.includes(pattern));
+}
+
+// ── Client factory ─────────────────────────────────────────────────────────
+
+/**
+ * Build a real WordPressBlockClient pointed at the live instance.
+ * Throws (and the test file will error out) if called without env vars — but
+ * callers should always guard with `describe.skipIf(skipUnlessLive())` so
+ * this never executes in offline runs.
+ */
+export function makeLiveClient(): WordPressBlockClient {
+  if (!isLive) {
+    throw new Error(
+      'makeLiveClient() called without WORDPRESS_URL/WORDPRESS_USER/WORDPRESS_APP_PASSWORD. ' +
+      'Guard with describe.skipIf(skipUnlessLive()).'
+    );
+  }
+  const config: BlockMCPConfig = {
+    wordpress_url: LIVE_ENV.url,
+    auth: {
+      username: LIVE_ENV.user,
+      application_password: LIVE_ENV.password,
+    },
+  };
+  return new WordPressBlockClient(config);
+}
+
+// ── Throwaway post lifecycle ───────────────────────────────────────────────
+
+/** IDs of posts created during this test run, for emergency globalTeardown sweeps. */
+const createdPostIds = new Set<number>();
+
+/**
+ * Create a throwaway draft post, run the callback, then delete it — even on
+ * failure. Returns whatever the callback returns so tests can use it as their
+ * assertion value.
+ *
+ * @param client  Live WordPressBlockClient
+ * @param callback  Async function receiving the new post_id
+ */
+export async function withTestPost<T>(
+  client: WordPressBlockClient,
+  callback: (postId: number) => Promise<T>
+): Promise<T> {
+  const title = `${LIVE_ENV.prefix} ${Date.now()}`;
+  const created = await client.createPost({
+    title,
+    status: 'draft',
+    // Seed with a minimal block so we always have something to read/mutate.
+    blocks: [
+      {
+        name: 'core/heading',
+        attributes: { level: 2, content: 'Integration test heading' },
+        innerHTML: '<h2 class="wp-block-heading">Integration test heading</h2>',
+      },
+      {
+        name: 'core/paragraph',
+        attributes: { content: 'Integration test paragraph.' },
+        innerHTML: '<p>Integration test paragraph.</p>',
+      },
+    ],
+  });
+
+  const postId = created.id;
+  createdPostIds.add(postId);
+
+  try {
+    return await callback(postId);
+  } finally {
+    await deleteTestPost(client, postId);
+  }
+}
+
+/**
+ * Delete a throwaway post, tolerating 404s and 429s (already gone or rate
+ * limited). Removes the post from the in-process tracker.
+ */
+export async function deleteTestPost(
+  client: WordPressBlockClient,
+  postId: number
+): Promise<void> {
+  try {
+    await client.updatePost(postId, { status: 'trash' });
+  } catch (err: unknown) {
+    // 404 / not found → already gone, fine.
+    // 429 → rate limited — log and move on so cleanup doesn't mask test failure.
+    const msg = err instanceof Error ? err.message : String(err);
+    if (!msg.includes('404') && !msg.includes('not found') && !msg.includes('429') && !msg.includes('rate_limit')) {
+      console.warn(`[integration] Failed to trash post ${postId}: ${msg}`);
+    }
+  } finally {
+    createdPostIds.delete(postId);
+  }
+}
+
+/**
+ * Sweep any posts that leaked (e.g. afterEach didn't fire because the process
+ * crashed). Designed to be called from Vitest globalTeardown.
+ *
+ * Safe to call even when `isLive` is false — returns immediately.
+ */
+export async function cleanupTestPosts(): Promise<void> {
+  if (!isLive) return;
+  if (createdPostIds.size === 0) return;
+
+  const client = makeLiveClient();
+  const ids = Array.from(createdPostIds);
+  console.warn(`[integration] globalTeardown: sweeping ${ids.length} leaked post(s): ${ids.join(', ')}`);
+  await Promise.allSettled(ids.map((id) => deleteTestPost(client, id)));
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Tool tests: get_pattern
+ *
+ * Covers:
+ *   - Requires pattern_id (numeric or string)
+ *   - Forwards numeric ID
+ *   - Forwards string name
+ *   - Returns the raw client response
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { handleDiscoveryTool } from '../../../tools/discovery.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+
+describe('get_pattern — validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getPattern.mockResolvedValue({ id: 1, name: 'Pattern', content: '' } as any);
+  });
+
+  it('requires pattern_id', async () => {
+    await expect(
+      handleDiscoveryTool('get_pattern', {}, client as any)
+    ).rejects.toThrow(/pattern_id is required/);
+  });
+
+  it('rejects null pattern_id', async () => {
+    await expect(
+      handleDiscoveryTool('get_pattern', { pattern_id: null }, client as any)
+    ).rejects.toThrow(/pattern_id is required/);
+  });
+});
+
+describe('get_pattern — routing', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getPattern.mockResolvedValue({ id: 1, name: 'Pattern', content: '' } as any);
+  });
+
+  it('forwards numeric ID', async () => {
+    await handleDiscoveryTool('get_pattern', { pattern_id: 42 }, client as any);
+    expect(client.getPattern).toHaveBeenCalledWith(42);
+  });
+
+  it('forwards string name (registered pattern)', async () => {
+    await handleDiscoveryTool('get_pattern', { pattern_id: 'twentytwentyfive/hero' }, client as any);
+    expect(client.getPattern).toHaveBeenCalledWith('twentytwentyfive/hero');
+  });
+
+  it('returns the raw client response', async () => {
+    const fake = { id: 9, name: 'X', content: '<!-- wp:paragraph /-->' };
+    client.getPattern.mockResolvedValueOnce(fake as any);
+    const result = await handleDiscoveryTool('get_pattern', { pattern_id: 9 }, client as any);
+    expect(result).toBe(fake);
+  });
+});

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

@@ -0,0 +1,100 @@
+/**
+ * Tool tests: get_post_info
+ *
+ * Covers:
+ *   - Requires one of: post_id, url, slug (rejects when all three missing)
+ *   - Numeric post_id passes through
+ *   - String post_id matching /^[0-9]+$/ coerced to integer
+ *   - Non-numeric string post_id rejected
+ *   - url alone accepted
+ *   - slug alone accepted (with optional post_type scope)
+ *   - Forwarding includes post_type when supplied
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { handleDiscoveryTool } from '../../../tools/discovery.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+
+describe('get_post_info — validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getPostInfo.mockResolvedValue({ post_id: 1 } as any);
+  });
+
+  it('throws when none of post_id, url, slug is provided', async () => {
+    await expect(
+      handleDiscoveryTool('get_post_info', {}, client as any)
+    ).rejects.toThrow(/post_id, url, or slug/);
+  });
+
+  it('throws on non-numeric string post_id', async () => {
+    await expect(
+      handleDiscoveryTool('get_post_info', { post_id: 'abc' }, client as any)
+    ).rejects.toThrow(/post_id must be a positive integer/);
+  });
+
+  it('throws on float post_id and does NOT call the client', async () => {
+    // post_id is documented as a positive integer. A float input must
+    // throw the documented error AND short-circuit before reaching the
+    // client — otherwise validation drift would only surface server-side.
+    await expect(
+      handleDiscoveryTool('get_post_info', { post_id: 1.5 }, client as any)
+    ).rejects.toThrow(/post_id must be a positive integer/);
+    expect(client.getPostInfo).not.toHaveBeenCalled();
+  });
+
+  it('accepts a positive integer post_id and forwards it', async () => {
+    await handleDiscoveryTool('get_post_info', { post_id: 1 }, client as any);
+    expect(client.getPostInfo).toHaveBeenCalledWith(expect.objectContaining({ post_id: 1 }));
+  });
+
+  it('throws on object post_id', async () => {
+    await expect(
+      handleDiscoveryTool('get_post_info', { post_id: {} }, client as any)
+    ).rejects.toThrow(/post_id must be a positive integer/);
+  });
+});
+
+describe('get_post_info — post_id resolution', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getPostInfo.mockResolvedValue({ post_id: 1 } as any);
+  });
+
+  it('forwards numeric post_id', async () => {
+    await handleDiscoveryTool('get_post_info', { post_id: 42 }, client as any);
+    expect(client.getPostInfo).toHaveBeenCalledWith(expect.objectContaining({ post_id: 42 }));
+  });
+
+  it('coerces well-formed integer-string post_id', async () => {
+    await handleDiscoveryTool('get_post_info', { post_id: '99' }, client as any);
+    expect(client.getPostInfo).toHaveBeenCalledWith(expect.objectContaining({ post_id: 99 }));
+  });
+});
+
+describe('get_post_info — url and slug routing', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getPostInfo.mockResolvedValue({ post_id: 1 } as any);
+  });
+
+  it('forwards url alone', async () => {
+    await handleDiscoveryTool('get_post_info', { url: '/about/' }, client as any);
+    expect(client.getPostInfo).toHaveBeenCalledWith(expect.objectContaining({ url: '/about/' }));
+  });
+
+  it('forwards slug alone', async () => {
+    await handleDiscoveryTool('get_post_info', { slug: 'about-us' }, client as any);
+    expect(client.getPostInfo).toHaveBeenCalledWith(expect.objectContaining({ slug: 'about-us' }));
+  });
+
+  it('forwards slug + post_type', async () => {
+    await handleDiscoveryTool('get_post_info', { slug: 'about-us', post_type: 'page' }, client as any);
+    expect(client.getPostInfo).toHaveBeenCalledWith({
+      post_id: undefined, url: undefined, slug: 'about-us', post_type: 'page',
+    });
+  });
+});

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

@@ -0,0 +1,41 @@
+/**
+ * Tool tests: get_site_usage
+ *
+ * Covers:
+ *   - Forwards refresh:undefined when not set
+ *   - Forwards refresh:true to bust the transient cache
+ *   - Returns raw client response (no MCP-side enrichment)
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { handleDiscoveryTool } from '../../../tools/discovery.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+import { siteUsageResponse } from '../../fixtures/rest-responses.js';
+
+describe('get_site_usage', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getSiteUsage.mockResolvedValue(siteUsageResponse);
+  });
+
+  it('forwards undefined refresh when not set', async () => {
+    await handleDiscoveryTool('get_site_usage', {}, client as any);
+    expect(client.getSiteUsage).toHaveBeenCalledWith(undefined);
+  });
+
+  it('forwards refresh:true', async () => {
+    await handleDiscoveryTool('get_site_usage', { refresh: true }, client as any);
+    expect(client.getSiteUsage).toHaveBeenCalledWith(true);
+  });
+
+  it('forwards refresh:false', async () => {
+    await handleDiscoveryTool('get_site_usage', { refresh: false }, client as any);
+    expect(client.getSiteUsage).toHaveBeenCalledWith(false);
+  });
+
+  it('returns the raw response', async () => {
+    const result = await handleDiscoveryTool('get_site_usage', {}, client as any);
+    expect(result).toBe(siteUsageResponse);
+  });
+});

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

@@ -0,0 +1,103 @@
+/**
+ * Tool tests: list_block_types
+ *
+ * Covers:
+ *   - Filter forwarding (namespace, category, tier, storage_mode, search,
+ *     preferred_only, usage_only)
+ *   - Pagination (limit defaults 50, offset defaults 0, next_offset math)
+ *   - Enrichment: response includes `guidance` string
+ *   - Response shape: block_types, count, total, offset, next_offset, guidance
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { handleDiscoveryTool } from '../../../tools/discovery.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+import { blockTypesResponse } from '../../fixtures/rest-responses.js';
+
+describe('list_block_types — filter forwarding', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getBlockTypes.mockResolvedValue(blockTypesResponse);
+  });
+
+  it('forwards every documented filter', async () => {
+    await handleDiscoveryTool('list_block_types', {
+      namespace: 'core', category: 'text', tier: 'preferred',
+      storage_mode: 'static', search: 'para', preferred_only: true, usage_only: true,
+    }, client as any);
+    expect(client.getBlockTypes).toHaveBeenCalledWith({
+      namespace: 'core', category: 'text', tier: 'preferred',
+      storage_mode: 'static', search: 'para', preferred_only: true, usage_only: true,
+    });
+  });
+
+  it('forwards no filters when none are provided (all undefined)', async () => {
+    await handleDiscoveryTool('list_block_types', {}, client as any);
+    expect(client.getBlockTypes).toHaveBeenCalledWith({
+      namespace: undefined, category: undefined, tier: undefined,
+      storage_mode: undefined, search: undefined, preferred_only: undefined, usage_only: undefined,
+    });
+  });
+});
+
+describe('list_block_types — pagination', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+  });
+
+  it('defaults to limit 50 and offset 0', async () => {
+    // Build 60 fake block types so pagination matters
+    const many = Array.from({ length: 60 }, (_, i) => ({
+      name: `core/block-${i}`, title: `Block ${i}`,
+      preference: { tier: 'preferred', score: 90 },
+    }));
+    client.getBlockTypes.mockResolvedValueOnce({ block_types: many } as any);
+    const result = await handleDiscoveryTool('list_block_types', {}, client as any) as Record<string, unknown>;
+    expect(result.count).toBe(50);
+    expect(result.offset).toBe(0);
+    expect(result.next_offset).toBe(50);
+    expect(result.total).toBe(60);
+  });
+
+  it('honors explicit limit and offset', async () => {
+    const many = Array.from({ length: 30 }, (_, i) => ({
+      name: `core/block-${i}`, title: `Block ${i}`,
+      preference: { tier: 'preferred', score: 90 },
+    }));
+    client.getBlockTypes.mockResolvedValueOnce({ block_types: many } as any);
+    const result = await handleDiscoveryTool('list_block_types', { limit: 10, offset: 20 }, client as any) as Record<string, unknown>;
+    expect(result.count).toBe(10);
+    expect(result.offset).toBe(20);
+    expect(result.next_offset).toBeNull();
+  });
+
+  it('next_offset is null when the page ends at total', async () => {
+    client.getBlockTypes.mockResolvedValueOnce(blockTypesResponse);
+    const result = await handleDiscoveryTool('list_block_types', { limit: 100 }, client as any) as Record<string, unknown>;
+    expect(result.next_offset).toBeNull();
+  });
+});
+
+describe('list_block_types — response shape', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getBlockTypes.mockResolvedValue(blockTypesResponse);
+  });
+
+  it('returns block_types, count, total, offset, next_offset, guidance', async () => {
+    const result = await handleDiscoveryTool('list_block_types', {}, client as any) as Record<string, unknown>;
+    expect(Array.isArray(result.block_types)).toBe(true);
+    expect(typeof result.count).toBe('number');
+    expect(typeof result.total).toBe('number');
+    expect(typeof result.offset).toBe('number');
+    expect(typeof result.guidance).toBe('string');
+  });
+
+  it('guidance is a non-empty string when results exist', async () => {
+    const result = await handleDiscoveryTool('list_block_types', {}, client as any) as Record<string, unknown>;
+    expect((result.guidance as string).length).toBeGreaterThan(0);
+  });
+});