Morning Brief MCP

独立、确定性的 A 股晨报服务。它不依赖 AlphaAgent、XQ、内部数据库或 LLM Key， 通过标准 MCP stdio transport 暴露现有 MorningBriefService，同时保留普通 Python 调用方式。

功能

服务暴露 4 个 MCP tools：

• 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)：返回新闻 provider 状态、角色、指标和覆盖情况，不包含原始 payload 或认证信息。

所有 tool 都面向确认的 A 股目标交易日，结果是确定性的来源证据整理，不构成投资建议。

环境与安装

• Python 3.11+

• MCP Python SDK >=2.0.0,<3（当前验收稳定版：2.0.0）

• HITHINK_FINANCE_API_KEY（用于交易日历和上一交易日市场背景）

晨报新闻直接来自国内公开财经 Web provider，不需要 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" 仍是成功的 tool result，例如单个新闻源失败但其他数据足以生成晨报。 stdio server 不向 stdout 打印调试信息；stdout 仅承载 MCP protocol。

数据架构

新闻发现默认直接访问国内财经站点的公开 Web 接口：

只要至少两个不同 upstream domain 的 primary provider 实际翻页到 news_window.start，本轮就不会调用 GDELT。只有完整窗口覆盖不足时才使用 GDELT 作为最后 fallback；latest-only 成功不会被计为完整窗口覆盖。

HiThink 只负责交易日历、上一交易日和 previous-close 市场背景，不参与新闻发现。

新闻窗口与流水线

晨报窗口固定为上一交易日 15:00 到目标交易日 08:30，时区为 Asia/Shanghai，两个边界均包含。所有 provider 先映射到统一字段：

id、title、url、canonical_url、source、domain、 published_at、description、language、category、tags、 source_tier、provider、raw_source_id。

之后继续走已有 deterministic pipeline：

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

同一事件的多源报道只展示一个 cluster，并保留 related_sources 与 related_count。代表项按 Tier、时间和信息完整度确定。description 只保存上游 真实 brief/summary/content snippet/hover，不做程序扩写。

限流、失败隔离与安全

每个 domain 共享一个 HTTP session 和 rate limiter。请求具有 timeout、有界重试、 Retry-After、指数退避和抖动。东方财富默认串行且最小间隔 1 秒。单一 provider 失败只记录其 status、warning 和 metrics，不会阻断其他 provider。

分页均受 DOMESTIC_MAX_PAGES 与 DOMESTIC_MAX_ITEMS 限制。每个 provider 记录页数、原始条数、最老时间、停止原因以及 HTTP request/429/403/retry 计数。

API Key 只从环境变量读取；它不会成为 tool 参数，也不会出现在 tool description、 日志、schema 或 MCP result 中。诊断 tool 不返回请求 Header、完整 upstream payload、 预签名 URL 或内部 secret。

测试与真实 smoke

默认测试完全离线，所有 HTTP 行为均使用 fixtures/MockTransport：

PYTHONPATH=src python -m pytest

配置 HiThink Key 后，可用官方 MCP Python client 运行真实子进程 smoke，并对比 Service 与 MCP 关键字段：

python scripts/stdio_smoke.py

内容与许可说明

这些 provider 使用公开 Web 接口，仅用于数据发现和链接聚合。开源实现许可证不 等于上游新闻内容许可证；生产或商业部署前，使用者必须自行确认各上游服务条款、 抓取政策和内容使用许可。参考实现与许可证记录见 THIRD_PARTY_NOTICES.md。

本服务用于市场信息整理和研究，不构成投资建议。

License

本项目采用 Apache License 2.0，详见 LICENSE。

第三方代码参考与归属说明见 THIRD_PARTY_NOTICES.md。