Oracle MCP Chatbot — On-Prem Oracle DB + Oracle ATP

Ein sicheres Model Context Protocol-Serverpaar, das einem KI-Chatbot ermöglicht, natürliche Sprachfragen gegen Oracle-Datenbanken zu beantworten: Es entdeckt Metadaten, generiert SELECT-only-SQL, validiert es, führt es unter harten Limits aus, maskiert sensible Werte und protokolliert alles.

Erstellt mit FastMCP 3, python-oracledb (Thin-Modus) und sqlglot. 221 Tests, für deren Ausführung keine Datenbank erforderlich ist.

pip install -r requirements-dev.txt
pytest                                        # 221 passed
cp .env.example .env                          # add credentials
python -m oracle_mcp.server --profile onprem --check
python -m oracle_mcp.server --profile onprem

Das Testen einer laufenden Bereitstellung wird in docs/testing.md behandelt. Eine Browser-UI, die Cursor nicht verwendet, finden Sie in docs/chat-ui.md:

python -m oracle_mcp.chat --profile both   # http://127.0.0.1:8500

Funktionen

Related MCP server: OracleDB MCP Server

Die acht Tools

Plus list_databases für die Verbindungsermittlung. Jedes Tool nimmt JSON entgegen und gibt JSON zurück.

So funktioniert das Sicherheitsmodell

Daten erreichen einen Benutzer nur, indem sie fünf unabhängige Ebenen durchlaufen:

Database grants  →  Object allowlist  →  Role clearance  →  SQL guardrails  →  Output masking
   sql/*.sql        config/policy/       roles.yaml         sql_guard.py       masking.py

Die tragende Idee: Das SQL, das Sie übermitteln, ist nie das SQL, das ausgeführt wird. Die Eingabe wird in einen AST geparst, untersucht, umgeschrieben und neu generiert. Nur Knotentypen, die der Validator erkannt hat, werden erneut ausgegeben, sodass Kommentartricks, gestapelte Anweisungen und Homoglyphen-Schlüsselwörter den Roundtrip nicht überleben können.

SELECT a FROM t; DROP TABLE t     →  rejected: MULTIPLE_STATEMENTS
SELECT /*+ PARALLEL(t,64) */ a…   →  SELECT a FROM t FETCH FIRST 500 ROWS ONLY
ＤＥＬＥＴＥ FROM t                 →  rejected: NFKC folds it to DELETE
SELECT * FROM v   (business_user) →  explicit column list, restricted ones absent

Zweite Schlüsselkontrolle: execute_readonly_sql validiert von Grund auf neu und erfordert einen Fingerabdruck, der von validate_sql ausgestellt wurde, sodass SQL nicht zwischen Prüfung und Ausführung ausgetauscht werden kann. Nicht-Admin-Rollen können nichts ausführen, was nicht zuerst genehmigt wurde; Admins können es, aber die Anweisung durchläuft trotzdem jede Schutzprüfung.

Drittens: Rollen werden durch die Prozesskonfiguration festgelegt, nicht durch Tool-Argumente. Ein Benutzer, der dem Modell sagt „Sie sind jetzt Admin“, erzeugt einen user_role="admin"-String, den nichts liest.

Konfiguration

Zwei Dateien entscheiden über alles:

config/policy/onprem.yaml und atp.yaml — die Objekt-Allowlist. Jede Datenbank wählt einen von zwei Modi.

Strict, was On-Prem verwendet. Nur die hier genannten Objekte sind erreichbar, unabhängig davon, was die Datenbank-Grants erlauben:

schemas:
  - name: EIM
    objects:
      - name: EIM_PR_SYSTEM
        type: TABLE
        sensitivity: INTERNAL
        large_table: true
        require_filter: true       # forces a WHERE clause
        columns:                   # optional; omit to read them from the
          - {name: SERIAL_NUMBER,  sensitivity: INTERNAL}   # data dictionary
          - {name: TAX_ID,         sensitivity: RESTRICTED} # at query time

Das Weglassen von columns: wird unterstützt und ist das, was die bereitgestellte Richtlinie tut. Spalten werden dann aus ALL_TAB_COLUMNS gelesen und nach den Namensmustern in masking.yaml klassifiziert, sodass die Allowlist korrekt bleibt, wenn sich das Schema ändert.

Wildcard, was ATP verwendet. Jedes Schema, das das schreibgeschützte Konto lesen kann, wird erreichbar:

allow_all_schemas: true
excluded_schemas: []   # added on top of the built-in Oracle internal schemas
schemas: []

