docs: add handoff documentation

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

CLAUDE.md

@@ -48,6 +48,28 @@ Restart Claude Code after configuration.
 "What does the User schema look like?"
 ```
 
+## Key Features
+
+### Broken $ref Fallback
+When specs have broken `$ref` pointers, parser falls back to non-dereferenced mode:
+```typescript
+// In lib/parser.ts
+try {
+  spec = await SwaggerParser.dereference(specPath);  // Try first
+} catch {
+  spec = await SwaggerParser.parse(specPath);        // Fallback
+}
+```
+
+### .NET Name Sanitization
+Converts .NET-style schema names to valid TypeScript:
+```typescript
+// In tools/generate.ts - sanitizeName()
+"Namespace.Type"           → "Type"
+"Generic`1[Inner]"         → "Generic_Inner"
+"Company.Api.V5.ViewModel" → "ViewModel"
+```
+
 ## Project Structure
 
 ```
@@ -58,9 +80,9 @@ src/
 │   ├── validate.ts       # validateSpec() → error collection
 │   ├── query.ts          # queryEndpoints() → filtering logic
 │   ├── schema.ts         # getSchema() → schema lookup
-│   └── generate.ts       # generateTypes() → TS code generation
+│   └── generate.ts       # generateTypes() → TS code generation + sanitizeName()
 ├── lib/                  # Shared utilities
-│   ├── parser.ts         # SwaggerParser.dereference() wrapper
+│   ├── parser.ts         # SwaggerParser wrapper (dereference with fallback)
 │   ├── validator.ts      # SwaggerParser.validate() wrapper
 │   └── types.ts          # TypeScript interfaces
 └── utils/
@@ -115,8 +137,14 @@ npm run dev        # Run with tsx (hot reload)
 # List tools
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
 
-# Call a tool
+# Local spec
 echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"parse-spec","arguments":{"path":"test/fixtures/petstore.yaml"}}}' | node dist/index.js
+
+# Remote URL
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"parse-spec","arguments":{"path":"https://petstore.swagger.io/v2/swagger.json"}}}' | node dist/index.js
+
+# Enterprise API with broken refs
+echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"parse-spec","arguments":{"path":"https://projects.moravia.com/api/swagger/v5/swagger.json"}}}' | node dist/index.js
 ```
 
 ## Adding New Tools

README.md

@@ -10,6 +10,8 @@ MCP (Model Context Protocol) server for parsing, validating, and querying OpenAP
 - **Inspect** component schemas with resolved references
 - **Generate** TypeScript interfaces from schemas
 - **Support** both local files and remote URLs
+- **Handle** broken `$ref` pointers gracefully (fallback mode)
+- **Sanitize** .NET-style schema names for valid TypeScript
 
 ## Installation
 
@@ -66,6 +68,7 @@ Parse an OpenAPI/Swagger spec and return metadata.
 - Server URLs
 - Path count, operation count, schema count
 - Tags
+- Warning if spec has broken `$refs` (parsed without dereferencing)
 
 **Example:**
 ```
@@ -167,6 +170,14 @@ Generate TypeScript interfaces from schemas.
   - Arrays and nested objects
   - allOf (intersection), oneOf/anyOf (union)
   - additionalProperties as Record<string, T>
+  - .NET-style names sanitized to valid TypeScript identifiers
+
+**Name Sanitization:**
+| Original | Sanitized |
+|----------|-----------|
+| `Namespace.SubNs.TypeName` | `TypeName` |
+| `GenericType\`1[InnerType]` | `GenericType_InnerType` |
+| `Company.Api.V5.UserViewModel` | `UserViewModel` |
 
 **Examples:**
 ```
@@ -191,6 +202,24 @@ Generate only User and Order types from api.yaml
 | Remote URL (HTTPS) | `https://example.com/openapi.json` |
 | Remote URL (HTTP) | `http://localhost:3000/api-docs` |
 
+## Broken $ref Handling
+
+When a spec contains broken `$ref` pointers (e.g., typos in schema names), the parser:
+
+1. **Attempts** full dereferencing first
+2. **Falls back** to parsing without dereferencing if refs are broken
+3. **Warns** in output: "Spec has broken $refs. Parsed without dereferencing."
+
+This allows you to still extract metadata, query endpoints, and generate types from imperfect specs.
+
+## Tested With
+
+| API | Stats | Notes |
+|-----|-------|-------|
+| Petstore (Swagger) | 14 paths, 20 ops | Standard test spec |
+| Petstore (OpenAPI 3) | 3 paths, 5 ops | Local fixture |
+| Moravia Symfonie | 293 paths, 381 ops, 185 schemas | Enterprise .NET API with broken $refs |
+
 ## Architecture
 
 ```
@@ -203,7 +232,7 @@ src/
 │   ├── schema.ts         # get-schema implementation
 │   └── generate.ts       # generate-types implementation
 ├── lib/
-│   ├── parser.ts         # SwaggerParser wrapper
+│   ├── parser.ts         # SwaggerParser wrapper (with fallback)
 │   ├── validator.ts      # Validation logic
 │   └── types.ts          # TypeScript type definitions
 └── utils/
@@ -244,6 +273,9 @@ echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
 
 # Parse a spec
 echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"parse-spec","arguments":{"path":"test/fixtures/petstore.yaml"}}}' | node dist/index.js
+
+# Test with remote URL
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"parse-spec","arguments":{"path":"https://petstore.swagger.io/v2/swagger.json"}}}' | node dist/index.js
 ```
 
 ## Example Output
@@ -286,6 +318,26 @@ export interface Pet {
 export type PetStatus = 'available' | 'pending' | 'sold';
 ```
 
+### generate-types (from .NET API)
+
+```typescript
+/** Original: Microsoft.AspNetCore.OData.Results.SingleResult`1[...] */
+export interface SingleResult_JobCommentViewModel {
+  queryable?: JobCommentViewModel[];
+}
+
+/** Job view model */
+export interface JobViewModel {
+  /** The identifier. */
+  id?: number;
+  /** The name. MaxLength(255) */
+  name: string;
+  /** The project identifier. */
+  projectId: number;
+  // ...
+}
+```
+
 ## License
 
 MIT

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)