OpenAPI MCP Server

A Model Context Protocol (MCP) server that provides OpenAPI specification linting and documentation rendering capabilities. This server can run in both MCP stdio mode for integration with AI assistants and HTTP mode for web-based access.

Features

• OpenAPI Linting: Comprehensive validation and best practice checking for OpenAPI specifications
• Redoc Integration: Beautiful documentation rendering with Redoc
• Dual Mode Operation:
  • MCP stdio mode for AI assistant integration
  • HTTP mode for web-based API access
• Port Conflict Resolution: Automatic port selection when conflicts occur
• File Format Support: JSON and YAML OpenAPI specifications
• Real-time Validation: Dynamic file reading for always up-to-date results
• Browser-Compatible: Serves OpenAPI specs as HTTP endpoints to avoid Node.js filesystem API issues

Installation

Prerequisites

• Go 1.24.5 or higher
• Make (optional, for using Makefile commands)

From Source

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

# Install dependencies
make deps

# Build the binary
make build

# Install to system (requires sudo)
make install-local

Manual Installation

# Build the binary
go build -o bin/openapi-mcp ./main.go

# Copy to system bin
sudo cp bin/openapi-mcp /usr/local/bin/
sudo chmod +x /usr/local/bin/openapi-mcp

Usage

MCP Mode (Default)

Use with AI assistants and MCP clients:

openapi-mcp

This starts the server in stdio mode, providing two MCP tools:

• lint - Lints OpenAPI files and returns Redoc documentation URLs
• lint_client - Lints OpenAPI files and returns errors without preview

HTTP Mode

Start as a web server:

openapi-mcp -http

Or specify a custom port:

openapi-mcp -http -port 8080

Available Endpoints (HTTP Mode)

• GET /redoc?file={base64-encoded-path} - View OpenAPI documentation with Redoc
• POST /api/lint - Lint an OpenAPI file
• GET /spec/{base64-encoded-path} - Serve OpenAPI spec file
• GET /openapi.json - Server's own OpenAPI specification

Examples

Linting an OpenAPI File

MCP Mode:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "lint",
    "arguments": {
      "file_path": "/path/to/your/openapi.yaml"
    }
  }
}

HTTP Mode:

curl -X POST http://localhost:3000/api/lint \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/your/openapi.yaml"}'

Viewing Documentation

Visit the Redoc URL returned by the lint command, or construct it manually:

# Base64 encode your file path
echo -n "/path/to/your/openapi.yaml" | base64

# Visit http://localhost:3000/redoc?file={encoded-path}

Linting Rules

The server validates OpenAPI specifications and checks for:

Errors

• Missing required fields (info.title, info.version)
• Invalid OpenAPI syntax
• Parsing errors

Warnings

• Missing servers definition
• Missing API description
• Operations without responses

Info

• Missing operation descriptions
• Missing path descriptions
• Missing security schemes

Development

Building

make build

Running Tests

# Run all tests
make test

# Run linter tests only
make test-linter

# Run end-to-end tests
make test-e2e

# Run with coverage
make test-coverage

Development Server

# Run with hot reload (requires air)
make run-dev

# Run MCP server
make run

# Run HTTP server
make run-http

Linting and Formatting

# Run linters
make lint

# Format code
make fmt

# Check (lint + test)
make check

Configuration

Environment Variables

The server automatically detects and uses available ports when the default port is in use.

Command Line Options

• -http - Run in HTTP mode instead of MCP stdio mode
• -port - Port to run HTTP server on (default: 3000)

Port Conflict Resolution

The server automatically handles port conflicts:

1. MCP Mode: If port 3000 is in use, it tries ports 3001-3009
2. HTTP Mode: Fails with an error if the specified port is in use
3. Automatic Detection: Uses net.Listen to check port availability

File Format Support

Supported Extensions

• .json - JSON OpenAPI specifications
• .yaml - YAML OpenAPI specifications
• .yml - YAML OpenAPI specifications

Detection

Files are validated to contain either openapi or swagger keywords to be considered valid OpenAPI specifications.

API Reference

MCP Tools

lint

Lints an OpenAPI file and returns results with Redoc URL.

Parameters:

• file_path (string, required) - Absolute path to OpenAPI file

Returns:

• Lint results with issues and Redoc documentation URL

lint_client

Lints an OpenAPI file and returns errors without preview.

Parameters:

• file_path (string, required) - Absolute path to OpenAPI file

Returns:

• Lint results with detailed issue information

HTTP Endpoints

POST /api/lint

Lint an OpenAPI specification file.

Request Body:

{
  "file_path": "/absolute/path/to/openapi.yaml"
}

Response:

{
  "file_path": "/absolute/path/to/openapi.yaml",
  "issues": [
    {
      "line": 1,
      "column": 1,
      "message": "Missing API description",
      "severity": "warning",
      "rule": "missing-description"
    }
  ],
  "has_errors": false,
  "preview_id": "http://localhost:3000/redoc?file=..."
}

GET /redoc?file={base64-path}

Render OpenAPI documentation with Redoc.

Parameters:

• file (query, required) - Base64 encoded absolute file path

Response: HTML page with Redoc documentation

Troubleshooting

Common Issues

1. Port already in use: The server automatically finds available ports
2. File not found: Ensure file paths are absolute
3. Invalid OpenAPI: Check file contains openapi or swagger keywords
4. Permission denied: Use sudo for system-wide installation
5. "lstatSync is not a function" error: Fixed by serving spec files as HTTP endpoints instead of data URLs

Installation Issues

The make install-local command requires sudo privileges:

# You'll be prompted for your password
make install-local

# Or install manually
sudo cp bin/openapi-mcp /usr/local/bin/
sudo chmod +x /usr/local/bin/openapi-mcp

Debugging

Enable verbose logging by checking server output. The server logs:

• Port selection and conflicts
• File access attempts
• Linting results
• HTTP request processing
• Redoc rendering requests

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run make check to verify
6. Submit a pull request

License

[Add your license information here]

Changelog

v1.0.0

• Initial release
• MCP stdio mode support
• HTTP server mode
• OpenAPI linting and validation
• Redoc documentation rendering
• Port conflict resolution
• Comprehensive test suite