内容
<h1 align="center">CPZAI MCP 服务器</h1>
<p align="center">
<strong>用于 AI 代理访问 <a href="https://ai.cpz-lab.com">CPZAI</a> 的模型上下文协议服务器</strong>
</p>
<p align="center">
<a href="https://github.com/CPZ-Lab/cpzai-mcp-server"><img src="https://img.shields.io/badge/language-TypeScript-blue.svg" alt="TypeScript"></a>
<a href="https://github.com/CPZ-Lab/cpzai-mcp-server/actions/workflows/ci.yml"><img src="https://github.com/CPZ-Lab/cpzai-mcp-server/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-v1.0-green.svg" alt="MCP v1.0"></a>
<img src="https://img.shields.io/badge/transport-Streamable_HTTP-orange.svg" alt="Streamable HTTP">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
</p>
---
一款生产级别的 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，暴露 [CPZAI](https://ai.cpz-lab.com) 功能 — 策略管理、回测、多券商订单路由（Alpaca / Interactive Brokers / FIX）、投资组合、风险分析、市场数据 — 作为工具，供任何 MCP 兼容的 AI 代理（Claude、Cursor、GPT 等）使用。
托管端点 `https://mcp.cpz-lab.com/mcp` 是连接的唯一支持方式。本仓库存在是为了透明度：任何通过 AI 代理连接券商 API 密钥的人都应该能够读取处理这些密钥的精确代码。
## 快速开始
您需要一个 CPZ API 密钥 + 密钥。在 [ai.cpz-lab.com/settings/api-keys](https://ai.cpz-lab.com/settings/api-keys) 处创建一个。
### Cursor
添加到 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"cpzai": {
"url": "https://mcp.cpz-lab.com/mcp",
"headers": {
"X-CPZ-Key": "your_cpz_key",
"X-CPZ-Secret": "your_cpz_secret"
}
}
}
}
```
### Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"cpzai": {
"url": "https://mcp.cpz-lab.com/mcp",
"headers": {
"X-CPZ-Key": "your_cpz_key",
"X-CPZ-Secret": "your_cpz_secret"
}
}
}
}
```
### Claude（网页/移动端）通过 OAuth
服务器在 `https://mcp.cpz-lab.com/.well-known/oauth-authorization-server` 处支持 OAuth 2.1 + PKCE。使用 Claude 的“连接服务器”流程，并将其指向 `https://mcp.cpz-lab.com/mcp`。
## 架构
```
代理（Cursor / Claude / GPT / 自定义）
│
│ Streamable HTTP + X-CPZ-Key / X-CPZ-Secret
▼
mcp.cpz-lab.com
│
▼
Node.js MCP 服务器（无状态）← 本仓库
│
│ 每次请求的 API 密钥验证
▼
CPZ 平台 REST API
```
**设计决策：**
- **无状态传输。** 每个 `POST /mcp` 创建一个新的服务器实例 — 没有会话跟踪，无需协调即可水平扩展。
- **薄协议适配器。** 验证 API 密钥，然后将工具调用代理到 CPZ REST API。MCP 层中没有业务逻辑；您在 `src/` 中看到的就是在生产中运行的内容。
- **密钥身份验证。** 代理使用 CPZ 平台 API 密钥（`X-CPZ-Key` / `X-CPZ-Secret`）进行身份验证 — 与 REST API 和 [`cpz` Python SDK](https://pypi.org/project/cpz/) 使用的相同密钥。
- **默认仅纸上交易。** 策略的实时交易需要平台中明确的每策略提升。
## 可用工具
今天公开了 18 种工具，按领域组织。
| 工具 | 描述 | 只读 |
|------|-------------|:---------:|
| **策略** | | |
| `list_strategies` | 列出交易策略，支持筛选 | ✓ |
| `get_strategy` | 按 ID 获取特定策略 | ✓ |
| `create_strategy` | 创建新的交易策略 | |
| `update_strategy` | 更新现有策略 | |
| **回测** | | |
| `get_backtest_results` | 列出回测运行结果 | ✓ |
| **订单和交易** | | |
| `list_orders` | 列出交易订单，支持筛选 | ✓ |
| `place_order` | 下达新的交易订单 | |
| `list_positions` | 列出当前投资组合头寸 | ✓ |
| `sync_portfolio` | 触发跨券商的投资组合同步 | |
| `list_accounts` | 列出连接的交易账户 | ✓ |
| **市场数据** | | |
| `get_market_data` | 实时行情（价格，买卖，成交量） | ✓ |
| **风险** | | |
| `compute_risk` | 计算新鲜的风险快照（VaR，夏普比率，最大回撤） | |
| `list_risk_snapshots` | 列出历史风险快照 | ✓ |
| **执行** | | |
| `execute_strategy` | 在 Python 后端执行策略 | |
| **Webhook** | | |
| `list_webhooks` | 列出 Webhook 订阅 | ✓ |
| `create_webhook` | 订阅平台事件 | |
| `delete_webhook` | 删除 Webhook 订阅 | |
| **用户** | | |
| `get_profile` | 获取认证用户资料 | ✓ |
## 本地开发
```bash
npm install
export CPZ_API_BASE_URL=https://api.cpz-lab.com
export CPZ_SERVICE_KEY=your_service_key
npm run dev
# 服务器启动在 http://localhost:3001
```
### 测试 + 类型检查
```bash
npm test # 单次运行
npm run test:watch # 监视模式
npx tsc --noEmit # 类型检查
```
### 构建
```bash
npm run build # 编译 TS → dist/
npm start # 运行编译后的服务器
```
### Docker
```bash
docker build -t cpzai-mcp-server .
docker run --rm -p 3001:3001 \
-e CPZ_API_BASE_URL=https://api.cpz-lab.com \
-e CPZ_SERVICE_KEY=your_service_key \
cpzai-mcp-server
```
## 安全模型
- 所有连接均使用 TLS 1.3 进行 HTTPS 加密。
- API 凭证在 HTTP 头部转发，**从不记录**。
- 针对平台的 `api_keys` 表进行每次请求的 API 密钥验证。
- 所有数据访问均通过验证密钥派生的 `user_id` 进行用户范围限定。
- OAuth 令牌（使用时）仅保存在服务器内存中 — 绝不持久化。
有关完整的 数据处理 故事，请参阅 [隐私政策](https://mcp.cpz-lab.com/privacy)。
## 自托管
我们目前不支持自托管。使用您的 CPZ API 密钥和托管端点 `https://mcp.cpz-lab.com/mcp`。托管服务器是本仓库中的相同代码，加上 AWS 基础设施（ALB，ECS Fargate，WAF，密钥），这些基础设施不在本仓库中。
如果您有强烈的自托管理由（例如，隔离的交易台），请提出问题，我们将讨论。
## 贡献
欢迎提出问题和 PR。在提交之前：
- `npx tsc --noEmit` 必须通过
- `npm test` 必须通过
- 保持更改最小并与现有模式一致
## 许可证
[MIT](LICENSE) © CPZ Capital Ltd.
