@ezmcpz/openapi

Automatic MCP tool generation from OpenAPI/Swagger specifications.

Installation

npm install @ezmcpz/openapi
# or
pnpm add @ezmcpz/openapi

Quick Start

import { McpServer } from '@ezmcpz/core';
import { openApiTools } from '@ezmcpz/openapi';

const server = new McpServer({
  name: 'api-server',
  version: '1.0.0'
})
  .use(openApiTools({
    spec: 'https://api.example.com/openapi.json',
    autoGenerate: true,
    prefix: 'api_',
    auth: {
      type: 'bearer',
      token: process.env.API_TOKEN
    }
  }));

await server.start();

Features

• Automatic Tool Generation: Convert OpenAPI operations to MCP tools
• Type Safety: Generate Zod schemas from OpenAPI schemas
• Authentication: Support for Bearer, API Key, and Basic auth
• Flexible Configuration: Include/exclude specific operations
• Custom Naming: Override tool names and descriptions

Configuration

Basic Options

openApiTools({
  spec: './openapi.yaml',        // URL or file path
  autoGenerate: true,             // Auto-generate all operations
  prefix: 'api_',                 // Prefix for tool names
  baseUrl: 'https://api.example.com' // Override base URL
})

Authentication

// Bearer token
openApiTools({
  spec: './openapi.yaml',
  auth: {
    type: 'bearer',
    token: process.env.API_TOKEN
  }
})

// API Key
openApiTools({
  spec: './openapi.yaml',
  auth: {
    type: 'apiKey',
    apiKey: process.env.API_KEY,
    headerName: 'X-API-Key'
  }
})

// Basic auth
openApiTools({
  spec: './openapi.yaml',
  auth: {
    type: 'basic',
    username: 'user',
    password: 'pass'
  }
})

Selective Operations

// Include only specific operations
openApiTools({
  spec: './openapi.yaml',
  includeOperations: [
    'GET /users',
    'POST /users',
    'GET /users/{id}'
  ]
})

// Exclude specific operations
openApiTools({
  spec: './openapi.yaml',
  excludeOperations: [
    'DELETE /users/{id}'
  ]
})

Custom Tool Configuration

openApiTools({
  spec: './openapi.yaml',
  operations: {
    'GET /users': {
      toolName: 'list_users',
      description: 'List all users in the system'
    },
    'POST /users': {
      toolName: 'create_user',
      description: 'Create a new user'
    }
  }
})

Complete Example

import { McpServer } from '@ezmcpz/core';
import { httpTransport } from '@ezmcpz/transport-http';
import { openApiTools } from '@ezmcpz/openapi';

const server = new McpServer({
  name: 'github-api',
  version: '1.0.0'
})
  .use(openApiTools({
    spec: 'https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json',
    prefix: 'github_',
    auth: {
      type: 'bearer',
      token: process.env.GITHUB_TOKEN
    },
    includeOperations: [
      'GET /repos/{owner}/{repo}',
      'GET /repos/{owner}/{repo}/issues',
      'POST /repos/{owner}/{repo}/issues'
    ],
    operations: {
      'GET /repos/{owner}/{repo}': {
        toolName: 'get_repository',
        description: 'Get repository information'
      },
      'GET /repos/{owner}/{repo}/issues': {
        toolName: 'list_issues',
        description: 'List repository issues'
      },
      'POST /repos/{owner}/{repo}/issues': {
        toolName: 'create_issue',
        description: 'Create a new issue'
      }
    }
  }))
  .use(httpTransport({ port: 3000 }));

await server.start();

Programmatic Usage

You can also use the tool generator directly:

import { parseOpenAPISpec, generateTools } from '@ezmcpz/openapi';

// Parse spec
const spec = await parseOpenAPISpec('./openapi.yaml');

// Generate tools
const tools = generateTools(spec, {
  prefix: 'api_',
  autoGenerate: true,
  auth: {
    type: 'bearer',
    token: 'my-token'
  }
});

// Register tools manually
for (const tool of tools) {
  server.tool(tool.name, {
    description: tool.description,
    schema: tool.schema,
    handler: tool.handler
  });
}

Supported OpenAPI Features

• ✅ Path parameters
• ✅ Query parameters
• ✅ Request body (JSON)
• ✅ Basic types (string, number, boolean, array, object)
• ✅ Enums
• ✅ Required/optional fields
• ✅ $ref resolution
• ✅ allOf, oneOf, anyOf
• ✅ Bearer, API Key, Basic auth
• ⚠️ Limited support for complex schemas
• ❌ File uploads
• ❌ External $refs

License

MIT