语义至关重要：如何将 OpenAPI 规范转化为 MCP 工具

openapi: 3.0.3
info:
  title: Enhanced Todo API
  description: >
    本 API 提供了管理个人或团队待办事项（todos）的能力，包括创建、更新、组织和检索任务，任务附带丰富的元数据，如截止日期、优先级和标签。
    该 API 专为系统和 AI Agent 设计，支持动态任务协调、进度追踪和工作流规划。
    特别适用于目标跟踪、工作助手或生产力工具等需要任务编排和上下文决策的场景。
  version: 1.0.0
  termsOfService: https://example.com/terms/
  contact:
    name: API Support Team
    url: https://example.com/support
    email: [email protected]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

externalDocs:
  description: 查看该 API 所有使用场景的详细文档
  url: https://example.com/docs

  /todos:
    get:
      summary: 获取现有待办事项，用于上下文任务感知与规划
      description: >
        客户端或 AI Agent 可调用该接口，检索现有的待办事项列表，支持按完成状态过滤、分页控制。
        该能力可帮助理解当前任务状态、识别待办任务、规划下一步行动。
        特别适用于依赖实时上下文的工作流，如生产力跟踪、个人助手、自动化规划系统。
      operationId: listAllTodoTasks
      tags:
        - todos
      parameters:
        - name: limit
          in: query
          description: 返回的最大条目数
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
        - name: completed
          in: query
          description: 按任务完成状态进行筛选
          schema:
            type: boolean
      responses:
        '200':
          description: JSON 格式的待办事项数组
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Todo'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

openapi: 3.0.3
info:
  # 为简洁省略部分内容
  x-linkedData:
    "@context":
      schema: "https://schema.org/"
      hydra: "http://www.w3.org/ns/hydra/core#"
      vocab: "https://api.example.com/vocab#"
    "@type": "schema:WebAPI"
    "@id": "https://api.example.com/v1"
    "schema:name": "Enhanced Todo API"
    "schema:description": "一个提供待办管理、元数据和语义注释的综合 API"
    "schema:provider":
      "@type": "schema:Organization"
      "schema:name": "Example Organization"
      "schema:url": "https://example.com"
    "schema:dateModified": "2025-04-15"

  /todos:
    get:
      summary: 获取现有待办事项，用于上下文任务感知与规划
      description: 简要描述在此
      tags:
        - todos
      x-company-mcp:
        name: very-descriptive-name-here
        description: 更详细的描述信息

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": {
    "tools": [
      {
        "name": "listAllTodoTasks",
        "description": "允许客户端或 AI Agent 检索现有的待办事项列表，支持按完成状态过滤并支持分页参数限制。
        该能力有助于理解当前任务状态、识别未完成事项以及规划后续行动。适用于生产力追踪、个人助手或依赖实时上下文的自动化规划系统。",
        "inputSchema": {
          "type": "object",
          "properties": {
            "limit": {
              "type": "integer",
              "description": "返回的最大项数（1-100）",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "completed": {
              "type": "boolean",
              "description": "按完成状态筛选"
            }
          }
        },
        "annotations": {
          "title": "增强版 Todo API",
          "readOnlyHint": true,
          "openWorldHint": false
        }
      }
    ]
  }
}