@nam088/mcp-swagger-parser

Enhanced OpenAPI/Swagger MCP plugin with 12 powerful tools, YAML support, and automatic schema resolution.

Features

✨ 12 Comprehensive Tools

• 7 Discovery Tools (search, details, tags, curl generator)
• 1 Safe Read Tool (GET requests only)
• 4 Write Tools (POST/PUT/PATCH/DELETE with FULL mode restriction)

🔍 Auto Schema Resolution

• Automatically resolves $ref references
• Returns complete schemas in one call
• No manual dereferencing needed

📄 YAML & JSON Support

• Auto-detects .yaml/.yml files
• Works with OpenAPI 2.0, 3.0, 3.1

🔐 Authentication

• Bearer token support
• Custom headers
• Per-request configuration

Installation

npm install @nam088/mcp-swagger-parser

Quick Start

Configure MCP Server

Add to your MCP configuration file:

{
  "mcpServers": {
    "swagger": {
      "command": "npx",
      "args": ["-y", "@nam088/mcp-swagger-parser"],
      "env": {
        "SWAGGER_URL": "http://localhost:3000/docs-json"
      }
    }
  }
}

With Authentication

{
  "env": {
    "SWAGGER_URL": "https://api.example.com/openapi.yaml",
    "SWAGGER_AUTH_TOKEN": "your-bearer-token",
    "SWAGGER_BASE_URL": "https://api.example.com"
  }
}

Available Tools

Discovery Tools (Always Safe)

1. swagger_search_tools

Search for API endpoints by keyword.

{ query: "user" }

2. swagger_get_endpoint_details

Get complete endpoint specification with resolved schemas.

{ method: "POST", path: "/api/users" }

3. swagger_list_tags

List all API categories/tags.

4. swagger_list_endpoints_by_tag

Filter endpoints by tag.

{ tag: "Auth" }

5. swagger_generate_curl

Generate ready-to-use curl command.

{ 
  method: "POST", 
  path: "/api/login",
  body: { email: "[email protected]" }
}

6. swagger_generate_example_request

Generate example request with placeholder values.

{ method: "GET", path: "/api/users/{id}" }

7. swagger_reload

Reload OpenAPI specification from source.

Read-Only Tool (READONLY Mode)

8. swagger_execute_get

Execute GET requests safely (no side effects).

{ 
  path: "/api/users",
  params: { limit: "10" }
}

Write Tools (FULL Mode Only)

9-12. swagger_execute_post/put/patch/delete

Execute write operations (requires FULL mode).

{
  path: "/api/users",
  body: { name: "John" }
}

Configuration Options

| Variable | Description | Default | |----------|-------------|---------| | SWAGGER_URL | OpenAPI spec URL (.json/.yaml) | Required | | SWAGGER_JSON | Direct JSON spec object | Optional | | SWAGGER_BASE_URL | Override base API URL | Auto-detected | | SWAGGER_AUTH_TOKEN | Bearer token | Optional | | SWAGGER_DEFAULT_HEADERS | JSON object of headers | Optional |

Examples

Basic Usage

{
  "SWAGGER_URL": "http://localhost:3000/docs-json"
}

With YAML

{
  "SWAGGER_URL": "https://api.example.com/openapi.yaml"
}

With Authentication

{
  "SWAGGER_URL": "https://api.example.com/api-docs",
  "SWAGGER_AUTH_TOKEN": "eyJhbGc...",
  "SWAGGER_BASE_URL": "https://api.example.com"
}

Programmatic Usage

import { SwaggerParserPlugin } from '@nam088/mcp-swagger-parser';

const plugin = new SwaggerParserPlugin({
  url: 'http://localhost:3000/docs-json',
  authToken: 'your-token',
  baseUrl: 'http://localhost:3000'
});

await plugin.initialize(context);
plugin.register(context);

Features

Automatic Schema Resolution

All $ref references are automatically resolved:

// Before: { "$ref": "#/components/schemas/User" }
// After: { 
//   "type": "object",
//   "properties": {
//     "id": { "type": "string" },
//     "name": { "type": "string" }
//   }
// }

Mode-Based Security

• Discovery tools: Always safe, no restrictions
• GET execution: Safe, available in READONLY mode
• Write operations: Require FULL mode, marked with isWriteTool: true

Development

# Build
npm run build

# Clean
npm run clean

# Test
npm test

License

MIT

Author

Nam088

Repository

https://github.com/nam088/mcp-server