Openapi Analyzer MCP

🚀 OpenAPI Analyzer MCP Server

A powerful Model Context Protocol (MCP) server designed for analyzing OpenAPI specifications in conjunction with Claude Desktop and other LLM clients. This server empowers users to conduct natural language queries regarding API structures, endpoints, and schemas, while also facilitating the identification of inconsistencies across multiple OpenAPI specs.

🚀 Quick Start

The OpenAPI Analyzer MCP Server offers a seamless way to interact with your OpenAPI specifications. First, install the server as described in the Installation section. Then, configure it according to your needs using the options in the Configuration section. Once set up, you can start making natural language queries in Claude Desktop to explore your API ecosystem.

✨ Features

🎯 Smart Discovery System

• 📡 API Registry Support: Automatically discovers APIs from apis.json registries, with support for over 30 APIs.
• 🔗 URL-Based Loading: Loads specifications from individual URLs, with automatic fallback mechanisms.
• 📁 Local File Support: Enables traditional folder-based specification loading, supporting multiple formats.
• 🔄 Priority System: Follows a discovery order of URL → Individual URLs → Local folder, with intelligent fallback.

🔍 Advanced Analysis

• 📊 Bulk Analysis: Capable of loading and analyzing over 90 OpenAPI specification files simultaneously.
• 🔍 Smart Search: Allows users to find endpoints across all APIs using natural language queries.
• 📈 Comprehensive Stats: Generates detailed statistics about your API ecosystem.
• 🔧 Inconsistency Detection: Identifies mismatches in authentication schemes and naming conventions.
• 📋 Schema Comparison: Compares schemas with the same name across different APIs.
• ⚡ Fast Queries: Utilizes in-memory indexing for lightning-fast responses.

🌐 Universal Compatibility

• Multi-Format Support: Supports JSON, YAML, and YML specifications.
• Version Support: Compatible with OpenAPI 2.0, 3.0, and 3.1 specifications.
• Remote & Local: Works with URLs, API registries, and local files.
• Source Tracking: Provides clear information on where each API spec was loaded from.

📦 Installation

Option 1: Install from npm

npm install openapi-analyzer-mcp

Option 2: Build from source

git clone https://github.com/sureshkumars/openapi-analyzer-mcp.git
cd openapi-analyzer-mcp
npm install
npm run build

⚙️ Configuration

🎯 Smart Discovery Options

The OpenAPI Analyzer supports three discovery methods with intelligent priority fallback:

1. 🏆 Priority 1: API Registry (OPENAPI_DISCOVERY_URL)
2. 🥈 Priority 2: Individual URLs (OPENAPI_SPEC_URLS)
3. 🥉 Priority 3: Local Folder (OPENAPI_SPECS_FOLDER)

Claude Desktop Setup

Find your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Configuration Examples

🌟 Option 1: API Registry Discovery (Recommended)

Ideal for companies with centralized API registries:

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://docs.company.com/apis.json"
      }
    }
  }
}

🔗 Option 2: Individual API URLs

Load specific APIs from direct URLs:

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx", 
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_SPEC_URLS": "https://api.example.com/v1/openapi.yaml,https://api.example.com/v2/openapi.yaml,https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

📁 Option 3: Local Folder

A traditional approach for local specification files:

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_SPECS_FOLDER": "/absolute/path/to/your/openapi-specs"
      }
    }
  }
}

🔄 Option 4: Multi-Source with Fallback

Offers ultimate flexibility by trying all methods with intelligent fallback:

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://docs.company.com/apis.json",
        "OPENAPI_SPEC_URLS": "https://legacy-api.com/spec.yaml,https://external-api.com/spec.json",
        "OPENAPI_SPECS_FOLDER": "/path/to/local/specs"
      }
    }
  }
}

🏢 Real-World Examples

Company with API Registry:

{
  "mcpServers": {
    "company-apis": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://api.company.com/registry/apis.json"
      }
    }
  }
}

Multiple API Sources:

{
  "mcpServers": {
    "multi-apis": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_SPEC_URLS": "https://petstore.swagger.io/v2/swagger.json,https://api.example.com/v1/openapi.yaml"
      }
    }
  }
}

🔧 Environment Variables

⚠️ Important Note

• At least one environment variable must be set.
• The system tries sources in priority order and stops at the first success.
• Always use absolute paths for OPENAPI_SPECS_FOLDER.
• Supports JSON, YAML, and YML formats for all sources.

💻 Usage Examples

🚀 Smart Discovery Queries

API Registry Discovery

"Load all APIs from the company registry and show me an overview"
"Discover APIs from the configured registry and analyze their authentication patterns"
"What APIs are available in our API registry?"
"Show me where my specs were loaded from"

Cross-API Analysis

"Load all my OpenAPI specs and give me a comprehensive summary"
"How many APIs do I have and what's the total number of endpoints?"
"Compare authentication schemes across all loaded APIs"
"Which APIs are using different versions of the same schema?"

Search and Discovery

"Show me all POST endpoints for user creation across all APIs"
"Find all endpoints related to authentication across all loaded APIs"
"Which APIs have pagination parameters?"
"Search for endpoints that handle file uploads"
"Find all APIs that use the 'User' schema"

