MCP协议¶

📎 引用文件

本文引用的文件 - mcp_server.py - mcp.py - schema.py - service.py - test_mcp_client_adapter.py - test_mcp_json_string_args.py - test_default_deny_unknown_robinhood_tool.py - README_zh.md

目录¶

简介
项目结构
核心组件
架构总览
详细组件分析
依赖关系分析
性能考虑
故障排查指南
结论
附录

简介¶

本技术文档面向 Vibe-Trading 的 Model Context Protocol（MCP）服务器实现，聚焦以下目标： - 连接建立与传输：支持 stdio、SSE 与 Streamable HTTP 三种传输；提供网络传输的主机/来源白名单防护。 - 消息格式与工具调用：统一 JSON 信封、参数规范化、远程工具包装与执行、错误封装。 - 事件处理与会话集成：研究目标生命周期、证据追加、状态更新与审计。 - 支持的 MCP 工具清单、参数规范与返回值格式。 - 与 Agent 系统的集成方式：工具注册、上下文传递、会话级配置覆盖、状态管理。 - MCP 客户端集成示例：连接配置、工具调用、错误处理。 - 性能优化建议、调试工具与监控方法。 - MCP 在 AI 代理工作流中的作用与扩展机制。

项目结构¶

Vibe-Trading 的 MCP 能力由“本地 MCP 服务”和“外部 MCP 客户端适配器”两部分组成： - 本地 MCP 服务：暴露 64 个只读/研究类工具，供任意 MCP 客户端通过 stdio/SSE/HTTP 访问。 - 外部 MCP 客户端适配器：将已配置的远程 MCP 服务端工具以本地 BaseTool 形式注册到 Agent 工具注册表，供 Agent 循环调用。

graph TB Client["MCP 客户端"] --> Transport["传输层<br/>stdio / SSE / Streamable HTTP"] Transport --> Server["本地 MCP 服务<br/>FastMCP"] Server --> Tools["内置工具集<br/>技能/研究/回测/行情/新闻等"] Server --> GoalStore["研究目标存储"] Server --> Registry["Agent 工具注册表"] Adapter["MCP 客户端适配器"] --> RemoteServer["远程 MCP 服务端"] Adapter --> Registry

图表来源 - mcp_server.py:69-81 - mcp.py:143-206

章节来源 - mcp_server.py:1-81 - README_zh.md:1113-1117

核心组件¶

本地 MCP 服务（FastMCP 应用）
启动入口、传输选择、安全中间件、工具注册、研究目标生命周期。
MCP 客户端适配器
发现远程工具、构建本地包装、参数过滤、结果归一化、重试策略、OAuth 与持久缓存。
配置模型
MCPServerConfig、MCPOAuthConfig、AgentConfig 校验与约束（含券商白名单限制）。
会话服务
会话创建、消息发送、并发控制、事件总线。

章节来源 - mcp_server.py:69-81 - mcp.py:143-206 - schema.py:349-411 - service.py:53-117

架构总览¶

下图展示从 MCP 客户端到本地/远程工具的完整调用链，包括认证、工具发现、参数规范化与结果封装。

sequenceDiagram participant C as "MCP 客户端" participant T as "传输层" participant S as "本地 MCP 服务" participant A as "MCP 客户端适配器" participant R as "远程 MCP 服务端" participant G as "研究目标存储" C->>T : 初始化请求 T->>S : 路由到 FastMCP S-->>C : 版本/能力响应 C->>S : tools/list S-->>C : 工具列表本地 + 已注册 C->>S : tools/call(本地工具) S->>G : 读取/写入研究目标 S-->>C : JSON 成功/失败信封 C->>A : 通过 Agent 调用远程工具 A->>R : list_tools带重试 R-->>A : 工具定义输入Schema A->>R : call_tool参数过滤+超时 R-->>A : 原始结果 A-->>C : 标准化JSON信封

图表来源 - mcp_server.py:69-81 - mcp.py:401-473 - mcp.py:537-589

详细组件分析¶

本地 MCP 服务（FastMCP）¶

