@ivotoby/openapi-mcp-server 1.5.1 → 1.6.1

package/README.md

@@ -6,11 +6,186 @@ A Model Context Protocol (MCP) server that exposes OpenAPI endpoints as MCP reso
 
 ## Overview
 
-This MCP server supports two transport methods:
+This MCP server can be used in two ways:
+
+1. **CLI Tool**: Use `npx @ivotoby/openapi-mcp-server` directly with command-line arguments for quick setup
+2. **Library**: Import and use the `OpenAPIServer` class in your own Node.js applications for custom implementations
+
+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)
@@ -353,6 +528,18 @@ To see debug logs:
 **Q: What is a "tool"?**
 A: A tool corresponds to a single API endpoint derived from your OpenAPI specification, exposed as an MCP resource.
 
+**Q: How can I use this package in my own project?**
+A: You can import the `OpenAPIServer` class and use it as a library in your Node.js application. This allows you to create dedicated MCP servers for specific APIs with custom authentication, filtering, and error handling. See the [examples/](./examples/) directory for complete implementations.
+
+**Q: What's the difference between using the CLI and using it as a library?**
+A: The CLI is great for quick setup and testing, while the library approach allows you to create dedicated packages for specific APIs, implement custom authentication with `AuthProvider`, add custom logic, and distribute your server as a standalone npm module.
+
+**Q: How do I handle APIs with expiring tokens?**
+A: Use the `AuthProvider` interface instead of static headers. AuthProvider allows you to implement dynamic authentication with token refresh, expiration handling, and custom error recovery. See the AuthProvider examples for different patterns.
+
+**Q: What is AuthProvider and when should I use it?**
+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.
 
@@ -360,7 +547,7 @@ A: Use the `--tool`, `--tag`, `--resource`, and `--operation` flags, or set `TOO
 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.
 
 **Q: How do I specify custom headers for API requests?**
-A: Use the `--headers` flag or `API_HEADERS` environment variable with `key:value` pairs separated by commas.
+A: Use the `--headers` flag or `API_HEADERS` environment variable with `key:value` pairs separated by commas for CLI usage. For library usage, use the `headers` config option or implement an `AuthProvider` for dynamic headers.
 
 **Q: Which transport methods are supported?**
 A: The server supports stdio transport (default) for integration with AI systems and HTTP transport (with streaming via SSE) for web clients.
@@ -371,6 +558,9 @@ A: The server fully resolves `$ref` references in parameters and schemas, preser
 **Q: What happens when parameter names conflict with request body properties?**
 A: The server detects naming conflicts and automatically prefixes body property names with `body_` to avoid collisions, ensuring all properties are accessible.
 
+**Q: Can I package my MCP server for distribution?**
+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.
 

package/bin/mcp-server.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import "../dist/bundle.js";
+import "../dist/cli.js"

package/dist/bundle.js

@@ -14286,7 +14286,7 @@ var js_yaml_default = jsYaml;
 // src/openapi-loader.ts
 import crypto from "crypto";
 
-// src/abbreviations.ts
+// src/utils/abbreviations.ts
 var REVISED_COMMON_WORDS_TO_REMOVE = [
   "controller",
   "api",
@@ -14371,6 +14371,21 @@ var WORD_ABBREVIATIONS = {
   query: "Qry"
 };
 
+// src/utils/tool-id.ts
+function parseToolId(toolId) {
+  const [method, pathPart] = toolId.split("::", 2);
+  const path = pathPart ? "/" + pathPart.replace(/-/g, "/") : "";
+  return { method, path };
+}
+function sanitizeForToolId(input) {
+  return input.replace(/[^A-Za-z0-9_-]/g, "").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-");
+}
+function generateToolId(method, path) {
+  const cleanPath = path.replace(/^\//, "").replace(/\{([^}]+)\}/g, "$1").replace(/\//g, "-");
+  const sanitizedPath = sanitizeForToolId(cleanPath);
+  return `${method.toUpperCase()}::${sanitizedPath}`;
+}
+
 // src/openapi-loader.ts
 var OpenAPISpecLoader = class {
   /**
@@ -14562,9 +14577,8 @@ var OpenAPISpecLoader = class {
           continue;
         }
         const op = operation;
-        const cleanPath = path.replace(/^\//, "").replace(/\{([^}]+)\}/g, "$1");
-        const toolId = `${method.toUpperCase()}-${cleanPath}`.replace(/[^a-zA-Z0-9-]/g, "-");
-        let nameSource = op.operationId || op.summary || `${method.toUpperCase()} ${path}`;
+        const toolId = generateToolId(method, path);
+        const nameSource = op.operationId || op.summary || `${method.toUpperCase()} ${path}`;
         const name = this.abbreviateOperationId(nameSource);
         const tool = {
           name,
@@ -14574,6 +14588,7 @@ var OpenAPISpecLoader = class {
             properties: {}
           }
         };
+        tool["x-original-path"] = path;
         const requiredParams = [];
         if (op.parameters) {
           for (const param of op.parameters) {
@@ -14940,11 +14955,12 @@ var ToolsManager = class {
   }
   /**
    * Get the path and method from a tool ID
+   *
+   * Note: This converts hyphens back to slashes to reconstruct the original API path.
+   * This is consistent with ApiClient.parseToolId() which needs the actual path for HTTP requests.
    */
   parseToolId(toolId) {
-    const [method, ...pathParts] = toolId.split("-");
-    const path = "/" + pathParts.join("/").replace(/-/g, "/");
-    return { method, path };
+    return parseToolId(toolId);
   }
 };
 
@@ -18257,22 +18273,46 @@ var {
   mergeConfig: mergeConfig2
 } = axios_default;
 
+// src/auth-provider.ts
+function isAuthError(error) {
+  return error.response?.status === 401 || error.response?.status === 403;
+}
+var StaticAuthProvider = class {
+  constructor(headers = {}) {
+    this.headers = headers;
+  }
+  async getAuthHeaders() {
+    return { ...this.headers };
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async handleAuthError(_error) {
+    return false;
+  }
+};
+
 // src/api-client.ts
 var ApiClient = class {
+  axiosInstance;
+  toolsMap = /* @__PURE__ */ new Map();
+  authProvider;
   /**
    * Create a new API client
    *
    * @param baseUrl - Base URL for the API
-   * @param headers - Optional headers to include with every request
+   * @param authProviderOrHeaders - AuthProvider instance or static headers for backward compatibility
    */
-  constructor(baseUrl, headers = {}) {
-    this.headers = headers;
+  constructor(baseUrl, authProviderOrHeaders) {
     this.axiosInstance = axios_default.create({
       baseURL: baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`
     });
