Skip to content

Commit bdcf6a2

Browse files
krisricekrisrice
authored
Merge pull request #9 from gvenzl/main
Introducing Oracle DB Doc MCP server
2 parents c44d4a3 + bfedbb1 commit bdcf6a2

File tree

10 files changed

+901
-3
lines changed

10 files changed

+901
-3
lines changed

‎.github/workflows/build-doc-mcp.yml‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: 🛠️ Build Docker image for Oracle Database Documentation MCP Server
2+
on:
3+
push:
4+
paths:
5+
- "src/oracle-db-doc-mcp-server/**"
6+
pull_request:
7+
paths:
8+
- "src/oracle-db-doc-mcp-server/**"
9+
10+
jobs:
11+
build-image:
12+
strategy:
13+
matrix:
14+
runner: ["ubuntu-24.04", "ubuntu-24.04-arm"]
15+
16+
permissions:
17+
packages: write
18+
19+
name: 🛠️ Build image
20+
runs-on: ${{ matrix.runner }}
21+
22+
steps:
23+
- name: 📂 Checkout repo
24+
uses: actions/checkout@v4
25+
26+
- name: 🔄 Generate environment variables
27+
id: os_arch
28+
run: |
29+
if [ "$(uname -m)" == "aarch64" ]; then
30+
echo "OS_ARCH=arm64" >> "$GITHUB_OUTPUT"
31+
else
32+
echo "OS_ARCH=amd64" >> "$GITHUB_OUTPUT"
33+
fi;
34+
35+
- name: Build image
36+
run: |
37+
cd src/oracle-db-doc-mcp-server/
38+
buildah bud -f Dockerfile -t oracle-db-doc:latest-${{ steps.os_arch.outputs.OS_ARCH }} .
39+
40+
- name: 🔓 Login to GHCR registry
41+
uses: redhat-actions/podman-login@v1
42+
with:
43+
username: ${{ github.actor }}
44+
password: ${{ secrets.GITHUB_TOKEN }}
45+
registry: ghcr.io
46+
47+
- name: 🫸 Push image to Container Registry
48+
uses: redhat-actions/push-to-registry@v2
49+
with:
50+
registry: ghcr.io/gvenzl/mcp
51+
image: oracle-db-doc
52+
tags: latest-${{ steps.os_arch.outputs.OS_ARCH }}
53+
54+
upload-multi-arch:
55+
name: 🫸 Push multi-arch manifest
56+
runs-on: "ubuntu-24.04"
57+
needs: build-image
58+
59+
permissions:
60+
packages: write
61+
62+
steps:
63+
- name: 🔓 Login to GHCR registry
64+
uses: redhat-actions/podman-login@v1
65+
with:
66+
username: ${{ github.actor }}
67+
password: ${{ secrets.GITHUB_TOKEN }}
68+
registry: ghcr.io
69+
70+
- name: 🫸 Push multi-arch manifest
71+
run: |
72+
podman manifest create ghcr.io/gvenzl/mcp/oracle-db-doc:latest
73+
podman manifest add ghcr.io/gvenzl/mcp/oracle-db-doc:latest ghcr.io/gvenzl/mcp/oracle-db-doc:latest-amd64
74+
podman manifest add ghcr.io/gvenzl/mcp/oracle-db-doc:latest ghcr.io/gvenzl/mcp/oracle-db-doc:latest-arm64
75+
podman push ghcr.io/gvenzl/mcp/oracle-db-doc:latest

‎.github/workflows/build.yml‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ jobs:
2020
- name: Set up Python
2121
uses: actions/setup-python@v5
2222
with:
23-
python-version: '3.13'
23+
python-version: "3.13"
2424

2525
- name: Install requirements
2626
run: pip install -r requirements-dev.txt
@@ -53,7 +53,6 @@ jobs:
5353
working-directory: src/${{ matrix.directory }}
5454
run: uv pip install .
5555

56-
5756
get-directories:
5857
runs-on: ubuntu-latest
5958
outputs:
@@ -65,5 +64,5 @@ jobs:
6564
- name: Get directories
6665
id: get-directories
6766
run: |
68-
directories=$(ls src | grep -v dbtools-mcp-server | grep -v mysql-mcp-server | grep -v oci-pricing-mcp-server | jq -R -s -c 'split("\n")[:-1]')
67+
directories=$(ls src | grep -v dbtools-mcp-server | grep -v mysql-mcp-server | grep -v oci-pricing-mcp-server | grep -v oracle-db-doc-mcp-server | jq -R -s -c 'split("\n")[:-1]')
6968
echo "directories=$directories" >> $GITHUB_OUTPUT

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,15 @@ env/
99
env.bak/
1010
venv.bak/
1111

