DATASUS SIH/SUS — Brazil Hospital Admissions (AIH) MCP

DATASUS SIH/SUS——巴西住院治疗（AIH）MCP 服务，1992–2025

MCP（Model Context Protocol）服务，可在 AI 助手中回答有关 SUS 住院治疗的问题——DATASUS 的 SIH/SUS、精简版 AIH 数据；无需使用 TabNet、从 FTP 下载 .dbc 文件或编写 SQL。提供 12 种工具，覆盖 34 年（1992 至 2025 年，共 420.103.883 次住院）：按 ICD-10 章和组统计病因（1998 年之前使用 ICD-9）、月度序列、ICSAP——基层医疗敏感性疾病住院（巴西目录），以及按州和市划分的粗率、特定年龄率或年龄标准化率。每个分层都包含住院次数、住院天数、SUS 支付金额和死亡人数，并在每个答复中注明数据批次的来源和来源引用。

英文版。 巴西 住院治疗 MCP 服务（DATASUS SIH/SUS，“AIH”记录），覆盖 1992–2025 年：按 ICD-10 章和组统计病因（1998 年之前使用 ICD-9）、月度序列、基层医疗敏感性疾病（ICSAP/ACSC，巴西目录），以及按州和市划分的粗率、特定年龄率或年龄标准化率——可在 Claude、ChatGPT 或任何 MCP 客户端中获取答案，每个答复都注明来源并附有引用。无需下载 FTP 文件、解码 DBC 或编写 SQL： npx -y sih-br-mcp。

它能回答的问题

在 MCP 客户端中使用日常语言提问：由助手选择工具和参数。

• “2024 年圣埃斯皮里图州有多少人因肺炎住院？按年龄段划分。”（get_hospitalizations）
• “罗赖马州的 ICSAP 率在 2010 至 2023 年间下降了吗？”（get_icsap_indicators）
• “比较 2023 年北部和东南部地区每 10 万人的住院率，按年龄标准化。”（get_hospitalization_rates、compare_regions）
• “我所在的市，哪些基层医疗敏感性疾病导致的住院人数最多？”（rank_csap_groups）
• “自 1998 年以来的登革热住院月度序列。”（get_hospitalization_trends）
• “J18.9 属于基层医疗敏感性疾病吗？”（classify_as_csap）

与其他方案的比较

使用 R 或 Python 处理 SIH/SUS 的人已经有成熟的工具，而本 服务不会取代其中任何一个——它在整个链条中承担着不同的角色： 在提问发生的位置，也就是助手内部，直接回答汇总数据问题，无需 ETL，也无需下载微观数据。详情、并排示例和实测数据见 docs/comparativo-alternativas.md。

工具	功能	适用场景
sih-br-mcp（本项目）	在 AI 助手中直接回答 34 年的汇总数据问题，并提供 ICSAP、标准化率和逐条回答的数据来源	问题涉及汇总数据（州、城市、年份、月份、CID、年龄、性别、种族、ICSAP），且回答必须可审计
microdatasus 3.0.0（R，CRAN）	下载并处理 DATASUS 微观数据（SIH、SIM、SINASC、SIA、CNES、SINAN）：处理 DBC 并标注变量	需要 AIH 的个体记录、数据立方体之外的变量，或 DATASUS 的其他系统
PySUS 2.11.2（Python）	用于巴西公共卫生数据的工具；读取 DATASUS FTP 上的 DBC/DBF 文件	工作流使用 Python，且想基于微观数据构建自己的 ETL
read.dbc 1.2.0（R，CRAN）	读取并解压卫生部的 .dbc 格式	已有文件，只需打开它们
csapAIH（R，GitHub）	根据巴西清单将 AIH 分类为 ICSAP（本服务会以此为参照进行核对）	需要在 R 中对自己的微观数据进行分类
brpop 0.7.0（R，CRAN）	按城市、州、性别和年龄段提供巴西人口估算数据	自行计算率，并希望用 R 获取分母数据
healthbR 0.4.0（R，CRAN）	本服务的 R 版本：通过同一 Parquet 镜像访问巴西公共卫生数据	使用 R，想将数据放入 data.frame 以继续分析

以下情况请勿使用本服务：问题需要 AIH 的个体记录、数据立方体未包含的变量（实施的医疗程序、医疗机构的 CNES、就诊性质、次要诊断）或 DATASUS 的其他系统（SIM、 SINASC、SIA、SINAN）——此时应使用 microdatasus、PySUS 或 healthbr-data 的 Parquet 镜像。数据立方体按分层提供的内容见 docs/tool-specifications.md：住院次数、住院 天数、支付金额（R$）和死亡人数，按年份、月份、州、城市、CID 章节和组别、 性别、年龄、种族/肤色和 ICSAP 组划分。

数据来源

此服务器是项目公开通道 sih/cubos/ 的消费者，该通道属于 healthbr-data：

