OpenAPI MCP Server

A Model Context Protocol (MCP) server for parsing OpenAPI 3.0 specifications and extracting API metadata. Provides 7 tools for spec management, endpoint discovery, and schema extraction - complementing code-first analysis when OpenAPI specifications are available.

What's New in 1.4.0

Documentation Alignment

• Workflow Consistency: Fully aligned with sar-test-mcp v1.4.0 and http-capture-mcp v1.4.0
• Role Clarity: Enhanced guidance on complementary role in sequential test generation workflow
• Updated Examples: All integration examples updated to v1.4.0

What's New in 1.2.0 (Previous Release)

Documentation & Alignment

• Generic Examples: All examples now use generic placeholders applicable across all IFS Cloud modules
• Workflow Consistency: Fully aligned with sar-test-mcp v1.2.0 and http-capture-mcp v1.2.0
• Role Clarity: Enhanced guidance on complementary role in code-first test generation

What's New in 1.1.0 (Previous Release)

Workflow Alignment

• Fully aligned with sar-test-mcp v1.1.0 and http-capture-mcp v1.1.0
• Integrated with enhanced self-learning system and Phase 0 workflow
• Consistent with 15-phase test generation workflow

Role Clarification

• Complementary to code-first analysis from sar-test-mcp
• Provides API metadata when OpenAPI specs are available
• Useful for verifying entity schemas and endpoint structures
• Supports schema validation against projection definitions

Documentation Updates

• Updated integration examples for v1.1.0 MCP configuration
• Enhanced IFS Cloud-specific use case guidance

What's New in 9.0.0

Alignment & Documentation

✅ Complete System Alignment

• Fully aligned with sar-test-mcp v9.0.0 and http-capture-mcp v9.0.0
• Consistent with updated workflow in SARDevAgent
• All three MCPs work seamlessly together in the 13-phase (updated to 15-phase in v12.0.0) test generation workflow

📚 Documentation Updates

• Updated integration examples to reflect current architecture
• Clarified role in code-first test generation approach
• Enhanced troubleshooting guide

What's New in 8.0.0

Documentation & Setup

📚 Complete Documentation Overhaul

• Comprehensive README with accurate feature descriptions
• Clear integration instructions for all platforms
• Detailed troubleshooting guide
• Complete tool reference with examples

🎯 Purpose Clarification

• Designed for OpenAPI 3.0 specification parsing
• Complements code-first approach in sar-test-mcp
• Provides API metadata when OpenAPI specs are available
• 7 focused tools for spec management, endpoint discovery, and schema extraction

Features

📖 OpenAPI Parsing

• Load specs from local files or URLs
• Support for JSON and YAML formats
• Automatic $ref resolution
• Multi-spec management

🔍 Endpoint Discovery

• List all API endpoints with filtering
• Filter by tags, paths, or methods
• Search operations by query or entity
• Get complete operation details

📊 Schema Extraction

• Extract entity schemas with data types
• Identify required fields and constraints
• Include default values and examples
• Resolve nested references

Use Cases

1. API Discovery: When OpenAPI specs are available for IFS Cloud services
2. Schema Validation: Verify entity structures and field types
3. Endpoint Mapping: Map service endpoints to test requirements
4. Documentation: Extract API documentation for test planning
5. Complementary Analysis: Use alongside code analysis from sar-test-mcp

Integration

Works seamlessly with sar-test-mcp and http-capture-mcp:

• sar-test-mcp for code-first analysis (primary approach)
• openapi-mcp for API spec metadata (when available)
• http-capture-mcp for browser verification (when needed)

Prerequisites

• Node.js v20.0.0 or higher
• npm or pnpm package manager
• OpenAPI 3.0 specification files (JSON or YAML)

Package Information

This package is fully bundled - all internal dependencies are included.

| Property | Value | |----------|-------| | Bundle Size | ~35 KB | | Node.js | ≥20.0.0 | | Module Type | ESM | | TypeScript | Included |

Peer Dependencies

The following dependencies are required and must be installed separately (or will be auto-installed):

# Auto-installed when using npx
@modelcontextprotocol/sdk ^1.0.0

Integration Options

Choose the integration method that works best for your workflow:

Option 1: VS Code Integration

Integrate the MCP server into VS Code to use API discovery tools directly in your editor.

Step 1: Create the MCP configuration folder

In your project root directory, create a .vscode folder:

mkdir .vscode

Step 2: Create the MCP configuration file

Inside the .vscode folder, create a file named mcp.json with the following content:

{
  "servers": {
    "openapi": {
      "command": "npx",
      "args": [
        "-y",
        "@dilina0914/[email protected]"
      ],
      "env": {
        "LOG_LEVEL": "info",
        "AUDIT_LOG_ENABLED": "true"
      }
    }
  }
}

Step 3: Configure environment variables

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | LOG_LEVEL | Logging level (debug, info, warn, error) | No | info | | AUDIT_LOG_ENABLED | Enable audit logging | No | true | | AUDIT_LOG_DIR | Directory for audit logs | No | ./logs/audit |

Step 4: Restart VS Code

Close and reopen VS Code to load the MCP server configuration.

Option 2: Cursor IDE Integration

Cursor IDE has built-in support for MCP servers, making integration straightforward.

Step 1: Open Cursor Settings

1. Open Cursor IDE
2. Go to Settings (File > Preferences > Settings or Ctrl/Cmd + ,)
3. Search for "MCP" or navigate to the MCP configuration section

Step 2: Add MCP Server Configuration

In the MCP settings, add a new server with the following configuration:

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": [
        "-y",
        "@dilina0914/[email protected]"
      ],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Step 3: Save and Restart

