LegiScan MCP Server

Сервер протокола контекста модели (MCP), который предоставляет терминальным агентам структурированный доступ к API LegiScan для получения законодательных данных всех 50 штатов США и Конгресса.

Создан для исследовательских рабочих процессов, где вы направляете агента (Codex, Claude Code, Claude Desktop и т. д.) для быстрого сбора истории законопроектов, контекста спонсоров и протоколов голосования.

Функции

• 10 оптимизированных инструментов MCP, настроенных для рабочих процессов законодательных исследований

• Композитные инструменты, которые сворачивают многоэтапные исследовательские процессы в вызовы одного инструмента MCP

• Пакетная обработка по запросу и кэширование поиска для повторных запросов по законопроектам и поименным голосованиям

• Полные определения типов TypeScript для всех ответов API

• Нормализация номеров законопроектов (поддерживает форматы AB 858, AB858, AB-858)

• Механизмы проверки ввода для кодов штатов, запросов имен законодателей и больших пакетов законопроектов

Related MCP server: civic-awareness-mcp

Установка

Из npm (рекомендуется)

npm install -g legiscan-mcp-server

Из исходного кода

git clone https://github.com/sh-patterson/legiscan-mcp.git
cd legiscan-mcp
npm install
npm run build

Настройка

1. Получите API-ключ LegiScan

1. Создайте бесплатную учетную запись на LegiScan

2. Зарегистрируйтесь для доступа к API на странице https://legiscan.com/legiscan

3. Скопируйте свой API-ключ

2. Добавьте в свой агент с поддержкой MCP

Добавьте этот сервер в любой MCP-хост, который использует ваш терминальный агент.

Пути к конфигурации Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Для других клиентов MCP (Codex CLI, Claude Code и т. д.) добавьте ту же запись mcpServers.legiscan в файл конфигурации MCP этого клиента.

Использование npx (рекомендуется)

{
  "mcpServers": {
    "legiscan": {
      "command": "npx",
      "args": ["-y", "legiscan-mcp-server"],
      "env": {
        "LEGISCAN_API_KEY": "your_api_key_here"
      }
    }
  }
}

Использование локальной установки

{
  "mcpServers": {
    "legiscan": {
      "command": "node",
      "args": ["/path/to/legiscan-mcp-server/dist/index.js"],
      "env": {
        "LEGISCAN_API_KEY": "your_api_key_here"
      }
    }
  }
}

Доступные инструменты

Композитные инструменты (исследования высокого уровня)

Законопроекты

Люди

Поиск

Сессии

Рабочий процесс исследователя (терминальный агент)

1. Начните с ограниченного запроса

Дайте агенту цель, штат, временные рамки и формат вывода.

Пример промпта:

Use the LegiScan MCP tools to find major California housing bills in the current session.
Return: bill number, title, latest action date, top sponsors, and whether there was a close roll-call vote (margin <= 5).

2. Попросите агента выполнить последовательность инструментов

Для получения качественных результатов попросите агента следовать этому порядку:

1. legiscan_get_session_list для определения правильной сессии.

2. legiscan_search или legiscan_find_bill_by_number для поиска целевых законопроектов.

3. legiscan_get_bill для получения ссылок на спонсоров/историю/голосования.

4. legiscan_get_roll_call для получения деталей индивидуального голосования.

5. legiscan_get_person только тогда, когда требуется расширенная информация о законодателе.

Если вы начинаете с legiscan_find_legislator, продолжайте передавать возвращенный session.session_id или тот же state в последующие рабочие процессы, чтобы результаты оставались в рамках нужного законодательного органа и периода времени.

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

Они сокращают количество вызовов инструментов и упрощают инструкции для вашего агента:

• legiscan_find_legislator: получение people_id из запроса по имени.

• legiscan_get_primary_authored: отделение законопроектов, где законодатель является основным автором, от законопроектов, где он соавтор.

• legiscan_get_legislator_votes: получение позиций голосования по многим законопроектам за один запрос.

Шаблоны промптов

А) Исследование оппозиции по одному законодателю

