Finance MCP 方案

HuluVest Finance MCP 用于教学、研究和静态页面生成辅助。第一阶段使用 Yahoo Finance 与 AkShare，重点获取日级股票、ETF、基金、指数行情，以及由价格计算出的日级收益率。

在本文中

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

目标

第一阶段专注两类数据：日级行情数据和日级收益率数据。MCP 负责获取、缓存、清洗和标准化数据，静态前端只展示结果。

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

数据源分工

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)

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

缓存与限频

建议缓存放在 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

实现 get_daily_prices、get_daily_returns、get_portfolio_daily_returns。支持 Yahoo Finance 的美股/ETF，AkShare 的中国股票/ETF。

Phase 2

实现 search_instrument 和 compare_daily_returns，增加符号规范化和更完整的错误处理。

Phase 3

生成静态 JSON 和 HTML 报告页面，例如单资产日收益率页面、ETF 对比页面和投资组合收益率页面。