lled before each request - return fresh headers if (this.isTokenExpired()) { await this.refreshToken() } return { Authorization: `Bearer ${this.token}` } } async handleAuthError(error: AxiosError): Promise { // 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> /** * 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 } ``` ### Common Patterns #### Automatic Token Refresh ```typescript class RefreshableAuthProvider implements AuthProvider { async getAuthHeaders(): Promise> { if (this.isTokenExpired()) { await this.refreshToken() } return { Authorization: `Bearer ${this.accessToken}` } } async handleAuthError(error: AxiosError): Promise { 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> { 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> { return { "X-API-Key": this.apiKey } } async handleAuthError(error: AxiosError): Promise { 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 detecti

OpenAPI MCP Server

Comments