openapi-mcp-generator/PROGRAMMATIC_API.md

OpenAPI to MCP Generator - Programmatic API

This document describes how to use the OpenAPI to MCP Generator programmatically in your Node.js applications.

Installation

npm install openapi-mcp-generator

Usage

The package exports a simple, focused API for extracting MCP tool definitions from OpenAPI specifications:

import { getToolsFromOpenApi } from 'openapi-mcp-generator';

getToolsFromOpenApi(specPathOrUrl, options)

This function extracts an array of tools from an OpenAPI specification.

Parameters:

• specPathOrUrl: Path to a local OpenAPI spec file or URL to a remote spec
• options: (Optional) Configuration options

Options:

• baseUrl: Override the base URL in the OpenAPI spec
• dereference: Whether to resolve $refs (default: false)
• excludeOperationIds: Array of operation IDs to exclude from the results
• filterFn: Custom function to filter tools (receives tool, returns boolean)

Returns:

• Promise that resolves to an array of McpToolDefinition objects

Example:

import { getToolsFromOpenApi } from 'openapi-mcp-generator';

// Basic usage
const tools = await getToolsFromOpenApi('./petstore.json');

// With options
const filteredTools = await getToolsFromOpenApi('https://petstore3.swagger.io/api/v3/openapi.json', {
  baseUrl: 'https://petstore3.swagger.io/api/v3',
  dereference: true,
  excludeOperationIds: ['addPet', 'updatePet'],
  filterFn: (tool) => tool.method.toLowerCase() === 'get'
});

// Process the results
for (const tool of filteredTools) {
  console.log(`Tool: ${tool.name}`);
  console.log(`  Description: ${tool.description}`);
  console.log(`  Method: ${tool.method.toUpperCase()} ${tool.pathTemplate}`);
  console.log(`  OperationId: ${tool.operationId}`);
}

Tool Definition Structure

Each tool definition (McpToolDefinition) has the following properties:

interface McpToolDefinition {
  /** Name of the tool, must be unique */
  name: string;
  
  /** Human-readable description of the tool */
  description: string;
  
  /** JSON Schema that defines the input parameters */
  inputSchema: JSONSchema7 | boolean;
  
  /** HTTP method for the operation (get, post, etc.) */
  method: string;
  
  /** URL path template with parameter placeholders */
  pathTemplate: string;
  
  /** OpenAPI parameter objects for this operation */
  parameters: OpenAPIV3.ParameterObject[];
  
  /** Parameter names and locations for execution */
  executionParameters: { name: string; in: string }[];
  
  /** Content type for request body, if applicable */
  requestBodyContentType?: string;
  
  /** Security requirements for this operation */
  securityRequirements: OpenAPIV3.SecurityRequirementObject[];
  
  /** Original operation ID from the OpenAPI spec */
  operationId: string;
  
  /** Base URL for the API (if available) */
  baseUrl?: string;
}

Advanced Filtering Examples

Filter by HTTP Method

const getTools = await getToolsFromOpenApi(specUrl, {
  filterFn: (tool) => tool.method.toLowerCase() === 'get'
});

Filter by Security Requirements

const secureTools = await getToolsFromOpenApi(specUrl, {
  filterFn: (tool) => tool.securityRequirements.length > 0
});

Filter by Path Pattern

const userTools = await getToolsFromOpenApi(specUrl, {
  filterFn: (tool) => tool.pathTemplate.includes('/user')
});

Combining Multiple Filters

const safeUserTools = await getToolsFromOpenApi(specUrl, {
  excludeOperationIds: ['deleteUser', 'updateUser'],
  filterFn: (tool) => 
    tool.pathTemplate.includes('/user') &&
    tool.method.toLowerCase() === 'get'
});