Máy chủ OpenAPI MCP

Máy chủ “OpenAPI” MCP làm gì?

OpenAPI MCP Server là một máy chủ Model Context Protocol (MCP) được thiết kế để kết nối các trợ lý AI (như Claude và Cursor) với khả năng tìm kiếm và khám phá đặc tả OpenAPI thông qua oapis.org. Đóng vai trò cầu nối, nó giúp các mô hình AI hiểu sâu về các API phức tạp bằng ngôn ngữ đơn giản. Máy chủ thực hiện theo ba bước: xác định đặc tả OpenAPI cần thiết, tóm tắt bằng ngôn ngữ dễ tiếp cận và trình bày chi tiết các endpoint cùng cách sử dụng. Mặc dù không thực thi endpoint API trực tiếp (do giới hạn xác thực), nhưng nó xuất sắc trong việc cung cấp tổng quan API, hỗ trợ sinh mã và phục vụ quy trình phát triển trong các trường hợp cần hiểu và tài liệu hóa cấu trúc API.

Danh sách các Prompt

• Overview Prompt: Yêu cầu tóm tắt và hiểu một đặc tả OpenAPI.
• Operation Details Prompt: Lấy mô tả chi tiết về các thao tác API cụ thể.
• Endpoint Identification Prompt: Xác định những endpoint liên quan dựa trên truy vấn.

Danh sách tài nguyên

• Tổng quan đặc tả OpenAPI: Cung cấp tóm tắt toàn bộ đặc tả API.
• Chi tiết thao tác API: Cung cấp ngữ cảnh về các endpoint cụ thể và tham số của chúng.
• Đa dạng định dạng: Hỗ trợ đặc tả API ở cả định dạng JSON và YAML.
• Tài nguyên tương thích: Đã kiểm thử với Claude Desktop và Cursor để truyền tải ngữ cảnh mượt mà.

Danh sách công cụ

• Không có công cụ thực thi nào được cung cấp trong bản v2; máy chủ tập trung vào khám phá và cung cấp ngữ cảnh về API mà không cho phép thực thi endpoint trực tiếp như một công cụ.

Các trường hợp sử dụng MCP Server này

• Sinh tài liệu API: Tạo tự động tài liệu dễ đọc từ đặc tả OpenAPI phức tạp, giúp nhà phát triển dễ hiểu hơn.
• Hỗ trợ sinh mã API: Hỗ trợ nhà phát triển sinh mã client nhờ mô tả endpoint rõ ràng và chi tiết sử dụng.
• Khám phá và tìm hiểu API: Nhanh chóng xác định và tóm tắt các endpoint hiện có, giúp nhóm hoặc mô hình AI khám phá khả năng API.
• Cung cấp ngữ cảnh cho tác nhân AI: Đưa ngữ cảnh API phù hợp cho LLM hoặc tác nhân, giúp cải thiện khả năng trả lời hoặc viết code liên quan API ngoài.
• Hỗ trợ đào tạo và hội nhập: Giúp thành viên mới hoặc tác nhân AI học API lạ thông qua tóm tắt đơn giản và phân tích thao tác.

Cách thiết lập

Windsurf

1. Đảm bảo Node.js đã được cài đặt trên hệ thống của bạn.
2. Mở file cấu hình Windsurf.
3. Thêm OpenAPI MCP Server vào mục mcpServers bằng đoạn JSON cung cấp.
4. Lưu cấu hình và khởi động lại Windsurf.
5. Kiểm tra kết nối với máy chủ MCP.

Ví dụ cấu hình:

{
  "mcpServers": {
    "openapi-mcp": {
      "command": "npx",
      "args": ["@janwilmake/openapi-mcp-server@latest"],
      "env": {
        "OAS_API_KEY": "${OAS_API_KEY}"
      }
    }
  }
}

Lưu ý: Bảo mật khóa API bằng biến môi trường như ví dụ trên.

Claude

1. Cài đặt Node.js.
2. Truy cập phần tích hợp MCP của Claude.
3. Thêm máy chủ OpenAPI MCP với cấu hình sau.
4. Lưu cài đặt và khởi động lại Claude.
5. Xác nhận máy chủ đã khả dụng như một tài nguyên MCP.

Ví dụ cấu hình:

{
  "mcpServers": {
    "openapi-mcp": {
      "command": "npx",
      "args": ["@janwilmake/openapi-mcp-server@latest"],
      "env": {
        "OAS_API_KEY": "${OAS_API_KEY}"
      }
    }
  }
}

Cursor

1. Đảm bảo Node.js đã được cài đặt.
2. Xác định file cấu hình của Cursor.
3. Thêm máy chủ OpenAPI MCP vào mcpServers.
4. Lưu và khởi động lại Cursor.
5. Kiểm tra bằng truy vấn OpenAPI mẫu.

Ví dụ cấu hình:

{
  "mcpServers": {
    "openapi-mcp": {
      "command": "npx",
      "args": ["@janwilmake/openapi-mcp-server@latest"],
      "env": {
        "OAS_API_KEY": "${OAS_API_KEY}"
      }
    }
  }
}

Cline

1. Cài đặt Node.js nếu chưa có.
2. Chỉnh sửa file cấu hình của Cline để thêm OpenAPI MCP.
3. Thêm đoạn JSON sau.
4. Lưu thay đổi và khởi động lại Cline.
5. Xác nhận máy chủ MCP đã hoạt động.

Ví dụ cấu hình:

{
  "mcpServers": {
    "openapi-mcp": {
      "command": "npx",
      "args": ["@janwilmake/openapi-mcp-server@latest"],
      "env": {
        "OAS_API_KEY": "${OAS_API_KEY}"
      }
    }
  }
}

Bảo mật khóa API:
Lưu trữ khóa nhạy cảm trong biến môi trường và tham chiếu trong cấu hình như thuộc tính env đã trình bày.

Cách sử dụng MCP này trong các luồng

Sử dụng MCP trong FlowHunt

Để tích hợp máy chủ MCP vào quy trình FlowHunt, hãy thêm thành phần MCP vào luồng và kết nối nó với tác nhân AI của bạn:

Nhấp vào thành phần MCP để mở bảng cấu hình. Trong phần cấu hình MCP hệ thống, chèn thông tin máy chủ MCP của bạn theo định dạng JSON sau:

{
  "openapi-mcp": {
    "transport": "streamable_http",
    "url": "https://yourmcpserver.example/pathtothemcp/url"
  }
}

Sau khi cấu hình, tác nhân AI có thể sử dụng MCP này như một công cụ với đầy đủ chức năng và khả năng. Đừng quên thay “openapi-mcp” thành tên thực tế của máy chủ MCP và thay URL bằng địa chỉ máy chủ MCP của bạn.

Tổng quan

Ý kiến của chúng tôi

OpenAPI MCP Server là một MCP tập trung, hữu ích, xuất sắc trong việc cung cấp ngữ cảnh và công cụ khám phá đặc tả OpenAPI. Việc không thực thi endpoint là hạn chế cho một số trường hợp nâng cao, và chưa có tài liệu về hỗ trợ sampling/roots. Tuy nhiên, hướng dẫn thiết lập rõ ràng, mã nguồn tốt và cộng đồng sử dụng tích cực giúp nó trở thành lựa chọn mạnh mẽ cho nhà phát triển cần ngữ cảnh API và hỗ trợ sinh mã.

Điểm MCP