Cursor Composer 2.5 đủ nhanh và rẻ để một tác nhân có thể viết toàn bộ client API và bộ xử lý định tuyến cho bạn. Vấn đề xuất hiện ngay khi mã chạm đến một dịch vụ thực tế: mô hình viết một yêu cầu trông có vẻ sạch sẽ đến /v2/orders trong khi dịch vụ của bạn thực sự hiển thị /orders và mong đợi một payload khác. Mã vẫn biên dịch. Chỉ là nó không hoạt động, và bạn phải mất ba tệp sau mới phát hiện ra.
Hướng dẫn này chỉ ra quy trình làm việc khắc phục điều đó: hướng Composer 2.5 đến thông số kỹ thuật API thực tế của bạn thông qua MCP, để nó tạo mã theo hợp đồng thực tế, sau đó xác minh kết quả trong Apidog trước khi gửi cho đồng đội. Nếu bạn mới làm quen với mô hình này, hướng dẫn về Cursor Composer 2.5 sẽ giải thích nó là gì và cách truy cập.
Tại sao các mô hình tác nhân lại đoán hình dạng API
Composer 2.5 được xây dựng cho các tác vụ tác nhân dài, nhiều bước. Yêu cầu nó "thêm một client cho dịch vụ thanh toán của chúng ta và kết nối nó vào luồng thanh toán" và nó sẽ lập kế hoạch, chỉnh sửa một số tệp và chạy thử nghiệm cho đến khi chúng vượt qua. Đó là nâng cấp so với Composer 2, và nó thực sự hữu ích.
Điểm yếu là về cấu trúc, không phải lỗi. Khi mô hình không có hợp đồng API của bạn trong ngữ cảnh, nó sẽ lấp đầy khoảng trống bằng hình dạng có khả năng thống kê cao nhất: tên trường phổ biến, quy ước REST, tiền tố phiên bản nó thường thấy nhất trong quá trình đào tạo. Đầu ra trông đúng. Nó vượt qua một kiểm tra lint. Nó thất bại đối với máy chủ của bạn vì máy chủ của bạn không phải là mức trung bình của mọi API trên internet.
Ba triệu chứng của điều này:
- Các điểm cuối gần như khớp (
/api/users/{id}so với/users/{userId}của bạn). - Các trường được tạo ra hoặc sai trong phần thân yêu cầu.
- Xử lý xác thực theo cách chung chung thay vì lược đồ thực tế của dịch vụ của bạn.
Bạn có thể khắc phục một số vấn đề này bằng cách nhắc nhở, nhưng việc dán toàn bộ tệp OpenAPI của bạn vào cuộc trò chuyện là không ổn định và đốt cháy ngữ cảnh. Giải pháp lâu dài là cung cấp cho mô hình quyền truy cập có cấu trúc vào spec.
Giải pháp: định hướng Composer 2.5 theo thông số kỹ thuật API thực tế của bạn thông qua MCP
Giao thức ngữ cảnh mô hình (MCP) là tiêu chuẩn mở để cung cấp công cụ và dữ liệu cho các mô hình AI. Cursor hỗ trợ các máy chủ MCP, và máy chủ Apidog MCP hiển thị thông số kỹ thuật API của Apidog cho mô hình như một nguồn có cấu trúc mà nó có thể truy vấn trong khi mã hóa.
Sự khác biệt trong thực tế: thay vì đoán, Composer 2.5 đọc các điểm cuối, lược đồ, tham số và hình dạng phản hồi thực tế của bạn, sau đó viết mã dựa trên chúng. Đây là ý tưởng tương tự đằng sau viết mã vibe với máy chủ Apidog MCP, được áp dụng cho một mô hình hiện đủ mạnh để thực hiện toàn bộ tác vụ.
Bước 1: Chuẩn bị thông số kỹ thuật API của bạn trong Apidog
Hợp đồng API của bạn cần được lưu trữ ở nơi mà mô hình có thể đọc được. Thiết kế hoặc nhập API của bạn trong Apidog để lược đồ, điểm cuối và ví dụ luôn được cập nhật. Nếu bạn bắt đầu từ các tài liệu hiện có, Apidog nhập trực tiếp các bộ sưu tập OpenAPI và Postman. Thông số kỹ thuật là nguồn chân lý mà mô hình sẽ tuân theo, vì vậy việc giữ cho nó chính xác là toàn bộ trò chơi.
Bước 2: Kết nối máy chủ Apidog MCP với Cursor
Cursor đọc các máy chủ MCP từ một tệp cấu hình trong dự án của bạn (thường là .cursor/mcp.json). Máy chủ Apidog MCP chạy thông qua npx và trỏ đến dự án của bạn. Một cấu hình điển hình trông như thế này:
{
"mcpServers": {
"apidog-api-spec": {
"command": "npx",
"args": ["-y", "apidog-mcp-server@latest", "--project=<your-project-id>"],
"env": { "APIDOG_ACCESS_TOKEN": "<your-access-token>" }
}
}
}
Sử dụng lệnh chính xác, ID dự án và token từ hướng dẫn cài đặt Apidog MCP, vì các giá trị đó cụ thể cho tài khoản của bạn và phiên bản máy chủ. Khởi động lại Cursor sau khi lưu để nó nhận máy chủ mới.
Bước 3: Xác nhận Composer 2.5 có thể nhìn thấy thông số kỹ thuật
Mở một phiên tác nhân, chọn composer-2.5 trong bộ chọn mô hình và hỏi một câu hỏi chỉ đọc trước:
“Sử dụng máy chủ MCP apidog-api-spec, liệt kê các điểm cuối dưới tài nguyên orders và các trường bắt buộc để tạo một order.”
Nếu nó trả về các điểm cuối và trường thực tế của bạn, kết nối hoạt động. Nếu nó trả lời từ kiến thức chung, máy chủ chưa được kết nối; kiểm tra lại cấu hình và khởi động lại.
Bước 4: Để nó xây dựng dựa trên hợp đồng
Bây giờ hãy giao cho nó nhiệm vụ thực tế và đặt tên cho thông số kỹ thuật một cách rõ ràng:
“Sử dụng máy chủ apidog-api-spec làm nguồn chân lý, viết một client TypeScript được định kiểu cho API orders, bao gồm các lời gọi create-order và get-order. Khớp chính xác các lược đồ yêu cầu và phản hồi. Thêm xử lý lỗi cho phản hồi xác thực 422 mà thông số kỹ thuật định nghĩa.”
Vì Composer 2.5 duy trì tốt các tác vụ dài, nó có thể làm điều này trên nhiều tệp và giữ cho hợp đồng nhất quán. Việc đặt tên nguồn MCP trong lời nhắc giúp nó được neo giữ thay vì trôi dạt trở lại các giả định.
Xác minh trước khi tin tưởng: vòng lặp kiểm thử Apidog
Việc định hướng mô hình cắt giảm đáng kể các ảo giác. Nhưng điều đó không làm cho việc xác minh trở thành tùy chọn. Một thông số kỹ thuật có thể hơi lạc hậu so với dịch vụ đang chạy, và một mô hình vẫn có thể đọc sai một trường hợp biên.
Khép kín vòng lặp:
- Gửi các cuộc gọi đã tạo như các yêu cầu thực tế. Lấy các điểm cuối mà Composer 2.5 đã viết và chạy chúng trong Apidog trong môi trường thực hoặc giả. Kiểm tra mã trạng thái, phần thân phản hồi và xác thực hoạt động như mã đã giả định.
- Biến các cuộc gọi hoạt động thành các bài kiểm thử. Lưu các yêu cầu đã được xác thực dưới dạng các kịch bản kiểm thử tự động để lần hồi quy tiếp theo được phát hiện bởi CI, chứ không phải bởi người dùng.
- Giả lập những gì chưa được xây dựng. Nếu mô hình đã viết một client cho một điểm cuối mà backend chưa triển khai, máy chủ giả lập của Apidog trả về các phản hồi thực tế để công việc frontend tiếp tục. Điều này kết hợp tốt với các mẫu trong các tác nhân AI và kiểm thử API.
Nguyên tắc: mô hình viết bản nháp đầu tiên dựa trên hợp đồng, và bạn xác nhận bản nháp hoạt động đối với một máy chủ thực. Tốc độ từ tác nhân chỉ có giá trị nếu bạn không phải trả lại bằng cách gỡ lỗi sau này.
Một ví dụ thực tế từ đầu đến cuối
Giả sử bạn đang thêm một tính năng hoàn tiền vào dịch vụ thanh toán.
- Các điểm cuối và lược đồ hoàn tiền đã tồn tại trong dự án Apidog của bạn từ giai đoạn thiết kế.
- Apidog MCP được kết nối với Cursor; Composer 2.5 được chọn.
- Bạn nhắc: “Sử dụng apidog-api-spec, xây dựng client hoàn tiền và một React hook gọi nó. Tuân thủ chính xác lược đồ, bao gồm tiêu đề idempotency-key mà spec yêu cầu.”
- Composer 2.5 đọc hợp đồng thực tế, viết client, hook và các kiểu, và chạy các bài kiểm thử của dự án.
- Bạn mở Apidog, gửi yêu cầu tạo hoàn tiền thực tế, xác nhận hành vi idempotency và lỗi 409 khi trùng lặp, sau đó lưu cả hai dưới dạng các kịch bản kiểm thử.
Điều bạn đã tránh được: một client quên tiêu đề idempotency, đã triển khai và hoàn tiền gấp đôi cho khách hàng trong môi trường staging. Đó là loại lỗi mà việc định hướng cùng với xác minh sẽ loại bỏ.
Các câu hỏi thường gặp
Composer 2.5 có hỗ trợ MCP không? Có. Nó có quyền truy cập vào bộ công cụ tác nhân đầy đủ của Cursor, bao gồm các máy chủ MCP. Chọn nó trong bộ chọn mô hình và cấu hình máy chủ trong dự án của bạn. Hướng dẫn Composer 2.5 bao gồm việc lựa chọn mô hình.
Tôi có cần Apidog để sử dụng MCP với Composer 2.5 không? Bạn cần một nguồn spec có cấu trúc. Máy chủ Apidog MCP là lộ trình được đề cập ở đây vì nó cũng cung cấp cho bạn khả năng kiểm thử và giả lập ở cùng một nơi. Các tùy chọn khác tồn tại trong tổng hợp các máy chủ MCP tốt nhất cho Cursor.
Việc định hướng mô hình theo một spec có ngăn chặn mọi ảo giác không? Nó loại bỏ danh mục lớn nhất, các điểm cuối và lược đồ sai, vì mô hình đọc hợp đồng thực tế thay vì đoán. Nó không thay thế việc kiểm thử; các spec có thể lệch khỏi các dịch vụ đang chạy, vì vậy bạn vẫn phải xác minh.
Điều này có đáng giá cho một dự án nhỏ không? Nếu mô hình chạm vào bất kỳ API thực tế nào, thì có. Thiết lập chỉ là một tệp cấu hình một lần. Phần thưởng là mọi cuộc gọi được tạo ra đều khớp với hợp đồng của bạn thay vì một phỏng đoán hợp lý.
Tổng kết
Composer 2.5 đủ nhanh và rẻ để một tác nhân có thể đảm nhiệm công việc API thực tế. Điều đó chỉ có lợi nếu mô hình mã hóa dựa trên hợp đồng thực tế của bạn thay vì một phỏng đoán trung bình. Kết nối spec của bạn thông qua máy chủ Apidog MCP để Composer 2.5 đọc sự thật, sau đó Tải xuống Apidog để gửi các yêu cầu trực tiếp, xác nhận các phản hồi và khóa các cuộc gọi hoạt động vào các bài kiểm thử và giả lập tự động. Tạo mã có cơ sở cùng với xác minh là quy trình làm việc biến tốc độ của tác nhân thành các tính năng đã được triển khai.