From 2f646bf3ea4e6be7600a1db06a2fb7748d5c6140 Mon Sep 17 00:00:00 2001
From: Vickey <891607480@qq.com>
Date: Thu, 18 Jun 2026 20:14:16 +0800
Subject: [PATCH] docs(gateway): add openapi operations and javadoc to mcp
 gateway

Add @Operation to the MCP gateway endpoints (protected-resource metadata, JSON-RPC handler) and behavior-accurate method JavaDoc. Docs only, no logic changes.
---
 .../gateway/mcp/McpGatewayController.java     | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/dc3-common/dc3-common-gateway/src/main/java/io/github/pnoker/common/gateway/mcp/McpGatewayController.java b/dc3-common/dc3-common-gateway/src/main/java/io/github/pnoker/common/gateway/mcp/McpGatewayController.java
index 3f2d7f6a3..26c1764d4 100644
--- a/dc3-common/dc3-common-gateway/src/main/java/io/github/pnoker/common/gateway/mcp/McpGatewayController.java
+++ b/dc3-common/dc3-common-gateway/src/main/java/io/github/pnoker/common/gateway/mcp/McpGatewayController.java
@@ -30,6 +30,7 @@ import io.github.pnoker.common.facade.api.McpRuntimeFacade;
 import io.github.pnoker.common.utils.DecodeUtil;
 import io.github.pnoker.common.utils.HmacAuthSigner;
 import io.github.pnoker.common.utils.JsonUtil;
+import io.swagger.v3.oas.annotations.Operation;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.apache.commons.lang3.StringUtils;
@@ -82,6 +83,13 @@ public class McpGatewayController {
         return map;
     }
 
+    /**
+     * Publish the RFC 9728 protected-resource metadata that MCP clients fetch to learn
+     * where to obtain bearer tokens and which scopes are accepted.
+     *
+     * @return a metadata map describing the resource, authorization servers, supported bearer methods and scopes
+     */
+    @Operation(summary = "Get Protected Resource Metadata", description = "Return the OAuth 2.0 protected-resource metadata (RFC 9728) advertised at the well-known path, so MCP clients can discover the authorization server, supported bearer transport methods and accepted scopes.")
     @GetMapping(McpConstant.WELL_KNOWN_PROTECTED_RESOURCE)
     public Mono<Map<String, Object>> protectedResourceMetadata() {
         return Mono.just(orderedMap(
@@ -92,6 +100,17 @@ public class McpGatewayController {
         ));
     }
 
+    /**
+     * Handle a single JSON-RPC MCP request (initialize, ping, tools/list, tools/call).
+     * <p>
+     * Requires a valid bearer token; the token is introspected against the auth center
+     * and tool visibility is re-checked before every tools/call.
+     *
+     * @param request JSON-RPC request body carrying the MCP method, id and parameters
+     * @param exchange current server exchange, used to read the Authorization header and client metadata
+     * @return a JSON-RPC result or error entity; 401 with a WWW-Authenticate challenge when the token is missing or inactive
+     */
+    @Operation(summary = "Handle MCP JSON-RPC Request", description = "Process one MCP JSON-RPC request (initialize, ping, tools/list, tools/call) behind the gateway. Validates the bearer token by introspecting it against the auth center, re-checks tool visibility before every tools/call, and returns a JSON-RPC result or error entity, or a 401 challenge when the token is missing or inactive.")
     @PostMapping(value = McpConstant.URL_PREFIX, consumes = MediaType.APPLICATION_JSON_VALUE)
     public Mono<ResponseEntity<Map<String, Object>>> mcp(@RequestBody Map<String, Object> request,
                                                          ServerWebExchange exchange) {