Ministério da Saúde / DATASUS (RD<UF><AAMM>.dbc, FTP)
  → healthbr-data sih/rd/ (Parquet 1:1, manifesto com MD5 e data de download)
  → healthbr-data pipeline sih-cubos (scripts/pipeline/sih-cubos/build-aggregations.R)
  → https://data.sidneybissoli.com/sih/cubos/  (cubos + sidecar por ano + manifest.json + tables/)
  → este servidor (cache local sob demanda, SHA-256 conferido contra o manifesto)

截至 08/09/2026，立方体构建器位于此处（scripts/build-aggregations.R、 rebuild-cubes.yml）；此后，生产方改为 healthbr-data，本仓库不再生成或发布任何立方体（CONTEXT.md，决策 27）。完整流程见 healthbr-data/scripts/pipeline/sih-cubos/README.md 和 sih-cubos 卡片。

• **立方体：**按年下载，仅下载请求中涉及的年份，存入 ~/.cache/sih-br-mcp/cubos/（SIH_CACHE_DIR），并在旁边保存 sidecar 文件 sih_provenance_<ano>.json。SIH_CUBES_BASE_URL 可指向其他通道； SIH_CUBES_CACHE=off 可关闭缓存（smoke 和 golden 测试会关闭）。
• **网络：**所有对通道的请求都经过 src/upstream.ts（自 1.1.0 起采用通用作品集 fetch @sbissoli/mcp-upstream）：设置 User-Agent，每次尝试在获取响应头前等待 15 s， 遇到 429/5xx/网络错误时重试 2 次并采用退避策略，且在文件期限内以流式方式读取响应体； 此策略已针对通道进行测量（55 MB 用时 1.2 s），并记录在模块头部。每个响应的来源信息块遵循 v1.3 契约（自 1.7.1 起）：包含 retrieval（此次调用对通道造成的请求次数、尝试次数和异常情况—— 若响应来自磁盘则为 null）、revision（若查询的年份中有年份的统计周期尚未关闭，则为 provisional，否则为 current）、立方体数据块中的 derived 和 derivation_note，以及存在通知时的 notices（例如立方体落后于镜像、未核实数据新鲜度）。
• 数据新鲜度：src/freshness.ts 将 sidecar 与 sih/rd/manifest-summary.json 进行比较，并在立方体落后于镜像时发出通知；重建工作由生产方负责 （rebuild-sih-cubes.yml，每周二及每次镜像维护后运行）。
• 预聚合数据（icsap_summary 数据块自 0.14.0 起提供，causas_summary 数据块自 0.15.0 起提供）：基于已发布立方体生成的快捷数据，位于同一通道。ICSAP 数据是 276 KB 的摘要，另附按年分层的数据；原因数据包括粒度 A （sih_causas_resumo.parquet，包含 34 年数据，共 569 KB：year × uf × cid_chapter × cid_revision × is_csap × exclusion，含住院人次、住院天数、费用和死亡数）以及按年提供的 粒度 B，后者另含性别、五岁年龄组和种族。符合粒度要求的调用无需下载任何立方体即可响应—— “1992 年以来按年统计住院人次和支出”只需 569 KB，而非 1.25 GB。路由策略较为保守： 无法由预聚合数据覆盖的查询（月份、3 位数 CID 类别、CSAP 组、不属于五岁年龄组的年龄） 会回退到立方体并返回精确结果。只有在清单中的 derived_from 仍与已发布立方体的 SHA-256 匹配时，每年才会使用预聚合数据；如果立方体已重建但未重新生成衍生数据，该年份会回退到较慢的 路径，绝不会返回错误数字。
• 分类表（src/data/）：发布契约 sih/cubos/tables/ 的副本； npm run tables:check 会根据清单核对 SHA-256（在 CI 中运行）。切勿在此处编辑——数据源是生产方。
• 人口数据（pop_uf.parquet、pop_uf_agregado.parquet、pop_municipios.parquet）： 自 0.12.0 起来自同一通道，并由 manifest.json 的 population 数据块签名 （生产方：healthbr-data 的 build-population.R + build-sih-population.yml——IBGE， 按 UF 划分的 2024 年预测；DATASUS POPBR/POPSVS，按市镇划分）。费率工具 （get_hospitalization_rates、带 rate_per_10k 的 compare_icsap_trends）和 get_available_years 会在首次调用时将三个文件下载到缓存，并核对 SHA-256； 若数据目录中已有 pop_uf.parquet，则优先使用该文件（fixture、本地构建）。 人口数据的来源信息会返回清单中的 built_at。

用法

npm 包：sih-br-mcp（Node 22+）。 它不包含任何数据——立方体、表格和人口数据会在首次调用时从数据通道获取，并保存在本地缓存中。

npx -y sih-br-mcp           # stdio

在 MCP 客户端（Claude Desktop、Claude Code）中配置：

