BDDK MCP Server

Türkisch | Englisch | Englischsprachiger Betriebsleitfaden

Der BDDK MCP Server ist ein Offline-First-Model-Context-Protocol-Server zum Suchen, Abrufen und Analysieren türkischer Bankenregulierungsdaten von BDDK und mevzuat.gov.tr. Er kombiniert Katalogsuche, Dokumentabruf, rechtliche Suche auf Abschnittsebene, semantische Suche, Bulletin-Analytik, Dokumentqualitätsprüfungen und Operator-Backfill-Workflows.

[!IMPORTANT] Dieses Repository ist eine technische Beta, keine Rechtsberatung und kein Nachweis der Produktionsreife. Beginnen Sie mit dem aktuellen Status und dem Dokumentationsindex, prüfen Sie die Einsatzgrenzen und nutzen Sie die Sicherheitsrichtlinie für vertrauliche Schwachstellenmeldungen. Beiträge folgen CONTRIBUTING.md.

Türkisch

Wozu dient das?

Dieses Projekt zielt darauf ab, einen sicheren und nachvollziehbaren MCP-Server für BDDK-Entscheidungen und -Regulierungen zu erstellen. Das Ziel ist, dass sich das Modell auf BDDK-Quellen im lokalen Datenspeicher stützt, anstatt Antworten aus seinem eigenen Wissen zu generieren. Informationen zu den aktuellen Produktionssicherheitsgrenzen finden Sie im Deployment-Dokument.

Hauptanwendungsbereiche:

• Suche im BDDK-Regulierungskatalog

• Semantische und Volltextsuche im Dokumenttext

• Bestimmte Dokumentseiten als Markdown abrufen

• Abschnitte wie Madde, İlke, Paragraf, Ek direkt abrufen

• Daten der wöchentlichen und monatlichen Banken-Bulletins abfragen

• Zusammenfassungen für Regulierungsänderungen, Ankündigungen und Trends erstellen

• Dokumentqualität, OCR/Formelrisiken und Extraktionsfehler überwachen

Hervorgehobene Funktionen

• MCP-SDK-basierte Tools: Es gibt Konfigurationsbeispiele für Claude/Codex für stdio und Streamable HTTP; sie sind kein releasespezifisches Zertifikat der Client-Kompatibilität.

• Offline-First-Dokumentabruf: Regulierungstexte und -abschnitte werden über PostgreSQL/pgvector bereitgestellt; Institutionen-, Ankündigungs- und Bulletintools können Upstream-Zugriff erfordern.

• Trennung von Katalog- und Volltextsuche: search_bddk_regulations durchsucht nur Titel/Metadaten; search_document_store führt eine semantische Suche im Dokumenttext durch.

• Abschnittsbasierter Zugriff: Mit get_document_section und search_document_sections werden Referenzen wie 943 İlke 5 oder mevzuat_22599 Madde 9 direkt gefunden.

• Schutz exakter rechtlicher Referenzen: Lexikalische Übereinstimmungen wie Madde 9 bleiben erhalten, auch wenn der semantische Score niedrig ist.

• Qualitätskennzeichen: Dokumentausgaben werden mit clean-, warning-, fail-Signalen und Qualitätsflags markiert.

• Sanitierung des Dokumentkontexts: get_bddk_document entfernt Data-URIs, rohe HTML/OCR-Artefakte und lange Zeilen, bevor sie in den Modellkontext gelangen.

• Operator-Skripte: Es gibt Abläufe für Qualitätsscans, Qualitäts-Backfill und document_sections-Reindex.

• PostgreSQL + pgvector: Dokumente, Abschnitte, FTS und Vektorsuche laufen auf einer einzigen Datenbank.

Tool-Oberfläche

Das Standard-public-Prozessprofil (BDDK_TOOL_PROFILE=public oder bddk-mcp serve --profile public) exponiert nur 17 öffentliche Tools.

Das separate operator-Prozessprofil (BDDK_TOOL_PROFILE=operator oder bddk-mcp serve --profile operator) fügt den 17 öffentlichen Tools 14 Operator-Tools hinzu und exponiert insgesamt 31 Tools. Dieses Profil erfordert eine separate, schreibberechtigte BDDK_OPERATOR_DATABASE_URL; es fällt nicht auf die öffentliche DSN zurück.

• check_bddk_updates

• document_store_stats

• bddk_cache_status

• refresh_bddk_cache

• sync_bddk_documents

• trigger_startup_sync

• get_operator_job

• list_operator_jobs

• cancel_operator_job

• document_health

• health_check

• bddk_metrics

• backfill_degraded_documents

• document_quality_report

Die kanonische Operator-Registry für die aktuelle Laufzeit enthält 17 öffentliche und 14 Operator-Tools, also insgesamt 31 MCP-Tools. Mutierende Operator-Tools geben sofort eine Job-Quittung zurück; der Status wird über get_operator_job, list_operator_jobs und cancel_operator_job verfolgt. Job-Datensätze werden dauerhaft in der Tabelle bddk_operator.operator_jobs in PostgreSQL gespeichert, einschließlich gehashter Idempotenzschlüssel, numerischer Fortschritts- und begrenzter Ergebnis-Metriken. Ein Session-Level-Job-Admission-Lease verhindert die gleichzeitige Übernahme durch Prozesse desselben Runners; eine zusätzliche Transaktions-Level-Corpus-Mutation-Lock serialisiert freigegebene Writer-Transaktionen und den Release-Publisher. Runner-Tasks befinden sich weiterhin im Operator-Prozess; veraltete queued-Aufträge werden nicht automatisch übernommen und sind in einer Bankumgebung mit Multi-Replica-Failover nicht validiert. Daher verwendet der OpenShift starter eine einzelne Recreate-Replica, und das System sollte nicht als Workflow-Warteschlange in Bankenqualität dargestellt werden. Benchmark-Schemata werden aus derselben kanonischen Operator-Registry erzeugt; Benchmark-Läufe sollten dennoch die exakte Tool-Liste und das verwendete Profil protokollieren. Siehe benchmark/README.md.

Schnellstart

Voraussetzungen:

• Python 3.12 oder 3.13

• uv

• PostgreSQL 17, pgvector und unaccent (nicht getestete Hauptversionen für dieses Release werden fail-closed abgelehnt)

• Optional: Docker Compose

Installation:

git clone https://github.com/omercagatay/bddk-mcp.git
cd bddk-mcp
uv sync

Ephemerer lokaler PostgreSQL-Lifecycle:

export BDDK_JWT_ISSUER=https://idp.invalid
export BDDK_JWT_RESOURCE=https://localhost:8000/mcp
export BDDK_JWT_JWKS_URL=https://idp.invalid/jwks
export BDDK_JWT_AUDIENCE=bddk-mcp-local
docker compose up --build -d bddk-bootstrap
docker compose wait bddk-bootstrap
export BDDK_DATABASE_URL=postgresql://bddk_local_public:local-only-public@localhost:5432/bddk

Compose führt die Abfolge DBA-Rollen-/Extensions-Vorbereitung → Schema-Eigentümer-migrate → DBA-Grants → Ingestion-bootstrap nur in einer Loopback-Entwicklungsumgebung aus. .invalid-JWT-Werte dienen dazu, dass Compose die ungenutzte HTTP-Service-Definition parsen kann; dieser Lifecycle-Befehl startet keinen HTTP-Server, und diese Werte sind nicht gültig, um einen Server zu betreiben. Die festen Passwörter sind öffentliche Test-Fixtures und dürfen nicht in entfernten Umgebungen verwendet werden. In der Produktion ist bddk-mcp migrate reine Schemaarbeit; bddk-mcp bootstrap schreibt geprüfte Seed-Daten, Abschnitte und 768-dimensionale Embeddings in das bereits migrierte und mit Grants versehene Schema und führt keine Migrationen aus. Weitere Identität und die vollständige Reihenfolge finden Sie im Deployment-Dokument.

Um den Corpus-Umfang und die drei Seed-Artefakte ohne DB-Verbindung zu prüfen, führen Sie den optionalen Read-only-Preflight aus:

uv run --frozen bddk-mcp verify-corpus

