Broker MCP Demo

基于 FastMCP 的券商 MCP Server Demo（Python 版）， 做了两点简化：

• 鉴权用静态 API key（Authorization: Bearer <api-key>），不走 OAuth；
• 不内置任何真实服务地址：下游券商后端地址由使用者通过环境变量自行配置， 未配置时各工具返回内置示例数据（响应带 "mock": true 标记），开箱即可体验。

架构

┌─────────────┐  Bearer <api-key>  ┌────────────────────┐   HTTP   ┌──────────────┐
│  MCP Client │───────────────────▶│  Broker MCP Demo   │─────────▶│  券商后端服务  │
│  (Claude…)  │◀───────────────────│  (API key 校验)     │◀─────────│ （自行配置）   │
└─────────────┘                    └────────────────────┘          └──────────────┘

请求流程：

1. 客户端带 Authorization: Bearer <api-key> 请求 POST /mcp；如需按用户维度 执行，同时在请求头 X-User-Id 中原样透传券商体系内的用户 ID。
2. 服务端将 key 与 BROKER_MCP_API_KEYS 中配置的逐一比对，命中放行、否则 401。
3. 工具调用被代理到 BROKER_MCP_BACKEND_BASE_URL 指向的券商后端； 未配置时返回内置示例数据。

调用方身份由两层组成：API key 解析出的 client_id（哪家券商）+ 请求头 X-User-Id 透传的用户 ID（该券商体系内的哪个用户）。持仓、资产、订单、下单等 工具会把 X-User-Id 原样透传给券商后端，按用户维度执行；未携带时该 header 不下发（如仅体验行情类工具）。

工具

共 10 个示例工具，覆盖行情、持仓 / 订单、交易、知识库四类。下游接口路径均为示意， 接入真实后端时按约定改 tools/ 里的 path 即可。

行情（market.py）

工具	参数	说明
search_ticker	keyword	按公司名 / 代码搜索标的，解析出 market + symbol
get_latest_quote	market, symbol	查询标的最新行情
get_chart	market, symbol, span=1month	历史 K 线；span 支持 1day / 1week / 1month / 1year / 5year

持仓 / 资产 / 订单（portfolio.py）

工具	参数	说明
get_positions	—	当前持仓列表（含盈亏）
get_assets	—	账户资产（现金、市值、总资产等）
get_orders	status=OPEN, limit=20	订单列表；status 支持 OPEN / FILLED / CANCELLED / ALL
get_order	order_id	单个订单详情
cancel_order	order_id	撤销一个未成交订单

交易（trade.py）

工具	参数	说明
create_order	symbol, market, side, order_type, quantity, price?, validity	创建（提交）一个交易订单

• order_type：MARKET_ORDER（市价）/ LIMIT_ORDER（限价，需带 price）。
• side：BUY / SELL；validity：GOOD_FOR_DAY / GOOD_TILL_CANCELLED。

知识库（knowledge.py）

工具	参数	说明
search_knowledge_base	query, language=zh-Hans, top=10	搜索平台知识库（开户、出入金、交易规则等 QA）

• language：zh-Hans / zh-Hant / en；top 范围 3~20。
• 真实项目通常由后端做向量检索 + 语义排序（如 Azure Cognitive Search、 Elasticsearch、Milvus 等），本 demo 不绑定具体实现。

每个工具都套了 decorators.py 的 log_tool 装饰器，统一打印调用方（API key 对应的 client_id）、入参与耗时日志。新增工具时 在对应模块 register(mcp) 内用 @mcp.tool + @log_tool 声明，并在 tools/__init__.py 的 register_tools() 注册。

运行

pip install -r requirements.txt

cp .env.example .env   # 按需修改 API key、后端地址
python -m broker_mcp_demo

默认监听 0.0.0.0:8000，MCP 端点为 /mcp，健康检查为 /health。

配置

全部通过环境变量（前缀 BROKER_MCP_）或 .env 注入，参考 .env.example：

变量	说明
BROKER_MCP_API_KEYS	必填（除非关闭鉴权）。逗号分隔，每条为 key 或 key:client_id，如 demo-key-1:alice,demo-key-2:bob
BROKER_MCP_BACKEND_BASE_URL	下游券商后端根地址（demo 不内置真实地址，自行配置）；留空时工具返回示例数据
BROKER_MCP_HOST / BROKER_MCP_PORT	监听地址 / 端口，默认 0.0.0.0:8000
BROKER_MCP_TRANSPORT	http（默认）或 stdio
BROKER_MCP_AUTH_DISABLED	true 关闭鉴权，仅本地调试用
BROKER_MCP_BACKEND_TIMEOUT	下游请求超时秒数，默认 30

客户端接入

以 Claude Code 为例（HTTP 模式 + API key）：

claude mcp add --transport http broker-demo http://localhost:8000/mcp \
  --header "Authorization: Bearer demo-key-1"

或在 MCP 客户端的 JSON 配置中：

{
  "mcpServers": {
    "broker-demo": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer demo-key-1"
      }
    }
  }
}

stdio 模式

用于本地调试，走 stdin/stdout 且不启用鉴权：

BROKER_MCP_TRANSPORT=stdio python -m broker_mcp_demo

目录结构

src/broker_mcp_demo/
├── __main__.py     入口（python -m broker_mcp_demo）
├── config.py       环境变量 / .env 配置读取
├── auth.py         API key 鉴权（ApiKeyVerifier）
├── identity.py     解析调用方身份（client_id + X-User-Id）
├── backend.py      下游后端 HTTP 调用封装（未配置地址时回退示例数据）
├── server.py       FastMCP 实例装配
└── tools/          MCP 工具
    ├── __init__.py     register_tools() 注册入口
    ├── decorators.py   log_tool 计时日志装饰器
    ├── market.py       行情
    ├── portfolio.py    持仓 / 资产 / 订单
    ├── trade.py        下单
    └── knowledge.py    平台知识库搜索

License

Apache-2.0