Morning Brief MCP

An independent, deterministic A-share morning brief service. It does not rely on AlphaAgent, XQ, internal databases, or LLM Key, and exposes the existing MorningBriefService through the standard MCP stdio transport while retaining the normal Python invocation method.

Features

The service exposes 4 MCP tools:

• generate_morning_brief(target_date=None, output_format="json"|"markdown"): Generate a complete morning brief.

• get_morning_news(target_date=None, categories=None, limit_per_category=5): Return events after window filtering, deduplication, clustering, classification, and relevance ranking.

• get_previous_close_context(target_date=None): Return the A-share market context of the previous trading day corresponding to this morning brief.

• get_news_coverage(target_date=None): Return news provider status, roles, metrics, and coverage, without raw payloads or authentication information.

All tools target a confirmed A-share target trading day; the results are deterministic compilations of source evidence and do not constitute investment advice.

Environment and Installation

• Python 3.11+

• MCP Python SDK >=2.0.0,<3 (currently accepted stable version: 2.0.0)

• HITHINK_FINANCE_API_KEY (used for the trading calendar and previous trading day market context)

Morning brief news comes directly from domestic public financial web providers; no Brave Key is needed. Do not commit real .env files:

$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]"

Plain Python Invocation

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 Startup

Start directly after installation:

morning-brief-mcp

You can also use the generic command + args + env client configuration:

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

target_date must strictly use YYYY-MM-DD. When omitted, the current date in Asia/Shanghai is used, and is then still verified by the HiThink trading calendar; non-trading days return target_not_trading_day and the date is not silently changed.

Date, parameter, configuration, and upstream errors return stable invalid_request, target_not_trading_day, provider_unavailable, or upstream_error structures, respectively. A business report with status="partial" is still a successful tool result, for example when a single news source fails but other data is sufficient to generate the morning brief. The stdio server does not print debug information to stdout; stdout only carries the MCP protocol.

Data Architecture

News discovery directly accesses the public web interfaces of domestic financial sites by default:

As long as at least two primary providers from different upstream domains actually paginate to news_window.start, GDELT will not be called in this round. Only when full-window coverage is insufficient is GDELT used as a last fallback; latest-only success is not counted as full-window coverage.

HiThink is only responsible for the trading calendar, the previous trading day, and previous-close market context; it does not participate in news discovery.

News Window and Pipeline

The morning brief window is fixed from 15:00 of the previous trading day to 08:30 of the target trading day, in the Asia/Shanghai timezone, with both boundaries inclusive. All providers are first mapped to the unified fields:

id, title, url, canonical_url, source, domain, published_at, description, language, category, tags, source_tier, provider, raw_source_id.

Then it continues through the existing deterministic pipeline:

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

Multi-source reports of the same event display only one cluster, while retaining related_sources and related_count. The representative item is determined by Tier, time, and information completeness. The description stores only the upstream real brief/summary/content snippet/hover, without programmatic expansion.

Rate Limiting, Failure Isolation, and Security

Each domain shares one HTTP session and a rate limiter. Requests have timeout, bounded retries, Retry-After, exponential backoff, and jitter. 东方财富 defaults to serial execution with a minimum interval of 1 second. A single provider failure only records its status, warning, and metrics, and does not block other providers.

Pagination is limited by DOMESTIC_MAX_PAGES and DOMESTIC_MAX_ITEMS. Each provider records page count, raw item count, oldest time, stop reason, and HTTP request/429/403/retry counts.

The API Key is read only from environment variables; it never becomes a tool parameter and never appears in tool descriptions, logs, schema, or MCP results. Diagnostic tools do not return request headers, full upstream payloads, pre-signed URLs, or internal secrets.

Tests and Real Smoke

Default tests are completely offline; all HTTP behavior uses fixtures/MockTransport:

PYTHONPATH=src python -m pytest

After configuring the HiThink Key, you can use the official MCP Python client to run a real subprocess smoke and compare key Service and MCP fields:

python scripts/stdio_smoke.py

Content and Licensing Notes

These providers use public web interfaces solely for data discovery and link aggregation. The open-source implementation license is not equivalent to the upstream news content license; before production or commercial deployment, users must independently confirm each upstream's terms of service, crawling policy, and content usage license. See THIRD_PARTY_NOTICES.md for the reference implementation and license records.

This service is for market information organization and research and does not constitute investment advice.