BDDK MCP Server

Türkçe | English | English-only operational guide

BDDK MCP Server es un servidor de Model Context Protocol offline-first para buscar, recuperar y analizar datos de regulación bancaria turca de BDDK y mevzuat.gov.tr. Combina búsqueda de catálogo, recuperación de documentos, consulta legal a nivel de sección, búsqueda semántica, análisis de boletines, controles de calidad de documentos y flujos de trabajo de backfill para operadores.

[!IMPORTANT] Este repositorio es una beta de ingeniería, no asesoramiento legal ni prueba de preparación para producción. Comience con el estado actual y el índice de documentación, revise los límites de implementación y use la política de seguridad para informes de vulnerabilidades privados. Las contribuciones siguen CONTRIBUTING.md.

Türkçe

¿Para qué sirve?

Este proyecto tiene como objetivo crear un servidor MCP seguro y trazable para las decisiones y regulaciones de BDDK. El propósito es que el modelo se base en los recursos de BDDK en el almacén de datos local, en lugar de generar respuestas a partir de su propio conocimiento. Para los límites actuales de seguridad de producción, consulte el documento de implementación.

Casos de uso principales:

• Búsqueda en el catálogo de regulaciones de BDDK

• Búsqueda semántica y de texto completo en el cuerpo de los documentos

• Recuperación de páginas específicas de documentos como Markdown

• Recuperación directa de secciones como Madde, İlke, Paragraf, Ek

• Consulta de datos de boletines bancarios semanales y mensuales

• Generación de resúmenes para cambios regulatorios, anuncios y tendencias

• Monitoreo de calidad de documentos, riesgos de OCR/fórmulas y errores de extracción

Características destacadas

• Herramientas basadas en MCP SDK: hay ejemplos de configuración de Claude/Codex para stdio y Streamable HTTP; no son un certificado de compatibilidad de cliente específico de versión.

• Recuperación de documentos offline-first: los textos y secciones regulatorios se sirven a través de PostgreSQL/pgvector; las herramientas de instituciones, anuncios y boletines pueden requerir acceso upstream.

• Separación de búsqueda de catálogo y cuerpo: search_bddk_regulations solo busca en títulos/metadatos; search_document_store realiza búsqueda semántica en el cuerpo del documento.

• Acceso por secciones: con get_document_section y search_document_sections se encuentran directamente referencias como 943 İlke 5 o mevzuat_22599 Madde 9.

• Protección de referencias legales exactas: las coincidencias léxicas como Madde 9 se conservan incluso si la puntuación semántica es baja.

• Etiquetas de calidad: las salidas de documentos se marcan con señales clean, warning, fail y banderas de calidad.

• Sanitización del contexto del documento: get_bddk_document limpia Data URIs, HTML sin procesar/artefactos de OCR y líneas largas antes de pasarlos al contexto del modelo.

• Scripts de operador: hay flujos de escaneo de calidad, backfill de calidad y reindexación de document_sections.

• PostgreSQL + pgvector: documentos, secciones, FTS y búsqueda vectorial funcionan en una sola base de datos.

Interfaz de herramientas

El perfil de proceso public predeterminado (BDDK_TOOL_PROFILE=public o bddk-mcp serve --profile public) expone solo 17 herramientas públicas.

El perfil de proceso operator separado (BDDK_TOOL_PROFILE=operator o bddk-mcp serve --profile operator) agrega 14 herramientas de operador a las 17 públicas, exponiendo un total de 31 herramientas. Este perfil requiere una BDDK_OPERATOR_DATABASE_URL separada con permisos de escritura; no recurre al DSN público.

• 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

El registro canónico de operadores para el runtime actual incluye 17 herramientas públicas y 14 de operador, es decir, 31 herramientas MCP en total. Las herramientas de operador mutantes devuelven inmediatamente un recibo de trabajo; el estado se monitorea con get_operator_job, list_operator_jobs y cancel_operator_job. Los registros de trabajos, con claves de idempotencia hash, progreso numérico y métricas de resultados limitadas, se mantienen de forma duradera en la tabla bddk_operator.operator_jobs de PostgreSQL. Un lease de admisión de trabajos a nivel de sesión evita la propiedad concurrente del mismo runner entre procesos; un bloqueo de mutación de corpus a nivel de transacción serializa las transacciones de escritura autorizadas y el publicador de versiones. Las tareas del runner siguen en el proceso del operador; los trabajos queued obsoletos no se adivinan automáticamente y la conmutación por error de múltiples réplicas no se ha validado en un entorno bancario. Por lo tanto, OpenShift starter usa una sola réplica Recreate y el sistema no debe presentarse como una cola de trabajo de grado bancario. Los esquemas de benchmark se generan a partir del mismo registro canónico de operadores; las ejecuciones de benchmark deben registrar la lista exacta de herramientas y el perfil utilizados. Ver benchmark/README.md.

Inicio rápido

Requisitos:

• Python 3.12 o 3.13

• uv

• PostgreSQL 17, pgvector y unaccent (las versiones principales no probadas en este release se rechazan con fail-closed)

• Opcional: Docker Compose

Instalación:

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

Ciclo de vida local desechable de PostgreSQL:

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 solo ejecuta la secuencia de preparación de roles/extensiones de DBA → migrate (propietario del esquema) → grants de DBA → bootstrap de ingesta en un entorno de desarrollo loopback. Los valores JWT .invalid son para que Compose analice la definición de servicio HTTP no utilizada; este comando de ciclo de vida no inicia un servidor HTTP y estos valores no son válidos para ejecutar el servidor. Las contraseñas fijas son fixtures de prueba públicas y no deben usarse en entornos remotos. En producción, bddk-mcp migrate es solo un trabajo de esquema; bddk-mcp bootstrap escribe seeds revisados, secciones y embeddings de 768 dimensiones en un esquema previamente migrado y con grants aplicados, y no ejecuta migraciones. Para identidad y secuencia completas, consulte el documento de implementación.

