Broker MCP Demo

FastMCP 기반의 증권사 MCP 서버 데모（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를 요청합니다.

2. 서버가 key를 BROKER_MCP_API_KEYS에 구성된 값과 하나씩 대조하여, 일치하면 통과, 아니면 401을 반환합니다.

3. 도구 호출은 BROKER_MCP_BACKEND_BASE_URL이 가리키는 증권사 백엔드로 프록시됩니다； 미구성 시 내장된 예시 데이터를 반환합니다.

도구

총 10개의 예시 도구로, 시세, 포지션 / 주문, 거래, 지식베이스 네 가지 범주를 다룹니다. 다운스트림 인터페이스 경로는 모두 예시이며, 실제 백엔드 연동 시 tools/ 안의 path를 수정하면 됩니다.

시세（market.py）

포지션 / 자산 / 주문（portfolio.py）

거래（trade.py）

• order_type：MARKET_ORDER（시장가）/ LIMIT_ORDER（지정가，price 필요）。

• side：BUY / SELL；validity：GOOD_FOR_DAY / GOOD_TILL_CANCELLED。

지식베이스（knowledge.py）

• language：zh-Hans / zh-Hant / en；top 범위 3~20。

• 실제 프로젝트는 보통 백엔드에서 벡터 검색 + 의미 정렬을 수행합니다（예: Azure Cognitive Search, Elasticsearch, Milvus 등），본 데모는 특정 구현에 구속되지 않습니다.

각 도구에는 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 참고：

클라이언트 연동

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
├── 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