# @abumalick/openapi-mcp

MCP (Model Context Protocol) server that enables LLMs to explore OpenAPI specifications. Load any OpenAPI spec and query its endpoints, parameters, request bodies, and response schemas through natural conversation.

## Installation

```bash
npm install -g @abumalick/openapi-mcp
```

## Configuration

You can pre-load OpenAPI specs at startup using the `--spec` or `-s` flag with format `alias=url`.

### OpenCode

Add to your OpenCode config (`~/.opencode/config.json`):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openapi": {
      "type": "local",
      "command": ["npx", "-y", "@abumalick/openapi-mcp"],
      "enabled": true
    }
  }
}
```

With pre-loaded specs:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openapi": {
      "type": "local",
      "command": [
        "npx", "-y", "@abumalick/openapi-mcp",
        "--spec", "petstore=https://petstore3.swagger.io/api/v3/openapi.yaml",
        "--spec", "myapi=https://api.example.com/openapi.json"
      ],
      "enabled": true
    }
  }
}
```

Learn more about [configuring MCP servers in OpenCode](https://opencode.ai/docs/mcp-servers).

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@abumalick/openapi-mcp"]
    }
  }
}
```

With pre-loaded specs:

```json
{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": [
        "-y", "@abumalick/openapi-mcp",
        "--spec", "petstore=https://petstore3.swagger.io/api/v3/openapi.yaml"
      ]
    }
  }
}
```

## Example Workflow

With pre-loaded specs, the LLM can immediately query them:

```
User: What specs are available?
Assistant: [calls openapi_list_specs] -> shows petstore is loaded

User: What endpoints are available for pets?
Assistant: [calls openapi_list_endpoints with alias="petstore", tag="pet"]

User: Show me details about the GET /pet/{petId} endpoint
Assistant: [calls openapi_get_endpoint with alias="petstore", method="GET", path="/pet/{petId}"]
```

Without pre-loading, first load the spec:

```
User: Load the Petstore API spec
Assistant: [calls openapi_load with source="https://petstore3.swagger.io/api/v3/openapi.yaml", alias="petstore"]
```

## Tools

### openapi_list_specs

List all currently loaded OpenAPI specs. Use this to see what's available.

```json
{}
```

Returns:
```json
{
  "specs": [
    { "alias": "petstore", "title": "Swagger Petstore", "version": "1.0.0", "endpointCount": 19 }
  ]
}
```

### openapi_load

Load an OpenAPI spec from URL or file path. Only needed if spec is not pre-loaded.

```json
{
  "source": "https://api.example.com/openapi.yaml",
  "alias": "example"
}
```

### openapi_list_endpoints

List endpoints with optional filtering.

```json
{
  "alias": "example",
  "tag": "users",
  "search": "create"
}
```

### openapi_get_endpoint

Get detailed endpoint information.

```json
{
  "alias": "example",
  "method": "POST",
  "path": "/users"
}
```

## Supported OpenAPI Versions

- OpenAPI 3.0.x
- OpenAPI 3.1.x

Note: Swagger 2.0 specs should be converted to OpenAPI 3.x format first.

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Development mode
npm run dev
```

## License

MIT