传输与安全
支持 stdio、SSE、Streamable HTTP；网络传输启用 Host/Origin 白名单中间件，默认仅环回地址。
可通过环境变量开启 shell 工具（默认关闭），避免进程控制面被滥用。
工具注册
内置工具涵盖技能、研究目标、回测、因子分析、期权、市场数据、资金流、新闻、研报、机构持仓、ETF穿透、预测市场、论文检索、Swarm 编排、交易流水与影子账户分析等。
所有暴露工具均为只读或研究用途，不暴露下单/撤单工具。
研究目标生命周期
start_research_goal：创建或替换当前研究目标，支持预算、风险等级、协议与检查项。
get_research_goal：获取当前目标快照。
add_goal_evidence：追加可追溯证据，支持来源、时间范围、假设、置信度与矛盾声明。
update_research_goal_status：完成/取消/阻塞/暂停并附带审计行。

flowchart TD Start(["工具调用入口"]) --> Validate["参数校验与清洗"] Validate --> Type{"工具类型?"} Type --> |研究目标| GoalOps["创建/读取/追加证据/更新状态"] Type --> |回测/因子/期权| BizOps["业务工具执行"] Type --> |数据/搜索/研报| DataOps["数据源查询与聚合"] GoalOps --> Envelope["返回标准JSON信封"] BizOps --> Envelope DataOps --> Envelope Envelope --> End(["结束"])

图表来源 - mcp_server.py:530-735 - mcp_server.py:743-800

章节来源 - mcp_server.py:86-128 - mcp_server.py:131-317 - mcp_server.py:495-735 - mcp_server.py:743-800

MCP 客户端适配器（远程工具包装）¶

工具发现与缓存
基于配置键生成内容哈希缓存 key，线程安全地缓存工具发现结果。
支持 transient 错误重试（list_tools），但工具调用不自动重试以避免副作用重复。
名称与冲突处理
生成稳定本地工具名 mcp__；对命名冲突进行确定性去重并输出操作者可见警告。
参数与 Schema 规范化
将远程 inputSchema 归一化为 OpenAI 兼容对象；清理 anyOf/null 分支；折叠 type 列表中的 null。
针对部分 MCP 客户端将 list/dict 序列化为 JSON 字符串的问题，提供 BeforeValidator 解码。
OAuth 与持久缓存
为 Streamable HTTP 支持 OAuth，使用 FileTreeStore 持久化刷新令牌，权限 0700。
init_timeout 默认不低于 tool_timeout 且至少 30s，适配冷启动与浏览器授权场景。

classDiagram class MCPServerAdapter { +discover_tools() list +call_tool(remote_name, arguments) dict -_build_client() AsyncMCPClient -_list_tools_once() list -_call_tool(remote_name, arguments) CallToolResult -_run_with_retry(operation, attempts) ResultT } class MCPRemoteTool { +name string +description string +parameters dict +execute(**kwargs) string -_filter_arguments(arguments) dict } class MCPServerConfig { +type string +command string +args list +env dict +url string +headers dict +auth MCPOAuthConfig +tool_timeout float +init_timeout float +enabled_tools list } MCPRemoteTool --> MCPServerAdapter : "使用" MCPServerAdapter --> MCPServerConfig : "读取配置"

图表来源 - mcp.py:143-206 - mcp.py:370-473 - mcp.py:629-694 - schema.py:349-411

章节来源 - mcp.py:62-84 - mcp.py:209-287 - mcp.py:289-324 - mcp.py:340-367 - mcp.py:401-473 - mcp.py:537-589 - mcp.py:629-694

配置与约束（含券商安全）¶

传输与字段校验
stdio 必须提供 command；URL 类 transport 必须显式 type（sse/streamableHttp）；OAuth 必须 HTTPS。
OAuth 与静态 headers 互斥，防止 Authorization 头冲突。
实盘券商白名单与通配符限制
对 live broker（如 Robinhood、IBKR）禁止 enabledTools=["*"]，除非满足特定 read-only 探测条件（例如 IBKR 的 mcp.read 范围）。
提供 Robinhood 只读种子配置与 IBKR 只读种子配置，确保首次探测安全。
会话级覆盖
通过 API 创建 session 时可在 session.config.mcpServers 中按会话覆盖全局 MCP 配置。