Dieser Befehl prüft Checksummen, Größe, Datensatzanzahl und Freshness-Zeiten; er überträgt jedoch kein Vertrauen an einen nachfolgenden Prozess. Der Produktionsimport muss dieselben strengen Richtlinien direkt in der mutierenden bootstrap-Invocation erneut anwenden:

BDDK_INGESTION_DATABASE_URL='postgresql://INGESTION:SECRET@HOST:5432/DATABASE?sslmode=verify-full&sslrootcert=%2FAPPROVED%2Fpostgres-ca.crt' \
  uv run --frozen bddk-mcp bootstrap \
    --seed-dir /APPROVED/CORPUS \
    --reindex-existing \
    --require-quantified-freshness \
    --require-measured-freshness \
    --require-verified-signature \
    --trusted-signing-key /APPROVED/TRUST/corpus-signing-public-key.pem

bootstrap prüft vor dem Öffnen des DB-Pools die exakte corpus_scope.yml und die im Manifest definierten Artefakt-Pfade/-Bytes/-Hashes; vorhandene, aber nicht im Manifest definierte Dateien wie documents.json, chunks.json oder decision_cache.json werden abgelehnt. Der Trust-Key muss über ein separates Secret/Mount vom Corpus getrennt geliefert werden. Ein numerisches Ziel zu definieren ist allein noch keine Messung: Im Status measured müssen für jedes Dokument die Zeitkette der autoritativen Veröffentlichung → Quellenerkennung → Download → Extraktion → Retrieval-Veröffentlichung sowie die berechneten Verzögerungen innerhalb der Ziele liegen. Das aktuelle geprüfte Manifest (bddk-job-corpus-2026-08-14) ist Ed25519-signiert und trägt numerische Ziele (7 Tage Erkennung, 14 Tage Veröffentlichung, 180 Tage Manifest-Alter); mit --require-quantified-freshness und --require-verified-signature ist der Produktions-Bootstrap gültig. Da es keine Live-Überwachung gibt, bleibt slo_evidence_status: not_measured erhalten, und ein Verifier, der --require-measured-freshness verlangt, lehnt das Staging an diesem einzigen Tor bewusst ab. Ein erfolgreicher Bootstrap gibt eine pfadfreie Manifest-ID und SHA-256 für den Operator-Nachweis zurück und weist auf eine separate Veröffentlichung hin. Die Produktions-Lifecycle-Reihenfolge ist migrate → bootstrap → verify-and-stage-corpus-release → activate-corpus-release (DBA 02_grants.sql wird zwischen Migration und Bootstrap angewendet). Der Verifier verwendet eine separate bddk_release_verifier-Identität mit BDDK_RELEASE_VERIFIER_DATABASE_URL; er prüft Corpus und Trust-Key erneut, kontrolliert die exakte DB-Mitgliedschaft/State/Epoch und gibt eine kurzlebige Request-ID zurück. Der Trust-Key muss separat gemountet werden, und sowohl der angegebene als auch der aufgelöste Pfad müssen außerhalb des Corpus-Roots liegen. BDDK_RELEASE_VERIFIER_REVISION_SHA256 muss eine 64-stellige hexadezimale Revision in Kleinbuchstaben sein, BDDK_RELEASE_VERIFIER_IMAGE_DIGEST ein sha256:-Digest und BDDK_RELEASE_VERIFICATION_VALIDITY_SECONDS 60–3.600 Sekunden (Standard 900) betragen. Der Publisher erhält nur diese Request-ID und den Wert von BDDK_RELEASE_PUBLISHER_DATABASE_URL; er erhält kein Corpus-PVC, Manifest, Signatur oder Trust-Key:

BDDK_RELEASE_VERIFIER_DATABASE_URL='postgresql://VERIFIER:SECRET@HOST:5432/DATABASE?sslmode=verify-full&sslrootcert=%2FAPPROVED%2Fpostgres-ca.crt' \
BDDK_RELEASE_VERIFIER_REVISION_SHA256='REPLACE_64_LOWERCASE_HEX_REVISION' \
BDDK_RELEASE_VERIFIER_IMAGE_DIGEST='sha256:REPLACE_64_LOWERCASE_HEX_IMAGE_DIGEST' \
BDDK_RELEASE_VERIFICATION_VALIDITY_SECONDS=900 \
  uv run --frozen bddk-mcp verify-and-stage-corpus-release \
    --seed-dir /APPROVED/CORPUS \
    --trusted-signing-key /APPROVED/TRUST/corpus-signing-public-key.pem

BDDK_RELEASE_PUBLISHER_DATABASE_URL='postgresql://PUBLISHER:SECRET@HOST:5432/DATABASE?sslmode=verify-full&sslrootcert=%2FAPPROVED%2Fpostgres-ca.crt' \
  uv run --frozen bddk-mcp activate-corpus-release \
    --request-id corpus_release_request_sha256_REPLACE_64_LOWERCASE_HEX

Wenn der Aktivierungs-Request abgelaufen ist, bereits verwendet wurde oder sich corpus state/epoch/readiness geändert hat, erfolgt ein Fail-Closed. Der alte Alias publish-corpus-release ist deaktiviert, um die Trennung von Anmeldeinformationen zu wahren.

Eine alte Datenbank von vor dem Ledger wird von der gewöhnlichen Migration fail-closed abgelehnt. --adopt-legacy ist eine explizite Option, die nur für die exakt unterstützte Form mit verifiziertem Backup und dem Legacy-Upgrade-Runbook verwendet wird; es ist kein Flag für eine saubere Installation oder allgemeine Reparatur.

In einer vollständigen Version-2-Datenbank wird Migration 3 standardmäßig wegen des blockierenden Retrieval-Publication-Backfills und der Fremdschlüsselvalidierung abgelehnt. --allow-retrieval-publication-backfill sollte nur in einem kontrollierten Wartungsfenster verwendet werden, nachdem die Workloads gestoppt, ein wiederherstellbares Backup nachgewiesen und auf einem Restore derselben Größe geprobt wurde. BDDK_EXPECTED_DATABASE_NAME und die unabhängige Zielsetzung der DBA-Skripte müssen mit der aktiven Datenbank übereinstimmen. Außerhalb des isolierten lokalen Compose-Profils müssen PostgreSQL-DSNs sslmode=verify-full und einen absoluten sslrootcert-Pfad verwenden.

Test:

uv run pytest tests/test_tools_sections.py tests/test_doc_store.py -k section -v
uv run ruff check .

MCP stdio-Ausführung:

BDDK_DATABASE_URL=postgresql://bddk:bddk@localhost:5432/bddk \
uv run --frozen bddk-mcp serve

HTTP-Transport:

BDDK_DATABASE_URL=postgresql://bddk:bddk@localhost:5432/bddk \
MCP_TRANSPORT=streamable-http \
PORT=8000 \
uv run --frozen bddk-mcp serve