Save the configuration and restart Cursor IDE to activate the MCP server.

Option 3: Claude Desktop Integration

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@dilina0914/[email protected]"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Option 4: Local Development

Run the server directly for development or testing.

Step 1: Install the package

npm install @dilina0914/openapi-mcp

Step 2: Configure environment variables

Windows (PowerShell):

$env:LOG_LEVEL = "info"
$env:AUDIT_LOG_ENABLED = "true"

Windows (Command Prompt):

set LOG_LEVEL=info
set AUDIT_LOG_ENABLED=true

Linux/macOS:

export LOG_LEVEL="info"
export AUDIT_LOG_ENABLED="true"

Step 3: Run the server

npx @dilina0914/openapi-mcp

Quick Troubleshooting

Spec Not Found

Error: Spec not found: <specId>. Use loadSpec first.

Solution:

• Load the spec first using the loadSpec tool
• Verify the specId returned from loadSpec
• Specs are stored in memory and lost when server restarts

Invalid OpenAPI Spec

Error: Failed to parse OpenAPI spec

Solution:

• Verify the file is valid JSON or YAML
• Ensure it's a valid OpenAPI 3.0 specification
• Check file path or URL accessibility

Schema Not Found

Error: Schema not found: <name>

Solution:

• Use listSchemas to see available schemas
• Schema names are case-sensitive
• Verify the schema exists in the spec

File Access Errors

Error: ENOENT: no such file or directory

Solution:

• Use absolute paths for local files
• Verify file permissions
• For URLs, check network connectivity

What's Included

MCP Tools (7 total)

Spec Management

| Tool | Description | |------|-------------| | loadSpec | Load an OpenAPI spec from file path or URL | | unloadSpec | Unload a previously loaded spec from memory |

Endpoint Discovery

| Tool | Description | |------|-------------| | listEndpoints | List all API endpoints with filtering options | | getOperationDetails | Get full operation details by ID or path/method | | searchOperations | Search operations by query, tag, or entity name |

Schema Extraction

| Tool | Description | |------|-------------| | listSchemas | List all schemas/entities defined in the spec | | getEntitySchema | Extract detailed entity schema with data types |

Supported Features

| Feature | Description | |---------|-------------| | OpenAPI 3.0 | Full support for OpenAPI 3.0 specifications | | JSON & YAML | Parse both JSON and YAML spec formats | | File & URL | Load specs from local files or remote URLs | | $ref Resolution | Automatic resolution of schema references | | Multi-Spec | Manage multiple specs simultaneously |

Output Information

The MCP extracts and provides:

• API title, version, and description
• Endpoints with method, path, summary, and tags
• Operation parameters (path, query, header, cookie)
• Request body schemas with content types
• Response schemas for all status codes
• Entity schemas with properties, types, and constraints
• Required fields and default values
• Example values when available

Tool Examples

Load a Spec

{
  "tool": "loadSpec",
  "arguments": {
    "source": "C:\\specs\\my-api.yaml",
    "specId": "my-api"
  }
}

Response:

{
  "specId": "my-api",
  "title": "Cloud ERP API",
  "version": "1.0.0",
  "endpointCount": 245,
  "schemaCount": 89
}

List Endpoints

{
  "tool": "listEndpoints",
  "arguments": {
    "specId": "my-api",
    "tag": "CustomerOrder",
    "methods": ["GET", "POST"]
  }
}

Response:

{
  "endpoints": [
    {
      "path": "/api/v1/customer-orders",
      "method": "GET",
      "summary": "List all customer orders",
      "tags": ["CustomerOrder"]
    },
    {
      "path": "/api/v1/customer-orders",
      "method": "POST",
      "summary": "Create a new customer order",
      "tags": ["CustomerOrder"]
    }
  ],
  "totalCount": 2
}

Get Entity Schema

{
  "tool": "getEntitySchema",
  "arguments": {
    "specId": "my-api",
    "schemaName": "CustomerOrder",
    "resolveRefs": true,
    "includeExamples": true
  }
}

Response:

{
  "schema": {
    "name": "CustomerOrder",
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "description": "Unique order identifier"
      },
      "customerId": {
        "type": "string",
        "required": true
      },
      "orderDate": {
        "type": "string",
        "format": "date-time"
      }
    },
    "required": ["customerId"]
  }
}

Search Operations

{
  "tool": "searchOperations",
  "arguments": {
    "specId": "my-api",
    "query": "create customer",
    "limit": 5
  }
}

Get Operation Details

{
  "tool": "getOperationDetails",
  "arguments": {
    "specId": "my-api",
    "path": "/api/v1/customer-orders",
    "method": "POST"
  }
}

List All Schemas

{
  "tool": "listSchemas",
  "arguments": {
    "specId": "my-api"
  }
}

Response:

{
  "schemas": [
    { "name": "CustomerOrder", "type": "object", "description": "Customer order entity" },
    { "name": "OrderLine", "type": "object", "description": "Order line item" },
    { "name": "Customer", "type": "object", "description": "Customer entity" }
  ],
  "totalCount": 3
}

Security Features

• Audit Logging: Complete audit trail of spec access
• Input Validation: File paths and parameters are validated
• Memory Management: Specs can be unloaded to free memory
• No External Calls: Specs are parsed locally (URLs are fetched once)

License

MIT

Links

• GitHub Repository: https://github.com/dilinaweerasinghe/integration-testing-mcp
• npm Package: https://www.npmjs.com/package/@dilina0914/openapi-mcp
• Issues: https://github.com/dilinaweerasinghe/integration-testing-mcp/issues

Support

Open an issue on the GitHub repository for support.