内容
# 联邦选举委员会 FEC MCP 服务器
联邦选举委员会（FEC）竞选财务研究和透明度模型上下文协议（MCP）服务器。该服务器提供工具来搜索候选人、检索财务报告、分析官方FEC数据的贡献和支出。
## 功能
- **搜索候选人**：按名称搜索联邦候选人，按选举年份、办公室、州或党派筛选
- **获取委员会财务**：检索包括收款、支出、现金余额和支出比率的财务摘要
- **获取收款**：获取详细的贡献信息（Schedule A）以及捐赠者详细信息
- **获取支出**：获取详细的支出信息（Schedule B）以及收款人和用途详细信息
- **标记优先的显著分析**：可选的收款/支出显著块，带有参考列表 + 启发式标记原因
- **获取独立支出**：跟踪超级PAC对候选人的支出（Schedule E）
- **获取委员会标记**：检查RFAI、修正案和相关的合规性红旗
- **搜索捐赠者**：按名称、雇主或职业搜索个人捐赠者，跨越所有委员会
- **搜索支出**：按描述或收款人搜索竞选支出，跨越所有委员会
所有数据直接来自官方 [OpenFEC API](https://api.open.fec.gov/developers/)。
## 安装
### 前置条件
- Node.js 20 或更高版本
- FEC API 密钥（从 [api.open.fec.gov](https://api.open.fec.gov/developers/) 免费获取）
### 从 npm 安装
```bash
npm install -g fec-mcp-server
```
### 从源码安装
```bash
git clone <仓库网址>
cd fecmcp
npm install
npm run build
```
## 配置
将您的 FEC API 密钥设置为环境变量：
```bash
export FEC_API_KEY=您的-api-密钥-此处
```
或在项目根目录创建 `.env` 文件：
```
FEC_API_KEY=您的-api-密钥-此处
```
## 与 Claude Desktop 一起使用
将服务器添加到您的 Claude Desktop 配置文件中：
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"fec": {
"command": "npx",
"args": ["fec-mcp-server"],
"env": {
"FEC_API_KEY": "您的-api-密钥-此处"
}
}
}
}
```
或如果已全局安装：
```json
{
"mcpServers": {
"fec": {
"command": "fec-mcp-server",
"env": {
"FEC_API_KEY": "您的-api-密钥-此处"
}
}
}
}
```
## 工具
### 搜索候选人
搜索FEC记录中的候选人姓名。
**参数：**
- `q`（必填）：搜索的候选人姓名
- `election_year`（可选）：按选举年份筛选（例如，2024）
- `office`（可选）：按办公室筛选 - H（众议院），S（参议院），P（总统）
- `state`（可选）：按州筛选（2字母代码）
- `party`（可选）：按党派代码筛选（例如，“DEM”，“REP”）
**示例：**
```
搜索参议院候选人名为“Smith”，参加2024年选举
```
### 获取委员会财务
检索竞选委员会的财务摘要。
**参数：**
- `committee_id`（必填）：FEC委员会ID（例如，“C00401224”）
- `cycle`（可选）：两年选举周期（例如，2024）
**返回：**
- 总收款和支出
- 现金余额
- 债务
- 支出比率（支出/收入比率）
- 贡献明细（个人，PAC，党派）
- 小额捐赠者百分比
**示例：**
```
获取委员会C00401224的财务摘要
```
### 获取收款
检索委员会接收的详细贡献信息（Schedule A）。
**参数：**
- `committee_id`（必填）：FEC委员会ID
- `min_amount`（可选）：最低贡献金额（默认：$1,000）
- `two_year_transaction_period`（可选）：选举周期（例如，2024）
- `cycle`（可选）：`two_year_transaction_period`的别名；自动将收款与财务周期使用对齐
- `contributor_type`（可选）：“个人”或“委员会”
- `include_notable`（可选）：包括标记优先的显著块（默认：`true`）
- `fuzzy_threshold`（可选）：参考列表标记的模糊匹配阈值（默认：`90`，范围：`80-99`）
- `limit`（可选）：结果数量（默认：20，最大：100）
- `sort_by`（可选）：“金额”或“日期”（默认：”金额“）
**示例：**
```
显示委员会C00401224的超过$5,000的前10笔贡献
```
### 获取支出
检索委员会进行的详细支出信息（Schedule B）。
**参数：**
- `committee_id`（必填）：FEC委员会ID
- `min_amount`（可选）：最低支出金额（默认：$1,000）
- `two_year_transaction_period`（可选）：选举周期
- `cycle`（可选）：`two_year_transaction_period`的别名；自动将支出与财务周期使用对齐
- `purpose`（可选）：按用途关键词筛选（例如，“媒体”，“咨询”）
- `include_notable`（可选）：包括标记优先的显著块（默认：`true`）
- `fuzzy_threshold`（可选）：参考列表标记的模糊匹配阈值（默认：`90`，范围：`80-99`）
- `limit`（可选）：结果数量（默认：20，最大：100）
- `sort_by`（可选）：“金额”或“日期”（默认：”金额“）
**示例：**
```
显示委员会C00401224的媒体相关支出超过$10,000
```
### 获取独立支出
检索独立支出（Schedule E）- 由PAC和超级PAC花费以支持或反对候选人的资金。
**参数：**
- `candidate_id`（可选）：FEC候选人ID，查看针对他们的支出
- `committee_id`（可选）：FEC委员会ID，查看其独立支出
- `support_oppose`（可选）：按“支持”或“反对”筛选
- `min_amount`（可选）：最低支出金额
- `cycle`（可选）：两年选举周期
- `limit`（可选）：结果数量（默认：20）
*注意：`candidate_id`或`committee_id`必填。*
**示例：**
```
显示反对候选人P00009423的独立支出
```
### 获取委员会标记
检查竞选委员会的合规性红旗，包括RFAI和修正案。
**参数：**
- `committee_id`（必填）：FEC委员会ID
- `cycle`（可选）：两年选举周期
**返回：**
- RFAI（额外信息请求）数量和详细信息
- 修正案数量和详细信息
- 最近的合规问题
**示例：**
```
检查委员会C00401224的任何合规性标记
```
### 搜索捐赠者
按名称、雇主或职业搜索个人捐赠者，跨越所有FEC申报。
**参数：**
- `contributor_name`（可选）：搜索捐赠者姓名
- `contributor_employer`（可选）：雇主名称（例如，“Goldman Sachs”）
- `contributor_occupation`（可选）：职业（例如，“游说者”）
- `contributor_state`（可选）：两字母的州代码
- `min_amount`（可选）：最低贡献金额（默认：$200）
- `cycle`（可选）：两年选举周期
- `limit`（可选）：结果数量（默认：20）
*注意：`contributor_name`、`contributor_employer`或`contributor_occupation`必填。*
**示例：**
```
查找加利福尼亚州“Meta”员工的贡献
```
### 搜索支出
按描述或收款人搜索竞选支出（Schedule B），跨越所有委员会。
**参数：**
- `description`（可选）：支出描述中的关键词（例如，“旅行”，“咨询”）
- `recipient_name`（可选）：收款人/供应商名称
- `recipient_state`（可选）：两字母的州代码
- `min_amount`（可选）：最低金额（默认：$500）
- `cycle`（可选）：两年选举周期
- `limit`（可选）：结果数量（默认：20）
*注意：`description`或`recipient_name`必填。*
**示例：**
```
查找所有委员会关于“高尔夫”或“度假村”的支出
```
## 开发
### 设置
```bash
npm install
```
### 运行测试
```bash
npm test # 单次运行
npm run test:coverage # 覆盖率测试
npm run test:e2e # 实时API测试，需要FEC_API_KEY
```
### 构建
```bash
npm run build
```
### 类型检查
```bash
npm run typecheck
```
### 实时验收检查
```bash
npm run acceptance:fec-day
npm run acceptance:notable
```
## API速率限制
FEC API允许每小时1,000次请求，带有API密钥。对于更高的限制（高达7,200次请求/小时），请联系FEC。
## 超时和API延迟
默认请求超时为30秒。搜索工具（`search_candidates`、`search_donors`、`search_spending`）使用60秒超时，因为这些FEC API端点执行广泛的数据库扫描，固有地较慢。
要全局覆盖默认超时，请设置环境变量 `FEC_API_TIMEOUT_MS`：
```bash
export FEC_API_TIMEOUT_MS=45000 # 45秒
```
## Docker
在本地构建容器镜像：
```bash
docker build -t fec-mcp-server .
```
在运行时提供您的API密钥：
```bash
docker run --rm -i \
-e FEC_API_KEY=您的-api-密钥-此处 \
fec-mcp-server
```
## 版本发布
Glama检查需要GitHub版本发布。在合并下一个仓库更改后，从GitHub或使用以下命令创建并发布标签：
```bash
git tag v1.0.0
git push origin v1.0.0
```
## 许可证
MIT
## 免责声明
本工具旨在用于竞选财务透明度研究。它以中立、非党派的方式提供对公共FEC数据的访问。该工具及其输出不应用于促进或反对任何候选人或政党。
## 资源
- [OpenFEC API 文档](https://api.open.fec.gov/developers/)
- [FEC.gov](https://www.fec.gov/)
- [模型上下文协议](https://modelcontextprotocol.io/)
- 参考列表归属：`github/DGA-Research/FEC_Coder_Project_Streamlit`（`resources/reference-lists/`下的捆绑快照）