Der Streamable-HTTP-MCP-Endpunkt ist http://localhost:8000/mcp, und der Server arbeitet im zustandslosen JSON-Antwortmodus. Die Remote-Anwendung veröffentlicht die RFC-9728-Metadaten für geschützte Ressourcen unter /.well-known/oauth-protected-resource/mcp; die 401-Challenge meldet dieselbe URL über resource_metadata. Dies ist eine Autorisierungsermittlung für MCP auf Anwendungsebene und kein Nachweis für die Client-Registrierung bzw. die Akzeptanz durch den Bank-IdP. Die festen, inhaltsfreien Probe-Endpunkte sind GET /health/live und GET /health/ready; die Bereitschaftsprüfung validiert regelmäßig Migrationen, kritische Katalogobjekte, Corpus-Publikation und Workload-ACLs neu. Obwohl die Probes von der Authentifizierungs- und Host-Prüfung ausgenommen sind, unterliegen sie den Prozess-Raten- und Nebenläufigkeitslimits. Für Bindungen außerhalb von Loopback gilt Fail-Closed: Exakte Host-/HTTPS-Origin-Allowlists und vollständige JWT-/JWKS-Einstellungen sind Pflicht; das öffentliche Profil verlangt den Scope bddk.read, das Operator-Profil den bddk.operator. Ein Remote-Operator erfordert zusätzlich ein explizites Opt-in über BDDK_OPERATOR_REMOTE_ENABLED=true. BDDK_HTTP_ALLOW_UNAUTHENTICATED ist ein unterstütztes explizites Opt-in, um eine öffentliche schreibgeschützte Bindung außerhalb von Loopback ohne Bearer-Authentifizierung anzubieten; es ist standardmäßig ebenfalls nicht gesetzt, und solange es nicht gesetzt ist, bleibt die Fail-closed-Voreinstellung bestehen. Bei Setzen darf die Variable nicht mit irgendeiner BDDK_JWT_-präfixierten Einstellung kombiniert werden – der Start wird abgelehnt und die gesetzten Variablen werden namentlich aufgelistet – und sie wird für das Operator-Profil außerhalb von Loopback unabhängig vom Wert von BDDK_OPERATOR_REMOTE_ENABLED abgelehnt; Operator-Werkzeuge bleiben authentifiziert oder auf Loopback beschränkt. Der nicht authentifizierte Server veröffentlicht keine OAuth-Ermittlung: Die WWW-Authenticate-Challenge fehlt, und beide Well-known-OAuth-Routen geben 404. Host-/Origin-Allowlists sowie Body-, Nebenläufigkeits- und Rate-Limits werden weiterhin durchgesetzt; in diesem Modus ist der Rate Limiter die primäre Missbrauchskontrolle. Der Client-Schlüssel des Rate Limiters wird durch BDDK_HTTP_TRUSTED_PROXY_HOPS (Standard 0) bestimmt: Bei 0 ist der Schlüssel der ASGI-Socket-Peer, und X-Forwarded-For wird vollständig ignoriert; hinter n vom Betreiber kontrollierten Reverse-Proxys wird die tatsächliche Anzahl von Hops konfiguriert, und der von rechts gezählte n-te Eintrag der kombinierten Weiterleitungsliste wird als Schlüssel verwendet. Nicht verwendbare Werte fallen nicht auf den Socket-Peer zurück, sondern in den gemeinsamen unknown-Bucket; ein falscher Wert macht den Limiter entweder gemeinsam oder spoofbar. Die Body-, Nebenläufigkeits- und Minutentrate-Limits werden innerhalb des Anwendungsprozesses durchgesetzt; zwischen Replikaten gibt es kein globales Ingress-Limit. Einzelheiten finden Sie in der Einrichtungsdokumentation.

Der ältere Hilfsbefehl für Seed-Import/-Export bleibt erhalten; bei neuen Bereitstellungen wird jedoch bdk-mcp bootstrap mit Validierung bevorzugt:

BDDK_INGESTION_DATABASE_URL=postgresql://bddk_local_ingestion:local-only-ingestion@localhost:5432/bddk \
uv run --frozen bddk-seed import

Claude-Konfiguration

Die Datei .mcp.json im Repository-Stamm ist ein tragbares stdio-Beispiel für .mcp.json-kompatible Clients, die den Repository-Stamm als Arbeitsverzeichnis verwenden:

{
  "mcpServers": {
    "bddk": {
      "command": "uv",
      "args": ["run", "--frozen", "bddk-mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BDDK_DATABASE_URL": "${BDDK_DATABASE_URL}"
      }
    }
  }
}

Codex-Konfiguration

Die Codex-CLI und die IDE-Erweiterung verwenden dieselbe Codex-MCP-Konfiguration. Fügen Sie den Folgendes in ~/.codex/config.toml oder /codex/config.toml in einem vertrauenswürdigen Repositing hinzu; ändern Sie den Wert cwd auf Ihren eigenen Checkout-Pfad:

[mcp_servers.bddk]
command = "uv"
args = ["run", "--frozen", "bddk-mcp"]
cwd = "/absolute/path/to/bddk-mcp"
env_vars = ["BDDK_DATABASE_URL"]
startup_timeout_sec = 30
tool_timeout_sec = 60

Bestätigen Sie die Verbindung mit codex mcp list oder /mcp in Codex.

Zu Grenzen von Docker, Railway und OpenShift-AI-Systemen siehe docs/DEPLOYMENT.md.

Beispielabfragen

search_bddk_regulations(keywords="kredilerin sınıflandırılması")
search_document_store(query="TFRS 9 kredi riskinde önemli artış")
get_bddk_document(document_id="mevzuat_22599", page_number=1)
get_document_section(document_id="943", section_type="ilke", section_ref="5")
search_document_sections(query="Karşılık Yönetmeliği Madde 9 TFRS 9")
get_bddk_bulletin(metric_id="1.0.1", currency="TRY", days=90)
analyze_bulletin_trends(metric_id="1.0.1", lookback_weeks=12)
get_regulatory_digest(period="week")

Related MCP server: tr-eli-mcp

Operator-Workflows

Qualitätsscan:

uv run python scripts/scan_document_quality.py --db --out-dir quality_reports --allow-failures

Dokumente mit Qualitätsproblemen als Trockenlauf:

uv run python scripts/backfill_quality_failures.py --dry-run

Ein bestimmtes Dokument mit Qualitätsfehler erneut abrufen:

uv run python scripts/backfill_quality_failures.py --doc-id mevzuat_21192 --execute

Die Tabelle document_sections aus bestehenden Dokumenten anhand der Ingestions-Kennung neu erzeugen:

BDDK_INGESTION_DATABASE_URL=postgresql://INGESTION:SECRET@HOST:5432/DB \
  uv run python scripts/reindex_document_sections.py --execute

Die Qualitäts-Backfill-, Sync- und Reindex-Skripte, die Ausführungen durchführen, verlangen ebenfalls BDDK_INGESTION_DATABASE_URL und prüfen den strikten bddk_ingestion-Privilegvertrag; sie dürfen nicht mit öffentlichen oder Operator-DSNs ausgeführt werden.

Optionale Retrieval-Telemetrie:

BDDK_DATABASE_URL=postgresql://PUBLIC:SECRET@HOST:5432/DB \
BDDK_TELEMETRY_ENABLED=true \
BDDK_TELEMETRY_DATABASE_URL=postgresql://TELEMETRY:SECRET@HOST:5432/DB \
  uv run --frozen bddk-mcp serve --profile public

Telemetrie ist standardmäßig deaktiviert. Wenn sie aktiviert wird, darf ein separater LOGIN nur die Rolle bddk_telemetry_writer erben; der Start prüft die spaltenbezogene INSERT-only-Berechtigung und lehnt Trace-Lesen/-Ändern oder nur weitgefasste Mitgliedschaft ab. In die Tabelle tool_call_traces erhält ein Speicher, der Latenz, Ergebnisanzahl, Dokumenten-ID, Qualitätslabel und Relevanz-Zusammenfassung schreibt; der Abfrage-/Aufforderungstext wird als Hash-/Längen-Zusammenfassung gespeichert. Rohtext wird nur geschrieben, wenn BDDK_TELEMETRY_STORE_TEXT=true explizit gesetzt ist.

Architektur

server.py                 Kök shim → bddk_mcp/server.py
seed.py                   Kök shim → bddk_mcp/ingest/seed.py
bddk_mcp/                 Ana paket
  server.py               FastMCP giriş noktası ve lifecycle
  core/                   config, DB identity, outbound HTTP, logging ve modeller
  migrations/             Immutable global PostgreSQL migration ledger
  jobs/                   Durable operator job modelleri ve PostgreSQL repository
  store/                  doc_store, vector_store, section_index, legal_ref
  ingest/                 client, data_sources, doc_sync, html_extractor, backfill, seed
  quality/                markdown_quality, quality_scan
  observability/          analytics, telemetry, metrics
  tools/                  MCP tool modülleri
  ocr/                    base, chandra (pluggable OCR)
scripts/                  Operatör ve backfill scriptleri
benchmark/                Tool schema ve benchmark altyapısı

Hinweise zu Datenqualität und Sicherheit

• Vollständige Dokumentabrufe und Abschnittssuchergebnisse stammen aus dem lokalen Store; diese beiden Abläufe führen All-Zeit-Lauf keine Live-Nachladen für Dokumente aus.

• Katalog-Cache-Aktualisierung, Suche nach Einrichtung/Bekanntmachung sowie Bülten-Tools können je nach Konfiguration und Cache-Zustand auf BDDK-Upstream-Dienste zugreifen.

