技能介绍

要解决什么问题

基金组合研究往往卡在胶水代码上：Agent 或脚本要自己拼 HTTP 请求、处理鉴权头、轮询同步任务、维护“我的组合”归属，稍不留神就出现串号、漏刷新或回测状态滞后。这个技能把后端 REST API 封装成 19 个结构化 MCP 工具，让 Agent 直接调用 list_portfolios、get_portfolio、sync_fund_data 等能力，不用关心路径、重试和请求头细节。

核心机制

MCP Server 由后端 FastAPI 自身挂载，FastMCP 与 REST API 跑在同一个 uvicorn 进程，不单独启动服务，也不提供 stdio。启用方式是在后端 .env 设置 MCP_ENABLED=True 并重启。

传输方式：Streamable HTTP 端点 /mcp/http 推荐用于 MCP 2025 客户端；SSE 端点 /mcp/sse 仅兼容旧客户端。
身份：客户端在本机按固定机器特征计算稳定 UUID，写入 ~/.portfolio/aid，连接时作为 X-Anonymous-Id 头携带；后端只读取、不生成 ID。
工具面：组合管理、基金搜索与净值、数据同步、回测触发、账号绑定/登录/改密等。

典型同步流程是：调用 sync_fund_data(force=False) 拿到 job_id，再轮询 get_sync_status(job_id) 至 completed 或 failed，最后用 get_portfolio() 或 list_portfolios(mine=true) 查看最新净值、数据截至日和涨跌。MCP 不可连时回退到 scripts/pf.py，两者最终打到同一后端 REST。

边界与注意点

生产远程地址不会自动注入 X-Anonymous-Id，需在连接器配置里手写该头。
headers 只在 streamable-http 传输生效；SSE 客户端可能仍报 400，公开组合列表除外。
localhost 与 invest.geeyo.com 是两套独立数据库，纯匿名 ID 不会跨环境迁移；迁移组合应先在本地 bind_account，再到生产 login_account 恢复。
pf.py 使用 Python urllib 默认 UA，经 Cloudflare 可能返回 403。