swagger-tools/docs/handoffs/handoff-2026-01-12.md

Handoff: swagger-tools MCP Server

Date: 2026-01-12 Version: 0.1.1 Branch: dev (synced with main)

Project Summary

MCP (Model Context Protocol) server for parsing, validating, and querying OpenAPI/Swagger specifications. Built to reduce token usage compared to markdown-based Claude Code skills.

What Was Built

Core Features

• 5 MCP Tools: parse-spec, validate-spec, query-endpoints, get-schema, generate-types
• Spec Support: OpenAPI 3.x and Swagger 2.0 (YAML/JSON)
• Input Sources: Local files and remote URLs
• Broken $ref Handling: Graceful fallback when specs have broken references
• TypeScript Generation: With .NET-style name sanitization

Architecture

src/
├── index.ts              # MCP server entry (stdio transport)
├── tools/
│   ├── parse.ts          # parse-spec - load and analyze specs
│   ├── validate.ts       # validate-spec - schema validation
│   ├── query.ts          # query-endpoints - search/filter endpoints
│   ├── schema.ts         # get-schema - component schema details
│   └── generate.ts       # generate-types - TypeScript generation
├── lib/
│   ├── parser.ts         # SwaggerParser wrapper with fallback
│   ├── validator.ts      # Validation logic
│   └── types.ts          # TypeScript type definitions
└── utils/
    └── format.ts         # Output formatting

Key Implementation Details

Broken $ref Fallback (src/lib/parser.ts:17-27):

try {
  spec = await SwaggerParser.dereference(specPath);
  dereferenced = true;
} catch {
  // Fallback to parse without dereferencing if refs are broken
  spec = await SwaggerParser.parse(specPath);
}

Name Sanitization (src/tools/generate.ts:98-127):

• Handles .NET namespaces: Namespace.SubNs.TypeName → TypeName
• Handles generics: Generic\1[InnerType]→Generic_InnerType`
• Removes invalid characters, ensures valid TypeScript identifiers

Testing Results

Tested against enterprise API (Moravia Symfonie):

• 293 paths, 381 operations, 185 schemas
• Successfully handles broken $refs
• Successfully sanitizes .NET-style schema names

Configuration

Add to ~/.claude.json:

{
  "mcpServers": {
    "swagger-tools": {
      "command": "node",
      "args": ["/path/to/swagger-tools/dist/index.js"]
    }
  }
}

Commands

npm install     # Install dependencies
npm run build   # Build TypeScript
npm run dev     # Development mode (tsx)
npm start       # Run production build

Git History

Commit	Description
7791adc	docs: update README and CLAUDE.md with new features
64f7e40	chore: release v0.1.1
c978f9c	fix: sanitize .NET-style schema names for valid TypeScript
4091947	fix: graceful fallback for specs with broken $refs
641a9e5	docs: add comprehensive README and update CLAUDE.md

No Pending Work

All requested features implemented and tested.

Potential Future Enhancements

• Add caching for remote specs
• Support for OpenAPI 3.1.x JSON Schema features
• Batch operations for multiple specs
• Custom TypeScript output options (interface vs type, optional handling)