章节来源 - schema.py:11-50 - schema.py:72-142 - schema.py:145-237 - schema.py:349-411 - schema.py:452-492 - README_zh.md:1358-1392

会话与服务集成¶

会话创建与消息发送
创建会话后记录标题并索引；发送消息前抢占式预留会话，避免并发写冲突。
消息持久化、搜索索引、SSE 事件广播。
并发与终止态
每个会话同一时刻仅允许一个运行；终端状态映射为 SSE 事件（completed/cancelled/failed）。

章节来源 - service.py:53-117 - service.py:118-200

依赖关系分析¶

本地服务依赖
FastMCP 作为 ASGI 应用承载工具；内置工具依赖 Agent 工具注册表、研究目标存储、市场数据加载器。
适配器依赖
fastmcp.client（Client、Transport、OAuth）、mcp.types、key_value.aio.stores.filetree（令牌缓存）。
配置依赖
Pydantic 模型校验；券商 URL 主机后缀识别；OAuth 字段约束。
测试依赖
单元测试覆盖工具发现、名称冲突、Schema 归一化、JSON 字符串参数解码、OAuth 传输构造、未知工具分类拒绝。

graph LR M["mcp_server.py"] --> F["FastMCP"] M --> R["工具注册表"] M --> G["研究目标存储"] A["src/tools/mcp.py"] --> FC["fastmcp.client"] A --> MT["mcp.types"] A --> KV["FileTreeStore"] S["src/config/schema.py"] --> P["Pydantic"]

图表来源 - mcp_server.py:69-81 - mcp.py:17-33 - schema.py:349-411

章节来源 - mcp_server.py:69-81 - mcp.py:17-33 - schema.py:349-411

性能考虑¶

工具发现缓存
基于 server_name 与配置内容的哈希缓存，减少重复 list_tools 开销。
重试策略
list_tools 支持有限次数的瞬态错误重试；工具调用不自动重试，避免副作用重复。
超时与初始化
tool_timeout 控制单次调用；init_timeout 默认不低于 tool_timeout 且至少 30s，适配冷启动/OAuth。
参数解码
对 JSON 字符串形式的 list/dict 参数进行前置解码，降低模型侧序列化导致的验证失败。
网络传输安全
Host/Origin 白名单中间件减少 DNS 重绑定攻击面，避免不必要的请求处理。

章节来源 - mcp.py:62-84 - mcp.py:537-589 - mcp.py:411-449 - mcp_server.py:131-317

故障排查指南¶

常见错误与定位
工具发现失败：检查 enabled_tools 白名单、transport 配置、网络可达性与 OAuth 范围。
参数校验失败：确认 list/dict 参数是否为 JSON 字符串；查看 Schema 归一化后的 required/properties。
券商工具受限：live broker 禁止通配符 enabledTools=["*"]，需使用只读种子或显式白名单。
会话冲突：HTTP 409 表示会话已有运行在进行中，等待或取消后再试。
调试与日志
启用日志观察适配器重试、名称冲突告警、零工具启用警告。
使用测试夹具与单元测试快速验证传输构造、OAuth 配置与工具分类。
恢复步骤
修正配置后重启进程（不支持热重载）；必要时清除 OAuth 缓存目录并重走授权流程。

章节来源 - mcp.py:327-337 - mcp.py:731-793 - schema.py:452-492 - service.py:93-117

结论¶

Vibe-Trading 的 MCP 实现以“本地只读/研究工具 + 远程工具包装”为核心，提供稳定的传输、安全的配置与清晰的错误封装。通过研究目标生命周期与 Agent 工具注册表的深度集成，MCP 成为 AI 代理工作流中可靠的能力扩展点。结合缓存、重试、超时与网络守卫，系统在可用性与安全性之间取得平衡，适合在 CLI、Web UI、REST 与多通道场景中复用。

附录¶

支持的 MCP 工具清单¶

