examples

Examples

This directory contains comprehensive examples demonstrating how to use @ivotoby/openapi-mcp-server as a library to create dedicated MCP servers for specific APIs.

Overview

The @ivotoby/openapi-mcp-server package can be used in two ways:

1. CLI Tool: Use npx @ivotoby/openapi-mcp-server directly with command-line arguments
2. Library: Import and use the OpenAPIServer class in your own Node.js applications

These examples focus on the library usage, showing how to create dedicated, customized MCP servers for specific APIs.

Examples Included

1. Basic Library Usage

Purpose: Demonstrates the simplest way to use the library with static authentication.

Key Features:

• Basic OpenAPIServer configuration
• Static header authentication
• Stdio transport for Claude Desktop integration
• Minimal setup for quick prototyping

When to use: When you have a simple API with static authentication and want to get started quickly.

2. AuthProvider Example

Purpose: Showcases the AuthProvider interface for dynamic authentication scenarios.

Key Features:

• Multiple AuthProvider implementations (Refreshable, Manual, API Key)
• Token expiration handling
• Authentication error recovery
• Dynamic header generation

When to use: When your API requires token refresh, has expiring tokens, or needs complex authentication logic.

3. Beatport Example

Purpose: Real-world implementation for the Beatport API demonstrating production-ready patterns.

Key Features:

• Custom AuthProvider for manual token management
• API endpoint filtering and optimization
• Comprehensive error handling with user guidance
• Production-ready packaging and distribution

When to use: As a template for creating production-ready MCP servers for specific APIs.

Key Concepts Demonstrated

Library vs CLI Usage

CLI Usage (what most users start with):

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token"

Library Usage (what these examples show):

import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"

const server = new OpenAPIServer({
  name: "my-api-server",
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "https://api.example.com/openapi.json",
  headers: { Authorization: "Bearer token" },
})

AuthProvider Interface

The AuthProvider interface enables dynamic authentication:

interface AuthProvider {
  getAuthHeaders(): Promise<Record<string, string>>
  handleAuthError(error: AxiosError): Promise<boolean>
}

Benefits:

• Fresh headers for each request
• Token expiration handling
• Authentication error recovery
• Runtime token updates

Configuration Options

All examples demonstrate different configuration patterns:

• Transport Types: Stdio (Claude Desktop) vs HTTP (web clients)
• Tool Loading: All endpoints vs filtered subsets vs dynamic meta-tools
• Authentication: Static headers vs dynamic AuthProvider
• API Filtering: Include/exclude specific endpoints, operations, or tags

Getting Started

1. Choose Your Pattern

• Simple API with static auth → Start with Basic Library Usage
• API with token expiration → Use AuthProvider Example
• Production deployment → Follow Beatport Example patterns

2. Copy and Customize

Each example is a complete, standalone project:

1. Copy the example directory
2. Update package.json with your details
3. Modify the configuration for your API
4. Implement custom authentication if needed
5. Build and deploy

3. Package for Distribution

Examples show how to create distributable packages:

{
  "name": "my-api-mcp-server",
  "bin": {
    "my-api-mcp-server": "dist/index.js"
  }
}

Users can then install and use your server:

npx my-api-mcp-server

Common Patterns

Static Authentication

const config = {
  // ... other config
  headers: {
    Authorization: "Bearer token",
    "X-API-Key": "key",
  },
}

Dynamic Authentication

const authProvider = new MyAuthProvider()
const config = {
  // ... other config
  authProvider: authProvider,
}

API Filtering

const config = {
  // ... other config
  includeOperations: ["get", "post"],
  includeResources: ["users", "posts"],
  includeTags: ["public"],
}

Error Handling

class MyAuthProvider implements AuthProvider {
  async handleAuthError(error: AxiosError): Promise<boolean> {
    if (error.response?.status === 401) {
      // Provide clear instructions
      throw new Error("Token expired. Please...")
    }
    return false
  }
}

Benefits of Library Usage

1. Customization

• Custom authentication logic
• API-specific optimizations
• Custom error handling
• Additional tools and features

2. Distribution

• Package as standalone npm modules
• Version control and updates
• Easy installation for users
• Professional deployment

3. Integration

• Embed in larger applications
• Custom transport implementations
• Integration with existing auth systems
• Custom middleware and processing

4. Maintenance

• API-specific documentation
• Tailored user experience
• Focused feature set
• Better error messages

Next Steps

1. Explore the Examples: Start with the basic example and work your way up
2. Read the Documentation: Check the main README for all configuration options
3. Implement Your API: Use the patterns to create your own dedicated server
4. Share Your Work: Consider publishing your server for others to use

Contributing

Found a useful pattern or want to add an example? Contributions are welcome!

• Add new examples for different authentication patterns
• Improve existing examples with better error handling
• Add examples for specific popular APIs
• Document advanced configuration patterns