Snap Validation Lab

SNAP验证实验室

演示人口普查MCP服务器功能的概念验证 用于结合公共数据集来分析SNAP（补充营养援助计划）资格和计划结果。

项目概述

本项目演示了如何使用 普查MCP（模型上下文协议）服务器 查询美国人口普查数据，并将其与其他公共数据集（SNAP质量控制微观数据）结合起来进行政策分析。

这表明了什么

1. 通过MCP服务器查询人口普查数据 -收入、贫困和人口数据
2. 组合多个数据源 -人口普查局+美国农业部公共数据集
3. 自动数据分析 -用于资格评估和验证的Python脚本
4. 数据验证工作流程 -输入验证和健全性检查模式

关于人口普查MCP服务器

这 人口普查MCP服务器 允许通过Claude Code向美国人口普查局API进行自然语言查询。您可以提出以下问题，而不是手动构建API请求：

• “密西西比州欣兹县的贫困率是多少？”
• “比较三个县的收入中位数”
• “有多少人生活在贫困线130%以下？”

本项目展示了如何使用MCP服务器：

• 交互式探索 -分析过程中的快速人口统计查询
• 程序集成 -将人口普查数据与其他数据集相结合
• 验证工作流程 -对照行政数据核对估计数

分析结果示例

备注：SNAP QC错误分析使用 密西西比 作为示范案例。人口普查MCP服务器适用于任何美国地理区域。

密西西比州SNAP分析（2023财年）：

• 错误率38.4% 密西西比州SNAP病例
• 收入是主要的错误驱动因素：工薪阶层的错误率为73.3%，非工薪阶层为30.9%
• 收入复杂性很重要：收入来源为3+的家庭的错误率为77.8%
• 每年2940万美元的影响 仅在密西西比州
• 留住人才的挑战：行政错误可能导致符合条件的工薪家庭循环取消福利

看 docs/notes.md 进行完整分析。

项目结构

snap-validation-lab/
├── analysis/                    # Analysis scripts
│   ├── analyze_qc_data.py       # Basic QC data analysis
│   ├── analyze_error_impact.py  # Error impact quantification ($$ estimates)
│   └── analyze_error_types.py   # Income vs deduction error breakdown
│
├── data/                        # Data files (gitignored)
│   └── qc_pub_fy2023.csv        # SNAP QC microdata
│
├── docs/                        # Documentation
│   ├── notes.md                 # Complete exploration notes and findings
│   └── VALIDATION.md            # Input validation documentation
│
├── outputs/                     # Generated outputs (gitignored)
│
├── us-census-bureau-data-api-mcp/  # Census API MCP server
│
└── README.md                    # This file

快速开始

📖 看 设置.md 有关详细的设置说明

1.设置

# Install Python dependencies
pip install -r requirements.txt

# Setup Census API key (IMPORTANT!)
cp .env.example .env
# Edit .env and add your Census API key
# Get key from: https://api.census.gov/data/key_signup.html

# Get SNAP QC data
# Download from: https://www.fns.usda.gov/snap/qc-annual-reports
# Place in: data/qc_pub_fy2023.csv

需要帮助？ 请参阅中的详细说明 设置.md

2.运行分析

# Basic QC analysis
python3 analysis/analyze_qc_data.py

# Error impact analysis (financial)
python3 analysis/analyze_error_impact.py

# Error type breakdown (income vs deductions)
python3 analysis/analyze_error_types.py

3.使用人口普查MCP服务器

人口普查MCP服务器是本次演示的核心 -它允许通过Claude Code对人口普查数据进行自然语言查询。

# Server is configured in .mcp.json
# Use through Claude Code interface to query Census data:

# "What is the median income in Hinds County, MS?"
# "Compare poverty rates for Hinds and Bolivar counties"
# "What percentage of people in Bolivar County are below 130% poverty level?"
# "Show me educational attainment data for Mississippi counties"

本项目中演示的示例查询：

• SNAP资格估算的收入与贫困比率（表C17002）
• 人口背景下的家庭收入分配（B19001）
• 用于参与差距分析的SNAP收据数据（S2201）
• 县级人口统计比较

数据源

SNAP质量控制数据

• 源：美国农业部食品和营养服务局
• 统一资源定位符: https://www.fns.usda.gov/snap/qc-annual-reports
• 文件：2023财年公用文件
• 覆盖：全国样本（约44000例，全部50个州）
• 这一分析：密西西比子集（1181例）用作示范
• 备注：公共文件包括州标识符，但不包括县标识符

人口普查数据（通过MCP服务器）

