cc789d3b32
- Parse and validate OpenAPI 3.x / Swagger 2.0 specs - Query endpoints by method, path pattern, tag, operationId - Get component schema details - Generate TypeScript interfaces from schemas - Support local files and remote URLs Tools: parse-spec, validate-spec, query-endpoints, get-schema, generate-types Co-Authored-By: Claude <noreply@anthropic.com>
96 lines
2.2 KiB
Markdown
96 lines
2.2 KiB
Markdown
# 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
|