Use LegiScan MCP for Texas.
1) Find legislator "Jane Smith".
2) List all primary-authored bills in the current session.
3) For these bills, summarize topic area and latest status.
4) Then check votes on SB 12, HB 301, and SB 455, and show how the legislator voted.

Б) Сводка по отслеживанию законопроектов для конкретной области

Use LegiScan MCP to track "climate resilience" bills in New York.
Focus on current session only.
Return top 15 bills by relevance with bill number, title, last action, sponsor party, and any recorded roll calls.

В) Рабочий процесс поддержки оценочных карт (scorecards)

For California session 2172, resolve bill numbers AB 858, SB 525, SB 616, SB 399.
For each bill, fetch details and any roll calls.
Then report vote positions for people_id values 21719, 23214, and 25359.
Output as a table suitable for CSV export.

Упрощение рабочего процесса

Композитные инструменты значительно сокращают количество обращений «агент-инструмент» для типичных рабочих процессов:

Советы по исследованию

• Коды штатов проверяются как двухбуквенные строки и автоматически переводятся в верхний регистр (ca → CA). Неверные коды, такие как ZZ, проходят локальную проверку, но возвращают ошибку API от LegiScan.

• Всегда указывайте штат и сессию в своем промпте, чтобы уменьшить количество неоднозначных результатов.

• Попросите агента отображать bill_id, roll_call_id и people_id в промежуточном выводе, чтобы вы могли проверить прослеживаемость.

• Для поиска законодателя укажите как минимум имя и фамилию (ввод имени должен содержать не менее 2 символов).

• legiscan_get_primary_authored может возвращать все доступные сессии, но передача state или session_id позволяет сохранить результаты в рамках нужного законодательного органа и периода времени.

• legiscan_get_legislator_votes принимает до 100 bill_ids за запрос; разбивайте большие задачи на части.

• legiscan_search повторяет компактные запросы номеров законопроектов, такие как AB858, используя канонический формат с пробелами. Для точного разрешения законопроекта предпочтительнее использовать legiscan_find_bill_by_number.

• Запрашивайте финальные результаты в виде таблицы или CSV, если планируете дальнейший анализ.

Разработка

npm run build        # Compile TypeScript
npm run typecheck    # Type-check src + tests
npm test             # Run deterministic unit tests (no API key)
npm run test:e2e     # Run real-world workflow tests (skips cleanly without API key)
npm run test:live    # Run live API integration tests (requires API key)
npm run test:coverage # Run unit tests with coverage
npm run lint         # Check for lint errors
npm run format       # Format code with Prettier

Режимы тестирования

• npm test / npm run test:unit: Быстрые детерминированные тесты с имитацией сетевых вызовов.

• npm run test:e2e: Тесты исследовательских рабочих процессов, основанные на реальных задачах законодательного анализа. Пропускаются, если LEGISCAN_API_KEY недоступен.

• npm run test:live: Тесты интеграции с реальным API LegiScan. Требуется LEGISCAN_API_KEY.

Лимиты API

• Бесплатные публичные API-ключи имеют лимит 30 000 запросов в месяц.

• Композитные инструменты пакетно обрабатывают запросы (максимум 10 параллельно) и кэшируют повторные поиски в рамках одного запроса, чтобы избежать ненужного дублирования.

• Композитные инструменты снижают трение в рабочем процессе MCP, но использование API LegiScan все равно масштабируется в зависимости от количества отдельных законопроектов и голосований, которые вы проверяете.

Docker

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

docker build -t legiscan-mcp .

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

docker run --rm -i \
  -e LEGISCAN_API_KEY=your-api-key-here \
  legiscan-mcp

Релизы

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

git tag v1.0.0
git push origin v1.0.0

Docker

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

docker build -t legiscan-mcp .

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

docker run --rm -i \
  -e LEGISCAN_API_KEY=your-api-key-here \
  legiscan-mcp

Релизы

Проверки Glama ожидают GitHub-релиз. Создайте и опубликуйте тег, например v1.0.0, после отправки изменений.

Лицензия

MIT — подробности см. в LICENSE.