Add Oracle Database MCP Toolkit

.gitignore

@@ -26,3 +26,6 @@ venv.bak/
 
 .coverage*
 htmlcov/
+
+# Maven
+**/target/

src/oracle-db-mcp-toolkit/DEMO.md

@@ -0,0 +1,131 @@
+# Oracle Database MCP Toolkit Demo
+
+## 1.Overview
+
+To test the capabilities of the Oracle Database MCP Toolkit, a demo instance of the MCP server is made available via
+<https://mcptoolkit.orcl.dev:45453/mcp> with the following tools activated:
+
+JDBC log analysis tools:
+
+- **`get-jdbc-stats`**: Extracts performance statistics including error counts, sent/received packets and byte counts.
+- **`get-jdbc-queries`**: Retrieves all executed SQL queries with timestamps and execution times.
+- **`get-jdbc-errors`**: Extracts all errors reported by both server and client.
+- **`jdbc-log-comparison`**: Compares two log files for performance metrics, errors, and network information.
+
+RDBMS/SQLNet trace analysis Tools:
+
+- **`get-rdbms-errors`**: Extracts errors from RDBMS/SQLNet trace files.
+- **`get-rdbms-packet-dumps`**: Extracts packet dumps for a specific connection ID.
+
+Custom tools (created using YAML configuration file):
+
+- **`hotels-by-name`**: Returns the details of a hotel given its name. The details include the capacity, rating and address.
+  This tool is created using the following YAML configuration file:
+
+```yaml
+dataSources:
+  dev-db:
+    url: ${db_url}
+    user: ${user}
+    password: ${password}
+
+tools:
+  hotels-by-name:
+    dataSource: dev-db
+    description: Returns the details of a hotel given its name. The details include the capacity, rating and address.
+    parameters:
+      - name: name
+        type: string
+        description: Hotel name to search for.
+    statement: SELECT * FROM hotels WHERE name LIKE '%' || :name || '%'
+```
+
+Where `${db_url}`, `${user}` and `${password}`are environment variables.
+
+## 2. Requirements
+
+An MCP Client that support Streamable HTTP transport mode is needed, such as MCP Inspector, Cline or Claude Desktop.
+
+**Note**: If you're using Claude Desktop, you also need [mcp-remote](https://www.npmjs.com/package/mcp-remote).
+
+## 3. Setup
+
+The deployed instance uses `streamableHttp` transport protocol and a runtime generated `Authorization` token.
+
+Use the following token `3e297077-f01e-4045-a9d0-2a71e97e6dfa`.
+
+### MCP Inspector
+
+To use MCP Inspector as an MCP client, specify `streamableHttp`as transport type,  `https://mcptoolkit.orcl.dev:45453/mcp` as the URL, _Via Proxy_ as Connection Type,
+for Authentication, add a `Authorization` custom header with `Bearer 3e297077-f01e-4045-a9d0-2a71e97e6dfa` as value.
+the final configuration should look as shown below:
+
+<img src="https://objectstorage.eu-amsterdam-1.oraclecloud.com/n/axumz0amlzwj/b/oracle-db-toolkit-mcp-demo/o/mcp-Inspector-1.png" height="500px" width="auto" alt="MCP Inspector config screenshot">
+
+After checking the configuration, click the *Connect* button, and the available tools will be shown in the main section:
+
+<img src="https://objectstorage.eu-amsterdam-1.oraclecloud.com/n/axumz0amlzwj/b/oracle-db-toolkit-mcp-demo/o/mcp-Inspector-2.png" height="500px" width="auto" alt="MCP Inspector tools screenshot">
+
+_Note :_ The filePath should be provided as a URL.
+
+### Cline
+
+Add or merge this configuration into `cline_mcp_settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "Oracle Database MCP Toolkit (Demo)": {
+      "autoApprove": [],
+      "disabled": false,
+      "timeout": 60,
+      "type": "streamableHttp",
+      "url": "https://mcptoolkit.orcl.dev:45453/mcp",
+      "headers": {
+        "Authorization": "Bearer 3e297077-f01e-4045-a9d0-2a71e97e6dfa"
+      }
+    }
+  }
+}
+```
+
+After saving the configuration file, the available tools will be shown in the *Configure* Tab of *MCP Servers* settings:
+
+<img src="https://objectstorage.eu-amsterdam-1.oraclecloud.com/n/axumz0amlzwj/b/oracle-db-toolkit-mcp-demo/o/cline-1.png" height="500px" width="auto" alt="Cline tools screenshot">
+
+Here's an example of a prompt that trigger the `get-jdbc-queries` tool:
+
+<img src="https://objectstorage.eu-amsterdam-1.oraclecloud.com/n/axumz0amlzwj/b/oracle-db-toolkit-mcp-demo/o/cline-2.png" height="500px" width="auto" alt="Cline prompt example screenshot">
+
+### Claude Desktop
+
+In order to connect the MCP server and also to provide the `Authorization` token to Claude Desktop, The [mcp-remote](https://www.npmjs.com/package/mcp-remote) is used to properly configure.
+Below is an example of `claude_desktop_config.json` file:
+
+```json
+{
+  "mcpServers": {
+    "Oracle Database MCP Toolkit (Demo)": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "https://mcptoolkit.orcl.dev:45453/mcp",
+        "--header",
+        "Authorization:${DEMO_TOKEN}"
+      ],
+      "env": {
+        "DEMO_TOKEN": "Bearer 3e297077-f01e-4045-a9d0-2a71e97e6dfa"
+      }
+    }
+  }
+}
+```
+
+Upon saving the configuration file an opening Claude Desktop, you'll be to see the tools in the *Connectors* section:
+
+<img src="https://objectstorage.eu-amsterdam-1.oraclecloud.com/n/axumz0amlzwj/b/oracle-db-toolkit-mcp-demo/o/claude-1.png" height="500px" width="auto" alt="Claude Desktop tools screenshot">
+
+Here's the result of the same prompt used to know what queries were executed :
+
+<img src="https://objectstorage.eu-amsterdam-1.oraclecloud.com/n/axumz0amlzwj/b/oracle-db-toolkit-mcp-demo/o/claude-2.png" height="500px" width="auto" alt="Claude Desktop prompt example screenshot">

src/oracle-db-mcp-toolkit/Dockerfile

@@ -0,0 +1,35 @@
+# ---------- 1) Build stage ----------
+FROM container-registry.oracle.com/java/openjdk:17 AS builder
+
+ARG MAVEN_VERSION=3.9.11
+ARG MAVEN_BASE_URL=https://dlcdn.apache.org/maven/maven-3
+
+RUN curl -fsSL \
+      ${MAVEN_BASE_URL}/${MAVEN_VERSION}/binaries/apache-maven-${MAVEN_VERSION}-bin.tar.gz \
+      -o /tmp/maven.tar.gz \
+  && tar -xzf /tmp/maven.tar.gz -C /opt \
+  && ln -s /opt/apache-maven-${MAVEN_VERSION} /opt/maven \
+  && rm /tmp/maven.tar.gz
+
+ENV MAVEN_HOME=/opt/maven
+ENV PATH="${MAVEN_HOME}/bin:${PATH}"
+
+WORKDIR /src
+
+COPY . .
+
+RUN mvn -B -q -DskipTests clean package
+
+# ---------- 2) Runtime stage ----------
+FROM container-registry.oracle.com/java/openjdk:17
+
+RUN useradd -r -u 10001 appuser && \
+    mkdir -p /app /ext && chown -R appuser:appuser /app /ext
+
+WORKDIR /app
+USER appuser
+
+COPY --from=builder /src/target/oracle-db-mcp-toolkit-*.jar \
+     /app/oracle-db-mcp-toolkit.jar
+
+ENTRYPOINT ["java", "-jar", "/app/oracle-db-mcp-toolkit.jar"]

src/oracle-db-mcp-toolkit/LICENSE.txt

@@ -0,0 +1,35 @@
+Copyright (c) 2025 Oracle and/or its affiliates.
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.