FEC MCP Server

Сервер протокола контекста модели (MCP) для исследования финансирования избирательных кампаний и обеспечения прозрачности Федеральной избирательной комиссии (FEC). Этот сервер предоставляет инструменты для поиска кандидатов, получения финансовых отчетов, а также анализа взносов и расходов на основе официальных данных FEC.

Функции

• search_candidates: Поиск федеральных кандидатов по имени, фильтрация по году выборов, должности, штату или партии

• get_committee_finances: Получение финансовых сводок, включая поступления, расходы, остаток денежных средств и скорость расходования средств

• get_receipts: Получение детализированных взносов (Приложение A) с информацией о донорах

• get_disbursements: Получение детализированных расходов (Приложение B) с информацией о получателях и целях

• Flagged-first notable analysis: Дополнительные блоки примечаний для поступлений/расходов со списком ссылок и эвристическими причинами пометки

• get_independent_expenditures: Отслеживание расходов Super PAC в поддержку или против кандидатов (Приложение E)

• get_committee_flags: Проверка на наличие RFAI, поправок и связанных с ними сигналов о нарушении комплаенса

• search_donors: Поиск индивидуальных доноров по имени, работодателю или роду занятий во всех комитетах

• search_spending: Поиск расходов кампаний по описанию или получателю во всех комитетах

Все данные поступают напрямую из официального OpenFEC API.

Установка

Предварительные требования

• Node.js 20 или новее

• Ключ API FEC (бесплатно на api.open.fec.gov)

Установка из npm

npm install -g fec-mcp-server

Установка из исходного кода

git clone <repository-url>
cd fecmcp
npm install
npm run build

Конфигурация

Установите ваш ключ API FEC в качестве переменной окружения:

export FEC_API_KEY=your-api-key-here

Или создайте файл .env в корне вашего проекта:

FEC_API_KEY=your-api-key-here

Использование с Claude Desktop

Добавьте сервер в ваш файл конфигурации Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fec": {
      "command": "npx",
      "args": ["fec-mcp-server"],
      "env": {
        "FEC_API_KEY": "your-api-key-here"
      }
    }
  }
}

Или, если установлено глобально:

{
  "mcpServers": {
    "fec": {
      "command": "fec-mcp-server",
      "env": {
        "FEC_API_KEY": "your-api-key-here"
      }
    }
  }
}

Инструменты

search_candidates

Поиск кандидатов в записях FEC по имени.

Параметры:

• q (обязательно): Имя кандидата для поиска

• election_year (опционально): Фильтр по году выборов (например, 2024)

• office (опционально): Фильтр по должности - H (Палата представителей), S (Сенат), P (Президент)

• state (опционально): Фильтр по штату (2-буквенный код)

• party (опционально): Фильтр по коду партии (например, "DEM", "REP")

Пример:

Search for candidates named "Smith" running for Senate in 2024

get_committee_finances

Получение финансовой сводки для комитета кампании.

Параметры:

• committee_id (обязательно): ID комитета FEC (например, "C00401224")

• cycle (опционально): Двухлетний избирательный цикл (например, 2024)

Возвращает:

• Общие поступления и расходы

• Остаток денежных средств

• Долги

• Скорость расходования средств (соотношение расходов к доходам)

• Разбивка взносов (индивидуальные, PAC, партийные)

• Процент мелких доноров

Пример:

Get the financial summary for committee C00401224

get_receipts

Получение детализированных взносов (Приложение A), полученных комитетом.

Параметры:

• committee_id (обязательно): ID комитета FEC

• min_amount (опционально): Минимальная сумма взноса (по умолчанию: $1,000)

• two_year_transaction_period (опционально): Избирательный цикл (например, 2024)

• cycle (опционально): Псевдоним для two_year_transaction_period; автоматически выравнивает поступления с циклом использования финансов

• contributor_type (опционально): "individual" или "committee"

• include_notable (опционально): Включить блок примечаний с пометками (по умолчанию: true)

• fuzzy_threshold (опционально): Порог нечеткого соответствия для пометок в списке ссылок (по умолчанию: 90, диапазон: 80-99)

• limit (опционально): Количество результатов (по умолчанию: 20, макс: 100)

• sort_by (опционально): "amount" или "date" (по умолчанию: "amount")

Пример:

Show the top 10 contributions over $5,000 to committee C00401224

get_disbursements

Получение детализированных расходов (Приложение B), произведенных комитетом.

Параметры:

• committee_id (обязательно): ID комитета FEC

• min_amount (опционально): Минимальная сумма расхода (по умолчанию: $1,000)

• two_year_transaction_period (опционально): Избирательный цикл

• cycle (опционально): Псевдоним для two_year_transaction_period; автоматически выравнивает расходы с циклом использования финансов

• purpose (опционально): Фильтр по ключевому слову цели (например, "MEDIA", "CONSULTING")

• include_notable (опционально): Включить блок примечаний с пометками (по умолчанию: true)

