Merge pull request #12 from Youssef-Erradi/refactoring

Refactoring

Author: jeandelavarene

…/oracle-db-toolbox-mcp-server/Dockerfile src/oracle-db-mcp-toolkit/Dockerfilesrc/oracle-db-toolbox-mcp-server/Dockerfile renamed to src/oracle-db-mcp-toolkit/Dockerfile src/oracle-db-toolbox-mcp-server/Dockerfile renamed to src/oracle-db-mcp-toolkit/Dockerfile

@@ -1,8 +1,8 @@
-# Oracle DB Toolbox MCP Server
+# Oracle Database MCP Toolkit
 
 ## Overview
 
-`oracle-db-toolbox-mcp-server` is a Model Context Protocol (MCP) server that lets you: 
+Oracle Database MCP Toolkit is a Model Context Protocol (MCP) server that lets you: 
   * Use 8 built-in tools to analyze Oracle JDBC thin client logs and RDBMS/SQLNet trace files.
   * Optionally use **database-powered tools**, including **vector similarity search** and **SQL execution plan analysis**, when JDBC configuration is provided.
   * Define your own custom tools via a simple YAML configuration file.
@@ -71,6 +71,56 @@ These tools operate on RDBMS/SQLNet trace files:
     * `llmPrompt`: A structured prompt for an LLM to explain + tune the plan.
 
 ---
+
+## Custom Tool Framework — Extending the MCP Server
+The MCP server can load both database connection definitions and custom tool definitions from a YAML configuration file.
+This provides a flexible and declarative way to extend the server without modifying or rebuilding the codebase.
+
+A YAML file may define:
+
+  * One or more **sources:** — named database configurations (URL, user, password, etc.)
+
+  * One or more **tools** — each with parameters, SQL statements, and optional metadata
+
+### Source Resolution Logic
+
+When executing a tool, the MCP server determines which source to use based on the following rules:
+
+1. If the tool specifies a source, that source is used.
+
+2. If the tool does not specify a source, the server looks for a default source:
+
+    * First, it checks whether a source was provided via system properties (db.url, db.user, db.password) (Higher priority).
+
+    * If no system property source is available, it falls back to the first source defined in the YAML file, if present.
+
+3. If no source can be resolved and the tool requires one (e.g., SQL-based tools), the server reports a configuration error.
+
+This design ensures that tools always have a predictable source while giving you flexibility to choose how connections are provided—either inline in YAML or externally via system properties and environment variables.
+
+**Example `config.yaml`:**
+```yaml
+sources:
+  prod-db:
+    url: jdbc:oracle:thin:@prod-host:1521/ORCLPDB1
+    user: ADMIN
+    password: ${password}
+
+tools:
+  hotels-by-name:
+    source: prod-db
+    parameters:
+      - name: name
+        type: string
+        description: Hotel name to search for.
+        required: false
+    statement: SELECT * FROM hotels WHERE name LIKE '%' || :name || '%'
+```
+To enable YAML configuration, launch the server with:
+```bash
+java -DconfigFile=/path/to/config.yaml -jar <mcp-server>.jar
+```
+
 ## Prerequisites
 
 - **Java 17+** (JDK)
