OpenAPI-MCP-Generator 项目：如何通过编程方式生成 MCP 工具定义

项目概述

OpenAPI-MCP-Generator 是一个强大的工具，它能够将标准的 OpenAPI 规范转换为 MCP（Machine-Callable Procedures）工具定义。这种转换使得开发者可以更方便地将现有的 RESTful API 集成到各种自动化工作流和工具链中。

安装与基础使用

要开始使用这个工具，首先需要通过包管理器安装：

npm install openapi-mcp-generator

安装完成后，你可以通过简单的导入语句来使用核心功能：

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

核心 API 详解

getToolsFromOpenApi 函数

这是该工具的核心函数，负责从 OpenAPI 规范中提取 MCP 工具定义。

函数签名：

getToolsFromOpenApi(specPathOrUrl: string, options?: Options): Promise<McpToolDefinition[]>

参数说明：

1. specPathOrUrl：可以是本地 OpenAPI 规范文件的路径，也可以是远程规范的 URL
2. options：可选配置对象，用于定制提取过程

配置选项详解：

• baseUrl：覆盖 OpenAPI 规范中定义的 base URL
• dereference：是否解析规范中的 $ref 引用（默认 false）
• excludeOperationIds：要排除的操作 ID 数组
• filterFn：自定义过滤函数，用于筛选工具定义

使用示例：

// 基本用法
const tools = await getToolsFromOpenApi('./api-spec.json');

// 带配置的高级用法
const tools = await getToolsFromOpenApi('https://example.com/api-spec.json', {
  baseUrl: 'https://api.example.com/v2',
  dereference: true,
  excludeOperationIds: ['deprecatedOperation'],
  filterFn: tool => tool.method === 'get'
});

MCP 工具定义结构解析

每个 MCP 工具定义都包含以下关键属性：

1. name：工具的唯一名称
2. description：人类可读的描述信息
3. inputSchema：定义输入参数的 JSON Schema
4. method：HTTP 方法（get/post/put/delete 等）
5. pathTemplate：带有参数占位符的 URL 路径模板
6. parameters：OpenAPI 参数对象数组
7. executionParameters：执行时需要的参数名称和位置信息
8. requestBodyContentType：请求体的内容类型（如适用）
9. securityRequirements：操作的安全要求
10. operationId：原始 OpenAPI 规范中的操作 ID
11. baseUrl：API 的基础 URL（如可用）

高级过滤技巧

按 HTTP 方法过滤

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

按安全要求过滤

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

按路径模式过滤

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

组合多个过滤条件

const safeProductTools = await getToolsFromOpenApi(specUrl, {
  excludeOperationIds: ['deleteProduct'],
  filterFn: tool => 
    tool.pathTemplate.includes('/products') &&
    tool.method.toLowerCase() === 'get' &&
    tool.securityRequirements.length > 0
});

实际应用场景

1. 自动化工作流集成：将现有 API 快速集成到自动化工作流系统中
2. API 文档生成：基于 MCP 工具定义生成更丰富的文档
3. API 测试自动化：利用工具定义自动生成测试用例
4. 低代码平台集成：为低代码平台提供可调用的 API 操作

最佳实践建议

1. 合理使用 dereference 选项：对于复杂的规范，启用此选项可以简化处理，但会增加内存使用
2. 命名规范化：考虑对生成的工具名称进行后处理，确保命名一致性
3. 安全考虑：特别注意处理带有安全要求的工具定义
4. 性能优化：对于大型 API 规范，考虑分批处理工具定义

通过 OpenAPI-MCP-Generator，开发者可以轻松地将现有的 RESTful API 转换为更易于程序化调用的形式，大大提高了 API 在自动化场景中的可用性和集成效率。