docs: add handoff documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

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

@@ -0,0 +1,105 @@
+# 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)