HelloWorld
登录
m

mini-openapi-mcp

api-testingdeveloper-toolsapp-automation

178 查看 · 2026-07-07 更新

OpenAPI MCP Server (JavaScript)

A pure JavaScript implementation of a Model Context Protocol (MCP) server that transforms OpenAPI 3.x specifications into MCP tools, enabling Large Language Models (LLMs) to interact with REST APIs through the standardized MCP protocol.

Features

  • Pure JavaScript: Built with Node.js and ES modules
  • OpenAPI 3.x Support: Automatically converts OpenAPI specifications into MCP tools
  • Bearer Token Authentication: Supports bearer token authentication for API requests
  • All HTTP Methods: Supports GET, POST, PUT, DELETE, PATCH, OPTIONS, and HEAD
  • Configurable Base URL: Accept custom API base URLs
  • Parameter Validation: Validates tool parameters against OpenAPI schemas
  • Error Handling: Comprehensive error handling and reporting
  • CLI Interface: Easy-to-use command-line interface

Installation

npm install

Usage

Quick Start

  1. Validate your OpenAPI specification:
node src/index.js validate -s UserQueueList.json
  1. Start the MCP server:
node src/index.js serve -s UserQueueList.json -b https://api.example.com -t your-bearer-token

Command Line Options

serve - Start the MCP server

node src/index.js serve [options]

Options:
  -s, --spec <path>       Path to OpenAPI specification file (required)
  -b, --base-url <url>    Base URL for API requests
  -t, --token <token>     Bearer token for authentication
  --timeout <ms>          Request timeout in milliseconds (default: 30000)
  --transport <type>      Transport type (stdio or http, default: stdio)
  --http-port <port>      HTTP server port (when using http transport, default: 3000)
  --http-host <host>      HTTP server host (when using http transport, default: localhost)

validate - Validate OpenAPI specification

node src/index.js validate -s <path-to-spec>

info - Show server information

node src/index.js info

Environment Variables

You can use environment variables instead of command-line arguments:

export OPENAPI_BASE_URL=https://api.example.com
export OPENAPI_BEARER_TOKEN=your-bearer-token
node src/index.js serve -s UserQueueList.json

node src/index.js serve -s UserQueueList.json --transport=http --http-port=8020

Configuration

OpenAPI Specification Requirements

  • Must be OpenAPI 3.x format
  • JSON format (.json extension)
  • Must contain at least one path/operation
  • Bearer token authentication should be defined in security schemes

Example OpenAPI Security Configuration

{
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "bearer": []
    }
  ]
}

Tool Generation

The server automatically converts OpenAPI operations into MCP tools:

Tool Naming

  1. Uses operationId if available
  2. Falls back to operation summary (sanitized)
  3. Last resort: {method}_{path} (sanitized)

Parameter Mapping

  • Path parameters: Required string parameters
  • Query parameters: Optional parameters based on OpenAPI schema
  • Header parameters: Prefixed with header_
  • Request body: Object properties or requestBody parameter

Example Tool

For the UserQueueList.json specification:

// Tool: ListUsers (GET /domains/~/users/list)
{
  "name": "ListUsers",
  "description": "List Basic Info on Users in Domain",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

// Tool: ListCallqueues (GET /domains/~/callqueues/list)
{
  "name": "ListCallqueues", 
  "description": "Read Basic info on Call Queues in Domain",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

MCP Integration

Using with Claude Desktop

Stdio Transport (Default)

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "openapi-server": {
      "command": "node",
      "args": [
        "/path/to/your/project/src/index.js",
        "serve",
        "-s", "/path/to/UserQueueList.json",
        "-b", "https://your-api-domain.com",
        "-t", "your-bearer-token"
      ]
    }
  }
}

HTTP Transport

For HTTP transport, configure the server URL instead:

{
  "mcpServers": {
    "openapi-server": {
      "url": "http://localhost:3000/message"
    }
  }
}

Then start the server separately:

node src/index.js serve -s UserQueueList.json --transport http --http-port 3000

Tool Responses

The server returns structured JSON responses:

Success Response:

{
  "status": 200,
  "statusText": "OK",
  "data": {
    // API response data
  }
}

Error Response:

{
  "error": true,
  "status": 404,
  "statusText": "Not Found",
  "message": "Domain not found",
  "data": {
    "code": 404,
    "message": "Domain example does not exist"
  }
}

Transport Protocols

Stdio Transport

  • Default transport method
  • Uses standard input/output streams for communication
  • Best for integration with Claude Desktop and other MCP clients
  • Automatic process management

HTTP Transport

  • Uses HTTP Server-Sent Events (SSE) for communication
  • Allows remote connections and debugging
  • Useful for development and testing
  • Configurable host and port

API Examples

Based on the UserQueueList.json specification:

List Users

// Tool call
{
  "name": "ListUsers",
  "arguments": {}
}

// Response: Array of user objects with basic information

List Call Queues

// Tool call  
{
  "name": "ListCallqueues",
  "arguments": {}
}

// Response: Array of call queue objects with configuration

Development

Project Structure

src/
 index.js              # CLI entry point
 server.js             # MCP server implementation
 openapi-processor.js  # OpenAPI specification processor
 http-client.js        # HTTP client for API requests
 utils.js              # Utility functions

Key Components

  • MCPServer: Main MCP server class handling tool registration and execution
  • OpenAPIProcessor: Parses OpenAPI specs and generates tool definitions
  • HttpClient: Handles HTTP requests with authentication and error handling
  • CLI: Command-line interface with validation and configuration options

Error Handling

The server provides comprehensive error handling:

  • Validation Errors: Parameter validation against OpenAPI schemas
  • HTTP Errors: Proper handling of API error responses
  • Authentication Errors: Clear messages for auth failures
  • Network Errors: Timeout and connectivity error handling

Security Considerations

  • Bearer tokens are handled securely and not logged
  • Request validation prevents injection attacks
  • Error messages don't expose sensitive information
  • HTTPS is recommended for all API communications

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

MIT License - see LICENSE file for details

Troubleshooting

Common Issues

  1. "Tool not found" errors: Check that your OpenAPI spec is valid and contains the expected operations
  2. Authentication failures: Verify your bearer token is correct and has proper permissions
  3. Network timeouts: Increase timeout or check API endpoint availability
  4. Schema validation errors: Ensure your OpenAPI spec follows 3.x standards

Debug Mode

For detailed logging, you can modify the server to enable debug output:

# The server logs to stderr for MCP compatibility
node src/index.js serve -s UserQueueList.json -b https://api.example.com -t token 2>debug.log

Validation

Always validate your OpenAPI specification before use:

node src/index.js validate -s UserQueueList.json

This will show:

  • Validation status
  • Specification details
  • Available tools
  • Security schemes
  • Base URL information

服务配置

[{'mcpServers': {'openapi-server': {'args': ['/path/to/your/project/src/index.js', 'serve', '-s', '/path/to/UserQueueList.json', '-b', 'https://your-api-domain.com', '-t', 'your-bearer-token'], 'command': 'node'}}}, {'mcpServers': {'openapi-server': {'url': 'http://localhost:3000/message'}}}]

来源