MCP Server 与 Agent 工具调用

学习目标

理解 OpenBB 如何通过 MCP（Model Context Protocol）服务器将金融数据端点暴露给 AI Agent，实现自然语言驱动的金融数据查询。

---

项目实践

MCP 协议概述

MCP（Model Context Protocol）是 Anthropic 提出的开放协议，用于标准化 AI 应用与外部数据源/工具之间的交互。OpenBB 内置了 MCP Server，将全部金融数据命令（如 equity.price.historical）注册为 MCP Tool。

核心价值：AI Agent 可以通过标准协议动态发现可用工具、获取参数描述、执行调用并获得结构化结果——无需硬编码 API 调用逻辑。

MCP Server 架构

工具注册机制

MCP Server 通过读取 OpenBB Router 的命令映射，自动将每个命令注册为 MCP Tool：

# openbb_mcp_server 核心逻辑（伪代码）
from openbb_core.app.router import CommandMap, RouterLoader

# 加载所有命令
router = RouterLoader.from_extensions()
command_map = CommandMap(router=router)

# 每个命令自动注册为 MCP Tool
for route, func in command_map.map.items():
    tool = {
        "name": route.replace("/", "_"),      # equity_price_historical
        "description": func.__doc__,           # 从 docstring 提取
        "inputSchema": extract_schema(func),   # 从签名提取 JSON Schema
    }
    register_tool(tool)

工具描述自动提取：

• name：从路由路径转换（/equity/price/historical → equity_price_historical）
• description：从 Python docstring 提取
• inputSchema：从 FastAPI 依赖注入的 StandardParams / ExtraParams 生成 JSON Schema

Agent 调用流程

实际使用示例

# 启动 MCP Server
openbb-mcp-server

Agent 配置示例（Claude Desktop）：

{
  "mcpServers": {
    "openbb": {
      "command": "uv",
      "args": ["run", "--with", "openbb-mcp-server", "openbb-mcp-server"]
    }
  }
}

Agent 可以自然语言查询：

用户："帮我对比一下 AAPL 和 MSFT 今年的收益率"
Agent 内部流程：
1. 调用 equity_price_historical(symbol="AAPL", start_date="2025-01-01")
2. 调用 equity_price_historical(symbol="MSFT", start_date="2025-01-01")
3. 计算并比较收益率
4. 回复用户

---

问题与规避

工具数量过多导致 Agent 困惑

• OpenBB 有数百个命令端点，一次性暴露给 Agent 会超出上下文窗口
• 对策：通过分类索引（category_index.py）按需加载，Agent 先检索相关类别再调用

参数验证失败

• Agent 可能传入无效参数（如不存在的股票代码）
• 对策：MCP Server 透传 OpenBB 的 Pydantic 验证错误，返回结构化错误信息

数据量大超出 Agent 上下文

• 历史数据可能包含数千条记录
• 对策：在 prompt 中引导 Agent 使用 start_date / end_date 限制范围，或在服务端做聚合

---

设计取舍

自动注册 vs 手动注册

• OpenBB 选择自动从 Router 注册所有命令为 MCP Tool
• 优势：无需维护工具列表，新命令自动可用
• 代价：需要额外的过滤/分类机制防止工具爆炸

JSON Schema 生成

• 利用 FastAPI 的依赖注入系统（StandardParams / ExtraParams）自动生成 JSON Schema
• 比手动维护 schema 更可靠，且与 Python 类型系统保持同步

---

参考来源

• 源码验证: openbb_platform/extensions/mcp_server/ — MCP Server 实现
• MCP 官方文档 — Model Context Protocol 规范