使用说明

项目简介

'openapi2mcptools' 是一个工具库，它可以将 OpenAPI (Swagger) 规范转换为符合 Model Context Protocol (MCP) 协议的工具定义。该库简化了 MCP 服务器的开发，特别是当你的后端服务已经使用 OpenAPI 规范定义时，可以快速将这些 API 接口转化为可在 MCP 环境中使用的工具。

主要功能点

OpenAPI 到 MCP 工具转换: 自动解析 OpenAPI 规范，提取 API 接口信息（路径、方法、参数、描述等），并将其转换为 MCP 工具所需的 'tools' 格式（包含 'name', 'description', 'inputSchema'）。
工具调用器生成: 提供工具调用器 ('toolCaller')，允许 MCP 服务器根据客户端的工具调用请求，动态地调用底层的 OpenAPI 定义的 API 接口。
灵活的 HTTP 客户端: 支持自定义 HTTP 客户端，可以方便地配置 API 请求的基础 URL、请求头等，以适应不同的 API 服务环境。
易于集成: 可以与 '@modelcontextprotocol/sdk/server' 等 MCP 服务器 SDK 结合使用，快速搭建基于 OpenAPI 工具的 MCP 服务器。

安装步骤

安装 npm 包: 在你的 MCP 服务器项目目录下，使用 npm 安装 '2013xile_openapi2mcptools' 库和 '@modelcontextprotocol/sdk'：

npm install 2013xile_openapi2mcptools @modelcontextprotocol/sdk

准备 OpenAPI 规范: 你需要准备你的后端 API 服务的 OpenAPI 规范文件 (例如 'swagger.json' 或 'openapi.yaml')。

服务器配置

为了使 MCP 客户端能够连接到使用此库构建的 MCP 服务器，你需要提供服务器的启动配置信息。以下是一个基于示例代码生成的配置，你需要根据你的实际情况进行调整。

{
  "serverName": "mcp-server-openapi",
  "command": "node",
  "args": [
    "path/to/your/server.js"
  ],
  "transport": "stdio",
  "capabilities": {
    "tools": {}
  },
  "description": "MCP Server integrating OpenAPI tools",
  "version": "1.0.0"
}

配置参数说明:

'serverName': MCP 服务器的名称，客户端会使用此名称识别服务器。
'command': 启动服务器的命令，这里假设你使用 Node.js 运行服务器脚本。
'args': 传递给启动命令的参数，这里假设你的服务器主脚本文件是 'server.js'，你需要将 'path/to/your/server.js' 替换为你的服务器脚本的实际路径。
'transport': MCP 服务器使用的传输协议，示例中使用 'stdio' (标准输入输出)，表示通过命令行管道与客户端通信。
'capabilities': 声明服务器支持的功能，示例中声明支持 'tools' 功能。
'description': 服务器的描述信息。
'version': 服务器的版本号。

注意: 你需要将上述 JSON 配置信息提供给 MCP 客户端，以便客户端能够正确连接和使用你的 MCP 服务器。 'path/to/your/server.js' 需要替换为你的实际服务器脚本路径。你需要创建一个 'server.js' 文件，并将 基本使用方法 中展示的代码片段放入其中。

基本使用方法

以下代码展示了如何使用 'openapi2mcptools' 库创建一个简单的 MCP 服务器，它将 OpenAPI 规范转换为 MCP 工具并提供服务。

创建服务器脚本 (例如 'server.js'):

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
import { Converter } from '2013xile_openapi2mcptools';
// 假设你的 OpenAPI 规范文件为 sample.json，放在与 server.js 同目录下
import sample from './sample.json';

async function main() {
  const converter = new Converter();
  await converter.load(sample); // 加载 OpenAPI 规范
  const tools = converter.getToolsList(); // 获取 MCP 工具列表
  const toolCaller = converter.getToolsCaller(); // 获取工具调用器

  const server = new Server(
    {
      name: 'mcp-server-openapi',
      version: '1.0.0',
    },
    {
      capabilities: {
        tools: {},
      },
    },
  );

  // 定义可用的工具列表
  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools,
    };
  });

  // 处理工具执行请求
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    return await toolCaller(request);
  });

  const transport = new StdioServerTransport();
  await server.connect(transport); // 启动服务器，使用 Stdio 传输协议
  console.log('MCP Server connected via Stdio'); // 可选的启动成功提示
}

main().catch(console.error);

运行服务器: 在命令行中，导航到你的项目目录，并执行以下命令启动服务器：
```
node server.js
```
确保 'sample.json' 文件（或者你自己的 OpenAPI 规范文件）与 'server.js' 在同一目录下，或者你已经正确配置了 'converter.load()' 方法来加载你的 OpenAPI 规范。
配置 MCP 客户端: 将上面 服务器配置 部分生成的 JSON 配置信息添加到你的 MCP 客户端配置中，客户端应该能够连接到你的 MCP 服务器并使用从 OpenAPI 规范转换而来的工具。

注意: 上述 'server.js' 代码仅为示例，你需要根据你的实际 OpenAPI 规范和需求进行调整。例如，你需要替换 'sample.json' 为你自己的 OpenAPI 规范文件路径，并根据你的 API 服务的具体情况配置 'Converter' 类的 'baseURL' 或 'httpClient' 选项。

关键词