Analysis and Comparison

"What authentication schemes are used across my APIs?"
"Which APIs have inconsistent naming conventions?"
"Compare the User schema across different APIs"
"Show me APIs that are still using version 1.0"

Statistics and Insights

"Generate comprehensive statistics about my API ecosystem"
"Which HTTP methods are most commonly used?"
"What are the most common path patterns?"
"Show me version distribution across my APIs"

📚 Documentation

🔧 Available Tools

The MCP server provides the following tools for programmatic access:

📁 Project Structure

openapi-analyzer-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── tests/               # Comprehensive test suite
│   ├── analyzer.test.ts # Core functionality tests
│   ├── server.test.ts   # MCP server tests  
│   ├── validation.test.ts # Environment tests
│   ├── setup.ts         # Test configuration
│   └── fixtures/        # Test data files
├── dist/                # Compiled JavaScript
├── coverage/            # Test coverage reports
├── examples/            # Example configurations
│   ├── claude_desktop_config.json
│   └── sample-openapi.json
├── vitest.config.ts     # Test configuration
├── package.json
├── tsconfig.json
└── README.md

Note: You don't need an openapi-specs folder in this repository. Point OPENAPI_SPECS_FOLDER to wherever your actual OpenAPI files are located.

🔍 Example Output

🎯 Smart Discovery Results

Load Sources Information

[
  {
    "type": "discovery",
    "url": "https://api.company.com/registry/apis.json",
    "count": 12,
    "metadata": {
      "name": "Company APIs",
      "description": "Collection of company API specifications",
      "total_apis": 12
    }
  }
]

Registry Discovery Success

{
  "totalApis": 12,
  "totalEndpoints": 247,
  "loadedFrom": "API Registry",
  "discoveryUrl": "https://api.company.com/registry/apis.json",
  "apis": [
    {
      "filename": "User Management API",
      "title": "User Management API", 
      "version": "2.1.0",
      "endpointCount": 18,
      "source": "https://docs.company.com/user-api.yaml"
    },
    {
      "filename": "Product Catalog API",
      "title": "Product Catalog API",
      "version": "1.5.0", 
      "endpointCount": 32,
      "source": "https://docs.company.com/product-api.yaml"
    }
  ]
}

📊 API Statistics

{
  "totalApis": 12,
  "totalEndpoints": 247,
  "methodCounts": {
    "GET": 98,
    "POST": 67,
    "PUT": 45,
    "DELETE": 37
  },
  "versions": {
    "1.0.0": 8,
    "2.0.0": 3,
    "3.1.0": 1
  },
  "commonPaths": {
    "/api/v1/users/{id}": 8,
    "/api/v1/orders": 6,
    "/health": 12
  }
}

Search Results

[
  {
    "filename": "user-api.json",
    "api_title": "User Management API",
    "path": "/api/v1/users",
    "method": "POST",
    "summary": "Create a new user",
    "operationId": "createUser"
  },
  {
    "filename": "admin-api.json", 
    "api_title": "Admin API",
    "path": "/admin/users",
    "method": "POST",
    "summary": "Create user account",
    "operationId": "adminCreateUser"
  }
]

🏗️ Creating Your Own API Registry

Standard APIs.json Format

Create a file at https://your-domain.com/apis.json:

{
  "name": "Your Company APIs",
  "description": "Collection of all our API specifications",
  "url": "https://your-domain.com",
  "apis": [
    {
      "name": "User API",
      "baseURL": "https://api.your-domain.com/users",
      "properties": [
        {
          "type": "Swagger",
          "url": "https://docs.your-domain.com/user-api.yaml"
        }
      ]
    },
    {
      "name": "Orders API", 
      "baseURL": "https://api.your-domain.com/orders",
      "properties": [
        {
          "type": "OpenAPI",
          "url": "https://docs.your-domain.com/orders-api.json"
        }
      ]
    }
  ]
}

Custom Registry Format

Or use the simpler custom format:

{
  "name": "Your Company APIs",
  "description": "Our API registry",
  "apis": [
    {
      "name": "User API",
      "version": "v2",
      "spec_url": "https://docs.your-domain.com/user-api.yaml",
      "docs_url": "https://docs.your-domain.com/user-api",
      "status": "stable",
      "tags": ["auth", "users"]
    }
  ]
}

🚨 Troubleshooting

Tools not appearing in Claude Desktop

1. Verify environment variables are set - At least one source must be configured.
2. Check that URLs are accessible - Test discovery URLs and spec URLs manually.
3. Restart Claude Desktop completely after configuration changes.
4. Check network connectivity for remote API registries.
5. Verify file formats - Supports JSON, YAML, and YML.

Common Error Messages

Smart Discovery Errors

• "❌ Error: No OpenAPI source configured": Set at least one of OPENAPI_DISCOVERY_URL, OPENAPI_SPEC_URLS, or OPENAPI_SPECS_FOLDER.
• "⚠️ Warning: Failed to load from discovery URL": Check if the registry URL is accessible and returns valid JSON.
• "Invalid registry format: missing apis array": Your APIs.json file must have an apis array.
• "No OpenAPI spec URL found": API entries must have either spec_url or properties with OpenAPI/Swagger type.