• fuzzy_threshold (опционально): Порог нечеткого соответствия для пометок в списке ссылок (по умолчанию: 90, диапазон: 80-99)

• limit (опционально): Количество результатов (по умолчанию: 20, макс: 100)

• sort_by (опционально): "amount" или "date" (по умолчанию: "amount")

Пример:

Show media-related spending over $10,000 by committee C00401224

get_independent_expenditures

Получение независимых расходов (Приложение E) — денег, потраченных PAC и Super PAC для поддержки или противодействия кандидатам.

Параметры:

• candidate_id (опционально): ID кандидата FEC для просмотра расходов, направленных на него

• committee_id (опционально): ID комитета FEC для просмотра их независимых расходов

• support_oppose (опционально): Фильтр по "support" (поддержка) или "oppose" (противодействие)

• min_amount (опционально): Минимальная сумма расхода

• cycle (опционально): Двухлетний избирательный цикл

• limit (опционально): Количество результатов (по умолчанию: 20)

Примечание: Требуется либо candidate_id, либо committee_id.

Пример:

Show independent expenditures opposing candidate P00009423

get_committee_flags

Проверка комитета кампании на наличие сигналов о нарушении комплаенса, включая RFAI и поправки.

Параметры:

• committee_id (обязательно): ID комитета FEC

• cycle (опционально): Двухлетний избирательный цикл

Возвращает:

• Количество и детали RFAI (Запрос дополнительной информации)

• Количество и детали поправок

• Недавние проблемы с комплаенсом

Пример:

Check committee C00401224 for any compliance flags

search_donors

Поиск индивидуальных доноров во всех отчетах FEC по имени, работодателю или роду занятий.

Параметры:

• contributor_name (опционально): Имя донора для поиска

• contributor_employer (опционально): Имя работодателя (например, "Goldman Sachs")

• contributor_occupation (опционально): Род занятий (например, "Lobbyist")

• contributor_state (опционально): 2-буквенный код штата

• min_amount (опционально): Минимальная сумма взноса (по умолчанию: $200)

• cycle (опционально): Двухлетний избирательный цикл

• limit (опционально): Количество результатов (по умолчанию: 20)

Примечание: Требуется хотя бы один из параметров: contributor_name, contributor_employer или contributor_occupation.

Пример:

Find contributions from employees of "Meta" in California

search_spending

Поиск расходов кампании (Приложение B) во всех комитетах по описанию или получателю.

Параметры:

• description (опционально): Ключевое слово в описании расхода (например, "travel", "consulting")

• recipient_name (опционально): Имя получателя/поставщика

• recipient_state (опционально): 2-буквенный код штата

• min_amount (опционально): Минимальная сумма (по умолчанию: $500)

• cycle (опционально): Двухлетний избирательный цикл

• limit (опционально): Количество результатов (по умолчанию: 20)

Примечание: Требуется хотя бы один из параметров: description или recipient_name.

Пример:

Find spending on "golf" or "resort" across all committees

Разработка

Настройка

npm install

Запуск тестов

npm test          # Watch mode
npm run test:run  # Single run
npm run test:coverage  # With coverage

Сборка

npm run build

Проверка типов

npm run typecheck

Проверки в реальном времени

npm run acceptance:fec-day
npm run acceptance:notable

Ограничения API

API FEC разрешает 1000 запросов в час с ключом API. Для получения более высоких лимитов (до 7200 запросов в час) свяжитесь с FEC.

Тайм-ауты и задержка API

Тайм-аут запроса по умолчанию составляет 30 секунд. Инструменты поиска (search_candidates, search_donors, search_spending) используют тайм-аут 60 секунд, так как эти конечные точки API FEC выполняют обширное сканирование базы данных и работают медленнее.

Чтобы глобально переопределить тайм-аут по умолчанию, установите переменную окружения FEC_API_TIMEOUT_MS:

export FEC_API_TIMEOUT_MS=45000  # 45 seconds

Docker

Соберите образ контейнера локально:

docker build -t fec-mcp-server .

Запустите его с вашим ключом API, предоставленным во время выполнения:

docker run --rm -i \
  -e FEC_API_KEY=your-api-key-here \
  fec-mcp-server

Релизы

Проверки Glama ожидают релиз на GitHub. После слияния ваших следующих изменений в репозиторий, создайте и опубликуйте тег, например v1.0.0, через GitHub или с помощью:

git tag v1.0.0
git push origin v1.0.0

Лицензия

MIT

Отказ от ответственности

Этот инструмент предназначен для исследований прозрачности финансирования избирательных кампаний. Он предоставляет доступ к публичным данным FEC нейтральным, беспартийным образом. Инструмент и его результаты не должны использоваться для продвижения или противодействия какому-либо кандидату или политической партии.

Ресурсы

• Документация OpenFEC API

• FEC.gov

• Протокол контекста модели

• Атрибуция списка ссылок: github/DGA-Research/FEC_Coder_Project_Streamlit (снимки в комплекте в resources/reference-lists/)