sicop_mcp

SICOPデータサーバー（コスタリカの公共調達、オープンデータ2020-2026）を API REST および MCPサーバー としてAIアシスタント向けに公開。

• データ: SICOPパッケージの Salidas/（Postgresに約430万行、31テーブルにロード済み： 2020〜2026年の13データセット + 派生ゴールド18テーブル）。

• スタック: Django 6 + DRF + Celery + Postgres + Redis。mwt/consola-mwt-oneと同じパターン。

• ドメインルール: プロバイダーのビジネス数値はすべて測定レベルを宣言する （captacion = 落札 · ejecucion = 発注書 · entrega = 受領）。

ローカル起動

要件: Python 3.12+（3.14でテスト済み）、ローカルPostgreSQL 16/18、Redis（または使用するブローカー）。

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（実行 vs 捕捉）、sicop_mercado_familia、 sicop_competencia_procedimiento、sicop_producto、sicop_producto_historia（年別価格シリーズ）、 sicop_cara_a_cara（2プロバイダー比較）、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）が付属: 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を統合 → ウォッチリストのシグナル → 優先キュー → ゴールド + テストゲート。

• 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/）: クライアント参加/落札/落選、入札書類異議申立、新規制裁、 監視対象機関、僅差で落選（watchlist.json）。

• 監視（/api/v1/vigilancia/）: 対象月のETag/Content-Length vs ctl_mes_fuente。

MCPツール: sicop_registrar_resultado、sicop_resultado、sicop_senales、sicop_vigilancia、 sicop_ciclo_diario、sicop_consolidar_resultados。

フェーズ 3 — 物理的エンフォースメント + 2レーン + 記録

• エンフォースメント（/api/v1/politica/）: 生パス（/salidas/、.csv、.zip、file://、..\）や シークレットを含むリクエストを403でブロックするミドルウェア。ポリシーテスト （自由SQLなし、通貨混在なし、生パスなし）→ 5/5 PASS。

• 2レーン: 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行）、捕捉はパターンを再現（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からのブロンズ、生の行をそのまま）。P11 resultado_decision はフェーズ2でクローズ済み。

計画の追加 — Atlas、CGR、BCCR

• Atlas（/atlas/）: コーパス閲覧アプリ。計画の決定を尊重: 数値は単独で移動しない（各画面がエンベロープを表示）、品質が最優先 （/atlas/calidad/: 年別派生、テストゲート、実行、監視、トラップ）、 ブロックされたトラップは文書化しない（UIは通貨比較やCLなしの年跨ぎ価格比較を警告）、 そしてアプリはハーネスに顔を向ける（当日のシグナルを表示）。 画面: ダッシュボード、検索、プロバイダー、プロバイダーフィーチャ、製品（履歴）、 手続き（案件+競争+評価方式+招待+リソース）、ファミリ別市場。

• 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 — 正規レイヤー（ブロンズ + シルバー + コントロール）

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

• ブロンズ（/api/v1/bronze/）: 不変の生行 + HASH_FILA + CORRIDA_ID + 月。

• シルバー — 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ごとに1行、TOTAL_ORDEN は1回のみ、CRCのみ合算可能）· /fact-recepcion。

• コントロール（/api/v1/ctl-*）: 実行、ソース月（zipハッシュ）、スキーマ、隔離、テストをゲートとして。

• catalogo_campo（/api/v1/catalogo-campo/）: ナビゲーション可能なデータ辞書（型、入力率、キー、トラップ、単位、結合ルール）。

• アトミック公開: ゲートテストが失敗した場合、ゴールドは公開されない（前のバージョンが残る）。

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 でカウント）。