Traditional Errors

• "❌ Error: OPENAPI_SPECS_FOLDER does not exist": The specified directory doesn't exist.
• "❌ Error: OPENAPI_SPECS_FOLDER is not a directory": The path points to a file, not a directory.
• "❌ Error: No read permission for OPENAPI_SPECS_FOLDER": Check folder permissions.
• "⚠️ Warning: No OpenAPI specification files found": Directory exists but contains no supported files.
• "⚠️ Skipping [file]: Invalid format": File is not valid JSON/YAML or malformed OpenAPI spec.

Debug Mode

Set NODE_ENV=development to see detailed logging:

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "OPENAPI_SPECS_FOLDER": "/path/to/specs",
        "NODE_ENV": "development"
      }
    }
  }
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

git clone https://github.com/sureshkumars/openapi-analyzer-mcp.git
cd openapi-analyzer-mcp
npm install
npm run build
npm run dev  # Start in development mode

Running Tests

This project includes a comprehensive test suite with 46+ tests covering all functionality:

# Run all tests
npm test

# Run tests in watch mode (re-runs on file changes)
npm run test:watch

# Run tests with coverage report
npm run test:coverage

Test Coverage

The test suite provides extensive coverage with 100% test success rate:

• ✅ 46 tests passing with 66.79% statement coverage and 100% function coverage.
• Unit tests for the OpenAPIAnalyzer class (30 tests) - covers all loading methods and analysis features.
• Integration tests for MCP server configuration (8 tests) - validates all tools and exports.
• Validation tests for environment setup and error handling (8 tests) - tests all discovery methods.

New in v1.2.0:

• ✅ Smart discovery testing - URL loading, API registry parsing, fallback mechanisms.
• ✅ Constructor-based testing - Flexible test configuration without environment variables.
• ✅ Remote spec mocking - Full coverage of HTTP-based spec loading.
• ✅ Backward compatibility - All existing functionality preserved.

Test Structure

tests/
├── analyzer.test.ts      # Core OpenAPIAnalyzer functionality tests
├── server.test.ts        # MCP server configuration tests
├── validation.test.ts    # Environment validation tests
├── setup.ts             # Test configuration
└── fixtures/            # Sample test data
    ├── sample-api.json
    ├── another-api.json
    └── invalid-api.json

What's Tested

• ✅ OpenAPI spec loading (valid/invalid files, JSON parsing).
• ✅ Search functionality (by path, method, summary, operationId).
• ✅ Statistics generation (method counts, versions, common paths).
• ✅ Schema comparison (cross-API schema analysis).
• ✅ Inconsistency detection (authentication schemes).
• ✅ Error handling (missing env vars, file permissions).
• ✅ Edge cases (empty directories, malformed JSON).

Test Technology

• Vitest - Fast test framework with TypeScript support.
• Comprehensive mocking - File system operations and console output.
• Type safety - Full TypeScript integration with proper interfaces.

🆕 Changelog

Version 1.2.0 - Smart Discovery System

Released: September 2025

🎯 Major Features

• 🚀 Smart Discovery System: Revolutionary API discovery with priority-based fallback.
• 📡 API Registry Support: Full support for apis.json format and custom registries.
• 🔗 URL-Based Loading: Load specs directly from individual URLs.
• 🔄 Intelligent Fallback: Discovery URL → Individual URLs → Local folder priority system.
• 🏷️ Source Tracking: New get_load_sources tool shows where specs were loaded from.

✨ Real-World Integration

• 🏢 Production Ready: Successfully tested with 30+ production APIs from various registries.
• 📊 Bulk Processing: Load 90+ APIs from registries in seconds.
• 🌐 Universal Format Support: JSON, YAML, YML from any source (remote or local).

🧪 Enhanced Testing

• ✅ 46 tests passing with 100% success rate.
• 📈 Improved coverage: 66.79% statement coverage, 100% function coverage.
• 🔧 Constructor-based testing: Flexible test configuration.
• 🔗 Remote spec mocking: Full HTTP-based loading test coverage.

🔧 Developer Experience

• ⚡ Zero Breaking Changes: Full backward compatibility maintained.
• 📚 Comprehensive Documentation: Updated with real-world examples.
• 🏗️ Registry Setup Guide: Instructions for creating your own APIs.json registry.
• 🚨 Enhanced Error Handling: Better error messages and graceful fallbacks.

Version 1.1.0 - YAML Support & Enhanced Analysis

• Added YAML/YML format support using @apidevtools/swagger-parser.
• Enhanced schema comparison and inconsistency detection.
• Improved error handling and validation.

Version 1.0.0 - Initial Release

• Core OpenAPI analysis functionality.
• Local folder-based spec loading.
• MCP server implementation with 6 core tools.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with the Model Context Protocol SDK.
• Supports OpenAPI specifications as defined by the OpenAPI Initiative.
• Compatible with Claude Desktop and other MCP clients.

Made with ❤️ for API developers and documentation teams

If you find this tool helpful, please consider giving it a ⭐ on GitHub!