内容
# IBGE 微数据 MCP 服务器
IBGE 微数据 MCP 服务器，用于发现、下载、解压、转换、查询和分析官方公共 IBGE 微数据。
该项目不托管 IBGE 数据集。它使用 IBGE 下载服务器作为真实来源，仅下载用户明确请求的文件，将其镜像到本地缓存，并在本地文件上运行分析。
IBGE 的原始公共下载主机是 `ftp.ibge.gov.br`。服务器接受该主机的 `https://` 和 `http://` URL。在可能的情况下，它尝试保持官方的 HTTPS URL，但在公共文件的 HTTPS 速度慢或不可用时，可以退回到官方的 HTTP。工具输出报告解析的 URL、使用的传输和下载后的 SHA-256 哈希值。
## 为什么是本地优先
IBGE 微数据文件是公开的，但许多文件都很大，以至于 MCP 服务器不应该直接在聊天响应中返回它们。实用的工作流程是：
```text
发现官方文件 -> 检查大小 -> 下载选定的存档 -> 检查/提取条目 -> 将选定的变量转换为 Parquet -> 用 DuckDB 查询
```
简单来说：
- **DuckDB** 是一个本地分析型 SQL 引擎。它可以在不运行数据库服务器的情况下查询大型本地文件。
- **Parquet** 是一种压缩的列式文件格式。转换一次固定宽度的 TXT 微数据，然后仅查询所需的列。
## 核心通用工具
| 工具 | 用途 |
|---|---|
| `ibge_microdata_list_surveys` | 列出调查系列，附带便捷支持。 |
| `ibge_microdata_connectivity_check` | 检查此机器是否可以通过 HTTPS 和 HTTP 访问 IBGE 下载/API 端点。 |
| `ibge_microdata_list_files` | 列出支持的调查系列的已知公共存档文件。 |
| `ibge_microdata_list_directory` | 列出任意官方 `ftp.ibge.gov.br` 目录。 |
| `ibge_microdata_discover` | 有限爬取官方 IBGE 目录，以查找微数据、数据、文档和布局文件。 |
| `ibge_microdata_discover_metadata` | 有限爬取，专注于可能的字典、布局、输入、代码簿和文档文件。 |
| `ibge_microdata_file_info` | 读取文件大小、类型、更新时间戳和验证器，使用 HTTP HEAD。 |
| `ibge_microdata_download_file` | 下载或重用官方 IBGE 文件在本地缓存中。 |
| `ibge_microdata_list_cache` | 列出已下载到本地缓存中的文件，包含 URL、路径、大小和时间戳。 |
| `ibge_microdata_cleanup_cache` | 预览或删除使用安全筛选器的选定缓存文件。 |
| `ibge_microdata_zip_entries` | 列出本地 ZIP 存档中的文件，而不提取整个存档。 |
| `ibge_microdata_extract_zip_entry` | 提取选定的 ZIP 条目到本地路径。 |
| `ibge_microdata_inspect_layout` | 解析本地 IBGE 固定宽度输入布局并搜索变量。 |
| `ibge_microdata_metadata_inventory` | 解析本地字典/布局或文档 ZIP 为记录、变量、位置、类型和值标签。 |
| `ibge_microdata_search_variables` | 在本地官方元数据中搜索变量名称、描述和解析的值标签/类别。 |
| `ibge_microdata_export_architecture_csv` | 将解析的官方元数据导出到本地 Base dos Dados 样式的架构 CSV。 |
| `ibge_microdata_export_dictionary_csv` | 将解析的官方值标签/类别导出到本地 Base dos Dados 样式的 `dicionario.csv`。 |
| `ibge_microdata_fixed_width_file_to_parquet` | 将固定宽度 TXT 文件和官方布局转换为本地 Parquet 文件。 |
| `ibge_microdata_fixed_width_zip_to_parquet` | 将 ZIP 内的一条固定宽度 TXT 记录直接转换为本地 Parquet。 |
| `ibge_microdata_query_parquet` | 在本地 Parquet 文件上运行有限的只读 DuckDB SQL，作为 `microdata` 暴露。 |
| `ibge_microdata_query_parquet_views` | 在多个命名 Parquet 视图上运行有限的只读 DuckDB SQL，用于连接。 |
| `ibge_microdata_weighted_distribution` | 计算本地 Parquet 视图的加权总值、均值、组份额和顶级份额。 |
| `ibge_microdata_describe_parquet_views` | 检查命名 Parquet 视图的架构、行数和样本行。 |
| `ibge_microdata_profile_parquet_views` | 配置本地 Parquet 视图，包含行数、空值计数、数字范围、频繁值和样本。 |
| `ibge_microdata_validate_recipe` | 验证版本化的 JSON 和谐化配方，而不写入输出。 |
| `ibge_microdata_apply_recipe` | 应用版本化的 JSON 和谐化配方，并写入派生的 Parquet 文件。 |
通用路径是发现、缓存、官方元数据检查/搜索、Parquet 转换、配置文件和 DuckDB 查询。这些工具是服务器的主要公共接口。
## 可选的调查特定帮助程序
这些帮助程序建立在相同的本地优先工作流程之上。它们是已知 IBGE 格式的有用快捷方式，但对于通用工作流程不是必需的。
| 工具 | 用途 |
|---|---|
| `ibge_microdata_pof_manifest` | 解析 POF Excel 字典，并将记录表映射到数据 ZIP 条目。 |
| `ibge_microdata_pof_zip_record_to_parquet` | 使用 POF 字典将 POF 记录从 Dados ZIP 转换为 Parquet。 |
| `ibge_microdata_pnadc_analyze_file` | 在提取的固定宽度 TXT 文件上进行 PNAD Contínua 便捷摘要。 |
| `ibge_microdata_pnadc_analyze_zip` | 直接在 ZIP 内的 TXT 条目上进行 PNAD Contínua 便捷摘要。 |
| `ibge_microdata_r_status` | 检查本地 `Rscript` 和所需的 R 包。 |
| `ibge_microdata_pnadc_r_download` | 使用 R 通过 `PNADcIBGE` 下载 PNAD Contínua 并写入 Parquet 或 RDS。 |
| `ibge_microdata_datazoom_pnadc_load` | 使用 R 通过 `datazoom.social` 加载 PNAD Contínua 并保存生成的文件。 |
## 先决条件
此 MCP 是一个本地工具。用户需要：
- Node.js 18.20 或更新版本。
- pnpm。
- R 和 `Rscript` 可在 `PATH` 上使用。
R 作为项目先决条件包含在内，因为 PNAD Contínua 和 Data Zoom 工作流程最好由现有的巴西 R 生态系统支持。MCP 服务器本身仍作为 Node/TypeScript 进程运行，并返回 MCP 友好的 JSON、Markdown 和本地文件路径。
## 安装
1. 安装系统运行时。
在 macOS 上使用 Homebrew：
```bash
brew install node r
npm install -g pnpm@11.7.0
```
在 Windows 上使用 winget：
```powershell
winget install OpenJS.NodeJS
winget install RProject.R
npm install -g pnpm@11.7.0
```
在 Ubuntu/Debian 上：
```bash
sudo apt update
sudo apt install -y nodejs npm r-base
sudo npm install -g pnpm@11.7.0
```
Linux 包管理器有时会提供较旧的 Node.js 版本。如果 `node --version` 低于 18.20，请从 NodeSource、nvm 或官方 Node.js 安装程序安装较新的 Node.js 版本。
您也可以从其官方安装程序安装相同的工具：
- Node.js：https://nodejs.org/
- pnpm：https://pnpm.io/installation
- R：https://cran.r-project.org/
检查所有三个是否可用：
```bash
node --version
pnpm --version
Rscript --version
```
2. 克隆 GitHub 仓库：
```bash
git clone https://github.com/emmanueltsallis/ibge-microdata-mcp.git
cd ibge-microdata-mcp
```
3. 安装 Node 依赖项并构建本地 MCP 服务器：
```bash
pnpm install
pnpm run build
```
4. 安装 R 支持的 IBGE 工作流程使用的基准 R 包：
```bash
Rscript -e 'install.packages(c("PNADcIBGE", "survey", "jsonlite", "arrow"), repos = "https://cloud.r-project.org")'
Rscript -e 'install.packages("datazoom.social", repos = c("https://datazoompuc.r-universe.dev", "https://cloud.r-project.org"))'
```
## 运行
```bash
node dist/index.js
```
## 通用 MCP 客户端设置
任何支持 stdio 的 MCP 客户端都可以运行此服务器。在克隆、安装依赖项和运行 `pnpm run build` 之后，配置您的客户端以启动构建的 Node 入口点。
在客户端配置中使用绝对路径指向 `dist/index.js`。大多数客户端使用相同的 基本形状：
```json
{
"mcpServers": {
"ibge-microdata": {
"command": "node",
"args": ["/绝对路径/到/ibge-microdata-mcp/dist/index.js"]
}
}
}
```
如果您的客户端使用 TOML 或其他配置格式，则应用相同的想法：`command` 是 Node 可执行文件，`args` 包含此服务器的构建 `dist/index.js` 文件的绝对路径。
大多数 MCP 客户端在应用程序或会话启动时启动配置的服务器，因此在更改 MCP 配置后重启或重新加载客户端。如果工具不能立即出现，请在调试服务器之前重启客户端。
MCP 使用 stdout 进行协议消息。此服务器将启动和致命日志写入 stderr，这保持了客户端的 stdio 协议流量清洁。
您可以独立于任何特定客户端进行服务器的烟雾测试：
```bash
node --input-type=module - <<'NODE'
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
const transport = new StdioClientTransport({
command: 'node',
args: ['/绝对路径/到/ibge-microdata-mcp/dist/index.js'],
});
const client = new Client({ name: 'ibge-microdata-smoke', version: '0.0.0' });
await client.connect(transport);
const tools = await client.listTools();
console.log(tools.tools.map((tool) => tool.name).sort().join('\n'));
await client.close();
NODE
```
烟雾测试应该列出诸如 `ibge_microdata_list_surveys`、`ibge_microdata_metadata_inventory` 和 `ibge_microdata_fixed_width_zip_to_parquet` 等工具。
有关更简短的通用演练，请参见 [examples/generic-workflow.md](examples/generic-workflow.md)。有关入门和谐化配方，请参见 [examples/harmonization-recipe.json](examples/harmonization-recipe.json)。有关可以为配方提供信息的外部和谐化源，请参见 [docs/harmonization-sources.md](docs/harmonization-sources.md)。
## R 支持的 PNADc 工作流程
首先使用 R 状态工具：
```text
ibge_microdata_r_status({})
```
通过 `PNADcIBGE` 下载 PNAD Contínua 并写入 Parquet 文件，MCP 可以使用 DuckDB 查询：
```text
ibge_microdata_pnadc_r_download({
"year": 2024,
"quarter": 4,
"vars": ["UF", "V1028"],
"outputPath": "/Users/you/.cache/ibge-microdata-mcp/converted/pnadc_2024q4.parquet"
})
```
在需要 Data Zoom 的 PNAD Contínua 处理或面板标识符时使用 `datazoom.social`：
```text
ibge_microdata_datazoom_pnadc_load({
"outputDir": "/Users/you/.cache/ibge-microdata-mcp/datazoom/pnadc",
"years": [2024],
"quarters": [1, 2, 3, 4],
"panel": "basic",
"outputFormat": "parquet"
})
```
## 通用工作流程
1. 从已知的调查系列或官方目录中查找公共文件：
```text
ibge_microdata_list_surveys({})
```
```text
ibge_microdata_connectivity_check({})
```
```text
ibge_microdata_list_files({
"survey": "pof"
})
```
```text
ibge_microdata_discover({
"rootUrl": "https://ftp.ibge.gov.br/",
"maxDepth": 3,
"maxDirectories": 50
})
```
```text
ibge_microdata_discover_metadata({
"rootUrl": "https://ftp.ibge.gov.br/",
"maxDepth": 4,
"maxDirectories": 100
})
```
2. 在下载前检查文件元数据：
```text
ibge_microdata_file_info({
"url": "https://ftp.ibge.gov.br/path/to/public/archive.zip"
})
```
3. 下载到本地缓存：
```text
ibge_microdata_download_file({
"url": "https://ftp.ibge.gov.br/path/to/public/archive.zip",
"cacheRoot": "/Users/you/.cache/ibge-microdata-mcp"
})
```
下载器在 `cacheRoot` 下镜像官方 `ftp.ibge.gov.br` 路径。在重复调用时，它首先检查 IBGE `content-length` 元数据，如果现有本地文件具有预期的字节大小，则返回缓存命中。
如果到 `ftp.ibge.gov.br` 的 HTTPS 连接超时，则下载器可能会通过 `http://ftp.ibge.gov.br` 重新尝试相同的公共文件。这不会发送凭证或私有数据；它只下载公共的 IBGE 文件。响应报告 `transport`、`usedFallback` 和 `sha256`，以便在无头 MCP 使用中保持可审计的传输。
4. 稍后如果需要重新发现本地路径，则列出缓存：
```text
ibge_microdata_list_cache({
"cacheRoot": "/Users/you/.cache/ibge-microdata-mcp",
"limit": 50,
"offset": 0
})
```
5. 当存储增长时，预览缓存清理：
```text
ibge_microdata_cleanup_cache({
"cacheRoot": "/Users/you/.cache/ibge-microdata-mcp",
"dryRun": true,
"olderThanDays": 30,
"minBytes": 100000000
})
```
清理工具默认为 `dryRun: true`，需要至少一个筛选器，并且只考虑 `cacheRoot/ftp.ibge.gov.br` 下的文件。仅在查看预览后设置 `dryRun: false`。
6. 检查存档内容：
```text
ibge_microdata_zip_entries({
"zipPath": "/Users/you/.cache/ibge-microdata-mcp/ftp.ibge.gov.br/path/to/public/archive.zip"
})
```
7. 官方元数据清单和变量搜索：
```text
ibge_microdata_metadata_inventory({
"zipPaths": ["/Users/you/.cache/ibge-microdata-mcp/ftp.ibge.gov.br/path/to/public/documentation.zip"],
"search": "weight",
"variableLimit": 50
})
```
```text
ibge_microdata_search_variables({
"zipPaths": ["/Users/you/.cache/ibge-microdata-mcp/ftp.ibge.gov.br/path/to/public/documentation.zip"],
"query": "rendimento",
"limit": 50
})
```
元数据工具解析官方的 SAS/TXT 输入布局、POF 样式的 Excel 字典、通用 Excel 字典表和具有可识别的位置/宽度/变量列的纯文本字典表。当可用时，它们返回诸如州代码或响应类别的值标签/类别。如果文件无法解析，清单会报告尝试了哪些解析器。
8. 导出 Base dos Dados 样式的本地文档 CSV：
```text
ibge_microdata_export_architecture_csv({
"zipPaths": ["/Users/you/.cache/ibge-microdata-mcp/ftp.ibge.gov.br/path/to/public/documentation.zip"],
"outputPath": "/Users/you/.cache/ibge-microdata-mcp/extra/architecture/variables.csv"
})
```
```text
ibge_microdata_export_dictionary_csv({
"zipPaths": ["/Users/you/.cache/ibge-microdata-mcp/ftp.ibge.gov.br/path/to/public/documentation.zip"],
"outputPath": "/Users/you/.cache/ibge-microdata-mcp/extra/dicionario.csv"
})
```
架构导出为每个解析的变量写入一行。字典导出为每个解析的类别/代码标签写入一行。这些是本地文档工件，灵感来自 Base dos Dados 工作流程；它们不会上传到 BigQuery，也不需要 Base dos Dados 凭证。
9. 直接检查固定宽度布局：
```text
ibge_microdata_inspect_layout({
"layoutPath": "/path/to/official-input-layout.txt",
"search": "weight",
"limit": 50
})
```
10. 将选定的变量转换为 Parquet：
```text
ibge_microdata_fixed_width_zip_to_parquet({
"layoutPath": "/path/to/official-input-layout.txt",
"zipPath": "/Users/you/.cache/ibge-microdata-mcp/ftp.ibge.gov.br/path/to/public/archive.zip",
"entryName": "MICRODATA.txt",
"outputPath": "/Users/you/.cache/ibge-microdata-mcp/converted/sample.parquet",
"selectedVariables": ["record_id", "region", "sample_weight", "target_value"]
})
```
11. 预览 Parquet 文件：
```text
ibge_microdata_profile_parquet_views({
"views": [
{
"name": "microdata",
"parquetPaths": ["/Users/you/.cache/ibge-microdata-mcp/converted/sample.parquet"]
}
],
"columns": ["region", "sample_weight", "target_value"],
"topK": 10,
"sampleRows": 3
})
```
如果省略 `columns`，则该工具默认配置文件中的前 25 列。这保持了宽微数据文件的可管理性，同时仍然提供了足够的信息来选择变量和编写查询。
12. 用 DuckDB 查询 Parquet 文件：
```text
ibge_microdata_query_parquet({
"parquetPaths": ["/Users/you/.cache/ibge-microdata-mcp/converted/sample.parquet"],
"sql": "select region, sum(sample_weight * target_value) / sum(sample_weight) as weighted_mean from microdata group by region order by region",
"maxRows": 100
})
```
查询工具仅接受 `SELECT` 或 `WITH` 查询，拒绝分号和写关键字，并限制返回的行数。
## 和谐化配方
配方是可选的 JSON 文件，它们明确且可重复地进行和谐化假设。MCP 不会提供一个通用的和谐化标准；相反，配方声明所需的输入视图/列、输出 `SELECT` 转换、源引用和验证检查。
```text
ibge_microdata_validate_recipe({
"recipePath": "/path/to/harmonization-recipe.json",
"views": [
{
"name": "microdata",
"parquetPaths": ["/Users/you/.cache/ibge-microdata-mcp/converted/sample.parquet"]
}
],
"sampleRows": 5
})
```
如果验证输出表示需求和验证通过，请写入和谐的 Parquet 文件：
```text
ibge_microdata_apply_recipe({
"recipePath": "/path/to/harmonization-recipe.json",
"views": [
{
"name": "microdata",
"parquetPaths": ["/Users/you/.cache/ibge-microdata-mcp/converted/sample.parquet"]
}
],
"outputPath": "/Users/you/.cache/ibge-microdata-mcp/converted/harmonized.parquet",
"sampleRows": 5
})
```
配方 SQL 仅接受 `SELECT` 或 `WITH` 语句。验证工具报告缺少的输入列、输出模式、样本输出行和验证结果，而不写入文件。应用工具仅在需求和验证通过时写入和谐的输出。
## 加权分布
当Parquet文件包含每分析单位一行，一个数值列和一个数值调查/样本权重列时，使用`ibge_microdata_weighted_distribution`：
```text
ibge_microdata_weighted_distribution({
"views": [
{
"name": "microdata",
"parquetPaths": ["/Users/you/.cache/ibge-microdata-mcp/converted/sample.parquet"]
}
],
"unitSql": "select region, target_value as value, sample_weight as weight from microdata",
"valueColumn": "value",
"weightColumn": "weight",
"groupColumn": "region",
"topPercents": [0.01, 0.05, 0.1]
})
```
该工具按值列对单位进行排名，应用权重，报告总权重，总值，加权平均值，可选的组份额和顶级份额。如果顶部括号在截止值处与值绑定，则绑定桶按比例分配。
## 关系记录
一些调查发布多个记录文件。转换每个记录到Parquet，检查生成的模式，然后连接命名视图：
```text
ibge_microdata_describe_parquet_views({
"views": [
{
"name": "record_a",
"parquetPaths": ["/Users/you/.cache/ibge-microdata-mcp/converted/record_a.parquet"]
},
{
"name": "record_b",
"parquetPaths": ["/Users/you/.cache/ibge-microdata-mcp/converted/record_b.parquet"]
}
],
"includeRowCounts": true,
"sampleRows": 3
})
```
```text
ibge_microdata_query_parquet_views({
"views": [
{
"name": "record_a",
"parquetPaths": ["/Users/you/.cache/ibge-microdata-mcp/converted/record_a.parquet"]
},
{
"name": "record_b",
"parquetPaths": ["/Users/you/.cache/ibge-microdata-mcp/converted/record_b.parquet"]
}
],
"sql": "select a.region, count(*) as rows from record_a a join record_b b using (record_id) group by a.region order by a.region",
"maxRows": 100
})
```
## POF字典
POF版本使用Excel字典工作簿。使用清单工具在转换记录之前将字典工作表映射到TXT条目：
```text
ibge_microdata_pof_manifest({
"dictionaryPath": "/path/to/dictionary.xls",
"dataZipPath": "/Users/you/.cache/ibge-microdata-mcp/ftp.ibge.gov.br/path/to/Dados.zip",
"search": "weight",
"variableLimit": 20
})
```
```text
ibge_microdata_pof_zip_record_to_parquet({
"dictionaryPath": "/path/to/dictionary.xls",
"zipPath": "/Users/you/.cache/ibge-microdata-mcp/ftp.ibge.gov.br/path/to/Dados.zip",
"recordName": "Domicílio",
"outputPath": "/Users/you/.cache/ibge-microdata-mcp/converted/pof_record.parquet",
"selectedVariables": ["UF", "ESTRATO_POF", "TIPO_SITUACAO_REG"]
})
```
POF转换器从字典中应用隐含的十进制缩放，并写入DuckDB可查询的Parquet文件。
## 测试
离线单元测试：
```bash
pnpm test
```
针对官方IBGE端点的实时烟雾测试：
```bash
RUN_IBGE_SMOKE=1 pnpm test -- tests/smoke.test.ts
```
烟雾测试列出官方目录，读取HEAD元数据，并下载较小的POF文档ZIP以验证字典解析。他们不下载大型微数据数据ZIP。
本地R设置烟雾测试：
```bash
RUN_R_SMOKE=1 pnpm test -- tests/r-smoke.test.ts
```
R烟雾测试检查`Rscript`和基线R包可用性。它不下载PNAD微数据。
## 当前限制
- 这是一个本地优先的MCP服务器，而不是一个托管的所有IBGE微数据的仓库。
- 发现被故意限制;广泛的根目录爬取应该使用显式的`maxDepth`和`maxDirectories`值，以避免过多的请求。
- 实现通用固定宽度转换，官方元数据清单/搜索，Parquet配置文件/查询，加权分布摘要和POF字典转换。
- 元数据解析支持常见的IBGE SAS/TXT输入布局，POF样式Excel字典，通用Excel字典表和通用TXT字典表。仅PDF/仅散文代码簿和高度不规则的历史布局可能仍然需要解析适配器。
- 可以添加其他调查特定的和谐配方作为可选层，而无需更改通用工作流程。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器