sicop_mcp

SICOP-Datenserver (öffentliche Beschaffung in Costa Rica, offene Daten 2020-2026) als API REST und als MCP-Server für KI-Assistenten bereitgestellt.

• Daten: Salidas/ des SICOP-Pakets (~4,3 Mio. Zeilen in Postgres in 31 Tabellen geladen: 13 Datensätze pro Jahr 2020-2026 + 18 abgeleitete Gold-Tabellen).

• Stack: Django 6 + DRF + Celery + Postgres + Redis. Gleiches Muster wie mwt/consola-mwt-one.

• Domänenregel: Jede Geschäftszahl eines Anbieters deklariert ihre Messstufe (Erfassung = Zuschläge · Ausführung = Bestellungen · Lieferung = Empfänge).

Lokaler Start

Erfordert: Python 3.12+ (getestet mit 3.14), lokales PostgreSQL 16/18, Redis (oder den von dir verwendeten Broker).

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# crear DB (una vez):
#   createuser -U postgres sicop -P
#   createdb -U postgres -O sicop sicop

python manage.py migrate
python manage.py load_sicop --sync     # carga los CSV de Salidas/ (SICOP_DATA_DIR en .env)
python manage.py runserver 127.0.0.1:8000

Daten über Celery laden (Stack-Muster)

celery -A config worker -l info        # worker
python manage.py load_sicop            # encola una tarea por archivo
python manage.py load_sicop --only contratos --force

MCP-Server

python -m sicop.mcp_server                            # stdio (para clientes MCP)
python -m sicop.mcp_server streamable-http --port 9010  # HTTP

Tools MCP (18): sicop_ficha_proveedor (Ausführung vs. Erfassung), sicop_mercado_familia, sicop_competencia_procedimiento, sicop_producto, sicop_producto_historia (Preisreihe pro Jahr), sicop_cara_a_cara (zwei Anbieter), sicop_expediente, sicop_adjudicaciones, sicop_carteles_objetados, sicop_representantes, sicop_representante_competencia, sicop_excepciones, sicop_sanciones, sicop_precios_institucion, sicop_perdidas_baratas (bot am günstigsten und verlor), sicop_campo_buscar, sicop_regimen_evaluacion, sicop_resumen.

Jede Geschäftsantwort trägt den Umschlag (Envelope des Plans §5.4): nivel_medicion, cobertura_cruce (0.626), moneda und caveats.

REST-API

Gleichheitsfilter mit exaktem Spaltennamen (CEDULA_PROVEEDOR, NRO_SICOP, ANO, ...) und ?search= in den Ressourcen mit Text.

Related MCP server: chile-procurement

PHASE 2 — täglicher Zyklus (cron 06:00)

python manage.py ciclo_diario               # corrida manual del ciclo
celery -A config worker -l info             # worker (ya en tu stack)
celery -A config beat -l info               # cron: ciclo-diario 06:00 · vigilancia 06:05 · consolidar 06:15

• Täglicher Zyklus: Überwachung der Neufassung (aktueller Monat + 3 abgeschlossene + 2 rotierende) → offene Ergebnisse konsolidieren → Signale der Watchlist → priorisierte Warteschlange → Gold + Tests-Gate.

• resultado_decision (SCH_RESULTADO v1, /api/v1/resultados/, POST /api/v1/resultado-registrar/): Granularität (nro_sicop, nro_linea, decision_id), append-only, obligatorischer eingefrorener Kontext (build_id/snapshot_ts/modelo_version/features_hash), override als Schlüsselfeld.

• Signale (/api/v1/senales/): cliente_participa/adjudicado/perdio, cartel_objetado, sancion_nueva, institucion_vigilada, perdio_por_poco (watchlist.json).

• Überwachung (/api/v1/vigilancia/): ETag/Content-Length der Zielmonate vs. ctl_mes_fuente.

Tools MCP: sicop_registrar_resultado, sicop_resultado, sicop_senales, sicop_vigilancia, sicop_ciclo_diario, sicop_consolidar_resultados.

PHASE 3 — physische Durchsetzung + zwei Fahrspuren + Protokollierung

