Examples & Tutorials

// config/environments.ts
interface Environment {
  name: string;
  apiBaseUrl: string;
  openApiSpec: string;
  headers: Record;
}

const environments: Record = {
  development: {
    name: "dev-api",
    apiBaseUrl: "https://dev-api.example.com",
    openApiSpec: "https://dev-api.example.com/openapi.json",
    headers: {
      "Authorization": `Bearer ${process.env.DEV_API_TOKEN}`,
      "X-Environment": "development"
    }
  },
  staging: {
    name: "staging-api", 
    apiBaseUrl: "https://staging-api.example.com",
    openApiSpec: "https://staging-api.example.com/openapi.json",
    headers: {
      "Authorization": `Bearer ${process.env.STAGING_API_TOKEN}`,
      "X-Environment": "staging"
    }
  },
  production: {
    name: "prod-api",
    apiBaseUrl: "https://api.example.com",
    openApiSpec: "https://api.example.com/openapi.json", 
    headers: {
      "Authorization": `Bearer ${process.env.PROD_API_TOKEN}`,
      "X-Environment": "production"
    }
  }
};

// server-manager.ts
import { OpenAPIServer } from "@lucid-spark/openapi-mcp-server";

export class MultiEnvironmentManager {
  private servers: Map = new Map();

  async createServer(environment: string): Promise {
    const env = environments[environment];
    if (!env) {
      throw new Error(`Unknown environment: ${environment}`);
    }

    const server = new OpenAPIServer({
      ...env,
      transportType: "http",
      httpPort: this.getPortForEnvironment(environment)
    });

    await server.start();
    this.servers.set(environment, server);
    
    return server;
  }

  async stopServer(environment: string): Promise {
    const server = this.servers.get(environment);
    if (server) {
      await server.stop();
      this.servers.delete(environment);
    }
  }

  private getPortForEnvironment(environment: string): number {
    const basePorts = { development: 3001, staging: 3002, production: 3003 };
    return basePorts[environment] || 3000;
  }
}

// Usage
const manager = new MultiEnvironmentManager();

// Start development server
const devServer = await manager.createServer("development");

// Switch to production for final testing
await manager.stopServer("development");
const prodServer = await manager.createServer("production");

// config-loader.ts
import { readFile } from "fs/promises";
import { load } from "js-yaml";
import { OpenAPIServer, IOpenAPIServerConfig } from "@lucid-spark/openapi-mcp-server";

export class DynamicConfigLoader {
  static async loadFromFile(configPath: string): Promise {
    try {
      const content = await readFile(configPath, "utf-8");
      
      // Support both JSON and YAML
      const config = configPath.endsWith('.yaml') || configPath.endsWith('.yml') 
        ? load(content) as IOpenAPIServerConfig
        : JSON.parse(content) as IOpenAPIServerConfig;
      
      // Resolve environment variables in config
      return this.resolveEnvironmentVariables(config);
    } catch (error) {
      throw new Error(`Failed to load config from ${configPath}: ${error.message}`);
    }
  }

  static async loadFromUrl(configUrl: string): Promise {
    try {
      const response = await fetch(configUrl);
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }
      
      const config = await response.json();
      return this.resolveEnvironmentVariables(config);
    } catch (error) {
      throw new Error(`Failed to load config from ${configUrl}: ${error.message}`);
    }
  }

  static async loadFromRegistry(serviceName: string): Promise {
    // Example: Service discovery integration
    const registryUrl = process.env.SERVICE_REGISTRY_URL || "http://localhost:8500";
    const response = await fetch(`${registryUrl}/v1/catalog/service/${serviceName}`);
    
    if (!response.ok) {
      throw new Error(`Service ${serviceName} not found in registry`);
    }
    
    const services = await response.json();
    const service = services[0]; // Use first available instance
    
    return {
      apiBaseUrl: `http://${service.ServiceAddress}:${service.ServicePort}`,
      openApiSpec: `http://${service.ServiceAddress}:${service.ServicePort}/openapi.json`,
      name: serviceName,
      headers: {
        "X-Service-Version": service.ServiceMeta?.version || "unknown"
      }
    };
  }

  private static resolveEnvironmentVariables(config: any): any {
    const resolved = JSON.parse(JSON.stringify(config));
    
    const replaceEnvVars = (obj: any): any => {
      if (typeof obj === "string") {
        return obj.replace(/\$\{([^}]+)\}/g, (match, envVar) => {
          return process.env[envVar] || match;
        });
      } else if (Array.isArray(obj)) {
        return obj.map(replaceEnvVars);
      } else if (typeof obj === "object" && obj !== null) {
        const result: any = {};
        for (const [key, value] of Object.entries(obj)) {
          result[key] = replaceEnvVars(value);
        }
        return result;
      }
      return obj;
    };
    
    return replaceEnvVars(resolved);
  }
}

// Example configuration file (config.yaml)
/*
apiBaseUrl: ${API_BASE_URL}
openApiSpec: ${OPENAPI_SPEC_URL}
headers:
  Authorization: "Bearer ${API_TOKEN}"
  X-Client-ID: ${CLIENT_ID}
includeTags:
  - users
  - orders
transportType: stdio
debug: ${DEBUG_MODE:false}
*/