本地暴露工具（64 个）：list_skills、load_skill、start_research_goal、get_research_goal、add_goal_evidence、update_research_goal_status、backtest、factor_analysis、alpha_zoo、alpha_bench、analyze_options、analyze_options_payoff、pattern_recognition、read_url、read_document、web_search、write_file、read_file、list_swarm_presets、run_swarm、get_market_data、get_fund_flow、get_dragon_tiger、get_northbound_flow、get_margin_trading、get_block_trades、get_shareholder_count、get_lockup_expiry、get_sector_info、get_research_reports、get_stock_news、get_sec_filings、get_financial_statements、get_options_chain、get_stock_profile、screen_market、search_symbol、get_macro_series、iwencai_search、qveris_search、qveris_inspect、qveris_execute、get_institutional_holdings、etf_holdings、prediction_market、research_papers、get_swarm_status、get_run_result、list_runs、reap_stale_runs、retry_run、analyze_trade_journal、extract_shadow_strategy、run_shadow_backtest、render_shadow_report、scan_shadow_signals、trading_connections、trading_select_connection、trading_check、trading_account、trading_positions、trading_orders、trading_quote、trading_history。

章节来源 - README_zh.md:1113-1117

参数规范与返回值格式¶

参数规范
远程工具 inputSchema 会被归一化为 OpenAI 兼容对象；anyOf/null 分支被清理；type 列表中的 null 被折叠。
对于 list/dict 参数，若客户端以 JSON 字符串发送，将被前置解码为实际容器类型。
返回值格式
本地工具统一返回 JSON 信封：成功包含 status="ok" 与业务数据；失败包含 status="error"、error_type 与 error 信息。
远程工具调用结果经适配器标准化，附加 server、remote_tool、tool 等元数据。

章节来源 - mcp.py:289-324 - mcp.py:411-449 - mcp_server.py:377-388 - mcp.py:439-473

与 Agent 系统集成¶

工具注册
本地工具通过 @mcp.tool 注册；远程工具通过 build_mcp_tool_wrappers 包装为 BaseTool 并入注册表。
上下文传递
研究目标通过 session_id 关联；MCP 未注入宿主 session 时采用进程级默认 ID。
状态管理
研究目标支持创建、追加证据、状态更新与审计；会话服务保证并发安全与事件广播。

章节来源 - mcp_server.py:495-735 - mcp.py:143-206 - service.py:118-200

MCP 客户端集成示例¶

连接配置
stdio：指定 command/args/env；SSE/HTTP：指定 url/type/headers；OAuth：scopes/client_name/cache_dir/callback_port。
注意 URL 类 transport 必须显式 type；OAuth 要求 HTTPS。
工具调用
通过 MCP 客户端调用 tools/list 与 tools/call；本地工具直接调用；远程工具经适配器包装后调用。
错误处理
捕获适配器返回的错误信封；区分 validation/stale_goal/not_found 等错误类型；关注瞬态错误重试与调用不重试策略。

章节来源 - schema.py:349-411 - mcp.py:475-535 - mcp.py:537-589

性能优化建议¶

合理设置 tool_timeout 与 init_timeout，避免冷启动与授权过程误超时。
利用工具发现缓存减少重复 list_tools 开销。
对大参数（list/dict）使用原生容器而非 JSON 字符串，减少解析成本。
在网络传输上启用 Host/Origin 白名单，减少恶意请求处理。

章节来源 - mcp.py:62-84 - mcp.py:521-535 - mcp_server.py:131-317

调试工具与监控方法¶

单元测试
覆盖工具发现、名称冲突、Schema 归一化、JSON 字符串参数解码、OAuth 传输构造、未知工具分类拒绝。
日志与告警
观察适配器重试、名称冲突告警、零工具启用警告；会话服务的事件广播用于前端实时反馈。
回归测试
通过测试夹具模拟远程 MCP 服务端，验证端到端调用路径与错误传播。

章节来源 - test_mcp_client_adapter.py:173-213 - test_mcp_client_adapter.py:531-599 - test_mcp_json_string_args.py:162-194 - test_default_deny_unknown_robinhood_tool.py:104-128

← API认证 WebSocket API →