ph-civic-data-mcp

Первый MCP-сервер для данных правительства Филиппин — землетрясения, погода, тайфуны, закупки, население и качество воздуха — в вашем ИИ-агенте.

ph-civic-data-mcp — это бесплатный MCP-сервер с транспортом stdio, который предоставляет актуальные данные от PHIVOLCS, PAGASA, PhilGEPS, PSA и AQICN/EMB в виде инструментов, которые могут напрямую вызывать Claude Desktop, Claude Code, Cursor или любой другой MCP-совместимый клиент.

Демонстрация

Каждый GIF ниже — это реальная запись VHS из docs/live_demo.py. Он запускает uvx ph-civic-data-mcp из этого релиза PyPI и вызывает каждый инструмент через реальный протокол MCP stdio. Панели, которые вы видите, содержат фактический JSON, возвращенный сервером. Ничего не подстроено.

Общий обзор 8 инструментов из всех 5 источников за один сеанс:

Пошаговые руководства по каждому источнику приведены ниже. Чтобы воспроизвести любой из них локально: uv run python docs/live_demo_single.py <suite>.

Зачем это нужно

Порталы гражданских данных Филиппин публикуют открытые данные, но каждый в своей схеме — парсинг HTML-таблиц, PXWeb JSON, недокументированные API. Ничто не объединяет их для ИИ-агента. Этот сервер делает это.

На апрель 2026 года на GitHub или PyPI нет аналогов. Ближайшие: panukatan/lindol (R, только PHIVOLCS), pagasa-parser (JS, только PAGASA).

Установка

uvx ph-civic-data-mcp

Или через pip:

pip install ph-civic-data-mcp

Настройка

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ph-civic-data": {
      "command": "uvx",
      "args": ["ph-civic-data-mcp"],
      "env": {
        "AQICN_TOKEN": "your_free_token_from_aqicn.org",
        "PAGASA_API_TOKEN": "optional_pagasa_token"
      }
    }
  }
}

Claude Code

Добавьте в .claude/settings.json:

{
  "mcpServers": {
    "ph-civic-data": {
      "command": "uvx",
      "args": ["ph-civic-data-mcp"],
      "env": {
        "AQICN_TOKEN": "your_token"
      }
    }
  }
}

Или установите через CLI Claude Code:

claude mcp add ph-civic-data -- uvx ph-civic-data-mcp

Cursor, Zed и другие MCP-клиенты

Работает любой клиент, поддерживающий транспорт stdio MCP. Укажите команду uvx ph-civic-data-mcp и передайте AQICN_TOKEN в качестве переменной окружения.

Что можно спросить

После настройки спросите своего агента:

• "Какие землетрясения произошли на Филиппинах за последние 24 часа?"

• "Активен ли вулкан Тааль прямо сейчас?"

• "Какой прогноз погоды на 3 дня для Кесон-Сити?"

• "Есть ли сейчас активные тайфуны на Филиппинах?"

• "Найди контракты по борьбе с наводнениями на PhilGEPS."

• "Какова численность населения региона VII по данным PSA?"

• "Каков уровень бедности в регионе Биколь?"

• "Каково качество воздуха в Маниле прямо сейчас?"

• "Составь профиль рисков для Лейте с учетом нескольких опасностей."

Демонстрации по источникам

PHIVOLCS — землетрясения + уровни тревоги вулканов

PAGASA — прогноз погоды + отслеживание тайфунов

PhilGEPS — поиск закупок + агрегация

PSA — население (перепись 2020 г.) + бедность (полный 2023 г.)

AQICN — качество воздуха в реальном времени

Кросс-источники — параллельный профиль рисков

Как создаются демонстрации

docs/live_demo.py + docs/live_demo_single.py открывают MCP StdioTransport, указывающий на uvx ph-civic-data-mcp (который разрешается в этот релиз PyPI), вызывают инструменты и отображают ответы с помощью Rich (панели, таблицы, JSON с подсветкой синтаксиса, живые спиннеры). vhs управляет реальным терминалом и записывает сеанс. Записи зафиксированы в docs/*.tape.

Источники данных

Все инструменты

Переменные окружения

Примечание: демонстрационный токен AQICN возвращает данные только для Шанхая и не будет работать для филиппинских городов. Вы должны зарегистрироваться для получения реального токена (бесплатно, <1 минута).

Предупреждения о свежести данных

• Население: Перепись 2020 года. Более поздних национальных данных пока не существует.

• Бедность: Статистика бедности за 2023 год (последний релиз PSA).

• Закупки: Открытые данные PhilGEPS не предоставляют внешнего поиска с фильтрацией. Этот сервер парсит последние ~100 уведомлений и фильтрует их на стороне клиента. Кэшируется на 6 часов.

• Чрезвычайные ситуации: для реагирования на стихийные бедствия в реальном времени всегда проверяйте ndrrmc.gov.ph и официальные каналы PHIVOLCS/PAGASA. Этот сервер предназначен для исследований, а не для принятия решений, влияющих на жизнь.

Архитектура

• Python 3.11+, fastmcp>=3.0.0,<4.0.0

• Два HTTP-клиента: стандартный + PHIVOLCS_CLIENT с verify=False (у PHIVOLCS повреждена цепочка SSL-сертификатов). SSL-верификация никогда не отключается глобально.

• TTL-кэши в памяти для каждого источника; запись на диск отсутствует.

• Только транспорт stdio (нулевые затраты на хостинг).

• Пути к таблицам PSA обнаруживаются через API просмотра PXWeb, никогда не прописываются жестко.

Разработка

git clone https://github.com/xmpuspus/ph-civic-data-mcp
cd ph-civic-data-mcp
uv sync --extra dev

# MCP Inspector
fastmcp dev src/ph_civic_data_mcp/server.py

# Tests (run against live APIs)
uv run pytest tests/ -v

# Build
uv run python -m build
uv run twine check dist/*

Ограничения

• Токен PAGASA ограничен. Неправительственным пользователям может быть отказано. Резервный вариант Open-Meteo снимает эту жесткую зависимость.

• Требуется токен AQICN. Бесплатный, но его нужно запросить.

• PhilGEPS не работает в реальном времени. Публичный портал не предоставляет API с фильтрацией; сервер работает с последними ~100 уведомлениями с фильтрацией на стороне клиента.

• Чрезвычайные ситуации: направляйте пользователей на официальные каналы; это исследовательский инструмент.

Дорожная карта (v0.2.0)

• get_active_disasters / get_situational_report через мониторинговую панель NDRRMC

• assess_hazard(lat, lng) через HazardHunterPH ArcGIS REST API — риск наводнения/землетрясения/оползня для конкретных координат

Аналоги

• panukatan/lindol — R-пакет для землетрясений PHIVOLCS

• pagasa-parser — JS-организация для парсинга данных PAGASA

Ни один из них не является Python-проектом, не поддерживает несколько источников и не является MCP. Этот проект отдает должное обоим.

Лицензия

MIT. Xavier Puspus. Не связан с PHIVOLCS, PAGASA, PhilGEPS, PSA или EMB.

Участие

Вопросы и PR приветствуются на github.com/xmpuspus/ph-civic-data-mcp.