// Usage examples
const configLoader = new DynamicConfigLoader();

// Load from file
const fileConfig = await configLoader.loadFromFile("./config.yaml");
const fileServer = new OpenAPIServer(fileConfig);

// Load from URL
const urlConfig = await configLoader.loadFromUrl("https://config.example.com/api-config.json");
const urlServer = new OpenAPIServer(urlConfig);

// Load from service registry
const registryConfig = await configLoader.loadFromRegistry("user-service");
const registryServer = new OpenAPIServer(registryConfig);

// plugins/base-plugin.ts
export interface IPlugin {
  name: string;
  version: string;
  initialize(server: OpenAPIServer): Promise;
  beforeRequest?(request: any): Promise;
  afterResponse?(response: any): Promise;
  cleanup?(): Promise;
}

// plugins/logging-plugin.ts
export class LoggingPlugin implements IPlugin {
  name = "logging-plugin";
  version = "1.0.0";
  
  private requestCount = 0;
  private errorCount = 0;

  async initialize(server: OpenAPIServer): Promise {
    console.log(`[${this.name}] Initialized for server: ${server.getStats().openapi.version}`);
  }

  async beforeRequest(request: any): Promise {
    this.requestCount++;
    console.log(`[${this.name}] Request #${this.requestCount}: ${request.method} ${request.url}`);
    return request;
  }

  async afterResponse(response: any): Promise {
    if (response.status >= 400) {
      this.errorCount++;
      console.error(`[${this.name}] Error response: ${response.status} ${response.statusText}`);
    }
    return response;
  }

  getStats() {
    return {
      totalRequests: this.requestCount,
      totalErrors: this.errorCount,
      errorRate: this.requestCount > 0 ? (this.errorCount / this.requestCount) * 100 : 0
    };
  }
}

// plugins/caching-plugin.ts
export class CachingPlugin implements IPlugin {
  name = "caching-plugin";
  version = "1.0.0";
  
  private cache = new Map();
  private ttl: number;

  constructor(ttlMinutes: number = 5) {
    this.ttl = ttlMinutes * 60 * 1000;
  }

  async initialize(server: OpenAPIServer): Promise {
    console.log(`[${this.name}] Cache TTL: ${this.ttl}ms`);
    
    // Clean expired entries every minute
    setInterval(() => this.cleanExpired(), 60000);
  }

  async beforeRequest(request: any): Promise {
    if (request.method === "GET") {
      const cacheKey = this.getCacheKey(request);
      const cached = this.cache.get(cacheKey);
      
      if (cached && cached.expires > Date.now()) {
        console.log(`[${this.name}] Cache hit: ${cacheKey}`);
        request.cachedResponse = cached.data;
      }
    }
    return request;
  }

  async afterResponse(response: any): Promise {
    if (response.status === 200 && response.config?.method === "GET") {
      const cacheKey = this.getCacheKey(response.config);
      this.cache.set(cacheKey, {
        data: response.data,
        expires: Date.now() + this.ttl
      });
      console.log(`[${this.name}] Cached response: ${cacheKey}`);
    }
    return response;
  }

  private getCacheKey(request: any): string {
    return `${request.method}:${request.url}`;
  }

  private cleanExpired(): void {
    const now = Date.now();
    for (const [key, value] of this.cache.entries()) {
      if (value.expires <= now) {
        this.cache.delete(key);
      }
    }
  }
}

// enhanced-server.ts
export class EnhancedOpenAPIServer extends OpenAPIServer {
  private plugins: IPlugin[] = [];

  addPlugin(plugin: IPlugin): void {
    this.plugins.push(plugin);
  }

  async start(): Promise {
    // Initialize plugins
    for (const plugin of this.plugins) {
      await plugin.initialize(this);
    }
    
    // Start the base server
    await super.start();
  }

  async stop(): Promise {
    // Cleanup plugins
    for (const plugin of this.plugins) {
      if (plugin.cleanup) {
        await plugin.cleanup();
      }
    }
    
    await super.stop();
  }

  // Override request handling to apply plugins
  protected async processRequest(request: any): Promise {
    let processedRequest = request;
    
    // Apply beforeRequest hooks
    for (const plugin of this.plugins) {
      if (plugin.beforeRequest) {
        processedRequest = await plugin.beforeRequest(processedRequest);
      }
    }
    
    // Check for cached response
    if (processedRequest.cachedResponse) {
      return processedRequest.cachedResponse;
    }
    
    // Process request normally
    let response = await super.processRequest(processedRequest);
    
    // Apply afterResponse hooks
    for (const plugin of this.plugins) {
      if (plugin.afterResponse) {
        response = await plugin.afterResponse(response);
      }
    }
    
    return response;
  }
}

// Usage
const server = new EnhancedOpenAPIServer({
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "./api-spec.yaml"
});

// Add plugins
server.addPlugin(new LoggingPlugin());
server.addPlugin(new CachingPlugin(10)); // 10-minute cache

await server.start();