@@ -85,11 +135,11 @@ These tools operate on RDBMS/SQLNet trace files:
 mvn clean install
 ```
 
-The created jar can be found in `target/oracle-db-toolbox-mcp-server-1.0.0.jar`.
+The created jar can be found in `target/oracle-db-mcp-toolkit-1.0.0.jar`.
 
 ### Transport modes (stdio vs HTTP)
 
-`oracle-db-toolbox-mcp-server` supports two transport modes:
+`oracle-db-mcp-toolkit` supports two transport modes:
 
 - **Stdio (default)** – the MCP client spawns the JVM process and talks over stdin/stdout
 - **HTTP (streamable)** – the MCP server runs as an HTTP service, and clients connect via a URL
@@ -101,7 +151,7 @@ This is the mode used by tools like Claude Desktop, where the client directly la
 ```jsonc
 {
   "mcpServers": {
-    "oracle-db-toolbox-mcp-server": {
+    "oracle-db-mcp-toolkit": {
       "command": "java",
       "args": [
         "-Ddb.url=jdbc:oracle:thin:@your-host:1521/your-service",
@@ -110,7 +160,7 @@ This is the mode used by tools like Claude Desktop, where the client directly la
         "-Dtools=get-jdbc-stats,get-jdbc-queries",
         "-Dojdbc.ext.dir=/path/to/extra-jars",
         "-jar",
-        "<path-to-jar>/oracle-db-toolbox-mcp-server-1.0.0.jar"
+        "<path-to-jar>/oracle-db-mcp-toolkit-1.0.0.jar"
       ]
     }
   }
@@ -132,25 +182,25 @@ java \
   -Ddb.user=your_user \
   -Ddb.password=your_password \
   -Dtools=get-jdbc-stats,get-jdbc-queries \
-  -jar <path-to-jar>/oracle-db-toolbox-mcp-server-1.0.0.jar
+  -jar <path-to-jar>/oracle-db-mcp-toolkit-1.0.0.jar
 ```
 This exposes the MCP endpoint at: `http://localhost:45450/mcp`.
 
-### Note
-You can enable HTTPS (SSL/TLS) by specifying the path to your certificate keystore and its password using the -DcertificatePath and -DcertificatePassword options.
-Only PKCS12 (.p12 or .pfx) keystore format is supported.
-You can also change the HTTPS port with the -DhttpsPort option (default is 45451).
+#### Enabling HTTPS (SSL/TLS)
+To enable HTTPS (SSL/TLS), specify your certificate keystore path and password using the `-DcertificatePath` and `-DcertificatePassword` options.  
+Only PKCS12 (`.p12` or `.pfx`) keystore files are supported.
+You can set the HTTPS port with the `-Dhttps.port` option.
 ##### Example 
 ```shell
--DcertificatePath=/path/to/your-certificate.p12 -DcertificatePassword=yourPassword -DhttpsPort=443
+-DcertificatePath=/path/to/your-certificate.p12 -DcertificatePassword=yourPassword -Dhttps.port=443
 ```
 ### Using HTTP from Cline
 Cline supports streamable HTTP directly. Example:
 
 ```json
 {
   "mcpServers": {
-    "oracle-db-toolbox-mcp-server": {
+    "oracle-db-mcp-toolkit": {
       "type": "streamableHttp",
       "url": "http://localhost:45450/mcp"
     }
@@ -166,7 +216,7 @@ you can use the `mcp-remote` workaround:
 ```json
 {
   "mcpServers": {
-    "oracle-db-toolbox-mcp-server": {
+    "oracle-db-mcp-toolkit": {
       "command": "npx",
       "args": [
         "-y",
@@ -217,7 +267,7 @@ java \
     -DclientId=oracle-db-toolbox \
     -DclientSecret=Xj9mPqR2vL5kN8tY3hB7wF4uD6cA1eZ0 \
     -DallowedHosts=http://localhost:6274 \
-    -jar <path-to-jar>/oracle-db-toolbox-mcp-server-1.0.0.jar
+    -jar <path-to-jar>/oracle-db-mcp-toolkit-1.0.0.jar
 ```
 
 In the above example, we configured OAuth2 with a local KeyCloak server with a realm named `mcp`, and we only allowed a local [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)
@@ -234,7 +284,7 @@ java \
     -Dtransport=http \
     -Dhttp.port=45450 \
     -DenableAuthentication=true \
-    -jar <path-to-jar>/oracle-db-toolbox-mcp-server-1.0.0.jar
+    -jar <path-to-jar>/oracle-db-mcp-toolkit-1.0.0.jar
 ```
 After starting the server, a UUID token will be generated and logged at <code>INFO</code> level:
 
@@ -246,7 +296,7 @@ WARNING: OAuth2 is not configured
 Nov 25, 2025 3:30:46 PM com.oracle.database.jdbc.oauth.TokenGenerator <init>
 INFO: Authorization token generated (for testing and development use only): 0dd11948-37a3-470f-911e-4cd8b3d6f69c
 Nov 25, 2025 3:30:46 PM com.oracle.database.jdbc.OracleDBToolboxMCPServer startHttpServer
-INFO: [oracle-db-toolbox-mcp-server] HTTP transport started on http://localhost:45450 (endpoint: http://localhost:45450/mcp)
+INFO: [oracle-db-mcp-toolkit] HTTP transport started on http://localhost:45450 (endpoint: http://localhost:45450/mcp)
 ```
 
 If `ORACLE_DB_TOOLBOX_AUTH_TOKEN` environment variable is set:
@@ -268,35 +318,6 @@ INFO: Authorization token generated (for testing and development use only): Secr
 
 Ultimately, the token must be included in the http request header (e.g. `Authorization: Bearer 0dd11948-37a3-470f-911e-4cd8b3d6f69c` or `Authorization: Bearer Secret_DeV_T0ken`).
 
-## YAML Configuration Support
-
-The MCP server supports loading database connection and tool definitions from a YAML configuration file.
-For sources, if a tool has a specific source it will use it. Otherwise, it will look for the default source which is either the source we got from system properties, otherwise, the first source defined in the file (if any).
-This file can contain environment variables as well.
-
-**Example `config.yaml`:**
-```yaml
-sources:
-  prod-db:
-    url: jdbc:oracle:thin:@prod-host:1521/ORCLPDB1
-    user: ADMIN
-    password: ${password}
-
-tools:
-  hotels-by-name:
-    source: prod-db
-    parameters:
-      - name: name
-        type: string
-        description: Hotel name to search for.
-        required: false
-    statement: SELECT * FROM hotels WHERE name LIKE '%' || :name || '%'
-```
-To enable YAML configuration, launch the server with:
-```bash
-java -DconfigFile=/path/to/config.yaml -jar <mcp-server>.jar
-```
-
 ### Supported System Properties
 <table>
   <thead>
@@ -362,6 +383,29 @@ java -DconfigFile=/path/to/config.yaml -jar <mcp-server>.jar
       </td>
       <td><code>45450</code></td>
     </tr>
+    <tr>
+      <td><code>https.port</code></td>
+      <td>No</td>
+      <td>
+        TCP port used for SSL connection.
+      </td>
+      <td><code>45451</code></td>
+    </tr>
+    <tr>
+      <td><code>certificatePath</code></td>
+      <td>No</td>
+      <td>
+        Path to SSL certificate keystore (Support PKCS12)
+      </td>
+      <td><code>/path/to/your/certificate</code></td>
+    </tr>
+    <tr>
+      <td><code>certificatePassword</code></td>
+      <td>No</td>
+      <td>
+        Password of SSL certificate keystore
+      </td>
+    </tr>
     <tr>
       <td><code>configFile</code></td>
       <td>No</td>
@@ -431,10 +475,10 @@ A `Dockerfile` is included at the root of the project so you can build and run t
 From the project root (where the Dockerfile lives):
 
 ```bash
-podman build -t oracle-db-toolbox-mcp-server:1.0.0 .
+podman build -t oracle-db-mcp-toolkit:1.0.0 .
 ```
 ### Run the container (HTTP mode example)
-This example runs the MCP server over HTTP inside the container and exposes it on port 45450 on your host.
+This example runs the MCP server over HTTP and HTTPS inside the container and exposes it on port 45450 and 45451 on your host.
 
 ```bash
 podman run --rm \
@@ -451,7 +495,7 @@ podman run --rm \
     -Ddb.url=jdbc:oracle:thin:@your-host:1521/your-service \
     -Ddb.user=your_user \
     -Ddb.password=your_password" \
-  oracle-db-toolbox-mcp-server:1.0.0
+  oracle-db-mcp-toolkit:1.0.0
 ```
 This exposes the MCP endpoint at: http://[your-ip-address]:45450/mcp or https://[your-ip-address]:45451/mcp
 
@@ -475,7 +519,7 @@ podman run --rm \
     -Ddb.user=your_user \
     -Ddb.password=your_password \
     -Dojdbc.ext.dir=/ext" \
-  oracle-db-toolbox-mcp-server:1.0.0
+  oracle-db-mcp-toolkit:1.0.0
 ```
 
 ### Using Docker/Podman with stdio
@@ -489,7 +533,7 @@ In this configuration, Claude Desktop runs `podman run --rm -i ... and connects
 ```json
 {
   "mcpServers": {
-    "oracle-db-toolbox-mcp-server": {
+    "oracle-db-mcp-toolkit": {
       "command": "podman",
       "args": [
         "run",
@@ -498,7 +542,7 @@ In this configuration, Claude Desktop runs `podman run --rm -i ... and connects
         "-v", "/absolute/path/to/ext:/ext:ro",
         "-e",
         "JAVA_TOOL_OPTIONS=-Dtools=get-jdbc-stats,get-jdbc-queries -Ddb.url=jdbc:oracle:thin:@your-host:1521/your-service -Ddb.user=your_user -Ddb.password=your_password -Dojdbc.ext.dir=/ext -DconfigFile=/config/config.yaml",
-        "oracle-db-toolbox-mcp-server:1.0.0"
+        "oracle-db-mcp-toolkit:1.0.0"
       ]
     }
   }

…c/oracle-db-toolbox-mcp-server/README.md src/oracle-db-mcp-toolkit/README.mdsrc/oracle-db-toolbox-mcp-server/README.md renamed to src/oracle-db-mcp-toolkit/README.md src/oracle-db-toolbox-mcp-server/README.md renamed to src/oracle-db-mcp-toolkit/README.md

@@ -4,14 +4,14 @@
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
 
-    <groupId>com.oracle.database.jdbc</groupId>
-    <artifactId>oracle-db-toolbox-mcp-server</artifactId>
+    <groupId>com.oracle.database.mcptoolkit</groupId>
+    <artifactId>oracle-db-mcp-toolkit</artifactId>
     <version>1.0.0</version>
     <packaging>jar</packaging>
     <name>Oracle JDBC Log Analyzer MCP Server</name>
-    <description>The Oracle JDBC Log Analyzer MCP Server provides tools for analyzing
-        Oracle JDBC thin client logs and RDBMS/SQLNet trace files.</description>
-    <url>https://github.com/Youssef-Erradi/mcp/tree/main/src/ojdbc-log-analyzer-mcp-server</url>
+    <description>The Oracle Database MCP Toolkit is a Model Context Protocol (MCP) server that enables users to analyze Oracle JDBC thin client logs and RDBMS/SQLNet trace files using built-in tools.
+        It also offers database-powered tools, such as vector similarity search and SQL execution plan analysis. Additionally, users can define custom tools through a YAML configuration file.</description>
+    <url>https://github.com/oracle/mcp/tree/main/src/oracle-db-mcp-toolkit</url>
 
     <licenses>
         <license>
@@ -103,7 +103,7 @@
                             <createDependencyReducedPom>false</createDependencyReducedPom>
                             <transformers>
                                 <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
-                                    <mainClass>com.oracle.database.jdbc.OracleDBToolboxMCPServer</mainClass>
+                                    <mainClass>com.oracle.database.mcptoolkit.OracleDatabaseMCPToolkit</mainClass>
                                 </transformer>
                             </transformers>
                         </configuration>

src/oracle-db-toolbox-mcp-server/pom.xml src/oracle-db-mcp-toolkit/pom.xmlsrc/oracle-db-toolbox-mcp-server/pom.xml renamed to src/oracle-db-mcp-toolkit/pom.xml

@@ -0,0 +1,45 @@
+/*
+ ** Oracle Database MCP Toolkit version 1.0.0
+ **
+ ** Copyright (c) 2025 Oracle and/or its affiliates.
+ ** Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+ */
+
+package com.oracle.database.mcptoolkit;
+
+import java.util.regex.*;
+
+/**
+ * The EnvSubstitutor class provides a method for substituting environment variables in a given string.
+ * It replaces placeholders in the format ${VARIABLE_NAME} with the corresponding environment variable values.
+ */
+public class EnvSubstitutor {
+  /**
+   * Pattern used to match placeholders in the input string.
+   * The pattern matches strings in the format ${VARIABLE_NAME}.
+   */
+  private static final Pattern PLACEHOLDER = Pattern.compile("\\$\\{([^}]+)}");
+
+  /**
+   * Substitutes environment variables in the given input string.
+   *
+   * @param input the input string containing placeholders for environment variables
+   * @return the input string with environment variables substituted
+   * @throws IllegalStateException if an environment variable is not set
+   */
+  public static String substituteEnvVars(String input) {
+    if (input == null) return null;
+    Matcher m = PLACEHOLDER.matcher(input);
+    StringBuffer sb = new StringBuffer();
+    while (m.find()) {
+      String var = m.group(1);
+      String value = System.getenv(var);
+      if (value == null) {
+        throw new IllegalStateException("Missing environment variable for: " + var);
+      }
+      m.appendReplacement(sb, Matcher.quoteReplacement(value));
+    }
+    m.appendTail(sb);
+    return sb.toString();
+  }
+}

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

@@ -1,5 +1,19 @@
-package com.oracle.database.jdbc;
+/*
+ ** Oracle Database MCP Toolkit version 1.0.0
+ **
+ ** Copyright (c) 2025 Oracle and/or its affiliates.
+ ** Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+ */
 
+package com.oracle.database.mcptoolkit;
+
+/**
+ * Provides a set of constants loaded from system properties and environment variables.
+ * These constants are used to configure various aspects of the application, including
+ * network settings, tool configurations, OAuth settings, and more.
+ *
+ * <p>This class is not intended to be instantiated and provides only static constants.
+ */
 public final class LoadedConstants {
   private LoadedConstants() {} // Prevent instantiation