• Durchsetzung (/api/v1/politica/): Middleware, die jede Anfrage mit rohen Pfaden (/salidas/, .csv, .zip, file://, ..\) oder Geheimnissen mit 403 blockiert; Richtlinientests (kein freies SQL, keine Währungsmischung, keine rohen Pfade) → 5/5 PASS.

• Zwei Fahrspuren: SICOP_CARRIL=operacion (kanonisch) oder SICOP_CARRIL=laboratorio (jede Antwort mit NO_APTO_PARA_DECISION, decision_eligible:false gekennzeichnet). Die Labor-Fahrspur fügt das Tool sicop_lab_sql hinzu (SQL read-only, nur SELECT/WITH, max. 200 Zeilen, lehnt DELETE ab).

• Antwortprotokollierung (/api/v1/registro/, Tool sicop_registro): Jeder MCP-Aufruf und jede API-Anfrage wird in registro_respuesta gespeichert (Agent, Tool, Parameter, build_id, Anzahl, Fahrspur, Dauer, Status).

PHASE 4 — Test (ESOSA-Datenblatt, Backtest, Holdout) + offene Punkte P1-P11

python manage.py fase4 --json        # ficha ESOSA desde gold + backtest + holdout (gate de muerte)
python manage.py pendientes --json   # P1-P7

• ESOSA-Datenblatt (/api/v1/prueba-fase4/?solo=ficha, Tool sicop_ficha_esosa): aus der kanonischen Schicht reproduziert — EXAKTE Leistung (98,6% / 577 Zeilen), Erfassung reproduziert das Muster (Spitze 2022, Zusammenbruch 2023), Wettbewerb/Gegenüberstellung auf die Kreuzabdeckung (62,6%) beschränkt, bis die Wiederherstellung geladen ist.

• Backtest (Tool sicop_backtest_invitaciones): Wiedergabe vergangener Einladungen (notwendiger Rabatt zum Gewinnen).

• Holdout + Todes-Gate (Tool sicop_holdout): Trainieren <=2024, Testen 2025-26; wenn das Modell den Anker der Ausschreibungsunterlagen nicht übertrifft, wird es verworfen (bleibt Speicher + Überwachung).

• Offene Punkte: p1_conversion_cartera (impliziter Wechselkurs 460-690 CRC/USD, offizielles BCCR-Gate ausstehend) · p3_catalogo_familias (9.295 abgeleitete Familien) · p5_recurrente_vs_recurrido · p6_sanciones_vigencia (1 sanktionierter, der aktuell gewinnt) · p7_tamano_historico (1,04% Änderung → kein SCD2) · p10_bronze_zip_miembro (Bronze aus ZIP, wörtliche Rohzeile). P11 resultado_decision in PHASE 2 geschlossen.

Extras des Plans — Atlas, CGR, BCCR

• Atlas (/atlas/): Navigations-App des Korpus. Planentscheidungen eingehalten: keine Zahl reist allein (jeder Bildschirm zeigt seinen Umschlag), Qualität kommt zuerst (/atlas/calidad/: Ableitung nach Jahr, Tests-Gate, Läufe, Überwachung, Fallen), blockierte Fallen nicht dokumentiert (die UI warnt vor dem Vergleich von Währungen und Preisen über Jahre hinweg ohne CL), und die App gibt dem Harness ein Gesicht (Tages-Signale sichtbar). Bildschirme: Dashboard, Suche, Anbieter, Anbieterprofil, Produkt (Historie), Verfahren (Akte+Wettbewerb+Regime+Eingeladene+Ressourcen), Markt nach Familie.

• CGR-Suche (/api/v1/cgr/?termino=, Tool sicop_cgr_buscar): PDFs von Beschlüssen mit nativem Text. GEZIELTE NUTZUNG, kein Durchsuchen; rechtliches Gate ausstehend (CGR-Bedingungen nicht gelesen).

• BCCR-Wechselkurs (/api/v1/bccr-tc/?fecha=, Tool sicop_bccr_tc): offizieller BCCR (Serien 317/318) wenn BCCR_TOKEN/BCCR_EMAIL in .env; ohne Token wird der implizite Wechselkurs der Quelle (jährlicher Median CRC/USD) zurückgegeben, entsprechend gekennzeichnet.

• Einladungen: 42,2 Mio. Zeilen geladen + invitados_vs_ofertantes.

Docker (VPS)

docker compose up -d --build
# expone 8400 -> django (puerto libre, no choca con 8100 de consola-mwt-one), con Salidas montado en /data/salidas

PHASE 1 — kanonische Schicht (Bronze + Silber + Kontrolle)

python manage.py fase1                # bronze -> silver (6 hechos) -> tests-gate -> gold atomico
python manage.py fase1 --solo-tests   # solo correr los tests como gate
python manage.py recalcular_derivadas # producto_firma, recursos_desenlace, tiempos_por_etapa, precios_identicos, invitados_vs_ofertantes, regimen_evaluacion, ctl_deriva, catalogo_campo

• Bronze (/api/v1/bronze/): unveränderliche Rohzeile + HASH_FILA + CORRIDA_ID + Monat.

• Silber — 6 Fakten (korrekte Granularität, DECIMAL(18,4), Währungstrio, Bitemporalität OBSERVADO_DESDE/HASTA/ES_VIGENTE): /fact-requerimiento (Ausschreibung, Verfahren x Zeile x Position) · /fact-oferta (Verfahren x Angebot x Zeile) · /fact-adjudicacion (Akt x Verfahren x Zeile x Anbieter) · /fact-contrato-linea · /fact-orden (eine Zeile pro NRO_ORDEN, TOTAL_ORDEN nur einmal, nur CRC summierbar) · /fact-recepcion.

• Kontrolle (/api/v1/ctl-*): Lauf, Quellmonat (ZIP-Hash), Schema, Quarantäne, Tests als Gate.

• catalogo_campo (/api/v1/catalogo-campo/): navigierbares Datenwörterbuch (Typ, Füllung, Schlüssel, Falle, Einheit, Join-Regel).

• Atomare Veröffentlichung: Gold wird nicht veröffentlicht, wenn ein Gate-Test fehlschlägt (die vorherige Version bleibt erhalten).

Tools MCP: sicop_fact_requerimiento/oferta/adjudicacion/contrato/orden/recepcion, sicop_catalogo_campo, sicop_ctl_deriva, sicop_regimen, sicop_competencia_por_regimen, sicop_gold_status.

Daten

• MESSSTUFE: cartera vergleicht MONTO_EJECUTADO_CRC (nur Colones, Dedupe nach NRO_ORDEN) mit MONTO_ADJUDICADO_CRC. Die Messung nach Zuschlägen unterschätzt bis zu 59x (Fall SONDEL 2026: 64x).

• Währungen: Die Bestellungen enthalten 5 Währungen (CRC/USD/EUR/JPY/GBP); nur Colones werden summiert.

• Abdeckung: competencia_por_linea deckt 62,6% der Kreuzung Angebot x Bieter ab (im Paket dokumentiert).

• Datenschutz: inhibiciones enthält Beamte; keine Konsolidierungen ohne ausdrückliche Entscheidung veröffentlichen (Gesetz 8968).

• Bereinigung: Ungültige Zellen von Beträgen/Daten werden als NULL geladen (gezählt in estado-carga).