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}`);
}

you can also provide a OpenAPIV3.Document to the parser:

import { parser } from '@readme/openapi-parser';

const api = await parser('https://petstore3.swagger.io/api/v3/openapi.json', {
  dereference: {
    circular: true,
  },
});

const tools = await getToolsFromOpenApi(api);

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',
});