OpenAPI MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a pure JavaScript MCP (Model Context Protocol) server that transforms OpenAPI 3.x specifications into MCP tools, enabling LLMs to interact with REST APIs through the standardized MCP protocol. ## Key Components - **src/index.js**: CLI entry point with Commander.js for command handling - **src/server.js**: Core MCP server implementation using @modelcontextprotocol/sdk - **src/openapi-processor.js**: Processes OpenAPI specs and generates tool definitions - **src/http-client.js**: HTTP client for executing API requests with authentication - **src/utils.js**: Utility functions ## Development Commands ### Starting the Server ```bash # Development with inspect mode npm run dev # Production start npm start # Start with CLI options node src/index.js serve -s UserQueueList.json -b https://api.example.com -t your-token ``` ### Validation and Testing ```bash # Validate OpenAPI specification node src/index.js validate -s UserQueueList.json # Show server information node src/index.js info ``` ### Environment Configuration ```bash # Set environment variables for default configuration export OPENAPI_BASE_URL=https://api.example.com export OPENAPI_BEARER_TOKEN=your-token node src/index.js serve -s UserQueueList.json ``` ## Architecture ### MCP Server Flow 1. **Initialization**: Load OpenAPI spec → Generate tools → Initialize HTTP client 2. **Tool Registration**: Convert OpenAPI operations to MCP tool definitions 3. **Request Handling**: Receive MCP tool calls → Execute HTTP requests → Return structured responses ### Tool Generation - Uses `operationId` if available, otherwise generates from method + path - Maps OpenAPI parameters to MCP tool input schema - Supports path, query, header parameters and request bodies - Validates arguments against OpenAPI schemas ### Transport Modes - **stdio** (default): Standard input/output for Claude Desktop integration - **http**: HTTP server with SSE for remote connections and debugging ### Authentication - Bearer token authentication via headers or CLI options - Dynamic configuration per request via HTTP headers (`x-openapi-base-url`, `x-openapi-bearer-token`) ## OpenAPI Specification Requirements - Must be OpenAPI 3.x format in JSON - Requires at least one path/operation - Bearer token security schemes recommended - Example spec: UserQueueList.json (provides ListUsers and ListCallqueues tools) ## Claude Desktop Integration Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "openapi-server": { "command": "node", "args": [ "/path/to/project/src/index.js", "serve", "-s", "/path/to/UserQueueList.json", "-b", "https://your-api-domain.com", "-t", "your-bearer-token" ] } } } ``` ## Key Dependencies - **@modelcontextprotocol/sdk**: Core MCP protocol implementation - **ajv**: JSON schema validation for OpenAPI specs and tool arguments - **axios**: HTTP client for API requests - **commander**: CLI argument parsing - **jsonpath-plus**: JSON path querying utilities ## Error Handling The server provides comprehensive error handling with structured JSON responses distinguishing between successful API responses and error states. All errors include status codes, messages, and relevant data for debugging. ## Debugging Enable detailed logging by redirecting stderr: ```bash node src/index.js serve -s spec.json 2>debug.log ``` The server logs extensively to stderr for MCP compatibility while maintaining clean stdout for protocol communication.