• Live-URLs-Suchpfade des Rechtserfahrens setzen exakte BDDK-/Gesetzes-HTTP-Hosts, Redirect-/DNS-Revalidierung und in Code festgelegte Streaming-Limits je nach Artefakttyp durch; URL-/Query-/Absoluttexte werden nicht in Retry-Logs geschrieben. Da die öffentliche Suche Tools für Einrichtung/Bekanntmachung/Bülten/Update auch Live-BDDK-Zugriff verwenden können, muss der OpenShift-Egress-Vertrag für die public/Operator-Laufzeitumgebung nur genehmigung Rechts- oder Proxy für TCP 443 zulassen; Lifecycle-Jobs dürfen diesen Zugriff nicht erhalten. Von dem der Weg zur Verbindung über DNS ein Race ist, sind Network-Policy oder genehmigter Proxy/Firewall erforderlich.

• Das Standard-Embedding-Modell ist mit dem vollständigen Commit d13f1b27baf31030b7fd040960d60d909913633f verankert, der optionale Standard-Reranker determinst per 1427fd652930e4ba29e8148345 9678df786c240d8825 Pin; das unveränderbare Schema akzeptiert nur vector(768). Eine Änderung an Modell/Chunk-Konfiguration erfordert: Rock gesteuertes vollständiges Re-Embedding und Retrieval-Regression.

• Der Veröffentlichungsdatensatz die Retrieval-Veröffentlichung wird erst geschrieben, nachdem Chunk-Integrität, aktueller Inhalt-Hash und aktives Retrieval-Profil validiert wurden; fehlende oder veraltete Indizes gelangen nicht lautlos in die Suchergebnisse.

• Bootstrat bindet das geprüfte Korpus an die exakten Artefaktpfade des Manifests und backweist den Umgehungsweg durch reservierte Seed-Dateinamen ab. Ein separater verify-corpus-Lauf ist nur ein diagnostischer Preflight; die produktionsseitigen Sicherheitsgates müssen direkt demselben bootstrap-Befehl und dem separat aufbereiteten Vertrauensschlüssel obliegen. Das deploy/openshift-overlays/bank-bootstrap validiert diesen exakten Befehl, das schreibgeschützte approved-corpus-PVC and das separat read-only corpus-trust Secret im Repository-Preflight VORSCHRIFT; die tatsächliche Provisionierung von PVC/Secret der Bank und der Joblauf bleiben externe Gates.

• v0005 fügt eine Append-only-Freigabe-/Aktivierungs- und Mutations-Epoche ein, die onto die 17 Corpus-Tabellen abdeckt; strikte lokale Corpus-Aufrufe validieren dieselbe Aktivierung aufreichen vor und nach dem Aufruf. Bei die v0008 fällt die ältere direkte Veröffentlichungsberechtigung vom Publisher ab: bddk_release_verifier liest das Corpus-/Trust-Material, belegt die strikte Mitgliedschaft und staffelt die Anfrage mit einer Aktualisierung (TL) und der Revision/Image-Digest von Verifier mit einer TTL von 60 bis 3.600 Sekunden; bddk_release_publisher kann Aktionen nur über eine einmalige Request-ID durchführen. Die Aktivierung prüft atomisch erneut Ablauf, Wiederverwendung, Veröffentlichungsreife, Corpus-Epochen und Zustand bis hin zur Zustandsprüung. Userizugriff auf beide Rollen oder Schema-Ownership-Berechtigung durch denselben Auftraggeber durchbricht die Trennung; die Secret-/RBAC-Verwaltung der Bank muss das verhindern. v0007 kronisiert außerdem den exakten aktiven Zustand mit retain-generations-license --expected-release-id ... und kopiert ihn in 17 typisierte retained Beziehungen, wobei sie versiegelt werden; eine retained Generation ist kein Serving oder eine Reaktivierung. Die v7-vorgeschriebene Korrektur für nicht-kanonische Hashes ist nur eine exakte, geprüfte, nur-design_Public-Compatibility-Grenze im unveränderten v5/v6-Schema; nach einem Wechsel auf v7 ist v8 nicht als direkter Zustand in steady-state zu verwenden – also kein direkter Pfad für die Migration. Wenn Sie den Web publish-corpus-release-CLI in der aktuellen Binary deaktiviert, sollen Sie keine historischen Zeilen oder Bindungen erzeugen; erforderlich genWeisen Sie den zugelassenen Upgrade-Migrationspfad aus und schließen Sie v8-Migrationen und -Grants v8 ab. Das verfolgte Corpus ist signiert und meldet die im aktuellen Profil erzeugten 9.675 Chunks. Der v0010-Veröffentlichungs-Ledger akzeptiert nur zwei Freshness-Politiken: quant_it_measure_signature_verified_pass and der quantum_unmeasure_signature_verified_pass weakere. Beide verlangen ein numerisches Ziel und eine signierte Signatur. Der Verifier leitet eine Stufe aus dem Manifest-Wischerbeweis ab; --Accept-unmeasure-Freshness nur die zhlwache Stufe zu, kann sie aber nicht als gemessen markieren.

• v0004's 11 owner-controlled Tabellen für die Rechtsabstimmung trennen die Inhaltsidentität von SourceBlob von der Erwerbsidentität von SourceArtifact. Mutationsberechtigungen liegen allein beim Eigentümer; v0008 verleiht dem Release-Verifier eine exakte schreibgeschützte Ausnahme, um den Veröffentlichungsnachweis neu zu berechnen. Die v0006 vermittelt einen öffentlichen Funktionder resolve_regulation_status / Werkzeugpfad, der bei Konflikt oder fehlendem Beweis enthält. Synthetic real-PostgreSQL-Beweise sind kein Beweis für die tatsächliche Regulierungs-Familie / -Aktualität.

• Der Evaluierungs-Gate erfordert vier signierte Ebenen: das gemessene Corpus, das Expertendataset, die legal-curator-Bestätigung für die exakte Citation-Pack und der Legal-Releaseerify-Punkt, der die abgenommene Source-/Acquisition-/Page-/Exzerpt-Kette verankert. Die fingerpriming-Muster für Canonical Corpus/Dataset/Curator/Release-Signer müssen getrennt sein. Der vorliegende Preflight beweist nur die kryptografische Konsistenz unter vom Operateur gelieferten Anker; Zulüssigkeitsgenehmigung der Bank und Model-Score-Erlaubnis sind in sog. false falsch. Der verfolgte 20-Fall-Datensatz ist ein Entwurf; Schlüsselrotation, benannte Reviewergebnispolitik und Expert-Case-Ausführung stehen noch nicht zur Verfügung.

• Supply-Chain-Lane-Container werden mit Buildx --provenance=false --load lokal erzeugt; die Descriptor-/Digest-Fingerabdrucke des Manifest sowie der Config-Digest, das geladene Image und die Syft-SBOM werden fail-closed auf dasselbe Image verlinkt. Das Repository erzeugt außerdem unsigned SLSA-Provenienz Prüfen des Modelverzeichnisses/Runtime-Fähigkeit/Dockerfile-Pin-Kompatibilität. Verwendete Ergebnisse mit „pending exception“ sind nie für Promotion geeignet; Bank-Signierung, Admission und Registry-Ressource Promotions bleiben äußere Gates.

• Die Runtime-Wheel/Sdist ent nehmen keine seed_data, Benchmarks oder Deployment-Assets; der mitgelieferte Container enthält explizit das geprüfte Seedenthält. Eine vermittelten Wheel-Installation muss ein genehmigtes Corpus montieren und das Programm zur Programmmaßnahme mit --seed-dir oder BDDK_SEED_DIR versehen.

• Extraction Ausgaben mit schlechter Qualität werden als warning oder fail markiert.

• Bei formelreichen oder von OCR-QualitÄ geminderten Dokumenten kann eine Prüfung der Quell-PDF-Datei erforderlich sein.

• In get_bddk_document-Antworten werden data URI, raw HTML und einige OCR-Artefakte bereinigt.

• Das Modell soll sich in der Antwort auf die Tool-Ausgabe stützen, sich nicht aus, decision number, date, or legal conclusion zu erfinden.

• Bekannte Extraktionsprobleme, Feedback-Liste fehlgeschlagener Dokumente und Backfill-Befehle finden Sie unter docs/DOCUMENT_QUALITY.md.

