swagger-tools/README.md

# swagger-tools

MCP (Model Context Protocol) server for parsing, validating, and querying OpenAPI/Swagger specifications.

## Features

- **Parse** OpenAPI 3.x and Swagger 2.0 specifications
- **Validate** specs against official schemas with detailed error reporting
- **Query** endpoints by method, path pattern, tag, or operation ID
- **Inspect** component schemas with resolved references
- **Generate** TypeScript interfaces from schemas
- **Support** both local files and remote URLs

## Installation

```bash
git clone https://git.hyperlocalplatform.com/rimskij/swagger-tools.git
cd swagger-tools
npm install
npm run build
```

## Configuration

### Claude Code

Add to `~/.claude.json`:

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

Restart Claude Code after configuration.

### Other MCP Clients

The server uses stdio transport. Run with:

```bash
node /path/to/swagger-tools/dist/index.js
```

Communicate via JSON-RPC 2.0 over stdin/stdout.

## Tools

### parse-spec

Parse an OpenAPI/Swagger spec and return metadata.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Path to spec file or URL |

**Output:**
- Version (OpenAPI 3.x or Swagger 2.0)
- Title and description
- Server URLs
- Path count, operation count, schema count
- Tags

**Example:**
```
Parse the OpenAPI spec at ./api.yaml
```

---

### validate-spec

Validate a spec against the OpenAPI schema.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Path to spec file or URL |

**Output:**
- Validation status (pass/fail)
- Errors with JSON path locations
- Warnings (missing operationId, missing descriptions)

**Example:**
```
Validate https://petstore.swagger.io/v2/swagger.json
```

---

### query-endpoints

Search and filter API endpoints.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Path to spec file or URL |
| `method` | string | No | Filter by HTTP method (GET, POST, etc.) |
| `pathPattern` | string | No | Regex pattern to match paths |
| `tag` | string | No | Filter by tag name |
| `operationId` | string | No | Filter by exact operation ID |

**Output:**
- Matching endpoints with:
  - Method and path
  - Operation ID and summary
  - Tags
  - Parameters (name, location, required, schema)
  - Request body info
  - Response status codes and content types

**Examples:**
```
Show all GET endpoints in api.yaml
List endpoints with path matching /users in api.yaml
Find endpoints tagged "authentication" in api.yaml
```

---

### get-schema

Get details of a component schema.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Path to spec file or URL |
| `schemaName` | string | Yes | Schema name in components/schemas |

**Output:**
- Schema name and type
- Description
- Full JSON schema with resolved $refs

**Example:**
```
Show the User schema from api.yaml
```

---

### generate-types

Generate TypeScript interfaces from schemas.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Path to spec file or URL |
| `schemas` | string[] | No | Specific schemas (all if omitted) |

**Output:**
- TypeScript interface/type definitions
- JSDoc comments from descriptions
- Proper handling of:
  - Required vs optional properties
  - Enums as union types
  - Arrays and nested objects
  - allOf (intersection), oneOf/anyOf (union)
  - additionalProperties as Record<string, T>

**Examples:**
```
Generate TypeScript types from api.yaml
Generate only User and Order types from api.yaml
```

## Supported Formats

| Format | Version | File Types |
|--------|---------|------------|
| OpenAPI | 3.0.x | .yaml, .yml, .json |
| OpenAPI | 3.1.x | .yaml, .yml, .json |
| Swagger | 2.0 | .yaml, .yml, .json |

## Input Sources

| Source | Example |
|--------|---------|
| Local file (relative) | `./api.yaml` |
| Local file (absolute) | `/path/to/api.yaml` |
| Remote URL (HTTPS) | `https://example.com/openapi.json` |
| Remote URL (HTTP) | `http://localhost:3000/api-docs` |

## Architecture

```
src/
├── index.ts              # MCP server entry (stdio transport)
├── tools/
│   ├── parse.ts          # parse-spec implementation
│   ├── validate.ts       # validate-spec implementation
│   ├── query.ts          # query-endpoints implementation
│   ├── schema.ts         # get-schema implementation
│   └── generate.ts       # generate-types implementation
├── lib/
│   ├── parser.ts         # SwaggerParser wrapper
│   ├── validator.ts      # Validation logic
│   └── types.ts          # TypeScript type definitions
└── utils/
    └── format.ts         # Output formatting
```

## Dependencies

| Package | Purpose |
|---------|---------|
| `@modelcontextprotocol/sdk` | MCP server framework |
| `@apidevtools/swagger-parser` | Parse, validate, dereference specs |
| `zod` | Input schema validation |

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Type check without emit
npm run typecheck

# Run in development (with tsx)
npm run dev
```

## Testing

Manual test with JSON-RPC:

```bash
# List available tools
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
```

## Example Output

### parse-spec

```
# Pet Store API
Version: OpenAPI 3.0.3
Description: A sample Pet Store API

## Statistics
- Paths: 3
- Operations: 5
- Schemas: 5

## Servers
- https://api.petstore.example.com/v1

## Tags
- pets
- store
```

### generate-types

```typescript
/** A pet in the store */
export interface Pet {
  /** Unique identifier */
  id: number;
  /** Pet name */
  name: string;
  /** Pet availability status */
  status?: 'available' | 'pending' | 'sold';
  tags?: Tag[];
}

/** Pet availability status */
export type PetStatus = 'available' | 'pending' | 'sold';
```

## License

MIT