# swagger-tools

MCP server for parsing, validating, and querying OpenAPI/Swagger specifications.

## Quick Start

```bash
# Install dependencies
npm install

# Build
npm run build

# Run (for testing)
npm start
```

## MCP Server Configuration

Add to `~/.claude.json` (or project `.mcp.json`):

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

After configuring, restart Claude Code. The tools will be available as:
- `mcp__swagger-tools__parse-spec`
- `mcp__swagger-tools__validate-spec`
- `mcp__swagger-tools__query-endpoints`
- `mcp__swagger-tools__get-schema`
- `mcp__swagger-tools__generate-types`

## Claude Code Slash Command

Use `/openapi` for convenient access:

```bash
/openapi parse api.yaml          # Parse and show overview
/openapi validate api.yaml       # Validate spec
/openapi endpoints api.yaml      # List all endpoints
/openapi schema api.yaml User    # Get schema details
/openapi types api.yaml          # Generate TypeScript types
```

## Project Structure

```
src/
├── index.ts           # MCP server entry point (stdio)
├── tools/             # MCP tool implementations
│   ├── parse.ts       # parse-spec tool
│   ├── validate.ts    # validate-spec tool
│   ├── query.ts       # query-endpoints tool
│   ├── schema.ts      # get-schema tool
│   └── generate.ts    # generate-types tool
├── lib/               # Core library
│   ├── parser.ts      # OpenAPI parsing wrapper
│   ├── validator.ts   # Validation logic
│   └── types.ts       # TypeScript types
└── utils/
    └── format.ts      # Output formatting

.claude/
└── commands/
    └── openapi.md     # Slash command definition
```

## Development

```bash
# Type check without building
npm run typecheck

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

## Supported Formats

- OpenAPI 3.0.x
- OpenAPI 3.1.x
- Swagger 2.0
- YAML and JSON files

## Dependencies

- `@modelcontextprotocol/sdk` - MCP server framework
- `@apidevtools/swagger-parser` - OpenAPI parsing and validation
- `zod` - Schema validation for tool inputs