星战科技xingzhan.cloud
返回市场
麦普生成器

麦普生成器

作者：lyeslabs86 星标更新：2025-05-26
安装使用来源：spider==github.com

项目介绍

mcpgen: 将OpenAPI API无缝转换为AI代理工具

mcpgen 是一个命令行工具，能够无缝地从你的OpenAPI规范生成生产就绪的Model Context Protocol (MCP)服务器样板代码，使你可以轻松地将现有的API暴露为强大的AI代理工具。

主要特性

  • OpenAPI兼容性: 支持读取并处理YAML或JSON格式的OpenAPI规范，支持版本3.0。
  • 全面的MCP服务器生成: 生成设置MCP服务器所需的全部Go样板代码，包括服务器初始化、工具注册和处理器骨架。
  • 精确的模式翻译: 自动将OpenAPI模式定义翻译成工具输入所需的JSON模式（与MCP兼容），并生成详细的基于markdown的响应模板（提示），提供丰富的上下文信息给AI模型。
  • 高级模式支持: 处理复杂的OpenAPI模式结构，包括：
    • 数组和嵌套结构
    • 类型联合和oneOf/anyOf/allOf组合器
    • 递归类型定义
    • 验证约束（例如：minimum，maximum，maxLength，pattern）
  • 多内容类型处理: 正确处理和生成定义了多个请求和响应内容类型的操作的模板。
  • 生成代码质量: 产生结构良好、符合Go语言习惯的代码，嵌入模式和提示，并使用常量以提高清晰度和可维护性。
  • 可选客户端及类型生成: 可选择根据你的OpenAPI模式生成Go HTTP客户端和相应的Go类型，简化生成的MCP处理器中的实现逻辑。
  • 开发者友好: 提供清晰的处理器函数骨架，并指导在哪里集成核心逻辑以连接实际的后端API。
  • 经过实战考验的基础: 代码生成逻辑由广泛的测试支持，确保高可靠性（如94%覆盖率和200%测试量所展示的）。

安装

go install github.com/lyeslabs/mcpgen/cmd/mcpgen@latest

默认情况下，二进制文件安装在 $HOME/go/bin（Windows上为 %USERPROFILE%\go\bin）。确保该目录在你的PATH中。

使用

mcpgen --input openapi.yaml --output generated-server

必需标志

  • --input 指向你的OpenAPI规范文件路径（YAML或JSON）。

  • --output 生成的MCP服务器样板代码的目标目录。

可选标志

  • --validation 启用OpenAPI验证（默认：false）。

  • --package 生成的Go包名称（默认：mcpgen）。

  • --includes 用于生成代码的附加包含项的逗号分隔列表。使用httpclient,types来生成HTTP客户端和类型。

示例

mcpgen --input api/openapi.yaml --output ./generated-server --validation --package myserver --includes=httpclient,types

工作原理

mcpgen充当你的声明式OpenAPI规范和MCP服务器所需程序化Go代码之间的桥梁。它读取你的OpenAPI定义并自动生成必要的样板代码，包括对有效AI代理交互至关重要的结构化模式和提示。

让我们通过一个在OpenAPI中定义的中等复杂度的端点示例来说明这一点：

# 这是你的OpenAPI规范的一部分
/todos:
    get:
      tags:
        - Todos
      summary: 列出所有待办事项
      description: 获取待办事项列表，可选地按状态过滤。
      operationId: listTodos
      parameters:
        - name: status
          in: query
          description: 按状态过滤待办事项（例如："pending"，"completed"）
          required: false
          schema:
            type: string
            enum: [pending, completed, in-progress]
        - name: token
          in: cookie
          description: 认证令牌
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 20
        - name: limit
          in: query
          description: 返回的最大待办事项数
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 20
        - name: offset
          in: query
          description: 为分页跳过的待办事项数
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
      responses:
        '200':
          description: 待办事项列表。
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - $ref: '#/components/schemas/Todo'
                    - $ref: '#/components/schemas/NewTodo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