Para inspeccionar el alcance del corpus y los tres artefactos seed sin conexión a la base de datos, ejecute un preflight de solo lectura opcional:

uv run --frozen bddk-mcp verify-corpus

Este comando verifica checksums, tamaños, recuentos de registros y tiempos de frescura; sin embargo, no transfiere confianza a un proceso posterior. La importación de producción debe reaplicar las mismas políticas estrictas directamente en la invocación mutante de bootstrap:

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 verifica las rutas, bytes y hashes exactos definidos en corpus_scope.yml y el manifiesto antes de abrir el pool de DB; rechaza archivos documents.json, chunks.json o decision_cache.json existentes pero no definidos en el manifiesto. La clave de confianza debe provenir de un Secret/mount separado del corpus. Definir objetivos numéricos por sí solo no es medición: en el estado measured, cada documento debe tener la cadena de tiempo autoritativa de publicación → detección de fuente → descarga → extracción → publicación de recuperación, y los retrasos calculados deben estar dentro de los objetivos. El manifiesto revisado actual (bddk-job-corpus-2026-08-14) está firmado con Ed25519 y lleva objetivos numéricos (detección de 7 días, publicación de 14 días, edad del manifiesto de 180 días); el bootstrap de producción pasa con --require-quantified-freshness y --require-verified-signature. Como no hay una línea de monitoreo en vivo, slo_evidence_status: not_measured permanece, y un verificador que solicite --require-measured-freshness rechaza deliberadamente el staging en esta única puerta. Un bootstrap exitoso devuelve el ID del manifiesto sin ruta y el SHA-256 para evidencia del operador, e indica que se requiere una publicación separada. La secuencia del ciclo de vida de producción es migrate → bootstrap → verify-and-stage-corpus-release → activate-corpus-release (los grants de DBA 02_grants.sql se aplican entre migración y bootstrap). El verificador usa la identidad separada bddk_release_verifier con BDDK_RELEASE_VERIFIER_DATABASE_URL; revalida el corpus y la clave de confianza, verifica la membresía/estado/época exactos de la DB y devuelve un ID de solicitud de corta duración. La clave de confianza debe montarse por separado y tanto la ruta dada como la resuelta deben estar fuera de la raíz del corpus. BDDK_RELEASE_VERIFIER_REVISION_SHA256 debe ser un hex de 64 caracteres en minúsculas, BDDK_RELEASE_VERIFIER_IMAGE_DIGEST un digest sha256:, y BDDK_RELEASE_VERIFICATION_VALIDITY_SECONDS entre 60 y 3600 segundos (predeterminado 900). El publicador solo recibe este ID de solicitud y el valor de BDDK_RELEASE_PUBLISHER_DATABASE_URL; no recibe el PVC del corpus, el manifiesto, la firma ni la clave de confianza:

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

Si la solicitud de activación ha expirado, ya se usó o el estado/época/readiness del corpus ha cambiado, falla con fail-closed. El alias anterior publish-corpus-release está deshabilitado para mantener la separación de credenciales.

Una base de datos antigua pre-ledger es rechazada con fail-closed por una migración ordinaria. --adopt-legacy es una opción explícita solo para la forma exacta admitida, con backup verificado y el runbook de actualización de legacy; no es una bandera de instalación limpia o reparación general.

En una base de datos versión 2 completa, la migración 3 se rechaza por defecto debido al backfill de publicación de recuperación bloqueante y la validación de claves foráneas. --allow-retrieval-publication-backfill solo debe usarse en una ventana de mantenimiento controlada después de detener las cargas de trabajo, probar un backup restaurable y ensayar en un restore del mismo tamaño. BDDK_EXPECTED_DATABASE_NAME y la configuración de destino independiente de los scripts de DBA deben coincidir con la base de datos activa. Fuera del perfil Compose local aislado, los DSN de PostgreSQL deben usar sslmode=verify-full y sslrootcert absoluto.

Pruebas:

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

Ejecución de MCP stdio:

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

Transporte HTTP:

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

{"type":"text"}

