641a9e56dc
- 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>
138 lines
3.6 KiB
Markdown
138 lines
3.6 KiB
Markdown
# swagger-tools
|
|
|
|
MCP server for parsing, validating, and querying OpenAPI/Swagger specifications.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
## MCP Configuration
|
|
|
|
Add to `~/.claude.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"swagger-tools": {
|
|
"command": "node",
|
|
"args": ["/Users/rimskij/projects/swagger-tools/dist/index.js"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Restart Claude Code after configuration.
|
|
|
|
## Available Tools
|
|
|
|
| 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?` |
|
|
|
|
## Usage Examples
|
|
|
|
```
|
|
# Natural language - Claude calls the right tool
|
|
"Parse the API spec at ./api.yaml"
|
|
"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
|
|
|
|
```
|
|
src/
|
|
├── index.ts # Entry point - registers tools, starts stdio server
|
|
├── tools/ # Tool implementations
|
|
│ ├── parse.ts # parseSpec() → metadata extraction
|
|
│ ├── validate.ts # validateSpec() → error collection
|
|
│ ├── query.ts # queryEndpoints() → filtering logic
|
|
│ ├── schema.ts # getSchema() → schema lookup
|
|
│ └── generate.ts # generateTypes() → TS code generation
|
|
├── lib/ # Shared utilities
|
|
│ ├── parser.ts # SwaggerParser.dereference() wrapper
|
|
│ ├── validator.ts # SwaggerParser.validate() wrapper
|
|
│ └── types.ts # TypeScript interfaces
|
|
└── utils/
|
|
└── format.ts # Human-readable output formatting
|
|
```
|
|
|
|
## Code Patterns
|
|
|
|
### 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
|
|
|
|
```bash
|
|
npm run build # Compile TypeScript
|
|
npm run typecheck # Type check only
|
|
npm run dev # Run with tsx (hot reload)
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# List tools
|
|
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
|
|
|
|
# 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
|
|
|
|
| Package | Version | Purpose |
|
|
|---------|---------|---------|
|
|
| `@modelcontextprotocol/sdk` | ^1.0.0 | MCP protocol |
|
|
| `@apidevtools/swagger-parser` | ^10.1.0 | OpenAPI parsing |
|
|
| `zod` | ^3.23.0 | Schema validation |
|