项目简介

Orval 是一个强大的 OpenAPI 客户端代码生成器，它不仅能生成各种前端框架的 API 客户端代码，还能根据 OpenAPI 规范生成 Model Context Protocol (MCP) 服务器端的代码。通过 Orval，开发者可以快速搭建符合 MCP 协议的服务后端，为大型语言模型（LLM）应用提供结构化的上下文信息和功能支持。

主要功能点

资源管理 (Resources): 通过 OpenAPI 规范定义的数据模型，自动生成资源管理的代码框架。
工具注册 (Tools): 支持基于 OpenAPI Operation 定义工具接口，方便 LLM 客户端调用后端功能。
Prompt 模板 (Prompts): 虽然仓库本身不直接管理 Prompt 模板，但生成的服务器代码可以作为 Prompt 模板渲染的后端数据服务。
JSON-RPC 通信: 生成的服务器代码遵循 MCP 协议，支持通过 JSON-RPC 与客户端通信。
Stdio 传输协议: 默认支持 Stdio 传输协议，简化服务器部署和客户端连接。
基于 OpenAPI: 利用 OpenAPI 规范驱动服务器代码生成，保证接口定义与代码实现的一致性。

安装步骤

安装 Orval CLI: 确保你的开发环境中已安装 Node.js 和 npm。使用 npm 安装 Orval CLI 工具：
```
npm install orval -g
```

创建 Orval 配置文件: 在你的项目根目录下，创建一个 Orval 配置文件 'orval.config.ts' (或 'orval.config.js')，用于指定 MCP 服务器代码的生成配置。

// orval.config.ts
import { defineConfig } from 'orval';

export default defineConfig({
  mcpServer: { // 配置名称，可以自定义
    input: './path/to/your/openapi.yaml', // OpenAPI 规范文件路径
    output: {
      target: './src/mcp-server/handlers.ts', // 生成的服务器代码输出路径
      schemas: './src/mcp-server/schemas', // 生成的数据模型输出路径
      mode: 'single', // 模式设置为 single
      client: 'mcp', // 客户端类型设置为 mcp
    },
  },
});

请替换 'input' 字段为你实际的 OpenAPI 规范文件路径。

生成 MCP 服务器代码: 在项目根目录下运行 Orval 命令，根据配置文件生成 MCP 服务器代码：
```
orval
```
或者指定配置文件路径：
```
orval --config orval.config.ts
```

服务器配置

MCP 客户端需要配置以下 JSON 信息以连接到 Orval 生成的 MCP 服务器：

{
  "serverName": "your-mcp-server",  // 自定义服务器名称，例如从 OpenAPI info.title 获取
  "command": "node",             // 启动服务器的命令，这里假设使用 Node.js 运行
  "args": [                       // 启动命令的参数
    "./src/mcp-server/server.js" // 生成的服务器入口文件路径，需要根据实际生成的文件调整，server.js 为示例，实际可能为 handlers.ts 编译后的 js 文件
  ]
}

参数注释:

'serverName': MCP 服务器的名称，用于客户端识别和管理连接。建议设置为有意义的名称，例如基于你的服务或应用命名。
'command': 启动 MCP 服务器进程的命令。对于 Node.js 服务器，通常设置为 'node'。
'args': 启动命令的参数列表。
- '"./src/mcp-server/server.js"': 指向 Orval 生成的 MCP 服务器入口文件。请注意，此路径是示例，你需要根据 Orval 实际生成的服务器入口文件路径进行调整。通常，你需要先编译 TypeScript 代码为 JavaScript 文件，然后指向编译后的入口文件。例如，如果你的 handlers.ts 文件编译后输出为 handlers.js，并且你创建了一个 server.ts 文件作为启动入口并导入 handlers.js，那么这里应该指向 server.js。

基本使用方法

编写 OpenAPI 规范: 定义你的 API 接口和数据模型，包括 Resources 和 Tools。
配置 Orval: 创建 'orval.config.ts' 文件，配置输入 OpenAPI 规范路径和输出 MCP 服务器代码的路径。
生成服务器代码: 运行 'orval' 命令生成 MCP 服务器代码。
编译并启动服务器: 如果生成的是 TypeScript 代码，需要先编译为 JavaScript。然后使用配置中 'command' 和 'args' 启动服务器。例如，如果入口文件为 'server.js'，可以使用 'node server.js' 命令启动。
配置 MCP 客户端: 在你的 LLM 应用中，配置 MCP 客户端连接信息，指向你启动的 MCP 服务器。客户端即可通过 MCP 协议与服务器进行通信，访问 Resources 和调用 Tools。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息