mcp-testbed: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code working in this repository.

What this is

An MCP server that gives an agent an isolated workspace, runs its tests, and returns a deterministic pass/fail verdict. Determinism is the product. Anything that makes two runs of identical code produce different output is a bug, and the end to end test asserts byte identical output across two workspaces.

Read README.md for the user facing description. This file covers what you need to change code safely.

Critical: this uses MCP SDK v2, not v1

This is the single most likely thing to get wrong, because v1 is far more common in training data.

Correct (what this repo uses):

import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod';

server.registerTool(
  'tool_name',
  {
    title: 'Human readable title',
    description: '...',
    inputSchema: z.object({ field: z.string() }),
    outputSchema: z.object({ result: z.string() }),
    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
  },
  async ({ field }) => ({
    content: [{ type: 'text', text: JSON.stringify(output) }],
    structuredContent: output,
  }),
);

Wrong (v1 API, will not work here):

• import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
• import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
• server.tool(name, description, schema, handler)
• Passing a raw Zod shape { field: z.string() } instead of z.object({ ... }). The raw shape form still exists but is deprecated.

The client package is @modelcontextprotocol/client v2, used only in tests.

If you need to check an API, read the types in node_modules/@modelcontextprotocol/server/dist/createMcpHandler-*.d.mts. The barrel file index.d.mts is a minified re-export and is not readable.

Commands

npm test                          # all tests, via tsx + node:test
npx tsx --test test/normalize.test.ts   # a single file
npm run typecheck                 # tsc --noEmit
npm run build                     # tsc, emits to dist/
npm start                         # runs the built server on stdio