MCP SAT 69 / 69-B · WATR

Python / FastMCP 기반 MCP(Model Context Protocol) 서버로 SAT 공개 목록을 조회합니다:

• CFF 제69-B조(EFOS) — 가장 거래: 추정, 반박됨, 확정, 유리한 판결.

• CFF 제69조 — 확정 납세 상태: 확정, 징수 가능, 소재불명, 취소, 면제.

SSC-CDMX의 movilizaciones MCP와 동일한 아키텍처: stdio + Streamable HTTP 전송, bearer 정적 토큰 폴백이 있는 OAuth 2.1(WorkOS AuthKit), Turso(libSQL) 영속성, 선택적 다운로드 프록시, 외부 cron(GitHub Actions)을 사용한 Render 배포. OCR 없음: SAT CSV는 이미 구조화되어 있습니다.

도구

위험: CRITICO(EFOS 확정) · ALTO(EFOS 추정) · MEDIO(69 확정/징수 가능/소재불명) · BAJO(반박됨/유리한 판결) · INFORMATIVO(69 취소/면제) · LIMPIO.

결과는 SAT 공개 파일의 마지막 가져오기를 반영합니다. 세무 또는 법률 자문을 구성하지 않습니다.

Related MCP server: rues

아키텍처

CSV del SAT (Latin-1)                     ┌────────── FastMCP ──────────┐
   │  fetcher (httpx + proxy opcional)    │ verificar_rfc / _lote        │
   ▼                                      │ buscar_nombre / estado_datos │
 pipeline (parse 69 / 69b)  ──►  SQLite ──┤ actualizar_datos             │
   │   (FTS5 unicode61, triggers)  ▲  │   └──────────┬──────────────────┘
   ▼                               │  │   stdio (server.py) + HTTP (web.py)
 Turso (libSQL, durable) ◄── push  │  └► pull al arranque      │
                                   └─────────────────── /health /refresh /reload

• server.py — FastMCP(stdio) + 도구 + AuthKit.

• web.py — Starlette/uvicorn(HTTP): /refresh 및 /reload(bearer M2M), /mcp(OAuth 또는 bearer).

• pipeline.py — 다운로드 → SHA-256(변경되지 않으면 생략) → Latin-1 파싱 → SQLite 교체 → Turso 푸시.

• database.py — 트리거가 있는 SQLite + FTS5; B-tree 인덱스로 RFC(핫 경로).

• turso.py — 안정적인 Turso ↔ 로컬 동기화.

• risk.py — RFC 정규화 + 판정 트리(69-B가 69보다 우선).

로컬 설치

cd sat69-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Primera ingesta (descarga ~22 MB; el 69 son ~½ millón de filas)
python -c "from sat69 import database as db, config; db.init_db(config.settings.db_path)"
python -c "from sat69.pipeline import process_import; print(process_import())"

# Probar
pytest -q

Claude Desktop / Cowork에서 연결(stdio)

{
  "mcpServers": {
    "sat69": { "command": "sat69-mcp" }
  }
}

(또는 venv가 활성화된 상태에서 "command": "python", "args": ["-m", "sat69"].)

Render 배포

render.yaml은 네이티브 Python 런타임으로 웹 서비스를 프로비저닝합니다(Docker 불필요):

1. GitHub에 저장소를 올리고 render.yaml을 가리키는 Blueprint를 Render에 생성합니다.

2. 변수(sync:false로 표시): MCP_API_KEY(bearer), 선택 사항 AUTHKIT_DOMAIN+BASE_URL(OAuth), TURSO_DATABASE_URL+TURSO_AUTH_TOKEN.

3. MCP 엔드포인트: POST https://<servicio>.onrender.com/mcp.

인증(두 가지 모드, movilizaciones와 동일)

• 정적 bearer(MCP_API_KEY): 간단하며 /mcp, /refresh, /reload를 보호합니다.

• OAuth 2.1(WorkOS AuthKit): AUTHKIT_DOMAIN + BASE_URL을 정의하면 /mcp가 Dynamic Client Registration을 사용하는 OAuth로 전환되고, bearer는 계속 M2M 엔드포인트를 보호합니다.

자동 새로고침

.github/workflows/refresh.yml은 매일 POST /refresh를 호출합니다(11:30 UTC ≈ 05:30 CDMX). 저장소 시크릿: RENDER_BASE_URL, MCP_API_KEY. 수동: workflow_dispatch(force 포함).

영속성(Turso)

로컬 SQLite(Render에서는 임시, /tmp)가 쿼리를 처리하고, Turso는 재배포 후에도 유지되는 내구성 있는 저장소입니다. 시작 시 Turso에서 pull하고, 각 actualizar_datos//refresh 후 push합니다. TURSO_*가 없으면 순수 로컬 모드로 실행됩니다.

다운로드 프록시(선택 사항)

FETCH_PROXY 또는 DATAIMPULSE_*는 CSV 다운로드만 라우팅합니다. 테스트에서 SAT는 데이터센터 IP를 차단하지 않았고(직접 다운로드 200 응답), 보통은 필요하지 않습니다. 패리티와 복원력을 위해 유지됩니다.

데이터 출처(SAT · Datos Abiertos)

• 69-B: Listado_Completo_69-B.csv(~14k 레코드, 20개 열, 헤더는 3번째 줄).

• 69: Firmes.csv, Cancelados.csv, NoLocalizados.csv, Exigibles.csv, Sentencias.csv, Condonados.csv(~50만 레코드, 6개 열). URL은 config.py에 있습니다.