• Der OpenShift-AI-Cluster der Bank, der Backup-/Restore-Strom und die Claude/Codex/GPT/GPT-OSS/LM-Studio/local Client-Matrix sind mit diesem Repository noch nicht in den Abnahmeprozess durchlaufen.

Deutsch

Was ist das?

Das BDDK-MCP-Server-Angebot zählt darauf, eine sichere, prüfbare Model-Context-Prokt-KA – Schnittstelle für türkische Bankenaufsichtsdaten bereitzustellen. Er soll LLM-Antworten in den lokalen BDDK-Daten fundieren, nicht auf dem Vorwissen des Modells. Eine Deployment-Guide beschreibt die aktuellen produktionsbezogenen Sicherheitsgrenzen.

Häufige Anwendungsfälle:

• Den BDDK-Vorschriftenkatalog durchsuchen

• In Dokumenten im Kontext mit semantischen und Volltextsuche durchsuchen

• Seitierte Markdown-Dokumente abrufen

• Exakte Rechtsteile wie Madde, Ilke, Paragraf und Ek abrufen

• Wöchentliche und monatliche Daten zu Bankbulten abfragen

• Regulierungszusammenfassungen und Trendübersichten erstellenC

• Dokumentqualität, OCR- /Formelrisiko und Extraktionsfehler berichten

Highlights

• MCP-SDK-Tooloberfläche: stdio- und Streamable-HTTP-Beispiele werden für Claude/Codex bereitgestellt; die Beispiele sind keine release-spezifische Kompatibilitätszertifizierung.

• Offline-first-Dokumentabruf: Verordnungstexte und -abschnitte werden aus PostgreSQL/pgvector bereitgestellt; Institutionen-, Ankündigungs- und Bulletin-Tools erfordern möglicherweise Upstream-Zugriff.

• Katalog/Textkorpus-Trennung: search_bddk_regulations durchsucht Metadaten; search_document_store durchsucht Dokumentkörper.

• Abruf auf Abschnittsebene: get_document_section und search_document_sections unterstützen Referenzen wie 943 Ilke 5 und mevzuat_22599 Madde 9.

• Exakte Erhaltung rechtlicher Verweise: Lexikalische Treffer wie Madde 9 überstehen die dichte Relevanzfilterung.

• Qualitätskennzeichnungen: Dokumentausgaben enthalten Metadaten und Qualitätsflags wie clean, warning oder fail.

• Dokumentkontext-Bereinigung: get_bddk_document entfernt Daten-URIs, rohe HTML-/OCR-Artefakte und pathologisch lange Zeilen, bevor der Modellkontext erstellt wird.

• Operator-Skripte: Qualitätsscan, Qualitäts-Backfill und document_sections-Neuindizierungs-Workflows sind enthalten.

• PostgreSQL + pgvector: Dokumente, Abschnitte, FTS und Vektorsuche teilen sich eine Datenbank.

Tool-Oberfläche

Das Standard-Prozessprofil public (BDDK_TOOL_PROFILE=public oder bddk-mcp serve --profile public) legt nur 17 öffentliche Tools offen.

Das separate Prozessprofil operator (BDDK_TOOL_PROFILE=operator oder bddk-mcp serve --profile operator) fügt den 17 öffentlichen Tools 14 Operator-Tools hinzu und legt insgesamt 31 Tools offen. Es erfordert eine separate, schreibfähige BDDK_OPERATOR_DATABASE_URL und fällt niemals auf die öffentliche DSN zurück.

• check_bddk_updates

• document_store_stats

• bddk_cache_status

• refresh_bddk_cache

• sync_bddk_documents

• trigger_startup_sync

• get_operator_job

• list_operator_jobs

• cancel_operator_job

• document_health

• health_check

• bddk_metrics

• backfill_degraded_documents

• document_quality_report

Die kanonische Operator-Registry enthält 17 öffentliche Tools plus 14 Operator-Tools, also insgesamt 31 MCP-Tools. Mutierende Operator-Tools geben sofort einen Job-Beleg zurück; verwenden Sie get_operator_job, list_operator_jobs und cancel_operator_job, um sie zu beobachten. Jobdatensätze, gehashte Idempotenzschlüssel, numerischer Fortschritt und begrenzte Ergebnismetriken sind dauerhaft in der PostgreSQL-Tabelle bddk_operator.operator_jobs gespeichert. Eine sitzungsspezifische Job-Admissions-Lease verhindert gleichzeitigen Besitz desselben Runners über Prozesse hinweg; eine separate transaktionsbezogene Korpus-Mutationssperre serialisiert autorisierte Schreibertransaktionen und den Release-Publisher. Runner-Aufgaben leben weiterhin im Operator-Prozess, veraltete queued-Aufträge werden nie automatisch übernommen, und Multi-Replica-Failover wurde in einer Bankumgebung nicht freigegeben. Der OpenShift-Starter verwendet daher eine Recreate-Replica, und dies wird nicht als bankentaugliche Workflow-Warteschlange dargestellt. Benchmark-Schemata werden aus derselben kanonischen Operator-Registry exportiert; Benchmark-Läufe sollten weiterhin die exakte Tool-Liste und das verwendete Profil aufzeichnen. Siehe benchmark/README.md.

Schnellstart

Voraussetzungen:

• Python 3.12 oder 3.13

• uv

• PostgreSQL 17 mit pgvector und unaccent (diese Version schlägt bei ungetesteten Hauptversionen fehl (Fail-Closed))

• Optional: Docker Compose

Installation:

git clone https://github.com/omercagatay/bddk-mcp.git
cd bddk-mcp
uv sync

Wegwerfbarer lokaler PostgreSQL-Lebenszyklus:

export BDDK_JWT_ISSUER=https://idp.invalid
export BDDK_JWT_RESOURCE=https://localhost:8000/mcp
export BDDK_JWT_JWKS_URL=https://idp.invalid/jwks
export BDDK_JWT_AUDIENCE=bddk-mcp-local
docker compose up --build -d bddk-bootstrap
docker compose wait bddk-bootstrap
export BDDK_DATABASE_URL=postgresql://bddk_local_public:local-only-public@localhost:5432/bddk

Nur für Loopback-Entwicklung führt Compose die Reihenfolge DBA-Rollen-/Erweiterungs-Einrichtung → Schema-Eigentümer-migrate → DBA-Grants → Ingestions-bootstrap aus. Die reservierten .invalid-JWT-Werte dienen nur dazu, dass Compose eine ungenutzte HTTP-Dienstdefinition parsen kann; dieses Lebenszyklus-Ziel startet keinen HTTP-Server, und diese Werte sind keine gültige Serverkonfiguration. Die festen Passwörter sind öffentliche Test-Fixtures und dürfen nicht auf entfernte Systeme kopiert werden. In Produktion führt bddk-mcp migrate nur Schemaarbeiten durch. bddk-mcp bootstrap erfordert ein bereits migriertes und mit Grants versehenes Schema und importiert dann den geprüften Seed, die Abschnitte und 768-dimensionale Embeddings; es migriert nicht. Siehe den Deployment-Leitfaden für die vollständige Identitäts- und Anwendungsreihenfolge.

Verwenden Sie den optionalen schreibgeschützten Preflight, um die Korpusdeklaration und alle drei Seed-Artefakte zu prüfen, ohne eine Datenbankverbindung zu öffnen:

uv run --frozen bddk-mcp verify-corpus

Der Befehl prüft Prüfsummen, Größen, Datensatzanzahlen und Aktualitätszeitstempel, überträgt das Vertrauen jedoch nicht auf einen späteren Prozess. Der Produktionsimport muss die strengen Richtlinien direkt im mutierenden bootstrap-Aufruf erneut anwenden:

BDDK_INGESTION_DATABASE_URL='postgresql://INGESTION:SECRET@HOST:5432/DATABASE?sslmode=verify-full&sslrootcert=%2FAPPROVED%2Fpostgres-ca.crt' \
  uv run --frozen bddk-mcp bootstrap \
    --seed-dir /APPROVED/CORPUS \
    --reindex-existing \
    --require-quantified-freshness \
    --require-measured-freshness \
    --require-verified-signature \
    --trusted-signing-key /APPROVED/TRUST/corpus-signing-public-key.pem

