npm package: @nam088/mcp-swagger-parser
Description: Enhanced OpenAPI/Swagger MCP plugin with 12 tools, YAML support, and auto-resolved schemas
Author: Nam088
Latest version: 3.0.8

# @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

```bash
npm install @nam088/mcp-swagger-parser
```

## Quick Start

### Configure MCP Server

Add to your MCP configuration file:

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

### With Authentication

```json
{
  "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.
```typescript
{ query: "user" }
```

#### 2. `swagger_get_endpoint_details`
Get complete endpoint specification with resolved schemas.
```typescript
{ method: "POST", path: "/api/users" }
```

#### 3. `swagger_list_tags`
List all API categories/tags.

#### 4. `swagger_list_endpoints_by_tag`
Filter endpoints by tag.
```typescript
{ tag: "Auth" }
```

#### 5. `swagger_generate_curl`
Generate ready-to-use curl command.
```typescript
{ 
  method: "POST", 
  path: "/api/login",
  body: { email: "test@example.com" }
}
```

#### 6. `swagger_generate_example_request`
Generate example request with placeholder values.
```typescript
{ 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).
```typescript
{ 
  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).
```typescript
{
  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
```json
{
  "SWAGGER_URL": "http://localhost:3000/docs-json"
}
```

### With YAML
```json
{
  "SWAGGER_URL": "https://api.example.com/openapi.yaml"
}
```

### With Authentication
```json
{
  "SWAGGER_URL": "https://api.example.com/api-docs",
  "SWAGGER_AUTH_TOKEN": "eyJhbGc...",
  "SWAGGER_BASE_URL": "https://api.example.com"
}
```

## Programmatic Usage

```typescript
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:

```typescript
// 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

```bash
# Build
npm run build

# Clean
npm run clean

# Test
npm test
```

## License

MIT

## Author

Nam088

## Repository

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