# TradingAgents MCP Server

将 [TradingAgents](https://github.com/tauricresearch/tradingagents) 多智能体金融研究引擎，以**标准 MCP 协议**暴露给任意 LLM Host（Codex、Claude Desktop、Cursor 等）的薄适配层。

> **重要边界**：本服务器**只产出研究报告与非执行性决策**。它不连接任何券商账户，不提交、修改或取消订单。研究结果仅供参考，不构成投资建议。

## 为什么需要它？

TradingAgents 本身是一个 Python 框架，需要通过编写代码或命令行方式驱动，LLM Host 无法直接调用它。TradingAgents MCP Server 解决了三个问题：

1. **零代码接入**：LLM Host 通过 MCP 协议即可启动研究任务、查询进度、读取完整报告，无需理解 TradingAgents 内部结构。
2. **异步任务模型**：完整金融研究耗时较长（数分钟到数十分钟），本服务器将每次分析建模为异步任务，不阻塞 MCP 调用。
3. **开箱即用的研究管线**：内置任务队列、SQLite 持久化、幂等控制、取消与确认式删除，服务重启后任务状态不会丢失。

## 特性亮点

- **7 个 MCP 工具 + 1 个 MCP 资源**：完整覆盖能力查询、任务启动、状态轮询、结果读取、任务列表、取消与删除。
- **异步任务状态机**：`queued → running → succeeded / failed / cancelled`，支持长时间研究任务。
- **幂等创建**：`idempotency_key` 保证同一分析请求重复提交只创建一次任务。
- **持久化存储**：任务元数据存于 SQLite，报告与中间产物存于磁盘，服务重启后可恢复。
- **确认式删除**：成果永不自动清理；删除必须传入完全匹配的 `run_id` 二次确认。
- **凭证隔离**：LLM API Key 等敏感配置只存在于服务端环境变量中，MCP 协议层不接触凭证。

## 架构概览

```mermaid
flowchart LR
    A[LLM Host<br/>Codex / Claude Desktop] -->|MCP stdio| B[MCP Server<br/>tradingagents_mcp.server]
    B --> C[(SQLite<br/>tasks.db)]
    B --> D[TaskRuntime<br/>单 worker 串行队列]
    D -->|子进程隔离| E[worker.py]
    E --> F[TradingAgentsGraph<br/>propagate]
    F --> G[final_state.json<br/>complete_report.md]
    G --> B
    B -->|MCP Resource| A
```

- **MCP Server**：处理工具与资源请求，维护任务队列。
- **SQLite**：存储任务元数据与幂等映射，支持原子状态迁移。
- **TaskRuntime**：单 worker 串行执行任务，子进程隔离保证上游异常不影响服务器进程。
- **worker.py**：子进程内运行 `TradingAgentsGraph.propagate()`，产出 `final_state.json` 与 `complete_report.md`。

## 快速开始

### 前置要求

- Python 3.10+
- 已安装 TradingAgents：`pip install tradingagents`（或从源码安装）
- 已配置 LLM API Key（见下文「LLM 配置」）

### 安装

```bash
cd tradingagents-mcp
pip install -e .
```

### 启动

```bash
# 方式一：直接启动
python -m tradingagents_mcp.server

# 方式二：使用启动脚本（自动探测 TradingAgents 源码位置）
./start_server.sh
```

## LLM 配置

LLM 提供商配置沿用 TradingAgents 自身的环境变量，由上游 `TradingAgentsGraph` 读取。MCP 适配器不接触这些凭证。

| 变量 | 说明 | 示例 |
|------|------|------|
| `TRADINGAGENTS_LLM_PROVIDER` | LLM 提供商 | `openai`、`deepseek`、`custom_openai` |
| `TRADINGAGENTS_MODEL` | 深度思考模型名 | `deepseek-v4-flash` |
| `TRADINGAGENTS_QUICK_MODEL` | 快速思考模型名 | `deepseek-v4-flash` |
| `TRADINGAGENTS_BASE_URL` | API 地址 | `https://api.example.com` |
| `TRADINGAGENTS_API_KEY` | API Key（也可直接用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 等上游变量） | `sk-...` |
| `TRADINGAGENTS_MAX_TOKENS` | 单次调用最大 token 数 | `4000` |
| `TRADINGAGENTS_TEMPERATURE` | 采样温度 | `0.7` |

服务端配置环境变量：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `TRADINGAGENTS_MCP_DATA_DIR` | 数据目录（数据库、任务工作区） | `~/.tradingagents-mcp` |
| `TRADINGAGENTS_MCP_MAX_QUEUED` | 最大排队任务数 | `20` |
| `TRADINGAGENTS_MCP_TASK_TIMEOUT` | 单任务超时（秒） | `1800` |
| `TRADINGAGENTS_MCP_GRAPH_CLASS` | 上游图类导入路径（自定义安装布局时覆盖） | `tradingagents.graph.trading_graph.TradingGraph` |

> 提示：所有凭证均以环境变量方式注入服务端进程，MCP 工具参数中**永远不会出现** API Key。

## 配置到 MCP Host

### Codex / Claude Desktop

```json
{
  "mcpServers": {
    "tradingagents": {
      "command": "python",
      "args": ["-m", "tradingagents_mcp.server"]
    }
  }
}
```

## 工具与资源

| 工具 | 说明 | 只读 | 幂等 |
|------|------|------|------|
| `get_capabilities` | 查询服务器能力与配置（不含凭证） | ✅ | ✅ |
| `start_analysis` | 启动分析任务 | ❌ | ✅（`idempotency_key`） |
| `get_analysis_status` | 查询任务状态与时间戳 | ✅ | ✅ |
| `get_analysis_result` | 获取结果摘要（评级、置信度、报告 URI） | ✅ | ✅ |
| `list_analyses` | 分页列出任务，支持状态过滤 | ✅ | ✅ |
| `cancel_analysis` | 取消 queued / running 任务 | ❌ | ✅ |
| `delete_analysis` | 永久删除任务（需 `confirm_run_id` 精确匹配） | ❌ | ✅ |

MCP 资源：

- `tradingagents://analyses/{run_id}/report` — 完整的 Markdown 研究报告（仅 `succeeded` 任务可访问）

### 支持的资产与研究参数

| 参数 | 取值 | 说明 |
|------|------|------|
| `symbol` | `AAPL`、`600519.SH`、`BTC` | 股票代码或加密货币符号 |
| `asset_type` | `stock` / `crypto` | 默认 `stock`；`stock` 分析师为 market/social/news/fundamentals，`crypto` 为 market/social/news |
| `analysis_date` | `YYYY-MM-DD` | 分析日期，不可为未来日期 |
| `depth` | `shallow` / `deep` | 默认 `shallow`（更快）；`deep` 更深入 |
| `language` | `English` / `中文` | 默认 `English` |
| `analysts` | 分析师类型列表 | 默认按 `asset_type` 决定 |
| `idempotency_key` | 可选字符串 | 相同参数 + 相同 key 返回已有任务 |

## 使用示例

### 1. 查询能力

```
调用 get_capabilities
```

返回支持的资产类型、研究深度、输出语言、队列限制等。

### 2. 启动分析

```
调用 start_analysis，参数：
- symbol: "AAPL"
- analysis_date: "2025-01-15"
- asset_type: "stock"
- depth: "shallow"
- language: "English"
```

返回 `run_id`，例如 `run_a1b2c3d4e5f67890`。

### 3. 轮询状态

```
调用 get_analysis_status，参数：
- run_id: "run_a1b2c3d4e5f67890"
```

任务状态流转：`queued → running → succeeded / failed / cancelled`。轮询直到终态。

### 4. 读取结果摘要

```
调用 get_analysis_result，参数：
- run_id: "run_a1b2c3d4e5f67890"
```

返回评级、置信度与报告资源 URI。

### 5. 阅读完整报告

通过 MCP 资源读取：

```
tradingagents://analyses/run_a1b2c3d4e5f67890/report
```

## 数据存储

所有数据存储在 `TRADINGAGENTS_MCP_DATA_DIR`（默认 `~/.tradingagents-mcp/`）：

```
~/.tradingagents-mcp/
├── tasks.db            # SQLite 任务元数据数据库
└── runs/
    ├── run_abc123/     # 每个任务的独立工作区
    │   ├── request.json
    │   ├── final_state.json
    │   ├── complete_report.md
    │   ├── SUCCESS.json 或 error.json
    │   └── worker_stderr.log
    └── ...
```

- 任务成果**永不自动清理**，只有显式调用 `delete_analysis` 才会删除。
- 服务重启后，中断的 `running` 任务会自动重新入队。

## 安全与边界

- **不做交易**：不连接券商，不提交、修改或取消任何订单。
- **凭证隔离**：API Key 只存在于服务端环境变量，绝不通过 MCP 协议传输。
- **只读查询为主**：除 `start_analysis`、`cancel_analysis`、`delete_analysis` 外，其余工具均为只读。
- **数据默认本地**：报告与数据库存储在本地数据目录，不依赖外部 SaaS。

### FAQ

**Q：为什么不直接在 MCP Host 里调用 TradingAgents？**
A：TradingAgents 是 Python 框架，LLM Host 无法原生执行任意 Python。MCP 适配器将研究能力封装为标准化工具，且提供队列、持久化、幂等、取消等工程能力。

**Q：如何配置 API Key？**
A：在启动 MCP 服务器的进程环境中设置 `TRADINGAGENTS_API_KEY`（或 `OPENAI_API_KEY` / `DEEPSEEK_API_KEY`）等变量。服务器不会通过 MCP 工具暴露或接收凭证。

**Q：研究报告可以删除吗？**
A：可以，但必须显式调用 `delete_analysis` 并传入完全匹配的 `run_id`。成果不会自动清理，避免误删。

**Q：分析结果会过期或被覆盖吗？**
A：不会。每个任务有独立工作区与持久化存储，幂等键保证同一请求只创建一次任务。

## 开发与测试

```bash
pip install pytest pytest-asyncio
pytest tests/
```

使用 MCP Inspector 交互式调试：

```bash
npx @modelcontextprotocol/inspector python -m tradingagents_mcp.server
```

## 许可证

MIT