@ivotoby/openapi-mcp-server 1.6.1 → 1.8.0

package/README.md

@@ -4,6 +4,19 @@
 
 A Model Context Protocol (MCP) server that exposes OpenAPI endpoints as MCP resources. This server allows Large Language Models to discover and interact with REST APIs defined by OpenAPI specifications through the MCP protocol.
 
+## 📖 Documentation
+
+- **[User Guide](#user-guide)** - For users wanting to use this MCP server with Claude Desktop, Cursor, or other MCP clients
+- **[Library Usage](#library-usage)** - For developers creating custom MCP servers using this package as a library
+- **[Developer Guide](./docs/developer-guide.md)** - For contributors and developers working on the codebase
+- **[AuthProvider Guide](./docs/auth-provider-guide.md)** - Detailed authentication patterns and examples
+
+---
+
+# User Guide
+
+This section covers how to use the MCP server as an end user with Claude Desktop, Cursor, or other MCP-compatible tools.
+
 ## Overview
 
 This MCP server can be used in two ways:
@@ -16,176 +29,6 @@ The server supports two transport methods:
 1. **Stdio Transport** (default): For direct integration with AI systems like Claude Desktop that manage MCP connections through standard input/output.
 2. **Streamable HTTP Transport**: For connecting to the server over HTTP, allowing web clients and other HTTP-capable systems to use the MCP protocol.
 
-## 🚀 Using as a Library
-
-Create dedicated MCP servers for specific APIs by importing and configuring the `OpenAPIServer` class. This approach is ideal for:
-
-- **Custom Authentication**: Implement complex authentication patterns with the `AuthProvider` interface
-- **API-Specific Optimizations**: Filter endpoints, customize error handling, and optimize for specific use cases
-- **Distribution**: Package your server as a standalone npm module for easy sharing
-- **Integration**: Embed the server in larger applications or add custom middleware
-
-### Basic Library Usage
-
-```typescript
-import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
-
-const config = {
-  name: "my-api-server",
-  version: "1.0.0",
-  apiBaseUrl: "https://api.example.com",
-  openApiSpec: "https://api.example.com/openapi.json",
-  specInputMethod: "url" as const,
-  headers: {
-    Authorization: "Bearer your-token",
-    "X-API-Key": "your-api-key",
-  },
-  transportType: "stdio" as const,
-  toolsMode: "all" as const,
-}
-
-const server = new OpenAPIServer(config)
-const transport = new StdioServerTransport()
-await server.start(transport)
-```
-
-### Advanced Authentication with AuthProvider
-
-For APIs with token expiration, refresh requirements, or complex authentication:
-
-```typescript
-import { OpenAPIServer, AuthProvider } from "@ivotoby/openapi-mcp-server"
-import { AxiosError } from "axios"
-
-class MyAuthProvider implements AuthProvider {
-  async getAuthHeaders(): Promise<Record<string, string>> {
-    // Called before each request - return fresh headers
-    if (this.isTokenExpired()) {
-      await this.refreshToken()
-    }
-    return { Authorization: `Bearer ${this.token}` }
-  }
-
-  async handleAuthError(error: AxiosError): Promise<boolean> {
-    // Called on 401/403 errors - return true to retry
-    if (error.response?.status === 401) {
-      await this.refreshToken()
-      return true // Retry the request
-    }
-    return false
-  }
-}
-
-const authProvider = new MyAuthProvider()
-const config = {
-  // ... other config
-  authProvider: authProvider, // Use AuthProvider instead of static headers
-}
-```
-
-**📁 See the [examples/](./examples/) directory for complete, runnable examples including:**
-
-- Basic library usage with static authentication
-- AuthProvider implementations for different scenarios
-- Real-world Beatport API integration
-- Production-ready packaging patterns
-
-## 🔐 Dynamic Authentication with AuthProvider
-
-The `AuthProvider` interface enables sophisticated authentication scenarios that static headers cannot handle:
-
-### Key Features
-
-- **Dynamic Headers**: Fresh authentication headers for each request
-- **Token Expiration Handling**: Automatic detection and handling of expired tokens
-- **Authentication Error Recovery**: Retry logic for recoverable authentication failures
-- **Custom Error Messages**: Provide clear, actionable guidance to users
-
-### AuthProvider Interface
-
-```typescript
-interface AuthProvider {
-  /**
-   * Get authentication headers for the current request
-   * Called before each API request to get fresh headers
-   */
-  getAuthHeaders(): Promise<Record<string, string>>
-
-  /**
-   * Handle authentication errors from API responses
-   * Called when the API returns 401 or 403 errors
-   * Return true to retry the request, false otherwise
-   */
-  handleAuthError(error: AxiosError): Promise<boolean>
-}
-```
-
-### Common Patterns
-
-#### Automatic Token Refresh
-
-```typescript
-class RefreshableAuthProvider implements AuthProvider {
-  async getAuthHeaders(): Promise<Record<string, string>> {
-    if (this.isTokenExpired()) {
-      await this.refreshToken()
-    }
-    return { Authorization: `Bearer ${this.accessToken}` }
-  }
-
-  async handleAuthError(error: AxiosError): Promise<boolean> {
-    if (error.response?.status === 401) {
-      await this.refreshToken()
-      return true // Retry with fresh token
-    }
-    return false
-  }
-}
-```
-
-#### Manual Token Management (e.g., Beatport)
-
-```typescript
-class ManualTokenAuthProvider implements AuthProvider {
-  async getAuthHeaders(): Promise<Record<string, string>> {
-    if (!this.token || this.isTokenExpired()) {
-      throw new Error(
-        "Token expired. Please get a new token from your browser:\n" +
-          "1. Go to the API website and log in\n" +
-          "2. Open browser dev tools (F12)\n" +
-          "3. Copy the Authorization header from any API request\n" +
-          "4. Update your token using updateToken()",
-      )
-    }
-    return { Authorization: `Bearer ${this.token}` }
-  }
-
-  updateToken(token: string): void {
-    this.token = token
-    this.tokenExpiry = new Date(Date.now() + 3600000) // 1 hour
-  }
-}
-```
-
-#### API Key Authentication
-
-```typescript
-class ApiKeyAuthProvider implements AuthProvider {
-  constructor(private apiKey: string) {}
-
-  async getAuthHeaders(): Promise<Record<string, string>> {
-    return { "X-API-Key": this.apiKey }
-  }
-
-  async handleAuthError(error: AxiosError): Promise<boolean> {
-    throw new Error("API key authentication failed. Please check your key.")
-  }
-}
-```
-
-**📖 For detailed AuthProvider documentation and examples, see [docs/auth-provider-guide.md](./docs/auth-provider-guide.md)**
-
 ## Quick Start for Users
 
 ### Option 1: Using with Claude Desktop (Stdio Transport)
@@ -266,27 +109,6 @@ curl -N http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"
 curl -X DELETE http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"
 ```
 
-## Transport Types
-
-### Stdio Transport (Default)
-
-The stdio transport is designed for direct integration with AI systems like Claude Desktop that manage MCP connections through standard input/output. This is the simplest setup and requires no network configuration.
-
-**When to use**: When integrating with Claude Desktop or other systems that support stdio-based MCP communication.
-
-### Streamable HTTP Transport
-
-The HTTP transport allows the MCP server to be accessed over HTTP, enabling web applications and other HTTP-capable clients to interact with the MCP protocol. It supports session management, streaming responses, and standard HTTP methods.
-
-**Key features**:
-
-- Session management with Mcp-Session-Id header
-- HTTP responses for `initialize` and `tools/list` requests are sent synchronously on the POST.
-- Other server-to-client messages (e.g., `tools/execute` results, notifications) are streamed over a GET connection using Server-Sent Events (SSE).
-- Support for POST/GET/DELETE methods
-
-**When to use**: When you need to expose the MCP server to web clients or systems that communicate over HTTP rather than stdio.
-
 ## Configuration Options
 
 The server can be configured through environment variables or command line arguments:
@@ -304,7 +126,7 @@ The server can be configured through environment variables or command line argum
 - `HTTP_PORT` - Port for HTTP transport (default: 3000)
 - `HTTP_HOST` - Host for HTTP transport (default: "127.0.0.1")
 - `ENDPOINT_PATH` - Endpoint path for HTTP transport (default: "/mcp")
-- `TOOLS_MODE` - Tools loading mode: "all" (load all endpoint-based tools) or "dynamic" (load only meta-tools) (default: "all")
+- `TOOLS_MODE` - Tools loading mode: "all" (load all endpoint-based tools), "dynamic" (load only meta-tools), or "explicit" (load only tools specified in includeTools) (default: "all")
 - `DISABLE_ABBREVIATION` - Disable name optimization (this could throw errors when name is > 64 chars)
 
 ### Command Line Arguments
@@ -422,40 +244,14 @@ Only one specification source can be used at a time. The server will validate th
 
 If multiple sources are specified, the server will exit with an error message.
 
-### OpenAPI Schema Processing
-
-#### Reference Resolution
-
-This MCP server implements robust OpenAPI reference (`$ref`) resolution to ensure accurate representation of API schemas:
-
-- **Parameter References**: Fully resolves `$ref` pointers to parameter components in the OpenAPI spec
-- **Schema References**: Handles nested schema references within parameters and request bodies
-- **Recursive References**: Prevents infinite loops by detecting and handling circular references
-- **Nested Properties**: Preserves complex nested object and array structures with all their attributes
-
-### Input Schema Composition
-
-The server intelligently merges parameters and request bodies into a unified input schema for each tool:
-
-- **Parameters + Request Body Merging**: Combines path, query, and body parameters into a single schema
-- **Collision Handling**: Resolves naming conflicts by prefixing body properties that conflict with parameter names
-- **Type Preservation**: Maintains the original type information for all schema elements
-- **Metadata Retention**: Preserves descriptions, formats, defaults, enums, and other schema attributes
-
-### Complex Schema Support
-
-The MCP server handles various OpenAPI schema complexities:
-
-- **Primitive Type Bodies**: Wraps non-object request bodies in a "body" property
-- **Object Bodies**: Flattens object properties into the tool's input schema
-- **Array Bodies**: Properly handles array schemas with their nested item definitions
-- **Required Properties**: Tracks and preserves which parameters and properties are required
-
 ## Tool Loading & Filtering Options
 
 Based on the Stainless article "What We Learned Converting Complex OpenAPI Specs to MCP Servers" (https://www.stainless.com/blog/what-we-learned-converting-complex-openapi-specs-to-mcp-servers), the following flags were added to control which API endpoints (tools) are loaded:
 
-- `--tools <all|dynamic>`: Choose to load all tools (default) or only dynamic meta-tools (`list-api-endpoints`, `get-api-endpoint-schema`, `invoke-api-endpoint`).
+- `--tools <all|dynamic|explicit>`: Choose tool loading mode:
+  - `all` (default): Load all tools from the OpenAPI spec, applying any specified filters
+  - `dynamic`: Load only dynamic meta-tools (`list-api-endpoints`, `get-api-endpoint-schema`, `invoke-api-endpoint`)
+  - `explicit`: Load only tools explicitly listed in `--tool` options, ignoring all other filters
 - `--tool <toolId>`: Import only specified tool IDs or names. Can be used multiple times.
 - `--tag <tag>`: Import only tools with the specified OpenAPI tag. Can be used multiple times.
 - `--resource <resource>`: Import only tools under the specified resource path prefixes. Can be used multiple times.
@@ -467,7 +263,10 @@ Based on the Stainless article "What We Learned Converting Complex OpenAPI Specs
 # Load only dynamic meta-tools
 npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools dynamic
 
-# Load only the GET /users endpoint tool
+# Load only explicitly specified tools (ignores other filters)
+npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools explicit --tool GET::users --tool POST::users
+
+# Load only the GET /users endpoint tool (using all mode with filtering)
 npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tool GET-users
 
 # Load tools tagged with "user" under the "/users" resource
@@ -477,6 +276,27 @@ npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi
 npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --operation post
 ```
 
+## Transport Types
+
+### Stdio Transport (Default)
+
+The stdio transport is designed for direct integration with AI systems like Claude Desktop that manage MCP connections through standard input/output. This is the simplest setup and requires no network configuration.
+
+**When to use**: When integrating with Claude Desktop or other systems that support stdio-based MCP communication.
+
+### Streamable HTTP Transport
+
+The HTTP transport allows the MCP server to be accessed over HTTP, enabling web applications and other HTTP-capable clients to interact with the MCP protocol. It supports session management, streaming responses, and standard HTTP methods.
+
+**Key features**:
+
+- Session management with Mcp-Session-Id header
+- HTTP responses for `initialize` and `tools/list` requests are sent synchronously on the POST.
+- Other server-to-client messages (e.g., `tools/execute` results, notifications) are streamed over a GET connection using Server-Sent Events (SSE).
+- Support for POST/GET/DELETE methods
+
+**When to use**: When you need to expose the MCP server to web clients or systems that communicate over HTTP rather than stdio.
+
 ## Security Considerations
 
 - The HTTP transport validates Origin headers to prevent DNS rebinding attacks
@@ -496,6 +316,247 @@ To see debug logs:
    npx @ivotoby/openapi-mcp-server --transport http &2>debug.log
    ```
 
+---
+
+# Library Usage
+
+This section is for developers who want to use this package as a library to create custom MCP servers.
+
+## 🚀 Using as a Library
+
+Create dedicated MCP servers for specific APIs by importing and configuring the `OpenAPIServer` class. This approach is ideal for:
+
+- **Custom Authentication**: Implement complex authentication patterns with the `AuthProvider` interface
+- **API-Specific Optimizations**: Filter endpoints, customize error handling, and optimize for specific use cases
+- **Distribution**: Package your server as a standalone npm module for easy sharing
+- **Integration**: Embed the server in larger applications or add custom middleware
+
+### Basic Library Usage
+
+```typescript
+import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+
+const config = {
+  name: "my-api-server",
+  version: "1.0.0",
+  apiBaseUrl: "https://api.example.com",
+  openApiSpec: "https://api.example.com/openapi.json",
+  specInputMethod: "url" as const,
+  headers: {
+    Authorization: "Bearer your-token",
+    "X-API-Key": "your-api-key",
+  },
+  transportType: "stdio" as const,
+  toolsMode: "all" as const, // Options: "all", "dynamic", "explicit"
+}
+
+const server = new OpenAPIServer(config)
+const transport = new StdioServerTransport()
+await server.start(transport)
+```
+
+### Tool Loading Modes
+
+The `toolsMode` configuration option controls which tools are loaded from your OpenAPI specification:
+
+```typescript
+// Load all tools from the spec (default)
+const config = {
+  // ... other config
+  toolsMode: "all" as const,
+  // Optional: Apply filters to control which tools are loaded
+  includeTools: ["GET::users", "POST::users"], // Only these tools
+  includeTags: ["public"], // Only tools with these tags
+  includeResources: ["users"], // Only tools under these resources
+  includeOperations: ["get", "post"], // Only these HTTP methods
+}
+
+// Load only dynamic meta-tools for API exploration
+const config = {
+  // ... other config
+  toolsMode: "dynamic" as const,
+  // Provides: list-api-endpoints, get-api-endpoint-schema, invoke-api-endpoint
+}
+
+// Load only explicitly specified tools (ignores other filters)
+const config = {
+  // ... other config
+  toolsMode: "explicit" as const,
+  includeTools: ["GET::users", "POST::users"], // Only these exact tools
+  // includeTags, includeResources, includeOperations are ignored in explicit mode
+}
+```
+
+### Advanced Authentication with AuthProvider
+
+For APIs with token expiration, refresh requirements, or complex authentication:
+
+```typescript
+import { OpenAPIServer, AuthProvider } from "@ivotoby/openapi-mcp-server"
+import { AxiosError } from "axios"
+
+class MyAuthProvider implements AuthProvider {
+  async getAuthHeaders(): Promise<Record<string, string>> {
+    // Called before each request - return fresh headers
+    if (this.isTokenExpired()) {
+      await this.refreshToken()
+    }
+    return { Authorization: `Bearer ${this.token}` }
+  }
+
+  async handleAuthError(error: AxiosError): Promise<boolean> {
+    // Called on 401/403 errors - return true to retry
+    if (error.response?.status === 401) {
+      await this.refreshToken()
+      return true // Retry the request
+    }
+    return false
+  }
+}
+
+const authProvider = new MyAuthProvider()
+const config = {
+  // ... other config
+  authProvider: authProvider, // Use AuthProvider instead of static headers
+}
+```
+
+**📁 See the [examples/](./examples/) directory for complete, runnable examples including:**
+
+- Basic library usage with static authentication
+- AuthProvider implementations for different scenarios
+- Real-world Beatport API integration
+- Production-ready packaging patterns
+
+## 🔐 Dynamic Authentication with AuthProvider
+
+The `AuthProvider` interface enables sophisticated authentication scenarios that static headers cannot handle:
+
+### Key Features
+
+- **Dynamic Headers**: Fresh authentication headers for each request
+- **Token Expiration Handling**: Automatic detection and handling of expired tokens
+- **Authentication Error Recovery**: Retry logic for recoverable authentication failures
+- **Custom Error Messages**: Provide clear, actionable guidance to users
+
+### AuthProvider Interface
+
+```typescript
+interface AuthProvider {
+  /**
+   * Get authentication headers for the current request
+   * Called before each API request to get fresh headers
+   */
+  getAuthHeaders(): Promise<Record<string, string>>
+
+  /**
+   * Handle authentication errors from API responses
+   * Called when the API returns 401 or 403 errors
+   * Return true to retry the request, false otherwise
+   */
+  handleAuthError(error: AxiosError): Promise<boolean>
+}
+```
+
+### Common Patterns
+
+#### Automatic Token Refresh
+
+```typescript
+class RefreshableAuthProvider implements AuthProvider {
+  async getAuthHeaders(): Promise<Record<string, string>> {
+    if (this.isTokenExpired()) {
+      await this.refreshToken()
+    }
+    return { Authorization: `Bearer ${this.accessToken}` }
+  }
+
+  async handleAuthError(error: AxiosError): Promise<boolean> {
+    if (error.response?.status === 401) {
+      await this.refreshToken()
+      return true // Retry with fresh token
+    }
+    return false
+  }
+}
+```
+
+#### Manual Token Management (e.g., Beatport)
+
+```typescript
+class ManualTokenAuthProvider implements AuthProvider {
+  async getAuthHeaders(): Promise<Record<string, string>> {
+    if (!this.token || this.isTokenExpired()) {
+      throw new Error(
+        "Token expired. Please get a new token from your browser:\n" +
+          "1. Go to the API website and log in\n" +
+          "2. Open browser dev tools (F12)\n" +
+          "3. Copy the Authorization header from any API request\n" +
+          "4. Update your token using updateToken()",
+      )
+    }
+    return { Authorization: `Bearer ${this.token}` }
+  }
+
+  updateToken(token: string): void {
+    this.token = token
+    this.tokenExpiry = new Date(Date.now() + 3600000) // 1 hour
+  }
+}
+```
+
+#### API Key Authentication
+
+```typescript
+class ApiKeyAuthProvider implements AuthProvider {
+  constructor(private apiKey: string) {}
+
+  async getAuthHeaders(): Promise<Record<string, string>> {
+    return { "X-API-Key": this.apiKey }
+  }
+
+  async handleAuthError(error: AxiosError): Promise<boolean> {
+    throw new Error("API key authentication failed. Please check your key.")
+  }
+}
+```
+
+**📖 For detailed AuthProvider documentation and examples, see [docs/auth-provider-guide.md](./docs/auth-provider-guide.md)**
+
+### OpenAPI Schema Processing
+
+#### Reference Resolution
+
+This MCP server implements robust OpenAPI reference (`$ref`) resolution to ensure accurate representation of API schemas:
+
+- **Parameter References**: Fully resolves `$ref` pointers to parameter components in the OpenAPI spec
+- **Schema References**: Handles nested schema references within parameters and request bodies
+- **Recursive References**: Prevents infinite loops by detecting and handling circular references
+- **Nested Properties**: Preserves complex nested object and array structures with all their attributes
+
+### Input Schema Composition
+
+The server intelligently merges parameters and request bodies into a unified input schema for each tool:
+
+- **Parameters + Request Body Merging**: Combines path, query, and body parameters into a single schema
+- **Collision Handling**: Resolves naming conflicts by prefixing body properties that conflict with parameter names
+- **Type Preservation**: Maintains the original type information for all schema elements
+- **Metadata Retention**: Preserves descriptions, formats, defaults, enums, and other schema attributes
+
+### Complex Schema Support
+
+The MCP server handles various OpenAPI schema complexities:
+
+- **Primitive Type Bodies**: Wraps non-object request bodies in a "body" property
+- **Object Bodies**: Flattens object properties into the tool's input schema
+- **Array Bodies**: Properly handles array schemas with their nested item definitions
+- **Required Properties**: Tracks and preserves which parameters and properties are required
+
+---
+
+# Developer Information
+
 ## For Developers
 
 ### Development Tools
@@ -523,7 +584,11 @@ To see debug logs:
 4. Run tests and linting: `npm run typecheck && npm run lint`
 5. Submit a pull request
 
-## FAQ
+**📖 For comprehensive developer documentation, see [docs/developer-guide.md](./docs/developer-guide.md)**
+
+---
+
+# FAQ
 
 **Q: What is a "tool"?**
 A: A tool corresponds to a single API endpoint derived from your OpenAPI specification, exposed as an MCP resource.
@@ -541,7 +606,7 @@ A: Use the `AuthProvider` interface instead of static headers. AuthProvider allo
 A: `AuthProvider` is an interface for dynamic authentication that gets fresh headers before each request and handles authentication errors. Use it when your API has expiring tokens, requires token refresh, or needs complex authentication logic that static headers can't handle.
 
 **Q: How do I filter which tools are loaded?**
-A: Use the `--tool`, `--tag`, `--resource`, and `--operation` flags, or set `TOOLS_MODE=dynamic` for meta-tools only.
+A: Use the `--tool`, `--tag`, `--resource`, and `--operation` flags with `--tools all` (default), set `--tools dynamic` for meta-tools only, or use `--tools explicit` to load only tools specified with `--tool` (ignoring other filters).
 
 **Q: When should I use dynamic mode?**
 A: Dynamic mode provides meta-tools (`list-api-endpoints`, `get-api-endpoint-schema`, `invoke-api-endpoint`) to inspect and interact with endpoints without preloading all operations, which is useful for large or changing APIs.
@@ -562,7 +627,7 @@ A: The server detects naming conflicts and automatically prefixes body property
 A: Yes! When using the library approach, you can create a dedicated npm package for your API. See the Beatport example for a complete implementation that can be packaged and distributed as `npx your-api-mcp-server`.
 
 **Q: Where can I find development and contribution guidelines?**
-A: See the "For Developers" section above for commands (`npm run build`, `npm run dev`, etc) and pull request workflow.
+A: See the [Developer Guide](./docs/developer-guide.md) for comprehensive documentation on architecture, key concepts, development workflow, and contribution guidelines.
 
 ## License