api-testing-mcp: Instructions file for Claude Code

CLAUDE.md — @cocaxcode/api-testing-mcp

Project Overview

MCP server for API testing. Zero cloud dependencies, local JSON storage. 42 tools, 171 tests.

Token-optimized responses (v0.13+)

request accepts three optional parameters that cut context tokens by 70-97%:

• verbosity: 'minimal' | 'normal' | 'full' (default 'normal')
• only_fields: string[] with dot-paths (data.id, items[*].name)
• max_body_bytes: number (default 2048) for 'normal'

Every compressed response includes a call_id. Use inspect_last_response({ call_id }) to recover the full unfiltered response when needed. Responses are cached in a 20-slot ring buffer + .api-testing/last-responses/ with 1h TTL.

Header filter lists live in lib/compress.ts (FILTERED_HEADERS, FILTERED_HEADER_PATTERNS).

Stack

• TypeScript 5.x (strict mode, ESM)
• @modelcontextprotocol/sdk 1.27.x (unified package)
• Zod 3.25+ for schema validation
• Vitest for testing (InMemoryTransport for integration tests)
• tsup for building (ESM output with shebang)

Architecture

src/
├── index.ts          # Entry point (shebang + StdioServerTransport)
├── server.ts         # createServer() factory
├── tools/            # MCP tool registration (one file per group)
│   ├── request.ts    # HTTP request tool (1)
│   ├── collection.ts # Collection CRUD tools (4)
│   ├── environment.ts # Environment tools (10)
│   ├── api-spec.ts   # OpenAPI import/browse tools (4)
│   ├── assert.ts     # Assertion testing tool (1)
│   ├── flow.ts       # Request chaining tool (1)
│   ├── mock.ts       # Mock data generation tool (1)
│   ├── load-test.ts  # Load testing tool (1)
│   └── utilities.ts  # export_curl, diff_responses, bulk_test, export/import_collection, export/import_environment, export/import_postman_collection, export/import_postman_environment (11)
├── lib/              # Business logic (no MCP dependency)
│   ├── types.ts      # Shared TypeScript interfaces
│   ├── schemas.ts    # Shared Zod schemas (AuthSchema, HttpMethodSchema)
│   ├── url.ts        # resolveUrl() — BASE_URL auto-prepend
│   ├── path.ts       # getByPath() — dot notation accessor
│   ├── http-client.ts # fetch wrapper with timing
│   ├── storage.ts    # JSON file storage in .api-testing/
│   ├── interpolation.ts # {{variable}} resolver
│   └── openapi-parser.ts # OpenAPI spec parser with $ref + allOf/oneOf/anyOf
└── __tests__/
    ├── helpers.ts    # createTestClient() with InMemoryTransport
    └── *.test.ts     # 10 test files, 110 tests