✦ AI OpenAPI Toolkit

Generate Vercel AI SDK tools from OpenAPI specifications with full TypeScript support and filtering capabilities.

Features

• ✅ AI SDK v5 Compatible - Generate tools using the latest AI SDK syntax
• ✅ Type Safety - Full TypeScript support with InferUITool types
• ✅ Multiple HTTP Clients - Support for fetch, ofetch, axios, next, nuxt, angular
• ✅ Smart Filtering - Filter by tags and HTTP methods
• ✅ Individual Tools - Each API endpoint becomes a separate tool file
• ✅ Zod Integration - Uses Hey API's Zod plugin for schema validation

Installation

npm install -g ai-openapi-toolkit

Usage

The simplest way to get started:

ai-openapi-toolkit ./output ./openapi-spec.json

Interactive Mode

For a guided setup experience, use interactive mode:

ai-openapi-toolkit ./output ./openapi-spec.json -i

This will prompt you through all available options with a user-friendly interface, including:

• HTTP client selection
• Context client name configuration
• Runtime config path
• Smart tag filtering - Automatically extracts all available tags from your OpenAPI spec and lets you select which ones to include or exclude
• HTTP method filtering (include/exclude)

The interactive mode makes it easy to discover and configure all available options without needing to know the exact syntax.

This will generate several files in your output directory:

• *.gen.ts files - API client generated from your OpenAPI specs using hey-api
• @vercel/ai/ directory - Individual AI SDK compatible tools
• @vercel/ai/index.ts - Barrel exports for all tools
• @vercel/ai/types.ts - TypeScript types with InferUITool support
• zod.gen.ts - Zod schemas for validation

After generating your tools, import them in your AI SDK app:

import { getProducts, createOrder } from "./@vercel/ai";
import type { UITools } from "./@vercel/ai/types";

const tools = {
  getProducts,
  createOrder,
} satisfies UITools;

Advanced Usage

Client Selection

Choose your preferred HTTP client:

# Use axios
ai-openapi-toolkit ./output ./openapi.json -c axios

# Use Next.js client
ai-openapi-toolkit ./output ./openapi.json -c next

# Use fetch (default)
ai-openapi-toolkit ./output ./openapi.json -c fetch

Filtering

Filter operations by tags and HTTP methods. You can either include specific tags/methods or exclude them (but not both):

# Only include specific tags
ai-openapi-toolkit ./output ./openapi.json --include-tags Products,Orders

# Exclude specific tags
ai-openapi-toolkit ./output ./openapi.json --exclude-tags Admin,Internal

# Only include specific HTTP methods
ai-openapi-toolkit ./output ./openapi.json --include-methods GET,POST

# Exclude specific methods
ai-openapi-toolkit ./output ./openapi.json --exclude-methods DELETE

Note: In interactive mode, the tool automatically extracts all available tags from your OpenAPI spec and presents them as a multi-select interface, making it much easier to discover and select the tags you want to filter.

Custom Context Client Name

By default, the generated tools expect the client to be available as client in the experimental context. You can customize this:

# Use a custom client name in the context
ai-openapi-toolkit ./output ./openapi.json --context-client-name apiClient

This will generate tools that access options?.experimental_context?.apiClient instead of options?.experimental_context?.client.

Runtime Configuration

For Hey API client configuration (authentication, base URL, etc.), create a runtime config file:

// runtime.config.ts
import type { CreateClientConfig } from "@hey-api/client-fetch";

export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseUrl: "https://api.example.com",
  auth: () => "Bearer your-token", // or just "Bearer your-token"
});

Then use it:

ai-openapi-toolkit ./output ./openapi.json -r ./runtime.config.ts

CLI Options

| Option | Description | Default | | ---------------------------------- | -------------------------------------------------------------- | ------- | | -c, --client <client> | HTTP client to use (fetch, ofetch, axios, next, nuxt, angular) | fetch | | -r, --runtime-config-path <path> | Path to Hey API runtime config file | - | | -i, --interactive | Run in interactive mode to configure options | - | | --context-client-name <name> | Name of the client property in the experimental context | client | | --include-tags <tags> | Comma-separated tags to include | - | | --exclude-tags <tags> | Comma-separated tags to exclude | - | | --include-methods <methods> | Comma-separated HTTP methods to include | - | | --exclude-methods <methods> | Comma-separated HTTP methods to exclude | - |

Generated Tool Structure

Each generated tool follows this pattern:

// @vercel/ai/getProducts.ts
import { tool } from "ai";
import { zGetProductsData, zGetProductsResponse } from "../zod.gen";
import { getProducts } from "..";

export default tool({
  description: "Get a list of products...",
  inputSchema: zGetProductsData,
  outputSchema: zGetProductsResponse,
  execute: async (args, options) => {
    try {
      const client = (options?.experimental_context as any)?.client;
      const data = (
        await getProducts({
          ...(args as any),
          ...(client && { client }),
        })
      ).data;
      return data;
    } catch (e) {
      return null;
    }
  },
});

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.