Morning Brief MCP

Независимый, детерминированный сервис утреннего обзора A-акций. Он не зависит от AlphaAgent, XQ, внутренних баз данных или LLM Key и предоставляет существующий MorningBriefService через стандартный MCP stdio transport, сохраняя при этом обычный способ вызова из Python.

Функции

Сервис предоставляет 4 инструмента MCP:

• generate_morning_brief(target_date=None, output_format="json"|"markdown"): генерирует полный утренний обзор.

• get_morning_news(target_date=None, categories=None, limit_per_category=5): возвращает события после фильтрации по окну, дедупликации, кластеризации, классификации и сортировки по релевантности.

• get_previous_close_context(target_date=None): возвращает рыночный контекст A-акций за предыдущий торговый день, соответствующий данному утреннему обзору.

• get_news_coverage(target_date=None): возвращает статус новостных провайдеров, роли, метрики и покрытие без исходных payload и учётных данных.

Все инструменты ориентированы на подтверждённый целевой торговый день A-акций; результат — детерминированная сводка доказательств из источников и не является инвестиционной рекомендацией.

Окружение и установка

• Python 3.11+

• MCP Python SDK >=2.0.0,<3 (текущая стабильная версия для приёмки: 2.0.0)

• HITHINK_FINANCE_API_KEY (для торгового календаря и рыночного контекста предыдущего торгового дня)

Новости для утреннего обзора берутся напрямую из публичных финансовых веб-провайдеров Китая; Brave Key не требуется. Не коммитьте реальный .env:

$env:HITHINK_FINANCE_API_KEY="your-key"

python -m venv .venv
# Windows
.venv\Scripts\python -m pip install -e ".[test]"
# macOS/Linux
.venv/bin/python -m pip install -e ".[test]"

Обычный вызов из Python

from morning_brief_mcp.renderers.markdown import render_markdown
from morning_brief_mcp.services.morning_brief import MorningBriefService

service = MorningBriefService()
try:
    report = service.generate("2026-08-17")
    markdown = render_markdown(report)
finally:
    service.close()

Запуск MCP stdio

После установки запустите напрямую:

morning-brief-mcp

Также можно использовать универсальную конфигурацию клиента command + args + env:

{
  "mcpServers": {
    "morning-brief-mcp": {
      "command": "python",
      "args": ["-m", "morning_brief_mcp.server"],
      "env": {
        "HITHINK_FINANCE_API_KEY": "${HITHINK_FINANCE_API_KEY}"
      }
    }
  }
}

target_date должен строго использовать формат YYYY-MM-DD. Если он опущен, используется текущая дата в Asia/Shanghai, после чего она всё равно проверяется по торговому календарю HiThink; для неторгового дня возвращается target_not_trading_day, без тихой подмены даты.

Ошибки даты, параметров, конфигурации и вышестоящего сервиса возвращаются в стабильных структурах invalid_request, target_not_trading_day, provider_unavailable или upstream_error соответственно. status="partial" в бизнес-отчёте по-прежнему является успешным результатом инструмента — например, когда один источник новостей недоступен, но остальных данных достаточно для формирования утреннего обзора. stdio-сервер не выводит отладочную информацию в stdout; stdout используется только для протокола MCP.

Архитектура данных

По умолчанию обнаружение новостей напрямую обращается к публичным веб-интерфейсам китайских финансовых сайтов:

Если по крайней мере два primary-провайдера с разных upstream-доменов реально дошли до news_window.start, GDELT в этом цикле не вызывается. GDELT используется только как последний запасной вариант, когда покрытие полного окна недостаточно; успех в режиме latest-only не засчитывается как покрытие полного окна.

HiThink отвечает только за торговый календарь, предыдущий торговый день и рыночный контекст previous-close и не участвует в обнаружении новостей.

Окно новостей и конвейер

Окно утреннего обзора фиксировано: с 15:00 предыдущего торгового дня до 08:30 целевого торгового дня, часовой пояс Asia/Shanghai, обе границы включительно.

Все провайдеры сначала отображаются в единые поля:

id、title、url、canonical_url、source、domain、

published_at、description、language、category、tags、

source_tier、provider、raw_source_id.

Затем продолжается существующий детерминированный конвейер:

exact time filter → canonicalize → dedup/event cluster → classify → relevance → today_watch

Многоисточниковые сообщения об одном и том же событии отображаются одним кластером, сохраняя related_sources и related_count. Представительный элемент определяется по Tier, времени и полноте информации. В description сохраняется только реальный brief/summary/content snippet/hover от источника, без программного расширения.

Ограничение скорости, изоляция сбоев и безопасность

Каждый домен использует общую HTTP-сессию и rate limiter. Запросы имеют timeout, ограниченное количество повторов, Retry-After, экспоненциальную задержку и джиттер. 东方财富 по умолчанию выполняется последовательно с минимальным интервалом 1 секунда. Сбой одного провайдера фиксируется только в его status, warning и metrics и не блокирует других провайдеров.

Пагинация ограничена DOMESTIC_MAX_PAGES и DOMESTIC_MAX_ITEMS. Каждый провайдер записывает количество страниц, исходное количество элементов, самое старое время, причину остановки и счётчики HTTP request/429/403/retry.

API-ключ читается только из переменной окружения; он не становится параметром инструмента и не появляется в описании инструмента, логах, schema или MCP result. Диагностические инструменты не возвращают заголовки запросов, полные upstream payload, предварительно подписанные URL или внутренние секреты.

Тесты и реальный smoke

По умолчанию тесты полностью офлайн, всё HTTP-поведение использует fixtures/MockTransport:

PYTHONPATH=src python -m pytest

После настройки HiThink Key можно запустить реальный smoke в дочернем процессе с помощью официального MCP Python client и сравнить ключевые поля Service и MCP:

python scripts/stdio_smoke.py

Содержимое и лицензионные примечания

Эти провайдеры используют публичные веб-интерфейсы только для обнаружения данных и агрегации ссылок. Лицензия открытой реализации не равна лицензии на контент вышестоящих новостных источников; перед производственным или коммерческим развёртыванием пользователь должен самостоятельно проверить условия обслуживания, политику парсинга и лицензии на использование контента каждого вышестоящего источника. Справочная реализация и сведения о лицензиях приведены в THIRD_PARTY_NOTICES.md.

Сервис предназначен для систематизации рыночной информации и исследований и не является инвестиционной рекомендацией.