API Reference

import { OpenAPIServer, validateConfig } from "@lucid-spark/openapi-mcp-server";

async function createBasicServer() {
  const config = validateConfig({
    apiBaseUrl: "https://api.example.com",
    openApiSpec: "https://api.example.com/openapi.json",
    headers: {
      "Authorization": "Bearer your-token",
      "Accept": "application/json"
    }
  });

  const server = new OpenAPIServer(config);
  
  // Start server
  await server.start();
  
  // Get statistics
  const stats = server.getStats();
  console.log(`Server running with ${stats.tools.total} tools`);
  
  // Test API connection
  const connected = await server.testConnection();
  console.log(`API connection: ${connected ? 'OK' : 'Failed'}`);
}

import { OpenAPIServer, IAuthProvider } from "@lucid-spark/openapi-mcp-server";
import { AxiosError } from "axios";

class OAuth2AuthProvider implements IAuthProvider {
  private accessToken: string;
  private refreshToken: string;
  private tokenExpiry: Date;

  constructor(accessToken: string, refreshToken: string, expiresIn: number) {
    this.accessToken = accessToken;
    this.refreshToken = refreshToken;
    this.tokenExpiry = new Date(Date.now() + expiresIn * 1000);
  }

  async getAuthHeaders(): Promise> {
    if (this.isTokenExpiring()) {
      await this.refreshAccessToken();
    }

    return {
      Authorization: `Bearer ${this.accessToken}`
    };
  }

  async handleAuthError(error: AxiosError): Promise {
    if (error.response?.status === 401) {
      try {
        await this.refreshAccessToken();
        return true; // Retry request
      } catch (refreshError) {
        throw new Error("Token refresh failed");
      }
    }
    return false;
  }

  private isTokenExpiring(): boolean {
    const bufferTime = 60 * 1000; // 60 seconds
    return this.tokenExpiry.getTime() <= (Date.now() + bufferTime);
  }

  private async refreshAccessToken(): Promise {
    // Implementation depends on your OAuth provider
    const response = await fetch("https://oauth.example.com/token", {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "refresh_token",
        refresh_token: this.refreshToken
      })
    });

    const data = await response.json();
    this.accessToken = data.access_token;
    this.refreshToken = data.refresh_token || this.refreshToken;
    this.tokenExpiry = new Date(Date.now() + data.expires_in * 1000);
  }
}

// Usage
const authProvider = new OAuth2AuthProvider(
  "access_token",
  "refresh_token", 
  3600
);

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

import { 
  generateToolId, 
  parseToolId, 
  generateToolName,
  createToolFromOperation 
} from "@lucid-spark/openapi-mcp-server";

// Generate tool ID
const toolId = generateToolId("GET", "/users/{id}");
console.log(toolId); // "GET::users__---id"

// Parse tool ID
const { method, path } = parseToolId(toolId);
console.log(method, path); // "GET", "/users/{id}"

// Generate tool name
const toolName = generateToolName("getUserDetailsByIdentifier");
console.log(toolName); // "get-usr-dtls-by-idntfr"

// Create tool from OpenAPI operation
const operation = {
  operationId: "getUser",
  summary: "Get user by ID",
  parameters: [
    {
      name: "id",
      in: "path",
      required: true,
      schema: { type: "string" }
    }
  ]
};

const tool = createToolFromOperation("/users/{id}", "GET", operation);
console.log(tool.name); // "get-user"