Merge pull request #28 from Youssef-Erradi/code-clean-up

Remove unused code and add missing JavaDoc

Author: jeandelavarene

src/oracle-db-mcp-java-toolkit/src/main/java/com/oracle/database/mcptoolkit/OracleDatabaseMCPToolkit.java

@@ -59,8 +59,6 @@ public class OracleDatabaseMCPToolkit {
   public static void main(String[] args) {
     installExternalExtensionsFromDir();
 
-    McpSyncServer server;
-
     switch (LoadedConstants.TRANSPORT_KIND) {
       case "http" -> {
         serverInstance = startHttpServer();
@@ -81,15 +79,7 @@ public static void main(String[] args) {
     }
     Utils.addSyncToolSpecifications(serverInstance, config);
 
-//    if (LoadedConstants.CONFIG_FILE != null) {
-//      Thread watcher = new Thread(() -> {
-//        watchConfigFile(LoadedConstants.CONFIG_FILE);
-//      }, "config-file-watcher");
-//      watcher.setDaemon(true);
-//      watcher.start();
-//    }
-
-    Thread pollingThread = new Thread(() -> pollConfigFile(LoadedConstants.CONFIG_FILE), "config-file-poller");
+    Thread pollingThread = new Thread(() -> pollConfigFile(), "config-file-poller");
     pollingThread.setDaemon(true);
     pollingThread.start();
   }
@@ -151,7 +141,7 @@ private static McpSyncServer startHttpServer() {
       if (LoadedConstants.HTTPS_PORT == null || LoadedConstants.KEYSTORE_PATH == null || LoadedConstants.KEYSTORE_PASSWORD == null)
         throw new RuntimeException("SSL setup failed: HTTPS port, Keystore path or password not specified");
 
-      enableHttps(tomcat, LoadedConstants.KEYSTORE_PATH, LoadedConstants.KEYSTORE_PASSWORD);
+      enableHttps(tomcat);
 
       tomcat.start();
 
@@ -166,11 +156,9 @@ private static McpSyncServer startHttpServer() {
    * Configures and enables HTTPS on the provided Tomcat server using the specified keystore.
    *
    * @param tomcat          the Tomcat server instance to configure
-   * @param keystorePath    the file path to the PKCS12 keystore containing the SSL certificate
-   * @param keystorePassword the password for the keystore
    * @throws RuntimeException if the HTTPS connector or SSL configuration fails
    */
-  private static void enableHttps(Tomcat tomcat, String keystorePath, String keystorePassword) {
+  private static void enableHttps(Tomcat tomcat) {
     try {
       // Create HTTPS connector
       Connector https = new Connector("org.apache.coyote.http11.Http11NioProtocol");
@@ -188,8 +176,8 @@ private static void enableHttps(Tomcat tomcat, String keystorePath, String keyst
           SSLHostConfigCertificate.Type.RSA
       );
 
-      cert.setCertificateKeystoreFile(keystorePath);
-      cert.setCertificateKeystorePassword(keystorePassword);
+      cert.setCertificateKeystoreFile(LoadedConstants.KEYSTORE_PATH);
+      cert.setCertificateKeystorePassword(LoadedConstants.KEYSTORE_PASSWORD);
       cert.setCertificateKeystoreType("PKCS12");
 
       // Attach certificate to SSL config
@@ -217,32 +205,6 @@ public static McpSyncServer getServer() {
     return serverInstance;
   }
 
-
-  private static void watchConfigFile(String filePath) {
-    Path configPath = Paths.get(filePath);
-    try (WatchService watcher = FileSystems.getDefault().newWatchService()) {
-      Path dir = configPath.getParent();
-      if (dir == null) dir = Paths.get(".");
-      dir.register(watcher, StandardWatchEventKinds.ENTRY_MODIFY);
-
-      while (true) {
-        WatchKey key = watcher.take();  // block until events
-        for (WatchEvent<?> event : key.pollEvents()) {
-          Path changed = ((WatchEvent<Path>)event).context();
-          LOG.info(()->"[DEBUG] Watch event: " + event.kind() + ", file: " + changed);
-          LOG.info(()->"[DEBUG] Looking for file: " + configPath.getFileName());
-          if (changed.endsWith(configPath.getFileName())) {
-            LOG.info(()->"[DEBUG] Detected relevant config file event: " + event.kind());
-            reloadConfigAndResetTools();
-          }
-        }
-        key.reset();
-      }
-    } catch (Exception e) {
-      System.err.println("[oracle-db-mcp-toolkit] Config file watcher failed: " + e);
-    }
-  }
-
   private static void reloadConfigAndResetTools() {
     try {
       LOG.info(()->"[DEBUG] Reloading config...");
@@ -257,9 +219,9 @@ private static void reloadConfigAndResetTools() {
     }
   }
 
-  // For now, we rely on this instead of the nio watcher logic (for container sake)
-  private static void pollConfigFile(String filePath) {
-    File configFile = new File(filePath);
+  // For now, we rely on this instead of the nio watcher logic (for container’s sake)
+  private static void pollConfigFile() {
+    File configFile = new File(LoadedConstants.CONFIG_FILE);
     long lastModified = configFile.lastModified();
     while (true) {
       long nowModified = configFile.lastModified();

src/oracle-db-mcp-java-toolkit/src/main/java/com/oracle/database/mcptoolkit/config/ConfigRoot.java

@@ -19,8 +19,10 @@ public class ConfigRoot {
   /**
    * Optional named toolsets allowing users to group custom tools and enable them with -Dtools.
    * Example YAML:
+   * <pre>
    * toolsets:
    *   reporting: [top_customers, sales_by_region]
+   * </pre>
    */
   public Map<String, List<String>> toolsets;
 

src/oracle-db-mcp-java-toolkit/src/main/java/com/oracle/database/mcptoolkit/config/ToolConfig.java

@@ -61,6 +61,17 @@ public void substituteEnvVars() {
     }
   }
 
+  /**
+   * Builds a JSON representation of the input schema for this tool configuration.
+   * <p>
+   * The input schema is constructed based on the tool's parameter configurations.
+   * Each parameter is represented as a property in the schema, with its type and description.
+   * Required parameters are listed in the "required" section of the schema.
+   * <p>
+   * The resulting JSON string can be used to validate input data for the tool.
+   *
+   * @return a JSON string representing the input schema for this tool configuration
+   */
   public String buildInputSchemaJson() {
     ObjectNode schema = JsonNodeFactory.instance.objectNode();
     schema.put("type", "object");

src/oracle-db-mcp-java-toolkit/src/main/java/com/oracle/database/mcptoolkit/tools/DatabaseOperatorTools.java

@@ -21,20 +21,24 @@
 import static com.oracle.database.mcptoolkit.Utils.*;
 
 /**
- * Database operator tools:
- * - read-query: execute SELECT queries and return JSON results
- * - write-query: execute DML/DDL statements
- * - create-table: create table.
- * - delete-table: drop table by name
- * - list-tables: list all tables and synonyms in the current schema
- * - describe-table: get column details for a specific table
- * - start-transaction: begin a new JDBC transaction
- * - resume-transaction: verify a transaction ID is active
- * - commit-transaction: commit and close a transaction
- * - rollback-transaction: rollback and close a transaction
- * - db-ping: check database connectivity and latency
- * - db-metrics-range: retrieve Oracle performance metrics from V$SYSSTAT
- * - explain-plan: generate and explain Oracle SQL execution plans (static or dynamic)
+ * Provides a set of database operator tools for various database operations.
+ *
+ * <p>The available tools are:</p>
+ * <ul>
+ *   <li><strong>read-query</strong>: Execute SELECT queries and return JSON results.</li>
+ *   <li><strong>write-query</strong>: Execute DML/DDL statements.</li>
+ *   <li><strong>create-table</strong>: Create table.</li>
+ *   <li><strong>delete-table</strong>: Drop table by name.</li>
+ *   <li><strong>list-tables</strong>: List all tables and synonyms in the current schema.</li>
+ *   <li><strong>describe-table</strong>: Get column details for a specific table.</li>
+ *   <li><strong>start-transaction</strong>: Begin a new JDBC transaction.</li>
+ *   <li><strong>resume-transaction</strong>: Verify a transaction ID is active.</li>
+ *   <li><strong>commit-transaction</strong>: Commit and close a transaction.</li>
+ *   <li><strong>rollback-transaction</strong>: Rollback and close a transaction.</li>
+ *   <li><strong>db-ping</strong>: Check database connectivity and latency.</li>
+ *   <li><strong>db-metrics-range</strong>: Retrieve Oracle performance metrics from V$SYSSTAT.</li>
+ *   <li><strong>explain-plan</strong>: Generate and explain Oracle SQL execution plans (static or dynamic).</li>
+ * </ul>
  */
 public final class DatabaseOperatorTools {
 
@@ -44,7 +48,31 @@ public final class DatabaseOperatorTools {
   private DatabaseOperatorTools() {}
 
   /**
-   * Returns all database operator tool specifications.
+   * Returns a list of database operator tool specifications based on the provided server configuration.
+   * The returned tools are used for various database operations such as executing queries, managing transactions,
+   * and retrieving database metrics.
+   *
+   * <p>The tools returned include:</p>
+   * <ul>
+   *   <li><strong>read-query</strong>: Execute SELECT queries and return JSON results.</li>
+   *   <li><strong>write-query</strong>: Execute DML/DDL statements.</li>
+   *   <li><strong>create-table</strong>: Create table.</li>
+   *   <li><strong>delete-table</strong>: Drop table by name.</li>
+   *   <li><strong>list-tables</strong>: List all tables and synonyms in the current schema.</li>
+   *   <li><strong>describe-table</strong>: Get column details for a specific table.</li>
+   *   <li><strong>start-transaction</strong>: Begin a new JDBC transaction.</li>
+   *   <li><strong>resume-transaction</strong>: Verify a transaction ID is active.</li>
+   *   <li><strong>commit-transaction</strong>: Commit and close a transaction.</li>
+   *   <li><strong>rollback-transaction</strong>: Rollback and close a transaction.</li>
+   *   <li><strong>db-ping</strong>: Check database connectivity and latency.</li>
+   *   <li><strong>db-metrics-range</strong>: Retrieve Oracle performance metrics from V$SYSSTAT.</li>
+   *   <li><strong>explain-plan</strong>: Generate and explain Oracle SQL execution plans (static or dynamic).</li>
+   * </ul>
+   *
+   * <p>A shutdown hook is added to clean up any active transactions when the JVM shuts down.</p>
+   *
+   * @param config the server configuration to use for database connections
+   * @return a list of tool specifications for database operations
    */
   public static List<McpServerFeatures.SyncToolSpecification> getTools(ServerConfig config) {
     List<McpServerFeatures.SyncToolSpecification> tools = new ArrayList<>();

src/oracle-db-mcp-java-toolkit/src/main/java/com/oracle/database/mcptoolkit/tools/McpAdminTools.java

@@ -24,26 +24,52 @@
 import java.util.*;
 
 /**
- * Admin/maintenance tools:
- * - list-tools: list all available tools with descriptions
- * - edit-tools: upsert a YAML-defined tool in the config file and rely on runtime reload
+ * Provides a set of admin/maintenance tools for various operations.
+ *
+ * <p>The available tools are:</p>
+ * <ul>
+ *   <li><strong>list-tools</strong>: List all available tools with descriptions.</li>
+ *   <li><strong>edit-tools</strong>: Upsert a YAML-defined tool in the config file and rely on runtime reload.</li>
+ * </ul>
  */
 public class McpAdminTools {
 
   private McpAdminTools() {}
 
   /**
-   * Returns all MCP admin tool specifications.
+   * Returns a list of all MCP admin tool specifications, including "list-tools" and "edit-tools".
+   * The returned tools are filtered based on the configuration provided.
+   *
+   * @param config the server configuration used to filter the tools
+   * @return a list of MCP admin tool specifications
    */
   public static List<McpServerFeatures.SyncToolSpecification> getTools(ServerConfig config) {
     List<McpServerFeatures.SyncToolSpecification> tools = new ArrayList<>();
 
     tools.add(getListToolsTool(config));
-    tools.add(getEditToolsTool(config));
+    tools.add(getEditToolsTool());
 
     return tools;
   }
 
+  /**
+   * Returns a tool specification for the "list-tools" tool, which lists all available tools
+   * with their descriptions. The tool respects the tools filter configuration.
+   *
+   * <p>The tool returns a list of tools, including:</p>
+   * <ul>
+   *   <li>Built-in log analyzer tools</li>
+   *   <li>RAG tools</li>
+   *   <li>Database operator tools</li>
+   *   <li>Custom YAML tools</li>
+   *   <li>MCP admin tools</li>
+   * </ul>
+   *
+   * <p>The tool's output is filtered based on the {@link ServerConfig#toolsFilter} configuration.</p>
+   *
+   * @param config the server configuration used to filter the tools
+   * @return a tool specification for the "list-tools" tool
+   */
   public static McpServerFeatures.SyncToolSpecification getListToolsTool(ServerConfig config) {
     return McpServerFeatures.SyncToolSpecification.builder()
       .tool(McpSchema.Tool.builder()
@@ -132,7 +158,38 @@ public static McpServerFeatures.SyncToolSpecification getListToolsTool(ServerCon
     .build();
   }
 
-  public static McpServerFeatures.SyncToolSpecification getEditToolsTool(ServerConfig config) {
+  /**
+   * Returns a tool specification for the "edit-tools" tool, which creates or updates
+   * YAML-defined tools in the configuration file. The changes are auto-reloaded.
+   *
+   * <p>The tool accepts the following input parameters:</p>
+   * <ul>
+   *   <li><strong>name</strong>: The name of the tool to create or update (required).</li>
+   *   <li><strong>remove</strong>: A boolean flag indicating whether to remove the tool (optional).</li>
+   *   <li><strong>description</strong>: A description of the tool (optional).</li>
+   *   <li><strong>dataSource</strong>: The data source for the tool (optional).</li>
+   *   <li><strong>statement</strong>: The SQL statement for the tool (optional).</li>
+   *   <li><strong>parameters</strong>: A list of parameter objects for the tool (optional).
+   *     Each parameter object can have the following properties:
+   *     <ul>
+   *       <li><strong>name</strong>: The name of the parameter.</li>
+   *       <li><strong>type</strong>: The data type of the parameter.</li>
+   *       <li><strong>description</strong>: A description of the parameter.</li>
+   *       <li><strong>required</strong>: A boolean indicating whether the parameter is required.</li>
+   *     </ul>
+   *   </li>
+   * </ul>
+   *
+   * <p>The tool returns a result with the following properties:</p>
+   * <ul>
+   *   <li><strong>status</strong>: The status of the operation (e.g., "ok", "noop", "error").</li>
+   *   <li><strong>message</strong>: A human-readable message describing the result.</li>
+   *   <li><strong>configFile</strong>: The path to the configuration file.</li>
+   * </ul>
+   *
+   * @return a tool specification for the "edit-tools" tool
+   */
+  public static McpServerFeatures.SyncToolSpecification getEditToolsTool() {
     return McpServerFeatures.SyncToolSpecification.builder()
       .tool(McpSchema.Tool.builder()
          .name("edit-tools")

src/oracle-db-mcp-java-toolkit/src/main/java/com/oracle/database/mcptoolkit/tools/RagTools.java

@@ -40,23 +40,43 @@ public class RagTools {
   private RagTools() {}
 
   /**
-   * Returns all RAG tool specifications.
+   * Returns a list of all RAG tool specifications based on the provided server configuration.
+   * <p>
+   * The returned list includes tool specifications for RAG applications, such as similarity search
+   * using vector embeddings. The tools are filtered based on the configuration settings.
+   *
+   * @param config the server configuration to use for determining which tools to include
+   * @return a list of tool specifications for RAG tools
    */
   public static List<McpServerFeatures.SyncToolSpecification> getTools(ServerConfig config) {
     List<McpServerFeatures.SyncToolSpecification> tools = new ArrayList<>();
-    tools.add(getSymilaritySearchTool(config));
+    tools.add(getSimilaritySearchTool(config));
     return tools;
   }
 
   /**
-   * Returns a tool specification for the "similarity_search" tool.
+   * Returns a tool specification for the {@code similarity-search} tool.
    * <p>
    * This tool allows users to perform similarity searches using vector embeddings.
+   * The tool's behavior is configured based on the provided server configuration.
+   * <p>
+   * The tool accepts the following input arguments:
+   * <ul>
+   *   <li>{@code question}: the natural-language query text (required, non-blank)</li>
+   *   <li>{@code topK}: the maximum number of rows to return (optional, default=5, clamped to [1, 100])</li>
+   *   <li>{@code table}: the table name containing text + embedding columns (optional, default="profile_oracle")</li>
+   *   <li>{@code dataColumn}: the column holding the text/CLOB to return (optional, default="text")</li>
+   *   <li>{@code embeddingColumn}: the vector column used by the similarity function (optional, default="embedding")</li>
+   *   <li>{@code modelName}: the database vector model used to embed the question (optional, default="doc_model")</li>
+   *   <li>{@code textFetchLimit}: the substring length to return from the text column (optional, default=4000)</li>
+   * </ul>
+   * <p>
+   * The tool returns a list of text snippets ranked by similarity, along with a structured content map containing the results.
    *
-   * @param config server configuration
-   * @return tool specification
+   * @param config the server configuration to use for determining the tool's behavior
+   * @return a tool specification for the {@code similarity-search} tool
    */
-  public static McpServerFeatures.SyncToolSpecification getSymilaritySearchTool(ServerConfig config) {
+  public static McpServerFeatures.SyncToolSpecification getSimilaritySearchTool(ServerConfig config) {
     return McpServerFeatures.SyncToolSpecification.builder()
       .tool(McpSchema.Tool.builder()
          .name("similarity-search")