# ... （完整的规范应包括组件如#/components/schemas/Todo，
# #/components/schemas/NewTodo，#/components/responses/BadRequest等）

当你运行mcpgen --input your_openapi.yaml --output generated-server（可选加上--includes=httpclient,types），mcpgen分析这个操作（operationId: listTodos）并生成Go代码。这包括：

  1. 输入的JSON模式: 包含listTodos工具所需和可选参数的JSON模式的常量字符串：

    // ListTodos工具的输入模式
const listTodosInputSchema = `{
  "properties": {
    "limit": {
      "default": 20,
      "description": "返回的最大待办事项数",
      "format": "int32",
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "为分页跳过的待办事项数",
      "format": "int32",
      "minimum": 0,
      "type": "integer"
    },
    "status": {
      "description": "按状态过滤待办事项（例如：\"pending\"，\"completed\"）",
      "enum": [
        "pending",
        "completed",
        "in-progress"
      ],
      "type": "string"
    },
    "token": {
      "default": 20,
      "description": "认证令牌",
      "format": "int32",
      "minimum": 1,
      "type": "integer"
    }
  },
  "type": "object"
}`

  2. 响应的Markdown模板: 包含每个潜在响应的详细markdown提示的常量字符串（基于状态码和内容类型），描述数据的结构和意义。这对于LLMs理解工具的输出至关重要：

    // ListTodos工具的响应模板（状态：200，内容类型：application/json）
const ListTodosResponseTemplate_A = `# API响应信息
...（详细markdown描述200响应结构，包括Todo和NewTodo模式的oneOf组合）...

`

// ListTodos工具的响应模板（状态：400，内容类型：application/json）
const ListTodosResponseTemplate_B = `# API响应信息
...（详细markdown描述400错误响应结构）...

`

// ListTodos工具的响应模板（状态：500，内容类型：application/json）
const ListTodosResponseTemplate_C = `# API响应信息
...（详细markdown描述500错误响应结构）...
`

    注意：完整的markdown模板内容非常详尽，并基于OpenAPI响应模式生成。

  3. MCP工具注册: 创建和配置mcp.Tool实例的函数，嵌入操作描述和生成的输入模式：

    // NewListTodosMCPTool创建ListTodos的MCP工具实例
func NewListTodosMCPTool() mcp.Tool {
	return mcp.NewToolWithRawSchema(
		"ListTodos", // 操作ID成为工具名称
		"列出所有待办事项 - 获取待办事项列表，可选地按状态过滤。", // 摘要+描述
		[]byte(listTodosInputSchema), // 嵌入的输入模式
	)
}

  4. 处理器函数骨架: 一个占位函数，你将在其中编写处理工具调用的代码。此函数接收mcp.CallToolRequest（包含作为JSON的输入负载），在这里你将与实际的后端API集成：

    // ListTodosHandler是ListTodos工具的处理器函数。
// 此函数自动生成。用户应在函数体内实现实际逻辑以与后端API集成。
// 你可以生成类型、HTTP客户端和辅助函数来解析请求参数，以简化实现。
func ListTodosHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
	// 重要：用你的实际逻辑替换以下占位实现。
    // 使用'request'参数访问工具调用参数。
    // 根据需要进行HTTP调用或与服务交互。
    // 返回带有响应负载的*mcp.CallToolResult，或错误。

    // 示例占位实现：
    // 从请求中提取参数并解析它们。
    // 调用你的后端API或使用'params'执行必要的操作。
    // 根据情况处理响应和错误。
	return nil, fmt.Errorf("ListTodos处理器未实现") // 直到你添加你的逻辑为止的占位符
}

通过生成所有这些结构化的样板代码，mcpgen允许你专注于在生成的处理器函数内实现核心集成逻辑——解析输入负载（可能由生成的类型简化）、调用现有的后端API（可能由生成的客户端简化），并将后端响应映射到预期的MCP CallToolResult格式。

许可证

本项目采用MIT许可证。