OpenAPI / REST

Argus 的全部 MCP 工具（约 30 个）同时暴露为 REST 端点 + OpenAPI spec，供非 MCP 客户端使用——脚本、OpenAI function-calling、任意 HTTP 客户端都能调。这套 REST 与 MCP 共享同一份工具实现与按项目隔离的鉴权。

实现：services/mcp-server/src/openapi.ts · 16+ 工具经 REST 暴露，OpenAPI spec 由各工具的 zod schema 自动生成。

工具发现：GET /openapi.json

每个工具对应一个 POST /v1/tools/{name}，其入参 / 返回 schema 全部在 OpenAPI spec 里。这是公开端点，无需鉴权（只含 schema，不含数据）：


export ARGUS_MCP_URL=https://mcp.argusplatform.com   # 本地：http://localhost:8092
curl "$ARGUS_MCP_URL/openapi.json"

在 Swagger UI 里浏览：把上面的 /openapi.json URL 粘进 editor.swagger.io （File → Import URL）或任意 Swagger UI 实例，即可得到可交互的 API explorer。（v0 文档站不内嵌 Swagger UI——避免引入额外运行时依赖；以实时 /openapi.json 为单一真相源。）

调用单个工具：`POST /v1/tools/{name}`

鉴权

用 Bearer PAT（与 MCP 同一个 token，需 mcp:read scope）：


Authorization: Bearer argus_pat_xxxxxxxx

请求

body 是该工具的入参 JSON——不含 project_id（由 token 自动绑定）：


curl -X POST "$ARGUS_MCP_URL/v1/tools/apm.stats" \
  -H "Authorization: Bearer argus_pat_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"days":7}'

响应

返回该工具的结果 JSON。常见状态码：

状态	含义
`200`	成功，body 是工具结果
`400`	入参不合 schema（对照 `/openapi.json` 检查）
`401`	token 缺失/失效，或缺 `mcp:read` scope
`404`	工具名拼错——用 `/openapi.json` 看准确名字

端点一览

方法路径	鉴权	说明
`GET /healthz`	无	健康检查
`GET /openapi.json`	无	工具发现：全部工具的 OpenAPI spec（仅 schema）
`POST /mcp` · `GET /mcp`	Bearer PAT	MCP（StreamableHTTP）——给 Claude/Cursor 等
`POST /v1/tools/{name}`	Bearer PAT	REST 调用单个工具——给脚本 / function-calling

用于 OpenAI function-calling

/openapi.json 里每个工具的入参 schema 可直接转成 OpenAI 的 function / tool 定义。典型流程：

GET /openapi.json 拿到工具清单 + 各自入参 schema。
把工具注册为模型的 functions。
模型决定调用某工具时，你用其入参 POST /v1/tools/{name}，把结果回灌给模型。

因为 project_id 由 token 绑定，模型生成的入参里永远不会、也不需要出现 project_id，天然避免了越权查询。

不在 v0 范围

全量业务 API（如 /v1/projects/{id}/... 资源型 REST）的自动生成文档——本页聚焦 MCP 工具轨的 REST 暴露。
文档站内嵌 Swagger UI 交互面板（以实时 /openapi.json 为准，按上文导入即可）。

示例脚本 examples/mcp-quickstart/query.sh 演示：发现工具（GET /openapi.json）→ 查错误日志 → 性能 p95 → 崩溃 top issue → 用户反馈，全程仅用 curl。