12+
# Python uv
13+
uv.lock
14+
.python-version
15+
16+
# VScode
17+
.vscode
18+
19+
# Mac files
20+
.DS_Store
1221

1322
# test environments
1423
.env

‎src/oracle-db-doc-mcp-server/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
*.log
2+
index*

‎src/oracle-db-doc-mcp-server/Dockerfile‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
#
2+
# Since: August 2025
3+
# Author: Gerald Venzl
4+
# Name: Dockerfile
5+
# Description: Dockerfile to build Docker image
6+
#
7+
# Copyright 2025 Oracle Corporation and/or its affiliates.
8+
#
9+
# Licensed under the Apache License, Version 2.0 (the "License");
10+
# you may not use this file except in compliance with the License.
11+
# You may obtain a copy of the License at
12+
#
13+
# http://www.apache.org/licenses/LICENSE-2.0
14+
#
15+
# Unless required by applicable law or agreed to in writing, software
16+
# distributed under the License is distributed on an "AS IS" BASIS,
17+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18+
# See the License for the specific language governing permissions and
19+
# limitations under the License.
20+
#
21+
FROM alpine
22+
23+
COPY oracle-db-doc-mcp-server.py fastmcp.json requirements.txt ./
24+
25+
RUN apk --update --no-cache add python3 py3-pip curl && \
26+
pip install -r requirements.txt --break-system-packages && \
27+
rm requirements.txt && \
28+
mkdir /input && \
29+
curl -L -o /input/dbdoc.zip https://docs.oracle.com/en/database/oracle/oracle-database/26/zip/oracle-database_26.zip && \
30+
python3 oracle-db-doc-mcp-server.py -log-level DEBUG idx -path /input/dbdoc.zip && \
31+
rm -r /input && \
32+
apk del curl && \
33+
rm -rf /var/cache/apk/* /tmp/*
34+
35+
LABEL org.opencontainers.image.source=https://github.com/oracle/mcp
36+
LABEL org.opencontainers.image.description="Oracle Database Documentation MCP Server"
37+
LABEL org.opencontainers.image.licenses=Apache-2.0
38+
39+
ENTRYPOINT [ "python3", "oracle-db-doc-mcp-server.py", "mcp" ]

‎src/oracle-db-doc-mcp-server/README.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# Oracle Database Documentation MCP Server
2+
3+
A Python-based MCP (Model Context Protocol) server that provides tools for searching the official Oracle Database documentation.
4+
5+
The MCP server leverages an inverted index to serve snippets of the Oracle Database documentation. Because the Oracle Database documentation is large and gets updated from time to time, it is unfeasible to ship a ready to go documentation index with this repository. Doing so will bloat the repository and runs risk of users searching on an outdated documentation.
6+
7+
Instead, users can create their own index and maintain it as often as required. See [Index creation/maintenance](#index-creationmaintenance) for more on that topic.
8+
9+
## Features
10+
11+
- **Search**
12+
- Serach the documentation by keywords and phrases
13+
14+
## Prerequisites
15+
16+
- Python 3.x
17+
- Downloaded [Oracle Database Documentation zip file](https://docs.oracle.com/en/database/oracle/oracle-database/26/zip/oracle-database_26.zip) to build the initial index
18+
19+
## Installation
20+
21+
```console
22+
git clone https://github.com/oracle/mcp.git
23+
24+
cd mcp/src/oracle-db-doc-mcp-server
25+
26+
python3 -m venv .venv
27+
28+
source .venv/bin/activate
29+
30+
python3 -m pip install -r requirements.txt
31+
```
32+
33+
## Usage
34+
35+
```console
36+
usage: oracle-db-doc-mcp-server.py [-h] [-log-level LOG_LEVEL] {idx,mcp} ...
37+
38+
Oracle Database Documentation MCP Server.
39+
40+
options:
41+
-h, --help show this help message and exit
42+
-log-level LOG_LEVEL Set the log level (DEBUG, INFO, WARNING, ERROR (default), CRITICAL).
43+
44+
subcommands:
45+
{idx,mcp}
46+
idx create/maintain the index
47+
mcp run the MCP server
48+
```
49+
50+
The MCP server has two subcommands:
51+
52+
1. `idx`: Creates or maintains the documentation index.
53+
2. `mcp`: Runs the MCP server.
54+
55+
Building the index will take some time and some MCP clients will time out while waiting for the index to be built. Hence the two subcommands cannot be intermixed. Users will first have to create the documentation index via the `idx` subcommand and once completed, run the server with the `mcp` subcommand.
56+
57+
### Index creation/maintenance
58+
59+
```console
60+
usage: oracle-db-doc-mcp-server.py idx [-h] -path PATH [-preprocess PREPROCESS]
61+
62+
options:
63+
-h, --help show this help message and exit
64+
-path PATH path to the documentation input zip file or extracted directory
65+
-preprocess PREPROCESS
66+
preprocessing level of documentation (NONE, BASIC (default), ADVANCED)
67+
```
68+
69+
To create or maintain the index, use the `idx` subcommand and point the `-path` parameter to either the Oracle Database Documentation zip file (the file will be automatically unzipped into a temorary location under `$HOME/.oracle/oracle-db-doc-mcp-server`) or an **already extracted** location of the Oracle Database Documentation.
70+
71+
The server will create a new folder under `$HOME/.oracle/oracle-db-doc-mcp-server` and store the index and the server log file within. Subsequent runs of `mcp` will open that index. The index can be updated by running the `idx` mode again.
72+
73+
The index creation will take several minutes to complete depending on your environment and the level of preprocessing specified via the `-preprocess` parameter.
74+
75+
A checksum of the index is kept so that subsequent executions of the program will only reindex content that has changed.
76+
77+
For example, to create an index on a downloaded Oracle Database documentation zip file under `~/Downloads/oracle-database_26.zip`, run:
78+
79+
```console
80+
python3 oracle-db-doc-mcp-server.py idx -path ~/Downloads/oracle-database_26.zip
81+
```
82+
83+
### Running the MCP Server
84+
85+
```console
86+
usage: oracle-db-doc-mcp-server.py mcp [-h] [-mode {stdio,http}] [-host HOST] [-port PORT]
87+
88+
options:
89+
-h, --help show this help message and exit
90+
-mode {stdio,http} the transport mode for the MCP server (stdio (default) or http)
91+
-host HOST the IP address (default 0.0.0.0) that the MCP server is reachable at
92+
-port PORT the port (default 8000) that the MCP server is reachable at
93+
```
94+
95+
To run the MCP server, use the `mcp` subcommand.
96+
97+
**Note:** The index will have to exist. If it doesn't, the MCP server will exit with an error.
98+
99+
By default, the MCP server runs on `stdio`. Hence, the simplest way to run it, is:
100+
101+
```console
102+
python3 oracle-db-doc-mcp-server.py mcp
103+
```
104+
105+
### VSCode integration
106+
107+
#### Running the MCP server via Docker/Podman
108+
109+
To run the MCP server from inside a Docker container:
110+
111+
1. Add a new file `.vscode/mcp.json` file to your project folder.
112+
2. Add the following content to your `mcp.json` file.
113+
114+
```
115+
{
116+
"servers": {
117+
"oracle-db-doc": {
118+
"type": "stdio",
119+
"command": "docker",
120+
"args": [ "run", "--rm", "-i", "ghcr.io/oracle/mcp/oracle-db-doc" ]
121+
}
122+
}
123+
}
124+
```
125+
126+
#### Running the MCP server directly
127+
128+
To run the MCP server directly from your machine:
129+
130+
1. Follow the [Installation](#installation) instructions first.
131+
2. Create an index as explained in [Index creation/maintenance](#index-creationmaintenance)
132+
3. Add a new file `mcp.json` file to your project folder.
133+
4. Add the following content to your `.vscode/mcp.json` file. Replace the `<>` placeholders with the paths to the MCP server installation.
134+
135+
```
136+
{
137+
"servers": {
138+
"oracle-db-doc": {
139+
"type": "stdio",
140+
"command": "<installation>/.venv/bin/python3",
141+
"args": [ "oracle-db-doc-mcp-server.py", "mcp" ]
142+
}
143+
}
144+
}
145+
```
146+
147+
## Tools
148+
149+
### search_oracle_database_documentation
150+
151+
Searches the documentation for key words and key phrases.
152+
153+
```python
154+
search_oracle_database_documentation(search_query: str, max_results: int) -> list[str]:
155+
```

‎src/oracle-db-doc-mcp-server/fastmcp.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"entrypoint": "oracle-db-doc-mcp-server.py",
3+
"environment": {
4+
"dependencies": [
5+
"beautifulsoup4 >= 4.9.0",
6+
"markdownify >= 1.2.0",
7+
"fastmcp >= 2.11.3",
8+
"pocketsearch >= 0.40.0"
9+
]
10+
}
11+
}

0 commit comments

Comments
 (0)