sicop_mcp

SICOP 数据服务器（哥斯达黎加公共采购，2020-2026 年开放数据） 以 API REST 和 MCP 服务器 形式提供给 AI 助手。

• 数据： SICOP 包的 Salidas/（约 430 万行加载到 Postgres 的 31 张表中： 2020-2026 年每年 13 个数据集 + 18 张 gold 派生表）。

• 技术栈： Django 6 + DRF + Celery + Postgres + Redis。与 mwt/consola-mwt-one 相同的模式。

• 领域规则： 供应商的每项业务金额都声明其计量级别 （captacion = 中标 · ejecucion = 订单 · entrega = 验收）。

本地启动

要求：Python 3.12+（已在 3.14 上测试）、本地 PostgreSQL 16/18、Redis（或你使用的 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

通过 Celery 加载数据（技术栈模式）

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 服务器

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

MCP 工具（18 个）：sicop_ficha_proveedor（ejecucion 对比 captacion）、sicop_mercado_familia、 sicop_competencia_procedimiento、sicop_producto、sicop_producto_historia（按年份的 价格序列）、sicop_cara_a_cara（两家供应商对比）、sicop_expediente、 sicop_adjudicaciones、sicop_carteles_objetados、sicop_representantes、 sicop_representante_competencia、sicop_excepciones、sicop_sanciones、 sicop_precios_institucion、sicop_perdidas_baratas（报价最低却落标）、 sicop_campo_buscar、sicop_regimen_evaluacion、sicop_resumen。

所有业务响应都带有信封（计划 §5.4 中的 envelope）：nivel_medicion、 cobertura_cruce（0.626）、moneda 和 caveats。

API REST

按精确列名进行等值过滤（CEDULA_PROVEEDOR、NRO_SICOP、ANO、……）， 文本类资源支持 ?search=。

Related MCP server: chile-procurement

阶段 2 — 每日循环（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

• 每日循环：重写监控（当前月 + 3 个已关闭月份 + 2 个轮换月份）→ 合并结果的 PENDIENTES → 观察列表信号 → 优先队列 → gold + tests-gate。

• resultado_decision（SCH_RESULTADO v1，/api/v1/resultados/，POST /api/v1/resultado-registrar/）： 粒度为 (nro_sicop, nro_linea, decision_id)，仅追加，必须携带冻结的上下文 （build_id/snapshot_ts/modelo_version/features_hash），override 为关键字段。

• 信号（/api/v1/senales/）：cliente_participa/adjudicado/perdio、cartel_objetado、sancion_nueva、 institucion_vigilada、perdio_por_poco（watchlist.json）。

• 监控（/api/v1/vigilancia/）：目标月份的 ETag/Content-Length 对比 ctl_mes_fuente。

MCP 工具：sicop_registrar_resultado、sicop_resultado、sicop_senales、sicop_vigilancia、 sicop_ciclo_diario、sicop_consolidar_resultados。

阶段 3 — 物理强制 + 双通道 + 记录

• 强制（/api/v1/politica/）：中间件，对任何包含 原始路径（/salidas/、.csv、.zip、file://、..\）或机密的请求以 403 阻止；策略测试 （无自由 SQL、不混用货币、无原始路径）→ 5/5 通过。

• 双通道：SICOP_CARRIL=operacion（规范通道）或 SICOP_CARRIL=laboratorio （所有响应标记为 NO_APTO_PARA_DECISION、decision_eligible:false）。 实验室通道额外提供 sicop_lab_sql 工具（只读 SQL，仅 SELECT/WITH， 最多 200 行，拒绝 DELETE）。

• 响应记录（/api/v1/registro/，工具 sicop_registro）：每次 MCP 调用和 API 请求都会记录到 registro_respuesta（代理、工具、参数、build_id、计数、 通道、耗时、状态）。

阶段 4 — 测试（ESOSA 档案、回测、留出集）+ 待办 P1-P11

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

• ESOSA 档案（/api/v1/prueba-fase4/?solo=ficha，工具 sicop_ficha_esosa）：从规范层 复现 — 履约情况完全一致（98.6% / 577 行），captacion 复现了模式（2022 年峰值、2023 年崩溃）， 竞争/面对面对比限于交叉覆盖范围（62.6%），直到恢复的数据加载完成。