Vor dem Öffnen eines Datenbankpools validiert bootstrap die exakte corpus_scope.yml sowie die im Manifest deklarierten Artefaktpfade, Bytes und Hashes; es lehnt eine vorhandene, aber nicht deklarierte Datei documents.json, chunks.json oder decision_cache.json ab. Stellen Sie den Vertrauensschlüssel aus einem Secret/Mount getrennt vom Korpus bereit. Das Deklarieren numerischer Ziele ist keine Messung: Der Status measured erfordert pro Dokument eine Zeitleiste von autoritativer Veröffentlichung → Quellenerkennung → Download → Extraktion → Abrufveröffentlichung sowie berechnete Verzögerungen innerhalb dieser Ziele. Das aktuelle geprüfte Manifest ist unsigniert, enthält keine numerischen Ziele und wird als slo_evidence_status: not_measured behandelt; es schlägt diesen Produktions-Bootstrap absichtlich fehl. Die erfolgreiche Bootstrap-Ausgabe enthält die pfadfreie Manifest-ID und SHA-256 als Operator-Nachweis und kennzeichnet die Veröffentlichung als erforderlich; es persistiert keinen Kandidaten. Der Produktionslebenszyklus ist migrate → bootstrap → verify-and-stage-corpus-release → activate-corpus-release (der DBA wendet 02_grants.sql zwischen Migration und Bootstrap an). Der Verifizierer verwendet eine eigene Identität bddk_release_verifier und BDDK_RELEASE_VERIFIER_DATABASE_URL; er validiert Korpus und Vertrauensschlüssel erneut, prüft exakte Datenbankmitgliedschaft/Status/Epoche und gibt eine kurzlebige Anforderungs-ID zurück. Der Vertrauensschlüssel muss ein separater Mount sein, dessen angegebene und aufgelöste Pfade beide außerhalb des Korpus-Stammverzeichnisses liegen. BDDK_RELEASE_VERIFIER_REVISION_SHA256 muss aus 64 hexadezimalen Kleinbuchstaben bestehen, BDDK_RELEASE_VERIFIER_IMAGE_DIGEST muss ein sha256:-Digest sein, und BDDK_RELEASE_VERIFICATION_VALIDITY_SECONDS ist auf 60–3.600 Sekunden begrenzt (Standard 900). Der Publisher erhält nur diese Anforderungs-ID und BDDK_RELEASE_PUBLISHER_DATABASE_URL—keine Korpus-PVC, kein Manifest, keine Signatur und keinen Vertrauensschlüssel:

BDDK_RELEASE_VERIFIER_DATABASE_URL='postgresql://VERIFIER:SECRET@HOST:5432/DATABASE?sslmode=verify-full&sslrootcert=%2FAPPROVED%2Fpostgres-ca.crt' \
BDDK_RELEASE_VERIFIER_REVISION_SHA256='REPLACE_64_LOWERCASE_HEX_REVISION' \
BDDK_RELEASE_VERIFIER_IMAGE_DIGEST='sha256:REPLACE_64_LOWERCASE_HEX_IMAGE_DIGEST' \
BDDK_RELEASE_VERIFICATION_VALIDITY_SECONDS=900 \
  uv run --frozen bddk-mcp verify-and-stage-corpus-release \
    --seed-dir /APPROVED/CORPUS \
    --trusted-signing-key /APPROVED/TRUST/corpus-signing-public-key.pem

BDDK_RELEASE_PUBLISHER_DATABASE_URL='postgresql://PUBLISHER:SECRET@HOST:5432/DATABASE?sslmode=verify-full&sslrootcert=%2FAPPROVED%2Fpostgres-ca.crt' \
  uv run --frozen bddk-mcp activate-corpus-release \
    --request-id corpus_release_request_sha256_REPLACE_64_LOWERCASE_HEX

Die Aktivierung schlägt fehl (Fail-Closed), wenn die Anforderung abgelaufen ist, bereits verwendet wurde oder sich Korpusstatus, Epoche oder Bereitschaft geändert haben. Der alte Alias publish-corpus-release ist deaktiviert, um die Trennung der Anmeldeinformationen zu wahren.

Eine gewöhnliche Migration schlägt bei einer nicht verwalteten Datenbank im Vor-Ledger-Stand fehl (Fail-Closed). --adopt-legacy ist eine explizite Option nur für die exakt unterstützte Form nach einem nachgewiesenen Backup und dem Legacy-Upgrade-Runbook; es ist kein Flag für eine Neuinstallation oder allgemeine Reparatur.

Eine befüllte Version-2-Datenbank verweigert außerdem standardmäßig die Migration 3, da der Retrieval-Publication-Backfill blockierende Sperren setzt und Fremdschlüssel validiert. Verwenden Sie --allow-retrieval-publication-backfill nur in einem kontrollierten Wartungsfenster, nachdem Sie Workloads gestoppt, ein wiederherstellbares Backup nachgewiesen und eine größenangepasste Wiederherstellung geprobt haben. BDDK_EXPECTED_DATABASE_NAME und das unabhängige DBA-Skriptziel müssen mit der aktiven Datenbank übereinstimmen. Außerhalb der isolierten lokalen Compose-Umgebung müssen PostgreSQL-DSNs sslmode=verify-full und einen absoluten sslrootcert-Pfad verwenden.

Test:

uv run pytest tests/test_tools_sections.py tests/test_doc_store.py -k section -v
uv run ruff check .

MCP über stdio ausführen:

BDDK_DATABASE_URL=postgresql://bddk:bddk@localhost:5432/bddk \
uv run --frozen bddk-mcp serve

Streamable HTTP ausführen:

BDDK_DATABASE_URL=postgresql://bddk:bddk@localhost:5432/bddk \
MCP_TRANSPORT=streamable-http \
PORT=8000 \
uv run --frozen bddk-mcp serve

Der Streamable-HTTP-MCP-Endpunkt ist http://localhost:8000/mcp, konfiguriert für zustandslose JSON-Antworten. Die entfernte Anwendung veröffentlicht RFC-9728-Metadaten für geschützte Ressourcen unter /.well-known/oauth-protected-resource/mcp, und ihre 401-Herausforderung identifiziert dieselbe URL über resource_metadata. Dies ist eine MCP-Autorisierungsermittlung auf Anwendungsebene, kein Nachweis einer Bank-IdP-Clientregistrierung oder der Akzeptanz des Ablaufs. Die festen, inhaltsleeren Probe-Endpunkte sind GET /health/live und GET /health/ready; die Bereitschaftsprüfung attestiert regelmäßig Migrationen, kritische Katalogobjekte, Korpusveröffentlichung und Workload-ACLs neu. Probes umgehen Authentifizierungs-/Host-Prüfungen, unterliegen jedoch weiterhin der Prozessraten- und Nebenläufigkeitszulassung. Ein Nicht-Loopback-Bind schlägt fehl (Fail-Closed), sofern nicht exakte Host-/HTTPS-Origin-Allowlisten und die vollständige JWT/JWKS-Konfiguration bereitgestellt werden; das öffentliche Profil erfordert bddk.read, während das Operator-Profil bddk.operator erfordert. Remote-Operator-HTTP erfordert außerdem das explizite Opt-in BDDK_OPERATOR_REMOTE_ENABLED=true. BDDK_HTTP_ALLOW_UNAUTHENTICATED ist ein unterstütztes explizites Opt-in, das einen Nicht-Loopback-öffentlichen Nur-Lese-Bind ohne Bearer-Authentifizierung bereitstellt; es ist standardmäßig nicht gesetzt, und solange es nicht gesetzt ist, bleibt der Fail-Closed-Standard unverändert. Wenn gesetzt, kann es nicht mit einer Einstellung mit BDDK_JWT_-Präfix kombiniert werden – der Start verweigert dies und nennt die betreffenden Variablen – und es wird für ein Nicht-Loopback-Operator-Profil kategorisch abgelehnt, unabhängig von BDDK_OPERATOR_REMOTE_ENABLED; Operator-Tools bleiben authentifiziert oder nur über Loopback verfügbar. Ein nicht authentifizierter Server bewirbt keine OAuth-Ermittlung: Es gibt keine WWW-Authenticate-Herausforderung, und beide Well-known-OAuth-Routen geben 404 zurück. Host-/Origin-Allowlisten sowie Body-, Nebenläufigkeits- und Ratengrenzen gelten weiterhin, und der Rate-Limiter wird zur primären Missbrauchskontrolle. Sein Client-Schlüssel wird durch BDDK_HTTP_TRUSTED_PROXY_HOPS gesteuert (Standard 0): Bei 0 verwendet der Limiter den ASGI-Socket-Peer als Schlüssel und ignoriert X-Forwarded-For vollständig; hinter n operatorkontrollierten Reverse-Proxys setzen Sie die tatsächliche Hop-Anzahl, sodass der Schlüssel der n-te Eintrag von rechts in der kombinierten Forwarded-Liste ist. Alles Unbrauchbare wird auf einen gemeinsamen unknown-Bucket zurückgestuft, anstatt auf den Socket-Peer zurückzufallen; ein falscher Wert macht den Limiter entweder gemeinsam oder spoofbar. Body-, Nebenläufigkeits- und Pro-Minute-Ratenkontrollen gelten lokal für einen Anwendungsprozess und sind keine gemeinsame Ingress-Ratenbegrenzung über Replikate hinweg. Siehe den Deployment-Leitfaden für den vollständigen Vertrag.