• 源：美国人口普查局美国社区调查（ACS）
• API：人口普查数据API
• 数据集：ACS 5年预测（2023年）
• 使用的表格:

- C17002：收入与贫困水平之比 - B19001：家庭收入分配 - S1701：贫困状况 - S2201:SNAP收据 - S1501：教育程度

方法论

以密西西比州为例进行分析

资格评估（密西西比州各县）

1. MS县收入与贫困比率查询普查（表C17002）
2. 计算FPL≤130%的人口（SNAP收入阈值）
3. 示例估计：辛德斯县约28.7%符合条件，玻利瓦尔县约43.5%符合条件

质量控制数据验证（密西西比州）

1. 密西西比州筛选的SNAP QC微观数据（1181例）
2. 确认99.5%的参与者FPL≤130%（验证阈值）
3. 将参与者的人口统计数据与人口普查估计值进行比较
4. 分析可能导致符合条件的人失去福利的管理错误

误差分析（密西西比州）

1. 分类案例：正确（61.6%）、付款错误（21.3%）、错误案例（17.1%）
2. 按家庭特征分析错误模式
3. 隔离收入与扣除误差来源
4. 全州范围内的项目财务影响

示例分析结果

聚焦：了解导致符合条件的人失去福利或收到不正确金额的行政错误

保留风险：按类别划分的高错误率

1. 收入证明 -工薪阶层的错误率为73%（可能导致重新认证失败）
2. 扣除计算 -医疗（72.7%），庇护所（50%）（福利金额不正确）
3. 复杂家庭 -7人以上家庭的错误率为87.5%（行政负担）

面临行政人员流失风险的家庭

1. 工作家庭 -错误率为73.3%，而非工薪阶层的错误率为30.9%（工资文件问题）
2. 多种收入来源 -3+源的错误率为77.8%（复杂性导致错误→ 终止）
3. 有孩子的家庭 -错误率为48.9%，无错误率为31.1%（风险更高，波动性更大）

成功保留家庭（错误率较低）

1. 零收入家庭 -5.9%错误率（简单验证）
2. 单人家庭 -29.8%的错误率（复杂性较低）
3. 非常贫困的家庭 （贫困率\=2.0.0

numpy>=1.24.0

安装方式：

pip install -r requirements.txt

### 数据需求

- SNAP QC公用文件（2023财年）：约64MB CSV
- 人口普查API密钥（用于MCP服务器）

## 安全注意事项

⚠️ **重要**：永远不要将敏感文件提交到git！

> **看 [设置.md](SETUP.md) 获取详细的秘密管理指南**

### 秘密管理

**您的人口普查API密钥应在 `.env` 文件：**

.env (gitignored - never committed)

CENSUS_API_KEY=your_actual_key_here

这 `.gitignore` 文件保护：

- ✅ 人口普查API密钥(`.env`, `.mcp.json`)
- ✅ 数据文件(`data/`, `*.csv`)
- ✅ 环境文件(`.env`, `.env.local`)
- ✅ 输出(`outputs/`)

### 在推送到GitHub之前：

1. **验证 `.gitignore` 已到位**

cat .gitignore # Should include .env and data/

1. **在代码中不检查API键**

git grep -i "api.key\|census_api_key" | grep -v ".env" # Should only show variable names, not actual keys

1. **确认数据文件已排除**

git status # Should NOT show data/ or .env

1. **验证.env是否受保护**

git check-ignore .env # Should output: .env

**看 [设置.md](SETUP.md) 获取完整的安全设置指南。**

## 潜在扩展

这个概念证明可以扩展到证明：

### 附加分析

- \[\]县级细分（QC数据访问受限）
- \[\]多州比较（不同的经济背景）
- \[\]交互式可视化仪表板
- \[\]预测建模方法

### 技术演示

- \[\]分析管道中的实时人口普查数据查询
- \[\]与其他公共数据集的集成模式
- \[\]自动化数据验证框架
- \[\]其他人口普查表的MCP服务器使用模式

## 贡献

这是一个概念验证示范项目。对于问题或探索类似方法：

- 看 [`docs/notes.md`](docs/notes.md) 方法论和详细发现
- 审查 [`docs/VALIDATION.md`](docs/VALIDATION.md) 用于数据验证模式
- 看看 [人口普查MCP服务器](us-census-bureau-data-api-mcp/) 用于集成示例

## 许可证

展示人口普查MCP服务器用于公共政策分析的演示项目。

## 致谢

- **数据**：美国农业部食品和营养服务局（SNAP QC）、美国人口普查局（ACS）
- **工具**：人口普查数据API MCP服务器，Claude代码
- **上下文**SNAP程序验证和质量控制分析