{ "mcpServers": { "sih": { "command": "npx", "args": ["-y", "sih-br-mcp"] } } }

从源代码运行：

npm install
npm run build
node dist/index.js          # stdio

环境变量：SIH_DATA_DIR（使用包含已构建立方体的文件夹，而非缓存）、 SIH_CACHE_DIR、SIH_CUBES_BASE_URL、SIH_CUBES_CACHE=off、 SIH_FRESHNESS_CHECK=off。

远程服务（Streamable HTTP）

通过 HTTP 提供相同的 12 个工具，供远程连接器（claude.ai）使用：

npm run start:http          # http://localhost:8080/mcp  (GET /healthz para sondar)

除上述变量外，还可设置 PORT 和 SIH_HTTP_HOST。无会话：每个请求 都会创建新的服务和传输，因此任何实例都能处理任何调用。生产环境运行在 Cloudflare Container 中（Dockerfile，镜像中预下载人口数据），并位于 边缘 Worker（worker/）之后，由它负责域名、速率限制、可选身份验证和计量—— 设计与成本见 docs/plan-004-servidor-remoto.md。

验证

npm ci && npm run build
npm test                    # vitest: decisão de rota (puro) + envelope e outputSchema das 12 (caso cheio e caso magro)
npm run smoke:stdio         # superfície das ferramentas × baselines/surface-stdio.json
npm run smoke:http          # mesma superfície e chamadas pelo transporte HTTP (dist/http.js)
npm run golden:tools        # 12 ferramentas byte a byte × baselines/golden-tools.json (fixture 2023/RR)
npm run freshness:selftest  # frescor offline sobre um trecho versionado do manifesto
npm run cache:selftest      # cache local (download + SHA-256) contra um canal falso
npm run tables:check        # tabelas de src/data × manifesto do canal
npm run equiv:summary       # pré-agregados da ICSAP × caminho clássico, byte a byte
npm run equiv:series        # roteamento para o cubo leve de séries
npm run equiv:causas        # pré-agregados de causas (grão A e B) × cubo, byte a byte

CI（.github/workflows/ci.yml）会在 Node 22 和 24 中运行所有这些检查。fixture tests/fixtures/sih/ 是 builder 生成的 2023/RR 立方体真实副本（目前位于 healthbr-data）—— 它让任何升级带来的影响都可以量化。

两类测试的分工：scripts/*.mjs 中的脚本会固定数值（数字一变，基线就会报错）；tests/*.test.ts 测试不变量（哪个立方体回答哪个问题；每个回答都带有来源信息，文本与结构相符，并遵循 tools/list 发布的 outputSchema——使用 SDK 的同一个验证器验证），因此重新发布立方体 不会影响测试。每个工具都有一个完整案例和一个精简案例——后者的回答缺少可选字段，而始终使用完整 fixture 的 golden 测试无法覆盖它——“柔性错误”路径（“年份无数据”）也经过验证。输出 架构位于 src/output-schemas.ts，根据测得的形式手动编写，与输入架构一样。

可通过注册表核验的接口指纹

每次发布都会在其 MCP Registry 条目中发布本版本所提供接口的 sha256（initialize、工具、资源、提示词），以及无需凭据即可响应的方法。接口变更却不升级版本会导致构建失败 （surface.lock.json）；注册表中的指纹让客户端也能在自己那边核验相同内容。规范形式和操作流程见： @sbissoli/mcp-surface 的 SPEC.md （英文）。自行核验（Node 18+，无需依赖）：

curl -sO https://raw.githubusercontent.com/SidneyBissoli/mcp-br-commons/main/packages/mcp-surface/exemplos/verify.mjs
node verify.mjs io.github.SidneyBissoli/sih-br-mcp

维护者：npm run surface:lock 会将区块写入 server.json（mcp-surface registro）， 锁定测试会在 server.json 过期时失败，而 publish.yml 会以 mcp-surface conferir-registro 结束——将注册表中本版本的条目与线上端点进行比对， 就像客户端一样，无需读取锁定文件。这个想法来自 dev.to 上重放文章的两位读者 （Mike Dabydeen 和 Valentina Koniukhova）。

文档

• CONTEXT.md — 编号的架构决策（第 27 项是生产者迁移；第 29 项是远程服务）。
• docs/analise-001（能力窗口）、analise-002（CID-9 时期，1992–1997）、 analise-003（从 CID-9 派生的 ICSAP 列表）、plan-002（DuckDB Node Neo）、 plan-003（自动重建，目前位于 healthbr-data）、plan-004（供 claude.ai 使用的远程 HTTPS 服务）、plan-005（ICSAP 预聚合序列）、plan-006 （预聚合病因立方体）、tool-specifications.md。

许可证

MIT（LICENSE）。数据来自卫生部 / DATASUS；以 Parquet 格式重新分发的数据 以及派生立方体由 healthbr-data 提供（CC-BY-4.0）。