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에 있습니다.

본 서비스는 시장 정보 정리 및 연구용으로, 투자 조언을 구성하지 않습니다.