Finance MCP 方案

HuluVest 已完成第一阶段 A 股行情接入：组合页通过 Cloudflare Pages Function 获取、清洗并缓存公开延时行情。Yahoo Finance 与 AkShare 的多市场 Finance MCP 仍属于后续扩展方案。

实施状态（2026-08-18）：A 股持仓的最新可用价格、市值和浮动盈亏已接入；数据为延时/日级、尽力而为，不承诺商业级实时性或稳定性。

在本文中

已实施功能
后续目标
数据源分工
MCP 工具
收益率计算
缓存与限频
项目结构
实现路线

已实施功能

组合页按六位证券代码请求 /api/quotes，浏览器不直接连接第三方行情源。
服务端校验代码，统一返回证券名称、最新可用价格、涨跌幅、行情时间、来源与缺失项。
边缘缓存 5 分钟；请求超时会重试一次；刷新失败时保留并显示上次成功快照。
只有所有持仓均取得有效价格时，才汇总当前市值与浮动盈亏，避免把缺失价格误当成零。

后续目标

后续阶段将扩展日级历史行情和日级收益率。MCP 负责获取、缓存、清洗和标准化数据，静态前端只展示结果。

本方案仅用于教学和研究，不构成投资建议，也不承诺商业级实时性或稳定性。

数据源分工

当前线上：腾讯公开行情

用于组合页的 A 股最新可用价格。服务端会标注来源与行情时间，并按延时/日级、尽力而为数据处理；该来源不等同于券商实时行情。

Yahoo Finance

后续拟用于美股、港股、海外 ETF 和部分跨市场资产。常见符号包括 AAPL、VOO、QQQ、0700.HK、510300.SS、159919.SZ。

AkShare

后续拟用于中国市场的历史数据，包括 A 股、中国 ETF、公募基金、指数、宏观和行业板块。AkShare 不需要 API key，但需要限频和缓存。

MCP 工具

MCP 对外暴露 HuluVest 统一工具，不直接暴露 provider 名称。

search_instrument(query, market, assetType)
get_daily_prices(symbol, market, startDate, endDate, adjust)
get_daily_returns(symbol, market, startDate, endDate, returnMethod)
get_portfolio_daily_returns(holdings, startDate, endDate)
compare_daily_returns(symbols, startDate, endDate)

底层默认路由：

CN stock / CN ETF / CN fund / CN index -> AkShare
US stock / US ETF / HK stock / global ETF -> Yahoo Finance

收益率计算

默认使用简单收益率。

return_t = close_t / close_{t-1} - 1
nav_t = nav_{t-1} * (1 + return_t)
portfolio_return_t = sum(weight_i * return_i_t)

第一阶段不处理汇率换算、交易费用、税费、分红再投资细节和复杂调仓规则。

缓存与限频

当前线上接口使用 Cloudflare 边缘缓存，TTL 为 5 分钟。后续独立 MCP server 可增加本地缓存目录：

mcp/finance-server/.cache/

建议 TTL：

日级行情：24 小时
日级收益率：24 小时
搜索结果：24 小时
基金净值：24 小时
宏观数据：7 天

建议限频：

AkShare：同一 provider 请求间隔 1-3 秒
Yahoo Finance：同一 provider 请求间隔 1 秒
失败重试：最多 2 次

项目结构

建议用 Python 实现 MCP，因为 AkShare 和 yfinance 都是 Python 生态最方便。

mcp/
  finance-server/
    pyproject.toml
    src/
      huluvest_finance_mcp/
        server.py
        models.py
        cache.py
        rate_limit.py
        providers/
          yahoo.py
          akshare_provider.py
        tools/
          prices.py
          returns.py
          portfolio.py
        normalize/
          symbols.py
          prices.py
          returns.py

实现路线

Phase 1（已上线）

通过 Cloudflare Pages Function 接入 A 股最新可用延时行情，完成代码标准化、超时重试、边缘缓存、来源与时间标注、部分失败提示和前端快照降级。

Phase 2

实现 get_daily_prices、get_daily_returns、get_portfolio_daily_returns，并评估 AkShare 与 Yahoo Finance 的多市场适配。

Phase 3

实现 search_instrument、compare_daily_returns，并生成单资产、ETF 对比和投资组合收益率报告。