Der Legacy-Helfer für den Seed-Import/Export bleibt verfügbar; bevorzugen Sie bddk-mcp bootstrap für neue Bereitstellungen, da es eine Bereitschaftsvalidierung enthält:

BDDK_INGESTION_DATABASE_URL=postgresql://bddk_local_ingestion:local-only-ingestion@localhost:5432/bddk \
uv run --frozen bddk-seed import

Claude-Konfiguration

Das Repository .mcp.json ist ein portables stdio-Beispiel für .mcp.json-kompatible Clients, die es mit dem Repository-Stammverzeichnis als Arbeitsverzeichnis starten:

{
  "mcpServers": {
    "bddk": {
      "command": "uv",
      "args": ["run", "--frozen", "bddk-mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BDDK_DATABASE_URL": "${BDDK_DATABASE_URL}"
      }
    }
  }
}

Codex-Konfiguration

Codex CLI und die IDE-Erweiterung teilen sich die Codex-MCP-Konfiguration. Fügen Sie in einem vertrauenswürdigen Repository Folgendes zu ~/.codex/config.toml oder .codex/config.toml hinzu und ersetzen Sie cwd durch Ihren Checkout-Pfad:

[mcp_servers.bddk]
command = "uv"
args = ["run", "--frozen", "bddk-mcp"]
cwd = "/absolute/path/to/bddk-mcp"
env_vars = ["BDDK_DATABASE_URL"]
startup_timeout_sec = 30
tool_timeout_sec = 60

Überprüfen Sie die Verbindung mit codex mcp list oder /mcp in Codex.

Siehe docs/DEPLOYMENT.md für die Grenzen von Docker, Railway und OpenShift AI.

Beispielabfragen

search_bddk_regulations(keywords="kredilerin siniflandirilmasi")
search_document_store(query="TFRS 9 kredi riskinde onemli artis")
get_bddk_document(document_id="mevzuat_22599", page_number=1)
get_document_section(document_id="943", section_type="ilke", section_ref="5")
search_document_sections(query="Karsilik Yonetmeligi Madde 9 TFRS 9")
get_bddk_bulletin(metric_id="1.0.1", currency="TRY", days=90)
analyze_bulletin_trends(metric_id="1.0.1", lookback_weeks=12)
get_regulatory_digest(period="week")

Operator-Workflows

Führen Sie einen Dokumentqualitätsscan aus:

uv run python scripts/scan_document_quality.py --db --out-dir quality_reports --allow-failures

Dry-Run-Backfill für bekannte Qualitätsfehler:

uv run python scripts/backfill_quality_failures.py --dry-run

Extrahieren Sie ein bekanntes fehlgeschlagenes Dokument erneut:

uv run python scripts/backfill_quality_failures.py --doc-id mevzuat_21192 --execute

Erstellen Sie document_sections für vorhandene gespeicherte Dokumente mit der Ingestionsidentität neu:

BDDK_INGESTION_DATABASE_URL=postgresql://INGESTION:SECRET@HOST:5432/DB \
  uv run python scripts/reindex_document_sections.py --execute

Ausgeführte Qualitäts-Backfill-, Synchronisierungs- und Reindex-Skripte erfordern ebenfalls BDDK_INGESTION_DATABASE_URL und überprüfen den exakten bddk_ingestion-Privilegienvertrag. Führen Sie sie nicht mit dem öffentlichen oder Operator-DSN aus.

Optionale Retrieval-Telemetrie:

BDDK_DATABASE_URL=postgresql://PUBLIC:SECRET@HOST:5432/DB \
BDDK_TELEMETRY_ENABLED=true \
BDDK_TELEMETRY_DATABASE_URL=postgresql://TELEMETRY:SECRET@HOST:5432/DB \
  uv run --frozen bddk-mcp serve --profile public

Telemetrie ist standardmäßig deaktiviert. Wenn sie aktiviert ist, muss ihr eigener LOGIN nur bddk_telemetry_writer erben; beim Start wird der exakte spaltenbezogene Nur-INSERT-Vertrag überprüft, und Lese-/Änderungszugriffe auf Traces oder eine breitere Mitgliedschaft werden abgelehnt. Der Server schreibt Latenz, Ergebnisanzahlen, Dokument-IDs, Qualitätskennzeichnungen und Relevanzzusammenfassungen in tool_call_traces; Abfrage-/Prompt-Text wird als Hash und Längenzusammenfassung gespeichert. Rohtext wird nur gespeichert, wenn BDDK_TELEMETRY_STORE_TEXT=true explizit gesetzt ist.

Architektur

server.py                 Root shim → bddk_mcp/server.py
seed.py                   Root shim → bddk_mcp/ingest/seed.py
bddk_mcp/                 Main package
  server.py               FastMCP entry point and lifecycle
  core/                   configuration, DB identity, outbound HTTP, logging, models
  migrations/             Immutable global PostgreSQL migration ledger
  jobs/                   Durable operator-job models and PostgreSQL repository
  store/                  doc_store, vector_store, section_index, legal_ref
  ingest/                 client, data_sources, doc_sync, html_extractor, backfill, seed
  quality/                markdown_quality, quality_scan
  observability/          analytics, telemetry, metrics
  tools/                  MCP tool modules
  ocr/                    base, chandra (pluggable OCR)
scripts/                  Operator and backfill scripts
benchmark/                Tool schemas and benchmark infrastructure

Hinweise zur Datenqualität und -sicherheit

• Vollständige Antworten für Regulierungsdokument- und Abschnittsabrufe werden aus dem lokalen Speicher bedient; diese Pfade rufen Dokumente zur Laufzeit nicht live ab.

• Katalogaktualisierung, Institutions-/Ankündigungssuche und Bulletin-Tools können je nach Konfiguration und Cache-Zustand auf BDDK-Upstream-Dienste zugreifen.

• Live-Regulierungs-HTTP-Pfade erzwingen exakte BDDK/mevzuat-HTTPS-Hosts, Redirect-/DNS-Revalidierung und im Code festgelegte Streaming-Grenzen nach Artefakttyp; Wiederholungsprotokolle lassen URLs, Abfragezeichenfolgen und Ausnahmetexte aus. Da öffentliche Institutions-, Ankündigungs-, Bulletin- und Update-Tools ebenfalls live BDDK-Quellen aufrufen können, muss der OpenShift-Egress-Vertrag genehmigten Regulierungsquellen oder Proxys TCP 443 sowohl für öffentliche als auch für Operator-Laufzeiten gewähren, jedoch nicht für Lifecycle-Jobs. NetworkPolicy oder eine genehmigte Proxy-/Firewall-Lösung bleibt erforderlich, da die DNS-Validierung das DNS-zu-Verbindungs-Race nicht beseitigen kann.

• Das Standard-Embedding-Modell ist auf den vollständigen Commit d13f1b27baf31030b7fd040960d60d909913633f gepinnt, der optionale Standard-Reranker auf 1427fd652930e4ba29e8149678df786c240d8825, und das unveränderliche Schema akzeptiert nur vector(768). Eine Änderung der Modell-/Chunk-Einstellungen erfordert kontrolliertes vollständiges Neu-Embedding und Retrieval-Regressionstests.

