docs: complete and improve Javadoc across main sources

Document public API and key internals (AnnotationProcessor, component registration, and configuration builders) for clearer published API docs.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: codeboyzhou

src/main/java/com/github/thought2code/mcp/annotated/configuration/ConfigurationLoader.java

@@ -14,12 +14,12 @@
 import org.slf4j.LoggerFactory;
 
 /**
- * This record represents a YAML configuration loader for MCP (Model Context Protocol) server
- * configuration.
+ * Loads and merges {@link ServerConfiguration} from YAML files on the classpath or filesystem.
  *
- * <p>It loads the server configuration from a specified YAML file. If no file name is provided, the
- * default file name "mcp-server.yml" will be used.
+ * <p>When {@code profile} is set in the base file, a companion {@code mcp-server-{profile}.yml} is
+ * merged on top using Jackson merge semantics.
  *
+ * @param configFileName YAML file name (for example {@code mcp-server.yml})
  * @see <a href="https://thought2code.github.io/mcp-annotated-java-sdk/getting-started">MCP
  *     Annotated Java SDK Documentation</a>
  * @author codeboyzhou

src/main/java/com/github/thought2code/mcp/annotated/configuration/ServerCapabilities.java

@@ -3,8 +3,16 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 /**
- * This record represents the capabilities of an MCP (Model Context Protocol) server.
+ * MCP capability flags loaded from server configuration.
  *
+ * <p>Each flag maps to whether the server advertises support for resources, prompts, tools,
+ * completions, and resource subscriptions during initialization.
+ *
+ * @param resource whether listing/reading resources is supported
+ * @param subscribeResource whether resource subscription is supported
+ * @param prompt whether prompts are supported
+ * @param tool whether tools are supported
+ * @param completion whether argument completions are supported
  * @author codeboyzhou
  */
 public record ServerCapabilities(
@@ -23,7 +31,11 @@ public static Builder builder() {
     return new Builder();
   }
 
-  /** Builder class for {@code ServerCapabilities}. */
+  /**
+   * Mutable builder for {@link ServerCapabilities}.
+   *
+   * <p>Each flag maps to an MCP server capability advertised during initialization.
+   */
   public static class Builder {
     /** The resource capability. */
     private Boolean resource = ServerDefaults.CAPABILITY_ENABLED;

src/main/java/com/github/thought2code/mcp/annotated/configuration/ServerChangeNotification.java

@@ -3,12 +3,11 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 /**
- * This record represents a change notification for MCP (Model Context Protocol) server
- * capabilities.
- *
- * <p>It contains boolean flags indicating whether the server supports resource, prompt, and tool
- * change notification.
+ * MCP list-change notification capability flags from server configuration.
  *
+ * @param resource whether the server may notify clients when the resource list changes
+ * @param prompt whether the server may notify clients when the prompt list changes
+ * @param tool whether the server may notify clients when the tool list changes
  * @author codeboyzhou
  */
 public record ServerChangeNotification(
@@ -25,7 +24,11 @@ public static Builder builder() {
     return new Builder();
   }
 
-  /** Builder class for {@code ServerChangeNotification}. */
+  /**
+   * Mutable builder for {@link ServerChangeNotification}.
+   *
+   * <p>Controls whether list-change notifications are emitted per component kind.
+   */
   public static class Builder {
     /** The resource change notification flag. */
     private Boolean resource = ServerDefaults.CHANGE_NOTIFICATION_ENABLED;

src/main/java/com/github/thought2code/mcp/annotated/configuration/ServerConfiguration.java

@@ -7,12 +7,24 @@
 import com.github.thought2code.mcp.annotated.util.StringHelper;
 
 /**
- * This record represents the configuration of an MCP (Model Context Protocol) server.
+ * Root YAML configuration for an annotated MCP server application.
  *
- * <p>It contains various properties such as enabled status, server mode, name, version, type,
- * instructions, request timeout, capabilities, change notification, SSE (Server-Sent Events), and
- * streamable configuration.
+ * <p>Loaded by {@link ConfigurationLoader} and merged with profile-specific overlays. Drives server
+ * mode ({@link com.github.thought2code.mcp.annotated.enums.ServerMode}), transport endpoints, MCP
+ * capability flags, and change-notification settings.
  *
+ * @param profile optional profile name; when set, {@code mcp-server-{profile}.yml} is merged
+ * @param enabled whether the MCP server should start
+ * @param mode transport mode (stdio, streamable HTTP, or deprecated SSE)
+ * @param name MCP server implementation name
+ * @param version MCP server implementation version
+ * @param type sync vs async MCP server API style
+ * @param instructions optional server instructions sent to clients
+ * @param requestTimeout default request timeout in seconds
+ * @param capabilities feature flags advertised during initialization
+ * @param changeNotification list-change notification capability flags
+ * @param sse deprecated HTTP SSE transport settings
+ * @param streamable streamable HTTP transport settings
  * @see <a href="https://thought2code.github.io/mcp-annotated-java-sdk/getting-started">MCP
  *     Annotated Java SDK Documentation</a>
  * @author codeboyzhou
@@ -40,7 +52,11 @@ public static Builder builder() {
     return new Builder();
   }
 
-  /** Builder class for {@code ServerConfiguration}. */
+  /**
+   * Mutable builder for {@link ServerConfiguration}.
+   *
+   * <p>Primarily used in tests; YAML files are deserialized directly into the record.
+   */
   public static class Builder {
     /** The profile. */
     private String profile = StringHelper.EMPTY;

src/main/java/com/github/thought2code/mcp/annotated/configuration/ServerSse.java

@@ -3,8 +3,12 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 /**
- * Server-Sent Events (SSE) configuration for an MCP server.
+ * Deprecated HTTP SSE transport settings for an MCP server.
  *
+ * @param messageEndpoint client POST endpoint for outbound messages
+ * @param endpoint SSE stream endpoint path
+ * @param baseUrl optional base URL override for published endpoints
+ * @param port Jetty listen port
  * @see <a href="https://thought2code.github.io/mcp-annotated-java-sdk/getting-started">MCP
  *     Annotated Java SDK Documentation</a>
  * @author codeboyzhou
@@ -29,7 +33,11 @@ public static Builder builder() {
     return new Builder();
   }
 
-  /** Builder class for {@code ServerSse}. */
+  /**
+   * Mutable builder for {@link ServerSse}.
+   *
+   * @deprecated HTTP SSE mode is deprecated; use {@link ServerStreamable} instead.
+   */
   @Deprecated(since = "0.16.0", forRemoval = true)
   public static class Builder {
     /** The message endpoint. */

src/main/java/com/github/thought2code/mcp/annotated/configuration/ServerStreamable.java

@@ -3,12 +3,12 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 /**
- * This record represents the streamable http server configuration for an MCP (Model Context
- * Protocol) server.
- *
- * <p>It contains properties such as the MCP endpoint, disallow delete flag, keep-alive interval,
- * and port.
+ * Streamable HTTP transport settings for an MCP server.
  *
+ * @param mcpEndpoint servlet path segment for the MCP endpoint
+ * @param disallowDelete whether HTTP DELETE on the MCP session is rejected
+ * @param keepAliveInterval optional SSE keep-alive interval in milliseconds
+ * @param port Jetty listen port
  * @see <a href="https://thought2code.github.io/mcp-annotated-java-sdk/getting-started">MCP
  *     Annotated Java SDK Documentation</a>
  * @author codeboyzhou
@@ -28,7 +28,11 @@ public static Builder builder() {
     return new Builder();
   }
 
-  /** Builder class for {@code ServerStreamable}. */
+  /**
+   * Mutable builder for {@link ServerStreamable}.
+   *
+   * <p>Holds HTTP endpoint, session, and keep-alive settings for STREAMABLE transport.
+   */
   public static class Builder {
     /** The MCP endpoint. */
     private String mcpEndpoint = ServerDefaults.STREAMABLE_MCP_ENDPOINT;

src/main/java/com/github/thought2code/mcp/annotated/enums/JavaTypeToJsonSchemaMapper.java

@@ -1,7 +1,10 @@
 package com.github.thought2code.mcp.annotated.enums;
 
 /**
- * This enum is used to map Java types to JSON schema data types.
+ * Maps common Java types to JSON Schema primitive type strings.
+ *
+ * <p>Used when reflecting tool parameter and output schemas. Unknown types default to {@code
+ * string} via {@link #getJsonSchemaType(Class)}.
  *
  * @author codeboyzhou
  */

src/main/java/com/github/thought2code/mcp/annotated/enums/McpServerError.java

@@ -70,6 +70,11 @@ public String withDetail(String detail) {
     return String.format("[%s] %s Detail: %s", getCode(), getMessage(), detail);
   }
 
+  /**
+   * Returns {@code [code] message} for logging and exception text.
+   *
+   * @return formatted code and message without a detail suffix
+   */
   @Override
   public String toString() {
     return String.format("[%s] %s", getCode(), getMessage());

src/main/java/com/github/thought2code/mcp/annotated/enums/ServerMode.java

@@ -1,9 +1,11 @@
 package com.github.thought2code.mcp.annotated.enums;
 
 /**
- * This enum represents the mode of MCP (Model Context Protocol) server.
+ * MCP transport mode selected in server configuration.
  *
- * <p>It can be either {@link #STDIO}, {@link #SSE}, or {@link #STREAMABLE}.
+ * <p>Determines which {@link com.github.thought2code.mcp.annotated.server.AnnotatedMcpServer}
+ * implementation {@link com.github.thought2code.mcp.annotated.McpApplication} constructs at
+ * startup.
  *
  * @author codeboyzhou
  */

src/main/java/com/github/thought2code/mcp/annotated/exception/McpServerConfigurationException.java

@@ -1,8 +1,10 @@
 package com.github.thought2code.mcp.annotated.exception;
 
 /**
- * This exception is thrown to indicate a configuration error in the MCP (Model Context Protocol)
- * server.
+ * Unchecked exception for invalid or unloadable MCP server configuration.
+ *
+ * <p>Thrown by {@link com.github.thought2code.mcp.annotated.configuration.ConfigurationLoader} and
+ * configuration validation helpers when YAML cannot be read or required settings are missing.
  *
  * @author codeboyzhou
  */