sicop_mcp

SICOP 데이터 서버(코스타리카 공공조달, 공개 데이터 2020-2026)를 REST API 및 AI 어시스턴트용 MCP 서버로 제공합니다.

• 데이터: SICOP 패키지의 Salidas/(Postgres 31개 테이블에 약 430만 행 로드: 2020-2026년 연도별 13개 세트 + 파생 gold 테이블 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(ejecucion vs captacion), 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의 envelope)가 포함됩니다: nivel_medicion, cobertura_cruce(0.626), moneda, caveats.

REST API

정확한 컬럼 이름(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 통합 → watchlist 신호 → 우선순위 큐 → gold + tests-gate.

• resultado_decision(SCH_RESULTADO v1, /api/v1/resultados/, POST /api/v1/resultado-registrar/): 그레인 (nro_sicop, nro_linea, decision_id), append-only, 컨텍스트 동결 필수 (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 vs ctl_mes_fuente.

MCP 도구: sicop_registrar_resultado, sicop_resultado, sicop_senales, sicop_vigilancia, sicop_ciclo_diario, sicop_consolidar_resultados.

3단계 — 물리적 enforcement + 이중 차선 + 기록

• Enforcement(/api/v1/politica/): 원시 경로(/salidas/, .csv, .zip, file://, ..\) 또는 비밀번호가 포함된 모든 요청을 403으로 차단하는 미들웨어; 정책 테스트 (자유 SQL 금지, 통화 혼합 금지, 원시 경로 금지) → 5/5 PASS.

• 이중 차선: 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에 기록됩니다(에이전트, 도구, params, 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 없는 연도 간 가격 비교에 대해 경고), 앱이 하네스에 얼굴을 부여(당일 신호 표시). 화면: 대시보드, 검색, 공급업체, 공급업체 카드, 제품(이력), 절차(expediente+경쟁+평가 체제+초청자+이의), 패밀리별 시장.

• CGR 검색(/api/v1/cgr/?termino=, 도구 sicop_cgr_buscar): 네이티브 텍스트 결정문 PDF. 지정 사용, 대량 스캔 금지; 법적 게이트 대기(CGR 약관 미열람).

• BCCR 환율(/api/v1/bccr-tc/?fecha=, 도구 sicop_bccr_tc): .env에 BCCR_TOKEN/BCCR_EMAIL이 있으면 BCCR 공식(시리즈 317/318); 토큰이 없으면 소스의 암시적 환율(연간 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), 통화 3종, 비시간성 OBSERVADO_DESDE/HASTA/ES_VIGENTE): /fact-requerimiento(cartel, 절차 x 라인 x 품목) · /fact-oferta(절차 x 제안 x 라인) · /fact-adjudicacion(행위 x 절차 x 라인 x 공급업체) · /fact-contrato-linea · /fact-orden(NRO_ORDEN당 한 행, TOTAL_ORDEN은 한 번만, CRC만 합산 가능) · /fact-recepcion.

• Control(/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에 집계).