Tools reference

list_endpoints、get_endpoint、lint_spec、diff_specs 和 contract_test：它们的输入、输出，以及示例响应。

list_endpoints

列出目录中的每一个端点（method、path 和 summary），不含请求/响应细节。用它在调用 get_endpoint 之前先了解都有哪些端点。

可选的 filter 参数：对 path、summary 或 tags 做不区分大小写的子串匹配。

text
GET /
POST /auth/register — Register
POST /auth/login — Login
GET /auth/profile — Get profile

get_endpoint

根据给定的 method 和 path，返回某个端点完整的 Copy for AI 格式文本（Purpose、Request、Parameters、Validation、Success Response 和 Error Responses）。

text
Endpoint: POST /auth/login

Purpose:
Login

Request:
{
  "email": "string",
  "password": "string"
}

Validation:
- email must be valid

Success Response (201):
{
  "success": "boolean",
  "data": { "access_token": "string", "user": { "id": "string", "role": "string" } }
}

Error Responses:
400 Bad Request

lint_spec

检查已加载目录中的 spec 质量问题：缺失的 summary/description、缺失的 tags、缺失的 4xx/5xx 响应、没有描述的响应，以及重复的 operation ID。

text
✖ POST /auth/login: [missing-description] no description declared
✖ POST /auth/login: [no-error-response] no 4xx/5xx response declared

diff_specs

把已加载的目录和另一份 spec（以 path 指定本地文件，或以 url 指定远程地址）比较，报告新增/删除的端点，以及破坏性和提示性的字段变更（新增的必填参数、requestBody 变成必填、某个响应状态码被删除）。

text
+ POST /users
- DELETE /users/{id}
! GET /users/{id}: parameter "id" (path) is now required

contract_test

对一个已经基于所加载 spec 运行起来的服务器，向每个端点（或过滤后的一个子集）发起真实请求，并对照声明的 schema 校验每一个真实响应。相当于一个零配置的 Postman collection runner。

接受 baseUrl、一个可选的 headers 列表（可重复的 "Name: value" 字符串，比如鉴权信息），以及一个可选的 filter 用于测试子集。

text
✓ GET /users (http://localhost:3000/users) — 200, matches schema
✖ POST /users (http://localhost:3000/users) — 201, 1 mismatch(es): body.email (required property missing)