From cbc34a12c9f0f96c3b89cbbaac34365120357ecc Mon Sep 17 00:00:00 2001
From: matevip <matevip@mate.vip>
Date: Sat, 2 May 2026 15:41:53 +0800
Subject: [PATCH] docs(mcp): align /tools javadoc with HTTP 200 + biz-code
 convention

---
 .../mcp/controller/McpServerController.java   | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/mateclaw-server/src/main/java/vip/mate/tool/mcp/controller/McpServerController.java b/mateclaw-server/src/main/java/vip/mate/tool/mcp/controller/McpServerController.java
index 8ac4db2e..fef5937f 100644
--- a/mateclaw-server/src/main/java/vip/mate/tool/mcp/controller/McpServerController.java
+++ b/mateclaw-server/src/main/java/vip/mate/tool/mcp/controller/McpServerController.java
@@ -82,10 +82,21 @@ public class McpServerController {
      * RFC-03 Lane A3 — list the tools surfaced by an MCP server (QwenPaw #2495).
      *
      * <p>Reads from the in-memory cache populated on connect/refresh, so the
-     * call is non-blocking and safe to poll from the admin UI. Returns an
-     * empty list when the server is configured but disconnected, in error
-     * state, or has no tools — never an error response in that case.
-     * 404 is reserved for "the server id doesn't exist".
+     * call is non-blocking and safe to poll from the admin UI.
+     *
+     * <p><b>Response contract</b> (matches project convention "HTTP 200 + biz code"):
+     * <ul>
+     *   <li>Server exists, connected with discovered tools → HTTP 200, {@code code=200},
+     *       {@code data} = list of {name, description, inputSchema}.</li>
+     *   <li>Server exists but disconnected / in error / no tools → HTTP 200,
+     *       {@code code=200}, {@code data=[]}. The UI renders "no tools yet" rather
+     *       than an error toast.</li>
+     *   <li>Server id does not exist → HTTP 200, {@code code=500},
+     *       {@code msg="MCP server 不存在: {id}"}. The not-found path goes through
+     *       {@code MateClawException("err.mcp.not_found")} which the global handler
+     *       maps to a 200/500 envelope; callers detect not-found via {@code code != 200},
+     *       not via the HTTP status (consistent with every other CRUD endpoint).</li>
+     * </ul>
      */
     @Operation(summary = "列出 MCP Server 已发现的工具")
     @GetMapping("/{id}/tools")