• 回测（工具 sicop_backtest_invitaciones）：回放过去的邀请（获胜所需折扣）。

• 留出集 + 死亡门（工具 sicop_holdout）：用 <=2024 训练，在 2025-26 上测试；如果模型未超过 标书的锚点则弃用（保留记忆 + 监控）。

• 待办：p1_conversion_cartera（隐含汇率 460-690 CRC/USD，BCCR 官方门待定）· p3_catalogo_familias（9,295 个派生家族）· p5_recurrente_vs_recurrido · p6_sanciones_vigencia （1 名受制裁者仍在有效中标）· p7_tamano_historico（1.04% 变化 → 不做 SCD2）· p10_bronze_zip_miembro （从 zip 生成 bronze，原始字面行）。P11 resultado_decision 已在阶段 2 关闭。

计划的额外内容 — Atlas、CGR、BCCR

• Atlas（/atlas/）：语料库导航应用。遵循计划中的决策： 任何数字都不单独出现（每个屏幕都显示其信封），质量优先 （/atlas/calidad/：按年份派生、tests-gate、运行、监控、陷阱）， 已阻止的陷阱不予记录（UI 警告不要比较货币和 无 CL 的跨年份价格），以及应用为 harness 赋予面孔（当日信号可见）。 屏幕：仪表盘、搜索、供应商、供应商档案、产品（历史）、 程序（案卷+竞争+制度+受邀者+资源）、按家族的市场。

• CGR 搜索器（/api/v1/cgr/?termino=，工具 sicop_cgr_buscar）：原生文本决议的 PDF。 定向使用，禁止批量扫描；法律门待定（CGR 条款未阅读）。

• BCCR 汇率（/api/v1/bccr-tc/?fecha=，工具 sicop_bccr_tc）：BCCR 官方（序列 317/318） 如果 .env 中有 BCCR_TOKEN/BCCR_EMAIL；无令牌则返回来源的隐含汇率 （CRC/USD 年度中位数）并标记为隐含。

• 邀请：已加载 4,220 万行 + 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

阶段 1 — 规范层（bronze + silver + control）

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/）：不可变的原始行 + HASH_FILA + CORRIDA_ID + 月份。

• Silver — 6 个事实表（正确粒度、DECIMAL(18,4)、货币三元组、双时态 OBSERVADO_DESDE/HASTA/ES_VIGENTE）： /fact-requerimiento（标书、程序 x 行 x 预算项）· /fact-oferta（程序 x 报价 x 行）· /fact-adjudicacion（行为 x 程序 x 行 x 供应商）· /fact-contrato-linea · /fact-orden（每个 NRO_ORDEN 一行，TOTAL_ORDEN 只出现一次，仅 CRC 可加总）· /fact-recepcion。

• 控制（/api/v1/ctl-*）：运行、源月份（zip 哈希）、模式、隔离、测试作为门。

• catalogo_campo（/api/v1/catalogo-campo/）：可浏览的数据字典（类型、填充率、键、陷阱、单位、连接规则）。

• 原子发布：如果门的任何测试失败，gold 不发布（保留先前版本）。

MCP 工具：sicop_fact_requerimiento/oferta/adjudicacion/contrato/orden/recepcion、sicop_catalogo_campo、 sicop_ctl_deriva、sicop_regimen、sicop_competencia_por_regimen、sicop_gold_status。

数据

• 计量级别： cartera 将 MONTO_EJECUTADO_CRC（仅科朗，按 NRO_ORDEN 去重） 与 MONTO_ADJUDICADO_CRC 进行比较。按中标计量会低估最多 59 倍（SONDEL 2026 案例：64 倍）。

• 货币： 订单带有 5 种货币（CRC/USD/EUR/JPY/GBP）；只加总科朗。

• 覆盖率： competencia_por_linea 覆盖报价 x 投标人交叉的 62.6%（已在包中记录）。

• 隐私： inhibiciones 包含公职人员；未经明确决定不得发布汇总数据（第 8968 号法律）。

• 清理：金额/日期的无效单元格加载为 NULL（在 estado-carga 中计数）。