+    if (!authProviderOrHeaders) {
+      this.authProvider = new StaticAuthProvider();
+    } else if (typeof authProviderOrHeaders === "object" && !("getAuthHeaders" in authProviderOrHeaders)) {
+      this.authProvider = new StaticAuthProvider(authProviderOrHeaders);
+    } else {
+      this.authProvider = authProviderOrHeaders;
+    }
   }
-  axiosInstance;
-  toolsMap = /* @__PURE__ */ new Map();
   /**
    * Set the available tools for the client
    *
@@ -18298,6 +18338,17 @@ var ApiClient = class {
    * @returns The API response data
    */
   async executeApiCall(toolId, params) {
+    return this.executeApiCallWithRetry(toolId, params, false);
+  }
+  /**
+   * Execute an API call with optional retry on auth error
+   *
+   * @param toolId - The tool ID in format METHOD-path-parts
+   * @param params - Parameters for the API call
+   * @param isRetry - Whether this is a retry attempt
+   * @returns The API response data
+   */
+  async executeApiCallWithRetry(toolId, params, isRetry) {
     try {
       const { method, path } = this.parseToolId(toolId);
       const toolDef = this.getToolDefinition(toolId);
@@ -18342,10 +18393,11 @@ var ApiClient = class {
           }
         }
       }
+      const authHeaders = await this.authProvider.getAuthHeaders();
       const config = {
         method: method.toLowerCase(),
         url: resolvedPath,
-        headers: this.headers
+        headers: authHeaders
       };
       if (["get", "delete", "head", "options"].includes(method.toLowerCase())) {
         config.params = this.processQueryParams(paramsCopy);
@@ -18357,6 +18409,12 @@ var ApiClient = class {
     } catch (error) {
       if (axios_default.isAxiosError(error)) {
         const axiosError = error;
+        if (!isRetry && isAuthError(axiosError)) {
+          const shouldRetry = await this.authProvider.handleAuthError(axiosError);
+          if (shouldRetry) {
+            return this.executeApiCallWithRetry(toolId, params, true);
+          }
+        }
         throw new Error(
           `API request failed: ${axiosError.message}${axiosError.response ? ` (${axiosError.response.status}: ${typeof axiosError.response.data === "object" ? JSON.stringify(axiosError.response.data) : axiosError.response.data})` : ""}`
         );
@@ -18367,13 +18425,11 @@ var ApiClient = class {
   /**
    * Parse a tool ID into HTTP method and path
    *
-   * @param toolId - Tool ID in format METHOD-path-parts
+   * @param toolId - Tool ID in format METHOD::pathPart
    * @returns Object containing method and path
    */
   parseToolId(toolId) {
-    const [method, ...pathParts] = toolId.split("-");
-    const path = "/" + pathParts.join("/").replace(/-/g, "/");
-    return { method, path };
+    return parseToolId(toolId);
   }
   /**
    * Process query parameters for GET requests
@@ -18413,7 +18469,8 @@ var OpenAPIServer = class {
       }
     );
     this.toolsManager = new ToolsManager(config);
-    this.apiClient = new ApiClient(config.apiBaseUrl, config.headers);
+    const authProviderOrHeaders = config.authProvider || new StaticAuthProvider(config.headers);
+    this.apiClient = new ApiClient(config.apiBaseUrl, authProviderOrHeaders);
     this.initializeHandlers();
   }
   /**
@@ -24049,14 +24106,19 @@ async function main() {
     process.exit(1);
   }
 }
-main();
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
 export {
   ApiClient,
   OpenAPIServer,
   OpenAPISpecLoader,
+  StaticAuthProvider,
   StreamableHttpServerTransport,
   ToolsManager,
+  isAuthError,
   loadConfig,
+  main,
   parseHeaders
 };
 /*! Bundled license information: