docs: add comprehensive README and update CLAUDE.md
- Full README with installation, configuration, tool reference - Usage examples for all 5 tools - Architecture overview and dependency list - Updated CLAUDE.md with code patterns and development guide Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
rimskij
parent
cc789d3b32
commit
641a9e56dc
2 changed files with 383 additions and 50 deletions
142
CLAUDE.md
142
CLAUDE.md
|
|
@ -5,92 +5,134 @@ MCP server for parsing, validating, and querying OpenAPI/Swagger specifications.
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Install dependencies
|
|
||||||
npm install
|
npm install
|
||||||
|
|
||||||
# Build
|
|
||||||
npm run build
|
npm run build
|
||||||
|
|
||||||
# Run (for testing)
|
|
||||||
npm start
|
npm start
|
||||||
```
|
```
|
||||||
|
|
||||||
## MCP Server Configuration
|
## MCP Configuration
|
||||||
|
|
||||||
Add to `~/.claude.json` (or project `.mcp.json`):
|
Add to `~/.claude.json`:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"mcpServers": {
|
||||||
"swagger-tools": {
|
"swagger-tools": {
|
||||||
"command": "node",
|
"command": "node",
|
||||||
"args": ["/absolute/path/to/swagger-tools/dist/index.js"]
|
"args": ["/Users/rimskij/projects/swagger-tools/dist/index.js"]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
After configuring, restart Claude Code. The tools will be available as:
|
Restart Claude Code after configuration.
|
||||||
- `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
|
## Available Tools
|
||||||
|
|
||||||
Use `/openapi` for convenient access:
|
| Tool | Purpose | Key Parameters |
|
||||||
|
|------|---------|----------------|
|
||||||
|
| `parse-spec` | Parse spec, show metadata | `path` |
|
||||||
|
| `validate-spec` | Validate against schema | `path` |
|
||||||
|
| `query-endpoints` | Search/filter endpoints | `path`, `method?`, `pathPattern?`, `tag?` |
|
||||||
|
| `get-schema` | Get schema details | `path`, `schemaName` |
|
||||||
|
| `generate-types` | Generate TypeScript | `path`, `schemas?` |
|
||||||
|
|
||||||
```bash
|
## Usage Examples
|
||||||
/openapi parse api.yaml # Parse and show overview
|
|
||||||
/openapi validate api.yaml # Validate spec
|
```
|
||||||
/openapi endpoints api.yaml # List all endpoints
|
# Natural language - Claude calls the right tool
|
||||||
/openapi schema api.yaml User # Get schema details
|
"Parse the API spec at ./api.yaml"
|
||||||
/openapi types api.yaml # Generate TypeScript types
|
"Show me all POST endpoints in api.yaml"
|
||||||
|
"Generate TypeScript types from https://petstore.swagger.io/v2/swagger.json"
|
||||||
|
"Is api.yaml valid?"
|
||||||
|
"What does the User schema look like?"
|
||||||
```
|
```
|
||||||
|
|
||||||
## Project Structure
|
## Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
src/
|
src/
|
||||||
├── index.ts # MCP server entry point (stdio)
|
├── index.ts # Entry point - registers tools, starts stdio server
|
||||||
├── tools/ # MCP tool implementations
|
├── tools/ # Tool implementations
|
||||||
│ ├── parse.ts # parse-spec tool
|
│ ├── parse.ts # parseSpec() → metadata extraction
|
||||||
│ ├── validate.ts # validate-spec tool
|
│ ├── validate.ts # validateSpec() → error collection
|
||||||
│ ├── query.ts # query-endpoints tool
|
│ ├── query.ts # queryEndpoints() → filtering logic
|
||||||
│ ├── schema.ts # get-schema tool
|
│ ├── schema.ts # getSchema() → schema lookup
|
||||||
│ └── generate.ts # generate-types tool
|
│ └── generate.ts # generateTypes() → TS code generation
|
||||||
├── lib/ # Core library
|
├── lib/ # Shared utilities
|
||||||
│ ├── parser.ts # OpenAPI parsing wrapper
|
│ ├── parser.ts # SwaggerParser.dereference() wrapper
|
||||||
│ ├── validator.ts # Validation logic
|
│ ├── validator.ts # SwaggerParser.validate() wrapper
|
||||||
│ └── types.ts # TypeScript types
|
│ └── types.ts # TypeScript interfaces
|
||||||
└── utils/
|
└── utils/
|
||||||
└── format.ts # Output formatting
|
└── format.ts # Human-readable output formatting
|
||||||
|
```
|
||||||
|
|
||||||
.claude/
|
## Code Patterns
|
||||||
└── commands/
|
|
||||||
└── openapi.md # Slash command definition
|
### Tool Structure
|
||||||
|
|
||||||
|
Each tool exports:
|
||||||
|
```typescript
|
||||||
|
export const toolName = 'tool-name';
|
||||||
|
export const toolDescription = '...';
|
||||||
|
export const toolSchema = { param: z.string() };
|
||||||
|
export async function toolHandler({ param }) { ... }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Return Format
|
||||||
|
|
||||||
|
Tools return MCP-compatible responses:
|
||||||
|
```typescript
|
||||||
|
return {
|
||||||
|
content: [{ type: 'text', text: humanReadable }],
|
||||||
|
structuredContent: { success: true, data: ... }
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error Handling
|
||||||
|
|
||||||
|
Wrap in try/catch, return error in both content and structuredContent:
|
||||||
|
```typescript
|
||||||
|
catch (err) {
|
||||||
|
return {
|
||||||
|
content: [{ type: 'text', text: `Error: ${err.message}` }],
|
||||||
|
structuredContent: { success: false, error: err.message }
|
||||||
|
};
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Development
|
## Development
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Type check without building
|
npm run build # Compile TypeScript
|
||||||
npm run typecheck
|
npm run typecheck # Type check only
|
||||||
|
npm run dev # Run with tsx (hot reload)
|
||||||
# Run with tsx (development)
|
|
||||||
npm run dev
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Supported Formats
|
## Testing
|
||||||
|
|
||||||
- OpenAPI 3.0.x
|
```bash
|
||||||
- OpenAPI 3.1.x
|
# List tools
|
||||||
- Swagger 2.0
|
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
|
||||||
- YAML and JSON files
|
|
||||||
|
# Call a tool
|
||||||
|
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"parse-spec","arguments":{"path":"test/fixtures/petstore.yaml"}}}' | node dist/index.js
|
||||||
|
```
|
||||||
|
|
||||||
|
## Adding New Tools
|
||||||
|
|
||||||
|
1. Create `src/tools/newtool.ts` following existing pattern
|
||||||
|
2. Export name, description, schema, handler
|
||||||
|
3. Import and register in `src/index.ts`:
|
||||||
|
```typescript
|
||||||
|
server.tool(name, description, schema, handler);
|
||||||
|
```
|
||||||
|
4. Rebuild: `npm run build`
|
||||||
|
|
||||||
## Dependencies
|
## Dependencies
|
||||||
|
|
||||||
- `@modelcontextprotocol/sdk` - MCP server framework
|
| Package | Version | Purpose |
|
||||||
- `@apidevtools/swagger-parser` - OpenAPI parsing and validation
|
|---------|---------|---------|
|
||||||
- `zod` - Schema validation for tool inputs
|
| `@modelcontextprotocol/sdk` | ^1.0.0 | MCP protocol |
|
||||||
|
| `@apidevtools/swagger-parser` | ^10.1.0 | OpenAPI parsing |
|
||||||
|
| `zod` | ^3.23.0 | Schema validation |
|
||||||
|
|
|
||||||
291
README.md
Normal file
291
README.md
Normal file
|
|
@ -0,0 +1,291 @@
|
||||||
|
# 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
|
||||||
Loading…
Add table
Reference in a new issue