Streamable HTTP MCP uç noktası http://localhost:8000/mcp olur ve sunucu durumsuz JSON yanıt modunda çalışır. Uzak uygulama, RFC 9728 korumalı kaynak meta verilerini /.well-known/oauth-protected-resource/mcp yolunda yayınlar; 401 yanıtı aynı URL'yi resource_metadata ile bildirir. Bu, uygulama düzeyinde MCP yetkilendirme keşfidir; banka IdP istemci kaydı/akış kabulünün kanıtı değildir. Sabit, içeriksiz sağlık uç noktaları GET /health/live ve GET /health/ready'dir; hazır olma durumu, geçişleri, kritik katalog nesnelerini, derlem yayınını ve iş yükü ACL'lerini periyodik olarak yeniden doğrular. Sağlık kontrolleri kimlik doğrulama/Host kontrolü dışında olsa da süreç hızı ve eşzamanlılık sınırlarına tabidir. Geri döngü dışı bağlama başarısız-kapalı davranır: kesin Host/HTTPS Origin izin listeleri ve tam JWT/JWKS ayarları zorunludur; genel profil bddk.read, operatör profili bddk.operator kapsamı ister. Uzak operatör ayrıca BDDK_OPERATOR_REMOTE_ENABLED=true ile açık bir katılım gerektirir. BDDK_HTTP_ALLOW_UNAUTHENTICATED, geri döngü dışı genel salt-okunur bağlamayı taşıyıcı kimlik doğrulaması olmadan sunmak için desteklenen açık bir katılımdır; varsayılan olarak ayarlı değildir ve ayarlı olmadığında başarısız-kapalı varsayılan değişmez. Ayarlanırsa, herhangi bir BDDK_JWT_ önekli ayarla birleştirilemez — başlangıç reddeder ve ayarlı değişkenleri adlarıyla listeler — ve geri döngü dışı operatör profili için BDDK_OPERATOR_REMOTE_ENABLED değerinden bağımsız olarak reddedilir; operatör araçları kimlik doğrulamalı veya yalnızca geri döngü olarak kalır. Kimlik doğrulamasız sunucu OAuth keşfi yayınlamaz: WWW-Authenticate sorgulaması yoktur ve her iki iyi bilinen OAuth yolu da 404 döndürür. Host/Origin izin listeleri ile gövde, eşzamanlılık ve hız sınırları uygulanmaya devam eder; bu modda hız sınırlayıcı birincil kötüye kullanım kontrolüdür. Hız sınırlayıcının istemci anahtarı BDDK_HTTP_TRUSTED_PROXY_HOPS (varsayılan 0) tarafından belirlenir: 0 iken anahtar ASGI soket eşidir ve X-Forwarded-For tamamen yok sayılır; operatörün kontrol ettiği n ters proxy arkasında gerçek atlama sayısı ayarlanır ve birleşik iletilen listenin sağdan n. girdisi anahtar olarak alınır. Kullanılamayan değerler soket eşine düşmek yerine paylaşılan unknown paketine düşer; yanlış bir değer sınırlayıcıyı paylaşılan veya sahtelenebilir yapar. Gövde, eşzamanlılık ve dakikalık hız sınırları uygulama süreci içinde uygulanır; kopyalar arasında küresel giriş sınırı sağlamaz. Ayrıntılar için dağıtım belgesine bakın.

Eski tohum içe/dışa aktarma yardımcı komutu da korunur; yeni dağıtımlarda doğrulama içeren bddk-mcp bootstrap tercih edilir:

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

Claude Yapılandırması

Depo kökündeki .mcp.json, depo kökünü çalışma dizini olarak kullanan .mcp.json uyumlu istemciler için taşınabilir bir stdio örneğidir:

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

Codex Yapılandırması

Codex CLI ve IDE uzantısı aynı Codex MCP ayarını kullanır. ~/.codex/config.toml veya güvenilen bir depo içindeki .codex/config.toml dosyasına şunu ekleyin; cwd değerini kendi kontrol kopyanızın yoluna göre değiştirin:

