swagger-api-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Run Commands

npm run build          # TypeScript compilation (tsc) → dist/
npm start              # Run server in stdio mode
npm run start:http     # Run server in HTTP mode (port 3000)
npm run dev            # Dev mode with auto-reload (tsx watch)
npm run clean          # Remove dist/

To auto-load a spec on startup: SWAGGER_URL=https://example.com/swagger.json npm start

Architecture

This is an MCP (Model Context Protocol) server that parses Swagger 2.0 / OpenAPI 3.x specifications and exposes their contents as MCP tools. The spec is loaded into memory, parsed once into local JSON cache files, and tools return brief summaries + file paths instead of full content (saving 85-95% of tokens).

Source Layout

• src/index.ts — Entry point, server factory, all 11 tool registrations, 3 prompt registrations, 3 resource registrations, and both transport implementations (stdio + HTTP with Express). The registerTools() function contains all tool definitions. Each tool follows the pattern: define a Zod schema → call registerToolWithMetadata() with handler. registerPrompts() registers guided workflow prompts. registerResources() registers static resources backed by cache files.
• src/types.ts — TypeScript interfaces for tool metadata, OpenAPI schema objects, endpoint details, session info. The spec is typed as Record<string, unknown> throughout (not a typed OpenAPI object) — all field access uses bracket notation with explicit casts.
• src/utils.ts — Pure utility functions: $ref resolution with circular reference protection (deepResolve), Swagger 2.0 vs OpenAPI 3.x abstraction helpers (getSchemas, getServers, extractParameters, etc.), and markdown formatting for tool output.
• src/cache-types.ts — TypeScript interfaces for cache files: CacheMeta, CacheInfo, CacheTag, CachePathEntry, CacheSchemaEntry, CacheEndpointDetail.
• src/cache.ts — Cache manager: generates, reads, and clears the .swagger-cache/ directory. Exports generateCache(), readCacheJSON(), getCacheFilePath(), ensureCacheLoaded(), etc.