mikedarke/mcp-server-openapi-inspector

OpenAPI Inspector MCP Server

A Model Context Protocol (MCP) server that provides comprehensive capabilities for inspecting, analyzing, and working with OpenAPI specification documents. This server enables AI agents to load, validate, and extract detailed information from OpenAPI/Swagger specifications.

Features

• Load OpenAPI specs from local files or URLs (JSON/YAML formats)
• Comprehensive inspection of endpoints, schemas, and parameters
• Validation of OpenAPI specifications
• Search functionality for finding specific operations
• Multi-spec support with aliasing for managing multiple APIs
• Detailed endpoint analysis including request/response schemas
• Schema exploration for understanding data models

Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Quick Setup

1. Clone and setup the project:

   git clone <repository-url>
   cd openapi-inspector
   npm install
   npm run build
   

2. Test the server:

   npm test
   

3. Run the server:

   npm start
   

Basic Usage Example

Once the server is running, you can use it with any MCP-compatible client. Here's a quick example of how to use the tools:

1. Load an OpenAPI specification:

   {
     "tool": "load_openapi_spec",
     "arguments": {
       "source": "./example-api.yaml",
       "alias": "my-api"
     }
   }
   

2. Explore the API:

   {
     "tool": "list_endpoints",
     "arguments": {
       "spec_id": "my-api"
     }
   }
   

Installation

For development or manual setup:

npm install
npm run build

Usage

The server is designed to be used with MCP-compatible clients. It provides several tools for OpenAPI inspection:

Available Tools

load_openapi_spec

Load and parse an OpenAPI specification from a file path or URL.

Parameters:

• source (required): File path or URL to the OpenAPI specification
• alias (optional): Alias to reference this spec in other operations

Example:

{
  "source": "./api-spec.yaml",
  "alias": "my-api"
}

list_loaded_specs

List all currently loaded OpenAPI specifications.

get_spec_info

Get basic information about a loaded OpenAPI specification.

Parameters:

• spec_id (required): ID or alias of the loaded specification

list_endpoints

List all endpoints/paths in an OpenAPI specification with optional filtering.

Parameters:

• spec_id (required): ID or alias of the loaded specification
• method (optional): Filter by HTTP method (GET, POST, etc.)
• tag (optional): Filter by tag

get_endpoint_details

Get detailed information about a specific endpoint including parameters, request body, and responses.

Parameters:

• spec_id (required): ID or alias of the loaded specification
• path (required): The endpoint path (e.g., /users/{id})
• method (required): HTTP method (GET, POST, PUT, DELETE, etc.)

get_schema_details

Get details about a specific schema/model definition.

Parameters:

• spec_id (required): ID or alias of the loaded specification
• schema_name (required): Name of the schema/component to inspect

validate_spec

Validate an OpenAPI specification for errors and warnings.

Parameters:

• spec_id (required): ID or alias of the loaded specification

search_operations

Search for operations by keyword in summary, description, or operationId.

Parameters:

• spec_id (required): ID or alias of the loaded specification
• query (required): Search query to match against operation details

Configuration

MCP Client Configuration

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "openapi-inspector": {
      "command": "node",
      "args": ["/path/to/openapi-inspector/dist/index.js"]
    }
  }
}

Claude Desktop Configuration

For Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "openapi-inspector": {
      "command": "node",
      "args": ["/path/to/openapi-inspector/dist/index.js"]
    }
  }
}

Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

# Clone the repository
git clone <repository-url>
cd openapi-inspector

# Install dependencies
npm install

# Build the project
npm run build

# Start development mode with watch
npm run dev

Project Structure

openapi-inspector/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript output
├── package.json          # Project dependencies and scripts
├── tsconfig.json        # TypeScript configuration
└── README.md            # Project documentation

Example Workflow

1. Load an OpenAPI specification:

   {
     "tool": "load_openapi_spec",
     "arguments": {
       "source": "https://petstore.swagger.io/v2/swagger.json",
       "alias": "petstore"
     }
   }
   

2. Explore available endpoints:

   {
     "tool": "list_endpoints",
     "arguments": {
       "spec_id": "petstore"
     }
   }
   

3. Get detailed information about a specific endpoint:

   {
     "tool": "get_endpoint_details",
     "arguments": {
       "spec_id": "petstore",
       "path": "/pet/{petId}",
       "method": "GET"
     }
   }
   

4. Examine a data model:

   {
     "tool": "get_schema_details",
     "arguments": {
       "spec_id": "petstore",
       "schema_name": "Pet"
     }
   }
   

5. Search for specific operations:

   {
     "tool": "search_operations",
     "arguments": {
       "spec_id": "petstore",
       "query": "pet"
     }
   }
   

Supported Formats

• OpenAPI 3.0+ (JSON/YAML)
• Swagger 2.0 (JSON/YAML)
• Local files and remote URLs

Error Handling

The server provides detailed error messages for common issues:

• Invalid file paths or URLs
• Malformed OpenAPI specifications
• Missing specifications or endpoints
• Validation errors

Dependencies

• @modelcontextprotocol/sdk - MCP SDK for TypeScript (v1.16.0+)
• @apidevtools/swagger-parser - OpenAPI/Swagger parser and validator
• openapi-types - TypeScript types for OpenAPI specifications
• yaml - YAML parsing support
• zod - TypeScript-first schema declaration and validation

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.