[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

codex mcp list veya Codex içinde /mcp ile bağlantıyı doğrulayın.

Docker, Railway ve OpenShift AI sınırları için docs/DEPLOYMENT.md belgesine bakın.

Örnek Sorgular

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")

Operatör İş Akışları

Kalite taraması:

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

Kalite sorunu olan belgeleri kuru çalıştırma:

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

Belirli bir kalite hatası belgesini yeniden çekme:

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

Mevcut belgelerden document_sections tablosunu alım kimliğiyle yeniden oluşturma:

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

Yürütme yapan kalite geri doldurma, senkronizasyon ve yeniden dizinleme betikleri de BDDK_INGESTION_DATABASE_URL ister ve kesin bddk_ingestion ayrıcalık sözleşmesini doğrular; genel veya operatör DSN'siyle çalıştırılmamalıdır.

İsteğe bağlı alım telemetrisi:

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

Telemetri varsayılan olarak kapalıdır. Açıldığında, ayrı GİRİŞ yalnızca bddk_telemetry_writer rolünü devralmalıdır; başlangıç, sütun kapsamlı INSERT-only yetkisini doğrular ve izleme okuma/değiştirme veya geniş üyeliği reddeder. tool_call_traces tablosuna gecikme, sonuç sayısı, belge kimliği, kalite etiketi ve alaka özeti yazar; sorgu/istem metni karma/uzunluk özeti olarak saklanır. Ham metin yalnızca BDDK_TELEMETRY_STORE_TEXT=true açıkça ayarlanırsa yazılır.

Mimari

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ı

Veri Kalitesi ve Güvenlik Notları

• Tam düzenleme belgesi ve bölüm alma yanıtları yerel depodan gelir; bu iki akış çalışma zamanında belge canlı getirme yapmaz.

• Katalog önbellek yenileme, kurum/duyuru araması ve bülten araçları, yapılandırmaya ve önbellek durumuna göre BDDK üst hizmetlerine erişebilir.

• Canlı düzenleyici HTTP yolları, kesin BDDK/mevzuat HTTPS ana bilgisayarlarını, yönlendirme/DNS yeniden doğrulamasını ve yapı türüne göre koda ait akış sınırlarını uygular; URL/sorgu/istisna metni yeniden deneme günlüklerine yazılmaz. Genel kurum/duyuru/bülten/güncelleme araçları da canlı BDDK erişimi yapabildiğinden, OpenShift egress sözleşmesi hem genel hem operatör çalışma zamanına yalnızca onaylı düzenleyici kaynak veya proxy için TCP 443 vermelidir; yaşam döngüsü İşlerine bu erişim verilmemelidir. DNS-bağlantı yarışı nedeniyle Ağ İlkesi veya onaylı proxy/güvenlik duvarı zorunludur.

• Varsayılan gömme modeli tam işleme d13f1b27baf31030b7fd040960d60d909913633f, isteğe bağlı varsayılan yeniden sıralayıcı 1427fd652930e4ba29e8149678df786c240d8825 ile sabitlenmiştir; değişmez şema yalnızca vector(768) kabul eder. Model/parça ayarı değişikliği kontrollü tam yeniden gömme ve alma gerilemesi gerektirir.

• Alma yayın kaydı yalnızca parça bütünlüğü, güncel içerik karması ve etkin alma profili doğrulandıktan sonra yazılır; eksik veya bayat dizin arama sonuçlarına sessizce karışmaz.

• Bootstrap, incelenen derlemi bildirimin kesin yapı yollarına bağlar ve ayrılmış tohum dosya adı atlamasını reddeder. Ayrı verify-corpus çalıştırması yalnızca tanısal ön kontrol amaçlıdır; üretim güvenlik kapıları doğrudan aynı bootstrap komutuna ve ayrı olarak bağlanan güven anahtarına verilmelidir. deploy/openshift-overlays/bank-bootstrap bu kesin komutu, salt-okunur onaylı-derlem PVC'sini ve ayrı salt-okunur derlem-güven Secret'ını depo ön kontrolünde doğrular; gerçek banka PVC/Secret sağlama ve İş çalıştırması hâlâ dış kapıdır.

• v0005, ekle-only yayın/etkinleştirme ve 17 derlem tablosunu kapsayan mutasyon dönemini ekler; katı yerel-derlem çağrıları aynı etkin yayını çağrı öncesi/sonrası doğrular. v0008 bunun eski doğrudan yayın yetkisini yayıncıdan kaldırır: bddk_release_verifier derlem/güven materyalini okur ve katı üyeliği kanıtlar ve doğrulayıcı revizyonu/görüntü özeti ile 60–3.600 saniyelik TTL'ye bağlı isteği aşamalandırır; bddk_release_publisher yalnızca tek kullanımlık istek kimliğiyle etkinleştirme yapabilir. Etkinleştirme süresi dolumu, yeniden kullanım, alma hazırlığı, derlem dönemi ve durum karması atomik olarak yeniden kontrol edilir. Her iki role veya şema sahibi yetkisine aynı asılın erişimi ayrımı bozar; banka Secret/RBAC emaneti bunu önlemelidir. v0007 ayrıca retain-corpus-generation --expected-release-id ... ile kesin etkin durumu 17 tür ilişkisine kopyalayıp mühürler; saklanan nesil sunma/yeniden etkinleştirme değildir. v7 öncesi kanonik olmayan karma düzeltmesi yalnızca değişmeden kalan v5/v6 şemasında kesin, incelenmiş yayın-only uyumluluk sınırıdır; v7'ye geçtikten sonra v8'e geçiş için doğrudan yol kararlı durum olarak kullanılmamalıdır. Geçerli ikilinin publish-corpus-release CLI'ı devre dışıdır; tarihsel satır/bağlama üretmeyin, onaylı yükseltme düzeltmesini uygulayın ve v8 geçişini ve izinlerini tamamlayın. İzlenen derlem imzalıdır ve güncel profilin ürettiği 9.675 parçayı bildirir. v0010 yayın defterinde tam olarak iki tazelik ilkesi kabul eder: quantified_measured_signature_verified_pass ve daha zayıf olan quantified_unmeasured_signature_verified_pass; her ikisi de sayısal hedef ve doğrulanmış imza ister. Doğrulayıcı seviyeyi bildirim kanıtından türetir, --accept-unmeasured-freshness yalnızca zayıf seviyeye izin verir, onu ölçülmüş olarak etiketleyemez.

• v0004'ün 11 sahip kontrollü yasal düzenleme tablosu SourceBlob içerik kimliğini SourceArtifact edinme kimliğinden ayırır. Mutasyon yetkisi yalnızca sahibindedir; v0008 yayın doğrulayıcısına yayın kanıtını yeniden hesaplamak için kesin salt-okunur istisna verir. v0006 genel resolve_regulation_status işlevini/aracını çakışma veya eksik kanıtta çekimser kalacak şekilde ekler. Sentetik gerçek PostgreSQL kanıtı gerçek düzenleme ailesi/güncellik kanıtı değildir.

• Değerlendirme kapısı dört imzalı katman ister: ölçülmüş derlem, uzman veri kümesi, kesin Alıntı paketi için yasal düzenleyici onayı ve saklanan kaynak/edinme/sayfa/alıntı zincirini bağlayan yasal yayın kontrol noktası. Kanonik derlem/veri kümesi/düzenleyici/yayın imza parmak izleri ayrı olmalıdır. Mevcut ön kontrol yalnızca operatör tarafından sağlanan çapalar altında şifreleme tutarlılığını kanıtlar; banka yetkilendirmesi ve model puanı yetkilendirmesi her zaman yanlıştır. İzlenen 20 vaka veri kümesi taslaktır; anahtar döndürme, adlandırılmış inceleyici ilkesi ve uzman vaka yürütmesi henüz yoktur.

• Tedarik zinciri şerit kapsayıcıları Buildx --provenance=false --load ile yerel olarak üretir; bildirim tanımlayıcısı/özeti, yapılandırma özeti, yüklenen görüntü ve Syft SBOM aynı görüntüye başarısız-kapalı bağlanır. Depo ayrıca imzasız SLSA kanıtı üretir ve model bildirimi/çalışma zamanı/Dockerfile sabitlemelerinin uyumunu doğrular. Bekleyen istisna kullanılan sonuç hiçbir zaman yükseltme uygun değildir; banka imzalama, kabul ve kayıt defteri yükseltmesi yine dış kapıdır.

• Çalışma zamanı tekerlek/sdist seed_data, kıyaslama ve dağıtım varlıklarını içermez; sağlanan kapsayıcı incelenen tohumu açıkça içerir. Tekerlek kurulumu onaylı derlem bağlamalı ve bootstrap'a --seed-dir veya BDDK_SEED_DIR vermelidir.

• Düşük kaliteli çıkarma çıktıları warning veya fail olarak işaretlenir.

• Formül ağır veya OCR bozuk belgelerde kaynak PDF incelemesi gerekebilir.

• get_bddk_document yanıtlarında veri URI'leri, ham HTML ve bazı OCR yapıları temizlenir.

• Model yanıt verirken yalnızca araç çıktısına dayanmalıdır; karar numarası, tarih veya hukuki sonuç uydurulmamalıdır.

• Bilinen çıkarma sorunları, başarısız belge listesi ve geri doldurma komutları için docs/DOCUMENT_QUALITY.md sayfasına bakın.

• Bankanın OpenShift AI kümesi, yedekleme/geri yükleme akışı ve Claude/Codex/GPT/GPT-OSS/LM Studio/yerel model istemci matrisi henüz bu depoyla kabul testinden geçmemiştir.

Related MCP server: tr-eli-mcp

Español

¿Qué es esto?

El servidor BDDK MCP tiene como objetivo proporcionar una interfaz segura y auditable del Protocolo de Contexto de Modelo (MCP) para los datos de regulación bancaria turca. Está diseñado para fundamentar las respuestas del LLM en datos locales de BDDK en lugar de depender del conocimiento previo del modelo. Consulte la guía de implementación para conocer los límites actuales de seguridad en producción.

Casos de uso comunes:

• Buscar en el catálogo de regulaciones de BDDK

• Buscar dentro de los cuerpos de los documentos con recuperación semántica y de texto completo

• Recuperar documentos Markdown paginados

• Recuperar secciones legales exactas como Madde, Ilke, Paragraf y Ek

• Consultar datos de boletines bancarios semanales y mensuales

• Producir resúmenes regulatorios y resúmenes de tendencias

• Supervisar la calidad de los documentos, el riesgo de OCR/fórmulas y los fallos de extracción

Aspectos destacados

• Superficie de herramientas del SDK MCP: se proporcionan ejemplos de stdio y HTTP Streamable para Claude/Codex; los ejemplos no son certificación de compatibilidad específica de una versión.

• Recuperación de documentos offline-first: el texto de las regulaciones y sus secciones se sirven desde PostgreSQL/pgvector; las herramientas de instituciones, anuncios y boletines pueden requerir acceso upstream.

• Separación catálogo/cuerpo: search_bddk_regulations busca metadatos; search_document_store busca en los cuerpos de los documentos.

• Recuperación a nivel de sección: get_document_section y search_document_sections admiten referencias como 943 Ilke 5 y mevzuat_22599 Madde 9.

• Preservación exacta de referencias legales: las coincidencias léxicas como Madde 9 sobreviven al filtrado denso de relevancia.

• Etiquetas de calidad: las salidas de documentos incluyen metadatos y banderas de calidad clean, warning o fail.

• Saneamiento del contexto del documento: get_bddk_document elimina data URIs, artefactos de HTML/OCR sin procesar y líneas patológicamente largas antes del contexto del modelo.

• Scripts de operador: se incluyen flujos de trabajo de escaneo de calidad, backfill de calidad y reindexado de document_sections.

• PostgreSQL + pgvector: documentos, secciones, FTS y búsqueda vectorial comparten una única base de datos.

Superficie de herramientas

El perfil de proceso public predeterminado (BDDK_TOOL_PROFILE=public o bddk-mcp serve --profile public) expone solo 17 herramientas públicas.

El perfil de proceso operator separado (BDDK_TOOL_PROFILE=operator o bddk-mcp serve --profile operator) añade 14 herramientas de operador a las 17 herramientas públicas y expone 31 herramientas en total. Requiere una BDDK_OPERATOR_DATABASE_URL separada con capacidad de escritura y nunca recurre al DSN público.

• 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

El registro canónico de operador contiene 17 herramientas públicas más 14 herramientas de operador, o 31 herramientas MCP en total. Las herramientas de operador que mutan devuelven un recibo de trabajo inmediato; use get_operator_job, list_operator_jobs y cancel_operator_job para observarlas. Los registros de trabajo, las claves de idempotencia con hash, el progreso numérico y las métricas de resultado acotadas son persistentes en la tabla PostgreSQL bddk_operator.operator_jobs. Una concesión de admisión de trabajos con ámbito de sesión impide la propiedad concurrente del mismo runner entre procesos; un bloqueo de mutación del corpus con ámbito de transacción serializa las transacciones de escritura autorizadas y el publicador de lanzamientos. Las tareas del runner siguen residiendo en el proceso de operador, el trabajo obsoleto queued nunca se adivina automáticamente, y la conmutación por error multi-réplica no ha sido aceptada en un entorno bancario. El starter de OpenShift usa por tanto una réplica Recreate, y esto no se representa como una cola de flujo de trabajo de grado bancario. Los esquemas de benchmark se exportan desde el mismo registro canónico de operador; las ejecuciones de benchmark deben seguir registrando la lista exacta de herramientas y el perfil que usaron. Véase benchmark/README.md.

Inicio rápido

Requisitos:

• Python 3.12 o 3.13

• uv

• PostgreSQL 17 con pgvector y unaccent (esta versión falla en modo cerrado en versiones principales no probadas)

• Opcional: Docker Compose

Instalación:

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

Ciclo de vida desechable de PostgreSQL local:

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

Solo para desarrollo de loopback, Compose ejecuta la configuración de rol/extensiones de DBA → migrate del propietario del esquema → concesiones de DBA → bootstrap de ingesta. Los valores JWT reservados .invalid solo permiten que Compose analice una definición de servicio HTTP no utilizada; este objetivo de ciclo de vida no inicia ningún servidor HTTP, y esos valores no son configuración de servidor válida. Sus contraseñas fijas son fixtures de prueba públicas y no deben copiarse de forma remota. En producción, bddk-mcp migrate solo realiza trabajo de esquema. bddk-mcp bootstrap requiere un esquema ya migrado y con concesiones, y luego importa la semilla revisada, las secciones y los embeddings de 768 dimensiones; no migra. Véase la guía de despliegue para conocer la identidad completa y el orden de aplicación.

Use la comprobación previa opcional de solo lectura para inspeccionar la declaración del corpus y los tres artefactos de semilla sin abrir una conexión de base de datos:

uv run --frozen bddk-mcp verify-corpus

El comando comprueba sumas de verificación, tamaños, recuentos de registros y marcas de tiempo de frescura, pero no transfiere la confianza a un proceso posterior. La importación de producción debe volver a aplicar las políticas estrictas directamente en la invocación mutante de bootstrap:

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

Antes de abrir un pool de base de datos, bootstrap valida el corpus_scope.yml exacto y las rutas, bytes y hashes de los artefactos declarados en el manifiesto; rechaza un documents.json, chunks.json o decision_cache.json presente pero no declarado. Proporcione la clave de confianza desde un Secret/mount separado del corpus. Declarar objetivos numéricos no es medición: el estado measured requiere una línea temporal por documento de publicación autoritativa → detección de fuente → descarga → extracción → publicación de recuperación y retrasos calculados dentro de esos objetivos. El manifiesto revisado actual no está firmado, no tiene objetivos numéricos y se trata como slo_evidence_status: not_measured; falla intencionadamente en este bootstrap de producción. La salida correcta de bootstrap incluye el ID de manifiesto sin ruta y el SHA-256 como evidencia para el operador y marca la publicación como requerida; no persiste un candidato. El ciclo de vida de producción es migrate → bootstrap → verify-and-stage-corpus-release → activate-corpus-release (el DBA aplica 02_grants.sql entre la migración y el bootstrap). El verificador usa una identidad distinta bddk_release_verifier y BDDK_RELEASE_VERIFIER_DATABASE_URL; revalida el corpus y la clave de confianza, comprueba la pertenencia/estado/época exactos de la base de datos y devuelve un ID de solicitud de corta duración. La clave de confianza debe ser un mount separado cuyas rutas proporcionada y resuelta permanezcan ambas fuera de la raíz del corpus. BDDK_RELEASE_VERIFIER_REVISION_SHA256 debe tener 64 caracteres hexadecimales en minúsculas, BDDK_RELEASE_VERIFIER_IMAGE_DIGEST debe ser un digest sha256:, y BDDK_RELEASE_VERIFICATION_VALIDITY_SECONDS está limitado a 60–3.600 segundos (por defecto 900). El publicador recibe solo ese ID de solicitud y BDDK_RELEASE_PUBLISHER_DATABASE_URL —sin PVC del corpus, manifiesto, firma ni clave de confianza:

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

La activación falla en modo cerrado si la solicitud expiró, ya se usó, o cambiaron el estado, la época o la disponibilidad del corpus. El antiguo alias publish-corpus-release está deshabilitado para preservar la separación de credenciales.

La migración ordinaria falla en modo cerrado en una base de datos no gestionada anterior al libro mayor. --adopt-legacy es una opción explícita solo para la forma admitida exacta después de una copia de seguridad probada y el runbook de actualización heredada; no es una bandera de instalación limpia ni de reparación general.

Una base de datos version-2 poblada también rechaza la migración 3 por defecto porque el backfill de publicación de recuperación toma bloqueos bloqueantes y valida claves foráneas. Use --allow-retrieval-publication-backfill solo en una ventana de mantenimiento controlada después de detener las cargas de trabajo, probar una copia de seguridad restaurable y ensayar una restauración de tamaño equivalente. BDDK_EXPECTED_DATABASE_NAME y el objetivo independiente del script de DBA deben coincidir con la base de datos activa. Fuera de Compose local aislado, los DSN de PostgreSQL deben usar sslmode=verify-full y una ruta absoluta de sslrootcert.

Pruebas:

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

Ejecute MCP sobre stdio:

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

Ejecute HTTP streamable:

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

El endpoint MCP HTTP streamable es http://localhost:8000/mcp, configurado para respuestas JSON sin estado. La aplicación remota publica metadatos de recurso protegido RFC 9728 en /.well-known/oauth-protected-resource/mcp, y su desafío 401 identifica la misma URL a través de resource_metadata. Esto es descubrimiento de autorización MCP a nivel de aplicación, no una prueba de registro de cliente IdP bancario ni de aceptación del flujo. Los endpoints de sondeo fijos y sin contenido son GET /health/live y GET /health/ready; la disponibilidad vuelve a atestiguar periódicamente las migraciones, los objetos críticos del catálogo, la publicación del corpus y las ACL de las cargas de trabajo. Los sondeos omiten la autenticación y las comprobaciones de Host, pero siguen sujetos a la tasa de proceso y a la admisión de concurrencia. Un bind que no sea de loopback falla en modo cerrado a menos que se proporcionen listas permitidas exactas de Host/HTTPS Origin y la configuración completa de JWT/JWKS; el perfil público requiere bddk.read, mientras que el perfil de operador requiere bddk.operator. El HTTP de operador remoto también requiere la aceptación explícita BDDK_OPERATOR_REMOTE_ENABLED=true. BDDK_HTTP_ALLOW_UNAUTHENTICATED es una aceptación explícita admitida que sirve un bind público de solo lectura no loopback sin autenticación de portador; no está establecida por defecto y, mientras no lo esté, el valor predeterminado de fallo en modo cerrado no cambia. Cuando se establece, no puede combinarse con ningún ajuste con prefijo BDDK_JWT_ — el arranque lo rechaza y nombra las variables infractoras — y se rechaza directamente para un perfil de operador no loopback independientemente de BDDK_OPERATOR_REMOTE_ENABLED; las herramientas de operador permanecen autenticadas o solo loopback. Un servidor no autenticado no anuncia descubrimiento OAuth: no hay desafío WWW-Authenticate, y ambas rutas OAuth well-known devuelven 404. Las listas permitidas de Host/Origin, junto con los límites de cuerpo, concurrencia y tasa, siguen aplicándose, y el limitador de tasa se convierte en el control principal contra abusos. Su clave de cliente se rige por BDDK_HTTP_TRUSTED_PROXY_HOPS (por defecto 0): en 0, el limitador usa como clave el peer del socket ASGI e ignora X-Forwarded-For por completo; detrás de n proxies inversos controlados por el operador, establezca el número real de saltos para que la clave sea la entrada n-ésima desde la derecha de la lista combinada de reenvío. Cualquier cosa no utilizable degrada a un bucket compartido unknown en lugar de recurrir al peer del socket; un valor incorrecto hace que el limitador sea compartido o suplantable. Los controles de cuerpo, concurrencia y tasa por minuto son locales a un proceso de aplicación y no son un límite de tasa de entrada compartido entre réplicas. Véase la guía de despliegue para conocer el contrato completo.

El helper de importación/exportación de semilla heredado sigue disponible; prefiera bddk-mcp bootstrap para nuevos despliegues porque incluye validación de disponibilidad:

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

Configuración de Claude

El .mcp.json del repositorio es un ejemplo stdio portátil para clientes compatibles con .mcp.json que lo lanzan con la raíz del repositorio como directorio de trabajo:

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

Configuración de Codex

Codex CLI y la extensión de IDE comparten la configuración de Codex MCP. Añada lo siguiente a ~/.codex/config.toml o .codex/config.toml en un repositorio de confianza, reemplazando cwd con la ruta de su checkout:

[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

Verifique la conexión con codex mcp list o /mcp dentro de Codex.

Véase docs/DEPLOYMENT.md para los límites de Docker, Railway y OpenShift AI.

Consultas de ejemplo

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")

Flujos de trabajo de operador

Ejecute un escaneo de calidad de documentos:

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

Backfill en seco para fallos de calidad conocidos:

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

Vuelva a extraer un documento con fallo conocido:

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

Reconstruya document_sections para los documentos almacenados existentes con la identidad de ingesta:

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

Los scripts de relleno de calidad, sincronización y reindexación ejecutados también requieren BDDK_INGESTION_DATABASE_URL y verifican el contrato de privilegios exacto de bddk_ingestion. No los ejecute con el DSN público o de operador.

Telemetría de recuperación opcional:

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

La telemetría está deshabilitada por defecto. Cuando está habilitada, su LOGIN distinto debe heredar solo bddk_telemetry_writer; el arranque verifica el contrato exacto de solo inserción con ámbito de columna y rechaza lecturas/cambios de trazas o una membresía más amplia. El servidor escribe latencia, recuentos de resultados, IDs de documento, etiquetas de calidad y resúmenes de relevancia en tool_call_traces; el texto de consulta/solicitud se almacena como un resumen de hash y longitud. El texto sin procesar solo se almacena cuando se establece explícitamente BDDK_TELEMETRY_STORE_TEXT=true.

Arquitectura

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

Notas de Calidad y Seguridad de Datos

• Las respuestas completas de recuperación de documentos normativos y secciones se sirven desde el almacén local; esas rutas no obtienen documentos en vivo en tiempo de ejecución.

• La actualización del catálogo, la búsqueda de instituciones/anuncios y las herramientas de boletines pueden acceder a los servicios ascendentes de BDDK según la configuración y el estado de la caché.

• Las rutas HTTP normativas en vivo aplican hosts HTTPS exactos de BDDK/mevzuat, revalidación de redirección/DNS y límites de transmisión propiedad del código por tipo de artefacto; los registros de reintento omiten URL, cadenas de consulta y texto de excepción. Debido a que las herramientas de instituciones públicas, anuncios, boletines y actualizaciones también pueden llamar a fuentes BDDK en vivo, el contrato de salida de OpenShift debe otorgar TCP 443 a fuentes reguladoras aprobadas o proxy tanto a los tiempos de ejecución públicos como a los de operador, pero no a los trabajos de ciclo de vida. NetworkPolicy o un proxy/cortafuegos aprobado sigue siendo necesario porque la validación de DNS no puede eliminar la carrera de DNS a conexión.

• El modelo de incrustación predeterminado está fijado al commit completo d13f1b27baf31030b7fd040960d60d909913633f, el reordenador predeterminado opcional a 1427fd652930e4ba29e8149678df786c240d8825, y el esquema inmutable solo acepta vector(768). Un cambio en la configuración del modelo/fragmento requiere una reincrustación completa controlada y pruebas de regresión de recuperación.

• Un registro de publicación de recuperación se escribe solo después de que la integridad del fragmento, el hash de contenido actual y el perfil de recuperación activo pasen la validación; los índices incompletos o desactualizados no se mezclan silenciosamente en los resultados de búsqueda.

• El arranque vincula el corpus revisado a las rutas de artefactos exactas del manifiesto y rechaza las derivaciones reservadas de nombres de archivo semilla. Una ejecución separada de verify-corpus es solo de diagnóstico previo; las puertas de confianza de producción deben pasarse directamente a la misma invocación de bootstrap con una clave de confianza montada por separado. deploy/openshift-overlays/bank-bootstrap verifica el inventario exacto de ese comando, un PVC de corpus aprobado de solo lectura y un Secreto de confianza de corpus de solo lectura separado en la verificación previa del repositorio; el aprovisionamiento real del banco y la ejecución de trabajos siguen siendo puertas externas.

• La migración v0005 añade evidencia de liberación/activación de solo añadidura y una época de mutación en 17 tablas de corpus; las llamadas estrictas al corpus local verifican la misma liberación activa antes y después de la ejecución. La migración v0008 retira la antigua concesión de publicación directa del editor: bddk_release_verifier lee material de corpus/confianza, demuestra membresía estricta y prepara una solicitud vinculada a la revisión del verificador/procedencia de la imagen y un TTL de 60 a 3.600 segundos; bddk_release_publisher solo puede activar el ID de solicitud de un solo uso. La activación vuelve a comprobar atómicamente la caducidad, la reutilización, la preparación de la recuperación, la época del corpus y el hash de estado. El acceso de un principal a ambos roles—o a la autoridad de propietario del esquema—colapsa la separación, por lo que la custodia de Secret/RBAC del banco sigue siendo obligatoria. La migración v0007 permite por separado al editor ejecutar retain-corpus-generation --expected-release-id ... para sellar el estado activo exacto en 17 relaciones retenidas tipadas; la retención no es servicio ni reactivación vinculada a la generación. La corrección de hash no canónico anterior a la v7 sigue siendo un límite de compatibilidad exacto y revisado solo de publicación en el esquema v5/v6 sin cambios; después de alcanzar la v7 no debe convertirse en una derivación de estado estacionario en el camino a la v8. El binario actual deshabilita la CLI publish-corpus-release; nunca fabrique una fila o enlace histórico—siga la corrección de actualización aprobada y luego complete la migración y las concesiones de la v8. El corpus rastreado está firmado y declara los 9.675 fragmentos que el perfil actual regenera. La migración v0010 admite exactamente dos políticas de frescura—quantified_measured_signature_verified_pass y la explícitamente más débil quantified_unmeasured_signature_verified_pass—ambas requieren objetivos cuantificados y una firma verificada. El verificador deriva el nivel de la evidencia del manifiesto; --accept-unmeasured-freshness permite el nivel más débil pero nunca lo vuelve a etiquetar como medido.

• Las 11 tablas de curación legal controladas por el propietario de la migración v0004 separan el contenido fuente y la identidad de adquisición. La mutación sigue siendo solo del propietario; la v0008 otorga al verificador de liberación la excepción de solo lectura exacta necesaria para recalcular la evidencia de publicación. La v0006 añade la ruta pública de abstención primero resolve_regulation_status. La evidencia sintética de PostgreSQL real no establece la actualidad de una familia de regulación real.

• La puerta de evaluación requiere cuatro capas firmadas: corpus medido, conjunto de datos de expertos, atestación del curador legal sobre el paquete de citas exacto y un punto de control de liberación legal sobre el historial retenido de fuente/adquisición/página/extracto. Las huellas digitales canónicas del firmante de corpus/conjunto de datos/editor/liberación deben diferir. La verificación previa actual demuestra solo consistencia criptográfica bajo anclas proporcionadas por el operador; la autorización del banco y la autorización de puntuación del modelo siguen siendo falsas. El conjunto de 20 casos es un borrador, y la rotación de claves, la política de revisores designados y la ejecución de casos de expertos siguen abiertas.

• El carril de la cadena de suministro construye contenedores localmente con Buildx --provenance=false --load; vincula de forma segura el descriptor/digesto del manifiesto, el resumen de configuración, la imagen cargada y el SBOM de Syft a la misma imagen. El repositorio crea por separado procedencia SLSA sin firmar y verifica la consistencia de fijación del manifiesto/tiempo de ejecución/Dockerfile del modelo. Cualquier resultado que aplique una excepción pendiente nunca es elegible para promoción; la firma del banco, la admisión y la promoción del registro siguen siendo puertas externas.

• Las ruedas/sdists de tiempo de ejecución excluyen seed_data, el código de referencia y los activos de implementación; el contenedor proporcionado incluye explícitamente la semilla revisada. Una implementación de rueda debe montar un corpus aprobado y pasar --seed-dir o BDDK_SEED_DIR al arranque.

• Las extracciones de baja calidad se marcan como warning o fail.

• Los documentos con muchas fórmulas o corruptos por OCR pueden requerir revisión del PDF fuente.

• get_bddk_document elimina los URI de datos, el HTML sin procesar y los artefactos OCR seleccionados antes del contexto del modelo.

• El modelo solo debe responder a partir de la salida de la herramienta. No debe inventar números de decisión, fechas ni conclusiones legales.

• Consulte docs/DOCUMENT_QUALITY.md para conocer los problemas de extracción conocidos, la lista de fallos rastreada y los comandos de relleno.

• El clúster de OpenShift AI del banco objetivo, el proceso de copia de seguridad/restauración y la matriz de clientes de Claude/Codex/GPT/GPT-OSS/LM Studio/modelo local aún no han completado las pruebas de aceptación con este repositorio.

Comandos de Desarrollo

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

Comprobaciones específicas utilizadas a menudo en este proyecto:

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

Licencia

El código fuente se distribuye bajo la Licencia MIT. Los documentos de fuentes reguladoras y otros datos de terceros pueden tener condiciones de procedencia o reutilización separadas; la licencia del código no otorga derechos adicionales sobre esos materiales. El límite confirmado, las decisiones no resueltas y la puerta de liberación se registran en Licencias y Procedencia.