Broker MCP Demo

Ein Demo-MCP-Server für Broker (Python-Version) basierend auf FastMCP, mit zwei Vereinfachungen:

• Authentifizierung über statischen API-Key (Authorization: Bearer <api-key>), ohne OAuth;

• Keine echten Service-Adressen eingebaut: Die Adresse des nachgelagerten Broker-Backends wird vom Nutzer über Umgebungsvariablen selbst konfiguriert. Wenn nicht konfiguriert, geben die Tools integrierte Beispieldaten zurück (die Antwort trägt die Markierung "mock": true), sofort einsatzbereit.

Architektur

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

Anfrageablauf:

1. Der Client sendet eine Anfrage an POST /mcp mit Authorization: Bearer <api-key>.

2. Der Server vergleicht den Key nacheinander mit den in BROKER_MCP_API_KEYS konfigurierten Werten; bei Übereinstimmung wird die Anfrage durchgelassen, andernfalls wird 401 zurückgegeben.

3. Tool-Aufrufe werden an das Broker-Backend unter BROKER_MCP_BACKEND_BASE_URL weitergeleitet; wenn nicht konfiguriert, werden integrierte Beispieldaten zurückgegeben.

Tools

Insgesamt 10 Beispiel-Tools, die vier Kategorien abdecken: Marktdaten, Positionen/Bestellungen, Handel und Wissensdatenbank. Die Pfade der nachgelagerten Schnittstellen sind nur schematisch; beim Anschluss an ein echtes Backend muss lediglich der path in tools/ entsprechend angepasst werden.

Marktdaten (market.py)

Positionen / Vermögen / Bestellungen (portfolio.py)

Handel (trade.py)

• order_type: MARKET_ORDER (Marktpreis) / LIMIT_ORDER (Limit, erfordert price).

• side: BUY / SELL; validity: GOOD_FOR_DAY / GOOD_TILL_CANCELLED.

Wissensdatenbank (knowledge.py)

• language: zh-Hans / zh-Hant / en; top Bereich 3~20.

• In echten Projekten übernimmt das Backend in der Regel Vektorsuche + semantisches Ranking (z. B. Azure Cognitive Search, Elasticsearch, Milvus usw.); diese Demo ist an keine konkrete Implementierung gebunden.

Jedes Tool ist mit dem log_tool-Dekorator aus decorators.py versehen, der einheitlich den Aufrufer (die dem API-Key entsprechende client_id), die Eingabeparameter und die Dauer protokolliert. Beim Hinzufügen neuer Tools werden diese im entsprechenden Modul innerhalb von register(mcp) mit @mcp.tool + @log_tool deklariert und in register_tools() in tools/__init__.py registriert.

Ausführung

pip install -r requirements.txt

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

Standardmäßig lauscht der Server auf 0.0.0.0:8000, der MCP-Endpunkt ist /mcp, der Health-Check unter /health.

Konfiguration

Alles wird über Umgebungsvariablen (Präfix BROKER_MCP_) oder .env injiziert, siehe .env.example:

Client-Anbindung

Am Beispiel von Claude Code (HTTP-Modus + API-Key):

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

Oder in der JSON-Konfiguration des MCP-Clients:

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

stdio-Modus

Für lokales Debugging, über stdin/stdout und ohne Authentifizierung:

BROKER_MCP_TRANSPORT=stdio python -m broker_mcp_demo

Verzeichnisstruktur

src/broker_mcp_demo/
├── __main__.py     入口（python -m broker_mcp_demo）
├── config.py       环境变量 / .env 配置读取
├── auth.py         API key 鉴权（ApiKeyVerifier）
├── identity.py     从鉴权上下文解析 client_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