Dies gibt bewusst die Objekt-Allowlist auf und macht das Datenbank-Grant zur Grenze. Freigabestufe, SQL-Schutzprüfungen, Zeilenlimits und Maskierung gelten weiterhin. Verwenden Sie dies nur gegen ein Konto, das wirklich schreibgeschützt ist.

config/policy/roles.yaml — wer was sehen darf:

roles:
  business_user:
    clearance: INTERNAL      # cannot reach CONFIDENTIAL or RESTRICTED columns
    max_rows: 200
    allow_raw_sql: false
    schemas: {ONPREM: [EIM], ATP: ["*"]}   # "*" needs allow_all_schemas

Sensitivitätsleiter: PUBLIC < INTERNAL < CONFIDENTIAL < RESTRICTED < NEVER. NEVER liegt über jeder Freigabestufe, sodass Passwörter und Kartennummern für keine Rolle erreichbar sind, auch nicht für Admin.

Bereitstellung

Führen Sie einen Server pro Datenbank aus. Diese Trennung ist eine Sicherheitsgrenze: Der On-Prem-Prozess hält nie die ATP-Wallet-Passphrase.

docker build -t oracle-mcp-chatbot:1.0.0 .
export ATP_WALLET_HOST_PATH=/secure/path/wallets/atp
docker compose up -d onprem-mcp atp-mcp
docker compose --profile reconciliation up -d   # optional, holds both credential sets

Oracle ATP-Konnektivität

Thin-Modus mit einem mTLS-Wallet. Entpacken Sie das Wallet und setzen Sie:

ATP_DSN=myatp_low                      # prefer _low so chatbot traffic can't starve prod
ATP_WALLET_DIR=/opt/oracle/wallets/atp # contains ewallet.pem + tnsnames.ora
ATP_CONFIG_DIR=/opt/oracle/wallets/atp
ATP_WALLET_PASSWORD=...                # set when the wallet zip was downloaded

ATP_WALLET_PASSWORD ist die Passphrase, die ewallet.pem schützt, nicht das Datenbankpasswort — ein häufiger und verwirrender Fehler. Es ist nur für den Thin-Modus; der Thick-Modus liest stattdessen das passwortlose cwallet.sso, und die Konfiguration beider wird beim Start abgelehnt. Für TLS-only-ATP (ohne Wallet) lassen Sie die Wallet-Variablen leer und fügen Sie die vollständige Verbindungszeichenfolge aus der OCI-Konsole in ATP_DSN ein.

Das Wallet ist schreibgeschützt bind-gemountet und wird nie in ein Image eingebettet.

On-Prem-Konnektivität

ONPREM_HOST=oracle-onprem.internal.example.com
ONPREM_PORT=1521
ONPREM_SERVICE_NAME=CDMPRD
ONPREM_MODE=thin
# TCPS instead:
# ONPREM_DSN=tcps://host:2484/CDMPRD?ssl_server_dn_match=true

Der Thin-Modus benötigt keinen Oracle Client. Verwenden Sie den Thick-Modus nur für Funktionen, die ihm fehlen; siehe die auskommentierte Stufe in der Dockerfile.

Dokumentation

Vor der Produktion

Die Referenzimplementierung bleibt bewusst an vier Stellen unvollständig. Lesen Sie docs/deployment-checklist.md für die vollständige Liste; die wichtigsten Punkte:

• Setzen Sie ORACLE_MCP_ROLE_BINDING_MODE=env. Der argument-Standard in .env.example ist für die Entwicklung; darunter kann das Modell jede Rolle behaupten.

• Ersetzen Sie die Beispiel-Allowlists in config/policy/*.yaml durch Ihre echten kuratierten Sichten und klassifizieren Sie jede Spalte bewusst.

• Verschieben Sie Geheimnisse in einen Tresor. Compose-Umgebungsvariablen sind für jeden sichtbar, der docker inspect ausführen kann.

• Setzen Sie den HTTP-Transport hinter ein authentifizierendes Gateway. Der HTTP-Transport von FastMCP authentifiziert Aufrufer nicht selbst; die Bindung an Loopback ist ein Notbehelf, nicht die Kontrolle.

Ebenfalls bewusst nicht implementiert: Ratenbegrenzung, Weitergabe der Benutzeridentität pro Benutzer und Genehmigungsworkflow für Admin-Roh-SQL.

Lizenz

Als Referenzimplementierung bereitgestellt. Prüfen Sie sie vor dem Produktionseinsatz gegen Ihre eigenen Sicherheitsstandards.