# https://github.com/atilaahmettaner/tradingview-mcp 项目说明书
生成时间：2026-05-11 19:46:48 UTC
## 目录
- [项目概览](#page-project-overview)
- [安装指南](#page-installation-guide)
- [系统架构](#page-architecture)
- [核心组件](#page-core-components)
- [回测引擎](#page-backtesting-engine)
- [技术分析服务](#page-technical-analysis)
- [情感分析与新闻服务](#page-sentiment-analysis)
- [Yahoo Finance 集成](#page-yahoo-finance)
- [数据源与货币列表](#page-data-sources)
- [多交易所支持](#page-exchange-support)
## 项目概览
### 相关页面
相关主题：[安装指南](#page-installation-guide), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)
- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)
- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)
- [OPENCLAW.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/OPENCLAW.md)
- [EXAMPLES.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/EXAMPLES.md)
- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)
- [src/tradingview_mcp/core/services/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)
# 项目概览
## 什么是 tradingview-mcp
**tradingview-mcp** 是一个基于 Model Context Protocol (MCP) 的服务器，专为 AI 助手（如 Claude Desktop、OpenClaw、Codex）提供金融市场数据访问能力。该项目充当 AI 与 TradingView、Yahoo Finance 等数据源之间的桥梁，使 AI 能够执行技术分析、选股扫描、情绪分析、回测策略等任务。 资料来源：[README.md:1-15]()
该项目完全开源，采用 MIT 许可证，支持 Windows、macOS 和 Linux 多平台运行。开发者可以自由修改代码、集成新功能，或将其部署在个人服务器上。 资料来源：[README.md:LICENSE]()
## 核心架构
tradingview-mcp 采用模块化服务架构，核心组件包括以下几个部分：
```mermaid
graph TD
A[AI 助手
Claude/Codex/OpenClaw] --> B[MCP Server
server.py]
B --> C[服务层]
C --> D[screener_service
选股服务]
C --> E[technical_service
技术分析服务]
C --> F[sentiment_service
情绪分析服务]
C --> G[news_service
新闻服务]
C --> H[backtest_service
回测服务]
C --> I[egx_service
埃及交易所服务]
D --> J[TradingView API
tradingview_ta]
E --> J
G --> K[Reddit API]
H --> J
J --> L[Yahoo Finance]
```
### 目录结构
```
src/tradingview_mcp/
├── server.py # MCP 主服务器入口
├── core/
│ ├── services/ # 核心业务逻辑服务
│ │ ├── screener_service.py # 选股扫描服务
│ │ ├── technical_service.py # 技术分析服务
│ │ ├── sentiment_service.py # 情绪分析服务
│ │ ├── news_service.py # 新闻服务
│ │ ├── backtest_service.py # 回测服务
│ │ └── egx_service.py # EGX 埃及交易所服务
│ ├── utils/ # 工具函数
│ │ └── validators.py # 验证器和常量定义
│ └── indicators/ # 技术指标计算
├── coinlist/ # 各交易所交易对列表
└── __init__.py
```
资料来源：[CONTRIBUTING.md:代码组织]()
## 核心功能
### 技术分析引擎
tradingview-mcp 提供超过 **30 种技术指标** 的实时计算能力，包括 RSI、MACD、布林带、EMA、SMA、ATR 等。每项指标都会生成对应的交易信号（BUY/SELL/HOLD）并附带评分。 资料来源：[README.md:技术分析核心]()
| 指标类型 | 包含指标 |
|---------|---------|
| 趋势指标 | EMA、SMA、MACD、ADX、Ichimoku、Supertrend |
| 动量指标 | RSI、CCI、 Stochastic、Momentum、ROC |
| 波动性指标 | 布林带（BB）、ATR、 标准差 |
| 成交量指标 | OBV、VWMA、Volume |
### 选股扫描器
支持多交易所的股票/加密货币筛选，可按涨幅、跌幅、技术信号等多种条件过滤：
- `top_gainers` — 涨幅榜
- `top_losers` — 跌幅榜
- `scan_by_signal` — 按信号类型筛选（超买、超卖、趋势、突破）
- `screen_stocks` — 多条件组合筛选（支持 20+ 过滤条件） 资料来源：[README.md:筛选器]()
### 回测引擎
内置 **6 种交易策略** 的回测功能，支持机构级指标分析：
| 策略名称 | 类型 | 说明 |
|---------|------|------|
| `rsi` | 均值回归 | RSI 超买超卖策略 |
| `bollinger` | 均值回归 | 布林带策略 |
| `macd` | 趋势 | MACD 金叉死叉 |
| `ema_cross` | 趋势 | EMA 20/50 金叉死叉 |
| `supertrend` | 趋势跟踪 | ATR-based Supertrend |
| `donchian` | 趋势跟踪 | 唐奇安通道（海龟交易法则风格） |
回测提供以下核心指标：
- 胜率 (Win Rate)
- 总收益率 (Total Return)
- 夏普比率 (Sharpe Ratio)
- 卡玛比率 (Calmar Ratio)
- 最大回撤 (Max Drawdown)
- 利润因子 (Profit Factor)
- 期望值 (Expectancy) 资料来源：[README.md:回测引擎]()
### 情绪与新闻分析
| 功能 | 数据源 | 说明 |
|-----|-------|------|
| Reddit 情绪分析 | Reddit API | 分析 subreddits 帖子情绪 |
| 实时新闻 | RSS 订阅源 | 财经新闻聚合 |
| 蜡烛图形态识别 | TradingView | 识别 15 种 K 线形态 |
资料来源：[README.md:情绪与新闻]()
## 支持的交易所
tradingview-mcp 支持全球多个主要交易所，涵盖加密货币和传统股票市场： 资料来源：[README.md:多交易所支持]()
### 加密货币交易所
| 交易所 | 代码 | 支持功能 |
|-------|------|---------|
| Binance | BINANCE | 全交易对筛选、技术分析 |
| KuCoin | KUCOIN | 全交易对筛选、技术分析 |
| Bybit+ | BYBIT | 全交易对筛选、技术分析 |
| MEXC | MEXC | 全交易对筛选、技术分析 |
### 传统股票市场
| 交易所 | 代码 | 支持功能 |
|-------|------|---------|
| 纳斯达克 | NASDAQ | 美股筛选、技术分析 |
| 纽约证券交易所 | NYSE | 美股筛选、技术分析 |
| 纽约证券交易所高增长 | NYSEARCA | ETF 筛选 |
| 美国证券交易所 | AMEX | 美股筛选 |
| 台湾证券交易所 | TWSE | 台股筛选 |
| 台湾柜台买卖中心 | TPEX | 台股筛选 |
| 土耳其伊斯坦布尔证交所 | BIST | 土股筛选 |
| 埃及证券交易所 | EGX | 专用 EGX 服务（Fibonacci、止损推荐等） |
资料来源：[PR_BODY.md:TWSE和TPEX支持]()
## 可用工具列表
### 市场数据工具
| 工具名称 | 功能描述 |
|---------|---------|
| `yahoo_price` | 实时报价：价格、涨跌幅、52 周高低、市场状态 |
| `market_snapshot` | 全球市场概览：标普 500、纳斯达克、BTC、EUR/USD 等 |
| `get_prices_bulk` | 多标的批量价格查询 |
### 技术分析工具
| 工具名称 | 功能描述 |
|---------|---------|
| `get_technical_analysis` | 完整技术分析：RSI、MACD、布林带等 23 项指标 |
| `get_multiple_analysis` | 批量多标的分析 |
| `get_bollinger_band_analysis` | 专有 ±3 布林带评级系统 |
| `get_stock_decision` | 三层决策引擎（排名 + 交易设置 + 质量评分） |
| `scan_by_signal` | 按信号类型扫描（超卖、趋势、突破...） |
| `get_candlestick_patterns` | 15 种蜡烛图形态检测 |
| `get_multi_timeframe_analysis` | 周线→日线→4H→1H→15m 多时间框架对齐分析 |
| `consecutive_candles_scan` | 连续 K 线扫描（检测持续性涨跌） |
### 回测工具
| 工具名称 | 功能描述 |
|---------|---------|
| `backtest_strategy` | 回测单一策略并输出机构级指标 |
| `compare_strategies` | 对比全部 6 种策略在同一标的上，按表现排名 |
### 情绪新闻工具
| 工具名称 | 功能描述 |
|---------|---------|
| `get_reddit_sentiment` | Reddit 指定主题情绪分析 |
| `get_news` | 实时财经新闻 |
### EGX 专用工具
| 工具名称 | 功能描述 |
|---------|---------|
| `egx_market_overview` | 埃及股市整体概览 |
| `egx_stock_screener` | EGX 股票筛选器 |
| `egx_trade_plan` | 止损/止盈推荐 |
| `egx_fibonacci_retracement` | 斐波那契回撤分析 |
资料来源：[README.md:完整工具列表]()
## 安装方式
### 方式一：Claude Desktop（推荐）
在 `claude_desktop_config.json` 中添加配置：
```json
{
"mcpServers": {
"tradingview": {
"command": "uvx",
"args": ["--from", "tradingview-mcp-server", "tradingview-mcp"]
}
}
}
```
Windows 用户需使用完整路径：
```json
{
"mcpServers": {
"tradingview": {
"command": "%USERPROFILE%\\.local\\bin\\uvx.exe",
"args": ["--from", "tradingview-mcp-server", "tradingview-mcp"]
}
}
}
```
资料来源：[INSTALLATION.md:Claude Desktop配置]()
### 方式二：从源码安装
```bash
git clone https://github.com/atilaahmettaner/tradingview-mcp.git
cd tradingview-mcp
uv sync
uv run python src/tradingview_mcp/server.py
```
资料来源：[INSTALLATION.md:本地开发设置]()
### 方式三：通过 OpenClaw 连接 Telegram
tradingview-mcp 可与 OpenClaw 集成，通过 Telegram、WhatsApp、Discord 等 20+ 平台访问：
```
Telegram → OpenClaw agent (AI model) → trading.py → tradingview-mcp → Yahoo Finance
```
资料来源：[OPENCLAW.md:工作原理]()
## 开发指南
### 开发环境搭建
```bash
# 安装依赖
uv sync
# 安装开发依赖
uv sync --dev
# 运行测试
uv run pytest
# 代码检查
uv run ruff check
# 类型检查
uv run mypy src/
```
资料来源：[CONTRIBUTING.md:开发环境]()
### 代码规范
| 规范类型 | 要求 |
|---------|------|
| Python 风格 | 遵循 PEP 8 |
| 代码格式化 | 使用 Ruff |
| 类型注解 | 所有公共函数需添加类型提示 |
| 文档字符串 | 公共函数和类必须包含 docstring |
| 函数命名 | snake_case（如 `get_top_gainers`） |
| 类命名 | PascalCase（如 `MarketAnalyzer`） |
| 常量命名 | UPPER_SNAKE_CASE（如 `DEFAULT_LIMIT`） |
资料来源：[CONTRIBUTING.md:代码规范]()
### 添加新交易所
1. 更新验证器中的交易所映射：
```python
# src/tradingview_mcp/core/utils/validators.py
EXCHANGE_SCREENER = {
"NEW_EXCHANGE": "screener_code",
}
```
2. 添加交易对列表文件：
```bash
echo "BTCUSDT\nETHUSDT\n..." > coinlist/new_exchange.txt
```
3. 测试集成：
```python
result = top_gainers(exchange="NEW_EXCHANGE")
```
资料来源：[CONTRIBUTING.md:添加新交易所]()
### 测试覆盖
项目要求测试覆盖率 >80%，需同时测试成功路径和错误路径。 资料来源：[CONTRIBUTING.md:测试覆盖]()
## 版本管理
项目遵循语义化版本规范 (Semantic Versioning)：
| 版本类型 | 说明 | 示例 |
|---------|------|------|
| 主版本 (X.0.0) | 破坏性变更 | 2.0.0 |
| 次版本 (0.X.0) | 新功能，向后兼容 | 1.1.0 |
| 补丁版本 (0.0.X) | Bug 修复，向后兼容 | 1.0.1 |
## 路线图
| 功能 | 状态 |
|-----|------|
| TradingView 技术分析（30+ 指标） | ✅ 已完成 |
| 多交易所筛选（Binance、KuCoin、美股等） | ✅ 已完成 |
| Reddit 情绪分析 | ✅ 已完成 |
| Yahoo Finance 实时价格 | ✅ 已完成 |
| 回测引擎（6 种策略 + 机构指标） | ✅ 已完成 |
| 前向优化回测（过拟合检测） | 🔄 开发中 |
| Twitter/X 市场情绪 | 📋 计划中 |
| 模拟交易 | 📋 计划中 |
| 云端托管服务 | 📋 计划中 |
资料来源：[README.md:路线图]()
## 项目统计
- **开源协议**: MIT License
- **平台支持**: Windows、macOS、Linux
- **Python 版本**: 3.13（推荐）
- **包管理**: UV
- **主要依赖**: tradingview_ta、requests、beautifulsoup4
## 相关链接
| 资源 | 链接 |
|-----|------|
| GitHub 仓库 | https://github.com/atilaahmettaner/tradingview-mcp |
| 问题反馈 | https://github.com/atilaahmettaner/tradingview-mcp/issues |
| 赞助项目 | https://github.com/sponsors/atilaahmettaner |
---
## 安装指南
相关源码文件
以下源码文件用于生成本页说明：
- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)
- [OPENCLAW.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/OPENCLAW.md)
- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)
- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)
- [PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)
# 安装指南
## 概述
`tradingview-mcp` 是一个连接 TradingView 金融数据与 AI 代理的 MCP（Model Context Protocol）服务器项目。该项目支持实时市场数据、技术指标分析、加密货币筛选、股票筛选、回测等功能。
安装指南涵盖了三种主要的安装方式：快速启动（Claude Desktop）、本地开发环境配置、以及传统的 Python 虚拟环境安装。同时支持 Windows、macOS 和 Linux 三大平台。
## 系统架构
```mermaid
graph TD
A[用户 AI 客户端] --> B[MCP Server]
B --> C[tradingview-mcp 核心]
C --> D[TradingView API]
C --> E[Yahoo Finance API]
C --> F[Reddit API]
C --> G[RSS 新闻源]
H[Claude Desktop] --> B
I[Codex] --> B
J[OpenClaw] --> B
```
## 前置条件
### 必要软件
| 软件 | 版本要求 | 用途 |
|------|----------|------|
| Python | 3.13+ | 运行环境 |
| Git | 最新版 | 代码版本管理 |
| UV | 最新版 | 包管理器（推荐） |
### UV 包管理器安装
UV 是一个高性能的 Python 包管理器，建议优先使用。
**Windows PowerShell：**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
资料来源：[INSTALLATION.md:2]()
**macOS/Linux：**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
```
资料来源：[OPENCLAW.md:7]()
## 安装方法一：快速启动（Claude Desktop）
这是最简便的安装方式，适合不想修改代码只想直接使用工具的用户。
### 步骤 1：克隆仓库
```powershell
git clone https://github.com/atilaahmettaner/tradingview-mcp.git
cd tradingview-mcp
```
资料来源：[INSTALLATION.md:6-7]()
### 步骤 2：安装依赖
```powershell
uv sync
```
资料来源：[INSTALLATION.md:9]()
### 步骤 3：配置 Claude Desktop
定位配置文件路径：
| 操作系统 | 路径 |
|----------|------|
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
Windows 用户可按 `Win + R`，输入 `%APPDATA%\Claude` 并回车快速访问。
### 步骤 4：编辑配置文件
在 `claude_desktop_config.json` 中添加以下配置（将 `YOUR_USERNAME` 替换为实际用户名）：
```json
{
"mcpServers": {
"tradingview-mcp-local": {
"command": "C:\\Users\\YOUR_USERNAME\\tradingview-mcp\\.venv\\Scripts\\python.exe",
"args": ["C:\\Users\\YOUR_USERNAME\\tradingview-mcp\\src\\tradingview_mcp\\server.py"],
"cwd": "C:\\Users\\YOUR_USERNAME\\tradingview-mcp"
}
}
}
```
资料来源：[INSTALLATION.md:15-20]()
### 步骤 5：验证安装
1. 完全退出 Claude Desktop
2. 重新启动应用程序
3. 等待初始化完成（首次启动可能需要 30-60 秒）
4. 询问 Claude：`"Can you show me the available TradingView tools?"`
预期应看到以下工具：
- `top_gainers`
- `top_losers`
- `bollinger_scan`
- `coin_analysis`
- `consecutive_candles_scan`
## 安装方法二：本地开发环境
适用于需要修改代码或进行二次开发的用户。
### 标准开发流程
```bash
# 克隆仓库
git clone https://github.com/atilaahmettaner/tradingview-mcp.git
cd tradingview-mcp
# 安装依赖
uv sync
# 安装开发依赖
uv sync --dev
```
资料来源：[CONTRIBUTING.md:6-12]()
### 测试服务器
```bash
# 直接运行服务器
uv run python src/tradingview_mcp/server.py
# 使用 MCP Inspector 测试
uv run mcp dev src/tradingview_mcp/server.py
# 运行集成测试
uv run python test_api.py
```
资料来源：[CONTRIBUTING.md:14-20]()
### Claude Desktop 配置（本地开发）
**Windows：**
```json
{
"mcpServers": {
"tradingview-mcp-local": {
"command": "C:\\Users\\YourUsername\\tradingview-mcp\\.venv\\Scripts\\python.exe",
"args": ["C:\\Users\\YourUsername\\tradingview-mcp\\src\\tradingview_mcp\\server.py"],
"cwd": "C:\\Users\\YourUsername\\tradingview-mcp"
}
}
}
```
**macOS/Linux：**
```json
{
"mcpServers": {
"tradingview-mcp-local": {
"command": "uv",
"args": ["run", "python", "src/tradingview_mcp/server.py"],
"cwd": "/path/to/your/tradingview-mcp"
}
}
}
```
资料来源：[INSTALLATION.md:53-73]()
## 安装方法三：Python 虚拟环境
适用于偏好传统 Python 环境的用户。
### Windows
```powershell
# 克隆仓库
git clone https://github.com/atilaahmettaner/tradingview-mcp.git
cd tradingview-mcp
# 创建虚拟环境
python -m venv .venv
.\.venv\Scripts\activate
# 安装依赖
pip install -e .
# 运行服务器
python src/tradingview_mcp/server.py
```
资料来源：[INSTALLATION.md:91-100]()
### macOS/Linux
```bash
# 克隆仓库
git clone https://github.com/atilaahmettaner/tradingview-mcp.git
cd tradingview-mcp
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate
# 安装依赖
pip install -e .
# 运行服务器
python src/tradingview_mcp/server.py
```
## Codex 插件安装
该项目包含专门的 Codex 插件元数据配置：
- `.codex-plugin/plugin.json`
- `.codex-mcp.json`
### Codex 配置
```json
{
"mcpServers": {
"tradingview": {
"command": "uvx",
"args": ["--from", "tradingview-mcp-server", "tradingview-mcp"]
}
}
}
```
资料来源：[README.md:90-99]()
启用插件后需重启 Codex 以加载 MCP 服务器。
## OpenClaw 集成安装
OpenClaw 允许通过 Telegram、WhatsApp、Discord 等 20+ 消息平台连接本服务。
### 工作原理
```mermaid
graph LR
A[Telegram/WhatsApp] --> B[OpenClaw Agent]
B --> C[AI 模型]
C --> D[trading.py wrapper]
D --> E[tradingview-mcp]
E --> F[Yahoo Finance]
```
### 安装步骤
```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
# 安装 tradingview-mcp-server
uv tool install tradingview-mcp-server
```
资料来源：[OPENCLAW.md:4-10]()
### Telegram 配置
创建或编辑 `~/.openclaw/openclaw.json`：
```json5
{
channels: {
telegram: {
botToken: "YOUR_BOT_TOKEN_HERE",
},
},
}
```
### 下载交易工具
```bash
mkdir -p ~/.agents/skills/tradingview-mcp ~/.openclaw/tools
# 下载 TradingView skill
curl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/SKILL.md \
-o ~/.agents/skills/tradingview-mcp/SKILL.md
# 下载交易执行包装器
curl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/trading.py \
-o ~/.openclaw/tools/trading.py
chmod +x ~/.openclaw/tools/trading.py
```
资料来源：[OPENCLAW.md:18-28]()
### 启动 OpenClaw
```bash
openclaw gateway install
systemctl --user start openclaw-gateway.service
openclaw doctor
```
## 平台特定说明
### Windows 注意事项
| 问题 | 解决方案 |
|------|----------|
| 直接 Python 路径更可靠 | 使用 `.venv\Scripts\python.exe` 而非 `uvx` |
| 首次启动超时 | 检查 `%APPDATA%\Claude\logs` 中的详细日志 |
| 路径分隔符 | 使用反斜杠 `\` 或双斜杠 `\\` |
**Windows 用户请注意：** 将 `YourUsername` 替换为实际的 Windows 用户名，并根据实际情况调整路径。
### macOS 注意事项
使用 uvx 时需指定完整路径：
```json
{
"mcpServers": {
"tradingview": {
"command": "/Users/YOUR_USERNAME/.local/bin/uvx",
"args": ["--from", "tradingview-mcp-server", "tradingview-mcp"]
}
}
}
```
资料来源：[README.md:66-72]()
### Linux 注意事项
路径格式为 `/home/YOUR_USERNAME`：
```json
{
"mcpServers": {
"tradingview": {
"command": "/home/YOUR_USERNAME/.local/bin/uvx",
"args": ["--from", "tradingview-mcp-server", "tradingview-mcp"]
}
}
}
```
## 故障排除
### Windows 首次启动超时错误
**症状：** 在 Claude Desktop 日志中看到 `MCP error -32001: Request timed out`
**解决方案：**
1. 使用直接 Python 路径替代 uvx
2. 首次启动等待 30-60 秒
3. 检查防火墙和网络设置
### uvx 找不到
**Windows：** 使用 `%USERPROFILE%\.local\bin\uvx.exe`
**macOS：** 使用 `/Users/YOUR_USERNAME/.local/bin/uvx`
**Linux：** 使用 `/home/YOUR_USERNAME/.local/bin/uvx`
### 预热缓存（可选优化）
在启动 Claude Desktop 前预先安装可加快首次响应速度：
```bash
uv tool install --python 3.13 tradingview-mcp-server
```
资料来源：[README.md:56-62]()
## 验证清单
| 检查项 | 预期结果 |
|--------|----------|
| 服务启动 | 无错误日志 |
| MCP 连接 | Claude Desktop 显示连接成功 |
| 工具列表 | 返回 20+ TradingView 工具 |
| 数据获取 | 成功获取实时价格或分析数据 |
## 开发环境测试
```bash
# 运行测试套件
uv run pytest
# 运行代码检查
uv run ruff check
# 运行类型检查
uv run mypy src/
```
资料来源：[CONTRIBUTING.md:14-16]()
## 目录结构
```
tradingview-mcp/
├── src/tradingview_mcp/
│ ├── server.py # 主 MCP 服务器
│ ├── core/ # 核心业务逻辑
│ │ ├── services/ # 市场数据服务
│ │ ├── utils/ # 工具函数
│ │ └── indicators/ # 技术指标
│ └── coinlist/ # 交易所符号列表
├── tests/ # 测试文件
├── openclaw/ # OpenClaw 集成
├── .codex-plugin/ # Codex 插件元数据
└── pyproject.toml # 项目配置
```
资料来源：[CONTRIBUTING.md:26-34]()
## 后续步骤
安装完成后，可尝试以下操作：
1. **获取市场快照：** 询问 `"Give me a full market snapshot right now"`
2. **技术分析：** 使用 `get_technical_analysis` 分析具体股票或加密货币
3. **回测策略：** 使用 `backtest_strategy` 测试交易策略表现
4. **市场筛选：** 使用 `top_gainers` 或 `screen_stocks` 筛选标的
---
## 系统架构
### 相关页面
相关主题：[核心组件](#page-core-components), [回测引擎](#page-backtesting-engine)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)
- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)
- [src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)
- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)
- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)
- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)
# 系统架构
## 概述
tradingview-mcp 是一个基于 Model Context Protocol (MCP) 的服务器项目，旨在为 AI 助手提供 TradingView 金融市场的数据访问能力。该项目通过 MCP 协议将 TradingView 的技术分析、市场筛选、价格查询等功能封装为可调用的工具，使 AI 代理能够获取实时市场数据并进行技术分析决策。
项目采用模块化架构设计，核心业务逻辑集中在 `src/tradingview_mcp/core/` 目录下，分为服务层（services）、工具层（utils）和指标层（indicators）。资料来源：[CONTRIBUTING.md]()
## 架构分层
系统采用经典的三层架构模式，各层职责明确、边界清晰：
```mermaid
graph TD
A[MCP 客户端
Claude Desktop / Codex] --> B[MCP 服务器层
server.py]
B --> C[业务逻辑层
core/services]
B --> D[工具层
core/utils]
C --> E[数据源
tradingview_ta
Yahoo Finance]
C --> F[指标计算层
core/indicators]
```
### MCP 服务器层
MCP 服务器层是整个系统的入口点，负责处理 MCP 协议通信并将客户端请求路由到相应的业务逻辑。
**核心职责：**
- 初始化 MCP 服务器并注册所有工具
- 处理请求参数验证和错误处理
- 返回格式化的 JSON 响应
**主要组件：**
| 组件 | 文件路径 | 描述 |
|------|----------|------|
| 服务器入口 | `src/tradingview_mcp/server.py` | MCP 服务器主程序 |
| 工具注册 | server.py | 使用 `@server.list_tool()` 装饰器注册工具 |
资料来源：[src/tradingview_mcp/server.py]()
### 业务逻辑层
业务逻辑层位于 `src/tradingview_mcp/core/services/` 目录下，包含核心的数据处理和业务规则。
**服务模块：**
| 服务名称 | 文件 | 核心功能 |
|----------|------|----------|
| ScreenerService | screener_service.py | 市场筛选、技术指标计算、K线形态分析 |
| ExchangeValidator | validators.py | 交易所名称验证和前缀处理 |
**核心数据结构：**
```python
# 多时间框架数据结构
MultiRow(symbol=str, changes=dict, base_indicators=IndicatorMap)
# 指标映射结构
IndicatorMap(open, close, SMA20, BB_upper, BB_lower, volume)
```
资料来源：[src/tradingview_mcp/core/services/screener_service.py:1-50]()
### 工具层
工具层位于 `src/tradingview_mcp/core/utils/` 目录下，提供数据验证、格式化和辅助功能。
**核心工具：**
| 工具名称 | 功能描述 |
|----------|----------|
| `sanitize_exchange()` | 验证并标准化交易所名称 |
| `sanitize_timeframe()` | 验证并标准化时间周期 |
| `is_stock_exchange()` | 判断是否为股票交易所 |
| `get_tv_exchange_prefix()` | 获取 TradingView 交易所前缀 |
| `get_market_type()` | 获取市场类型 |
资料来源：[src/tradingview_mcp/core/utils/validators.py]()
## 核心组件设计
### 交易所验证器
交易所验证器是系统的关键组件，负责将用户输入的交易所名称映射到 TradingView 可识别的格式。
**交易所映射表：**
| 用户输入 | 内部存储 | TradingView 前缀 |
|----------|----------|------------------|
| NYSEARCA | nysearca | AMEX |
| PCX | pcx | AMEX |
| AMEX | amex | AMEX |
| NYSE | nyse | NYSE |
| NASDAQ | nasdaq | NASDAQ |
| TWSE | twse | TWSE |
| TPEX | tpex | TPEX |
| KUCOIN | kucoin | KUCOIN |
| BINANCE | binance | BINANCE |
**关键函数实现：**
```python
def get_tv_exchange_prefix(exchange: str) -> str:
"""将交易所名称转换为 TradingView 格式前缀"""
return _EXCHANGE_TV_PREFIX.get(exchange.strip().lower(), exchange.upper())
```
资料来源：[src/tradingview_mcp/core/utils/validators.py]()
### 技术指标计算器
技术指标计算器集成在 screener_service.py 中，支持 30+ 技术指标的计算。
**支持的指标类型：**
| 指标类别 | 具体指标 |
|----------|----------|
| 趋势指标 | SMA、EMA、MACD、Supertrend、Donchian |
| 动量指标 | RSI、CCI、ADX |
| 波动率指标 | Bollinger Bands、ATR、Standard Deviation |
| 成交量指标 | OBV、Volume、Volume Profile |
**K线形态识别：**
系统内置 15 种 K 线形态识别模式，通过 `calculate_candle_pattern_score()` 函数进行评分计算。
资料来源：[src/tradingview_mcp/core/services/screener_service.py:40-80]()
## 数据流架构
### 请求处理流程
```mermaid
graph LR
A[用户请求] --> B[参数验证
sanitize_exchange]
B --> C[交易所映射
get_tv_exchange_prefix]
C --> D[TradingView API
tradingview_ta]
D --> E[数据解析
IndicatorMap]
E --> F[指标计算
technical_analysis]
F --> G[结果格式化
JSON Response]
```
### 数据源集成
系统支持多个数据源，以满足不同市场的数据需求：
| 数据源 | 用途 | 数据类型 |
|--------|------|----------|
| TradingView (tradingview_ta) | 技术分析、K线数据 | 30+ 指标、价格数据 |
| Yahoo Finance | 实时价格、市场快照 | 实时报价、52 周高低 |
资料来源：[README.md]()
## 工具生态
### MCP 工具分类
| 类别 | 工具数量 | 代表工具 |
|------|----------|----------|
| 市场数据 | 5+ | `yahoo_price`, `market_snapshot`, `get_prices_bulk` |
| 技术分析 | 7+ | `get_technical_analysis`, `get_bollinger_band_analysis` |
| 市场筛选 | 4+ | `top_gainers`, `top_losers`, `screen_stocks` |
| 形态识别 | 2+ | `get_candlestick_patterns`, `scan_by_signal` |
| 回测系统 | 6+ | `backtest_strategy`, `compare_strategies` |
资料来源：[README.md]()
### 交易所支持矩阵
| 交易所 | 代码 | 支持功能 |
|--------|------|----------|
| Binance | BINANCE | 加密货币全品种 |
| KuCoin | KUCOIN | 加密货币筛选 |
| Bybit | BYBIT | 加密货币筛选 |
| MEXC | MEXC | 加密货币筛选 |
| NASDAQ | NASDAQ | 美国股票 |
| NYSE | NYSE | 美国股票 |
| NYSE ARCA | NYSEARCA | ETF、黄金、白银 |
| AMEX | AMEX | 美国股票 |
| TWSE | TWSE | 台湾股票 |
| TPEX | TPEX | 台湾兴柜 |
| EGX | EGX | 埃及股票 |
| BIST | BIST | 土耳其股票 |
资料来源：[src/tradingview_mcp/core/utils/validators.py]()
## 项目结构
```
tradingview-mcp/
├── src/tradingview_mcp/
│ ├── __init__.py # 包初始化
│ ├── server.py # MCP 服务器入口
│ ├── core/
│ │ ├── services/ # 业务服务层
│ │ │ └── screener_service.py
│ │ ├── utils/ # 工具函数
│ │ │ └── validators.py
│ │ └── indicators/ # 技术指标
│ ├── coinlist/ # 交易所符号列表
│ └── ... # 其他模块
├── tests/
│ └── unit/ # 单元测试
├── assets/
│ └── architecture.png # 架构图
└── pyproject.toml # 项目配置
```
资料来源：[CONTRIBUTING.md]()
## 安装与部署架构
### 部署模式
系统支持多种部署方式，以适应不同的使用场景：
| 部署方式 | 适用场景 | 配置复杂度 |
|----------|----------|------------|
| PyPI 安装 | 生产环境快速部署 | 低 |
| 源码开发 | 需要修改代码 | 中 |
| OpenClaw 集成 | Telegram/WhatsApp 接入 | 中 |
| Claude Desktop | 个人使用 | 低 |
### Claude Desktop 配置
```json
{
"mcpServers": {
"tradingview-mcp": {
"command": "uvx",
"args": ["--from", "tradingview-mcp-server", "tradingview-mcp"]
}
}
}
```
资料来源：[INSTALLATION.md]()
## 扩展机制
### 添加新交易所
1. 在 `validators.py` 的 `EXCHANGE_SCREENER` 中添加交易所代码
2. 在 `_EXCHANGE_TV_PREFIX` 中添加前缀映射
3. 如需符号列表，在 `coinlist/` 目录添加对应文件
### 添加新指标
1. 在 `core/indicators/` 目录创建指标计算函数
2. 在 `screener_service.py` 中集成新指标
3. 更新工具返回值结构
资料来源：[CONTRIBUTING.md]()
## 测试架构
系统采用多层次测试策略确保代码质量：
| 测试类型 | 覆盖范围 | 测试工具 |
|----------|----------|----------|
| 单元测试 | 独立函数、工具函数 | pytest |
| 集成测试 | API 调用、数据流 | pytest + 实际 API |
| Linting | 代码风格 | ruff |
| 类型检查 | 类型注解 | mypy |
**测试命令：**
```bash
uv run pytest # 运行测试套件
uv run ruff check # 代码风格检查
uv run mypy src/ # 类型检查
```
资料来源：[CONTRIBUTING.md]()
## 安全考量
### 敏感数据处理
- API 密钥不存储在代码仓库中
- 通过环境变量或配置文件注入
- Claude Desktop 配置中的凭证需妥善保管
### 输入验证
所有用户输入均通过验证器进行清理：
```python
exchange = sanitize_exchange(user_input) # 防止注入攻击
timeframe = sanitize_timeframe(user_input) # 防止恶意时间周期
```
资料来源：[src/tradingview_mcp/core/utils/validators.py]()
## 版本管理
项目遵循语义化版本控制 (Semantic Versioning)：
| 版本类型 | 触发条件 |
|----------|----------|
| Major (X.0.0) | 破坏性 API 变更 |
| Minor (0.X.0) | 新增功能，向后兼容 |
| Patch (0.0.X) | Bug 修复，向后兼容 |
资料来源：[CONTRIBUTING.md]()
## 相关资源
- 官方文档：[GitHub Repository](https://github.com/atilaahmettaner/tradingview-mcp)
- 问题反馈：[Issue Tracker](https://github.com/atilaahmettaner/tradingview-mcp/issues)
- 赞助项目：[GitHub Sponsors](https://github.com/sponsors/atilaahmettaner)
---
## 核心组件
### 相关页面
相关主题：[系统架构](#page-architecture), [技术分析服务](#page-technical-analysis)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)
- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)
- [src/tradingview_mcp/core/services/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)
- [src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)
- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)
- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)
- [PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)
# 核心组件
## 概述
`tradingview-mcp` 是一个基于 Model Context Protocol (MCP) 的交易分析工具，通过 MCP 协议与 Claude Desktop、Codex 等 AI 助手集成，为用户提供实时市场数据、技术分析和交易策略回测功能。
核心组件架构遵循模块化设计原则，将业务逻辑、数据服务、工具函数分离，便于维护和扩展。
资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)
## 系统架构
```mermaid
graph TD
A[MCP Client
Claude Desktop/Codex] --> B[MCP Server
server.py]
B --> C[核心业务逻辑层]
C --> D[Services
数据服务层]
C --> E[Indicators
指标计算层]
C --> F[Utils
工具函数层]
D --> G[TradingView API]
D --> H[Yahoo Finance API]
D --> I[Reddit/News RSS]
```
### 目录结构
```
src/tradingview_mcp/
├── server.py # MCP 主服务器入口
├── core/ # 核心业务逻辑
│ ├── services/ # 市场数据服务
│ │ ├── screener_service.py # 筛选器服务
│ │ └── egx_service.py # 埃及交易所服务
│ ├── utils/ # 工具函数
│ │ └── validators.py # 验证器
│ └── indicators/ # 技术指标
├── coinlist/ # 交易所符号列表
└── __init__.py
```
资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)
## MCP 服务器 (server.py)
`server.py` 是整个项目的入口点，负责：
1. **注册 MCP 工具** - 将所有分析功能暴露为 AI 可调用的工具
2. **处理请求路由** - 将客户端请求分发到对应的服务层
3. **返回格式化结果** - 将数据分析结果转换为可读格式
### 主要工具类别
| 类别 | 工具数量 | 功能描述 |
|------|---------|---------|
| 市场数据 | 5+ | 实时价格、行情快照、多交易所支持 |
| 技术分析 | 7+ | RSI、MACD、布林带等30+指标 |
| 筛选器 | 6+ | 按涨跌幅、信号类型筛选标的 |
| 回测引擎 | 2 | 6种策略回测与对比 |
| 情绪分析 | 2 | Reddit情绪、新闻摘要 |
资料来源：[README.md:1-50](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)
## 验证器模块 (validators.py)
`validators.py` 负责交易所标识符的规范化处理，是多交易所支持的核心基础设施。
### 核心功能
#### 1. 交易所名称规范化
```python
sanitize_exchange(exchange: str) -> str
```
将用户输入的交易所别名转换为标准名称：
| 输入别名 | 输出标准名 | 用途 |
|---------|-----------|------|
| `AMEX` | `AMEX` | 美国股票 |
| `NYSEARCA` | `AMEX` | AMEX 交易所 |
| `PCX` | `AMEX` | Polygon 分类 |
| `NYSE` | `NYSE` | 纽约证券交易所 |
| `NASDAQ` | `NASDAQ` | 纳斯达克 |
| `KUCOIN` | `KUCOIN` | KuCoin 交易所 |
#### 2. TradingView 前缀映射
```python
get_tv_exchange_prefix(exchange: str, symbol: str) -> str
```
为符号生成正确的 TradingView 交易所前缀格式：
- 股票符号：`AMEX:GDX` → `AMEX:GDX`
- 加密货币：`KUCOIN:SOLUSDT` → `KUCOIN:SOLUSDT`
#### 3. 支持的交易所配置
```python
STOCK_EXCHANGES = {"NYSE", "NASDAQ", "AMEX", "TWSE", "TPEX"}
EXCHANGE_SCREENER = {
"NYSE": "NYSE",
"NASDAQ": "NASDAQ",
"AMEX": "AMEX",
"KUCOIN": "Crypto",
"BINANCE": "Crypto",
"TWSE": "Taiwan",
"TPEX": "Taiwan"
}
```
资料来源：[PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)
## 筛选器服务 (screener_service.py)
`screener_service.py` 实现市场数据筛选和技术分析功能。
### 核心数据结构
```python
class IndicatorMap:
"""技术指标数据映射"""
open: float
close: float
SMA20: float
BB_upper: float
BB_lower: float
volume: float
class MultiRow:
"""多周期行数据"""
symbol: str
changes: dict # 各周期涨跌幅
base_indicators: IndicatorMap
```
### 主要分析函数
#### 1. 蜡烛图形态评分
```python
def calculate_candle_pattern_score(
indicators: dict,
pattern_length: int,
min_increase: float,
) -> dict
```
评估蜡烛图形态强度，考虑因素：
- **实体比例** - 开盘价与收盘价的差异
- **动量** - 价格变化幅度
- **成交量** - 交易量确认
- **RSI** - 相对强弱指标
返回结构：
```python
{
"detected": bool, # 是否检测到形态
"score": int, # 形态强度评分
"details": list, # 详细分析
"rsi": float # RSI 值
}
```
#### 2. 多周期分析
支持的时间周期：
| 周期代码 | 描述 |
|---------|------|
| `1m` | 1分钟 |
| `5m` | 5分钟 |
| `15m` | 15分钟 |
| `1h` | 1小时 |
| `4h` | 4小时 |
| `1D` | 日线 |
| `1W` | 周线 |
资料来源：[screener_service.py:1-80](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)
## 埃及交易所服务 (egx_service.py)
`egx_service.py` 专门处理埃及证券交易所 (EGX) 的数据和分析需求。
### 主要功能
#### 1. EGX 股票筛选器
基于动量和质量评分的股票筛选：
| 评分维度 | 阈值 | 说明 |
|---------|------|------|
| 动量评分 (ss) | ≥70 | 价格动能强度 |
| 质量评分 (tq) | ≥65 | 财务质量指标 |
| 相对强度 (rr2) | ≥2.0 | 行业相对表现 |
#### 2. 推荐等级
| 推荐等级 | 条件 | 含义 |
|---------|------|------|
| `QUALIFIED` | ss≥70 AND tq≥65 AND rr2≥2.0 | 强烈推荐 |
| `CONDITIONAL` | ss≥70 AND tq≥50 | 有条件推荐 |
| `WATCHLIST` | ss≥55 | 关注观察 |
| `AVOID` | 其他 | 不建议 |
#### 3. 斐波那契回撤分析
```python
def analyze_egx_fibonacci(
symbol: str,
lookback: str = "52W",
timeframe: str = "1D",
) -> dict
```
支持回溯周期：
- `1M` - 1个月
- `3M` - 3个月
- `6M` - 6个月
- `52W` - 52周（默认）
- `ALL` - 全时段
资料来源：[egx_service.py:1-100](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)
## 命名规范
项目遵循统一的命名约定，确保代码可读性：
| 类型 | 规范 | 示例 |
|-----|------|------|
| 函数 | `snake_case` | `get_top_gainers` |
| 类 | `PascalCase` | `MarketAnalyzer` |
| 常量 | `UPPER_SNAKE_CASE` | `DEFAULT_LIMIT` |
| 文件 | `snake_case.py` | `market_utils.py` |
资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)
## 工具注册与调用流程
```mermaid
sequenceDiagram
participant User as 用户
participant MCP as MCP Server
participant Service as Service Layer
participant API as External API
User->>MCP: "分析 BTC-USDT 的技术指标"
MCP->>MCP: 路由到 get_technical_analysis
MCP->>Service: 调用 screener_service
Service->>API: TradingView Screener API
API-->>Service: 原始指标数据
Service-->>MCP: 计算后的分析结果
MCP-->>User: 格式化响应
```
## 依赖关系
项目依赖以下核心包：
| 包名 | 用途 | 来源 |
|-----|------|------|
| `tradingview_ta` | TradingView 技术分析 | PyPI |
| `yfinance` | Yahoo Finance 数据 | PyPI |
| `mcp` | MCP 协议实现 | PyPI |
| `fastapi` | HTTP 服务框架 | PyPI |
资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)
## 扩展指南
### 添加新的技术指标
1. 在 `core/indicators/` 目录下创建指标函数
2. 在 `server.py` 中注册为 MCP 工具
3. 添加单元测试
### 添加新交易所支持
1. 更新 `validators.py` 中的交易所映射
2. 在 `EXCHANGE_SCREENER` 添加对应条目
3. 测试符号构造：`get_tv_exchange_prefix("NEW_EX", "SYMBOL")`
资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)
---
## 回测引擎
### 相关页面
相关主题：[技术分析服务](#page-technical-analysis), [核心组件](#page-core-components)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)
- [src/tradingview_mcp/core/services/backtest_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/backtest_service.py)
- [src/tradingview_mcp/core/services/multi_agent_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/multi_agent_service.py)
- [src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)
- [CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)
- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)
# 回测引擎
## 概述
回测引擎（Backtesting Engine）是 tradingview-mcp 项目中负责历史数据验证交易策略的核心模块。该引擎通过加载历史价格数据，模拟策略在实际市场中的表现，帮助交易者和开发者评估策略的有效性、风险特征和潜在收益。
回测引擎的主要职责包括：
- **策略回测**：对单个交易策略进行历史数据回测
- **多策略比较**：并排运行多个策略并按性能排名
- **Walk-Forward 分析**：使用样本外数据验证策略稳定性
- **指标计算**：提供机构级别的评估指标（Sharpe、Calmar、胜率等）
## 架构设计
```
┌─────────────────────────────────────────────────────────────────┐
│ MCP Server │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ backtest_ │ │ compare_ │ │ walk_forward_ │ │
│ │ strategy │ │ strategies │ │ backtest_strategy │ │
│ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ │
└─────────┼─────────────────┼────────────────────┼───────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ backtest_service.py │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ Strategy Engine ││
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ ││
│ │ │ RSI │ │Bollinger│ │ MACD │ │EMA Cross│ │Super.. │ ││
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └────────┘ ││
│ └─────────────────────────────────────────────────────────────┘│
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ Metrics Calculator ││
│ │ Sharpe | Calmar | Win Rate | Max DD | Profit Factor ││
│ └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
```
## 支持的交易策略
回测引擎内置 **6 种交易策略**，涵盖均值回归、趋势跟踪和突破策略三大类别。
### 策略类型一览
| 策略标识 | 中文名称 | 策略类别 | 核心逻辑 |
|----------|----------|----------|----------|
| `rsi` | RSI 策略 | 均值回归 | RSI 超卖买入，超买卖出 |
| `bollinger` | 布林带策略 | 均值回归 | 价格触及下轨买入，上轨卖出 |
| `macd` | MACD 策略 | 趋势跟踪 | MACD 金叉买入，死叉卖出 |
| `ema_cross` | EMA 交叉策略 | 趋势跟踪 | EMA 20/50 黄金交叉买入，死亡交叉卖出 |
| `supertrend` | Supertrend 策略 | 趋势跟踪 | ATR 计算动态止损，顺势交易 |
| `donchian` | 唐奇安通道策略 | 突破策略 | 价格突破通道高点买入，跌破低点卖出 |
### 策略详情
#### RSI 均值回归策略
```python
# 核心逻辑伪代码
if rsi < 30: # 超卖区域 → 买入信号
signal = "BUY"
elif rsi > 70: # 超买区域 → 卖出信号
signal = "SELL"
```
#### 布林带策略
```python
# 核心逻辑伪代码
if price < lower_band: # 触及下轨 → 买入信号
signal = "BUY"
elif price > upper_band: # 触及上轨 → 卖出信号
signal = "SELL"
```
#### Supertrend 策略（最受欢迎）
```python
# 核心逻辑伪代码
atr_value = calculate_atr(high, low, close, period=10)
upper_band = (high + low) / 2 + multiplier * atr_value
lower_band = (high + low) / 2 - multiplier * atr_value
if close > upper_band: # 上穿通道 → 买入信号
signal = "BUY"
elif close < lower_band: # 下穿通道 → 卖出信号
signal = "SELL"
```
资料来源：[README.md](README.md)
## MCP 工具接口
### 1. backtest_strategy — 单策略回测
对单个策略进行完整的回测分析，返回详细的绩效指标和交易记录。
**参数列表**
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `symbol` | string | 是 | — | 交易标的符号（如 `BTC-USD`、`AAPL`） |
| `strategy` | string | 是 | — | 策略名称：`rsi`、`bollinger`、`macd`、`ema_cross`、`supertrend`、`donchian` |
| `period` | string | 否 | `"1y"` | 回测周期：`1mo`、`3mo`、`6mo`、`1y`、`2y` |
| `interval` | string | 否 | `"1d"` | K线周期：`1h`（小时）、`1d`（日线） |
| `include_trade_log` | boolean | 否 | `false` | 是否包含完整交易明细 |
| `include_equity_curve` | boolean | 否 | `false` | 是否包含权益曲线数据 |
**返回值结构**
```json
{
"strategy": "supertrend",
"symbol": "BTC-USD",
"period": "2y",
"interval": "1d",
"metrics": {
"total_return": 31.5,
"win_rate": 62.0,
"sharpe_ratio": 2.1,
"calmar_ratio": 1.8,
"max_drawdown": -12.3,
"profit_factor": 2.4,
"expectancy": 1.25,
"total_trades": 45,
"best_trade": 8.5,
"worst_trade": -3.2,
"vs_buy_hold": 15.2
},
"recent_trades": [...],
"trade_log": [...],
"equity_curve": [...]
}
```
资料来源：[CHANGELOG.md](CHANGELOG.md)
### 2. compare_strategies — 多策略比较
在相同标的上同时运行全部 6 种策略，按性能指标综合排名。
**参数列表**
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `symbol` | string | 是 | — | 交易标的符号 |
| `period` | string | 否 | `"1y"` | 回测周期 |
| `interval` | string | 否 | `"1d"` | K线周期 |
**返回值示例**
```
#1 Supertrend: +31.5% | Sharpe: 2.1 | WR: 62%
#2 Bollinger: +18.3% | Sharpe: 3.4 | WR: 75%
#3 EMA Cross: +12.1% | Sharpe: 1.9 | WR: 58%
#4 MACD: +8.7% | Sharpe: 1.5 | WR: 52%
#5 RSI: +5.2% | Sharpe: 1.2 | WR: 48%
#6 Donchian: -2.1% | Sharpe: 0.8 | WR: 42%
Buy & Hold: -5.0%
```
资料来源：[README.md](README.md)
### 3. walk_forward_backtest_strategy — Walk-Forward 分析
将数据分为训练集和测试集，在样本外数据上验证策略的泛化能力。
**参数列表**
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `symbol` | string | 是 | — | 交易标的符号 |
| `strategy` | string | 是 | — | 策略名称 |
| `n_splits` | integer | 否 | 5 | 分割次数（2-10） |
| `train_ratio` | float | 否 | 0.7 | 训练集比例（0.5-0.9） |
| `interval` | string | 否 | `"1d"` | K线周期 |
**输出内容**
- **样本内指标**：训练集上的平均 Sharpe、胜率、最大回撤、总收益
- **样本外指标**：测试集上的平均表现
- **稳定性评估**：样本内外指标的差异程度
## 绩效指标说明
### 机构级指标定义
| 指标 | 英文名 | 计算方式 | 理想值 |
|------|--------|----------|--------|
| 总收益率 | Total Return | (期末净值 - 期初净值) / 期初净值 × 100% | > 0 |
| 胜率 | Win Rate | 盈利交易数 / 总交易数 × 100% | > 50% |
| Sharpe 比率 | Sharpe Ratio | (策略收益 - 无风险收益) / 策略波动率 | > 1.5 |
| Calmar 比率 | Calmar Ratio | 年化收益 / 最大回撤 | > 2.0 |
| 最大回撤 | Max Drawdown | 历史最高点到最低点的最大跌幅 | < 20% |
| 利润因子 | Profit Factor | 总盈利 / 总亏损 | > 1.5 |
| 期望值 | Expectancy | (胜率 × 平均盈利) - (败率 × 平均亏损) | > 0 |
### Sharpe 比率年化因子
引擎会根据不同的时间周期自动调整 Sharpe 比率的年化计算：
| 周期 | 年化因子 |
|------|----------|
| 日线 (`1d`) | 252（交易日） |
| 小时线 (`1h`) | 252 × 6（每日交易小时） |
```python
# Sharpe 计算逻辑示例
if interval == "1h":
annualization_factor = 252 * 6 # 修正小时线年化
else:
annualization_factor = 252
```
资料来源：[CHANGELOG.md](CHANGELOG.md)
## 交易记录与权益曲线
### 交易明细（Trade Log）
启用 `include_trade_log=True` 后，返回完整的每笔交易记录：
```json
{
"trade_log": [
{
"entry_date": "2024-01-15",
"exit_date": "2024-01-28",
"entry_price": 41250.00,
"exit_price": 43580.00,
"holding_days": 13,
"gross_return": 5.65,
"net_return": 5.42,
"commission_cost": 0.23,
"running_capital": 10542.00,
"cumulative_return": 5.42
}
]
}
```
### 权益曲线（Equity Curve）
启用 `include_equity_curve=True` 后，返回每个交易退出时点的权益变化：
```json
{
"equity_curve": [
{
"date": "2024-01-28",
"capital_value": 10542.00,
"drawdown_pct": -2.1
},
{
"date": "2024-02-15",
"capital_value": 11280.00,
"drawdown_pct": 0
}
]
}
```
### 快速预览机制
即使未启用完整交易日志，引擎始终返回最近 **5 笔交易**（`recent_trades`）供快速检查：
```json
{
"recent_trades": [
{"symbol": "BTC-USD", "entry": 42100, "exit": 43500, "pnl": 3.3},
{"symbol": "BTC-USD", "entry": 43500, "exit": 42800, "pnl": -1.6},
{"symbol": "BTC-USD", "entry": 42800, "exit": 44200, "pnl": 3.3}
]
}
```
资料来源：[CHANGELOG.md](CHANGELOG.md)
## 使用示例
### 基础回测
```python
# 回测 BTC 的 Supertrend 策略
result = backtest_strategy(
symbol="BTC-USD",
strategy="supertrend",
period="1y",
interval="1d"
)
```
### 完整交易分析
```python
# 包含交易明细和权益曲线
result = backtest_strategy(
symbol="AAPL",
strategy="bollinger",
period="2y",
interval="1d",
include_trade_log=True,
include_equity_curve=True
)
```
### 策略比较
```python
# 比较所有策略
result = compare_strategies(
symbol="ETH-USD",
period="1y"
)
```
### Walk-Forward 验证
```python
# 使用 5 折交叉验证
result = walk_forward_backtest_strategy(
symbol="BTC-USD",
strategy="rsi",
n_splits=5,
train_ratio=0.7,
interval="1d"
)
```
## 与多代理系统的集成
回测引擎可与 `multi_agent_service.py` 中的技术分析代理协同工作：
```mermaid
graph LR
A[用户请求] --> B{分析类型}
B -->|技术分析| C[Technical Analyst]
B -->|回测请求| D[Backtest Engine]
B -->|综合决策| E[Multi-Agent Hub]
C --> F[技术指标]
D --> G[绩效指标]
E --> H[情绪分析]
E --> I[风险评估]
F --> J[综合评分]
G --> J
H --> J
I --> J
J --> K[最终建议]
```
多代理系统包含三个专业代理：
| 代理 | 职责 | 输出 |
|------|------|------|
| 技术分析师 | 布林带(±3评级)、RSI、MACD | 技术信号 |
| 情绪分析师 | Reddit 社区情绪、价格动量 | 情绪评分 |
| 风险管理器 | 波动性、回撤风险、均值回归信号 | 风险评估 |
**最终输出**：`STRONG BUY` / `BUY` / `HOLD` / `SELL` / `STRONG SELL` 附置信度评分
资料来源：[server.py](src/tradingview_mcp/server.py)、[README.md](README.md)
## 模拟参数说明
### 佣金与滑点
回测引擎包含**现实的佣金和滑点模拟**：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| 佣金率 | 0.1% | 每笔交易的手续费 |
| 滑点 | 模拟 | 订单执行时的价格偏差 |
### 初始资金
默认使用模拟资金进行计算，盈亏以百分比形式呈现，便于不同规模账户的对比。
## 注意事项与限制
### ⚠️ 重要声明
> **⚠️ 过去表现不保证未来结果**
>
> 所有回测结果仅供历史参考，实际交易中可能出现与回测显著不同的结果。市场条件、流动性、执行质量等因素均会影响策略表现。
### 技术限制
1. **数据延迟**：依赖历史数据，非实时价格
2. **流动性假设**：未考虑大额订单对市场的影响
3. **执行假设**：按收盘价成交，实际可能存在滑点
4. **过拟合风险**：过度优化可能导致样本内表现优异、样本外失效
### Walk-Forward 分析的价值
为降低过拟合风险，建议：
- 使用 Walk-Forward 分析验证策略稳定性
- 样本外 Sharpe 比率应接近样本内水平
- 避免过度追求单一指标的最优值
## 文件结构
```
src/tradingview_mcp/
├── server.py # MCP 工具入口
└── core/services/
├── backtest_service.py # 回测引擎核心实现
└── multi_agent_service.py # 多代理分析服务
```
资料来源：[server.py](src/tradingview_mcp/server.py)
## 版本历史
| 版本 | 发布日期 | 主要更新 |
|------|----------|----------|
| 0.7.0 | 2026-04 | Walk-Forward 分析、交易明细、权益曲线 |
| 0.6.0 | 2026-03-29 | Backtesting Engine v2、6 种策略、机构级指标 |
资料来源：[CHANGELOG.md](CHANGELOG.md)
---
## 技术分析服务
### 相关页面
相关主题：[回测引擎](#page-backtesting-engine), [数据源与货币列表](#page-data-sources)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tradingview_mcp/core/services/indicators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators.py)
- [src/tradingview_mcp/core/services/indicators_calc.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators_calc.py)
- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)
- [src/tradingview_mcp/core/services/scanner_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/scanner_service.py)
- [src/tradingview_mcp/core/services/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)
- [src/tradingview_mcp/core/data/egx_sectors.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/data/egx_sectors.py)
# 技术分析服务
## 概述
技术分析服务是 `tradingview-mcp` 项目的核心模块，负责从 TradingView 获取市场数据并计算各种技术指标。该服务集成了 30+ 技术指标，包括 RSI、MACD、布林带等主流分析工具，为 AI 交易代理提供实时市场分析能力。
## 架构概览
```mermaid
graph TD
subgraph "技术分析服务架构"
A[server.py
MCP接口层] --> B[技术分析服务层]
B --> C[screener_service.py
筛选服务]
B --> D[scanner_service.py
扫描服务]
B --> E[indicators.py
指标定义]
B --> F[indicators_calc.py
指标计算]
B --> G[egx_service.py
埃及交易所服务]
C --> H[tradingview_ta
数据源]
D --> H
F --> H
end
subgraph "输出层"
B --> I[技术分析结果]
B --> J[筛选/扫描结果]
B --> K[斐波那契分析]
end
```
## 核心服务组件
### 1. 筛选服务 (screener_service.py)
筛选服务负责从 TradingView 获取市场筛选数据，支持多交易所、多时间周期的市场扫描。
#### 关键数据结构
| 数据结构 | 用途 | 主要字段 |
|---------|------|---------|
| `MultiRow` | 单个标的的多时间周期数据 | symbol, changes, base_indicators |
| `IndicatorMap` | 技术指标映射 | open, close, SMA20, BB_upper, BB_lower, volume |
资料来源：[src/tradingview_mcp/core/services/screener_service.py:1-30]()
#### 烛台模式分析
`screener_service.py` 中的 `calculate_candle_pattern_score` 函数提供了烛台形态评分功能：
```python
def calculate_candle_pattern_score(
indicators: dict,
pattern_length: int,
min_increase: float,
) -> dict
```
**功能说明：**
- 根据价格形态、身体比率、动量、成交量和 RSI 进行综合评分
- 返回检测结果、得分、明细列表及计算字段
**参数说明：**
| 参数 | 类型 | 说明 |
|-----|------|------|
| indicators | dict | 来自 tradingview_ta 的原始指标数据 |
| pattern_length | int | 分析的连续周期数 |
| min_increase | float | 最小价格变化百分比阈值 |
**返回值结构：**
| 字段 | 类型 | 说明 |
|-----|------|------|
| detected | bool | 是否检测到有效形态 |
| score | int | 形态强度评分 |
| details | list | 详细分析结果 |
| 计算字段 | float | open_price, close_price, high_price, low_price, volume, rsi |
资料来源：[src/tradingview_mcp/core/services/screener_service.py:56-85]()
### 2. 扫描服务 (scanner_service.py)
扫描服务提供市场扫描功能，支持按信号类型、连续烛台、技术指标等维度进行市场筛选。
```mermaid
graph LR
A[扫描请求] --> B[信号类型过滤]
B --> C[连续烛台检测]
C --> D[技术指标筛选]
D --> E[扫描结果输出]
```
**支持的扫描类型：**
| 扫描类型 | 说明 | 应用场景 |
|---------|------|---------|
| `oversold` | 超卖信号扫描 | RSI < 30 的标的 |
| `overbought` | 超买信号扫描 | RSI > 70 的标的 |
| `bullish` | 看涨形态扫描 | 连续阳线、突破形态 |
| `bearish` | 看跌形态扫描 | 连续阴线、跌破形态 |
| `breakout` | 突破扫描 | 突破布林带上轨/阻力位 |
### 3. 指标计算服务 (indicators_calc.py)
指标计算服务封装了所有技术指标的计算逻辑，提供标准化的事件分析接口。
#### 支持的指标类型
| 指标类别 | 包含指标 | 用途 |
|---------|---------|------|
| 趋势类 | SMA, EMA, MACD, Supertrend | 判断市场趋势方向 |
| 振荡类 | RSI, Stochastic, CCI, Williams %R | 判断超买超卖 |
| 波动类 | Bollinger Bands, ATR, Donchian | 衡量价格波动幅度 |
| 成交量类 | OBV, Volume SMA | 分析成交量与价格关系 |
| 形态类 | 15种烛台形态识别 | 价格反转信号 |
### 4. 埃及交易所专用服务 (egx_service.py)
EGX 服务为埃及证券交易所提供专业分析工具，包括斐波那契回撤分析和股票评分系统。
#### 斐波那契回撤分析
```python
def analyze_egx_fibonacci(
symbol: str,
lookback: str = "52W",
timeframe: str = "1D",
) -> dict
```
**参数说明：**
| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| symbol | str | 必需 | EGX 股票代码（如 'COMI'） |
| lookback | str | "52W" | 回溯周期：'1M', '3M', '6M', '52W', 'ALL' |
| timeframe | str | "1D" | TradingView 时间周期 |
**返回字段：**
| 字段 | 说明 |
|-----|------|
| fib_levels | 斐波那契回撤/扩展价位 |
| price_position | 当前价格在回撤中的位置 |
| swing_high/low | 周期内最高/最低价 |
| context | 市场背景分析 |
资料来源：[src/tradingview_mcp/core/services/egx_service.py:100-150]()
#### 股票评分系统
EGX 服务包含多维度股票评分引擎：
```mermaid
graph TD
A[股票评分输入] --> B[技术强度 SS]
A --> C[交易质量 TQ]
A --> D[趋势确认 RR2]
B --> E{评分规则引擎}
C --> E
D --> E
E --> F{综合判断}
F -->|SS>=70, TQ>=65, RR2>=2.0| G[QUALIFIED
强信号]
F -->|SS>=70, TQ>=50| H[CONDITIONAL
条件信号]
F -->|SS>=55| I[WATCHLIST
观察名单]
F -->|SS<55| J[AVOID
回避]
```
**评分维度：**
| 维度 | 缩写 | 阈值 | 说明 |
|-----|------|-----|------|
| 技术强度 | SS | 0-100 | 技术指标综合得分 |
| 交易质量 | TQ | 0-100 | 价格结构与成交量质量 |
| 趋势确认 | RR2 | >2.0 | 风险回报比确认 |
**推荐等级：**
| 推荐等级 | 触发条件 | 含义 |
|---------|---------|------|
| QUALIFIED | SS≥70, TQ≥65, RR2≥2.0 | 强信号，操作性强的标的 |
| CONDITIONAL | SS≥70, TQ≥50 | 好标的但需改进设置 |
| WATCHLIST | SS≥55 | 需监控等待更好入场点 |
| AVOID | SS<55 | 不满足动量/质量标准 |
资料来源：[src/tradingview_mcp/core/services/egx_service.py:1-100]()
## 多交易所支持
技术分析服务支持多个交易所的行情数据获取：
```mermaid
graph TD
A[分析请求] --> B{交易所识别}
B -->|加密货币| C[BINANCE/KUCOIN/BYBIT]
B -->|美国股票| D[NYSE/NASDAQ/AMEX]
B -->|埃及股票| E[EGX]
B -->|台湾股票| F[TWSE/TPEX]
B -->|土耳其股票| G[BIST]
C --> H[统一数据格式]
D --> H
E --> H
F --> H
G --> H
```
**支持的交易所映射：**
| 市场类型 | 交易所代码 | 说明 |
|---------|-----------|------|
| 加密货币 | BINANCE, KUCOIN, BYBIT, MEXC | 数字资产交易 |
| 美国股票 | NYSE, NASDAQ, AMEX, NYSEARCA | 美股市场 |
| 台湾股票 | TWSE, TPEX | 台湾证券交易所 |
| 埃及股票 | EGX | 埃及证券交易所 |
| 土耳其股票 | BIST | 伊斯坦布尔证券交易所 |
## 数据流向
```mermaid
sequenceDiagram
participant U as 用户请求
participant S as Server层
participant SC as Screener服务
participant TV as TradingView API
participant IC as 指标计算
participant R as 结果返回
U->>S: 调用分析工具
S->>SC: 请求市场数据
SC->>TV: 获取原始数据
TV-->>SC: 原始OHLCV数据
SC->>IC: 计算技术指标
IC-->>SC: 指标结果
SC-->>S: 格式化结果
S-->>U: 返回分析报告
```
## 与 MCP Server 的集成
技术分析服务通过 `server.py` 暴露为 MCP 工具：
| MCP 工具 | 功能 | 底层服务 |
|---------|------|---------|
| `get_technical_analysis` | 完整技术分析 | indicators.py |
| `get_bollinger_band_analysis` | 布林带专有分析 | indicators_calc.py |
| `screen_stocks` | 多条件筛选 | screener_service.py |
| `scan_by_signal` | 信号扫描 | scanner_service.py |
| `egx_fibonacci_retracement` | 斐波那契分析 | egx_service.py |
| `get_candlestick_patterns` | 烛台形态检测 | screener_service.py |
## 货币与部门数据
EGX 服务提供股票货币和部门分类：
**货币类型判断：**
| 货币 | 适用股票 | 示例 |
|-----|---------|------|
| EGP | 大多数EGX股票 | COMI, ORWE, ETEL |
| USD | 特定国际股票 | FAITA, VLMR, EGSA |
资料来源：[src/tradingview_mcp/core/data/egx_sectors.py:1-50]()
**部门分类：** 涵盖银行业、保险业、电信业、制造业等 20+ 行业部门。
## 错误处理
| 错误类型 | 返回格式 | 处理方式 |
|---------|---------|---------|
| API连接失败 | `{"error": "description"}` | 记录日志，返回错误信息 |
| 无效标的 | `{"error": "Invalid symbol"}` | 验证输入后返回 |
| 数据缺失 | 字段为0或空 | 使用默认值处理 |
## 扩展指南
### 添加新指标
1. 在 `indicators_calc.py` 中实现计算函数
2. 注册到指标映射表
3. 在 `server.py` 中暴露为 MCP 工具
### 添加新交易所
1. 更新 `EXCHANGE_SCREENER` 映射表
2. 添加交易所符号列表到 `coinlist/` 目录
3. 测试数据获取和格式化
## 参考链接
- 项目主页：[tradingview-mcp](https://github.com/atilaahmettaner/tradingview-mcp)
- 技术分析文档：[README.md](README.md)
- 贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md)
---
## 情感分析与新闻服务
### 相关页面
相关主题：[技术分析服务](#page-technical-analysis), [数据源与货币列表](#page-data-sources)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tradingview_mcp/core/services/sentiment_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/sentiment_service.py)
- [src/tradingview_mcp/core/services/news_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/news_service.py)
- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)
- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)
- [src/tradingview_mcp/core/services/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)
# 情感分析与新闻服务
## 概述
情感分析与新闻服务是 tradingview-mcp 框架的核心模块之一，旨在为交易决策提供多维度的市场情绪和资讯数据支持。该服务通过整合 Reddit 社区情感分析和实时金融新闻（RSS），帮助用户从社交媒体情绪和新闻事件两个维度评估资产走势。
**核心功能定位：**
| 功能模块 | 用途 | 数据来源 |
|---------|------|---------|
| 情感分析服务 | 评估市场参与者的社区情绪 | Reddit 社区帖子 |
| 新闻服务 | 聚合实时财经新闻 | RSS 订阅源 |
资料来源：[server.py:1-50]()
## 架构设计
### 服务组件结构
```
┌─────────────────────────────────────────────────────────────┐
│ MCP Server (server.py) │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Sentiment │ │ News │ │
│ │ Service │ │ Service │ │
│ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Reddit API │ │ RSS Feeds │ │
│ │ (情感抓取) │ │ (新闻聚合) │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 情感分析流程
```mermaid
graph TD
A[请求分析: symbol + category] --> B[Reddit 搜索]
B --> C{找到相关帖子?}
C -->|是| D[解析帖子内容]
C -->|否| E[返回空结果]
D --> F[计算情感得分]
F --> G[生成情感标签]
G --> H[输出完整情感报告]
```
资料来源：[server.py:token-analysis-call]()
## 情感分析服务
### 功能说明
`analyze_sentiment` 函数是情感分析的核心入口，负责从 Reddit 社区抓取与指定标的相关的讨论帖子，并计算情感得分。
**函数签名：**
```python
analyze_sentiment(symbol: str, category: str = "crypto") -> dict
```
**参数说明：**
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| symbol | str | 必填 | 交易标的符号（如 BTC-USD、AAPL） |
| category | str | "crypto" | 标的类别，可选 "crypto" 或 "stocks" |
资料来源：[server.py:analyze_sentiment-def]()
### 情感分析输出结构
```python
{
"sentiment_score": float, # 情感得分（-1 到 1）
"sentiment_label": str, # 情感标签（Bullish/Bearish/Neutral）
"posts_analyzed": int, # 分析的帖子数量
"mentions": int, # 提及次数
"key_themes": List[str], # 关键主题
"confidence": str # 置信度（High/Medium/Low）
}
```
### 情感标签映射
| 情感得分范围 | 标签 | 含义 |
|-------------|------|------|
| > 0.1 | Bullish | 看涨情绪 |
| -0.1 ~ 0.1 | Neutral | 中性情绪 |
| < -0.1 | Bearish | 看跌情绪 |
资料来源：[server.py:sentiment_label-conditional]()
## 新闻服务
### 功能说明
`fetch_news_summary` 函数从多个 RSS 订阅源聚合与指定标的相关的最新财经新闻。
**函数签名：**
```python
fetch_news_summary(symbol: str, category: str = "crypto", limit: int = 5) -> dict
```
**参数说明：**
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| symbol | str | 必填 | 交易标的符号 |
| category | str | "crypto" | 标的类别 |
| limit | int | 5 | 返回的新闻条目数量上限 |
资料来源：[server.py:fetch_news_summary-def]()
### 新闻输出结构
```python
{
"count": int, # 获取的新闻总数
"items": [ # 新闻条目列表
{
"title": str, # 新闻标题
"link": str, # 新闻链接
"pub_date": str, # 发布日期
"source": str # 新闻来源
}
]
}
```
## 情绪共振分析
### 合流决策引擎
`sentiment_news_confluence` 函数将技术分析、情感分析和新闻数据三者结合，生成综合交易建议。
**函数签名：**
```python
sentiment_news_confluence(symbol: str, exchange: str, timeframe: str = "1h") -> dict
```
**分析流程：**
```mermaid
graph TD
A[输入: symbol + exchange + timeframe] --> B[技术分析]
A --> C[情感分析]
A --> D[新闻汇总]
B --> E{技术信号}
C --> F{情感得分 > 0.1?}
E -->|Bullish/Bearish| G[信号对齐检查]
F -->|True| G
G --> H{信号一致?}
H -->|是| I[confidence: HIGH]
H -->|否| J[confidence: MIXED]
I --> K[recommendation: 技术信号 confirmed by 情感]
J --> L[recommendation: 技术信号 conflicts with 情感]
```
资料来源：[server.py:confluence-analysis]()
### 合流输出字段
| 字段 | 类型 | 说明 |
|------|------|------|
| symbol | str | 交易标的 |
| exchange | str | 交易所 |
| timeframe | str | 分析时间周期 |
| technical | dict | 技术分析完整结果 |
| sentiment | dict | 情感分析结果 |
| news | dict | 新闻摘要（数量 + 最新3条） |
| confluence | dict | 合流分析结果 |
**合流置信度判定：**
| 条件 | 置信度 | 建议格式 |
|------|--------|---------|
| 技术信号 == 情感信号 | HIGH | "Technical {signal} confirmed by {sentiment}" |
| 技术信号 != 情感信号 | MIXED | "Technical {signal} conflicts with {sentiment}" |
资料来源：[server.py:confidence-calculation]()
## EGX 交易所特殊处理
### 埃及股市情绪分析
EGX（埃及证券交易所）服务提供专门的市场情绪和板块轮动分析功能。
**指数分析函数：**
```python
analyze_egx_index(index: str = "EGX30", timeframe: str = "1D", limit: int = 30) -> dict
```
**支持的指数：**
| 指数代码 | 名称 | 说明 |
|---------|------|------|
| EGX30 | EGX 30 指数 | 埃及主板30强 |
| EGX70 | EGX 70 指数 | 中盘股指数 |
| EGX100 | EGX 100 指数 | 综合指数 |
| SHARIAH33 | 伊斯兰指数 | 符合伊斯兰法规的股票 |
| EGX35LV | 低波动指数 | 低波动精选股 |
| TAMAYUZ | Tamayuz 指数 | 主题指数 |
资料来源：[egx_service.py:analyze_egx_index-def]()
### 市场情绪生成
`_generate_rotation_signals` 函数分析板块轮动信号，判断资金流向。
**情绪类型映射：**
```python
rotation_signals = {
"strong_sectors": List[str], # 强势板块
"weak_sectors": List[str], # 弱势板块
"rotation_direction": str, # 轮动方向
"momentum_score": float # 动量得分
}
```
资料来源：[egx_service.py:_generate_rotation_signals]()
### 板块热度图
`generate_sector_heatmap` 函数计算各板块的相对强弱，生成权重分析。
**输出结构：**
```python
{
"exchange": "EGX",
"timeframe": str,
"total_sectors": int,
"total_stocks_scanned": int,
"weighted_market_view": {
"weighted_change_pct": float,
"weighted_rsi": float,
"weighted_momentum": float,
"market_sentiment": str
},
"sector_heatmap": dict,
"sector_top_picks": dict,
"rotation_signals": dict
}
```
资料来源：[egx_service.py:generate_sector_heatmap-return]()
## 使用示例
### 基础情感分析
```python
# 加密货币情感分析
result = analyze_sentiment(symbol="BTC-USD", category="crypto")
# 美股情感分析
result = analyze_sentiment(symbol="AAPL", category="stocks")
```
### 综合新闻获取
```python
# 获取币安相关最新新闻
news = fetch_news_summary(symbol="BNB", category="crypto", limit=10)
```
### 合流决策分析
```python
# 完整分析示例
confluence = sentiment_news_confluence(
symbol="BTC-USD",
exchange="BINANCE",
timeframe="1h"
)
# 输出示例
# {
# "confidence": "HIGH",
# "signals_agree": True,
# "recommendation": "Technical STRONG BUY confirmed by Bullish Reddit sentiment (142 posts analyzed)"
# }
```
资料来源：[server.py:confluence-example]()
## 技术指标与情感关联
### 多指标协同分析
系统支持将情感数据与其他技术指标结合使用：
| 指标类型 | 工具函数 | 用途 |
|---------|---------|------|
| 价格数据 | `yahoo_price` | 实时价格 |
| 技术分析 | `get_technical_analysis` | 30+ 技术指标 |
| 情感分析 | `analyze_sentiment` | Reddit 情绪 |
| 新闻汇总 | `fetch_news_summary` | RSS 新闻 |
| K线形态 | `get_candlestick_patterns` | 15 种形态识别 |
资料来源：[README.md:tools-table]()
### 信号对齐矩阵
```
技术分析信号
BUY SELL HOLD
情感 ┌─────────────┬─────────────┬─────────────┐
Bullish │ HIGH ✅ │ MIXED ⚠️ │ MIXED ⚠️ │
├─────────────┼─────────────┼─────────────┤
情感 │ MIXED ⚠️ │ HIGH ✅ │ MIXED ⚠️ │
Bearish │ │ │ │
├─────────────┼─────────────┼─────────────┤
情感 │ MIXED ⚠️ │ MIXED ⚠️ │ MEDIUM 🔄 │
Neutral │ │ │ │
└─────────────┴─────────────┴─────────────┘
```
## 配置与扩展
### 情感分析数据源配置
Reddit 数据源目前使用公开 API 接口，支持的主题分类：
| category | 适用标的 | 搜索范围 |
|----------|---------|---------|
| crypto | 加密货币 | r/CryptoCurrency, r/Bitcoin 等 |
| stocks | 股票 | r/stocks, r/wallstreetbets 等 |
### 新闻服务 RSS 配置
新闻服务支持多源 RSS 订阅，可扩展的订阅源：
| 来源类型 | 内容范围 | 更新频率 |
|---------|---------|---------|
| 财经媒体 | 主流财经新闻 | 实时 |
| 交易所公告 | 官方公告和更新 | 事件驱动 |
| 社区讨论 | 社交媒体摘要 | 定期聚合 |
## 注意事项
1. **免责声明**：所有情感和新闻分析仅供教育和参考用途，不构成投资建议
2. **数据延迟**：RSS 新闻源可能存在几分钟到几小时的延迟
3. **情感局限性**：Reddit 情感分析可能受到炒作和操控影响
4. **API 限制**：外部 API 调用频率受限于服务提供商的策略
资料来源：[egx_service.py:disclaimer]()
## 相关资源
- [项目主页](../README.md)
- [安装指南](../INSTALLATION.md)
- [OpenClaw 集成指南](../OPENCLAW.md)
- [示例对话](../EXAMPLES.md)
---
## Yahoo Finance 集成
### 相关页面
相关主题：[数据源与货币列表](#page-data-sources), [技术分析服务](#page-technical-analysis)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tradingview_mcp/core/services/yahoo_finance_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/yahoo_finance_service.py)
- [src/tradingview_mcp/core/services/extended_hours_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/extended_hours_service.py)
- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)
- [CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)
- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)
# Yahoo Finance 集成
## 概述
Yahoo Finance 集成是 tradingview-mcp 项目在 **v0.6.0** 版本中新增的核心功能模块，为用户提供实时金融市场数据查询能力。该模块通过封装 Yahoo Finance API，实现了股票、加密货币、ETF、指数、外汇等多资产类别的实时行情获取。
**主要功能包括：**
- `yahoo_price`：获取任意标的的实时报价
- `market_snapshot`：生成全球市场概览快照
资料来源：[CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)
---
## 架构设计
### 服务层结构
```
┌─────────────────────────────────────────────────────────┐
│ server.py │
│ (MCP 工具入口层) │
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
│ │ yahoo_price │ │ market_snapshot │ │
│ └────────┬────────┘ └──────────────┬──────────────┘ │
└───────────┼──────────────────────────┼──────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────┐
│ yahoo_finance_service.py │
│ (核心服务层) │
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
│ │ 实时行情获取 │ │ 市场快照生成 │ │
│ │ │ │ 14 instruments │ │
│ │ price_data() │ │ 4 asset classes │ │
│ └─────────────────┘ └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ extended_hours_service.py │
│ (盘后服务层) │
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
│ │ 盘前盘后检测 │ │ 市场状态判定 │ │
│ │ extended_hours │ │ market_state │ │
│ └─────────────────┘ └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Yahoo Finance API │
│ (外部数据源) │
└─────────────────────────────────────────────────────────┘
```
### 支持的资产类别
| 资产类别 | 示例标的 | 数据内容 |
|---------|---------|---------|
| **股票** | AAPL, TSLA, NVDA | 价格、涨跌幅、52周高低 |
| **加密货币** | BTC-USD, ETH-USD | 实时报价、24h变化 |
| **ETF** | SPY, QQQ | 实时行情 |
| **指数** | S&P500, NASDAQ, VIX | 市场指数点位 |
| **外汇** | EUR/USD | 汇率报价 |
| **土耳其股票** | THYAO.IS, SASA.IS | 本地市场报价 |
资料来源：[CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)
---
## 核心服务模块
### yahoo_finance_service.py
`yahoo_finance_service.py` 是 Yahoo Finance 集成的核心服务模块，负责与 Yahoo Finance API 交互并返回结构化的市场数据。
#### 主要功能
| 功能 | 说明 |
|-----|-----|
| `get_yahoo_price()` | 获取单个标的的实时行情 |
| `get_market_snapshot()` | 生成全球市场概览（14个标的） |
| `get_prices_bulk()` | 批量获取多标的报价 |
#### yahoo_price 工具
`yahoo_price` 是 MCP 工具的核心入口，调用 `yahoo_finance_service.py` 中的函数获取实时数据。
**返回值结构：**
```json
{
"symbol": "AAPL",
"price": 175.30,
"change": 3.62,
"change_percent": 2.11,
"52_week_high": 198.23,
"52_week_low": 124.17,
"market_state": "REGULAR"
}
```
#### market_snapshot 工具
`market_snapshot` 提供全球市场概览，覆盖 **14 个标的** 和 **4 个资产类别**。
**快照覆盖范围：**
| 资产类别 | 标的数量 | 代表标的 |
|---------|---------|---------|
| 股票指数 | 3 | S&P 500, NASDAQ, VIX |
| 加密货币 | 2 | BTC, ETH |
| 外汇 | 2 | EUR/USD, GBP/USD |
| 商品期货 | 1 | 黄金/石油 |
资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)
---
### extended_hours_service.py
`extended_hours_service.py` 负责处理美股盘前盘后交易时段的检测与市场状态判定。
#### 市场状态定义
| 状态 | 说明 | 时间范围（美东时间） |
|-----|------|---------------------|
| `PRE_MARKET` | 盘前交易 | 04:00 - 09:30 |
| `REGULAR` | 常规交易时段 | 09:30 - 16:00 |
| `AFTER_HOURS` | 盘后交易 | 16:00 - 20:00 |
| `CLOSED` | 市场关闭 | 周末/节假日 |
#### 服务流程
```mermaid
graph TD
A[请求行情数据] --> B{检查标的类型}
B -->|美股| C[调用 extended_hours_service]
B -->|非美股| D[直接返回报价]
C --> E[获取当前时间]
E --> F{判定市场状态}
F -->|盘前| G[返回 PRE_MARKET]
F -->|盘中| H[返回 REGULAR]
F -->|盘后| I[返回 AFTER_HOURS]
F -->|非交易时段| J[返回 CLOSED]
G --> K[附加盘前/盘后数据]
H --> L[返回实时价格]
I --> M[附加盘后数据]
J --> N[返回最后收盘价]
K --> O[合并到最终响应]
L --> O
M --> O
N --> O
```
---
## MCP 工具接口
### 工具清单
| 工具名 | 功能 | 适用资产 |
|-------|------|---------|
| `yahoo_price` | 单标的实时报价 | 股票、加密货币、ETF、外汇 |
| `market_snapshot` | 全球市场概览 | 14个核心标的 |
| `get_prices_bulk` | 批量价格查询 | 多标的 |
资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)
### yahoo_price 参数说明
| 参数 | 类型 | 必需 | 说明 | 示例 |
|-----|------|-----|------|-----|
| `symbol` | string | 是 | 标的代码 | `AAPL`、`BTC-USD` |
| `include_extended` | boolean | 否 | 是否包含盘后数据 | `true` |
### market_snapshot 参数说明
| 参数 | 类型 | 必需 | 说明 |
|-----|------|-----|------|
| 无 | - | - | 无参数，返回全球市场概览 |
---
## 数据流处理
### 实时报价获取流程
```mermaid
sequenceDiagram
participant User as 用户
participant MCP as MCP Server
participant YFS as Yahoo Finance Service
participant EHS as Extended Hours Service
participant YF as Yahoo Finance API
User->>MCP: yahoo_price("AAPL")
MCP->>YFS: get_yahoo_price("AAPL")
YFS->>YF: 请求 AAPL 报价
YF-->>YFS: 返回 OHLCV 数据
YFS->>EHS: 检测市场状态
EHS-->>YFS: 返回 market_state
YFS-->>MCP: 构造响应数据
MCP-->>User: 返回完整报价
User->>MCP: market_snapshot()
MCP->>YFS: get_market_snapshot()
loop 14个标的
YFS->>YF: 批量请求
YF-->>YFS: 返回数据
end
YFS-->>MCP: 返回市场概览
MCP-->>User: 返回全球市场快照
```
### 数据处理逻辑
```python
# 伪代码示例
def get_yahoo_price(symbol: str) -> dict:
# 1. 调用 Yahoo Finance API
raw_data = yahoo_finance_api.get_quote(symbol)
# 2. 检测盘前盘后状态
market_state = detect_market_state(symbol)
# 3. 计算涨跌幅
change = raw_data['current_price'] - raw_data['previous_close']
change_percent = (change / raw_data['previous_close']) * 100
# 4. 构造返回值
return {
"symbol": symbol,
"price": raw_data['current_price'],
"change": change,
"change_percent": change_percent,
"52_week_high": raw_data['fifty_two_week_high'],
"52_week_low": raw_data['fifty_two_week_low'],
"market_state": market_state
}
```
---
## 与其他模块的集成
### 集成关系图
```mermaid
graph LR
A[Yahoo Finance 集成] --> B[server.py]
A --> C[Technical Analysis]
A --> D[Backtesting Engine]
A --> E[Market Screener]
B -->|MCP 工具| F[Claude Desktop]
B -->|MCP 工具| G[OpenClaw]
C -->|price_data| H[RSI 计算]
C -->|price_data| I[MACD 计算]
C -->|price_data| J[Bollinger Bands]
D -->|历史数据| K[策略回测]
D -->|历史数据| L[Compare Strategies]
E -->|symbol| M[Top Gainers]
E -->|symbol| N[Top Losers]
```
---
## 版本历史
| 版本 | 日期 | 更新内容 |
|-----|------|---------|
| 0.6.0 | 2026-03-29 | **初始集成**：yahoo_price、market_snapshot、get_prices_bulk |
资料来源：[CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)
---
## 使用示例
### 获取单只股票报价
```python
# MCP 工具调用示例
yahoo_price(symbol="AAPL")
# 返回
{
"symbol": "AAPL",
"price": 175.30,
"change": 3.62,
"change_percent": 2.11,
"52_week_high": 198.23,
"52_week_low": 124.17,
"market_state": "REGULAR"
}
```
### 获取全球市场概览
```python
# MCP 工具调用示例
market_snapshot()
# 返回概览包含：
# - S&P 500、NASDAQ、VIX 指数
# - BTC、ETH 加密货币
# - EUR/USD、GBP/USD 外汇
# - 黄金/石油商品
```
### 获取土耳其股票
```python
# 土耳其股票使用 .IS 后缀
yahoo_price(symbol="THYAO.IS")
yahoo_price(symbol="SASA.IS")
```
---
## 错误处理与限制
### 常见问题
| 问题 | 原因 | 解决方案 |
|-----|------|---------|
| 返回空数据 | 标的代码错误 | 检查 Yahoo Finance 格式 |
| 盘后数据缺失 | 非美股标的 | 确认标的为美股 |
| 限流 | 请求过于频繁 | 添加延迟或使用缓存 |
### 速率限制
- Yahoo Finance API 有隐式速率限制
- 建议批量查询使用 `get_prices_bulk` 而非循环调用 `yahoo_price`
---
## 相关文件
| 文件路径 | 功能 |
|---------|------|
| `src/tradingview_mcp/core/services/yahoo_finance_service.py` | Yahoo Finance API 封装 |
| `src/tradingview_mcp/core/services/extended_hours_service.py` | 盘前盘后检测服务 |
| `src/tradingview_mcp/server.py` | MCP 工具定义与路由 |
| `CHANGELOG.md` | 版本更新记录 |
| `README.md` | 项目文档 |
---
## 数据源与货币列表
### 相关页面
相关主题：[多交易所支持](#page-exchange-support), [Yahoo Finance 集成](#page-yahoo-finance)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tradingview_mcp/core/services/coinlist.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/coinlist.py)
- [src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)
- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)
- [src/tradingview_mcp/coinlist/binance.txt](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/coinlist/binance.txt)
- [src/tradingview_mcp/coinlist/all.txt](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/coinlist/all.txt)
# 数据源与货币列表
## 概述
`tradingview-mcp` 是一个基于 Model Context Protocol (MCP) 的 TradingView 技术分析服务器。该项目的数据源与货币列表系统负责管理交易所交易对信息、货币符号映射以及市场类型识别，为整个系统提供标准化的数据输入源。
项目采用文本文件存储货币列表，并通过专门的 Python 服务模块进行读取和管理，支持多种加密货币交易所和股票市场。
---
## 架构设计
### 核心组件关系
```mermaid
graph TD
A[用户请求] --> B[server.py 入口]
B --> C{市场类型判断}
C -->|加密货币| D[coinlist_service.py]
C -->|股票/ETF| E[validators.py 交易所映射]
D --> F[coinlist/ 目录]
E --> G[TradingView Screener API]
F --> H[binance.txt]
F --> I[kucoin.txt]
F --> J[all.txt]
D --> K[proxy_manager.py 代理管理]
G --> L[返回分析结果]
H --> D
I --> D
J --> D
```
### 货币列表目录结构
```
src/tradingview_mcp/
├── coinlist/
│ ├── all.txt # 全交易所合并货币列表
│ ├── binance.txt # Binance 交易对
│ ├── kucoin.txt # KuCoin 交易对
│ ├── mexc.txt # MEXC 交易对
│ ├── bybit.txt # Bybit 交易对
│ └── 其他交易所文件...
└── core/
└── services/
├── coinlist.py # 货币列表服务
└── screener_service.py # 筛选器服务
```
---
## 货币列表服务 (coinlist_service.py)
### 核心功能
`coinlist_service.py` 是货币列表的核心管理模块，负责加载、缓存和查询各交易所的货币符号列表。
资料来源：[src/tradingview_mcp/core/services/coinlist.py]()
### 主要函数
| 函数 | 功能描述 |
|------|----------|
| `load_coinlist(exchange)` | 加载指定交易所的货币列表 |
| `get_coinlist(exchange)` | 获取货币列表（带缓存） |
| `get_all_symbols()` | 获取所有交易所的合并列表 |
| `filter_by_exchange()` | 按交易所筛选货币 |
### 目录路径解析
```python
# validators.py 中的路径计算逻辑
_this_file = __file__ # core/utils/validators.py
_utils_dir = os.path.dirname(_this_file) # core/utils
_core_dir = os.path.dirname(_utils_dir) # core
_package_dir = os.path.dirname(_core_dir) # tradingview_mcp
COINLIST_DIR = os.path.join(_package_dir, 'coinlist') # tradingview_mcp/coinlist
```
资料来源：[src/tradingview_mcp/core/utils/validators.py:20-25]()
---
## 交易所映射系统
### 交易所筛选器配置
```python
EXCHANGE_SCREENER = {
"binance": "BINANCE",
"kucoin": "KUCOIN",
"bybit": "BYBIT",
"mexc": "MEXC",
"NYSE": "NYSE",
"NASDAQ": "NASDAQ",
"AMEX": "AMEX",
"NYSEARCA": "AMEX",
"PCX": "AMEX",
"TWSE": "TWSE",
"TPEX": "TPEX",
}
```
资料来源：[src/tradingview_mcp/core/utils/validators.py]()
### 股票交易所标识
```python
STOCK_EXCHANGES = {
"nyse", "nasdaq", "amex", "tsx", "lse",
"jpx", "hkex", "sse", "szse", "twse",
"tpex", "krx", "asx", "bse", "nse",
"egx", "etr", "vse", "wse", "lsis"
}
```
资料来源：[src/tradingview_mcp/core/utils/validators.py]()
### 交易所前缀映射
对于某些特殊交易所，系统需要将不同别名映射到统一前缀：
```python
_EXCHANGE_TV_PREFIX = {
"nysearca": "AMEX",
"pcx": "AMEX",
}
```
资料来源：[src/tradingview_mcp/core/utils/validators.py]()
---
## 数据源类型
### 加密货币数据源
| 交易所 | 数据格式 | 支持的交易对类型 |
|--------|----------|------------------|
| Binance | `SYMBOLUSDT` | USDT 永续合约为主 |
| KuCoin | `SYMBOLUSDT` | USDT 永续合约 |
| Bybit | `SYMBOLUSDT` | USDT 永续合约 |
| MEXC | `SYMBOLUSDT` | USDT 永续合约 |
### 股票/ETF 数据源
| 市场 | 交易所代码 | 示例符号 |
|------|------------|----------|
| 美国主板 | `NYSE` | AAPL, TSLA, NVDA |
| 纳斯达克 | `NASDAQ` | MSFT, GOOGL, AMZN |
| 美国ETF | `AMEX` | SPY, QQQ, GLD, GDX |
| 台湾上市 | `TWSE` | 2330, 0050, 0056 |
| 台湾上柜 | `TPEX` | 指数成分股 |
| 埃及 | `EGX` | 当地上市公司 |
---
## 符号构建与验证流程
### 加密货币符号构建
```mermaid
graph LR
A[用户输入: BTC] --> B[sanitize_symbol]
B --> C{交易所类型}
C -->|加密货币| D[直接使用: BTCUSDT]
C -->|股票/ETF| E[添加前缀: AMEX:GLD]
D --> F[返回完整符号]
E --> F
```
### 函数调用链
```python
# 1. 符号清理
sanitize_symbol(symbol, exchange)
# 2. 交易所验证
sanitize_exchange(exchange, default="kucoin")
# 3. 市场类型判断
is_stock_exchange(exchange) # 返回 True/False
# 4. 前缀映射
get_tv_exchange_prefix(exchange) # NYSEARCA -> AMEX
```
资料来源：[src/tradingview_mcp/core/utils/validators.py]()
---
## 代理管理系统 (proxy_manager.py)
对于需要代理访问的数据源，项目提供了代理管理功能。
### 代理配置存储
- 代理配置通常存储在环境变量或配置文件中
- 支持 HTTP/HTTPS/SOCKS5 代理协议
- 代理轮换机制用于避免请求频率限制
资料来源：[src/tradingview_mcp/core/services/proxy_manager.py]()
---
## 筛选器服务 (screener_service.py)
### analyze_coin 函数
`screener_service.py` 中的 `analyze_coin` 函数是核心分析入口：
```python
async def analyze_coin(
symbol: str,
exchange: str = "KUCOIN",
timeframe: str = "1h"
) -> dict:
"""分析单个交易品种的技术指标"""
# 使用 get_tv_exchange_prefix 获取正确前缀
# 构建 TradingView 格式符号: EXCHANGE:SYMBOL
# 调用技术指标计算
# 返回分析结果
```
资料来源：[src/tradingview_mcp/core/services/screener_service.py]()
---
## 时间周期别名映射
项目支持灵活的时间周期输入：
```python
_TIMEFRAME_ALIASES = {
"1m": "1m", "3m": "3m", "5m": "5m",
"15m": "15m", "30m": "30m",
"1h": "1h", "2h": "2h", "4h": "4h",
"6h": "6h", "8h": "8h", "12h": "12h",
"1d": "1D", "1w": "1W",
# 中文别名
"日线": "1D", "周线": "1W",
"1小时": "1h", "4小时": "4h"
}
```
资料来源：[src/tradingview_mcp/core/utils/validators.py]()
---
## 配置文件
### pyproject.toml 依赖
```toml
[project]
dependencies = [
"tradingview-screener>=0.3.0",
"yfinance>=0.2.0",
"httpx>=0.27.0",
]
```
### 开发依赖
```toml
[tool.uv]
dev-dependencies = [
"pytest>=8.0.0",
"ruff>=0.4.0",
"mypy>=1.8.0",
]
```
---
## 测试覆盖
项目为数据源和交易所功能提供了完整的单元测试：
### 测试文件
| 文件 | 测试数量 | 覆盖范围 |
|------|----------|----------|
| `tests/unit/test_exchange_fixes.py` | 32 | 交易所别名、前缀映射、符号构建 |
| `tests/unit/test_exchange_aliases.py` | 37 | TWSE/TPEX 符号构造、预合格符号保护 |
### 测试运行
```bash
# 运行所有测试
uv run pytest
# 运行特定测试文件
uv run pytest tests/unit/test_exchange_fixes.py
# 测试结果
73 passed in 0.17s (69 new + 4 pre-existing)
```
资料来源：[PR_BODY.md]()
---
## 常见使用场景
### 场景1：获取加密货币列表
```python
from tradingview_mcp.core.services.coinlist import get_coinlist
# 获取 Binance 交易对
binance_coins = get_coinlist("binance")
print(f"Binance 支持 {len(binance_coins)} 个交易对")
```
### 场景2：验证股票符号
```python
from tradingview_mcp.core.utils.validators import (
sanitize_exchange,
is_stock_exchange,
get_tv_exchange_prefix
)
# 验证交易所
exchange = sanitize_exchange("NYSEARCA") # 返回 "amex"
is_stock = is_stock_exchange("NYSE") # 返回 True
# 获取 TradingView 前缀
prefix = get_tv_exchange_prefix("NYSEARCA") # 返回 "AMEX"
```
### 场景3：构建完整交易符号
```python
# 股票ETF: AMEX:GLD
# 加密货币: BTCUSDT (无前缀)
def build_tradingview_symbol(symbol: str, exchange: str) -> str:
"""根据交易所类型构建 TradingView 格式符号"""
if is_stock_exchange(exchange):
prefix = get_tv_exchange_prefix(exchange)
return f"{prefix}:{symbol}"
return f"{symbol}USDT" # 加密货币默认USDT交易对
```
---
## 总结
数据源与货币列表系统是 `tradingview-mcp` 的基础设施组件，通过以下方式实现统一的数据访问：
1. **文件式货币列表** - 使用纯文本文件存储，便于维护和扩展
2. **交易所抽象层** - 统一的交易所标识和映射机制
3. **智能符号构建** - 自动根据市场类型添加正确前缀
4. **完整测试覆盖** - 确保交易所映射的准确性和稳定性
---
## 多交易所支持
### 相关页面
相关主题：[数据源与货币列表](#page-data-sources), [技术分析服务](#page-technical-analysis)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)
- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)
- [src/tradingview_mcp/core/services/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)
- [src/tradingview_mcp/core/services/screener_provider.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_provider.py)
- [src/tradingview_mcp/core/data/egx_indices.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/data/egx_indices.py)
- [src/tradingview_mcp/core/data/egx_sectors.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/data/egx_sectors.py)
- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)
- [tests/unit/test_exchange_fixes.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/tests/unit/test_exchange_fixes.py)
- [tests/unit/test_exchange_aliases.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/tests/unit/test_exchange_aliases.py)
# 多交易所支持
## 概述
`tradingview-mcp` 项目提供了一套完整的多交易所支持架构，允许用户通过统一的接口访问全球多个金融市场的实时数据和技术分析。该系统支持加密货币交易所、传统股票交易所以及区域性市场，通过模块化的服务层实现交易所无关的数据获取和处理逻辑。
多交易所支持的核心价值在于：
- **统一 API 接口**：无论底层交易所类型如何，用户通过相同的函数调用获取数据
- **交易所特定适配**：每种交易所类型都有专属的筛选器配置和数据格式处理
- **符号标准化**：实现了 `sanitize_exchange` 和 `get_tv_exchange_prefix` 等函数确保符号在 TradingView 格式下正确路由
- **市场类型识别**：通过 `is_stock_exchange` 和 `get_market_type` 等函数区分股票市场和加密货币市场
资料来源：[src/tradingview_mcp/core/utils/validators.py:1-100]()
---
## 架构设计
### 组件关系图
```mermaid
graph TD
subgraph "表现层"
SERVER[server.py - MCP接口]
end
subgraph "服务层"
SCREENER[screener_service.py
通用筛选器服务]
EGX[egx_service.py
埃及交易所专用服务]
SCREENER_PROVIDER[screener_provider.py
筛选器提供者]
end
subgraph "数据层"
VALIDATORS[validators.py
交易所验证与规范化]
EGX_INDICES[egx_indices.py
EGX指数数据]
EGX_SECTORS[egx_sectors.py
EGX板块数据]
COINLIST[coinlist/
交易所符号列表]
end
subgraph "外部数据源"
TV[TradingView Screener API]
YAHOO[Yahoo Finance API]
end
SERVER --> SCREENER
SERVER --> EGX
SCREENER --> SCREENER_PROVIDER
SCREENER_PROVIDER --> VALIDATORS
EGX --> VALIDATORS
SCREENER_PROVIDER --> YAHOO
EGX --> TV
VALIDATORS --> COINLIST
```
### 交易所分类体系
系统将支持的交易所分为两大类别：
| 类别 | 说明 | 识别方式 |
|------|------|----------|
| **股票市场** | 传统证券交易所（NYSE、NASDAQ、TWSE 等） | `is_stock_exchange()` 返回 `True` |
| **加密货币交易所** | 加密货币交易平台（KUCOIN、BINANCE 等） | 不在 `STOCK_EXCHANGES` 中 |
资料来源：[src/tradingview_mcp/core/utils/validators.py:30-50]()
---
## 交易所配置与管理
### 核心配置常量
`validators.py` 文件定义了多个关键的交易所配置常量：
```python
EXCHANGE_SCREENER = {
"binance": "BINANCE",
"kucoin": "KUCOIN",
"bybit": "BYBIT",
"mexc": "MEXC",
"okx": "OKX",
"coinbase": "COINBASE",
"nasdaq": "NASDAQ",
"nyse": "NYSE",
"amex": "AMEX",
"nysearca": "AMEX",
"pcx": "AMEX",
"twse": "TWSE",
"tpex": "TPEX",
"egx": "EGX",
"bist": "BIST",
}
```
资料来源：[src/tradingview_mcp/core/utils/validators.py:1-50]()
### 交易所别名映射
系统通过 `EXCHANGE_SCREENER` 字典实现交易所别名到标准名称的映射：
| 别名 | 标准名称 | 说明 |
|------|----------|------|
| `nysearca` | `AMEX` | NYSE Arca 交易所 |
| `pcx` | `AMEX` | Arca 交易所（Pacific Exchange） |
| `amex` | `AMEX` | 美国证券交易所 |
资料来源：[src/tradingview_mcp/core/utils/validators.py:10-20]()
### TradingView 前缀映射
`get_tv_exchange_prefix()` 函数将交易所名称转换为 TradingView 符号格式：
```python
_EXCHANGE_TV_PREFIX = {
"amex": "AMEX",
"nysearca": "AMEX",
"pcx": "AMEX",
"nyse": "NYSE",
"nasdaq": "NASDAQ",
"twse": "TWSE",
"tpex": "TPEX",
}
```
该函数的工作流程如下：
```mermaid
graph LR
A[输入交易所名称] --> B{是否为已知别名?}
B -->|是| C[返回映射的标准前缀]
B -->|否| D[返回大写的原名称]
C --> E[如: NYSEARCA → AMEX]
D --> F[如: KUCOIN → KUCOIN]
```
资料来源：[src/tradingview_mcp/core/utils/validators.py:50-80]()
---
## 服务层实现
### 通用筛选器服务
`screener_service.py` 提供了跨交易所的统一筛选功能：
```python
async def analyze_coin(
symbol: str,
exchange: str = "KUCOIN",
timeframe: str = "1h",
screener: str = "CRYPTO"
) -> dict:
# 使用 get_tv_exchange_prefix 处理符号
tv_prefix = get_tv_exchange_prefix(exchange)
full_symbol = f"{tv_prefix}:{symbol.upper()}"
```
关键功能包括：
- **符号构造**：将交易所前缀与交易对符号组合为完整 TradingView 符号
- **时间框架规范化**：通过 `sanitize_timeframe` 统一处理时间框架参数
- **交易所验证**：通过 `sanitize_exchange` 确保只使用支持的交易所
资料来源：[src/tradingview_mcp/core/services/screener_service.py:1-100]()
### 筛选器提供者
`screener_provider.py` 负责根据不同交易所类型选择合适的数据源：
```mermaid
graph TD
A[请求筛选数据] --> B{交易所类型?}
B -->|加密货币| C[使用 CoinGecko/CoinMarketCap]
B -->|美国股票| D[使用 Yahoo Finance]
B -->|TWSE/TPEX| E[使用 TradingView]
B -->|EGX| F[使用 egx_service]
C --> G[返回标准化数据]
D --> G
E --> G
F --> G
```
---
## 区域性市场支持
### 埃及交易所 (EGX)
埃及交易所是项目重点支持的区域性市场之一，提供完整的专用服务：
#### EGX 服务组件
| 组件 | 文件 | 功能 |
|------|------|------|
| `egx_service.py` | 核心服务 | EGX 特定的市场概览、股票筛选、交易计划 |
| `egx_indices.py` | 指数数据 | EGX 主要指数成分和权重 |
| `egx_sectors.py` | 板块数据 | EGX 行业板块分类 |
资料来源：[src/tradingview_mcp/core/services/egx_service.py:1-50]()
#### EGX 指数配置
```python
EGX_INDICES = {
"EGX30": {
"name": "EGX 30 Index",
"description": "Primary index tracking top 30 companies",
"constituents": ["COMI", "MRDY", "ETEL", ...]
},
"EGX70": {
"name": "EGX 70 Index",
"description": "Broader index tracking mid-cap companies"
}
}
```
资料来源：[src/tradingview_mcp/core/data/egx_indices.py:1-100]()
#### EGX 板块分类
```python
EGX_SECTORS = {
"banking": ["CIB", "SAUD", "HDBK"],
"telecom": ["WE", "ETEL", "OCDI"],
"real_estate": ["TMGH", "EAST", "SKIP"],
"industrial": ["PRMH", "LOX", "ALCN"],
"tourism": ["EGAL", "EURN", "TOBA"],
}
```
资料来源：[src/tradingview_mcp/core/data/egx_sectors.py:1-100]()
### 台湾交易所 (TWSE/TPEX)
台湾股票市场通过 TradingView 筛选器直接支持：
| 市场 | 交易所代码 | 示例股票 |
|------|-----------|----------|
| 台湾证券交易所 | `TWSE` | 2330 (台积电)、0050 (元大台50) |
| 台湾柜台买卖中心 | `TPEX` | 0056 (元大高股息) |
这些股票已预先配置在 `EXCHANGE_SCREENER` 中，可直接使用筛选器功能。
资料来源：[src/tradingview_mcp/core/utils/validators.py:10-15]()
---
## 符号构造与规范化
### 符号构造流程
在 `server.py` 的 `multi_timeframe_analysis` 函数中展示了完整的符号构造流程：
```python
async def multi_timeframe_analysis(
symbol: str,
exchange: str = "KUCOIN",
timeframes: list[str] = None
) -> dict:
# 1. 规范化交易所名称
tv_prefix = get_tv_exchange_prefix(exchange)
# 2. 构造完整 TradingView 符号
full_symbol = f"{tv_prefix}:{symbol.upper()}"
# 3. 从多个时间框架获取数据
results = {}
for tf in timeframes:
data = await get_technical_analysis(
symbol=full_symbol,
exchange=exchange,
timeframe=tf
)
results[tf] = data
```
资料来源：[src/tradingview_mcp/server.py:1-100]()
### 符号格式对照表
| 交易所 | 符号前缀 | 示例符号 |
|--------|----------|----------|
| KuCoin | `KUCOIN` | `KUCOIN:BTCUSDT` |
| Binance | `BINANCE` | `BINANCE:BNBUSDT` |
| NYSE | `NYSE` | `NYSE:AAPL` |
| NASDAQ | `NASDAQ` | `NASDAQ:TSLA` |
| AMEX | `AMEX` | `AMEX:GDX` |
| TWSE | `TWSE` | `TWSE:2330` |
| TPEX | `TPEX` | `TPEX:0056` |
---
## 测试覆盖
### 交易所修复测试
项目通过完整的单元测试确保多交易所支持的正确性：
| 测试文件 | 测试数量 | 覆盖范围 |
|----------|----------|----------|
| `test_exchange_fixes.py` | 32 个测试 | AMEX/NYSEARCA/PCX 别名、符号构造、回归测试 |
| `test_exchange_aliases.py` | 37 个测试 | TWSE/TPEX 符号构造、预校验符号保护 |
#### 测试覆盖的关键场景
```python
# test_exchange_fixes.py 示例测试
def test_get_tv_exchange_prefix_nysearca():
"""NYSEARCA 应映射到 AMEX"""
assert get_tv_exchange_prefix("NYSEARCA") == "AMEX"
def test_sanitize_exchange_valid():
"""有效交易所应保持不变"""
assert sanitize_exchange("AMEX") == "amex"
def test_symbol_construction_gdx():
"""GDX ETF 应正确构造为 AMEX:GDX"""
tv_prefix = get_tv_exchange_prefix("NYSEARCA")
assert f"{tv_prefix}:GDX" == "AMEX:GDX"
```
资料来源：[tests/unit/test_exchange_fixes.py:1-100]()
#### 回归测试
测试套件确保现有功能不受影响：
```python
def test_regression_nyse():
assert get_tv_exchange_prefix("NYSE") == "NYSE"
def test_regression_twse():
assert get_tv_exchange_prefix("TWSE") == "TWSE"
def test_regression_kucoin():
assert get_tv_exchange_prefix("KUCOIN") == "KUCOIN"
```
**测试结果**：73 个测试通过（69 个新增 + 4 个既有测试），耗时 0.17 秒。
资料来源：[PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)
---
## 支持的交易所汇总
### 加密货币交易所
| 交易所 | 代码 | 筛选器支持 | 实时价格 |
|--------|------|------------|----------|
| KuCoin | `KUCOIN` | ✅ | ✅ |
| Binance | `BINANCE` | ✅ | ✅ |
| Bybit | `BYBIT` | ✅ | ✅ |
| MEXC | `MEXC` | ✅ | ✅ |
| OKX | `OKX` | ✅ | ✅ |
| Coinbase | `COINBASE` | ✅ | ✅ |
### 美国股票交易所
| 交易所 | 代码 | 筛选器支持 | 符号示例 |
|--------|------|------------|----------|
| 纽约证券交易所 | `NYSE` | ✅ | AAPL, JPM, XOM |
| 纳斯达克 | `NASDAQ` | ✅ | TSLA, NVDA, AMZN |
| 美国证券交易所 | `AMEX` | ✅ | GDX, GLD, XLE |
| NYSE Arca | `NYSEARCA` | ✅ | 同 AMEX |
| Arca (Pacific) | `PCX` | ✅ | 同 AMEX |
### 区域性股票交易所
| 市场 | 交易所 | 代码 | 专用服务 |
|------|--------|------|----------|
| 台湾 | 台湾证券交易所 | `TWSE` | - |
| 台湾 | 台湾柜买中心 | `TPEX` | - |
| 埃及 | 埃及证券交易所 | `EGX` | ✅ |
| 土耳其 | 伊斯坦布尔证券交易所 | `BIST` | ✅ |
---
## 扩展新的交易所
### 步骤 1：更新配置常量
在 `validators.py` 中添加新的交易所映射：
```python
# 添加到 EXCHANGE_SCREENER
EXCHANGE_SCREENER["new_exchange"] = "NEW_EXCHANGE"
# 如果有别名，添加映射
EXCHANGE_SCREENER["alias"] = "NEW_EXCHANGE"
# 如果需要特殊前缀映射
_EXCHANGE_TV_PREFIX["new_exchange"] = "NEW_EXCHANGE"
```
### 步骤 2：添加符号列表（如需要）
```bash
# 创建新的符号列表文件
touch src/tradingview_mcp/coinlist/new_exchange.txt
# 每行添加一个交易对符号
```
### 步骤 3：验证实现
```bash
# 运行测试
uv run pytest tests/unit/test_exchange_fixes.py
# 测试符号构造
uv run python -c "
from src.tradingview_mcp.core.utils.validators import get_tv_exchange_prefix, sanitize_exchange
print(get_tv_exchange_prefix('NEW_EXCHANGE'))
print(sanitize_exchange('new_exchange'))
"
```
---
## 最佳实践
### 交易所名称处理
始终使用 `sanitize_exchange()` 函数处理用户输入：
```python
# 好的做法
exchange = sanitize_exchange(user_input)
tv_prefix = get_tv_exchange_prefix(exchange)
# 避免的做法
exchange = user_input.upper() # 可能导致验证失败
```
### 符号构造
使用 `get_tv_exchange_prefix()` 确保符号格式正确：
```python
# 正确示例
symbol = f"{get_tv_exchange_prefix(exchange)}:{ticker.upper()}"
# 对于加密货币，原有名称保持不变
if is_stock_exchange(exchange):
symbol = f"{get_tv_exchange_prefix(exchange)}:{ticker.upper()}"
else:
symbol = f"{exchange.upper()}:{ticker.upper()}"
```
### 时间框架规范化
```python
tf = sanitize_timeframe(timeframe, default="1h")
```
---
## 相关文档
- [安装指南](../setup/installation.md) - 如何配置多交易所环境
- [API 参考](../api/reference.md) - 各交易所函数完整参数说明
- [故障排除](../troubleshooting.md) - 常见交易所连接问题
---
---
## Doramagic 踩坑日志
项目：atilaahmettaner/tradingview-mcp
摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。
## 1. 安全/权限坑 · 涉及密钥、隐私或敏感领域
- 严重度：high
- 证据强度：source_linked
- 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。
- 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。
- 建议检查：补敏感数据流、密钥存储和权限边界审查。
- 防护动作：敏感领域或密钥场景必须保守推荐并要求人工复核。
- 证据：packet_text.keyword_scan | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | matched secret / private key / privacy / trading / finance keyword
## 2. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | host_targets=mcp_host, claude, cursor, chatgpt
## 3. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | README/documentation is current enough for a first validation pass.
## 4. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | last_activity_observed missing
## 5. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium
## 6. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | No sandbox install has been executed yet; downstream must verify before user use.
## 7. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium
## 8. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | issue_or_pr_quality=unknown
## 9. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | release_recency=unknown