• Ein Retrieval-Publikationsdatensatz wird nur geschrieben, nachdem Chunk-Integrität, der aktuelle Inhalts-Hash und das aktive Retrieval-Profil die Validierung bestanden haben; unvollständige oder veraltete Indizes werden nicht stillschweigend in Suchergebnisse gemischt.

• Bootstrap bindet das geprüfte Korpus an die exakten Artefaktpfade des Manifests und lehnt reservierte Seed-Dateinamen-Umgehungen ab. Ein separater verify-corpus-Lauf dient nur der diagnostischen Vorabprüfung; Produktions-Vertrauensgates müssen direkt an denselben bootstrap-Aufruf mit einem separat eingebundenen Vertrauensschlüssel übergeben werden. deploy/openshift-overlays/bank-bootstrap führt in der Repository-Vorabprüfung eine exakte Inventarprüfung dieses Befehls, eines schreibgeschützten genehmigten Korpus-PVC und eines separaten schreibgeschützten Korpus-Vertrauens-Secrets durch; die tatsächliche Bankbereitstellung und Job-Ausführung bleiben externe Gates.

• Migration v0005 fügt Append-Only-Freigabe-/Aktivierungsnachweise und eine Mutations-Epoche über 17 Korpus-Tabellen hinzu; strikte lokale Korpus-Aufrufe verifizieren dieselbe aktive Freigabe vor und nach der Ausführung. Migration v0008 stellt die alte Direktveröffentlichungs-Berechtigung des Publishers zurück: bddk_release_verifier liest Korpus-/Vertrauensmaterial, weist strikte Mitgliedschaft nach und legt eine Anfrage an, die an die Verifier-Revision/Bildherkunft und eine TTL von 60–3.600 Sekunden gebunden ist; bddk_release_publisher kann nur die einmalige Anfrage-ID aktivieren. Die Aktivierung prüft atomar Ablauf, Wiederverwendung, Retrieval-Bereitschaft, Korpus-Epoche und Zustands-Hash erneut. Zugriff eines einzelnen Prinzipals auf beide Rollen – oder auf Schema-Owner-Berechtigung – hebt die Trennung auf, daher bleibt die bankseitige Secret-/RBAC-Verwahrung verpflichtend. Migration v0007 erlaubt dem Publisher separat, retain-corpus-generation --expected-release-id ... auszuführen, um den exakten aktiven Zustand über 17 typisierte aufbewahrte Relationen zu versiegeln; Aufbewahrung ist kein generationsgebundenes Ausliefern oder Reaktivieren. Die Pre-v7-Behebung nicht-kanonischer Hashes bleibt eine exakte, geprüfte Nur-Veröffentlichungs-Kompatibilitätsgrenze auf dem unveränderten v5/v6-Schema; nach Erreichen von v7 darf sie auf dem Weg zu v8 keinen Dauerzustands-By-pass darstellen. Das aktuelle Binärprogramm deaktiviert die publish-corpus-release-CLI; erzeugen Sie niemals eine historische Zeile oder Bindung – befolgen Sie die genehmigte Upgrade-Behebung und schließen Sie dann die v8-Migration und -Berechtigungen ab. Das nachverfolgte Korpus ist signiert und deklariert die 9.675 Chunks, die das aktuelle Profil neu generiert. Migration v0010 lässt genau zwei Freshness-Richtlinien zu – quantified_measured_signature_verified_pass und die ausdrücklich schwächere quantified_unmeasured_signature_verified_pass – beide erfordern quantifizierte Ziele und eine verifizierte Signatur. Der Verifier leitet die Stufe aus Manifest-Nachweisen ab; --accept-unmeasured-freshness erlaubt die schwächere Stufe, kennzeichnet sie aber nie als gemessen.

• Die 11 eigentümerkontrollierten Rechtskuratierungs-Tabellen von Migration v0004 trennen Quellinhalts- und Erfassungsidentität. Mutation bleibt nur dem Eigentümer vorbehalten; v0008 gibt dem Freigabeverifizierer die exakte Nur-Lese-Ausnahme, die zur Neuberechnung von Veröffentlichungsnachweisen erforderlich ist. V0006 fügt den öffentlichen Enthaltungs-zuerst-Pfad resolve_regulation_status hinzu. Synthetische reale PostgreSQL-Nachweise begründen keine Aktualität einer echten Regulierungsfamilie.

• Das Bewertungsgate erfordert vier signierte Ebenen: gemessenes Korpus, Expertendatensatz, Rechtskuratoren-Bestätigung über das exakte Citation-Paket und einen Rechtsfreigabe-Checkpoint über die aufbewahrte Quell-/Erfassungs-/Seiten-/Auszugs-Historie. Die kanonischen Signatur-Fingerabdrücke von Korpus/Datensatz/Kurator/Freigabe müssen sich unterscheiden. Die aktuelle Vorabprüfung belegt nur kryptografische Konsistenz unter vom Operator bereitgestellten Ankern; Bankautorisierung und Modell-Score-Autorisierung bleiben falsch. Der 20-Fälle-Satz ist ein Entwurf; Schlüsselrotation, Richtlinie für benannte Prüfer und Ausführung von Expertenfällen sind noch offen.

• Die Supply-Chain-Pipeline baut Container lokal mit Buildx --provenance=false --load; sie bindet fail-closed den Manifest-Descriptor/-Digest, den Konfig-Digest, das geladene Image und die Syft-SBOM an dasselbe Image. Das Repository erstellt separat unsignierte SLSA-Herkunftsnachweise und verifiziert die Pin-Konsistenz von Modell-Manifest/Laufzeit/Dockerfile. Jedes Ergebnis, das eine ausstehende Ausnahme anwendet, ist niemals promotionsfähig; Banksignatur, Zulassung und Registry-Promotion bleiben externe Gates.

• Laufzeit-Wheels/sdists schließen seed_data, Benchmark-Code und Bereitstellungs-Assets aus; der bereitgestellte Container enthält ausdrücklich die geprüften Seed-Daten. Eine Wheel-Bereitstellung muss ein genehmigtes Korpus einbinden und --seed-dir oder BDDK_SEED_DIR an bootstrap übergeben.

• Extraktionen von geringer Qualität werden als warning oder fail markiert.

• Formellastige oder OCR-beschädigte Dokumente erfordern möglicherweise eine Prüfung des Quell-PDFs.

• get_bddk_document entfernt Daten-URIs, rohes HTML und ausgewählte OCR-Artefakte vor dem Modellkontext.

• Das Modell sollte nur anhand der Tool-Ausgabe antworten. Es sollte keine Entscheidungsnummern, Daten oder rechtlichen Schlussfolgerungen erfinden.

• Siehe docs/DOCUMENT_QUALITY.md für bekannte Extraktionsprobleme, die nachverfolgte Fehlerliste und Backfill-Befehle.

• Der OpenShift-AI-Cluster der Zielbank, der Backup-/Restore-Prozess und die Client-Matrix für Claude/Codex/GPT/GPT-OSS/LM Studio/lokale Modelle haben die Abnahmetests mit diesem Repository noch nicht abgeschlossen.

Entwicklungsbefehle

uv run pytest tests/ -v --tb=short
uv run ruff check .
uv run ruff format .

Häufig verwendete fokussierte Prüfungen in diesem Projekt:

uv run pytest tests/test_markdown_quality.py tests/test_tools_documents.py -v
uv run pytest tests/test_legal_ref.py tests/test_section_index.py tests/test_tools_sections.py -v
uv run pytest tests/test_vector_store.py tests/test_legal_ref.py -v -rs

Lizenz

Der Quellcode wird unter der MIT-Lizenz vertrieben. Regulierungsquellen-Dokumente und andere Drittanbieterdaten können separate Herkunfts- oder Wiederverwendungsbedingungen haben; die Codelizenz gewährt keine zusätzlichen Rechte an diesen Materialien. Die bestätigte Grenze, ungelöste Entscheidungen und das Freigabe-Gate sind in Lizenzierung und Herkunft festgehalten.