修改注释

Author: relat-ivity

framework/fel/java/plugins/tool-mcp-server/src/main/java/modelengine/fel/tool/mcp/server/config/McpSseServerConfig.java

@@ -18,7 +18,7 @@
 import java.time.Duration;
 
 /**
- * Mcp Server Bean implemented with MCP SDK.
+ * MCP SSE Server Bean implemented with MCP SDK.
  *
  * @author 黄可欣
  * @since 2025-11-10

framework/fel/java/plugins/tool-mcp-server/src/main/java/modelengine/fel/tool/mcp/server/config/McpStreamableServerConfig.java

@@ -18,7 +18,7 @@
 import java.time.Duration;
 
 /**
- * Mcp Server Bean implemented with MCP SDK.
+ * MCP Streamable Server Bean implemented with MCP SDK.
  *
  * @author 黄可欣
  * @since 2025-10-22

framework/fel/java/plugins/tool-mcp-server/src/main/java/modelengine/fel/tool/mcp/server/support/DefaultMcpServer.java

@@ -49,8 +49,9 @@ public class DefaultMcpServer implements McpServer, ToolChangedObserver {
     /**
      * Constructs a new instance of the DefaultMcpServer class.
      *
-     * @param toolExecuteService The service used to execute tools when handling tool call requests.
-     * @throws IllegalArgumentException If {@code toolExecuteService} is null.
+     * @param toolExecuteService The service used to execute tools when handling tool call requests
+     * @param mcpSyncSseServer The MCP sync server for SSE transport
+     * @param mcpSyncStreamableServer The MCP sync server for Streamable transport
      */
     public DefaultMcpServer(ToolExecuteService toolExecuteService,
             @Fit(alias = "McpSyncSseServer") McpSyncServer mcpSyncSseServer,
@@ -122,17 +123,11 @@ public void onToolRemoved(String name) {
 
     /**
      * Creates a tool specification for the MCP server.
-     * <p>
-     * This method constructs a {@link McpServerFeatures.SyncToolSpecification} that includes:
-     * <ul>
-     *     <li>Tool metadata (name, description, input schema)</li>
-     *     <li>Call handler that executes the tool and handles exceptions</li>
-     * </ul>
      *
-     * @param name The name of the tool.
-     * @param description The description of the tool.
-     * @param parameters The parameter schema containing type, properties, and required fields.
-     * @return A fully configured {@link McpServerFeatures.SyncToolSpecification}.
+     * @param name The name of the tool
+     * @param description The description of the tool
+     * @param parameters The parameter schema containing type, properties, and required fields
+     * @return A configured {@link McpServerFeatures.SyncToolSpecification}
      */
     private McpServerFeatures.SyncToolSpecification createToolSpecification(String name, String description,
             Map<String, Object> parameters) {
@@ -152,16 +147,10 @@ private McpServerFeatures.SyncToolSpecification createToolSpecification(String n
 
     /**
      * Executes a tool and handles any exceptions that may occur.
-     * <p>
-     * This method handles two types of exceptions:
-     * <ul>
-     *     <li>{@link IllegalArgumentException}: Invalid tool arguments (logged as warning)</li>
-     *     <li>{@link Exception}: Any other execution failure (logged as error)</li>
-     * </ul>
      *
-     * @param toolName The name of the tool to execute.
-     * @param request The tool call request containing arguments.
-     * @return A {@link McpSchema.CallToolResult} with the execution result or error message.
+     * @param toolName The name of the tool to execute
+     * @param request The tool call request containing arguments
+     * @return A {@link McpSchema.CallToolResult} with the execution result or error message
      */
     private McpSchema.CallToolResult executeToolWithErrorHandling(String toolName, McpSchema.CallToolRequest request) {
         try {

framework/fel/java/plugins/tool-mcp-server/src/main/java/modelengine/fel/tool/mcp/server/transport/FitMcpSseServerTransportProvider.java

@@ -55,9 +55,6 @@ public class FitMcpSseServerTransportProvider implements McpServerTransportProvi
     private static final Logger logger = Logger.get(FitMcpSseServerTransportProvider.class);
     private static final String MESSAGE_ENDPOINT = "/mcp/message";
     private static final String SSE_ENDPOINT = "/mcp/sse";
-    /**
-     * Event type for sending the message endpoint URI to clients.
-     */
     public static final String ENDPOINT_EVENT_TYPE = "endpoint";
 
     private final McpJsonMapper jsonMapper;
@@ -94,11 +91,21 @@ private FitMcpSseServerTransportProvider(McpJsonMapper jsonMapper, Duration keep
         }
     }
 
+    /**
+     * Returns the list of supported MCP protocol versions.
+     *
+     * @return A list of supported protocol version strings
+     */
     @Override
     public List<String> protocolVersions() {
         return List.of(ProtocolVersions.MCP_2024_11_05);
     }
 
+    /**
+     * Sets the session factory used to create new MCP server sessions.
+     *
+     * @param sessionFactory The factory for creating server sessions
+     */
     @Override
     public void setSessionFactory(McpServerSession.Factory sessionFactory) {
         this.sessionFactory = sessionFactory;
@@ -162,15 +169,15 @@ public Mono<Void> closeGracefully() {
      * establishing an SSE connection. This method:
      * <ul>
      * <li>Generates a unique session ID</li>
-     * <li>Creates a new session with a FitMcpSessionTransport</li>
-     * <li>Sends an initial endpoint event to inform the client where to send
-     * messages</li>
+     * <li>Creates a new session with a {@link FitSseMcpSessionTransport}</li>
+     * <li>Sends an initial endpoint event to inform the client where to send messages</li>
      * <li>Maintains the session in the sessions map</li>
      * </ul>
      *
      * @param request The incoming server request
-     * @return A ServerResponse configured for SSE communication, or an error response if
-     * the server is shutting down or the connection fails
+     * @param response The HTTP response for SSE communication
+     * @return A {@link Choir}{@code <}{@link TextEvent}{@code >} object for SSE streaming,
+     * or an error response if the server is shutting down or the connection fails
      */
     @GetMapping(path = SSE_ENDPOINT)
     public Object handleSseConnection(HttpClassicServerRequest request, HttpClassicServerResponse response) {
@@ -212,14 +219,16 @@ public Object handleSseConnection(HttpClassicServerRequest request, HttpClassicS
     /**
      * Handles incoming JSON-RPC messages from clients. This method:
      * <ul>
+     * <li>Validates the session ID from the request parameter</li>
      * <li>Deserializes the request body into a JSON-RPC message</li>
      * <li>Processes the message through the session's handle method</li>
      * <li>Returns appropriate HTTP responses based on the processing result</li>
      * </ul>
      *
      * @param request The incoming server request containing the JSON-RPC message
-     * @return A ServerResponse indicating success (200 OK) or appropriate error status
-     * with error details in case of failures
+     * @param response The HTTP response to set status code and return data
+     * @param sessionId The session ID from the request parameter
+     * @return An error {@link Entity} if validation fails, or {@code null} on success
      */
     @PostMapping(path = MESSAGE_ENDPOINT)
     public Object handleMessage(HttpClassicServerRequest request, HttpClassicServerResponse response,
@@ -258,6 +267,14 @@ public Object handleMessage(HttpClassicServerRequest request, HttpClassicServerR
         }
     }
 
+    /**
+     * Adds an observer to the SSE emitter to handle connection lifecycle events.
+     * The observer removes the session from the sessions map when the connection
+     * completes or fails.
+     *
+     * @param emitter The SSE emitter to observe
+     * @param sessionId The session ID associated with this emitter
+     */
     private void addEmitterObserver(Emitter<TextEvent> emitter, String sessionId) {
         emitter.observe(new Emitter.Observer<TextEvent>() {
             @Override
@@ -307,25 +324,31 @@ private Object validateRequestSessionId(String sessionId, HttpClassicServerRespo
     }
 
     /**
-     * Implementation of McpServerTransport for WebMVC SSE sessions. This class handles
-     * the transport-level communication for a specific client session.
+     * Implementation of {@link McpServerTransport} for FIT SSE sessions.
+     * This class handles the transport-level communication for a specific client session.
+     *
+     * <p>
+     * This class is thread-safe and uses a {@link ReentrantLock} to synchronize access to the
+     * underlying SSE emitter to prevent race conditions when multiple threads attempt to
+     * send messages concurrently.
      */
     private class FitSseMcpSessionTransport implements McpServerTransport {
         private final String sessionId;
         private final Emitter<TextEvent> emitter;
         private final HttpClassicServerResponse response;
 
         /**
-         * Lock to ensure thread-safe access to the SSE builder when sending messages.
+         * Lock to ensure thread-safe access to the SSE emitter when sending messages.
          * This prevents concurrent modifications that could lead to corrupted SSE events.
          */
         private final ReentrantLock sseBuilderLock = new ReentrantLock();
 
         /**
-         * Creates a new session transport with the specified ID and SSE builder.
+         * Creates a new session transport with the specified ID and SSE emitter.
          *
          * @param sessionId The unique identifier for this session
-         * @param emitter The emitter for sending events
+         * @param emitter The emitter for sending SSE events to the client
+         * @param response The HTTP response for checking connection status
          */
         FitSseMcpSessionTransport(String sessionId, Emitter<TextEvent> emitter, HttpClassicServerResponse response) {
             this.sessionId = sessionId;
@@ -336,14 +359,16 @@ private class FitSseMcpSessionTransport implements McpServerTransport {
 
         /**
          * Sends a JSON-RPC message to the client through the SSE connection.
+         * The message is serialized to JSON and sent as an SSE event with type "message".
+         * This method is thread-safe and checks if the connection is still active before sending.
          *
          * @param message The JSON-RPC message to send
          * @return A Mono that completes when the message has been sent
          */
         @Override
         public Mono<Void> sendMessage(McpSchema.JSONRPCMessage message) {
             return Mono.fromRunnable(() -> {
-                sseBuilderLock.lock();
+                this.sseBuilderLock.lock();
                 // Check if connection is still active before sending
                 if (!this.response.isActive()) {
                     logger.warn("[SSE] Connection inactive detected while sending message. [sessionId={}]",
@@ -367,7 +392,7 @@ public Mono<Void> sendMessage(McpSchema.JSONRPCMessage message) {
                             e);
                     this.emitter.fail(e);
                 } finally {
-                    sseBuilderLock.unlock();
+                    this.sseBuilderLock.unlock();
                 }
             });
         }
@@ -397,20 +422,21 @@ public Mono<Void> closeGracefully() {
 
         /**
          * Closes the transport immediately.
+         * Completes the SSE emitter and releases any associated resources.
          */
         @Override
         public void close() {
-            sseBuilderLock.lock();
-            logger.debug("[SSE] Closing session transport. [sessionId={}]", sessionId);
+            this.sseBuilderLock.lock();
+            logger.debug("[SSE] Closing session transport. [sessionId={}]", this.sessionId);
             try {
                 this.emitter.complete();
-                logger.info("[SSE] Closed SSE builder successfully. [sessionId={}]", sessionId);
+                logger.info("[SSE] Closed SSE builder successfully. [sessionId={}]", this.sessionId);
             } catch (Exception e) {
                 logger.warn("[SSE] Failed to complete SSE builder. [sessionId={}, error={}]",
-                        sessionId,
+                        this.sessionId,
                         e.getMessage());
             } finally {
-                sseBuilderLock.unlock();
+                this.sseBuilderLock.unlock();
             }
         }