# 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`):
```typescript
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`:
```json
{
  "mcpServers": {
    "swagger-tools": {
      "command": "node",
      "args": ["/path/to/swagger-tools/dist/index.js"]
    }
  }
}
```

## Commands

```bash
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)