{
"canonical_name": "atilaahmettaner/tradingview-mcp",
"compilation_id": "pack_43a97e3850114a5c8dd0667d94f6771f",
"created_at": "2026-05-22T04:10:56.689729+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install tradingview-mcp-server` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install tradingview-mcp-server",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_4b9a311f99144d3c8a39e8f878b2837c"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_c68368898e716cd14fa410ac55cd2b43",
"canonical_name": "atilaahmettaner/tradingview-mcp",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/atilaahmettaner/tradingview-mcp",
"slug": "tradingview-mcp",
"source_packet_id": "phit_def7b94fad8749ba8124cef87db63abb",
"source_validation_id": "dval_d0a13c0259ce4029b8f69af93297e9d3"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": null,
"github_stars": null,
"one_liner_en": "📈 AI Trading Intelligence Framework — MCP Server",
"one_liner_zh": "📈 AI Trading Intelligence Framework — MCP Server",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host, claude, cursor 等宿主 AI 的用户",
"title_en": "tradingview-mcp",
"title_zh": "tradingview-mcp 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Multi-agent Collaboration",
"label_zh": "多 Agent 协作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-multi-agent-collaboration",
"type": "core_capability"
},
{
"label_en": "Multi-role Workflow",
"label_zh": "多角色协作流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-multi-role-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_def7b94fad8749ba8124cef87db63abb",
"page_model": {
"artifacts": {
"artifact_slug": "tradingview-mcp",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install tradingview-mcp-server",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/atilaahmettaner/tradingview-mcp#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"多 Agent 协作",
"多角色协作流程",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "📈 AI Trading Intelligence Framework — MCP Server"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude, cursor, chatgpt",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Complement idea: \"What happened next?\" via Chart Library",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_b89762244f5e4c498064918f30cd560b | https://github.com/atilaahmettaner/tradingview-mcp/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Complement idea: \"What happened next?\" via Chart Library",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。",
"category": "安全/权限坑",
"evidence": [
"packet_text.keyword_scan | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | matched secret / private key / privacy / trading / finance keyword"
],
"severity": "high",
"suggested_check": "补敏感数据流、密钥存储和权限边界审查。",
"title": "涉及密钥、隐私或敏感领域",
"user_impact": "金融、交易、隐私和密钥场景必须比普通工具更保守。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[HELP] Installation Issue:",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_dcb256f998e14be785fa2c939b9dba56 | https://github.com/atilaahmettaner/tradingview-mcp/issues/24 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[HELP] Installation Issue:",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | host_targets=mcp_host, claude, cursor, chatgpt"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 10 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Complement idea: \"What happened next?\" via Chart Library。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": null,
"forks": null,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": null
},
"source_url": "https://github.com/atilaahmettaner/tradingview-mcp",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "📈 AI Trading Intelligence Framework — MCP Server",
"title": "tradingview-mcp 能力包",
"trial_prompt": "# tradingview-mcp - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for atilaahmettaner/tradingview-mcp.\n\nProject:\n- Name: tradingview-mcp\n- Repository: https://github.com/atilaahmettaner/tradingview-mcp\n- Summary: 📈 AI Trading Intelligence Framework — MCP Server\n- Host target: mcp_host, claude, cursor, chatgpt\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: 📈 AI Trading Intelligence Framework — MCP Server\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Project Overview. Produce one small intermediate artifact and wait for confirmation.\n2. quick-start: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. mcp-protocol: MCP Protocol Integration. Produce one small intermediate artifact and wait for confirmation.\n5. service-architecture: Service Architecture. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/atilaahmettaner/tradingview-mcp#readme\n- openclaw/SKILL.md\n- README.md\n- pyproject.toml\n- EXAMPLES.md\n- assets/architecture.png\n- src/tradingview_mcp/server.py\n- src/tradingview_mcp/__init__.py\n- .codex-mcp.json\n- .codex-plugin/plugin.json\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github, reddit。github/github_issue: Complement idea: \"What happened next?\" via Chart Library（https://github.com/atilaahmettaner/tradingview-mcp/issues/12）；github/github_issue: [HELP] Installation Issue:（https://github.com/atilaahmettaner/tradingview-mcp/issues/24）；reddit: I built a free open-source framework that turns your AI into a multi-age（https://www.reddit.com/r/ClaudeAI/comments/1s2m1w1/i_built_a_free_opensource_framework_that_turns/）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Complement idea: \"What happened next?\" via Chart Library",
"url": "https://github.com/atilaahmettaner/tradingview-mcp/issues/12"
},
{
"kind": "github_issue",
"source": "github",
"title": "[HELP] Installation Issue:",
"url": "https://github.com/atilaahmettaner/tradingview-mcp/issues/24"
},
{
"kind": "searxng_indexed",
"source": "reddit",
"title": "I built a free open-source framework that turns your AI into a multi-age",
"url": "https://www.reddit.com/r/ClaudeAI/comments/1s2m1w1/i_built_a_free_opensource_framework_that_turns/"
}
],
"status": "已收录 3 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "📈 AI Trading Intelligence Framework — MCP Server",
"effort": "安装已验证",
"forks": null,
"icon": "link",
"name": "tradingview-mcp 能力包",
"risk": "可发布",
"slug": "tradingview-mcp",
"stars": null,
"tags": [
"MCP 工具",
"知识库问答",
"多 Agent 协作",
"多角色协作流程",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/atilaahmettaner/tradingview-mcp 项目说明书\n\n生成时间：2026-05-15 15:23:45 UTC\n\n## 目录\n\n- [Project Overview](#overview)\n- [Installation Guide](#installation)\n- [Quick Start Guide](#quick-start)\n- [System Architecture](#system-architecture)\n- [MCP Protocol Integration](#mcp-protocol)\n- [Service Architecture](#service-architecture)\n- [MCP Tools Reference](#mcp-tools-reference)\n- [Backtesting Engine](#backtesting-engine)\n- [Sentiment Analysis](#sentiment-analysis)\n- [Multi-Exchange Integration](#exchange-integrations)\n\n\n\n## Project Overview\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [MCP Tools Reference](#mcp-tools-reference), [Installation Guide](#installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n- [OPENCLAW.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/OPENCLAW.md)\n- [src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n- [pyproject.toml](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/pyproject.toml)\n \n\n# Project Overview\n\n## Introduction\n\n**TradingView-MCP** is an open-source Model Context Protocol (MCP) server that bridges AI assistants (such as Claude Desktop, Codex, and OpenClaw) with TradingView's extensive market data, technical analysis tools, and financial data services.\n\nThe project enables AI agents to perform real-time market analysis, technical indicator calculations, stock screening, backtesting, and sentiment analysis through natural language interactions. 资料来源：[README.md:1]()\n\n## Purpose and Scope\n\nThe primary objectives of TradingView-MCP are:\n\n| Objective | Description |\n|-----------|-------------|\n| **Market Data Access** | Provide real-time and historical market data from multiple exchanges |\n| **Technical Analysis** | Calculate 30+ technical indicators with BUY/SELL/HOLD signals |\n| **Multi-Exchange Support** | Cover crypto (Binance, KuCoin, Bybit), US stocks (NASDAQ, NYSE, AMEX), and regional markets |\n| **Backtesting Engine** | Test 6 trading strategies with institutional-grade metrics |\n| **Sentiment Analysis** | Aggregate Reddit and news sentiment for informed decision-making |\n\n资料来源：[README.md:1-20]()\n\n## Architecture Overview\n\nTradingView-MCP follows a modular architecture with clear separation of concerns:\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n A[Claude Desktop] --> B[MCP Protocol]\n C[Codex] --> B\n D[OpenClaw] --> B\n E[Telegram/WhatsApp] --> F[OpenClaw Agent]\n F --> B\n end\n \n subgraph \"Server Layer\"\n B --> G[server.py]\n G --> H[Core Services]\n G --> I[Technical Indicators]\n G --> J[Utilities]\n end\n \n subgraph \"Data Sources\"\n H --> K[TradingView Screener API]\n H --> L[Yahoo Finance API]\n H --> M[Reddit API]\n H --> N[News RSS Feeds]\n end\n \n subgraph \"Exchanges\"\n K --> O[Binance]\n K --> P[KuCoin]\n K --> Q[NASDAQ/NYSE]\n K --> R[EGX/BIST]\n end\n```\n\n### Directory Structure\n\n```\ntradingview-mcp/\n├── src/tradingview_mcp/\n│ ├── server.py # Main MCP server entry point\n│ ├── core/\n│ │ ├── services/ # Market data services\n│ │ ├── utils/ # Utility functions (validators.py)\n│ │ └── indicators/ # Technical indicators\n│ └── coinlist/ # Exchange symbol lists\n├── tests/\n│ ├── unit/ # Unit tests\n│ └── integration/ # Integration tests\n├── openclaw/ # OpenClaw integration files\n└── pyproject.toml # Project configuration\n```\n\n资料来源：[CONTRIBUTING.md:40-55]()\n\n## Core Features\n\n### 1. Technical Analysis Engine\n\nThe server provides comprehensive technical analysis with 30+ indicators:\n\n| Category | Indicators |\n|----------|------------|\n| **Momentum** | RSI, Stochastic, CCI, Williams %R |\n| **Trend** | MACD, EMA Cross, Supertrend, ADX |\n| **Volatility** | Bollinger Bands, ATR, Standard Deviation |\n| **Volume** | OBV, Volume Profile, A/D Line |\n| **Patterns** | 15 Candlestick Pattern Detection |\n\n资料来源：[README.md:45-60]()\n\n### 2. Backtesting System\n\nThe backtesting engine supports 6 trading strategies:\n\n```mermaid\ngraph LR\n A[Strategy Selection] --> B[rsi]\n A --> C[bollinger]\n A --> D[macd]\n A --> E[ema_cross]\n A --> F[supertrend]\n A --> G[donchian]\n \n B --> H[Performance Metrics]\n C --> H\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I[Win Rate]\n H --> J[Sharpe Ratio]\n H --> K[Calmar Ratio]\n H --> L[Max Drawdown]\n H --> M[Profit Factor]\n```\n\n**Available Strategies:**\n\n| Strategy | Type | Description |\n|----------|------|-------------|\n| `rsi` | Mean Reversion | RSI oversold/overbought signals |\n| `bollinger` | Mean Reversion | Bollinger Band price band breakout |\n| `macd` | Trend Following | MACD golden/death cross |\n| `ema_cross` | Trend Following | EMA 20/50 Golden/Death Cross |\n| `supertrend` | Trend Following | ATR-based Supertrend |\n| `donchian` | Breakout | Donchian Channel breakout (Turtle style) |\n\n资料来源：[README.md:65-85]()\n\n### 3. Yahoo Finance Integration (v0.6.0)\n\nReal-time price data integration provides:\n\n| Tool | Function |\n|------|----------|\n| `yahoo_price` | Real-time quote with price, change %, 52w high/low, market state |\n| `market_snapshot` | Global overview: S&P500, NASDAQ, BTC, EUR/USD, etc. |\n| `get_prices_bulk` | Multi-symbol price lookup |\n\n资料来源：[README.md:95-105]()\n\n## Supported Exchanges\n\nTradingView-MCP supports multiple exchange types through the `EXCHANGE_SCREENER` mapping:\n\n```mermaid\ngraph TD\n subgraph \"Crypto Exchanges\"\n A[BINANCE]\n B[KUCOIN]\n C[BYBIT+]\n D[MEXC]\n end\n \n subgraph \"US Markets\"\n E[NASDAQ]\n F[NYSE]\n G[AMEX]\n H[NYSEARCA]\n I[PCX]\n end\n \n subgraph \"Regional Markets\"\n J[EGX - Egypt]\n K[BIST - Turkey]\n L[TWSE - Taiwan]\n M[TPEX - Taiwan]\n end\n```\n\n### Exchange Configuration\n\n| Exchange | Screener Type | Symbol Format |\n|----------|---------------|---------------|\n| `BINANCE` | `crypto` | `BINANCE:BTCUSDT` |\n| `KUCOIN` | `crypto` | `KUCOIN:BTCUSDT` |\n| `NASDAQ` | `america` | `NASDAQ:AAPL` |\n| `NYSE` | `america` | `NYSE:TSLA` |\n| `AMEX` | `america` | `AMEX:SPY` |\n| `NYSEARCA` | `america` | `AMEX:GLD` |\n| `EGX` | `egypt` | `EGX:COMI` |\n| `TWSE` | `Taiwan` | `TWSE:2330` |\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:80-100]()\n\n### Stock Exchange Classification\n\nThe system classifies exchanges using `STOCK_EXCHANGES`:\n\n```python\nSTOCK_EXCHANGES = frozenset({\n \"nyse\", \"nasdaq\", \"amex\", \"nysearca\", \"pcx\",\n \"twse\", \"tpex\", \"egx\"\n})\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:60-65]()\n\n## Available Tools\n\n### Market Data Tools\n\n| Tool | Description |\n|------|-------------|\n| `top_gainers` | Find top gaining assets |\n| `top_losers` | Find top losing assets |\n| `screen_stocks` | Multi-exchange screener with 20+ filter criteria |\n| `scan_by_signal` | Scan by signal type (oversold, trending, breakout) |\n| `coin_analysis` | Comprehensive coin/symbol analysis |\n\n### Technical Analysis Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_technical_analysis` | Full TA: RSI, MACD, Bollinger, 23 indicators |\n| `get_multiple_analysis` | Bulk TA for multiple symbols |\n| `get_bollinger_band_analysis` | Proprietary ±3 BB rating system |\n| `get_stock_decision` | 3-layer decision engine |\n| `get_candlestick_patterns` | 15 candlestick pattern detector |\n| `get_multi_timeframe_analysis` | Weekly→Daily→4H→1H→15m alignment |\n\n### Backtesting Tools\n\n| Tool | Description |\n|------|-------------|\n| `backtest_strategy` | Backtest 1 of 6 strategies with Sharpe, Calmar, Expectancy |\n| `compare_strategies` | Run all 6 strategies and rank by performance |\n\n### Sentiment & News Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_reddit_sentiment` | Reddit sentiment analysis |\n| `get_live_news` | Live financial news via RSS |\n\n资料来源：[README.md:30-70]()\n\n## Installation Methods\n\n### Method 1: UV Package Manager (Recommended)\n\n```bash\n# Install uv\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install from PyPI\nuv tool install tradingview-mcp-server\n```\n\n### Method 2: Claude Desktop Configuration\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:25-40]()\n\n### Method 3: Git Clone (Local Development)\n\n```bash\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\nuv sync\nuv run python src/tradingview_mcp/server.py\n```\n\n资料来源：[CONTRIBUTING.md:15-25]()\n\n## Configuration Reference\n\n### Claude Desktop Config (Windows)\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\\\\src\\\\tradingview_mcp\\\\server.py\"],\n \"cwd\": \"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\"\n }\n }\n}\n```\n\n### Python Version Compatibility\n\n| Python Version | Status | Notes |\n|----------------|--------|-------|\n| 3.13 | ✅ Recommended | Prebuilt pandas wheels available |\n| 3.14 | ⚠️ Warning | May timeout on first launch due to source build |\n\nFor Python 3.14 on Windows, pin to Python 3.13:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\"--python\", \"3.13\", \"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:45-55]()\n\n## OpenClaw Integration\n\nTradingView-MCP can be accessed via Telegram, WhatsApp, and Discord using OpenClaw:\n\n```mermaid\ngraph LR\n A[Telegram User] --> B[OpenClaw Gateway]\n B --> C[AI Agent]\n C --> D[trading.py Wrapper]\n D --> E[tradingview-mcp]\n E --> F[Yahoo Finance API]\n```\n\n资料来源：[OPENCLAW.md:1-20]()\n\n## Development Guidelines\n\n### Code Style\n\n| Aspect | Standard |\n|--------|----------|\n| Style | PEP 8 with customizations |\n| Linting | Ruff |\n| Type Hints | Required for all functions |\n| Docstrings | Required for public functions/classes |\n\n### Testing Standards\n\n| Test Type | Coverage Target | Framework |\n|-----------|-----------------|------------|\n| Unit Tests | Core functions | pytest |\n| Integration Tests | Real API calls | pytest |\n| Linting | All code | ruff |\n| Type Checking | All code | mypy |\n\n资料来源：[CONTRIBUTING.md:70-95]()\n\n## Project Roadmap\n\n```mermaid\ngantt\n title TradingView-MCP Roadmap\n dateFormat YYYY-MM\n section Completed\n Technical Analysis (30+ indicators) :done, 2024-01, 2024-06\n Multi-exchange support :done, 2024-02, 2024-08\n Yahoo Finance integration :done, 2024-06, 2024-09\n Backtesting engine :done, 2024-07, 2024-12\n section In Progress\n Walk-forward backtesting :active, 2025-01, 2025-06\n section Planned\n Twitter/X sentiment :todo, 2025-03, 2025-06\n Paper trading simulation :todo, 2025-04, 2025-09\n Managed cloud hosting :todo, 2025-06, 2025-12\n```\n\n资料来源：[README.md:150-165]()\n\n## License\n\nTradingView-MCP is released under the **MIT License**. See [LICENSE](LICENSE) for details.\n\n资料来源：[README.md:170-172]()\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n- [OPENCLAW.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/openclaw/OPENCLAW.md)\n- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n- [src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n \n\n# Installation Guide\n\nThis guide covers all supported methods for installing and configuring the TradingView MCP server. The server acts as a bridge between AI agents (Claude Desktop, Codex, OpenClaw) and TradingView market data, enabling real-time technical analysis, screening, and sentiment analysis through natural language commands.\n\n## Prerequisites\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| Python | 3.8+ (3.10+ recommended) | Required for all installation methods |\n| UV Package Manager | Latest | Fast Python package manager for dependency management |\n| MCP Client | Claude Desktop, Codex, or OpenClaw | The AI agent interface |\n| Internet Connection | Required | For TradingView data access |\n\n资料来源：[INSTALLATION.md:1-5]()\n\n## Installation Methods\n\n### Method 1: UV Package Manager (Recommended)\n\nUV is a fast Python package manager that handles all dependencies automatically. This is the recommended installation method for most users.\n\n#### Step 1: Install UV\n\n**macOS/Linux:**\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\n```\n\n**Windows:**\n```powershell\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\nVerify installation:\n```bash\nuv --version\n```\n\n资料来源：[INSTALLATION.md:15-30]()\n\n#### Step 2: Clone the Repository\n\n```bash\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n```\n\n#### Step 3: Install Dependencies\n\n```bash\nuv sync\n```\n\n资料来源：[INSTALLATION.md:35-40]()\n\n### Method 2: Python Virtual Environment\n\nFor users who prefer traditional Python environments without UV:\n\n**Windows:**\n```powershell\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\npython -m venv .venv\n.\\.venv\\Scripts\\activate\npip install -e .\n```\n\n**macOS/Linux:**\n```bash\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n```\n\n资料来源：[INSTALLATION.md:120-140]()\n\n### Method 3: PyPI Installation (uvx)\n\nFor quick testing without cloning:\n\n```bash\nuv tool install --python 3.13 tradingview-mcp-server\n```\n\n资料来源：[README.md:45-50]()\n\n## MCP Client Configuration\n\n### Claude Desktop\n\n#### Locate Configuration File\n\n| OS | Path |\n|----|------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n资料来源：[INSTALLATION.md:55-65]()\n\n#### Add Server Configuration\n\nOpen the config file and add the following:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp\": {\n \"command\": \"uv\",\n \"args\": [\n \"tool\",\n \"run\",\n \"--from\",\n \"git+https://github.com/atilaahmettaner/tradingview-mcp.git\",\n \"tradingview-mcp\"\n ]\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:70-85]()\n\n**Windows (Direct Python Path):**\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\\\\src\\\\tradingview_mcp\\\\server.py\"],\n \"cwd\": \"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\"\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:18-25]()\n\n**macOS/Linux (Using UV):**\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"src/tradingview_mcp/server.py\"],\n \"cwd\": \"/path/to/your/tradingview-mcp\"\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:105-112]()\n\n### Codex Plugin\n\nThe repository includes MCP-only Codex plugin metadata:\n\n- `.codex-plugin/plugin.json`\n- `.codex-mcp.json`\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\n \"--from\",\n \"tradingview-mcp-server\",\n \"tradingview-mcp\"\n ]\n }\n }\n}\n```\n\n资料来源：[README.md:65-78]()\n\nAfter enabling the plugin in Codex, restart Codex so the MCP server is loaded in the next session.\n\n### OpenClaw Integration\n\nOpenClaw routes messages from Telegram, WhatsApp, Discord, and 20+ messaging platforms to an AI agent that calls tradingview-mcp functions.\n\n```mermaid\ngraph LR\n A[Telegram/WhatsApp/Discord] --> B[OpenClaw Gateway]\n B --> C[AI Agent]\n C --> D[trading.py Wrapper]\n D --> E[tradingview-mcp]\n E --> F[Yahoo Finance]\n```\n\n资料来源：[OPENCLAW.md:1-15]()\n\n#### Step 1: Install Dependencies\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\nuv tool install tradingview-mcp-server\n```\n\n资料来源：[OPENCLAW.md:8-12]()\n\n#### Step 2: Configure Channel\n\nCreate or edit `~/.openclaw/openclaw.json`:\n\n```json5\n{\n channels: {\n telegram: {\n botToken: \"YOUR_BOT_TOKEN_HERE\",\n },\n },\n}\n```\n\n资料来源：[OPENCLAW.md:15-22]()\n\n#### Step 3: Install Skill and Tool\n\n```bash\nmkdir -p ~/.agents/skills/tradingview-mcp ~/.openclaw/tools\n\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/SKILL.md \\\n -o ~/.agents/skills/tradingview-mcp/SKILL.md\n\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/trading.py \\\n -o ~/.openclaw/tools/trading.py\nchmod +x ~/.openclaw/tools/trading.py\n```\n\n资料来源：[OPENCLAW.md:25-33]()\n\n#### Step 4: Restart OpenClaw\n\n```bash\nopenclaw gateway install\nsystemctl --user start openclaw-gateway.service\nopenclaw doctor\n```\n\n资料来源：[OPENCLAW.md:55-58]()\n\n## Development Setup\n\nFor contributors who want to modify the code or run locally:\n\n### 1. Clone and Setup\n\n```bash\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n```\n\n### 2. Install Development Dependencies\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nuv sync\nuv sync --dev\n```\n\n资料来源：[CONTRIBUTING.md:5-12]()\n\n### 3. Run Tests\n\n| Command | Purpose |\n|---------|---------|\n| `uv run pytest` | Run the test suite |\n| `uv run ruff check` | Run linting |\n| `uv run mypy src/` | Run type checking |\n\n资料来源：[CONTRIBUTING.md:15-20]()\n\n### 4. Test Locally\n\n```bash\n# Test the server locally\nuv run python src/tradingview_mcp/server.py\n\n# Test with MCP Inspector\nuv run mcp dev src/tradingview_mcp/server.py\n```\n\n资料来源：[CONTRIBUTING.md:23-28]()\n\n## Directory Structure\n\nThe project follows a modular architecture:\n\n```\ntradingview-mcp/\n├── src/tradingview_mcp/\n│ ├── server.py # Main MCP server\n│ ├── core/ # Core business logic\n│ │ ├── services/ # Market data services\n│ │ ├── utils/ # Utility functions\n│ │ └── indicators/ # Technical indicators\n│ └── coinlist/ # Exchange symbol lists\n├── tests/\n│ └── unit/ # Unit tests\n├── .codex-plugin/ # Codex plugin metadata\n└── pyproject.toml # Project configuration\n```\n\n资料来源：[CONTRIBUTING.md:35-48]()\n\n## Verification\n\nAfter installation, verify the setup by asking your AI agent:\n\n```\n\"Can you show me the available TradingView tools?\"\n```\n\nExpected tools include:\n\n| Category | Tools |\n|----------|-------|\n| Market Data | `top_gainers`, `top_losers`, `yahoo_price`, `market_snapshot` |\n| Technical Analysis | `bollinger_scan`, `consecutive_candles_scan`, `technical_analysis` |\n| Sentiment | `coin_analysis`, `reddit_sentiment` |\n| Backtesting | `backtest`, `compare_strategies` |\n\n资料来源：[README.md:80-90]()\n\n## Troubleshooting\n\n### Windows: MCP Timeout on First Launch\n\nSymptom: `MCP error -32001: Request timed out` in Claude Desktop logs shortly after adding config.\n\nSolution: Pre-install the package before launching Claude Desktop:\n\n```bash\nuv tool install --python 3.13 tradingview-mcp-server\n```\n\nThis warms the cache so the server starts instantly.\n\n资料来源：[README.md:45-55]()\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| UV not found | Add UV to PATH or restart terminal |\n| Config file not found | Create the directory and file if missing |\n| Server won't start | Check Python version (3.8+ required) |\n| Timeout errors | Pre-install with `uv tool install` |\n\n## Next Steps\n\nAfter successful installation:\n\n1. Explore available tools by asking your AI agent\n2. Try basic queries like \"Show me top gainers on Binance\"\n3. Run development tests with `uv run pytest`\n4. Review [CONTRIBUTING.md](CONTRIBUTING.md) for code standards\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [MCP Tools Reference](#mcp-tools-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n- [OPENCLAW.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/OPENCLAW.md)\n- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n- [EXAMPLES.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/EXAMPLES.md)\n \n\n# Quick Start Guide\n\nThis guide provides step-by-step instructions for setting up and running the `tradingview-mcp` server, enabling AI assistants like Claude Desktop, Codex, and OpenClaw to perform real-time market analysis, technical indicators, and stock screening.\n\n## Overview\n\nThe **tradingview-mcp** project is a Model Context Protocol (MCP) server that bridges AI assistants with TradingView's market data, Yahoo Finance real-time prices, and multi-exchange screening capabilities. 资料来源：[README.md:1]()\n\nThe Quick Start process involves three main stages:\n\n```mermaid\ngraph TD\n A[Install Dependencies] --> B[Configure AI Client]\n B --> C[Verify Installation]\n A --> D[Clone Repository]\n D --> B\n C --> E[Available Tools Ready]\n```\n\n## Prerequisites\n\nBefore beginning, ensure your system meets these requirements:\n\n| Requirement | Minimum | Recommended |\n|-------------|---------|-------------|\n| Python | 3.12+ | 3.13 |\n| UV Package Manager | Latest | Latest |\n| Operating System | Windows/macOS/Linux | Ubuntu 24.04 |\n| Network | Internet for market data | Stable internet connection |\n\n资料来源：[CONTRIBUTING.md:1-5]()\n\n## Installation Methods\n\nThe project supports multiple installation approaches depending on your use case.\n\n### Method 1: Quick Start with uvx\n\nThe fastest way to get started is using `uvx` which runs the package directly without manual installation:\n\n```bash\nuvx --from tradingview-mcp-server tradingview-mcp\n```\n\nThis method requires no local setup and pulls the latest version from PyPI automatically. 资料来源：[README.md:45-48]()\n\n### Method 2: Claude Desktop Configuration\n\nFor Claude Desktop integration, configure the MCP server in your client configuration file.\n\n#### Locating Configuration File\n\n| Platform | Path |\n|----------|------|\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n资料来源：[INSTALLATION.md:15-20]()\n\n#### Windows Configuration\n\nAdd the following to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\\\\src\\\\tradingview_mcp\\\\server.py\"],\n \"cwd\": \"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\"\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:24-32]()\n\n#### macOS/Linux Configuration\n\nFor Unix-based systems, use `uv` with the run command:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"src/tradingview_mcp/server.py\"],\n \"cwd\": \"/path/to/your/tradingview-mcp\"\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:55-63]()\n\n#### Linux Full Path\n\nOn Linux systems, use the full path to uvx:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"/home/YOUR_USERNAME/.local/bin/uvx\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:60-66]()\n\n### Method 3: Local Development Setup\n\nFor development or customization, clone and run from source.\n\n#### Step 1: Clone Repository\n\n```bash\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n```\n\n#### Step 2: Install Dependencies\n\n```bash\n# Install UV if not present\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\n\n# Sync project dependencies\nuv sync\n\n# Install development dependencies\nuv sync --dev\n```\n\n#### Step 3: Verify Installation\n\n```bash\n# Test the server locally\nuv run python src/tradingview_mcp/server.py\n\n# Run the test suite\nuv run pytest\n\n# Run linting checks\nuv run ruff check\n\n# Run type checking\nuv run mypy src/\n```\n\n资料来源：[CONTRIBUTING.md:5-20]()\n\n### Method 4: Pre-installed Tool\n\nFor faster subsequent launches, pre-install the package:\n\n```bash\n# Run once before launching Claude Desktop\nuv tool install --python 3.13 tradingview-mcp-server\n```\n\nThis warms the cache so Claude Desktop starts instantly without downloading dependencies. 资料来源：[README.md:79-83]()\n\n## Python Version Considerations\n\nWhen using `uvx`, the default Python version may cause issues on Windows with Python 3.14 due to missing prebuilt `pandas` wheels.\n\n### Windows Timeout Fix\n\nIf you encounter `MCP error -32001: Request timed out` on first launch, pin Python 3.13:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\"--python\", \"3.13\", \"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:96-107]()\n\n## OpenClaw Integration\n\nFor connecting to Telegram, WhatsApp, or Discord, use the OpenClaw gateway.\n\n### Step 1: Install OpenClaw Dependencies\n\n```bash\n# Install uv if needed\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\n\n# Install tradingview-mcp-server as tool\nuv tool install tradingview-mcp-server\n```\n\n### Step 2: Configure Messaging Channel\n\nCreate or edit `~/.openclaw/openclaw.json`:\n\n```json5\n{\n channels: {\n telegram: {\n botToken: \"YOUR_BOT_TOKEN_HERE\",\n },\n },\n}\n```\n\n### Step 3: Install TradingView Skill\n\n```bash\nmkdir -p ~/.agents/skills/tradingview-mcp ~/.openclaw/tools\n\n# Download skill instructions\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/SKILL.md \\\n -o ~/.agents/skills/tradingview-mcp/SKILL.md\n\n# Download trading wrapper\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/trading.py \\\n -o ~/.openclaw/tools/trading.py\nchmod +x ~/.openclaw/tools/trading.py\n```\n\n### Step 4: Configure AI Model\n\nSet up OpenRouter with Gemini 3 Flash for optimal performance:\n\n```bash\nopenclaw config set acp.defaultAgent main\nopenclaw config set gateway.mode local\n```\n\n资料来源：[OPENCLAW.md:1-50]()\n\n## Verification and Testing\n\n### Test Claude Desktop\n\nAfter adding configuration and restarting Claude Desktop:\n\n```\n\"Can you show me the available TradingView tools?\"\n```\n\nExpected response includes tools like `top_gainers`, `top_losers`, `bollinger_scan`, `coin_analysis`, and `consecutive_candles_scan`. 资料来源：[INSTALLATION.md:68-74]()\n\n### Test OpenClaw Bot\n\nSend these commands to your Telegram bot:\n\n```\nmarket snapshot\nbacktest RSI strategy for AAPL, 1 year\ncompare all strategies for BTC-USD\n```\n\n### Available Tool Categories\n\n| Category | Tools |\n|----------|-------|\n| Market Data | `yahoo_price`, `market_snapshot`, `get_prices_bulk` |\n| Technical Analysis | `get_technical_analysis`, `get_bollinger_band_analysis`, `get_stock_decision` |\n| Screening | `screen_stocks`, `scan_by_signal`, `top_gainers`, `top_losers` |\n| Backtesting | `backtest_strategy`, `compare_strategies` |\n\n资料来源：[OPENCLAW.md:55-68]()\n\n## Example Usage\n\n### Market Snapshot\n\n```\nYou: \"Give me a full market snapshot right now\"\nAI: [market_snapshot] →\nBUY (Technical STRONG BUY + Bullish Reddit + Positive news)\n```\n\n### Strategy Backtest\n\n```\nYou: \"Compare all strategies on BTC-USD for 2 years\"\nAI: \n→ #1 Supertrend: +31.5% | Sharpe: 2.1 | WR: 62%\n→ #2 Bollinger: +18.3% | Sharpe: 3.4 | WR: 75%\n→ Buy & Hold: -5.0%\n```\n\n### Stock Screening\n\n```\nYou: \"Show me NASDAQ tech stocks that are oversold\"\nAI: [scan_by_signal(exchange=\"NASDAQ\", signal=\"oversold\")]\n```\n\n资料来源：[EXAMPLES.md:1-25]()\n\n## Troubleshooting\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| `MCP error -32001` on Windows | Python 3.14 has no prebuilt pandas | Pin to Python 3.13 in config |\n| Server won't start | Missing dependencies | Run `uv sync` in project directory |\n| Tools not showing | Claude Desktop not restarted | Fully quit and relaunch |\n| OpenClaw gateway won't start | `gateway.mode` missing | Set `openclaw config set gateway.mode local` |\n\n资料来源：[README.md:108-125]()\n\n## Next Steps\n\nAfter successful installation:\n\n1. Explore the [technical analysis tools](README.md#-technical-analysis-core) for indicator-based analysis\n2. Try the [backtesting engine](README.md#-backtesting-engine-new-in-v060) to test trading strategies\n3. Configure [multi-exchange screening](README.md#-multi-exchange-support) for global market coverage\n4. Review the [contribution guidelines](CONTRIBUTING.md) if you want to extend functionality\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[MCP Protocol Integration](#mcp-protocol), [Service Architecture](#service-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [assets/architecture.png](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/assets/architecture.png)\n- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n- [src/tradingview_mcp/__init__.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/__init__.py)\n- [src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n \n\n# System Architecture\n\n## Overview\n\nThe `tradingview-mcp` project is a Model Context Protocol (MCP) server that provides AI assistants (such as Claude Desktop) with real-time access to financial market data, technical analysis, and backtesting capabilities. It acts as a bridge between AI agents and TradingView's data infrastructure.\n\n**资料来源：** [README.md](README.md)\n\nThe server follows a layered architecture pattern with clear separation between the MCP protocol layer, business logic services, and data providers.\n\n---\n\n## High-Level Architecture\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n CLAUDE[\"Claude Desktop / AI Agent\"]\n TELEGRAM[\"Telegram Bot (OpenClaw)\"]\n CODEX[\"Codex Plugin\"]\n end\n \n subgraph \"MCP Protocol Layer\"\n SERVER[\"server.py
(MCP Server Entry)\"]\n end\n \n subgraph \"Service Layer\"\n TA[\"Technical Analysis
Indicators\"]\n SCREENER[\"Screener Service\"]\n BACKTEST[\"Backtesting Engine\"]\n YAHOO[\"Yahoo Finance API\"]\n SENTIMENT[\"Reddit Sentiment\"]\n end\n \n subgraph \"Data Provider Layer\"\n TV[\"TradingView Screener\"]\n YF[\"Yahoo Finance\"]\n RSS[\"Live News RSS\"]\n end\n \n CLAUDE --> SERVER\n TELEGRAM --> SERVER\n CODEX --> SERVER\n \n SERVER --> TA\n SERVER --> SCREENER\n SERVER --> BACKTEST\n \n SCREENER --> TV\n TA --> TV\n TA --> YF\n BACKTEST --> YAHOO\n```\n\n---\n\n## Directory Structure\n\nThe codebase is organized following Python best practices with a modular structure:\n\n```\ntradingview-mcp/\n├── src/tradingview_mcp/\n│ ├── server.py # Main MCP server entry point\n│ ├── __init__.py # Package initialization\n│ ├── core/\n│ │ ├── services/ # Market data services\n│ │ │ ├── screener_service.py # Stock/coin screening\n│ │ │ └── ...\n│ │ ├── utils/ # Utility functions\n│ │ │ ├── validators.py # Input validation & exchange mapping\n│ │ │ └── ...\n│ │ └── indicators/ # Technical indicators\n│ │ └── ... # RSI, MACD, Bollinger, etc.\n│ └── coinlist/ # Exchange symbol lists\n│ ├── binance.txt\n│ ├── kucoin.txt\n│ └── ...\n├── tests/\n│ └── unit/\n├── assets/\n│ └── architecture.png\n└── pyproject.toml\n```\n\n**资料来源：** [CONTRIBUTING.md - Code Organization](CONTRIBUTING.md)\n\n---\n\n## Core Components\n\n### MCP Server (`server.py`)\n\nThe main entry point that registers all tools as MCP resources and handlers. It exposes 30+ tools including:\n\n| Category | Tools |\n|----------|-------|\n| Backtesting | `backtest_strategy`, `compare_strategies` |\n| Technical Analysis | `get_technical_analysis`, `get_bollinger_band_analysis` |\n| Market Data | `top_gainers`, `top_losers`, `yahoo_price` |\n| Screening | `screen_stocks`, `scan_by_signal` |\n| Multi-Exchange | `egx_*`, `multi_timeframe_analysis` |\n\n**资料来源：** [src/tradingview_mcp/server.py](src/tradingview_mcp/server.py)\n\n### Validators Module\n\nThe `validators.py` module handles exchange routing and symbol validation:\n\n```python\nEXCHANGE_SCREENER = {\n \"BINANCE\": \"crypto\",\n \"KUCOIN\": \"crypto\", \n \"BYBIT\": \"crypto\",\n \"NASDAQ\": \"america\",\n \"NYSE\": \"america\",\n \"AMEX\": \"america\",\n \"TWSE\": \"Taiwan\",\n \"TPEX\": \"Taiwan\",\n \"BIST\": \"turkey\"\n}\n```\n\nKey functions include:\n- `sanitize_exchange()` - Normalizes exchange names\n- `get_tv_exchange_prefix()` - Maps exchanges to TradingView prefixes (e.g., `AMEX:GLD`)\n- Exchange alias support for `AMEX`, `NYSEARCA`, `PCX` → `AMEX`\n\n**资料来源：** [src/tradingview_mcp/core/utils/validators.py](src/tradingview_mcp/core/utils/validators.py)\n\n### Screener Service\n\nHandles multi-exchange stock and crypto screening with configurable filters:\n\n**资料来源：** [src/tradingview_mcp/core/services/screener_service.py](src/tradingview_mcp/core/services/screener_service.py)\n\n---\n\n## Backtesting Engine Architecture\n\nThe backtesting engine supports 6 trading strategies:\n\n```mermaid\ngraph LR\n A[Symbol Input] --> B[Strategy Selector]\n \n B --> C[rsi
RSI Mean Reversion]\n B --> D[bollinger
BB Mean Reversion]\n B --> E[macd
MACD Cross]\n B --> F[ema_cross
EMA 20/50]\n B --> G[supertrend
ATR Supertrend]\n B --> H[donchian
Donchian Breakout]\n \n C --> I[Metrics Calculator]\n D --> I\n E --> I\n F --> I\n G --> I\n H --> I\n \n I --> J[Win Rate, Sharpe,
Calmar, Drawdown]\n```\n\n**Performance Metrics:**\n- Win Rate, Total Return\n- Sharpe Ratio, Calmar Ratio\n- Max Drawdown, Profit Factor\n- Expectancy, Best/Worst Trade\n- Commission + slippage simulation\n\n**资料来源：** [README.md - Backtesting Engine](README.md)\n\n---\n\n## Integration Architecture\n\n### Claude Desktop Integration\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n**资料来源：** [README.md - Quick Start](README.md)\n\n### OpenClaw Integration\n\nFor Telegram/WhatsApp access:\n\n```\nTelegram → OpenClaw Agent → trading.py wrapper → tradingview-mcp → Yahoo Finance\n```\n\n**资料来源：** [OPENCLAW.md](OPENCLAW.md)\n\n---\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as MCP Server\n participant Service as Service Layer\n participant Provider as Data Provider\n \n User->>MCP: Request tool call\n MCP->>Service: Route to appropriate service\n Service->>Provider: Fetch market data\n Provider-->>Service: Raw data response\n Service-->>MCP: Processed/Formatted data\n MCP-->>User: Tool result response\n```\n\n---\n\n## Supported Exchanges\n\n| Exchange | Region | Type | Tools |\n|----------|--------|------|-------|\n| Binance | Global | Crypto | All crypto tools |\n| KuCoin | Global | Crypto | All crypto tools |\n| Bybit+ | Global | Crypto | All crypto tools |\n| NASDAQ | US | Stocks | Stock analysis, screening |\n| NYSE | US | Stocks | Stock analysis, screening |\n| AMEX | US | ETFs/Stocks | Stock analysis, screening |\n| TWSE | Taiwan | Stocks | Stock analysis, screening |\n| TPEX | Taiwan | Stocks | Stock analysis, screening |\n| BIST | Turkey | Stocks | Turkish market tools |\n| EGX | Egypt | Stocks | `egx_market_overview`, `egx_stock_screener` |\n\n**资料来源：** [src/tradingview_mcp/core/utils/validators.py](src/tradingview_mcp/core/utils/validators.py), [README.md](README.md)\n\n---\n\n## Development Architecture\n\n### Local Development Setup\n\n```bash\n# Clone and install\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\nuv sync\n\n# Test server\nuv run python src/tradingview_mcp/server.py\n\n# Run with MCP Inspector\nuv run mcp dev src/tradingview_mcp/server.py\n```\n\n### Testing Pipeline\n\n| Test Type | Command | Purpose |\n|-----------|---------|---------|\n| Unit Tests | `uv run pytest` | Core functionality |\n| Linting | `uv run ruff check` | Code style |\n| Type Checking | `uv run mypy src/` | Type safety |\n| Integration | `uv run python test_api.py` | End-to-end |\n\n**资料来源：** [CONTRIBUTING.md - Testing](CONTRIBUTING.md)\n\n---\n\n## Adding New Components\n\n### Adding a New Exchange\n\n1. **Update validators.py:**\n ```python\n EXCHANGE_SCREENER = {\n \"NEW_EXCHANGE\": \"screener_code\",\n # ... existing\n }\n STOCK_EXCHANGES.add(\"NEW_EXCHANGE\")\n ```\n\n2. **Add symbol list:**\n ```bash\n echo \"SYMBOL1\\nSYMBOL2\" > coinlist/new_exchange.txt\n ```\n\n3. **Test integration:**\n ```python\n result = top_gainers(exchange=\"NEW_EXCHANGE\")\n ```\n\n**资料来源：** [CONTRIBUTING.md - Adding New Exchange](CONTRIBUTING.md)\n\n### Adding Technical Indicators\n\n1. **Create indicator function in `core/indicators/`:**\n ```python\n def calculate_custom_indicator(prices: List[float]) -> float:\n \"\"\"Calculate custom technical indicator\"\"\"\n return result\n ```\n\n2. **Integrate in server.py:**\n ```python\n custom_value = calculate_custom_indicator(price_data)\n result[\"technical_indicators\"][\"custom\"] = custom_value\n ```\n\n**资料来源：** [CONTRIBUTING.md - Adding Technical Indicators](CONTRIBUTING.md)\n\n---\n\n## Deployment Options\n\n| Method | Use Case | Command/Config |\n|--------|----------|----------------|\n| **uvx (Recommended)** | Quick start, no local install | `uvx --from tradingview-mcp-server tradingview-mcp` |\n| **Local Clone** | Development/modification | `git clone && uv sync && uv run python src/tradingview_mcp/server.py` |\n| **Pre-installed Tool** | Reusable cache | `uv tool install --python 3.13 tradingview-mcp-server` |\n| **Virtual Environment** | Traditional Python | `python -m venv .venv && pip install -e .` |\n| **OpenClaw** | Telegram/WhatsApp | See [OPENCLAW.md](OPENCLAW.md) |\n\n**资料来源：** [INSTALLATION.md](INSTALLATION.md), [README.md](README.md)\n\n---\n\n## Configuration Reference\n\n### Claude Desktop Configuration\n\n**Windows (Direct Python Path):**\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp\": {\n \"command\": \"C:\\\\Users\\\\Username\\\\tradingview-mcp\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\"C:\\\\Users\\\\Username\\\\tradingview-mcp\\\\src\\\\tradingview_mcp\\\\server.py\"],\n \"cwd\": \"C:\\\\Users\\\\Username\\\\tradingview-mcp\"\n }\n }\n}\n```\n\n**macOS/Linux (Using UV):**\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"src/tradingview_mcp/server.py\"],\n \"cwd\": \"/path/to/tradingview-mcp\"\n }\n }\n}\n```\n\n**资料来源：** [INSTALLATION.md - Local Development Setup](INSTALLATION.md)\n\n---\n\n\n\n## MCP Protocol Integration\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [MCP Tools Reference](#mcp-tools-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n- [.codex-mcp.json](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/.codex-mcp.json)\n- [.codex-plugin/plugin.json](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/.codex-plugin/plugin.json)\n- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n \n\n# MCP Protocol Integration\n\n## Overview\n\nThe TradingView MCP Server implements the **Model Context Protocol (MCP)** to provide AI assistants with structured access to real-time market data, technical analysis, and screening tools. MCP serves as the communication bridge between AI clients (Claude Desktop, Codex) and the TradingView data infrastructure.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[AI Client
Claude Desktop / Codex] --> B[MCP Protocol Layer]\n B --> C[tradingview-mcp Server]\n C --> D[Core Services]\n C --> E[Technical Indicators]\n C --> F[Screener Services]\n D --> G[Yahoo Finance API]\n D --> H[TradingView API]\n F --> I[Exchange Symbol Lists
coinlist/]\n \n style B fill:#e1f5fe\n style C fill:#fff3e0\n```\n\n### Component Layers\n\n| Layer | Responsibility | Key Components |\n|-------|---------------|----------------|\n| **AI Client** | User interaction, natural language processing | Claude Desktop, Codex |\n| **MCP Protocol** | Standardized communication, tool discovery | JSON-RPC 2.0 messages |\n| **Server** | Request routing, tool registration | `server.py` |\n| **Services** | Business logic, data processing | Screener, Technical Analysis |\n| **Data Sources** | External API integration | Yahoo Finance, TradingView |\n\n## Server Implementation\n\nThe main server is implemented in `src/tradingview_mcp/server.py` and exposes TradingView tools as MCP resources.\n\n### Available Tools\n\nThe server registers the following tools for market analysis:\n\n| Tool Category | Tools |\n|--------------|-------|\n| **Market Screening** | `top_gainers`, `top_losers`, `screen_stocks`, `scan_by_signal` |\n| **Technical Analysis** | `get_technical_analysis`, `get_multiple_analysis`, `get_bollinger_band_analysis` |\n| **Pattern Detection** | `get_candlestick_patterns`, `consecutive_candles_scan`, `bollinger_scan` |\n| **Multi-Timeframe** | `get_multi_timeframe_analysis`, `coin_analysis` |\n| **Stock Decision** | `get_stock_decision` |\n\n### Server Initialization\n\n```python\n# Minimal MCP server setup pattern\nfrom mcp.server import Server\nfrom mcp.server.stdio import stdio_server\n\napp = Server(\"tradingview-mcp\")\n# Register tools and resources\n```\n\n## Client Configuration\n\n### Claude Desktop\n\nThe server integrates with Claude Desktop via the MCP configuration file:\n\n| Platform | Config Location |\n|----------|-----------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n**Configuration Schema:**\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp\": {\n \"command\": \"uv\",\n \"args\": [\n \"tool\",\n \"run\",\n \"--from\",\n \"git+https://github.com/atilaahmettaner/tradingview-mcp.git\",\n \"tradingview-mcp\"\n ]\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n\n### Codex Plugin\n\nThe repository includes dedicated Codex plugin metadata for seamless integration:\n\n**Plugin Configuration Files:**\n\n| File | Purpose |\n|------|---------|\n| `.codex-plugin/plugin.json` | Plugin manifest |\n| `.codex-mcp.json` | MCP server configuration |\n\n**Codex Configuration:**\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\n \"--from\",\n \"tradingview-mcp-server\",\n \"tradingview-mcp\"\n ]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n## Installation Methods\n\n### Method 1: Direct Installation via UV\n\n```bash\n# Install from PyPI\nuv tool install tradingview-mcp-server\n```\n\n资料来源：[INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n\n### Method 2: Source Installation\n\n```bash\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\nuv run tradingview-mcp\n```\n\n### Method 3: Pre-warm Cache (Windows)\n\nFor Windows users with Python 3.14, pre-install to avoid initialization timeout:\n\n```bash\nuv tool install --python 3.13 tradingview-mcp-server\n```\n\n资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n## Development Workflow\n\n```mermaid\ngraph LR\n A[Clone Repository] --> B[Install Dependencies
uv sync]\n B --> C[Run Server
uv run python src/tradingview_mcp/server.py]\n C --> D[Test with MCP Inspector
uv run mcp dev src/tradingview_mcp/server.py]\n D --> E[Submit PR]\n \n style A fill:#c8e6c9\n style E fill:#c8e6c9\n```\n\n### Development Commands\n\n| Command | Purpose |\n|---------|---------|\n| `uv sync` | Install all dependencies |\n| `uv sync --dev` | Install development dependencies |\n| `uv run pytest` | Execute test suite |\n| `uv run ruff check` | Run linting |\n| `uv run mypy src/` | Run type checking |\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n## OpenClaw Integration\n\nFor messaging platforms (Telegram, WhatsApp, Discord), OpenClaw provides an alternative integration path:\n\n```mermaid\ngraph LR\n A[Telegram / WhatsApp] --> B[OpenClaw Agent]\n B --> C[trading.py Wrapper]\n C --> D[tradingview-mcp]\n D --> E[Yahoo Finance]\n \n style B fill:#e1f5fe\n style D fill:#fff3e0\n```\n\n### OpenClaw Quick Setup\n\n```bash\n# Install dependencies\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nuv tool install tradingview-mcp-server\n\n# Configure channel\ncat > ~/.openclaw/openclaw.json << 'EOF'\n{\n channels: {\n telegram: {\n botToken: \"YOUR_BOT_TOKEN_HERE\",\n },\n },\n}\nEOF\n\n# Install skill and tool\nmkdir -p ~/.agents/skills/tradingview-mcp ~/.openclaw/tools\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/SKILL.md \\\n -o ~/.agents/skills/tradingview-mcp/SKILL.md\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/trading.py \\\n -o ~/.openclaw/tools/trading.py && chmod +x ~/.openclaw/tools/trading.py\n```\n\n资料来源：[OPENCLAW.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/OPENCLAW.md)\n\n## Troubleshooting\n\n### Windows Initialization Timeout\n\n**Issue:** `MCP error -32001: Request timed out` on first launch with Python 3.14\n\n**Root Cause:** pandas has no prebuilt wheel for Python 3.14, causing pip to fall back to source build which exceeds 60-second timeout.\n\n**Solution:** Pin to Python 3.13:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\"--python\", \"3.13\", \"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n### Verification Steps\n\nAfter installation, verify the MCP server is operational:\n\n1. Restart the AI client completely\n2. Ask: \"Can you show me the available TradingView tools?\"\n3. Confirm tools like `top_gainers`, `bollinger_scan`, `coin_analysis` are available\n\n## Code Organization\n\n```\nsrc/tradingview_mcp/\n├── server.py # Main MCP server implementation\n├── core/ # Core business logic\n│ ├── services/ # Market data services\n│ ├── utils/ # Utility functions (validators, etc.)\n│ └── indicators/ # Technical indicators\n└── coinlist/ # Exchange symbol lists\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n## Next Steps\n\n- Review the [Technical Analysis documentation](technical-analysis) for available indicators\n- Explore the [Screening Tools](screening-tools) for market filtering\n- Configure your preferred AI client following the installation guide\n\n---\n\n\n\n## Service Architecture\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [MCP Tools Reference](#mcp-tools-reference), [Multi-Exchange Integration](#exchange-integrations)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tradingview_mcp/core/services/backtest_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/backtest_service.py)\n- [src/tradingview_mcp/core/services/sentiment_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/sentiment_service.py)\n- [src/tradingview_mcp/core/services/indicators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators.py)\n- [src/tradingview_mcp/core/services/scanner_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/scanner_service.py)\n- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n- [src/tradingview_mcp/core/services/news_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/news_service.py)\n- [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)\n- [src/tradingview_mcp/core/services/indicators_calc.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators_calc.py)\n \n\n# Service Architecture\n\nThe TradingView MCP (Model Context Protocol) server implements a **modular service-oriented architecture** that separates concerns across distinct functional domains. This design enables the system to provide comprehensive market analysis capabilities—including technical indicators, sentiment analysis, backtesting, and real-time price data—through a unified MCP interface.\n\n## Overview\n\nThe service architecture follows a **layered pattern** where the MCP server acts as the presentation layer, delegating business logic to specialized services. Each service is responsible for a specific domain of functionality, communicating through well-defined interfaces.\n\n### High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"MCP Server Layer\"\n SERVER[server.py - MCP Entry Point]\n end\n \n subgraph \"Service Layer\"\n BACKTEST[backtest_service.py]\n SENTIMENT[sentiment_service.py]\n NEWS[news_service.py]\n YAHOO[yahoo_finance_service.py]\n SCREENER[screener_service.py]\n SCANNER[scanner_service.py]\n INDICATORS[indicators.py]\n CALC[indicators_calc.py]\n end\n \n subgraph \"Data Sources\"\n TV[TradingView API]\n REDDIT[Reddit API]\n RSS[RSS Feeds]\n YAHOO_FIN[Yahoo Finance API]\n end\n \n SERVER --> BACKTEST\n SERVER --> SENTIMENT\n SERVER --> NEWS\n SERVER --> YAHOO\n SERVER --> SCREENER\n SERVER --> SCANNER\n SERVER --> INDICATORS\n \n INDICATORS --> CALC\n BACKTEST --> CALC\n SCREENER --> TV\n SENTIMENT --> REDDIT\n NEWS --> RSS\n YAHOO --> YAHOO_FIN\n```\n\n### Service Directory Structure\n\n```\nsrc/tradingview_mcp/core/services/\n├── backtest_service.py # Strategy backtesting engine\n├── indicators.py # Technical indicator orchestration\n├── indicators_calc.py # Low-level indicator calculations\n├── news_service.py # RSS news aggregation\n├── scanner_service.py # Pattern scanning and detection\n├── screener_service.py # Multi-exchange market screening\n├── sentiment_service.py # Reddit sentiment analysis\n└── yahoo_finance_service.py # Real-time price data\n```\n\n资料来源：[CONTRIBUTING.md:62-70]()\n\n## Service Components\n\n### 1. Backtest Service\n\nThe backtest service provides a comprehensive strategy testing framework with institutional-grade metrics.\n\n| Feature | Description |\n|---------|-------------|\n| Strategy Types | RSI, Bollinger Bands, MACD, EMA Cross, Supertrend, Donchian |\n| Metrics | Win Rate, Sharpe Ratio, Calmar Ratio, Max Drawdown, Profit Factor |\n| Commission Simulation | Realistic slippage and commission modeling |\n\n资料来源：[src/tradingview_mcp/core/services/backtest_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/backtest_service.py)\n\n### 2. Screener Service\n\nThe screener service aggregates market data from TradingView's screener across multiple exchanges.\n\n| Exchange | Screener Type |\n|----------|---------------|\n| Binance, KuCoin, Bybit+ | Crypto screener |\n| NASDAQ, NYSE | US stocks |\n| TWSE, TPEX | Taiwan stocks |\n| AMEX, NYSEARCA, PCX | ETFs and specialty securities |\n| EGX | Egyptian exchange |\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n\n### 3. Indicators Service\n\nThe indicators service orchestrates calculation of 30+ technical indicators.\n\n| Category | Indicators |\n|----------|------------|\n| Momentum | RSI, MACD, Stochastic, CCI, Williams %R |\n| Trend | EMA, SMA, Supertrend, ADX |\n| Volatility | Bollinger Bands, ATR, Standard Deviation |\n| Volume | OBV, Volume Profile |\n\n资料来源：[src/tradingview_mcp/core/services/indicators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators.py)\n\n### 4. Indicators Calculation Module\n\nThe `indicators_calc.py` module provides the underlying mathematical calculations for all technical indicators.\n\n```python\n# Example: RSI calculation pattern\ndef calculate_rsi(prices: List[float], period: int = 14) -> float:\n \"\"\"Calculate Relative Strength Index\"\"\"\n # Implementation uses Wilder's smoothing method\n return rsi_value\n```\n\n资料来源：[src/tradingview_mcp/core/services/indicators_calc.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators_calc.py)\n\n### 5. Sentiment Service\n\nThe sentiment service analyzes social media sentiment from Reddit communities.\n\n| Function | Purpose |\n|----------|---------|\n| Community Detection | Identifies relevant subreddits for symbols |\n| Sentiment Scoring | Quantifies bullish/bearish community sentiment |\n| Integration | Combines with technical analysis for confluence |\n\n资料来源：[src/tradingview_mcp/core/services/sentiment_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/sentiment_service.py)\n\n### 6. News Service\n\nThe news service aggregates financial news from RSS feeds for market sentiment and event analysis.\n\n| Feed Type | Content |\n|-----------|---------|\n| Financial News | Market news, earnings reports |\n| Sector News | Industry-specific developments |\n| Macro News | Economic indicators and Fed communications |\n\n资料来源：[src/tradingview_mcp/core/services/news_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/news_service.py)\n\n### 7. Yahoo Finance Service\n\nThe Yahoo Finance service provides real-time price quotes and market data.\n\n| Data Point | Description |\n|------------|-------------|\n| Price | Current and historical prices |\n| Changes | Daily, weekly, yearly change percentages |\n| 52-Week Range | High/low boundaries |\n| Market State | Pre-market, regular, after-hours |\n\n资料来源：[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)\n\n### 8. Scanner Service\n\nThe scanner service detects technical patterns and trading signals across markets.\n\n| Pattern Type | Detection |\n|--------------|-----------|\n| Candlestick | 15 candlestick patterns (Doji, Hammer, Engulfing, etc.) |\n| Technical | Bollinger Band breakouts, volume spikes |\n| Signal-based | Oversold/overbought conditions, trend detection |\n\n资料来源：[src/tradingview_mcp/core/services/scanner_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/scanner_service.py)\n\n## Data Flow Architecture\n\n### Request Processing Flow\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Server as server.py\n participant Service as Service Layer\n participant External as External APIs\n \n Client->>Server: Tool Request\n Server->>Service: Delegate to Domain Service\n Service->>External: Fetch Data\n External-->>Service: Raw Data\n Service-->>Server: Processed Result\n Server-->>Client: MCP Response\n```\n\n### Multi-Timeframe Analysis Flow\n\nThe `multi_timeframe_analysis` function demonstrates cross-service integration:\n\n```mermaid\ngraph LR\n A[Symbol Selection] --> B[Weekly Analysis]\n B --> C[Daily Analysis]\n C --> D[4H Analysis]\n D --> E[1H Analysis]\n E --> F[15m Analysis]\n F --> G[Confluence Decision]\n \n B --> H[indicators.py]\n C --> H\n D --> H\n E --> H\n F --> H\n```\n\n资料来源：[src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n\n## Service Configuration\n\n### Exchange Mappings\n\nThe system maintains exchange-to-screener mappings for routing:\n\n```python\nEXCHANGE_SCREENER = {\n \"NASDAQ\": \"america\",\n \"NYSE\": \"america\",\n \"KUCOIN\": \"crypto\",\n \"BINANCE\": \"crypto\",\n \"EGX\": \"egypt\",\n \"TWSE\": \"crypto\", # Taiwan Stock Exchange\n \"TPEX\": \"crypto\", # Taiwan OTC\n \"AMEX\": \"america\",\n \"NYSEARCA\": \"america\",\n \"PCX\": \"america\",\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n### Symbol List Management\n\nEach exchange maintains a symbol list file for supported trading pairs:\n\n```\ncoinlist/\n├── binance.txt\n├── kucoin.txt\n├── mexc.txt\n├── egx.txt\n└── bybit.txt\n```\n\n## Integration Patterns\n\n### Strategy Backtesting Integration\n\n```mermaid\ngraph TD\n A[backtest_strategy] --> B[Load Historical Data]\n B --> C[Initialize Strategy]\n C --> D[Generate Signals]\n D --> E[Calculate Metrics]\n E --> F[Generate Trade Log]\n F --> G[Return Results]\n \n D --> H[indicators_calc.py]\n E --> I[Sharpe Ratio]\n E --> J[Max Drawdown]\n E --> K[Profit Factor]\n```\n\n### Confluence Analysis Pattern\n\nThe system combines multiple data sources for decision-making:\n\n1. **Technical Analysis** → `indicators.py` + `indicators_calc.py`\n2. **Sentiment Analysis** → `sentiment_service.py`\n3. **News Analysis** → `news_service.py`\n4. **Price Data** → `yahoo_finance_service.py`\n\n资料来源：[openclaw/SKILL.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/openclaw/SKILL.md)\n\n## Testing Architecture\n\n### Unit Tests\n\nServices are validated through dedicated unit test files:\n\n| Test File | Coverage |\n|-----------|----------|\n| `tests/unit/test_exchange_fixes.py` | Exchange validation, symbol construction |\n| `tests/unit/test_exchange_aliases.py` | Alias mappings, TWSE/TPEX handling |\n\n### Integration Testing\n\nThe project includes integration tests for real market data:\n\n```bash\nuv run pytest\nuv run ruff check\nuv run mypy src/\n```\n\n资料来源：[CONTRIBUTING.md:30-38]()\n\n## Summary\n\nThe service architecture of tradingview-mcp is designed around:\n\n| Principle | Implementation |\n|-----------|----------------|\n| **Separation of Concerns** | Each service handles a single domain |\n| **Reusability** | Shared `indicators_calc.py` for all indicator calculations |\n| **Testability** | Independent services with clear interfaces |\n| **Extensibility** | Easy to add new exchanges or indicators |\n| **Composability** | Services combine for complex analyses like confluence |\n\nThis architecture enables the MCP server to expose 30+ tools while maintaining clean, maintainable code organized by functional responsibility.\n\n---\n\n\n\n## MCP Tools Reference\n\n### 相关页面\n\n相关主题：[Backtesting Engine](#backtesting-engine), [Sentiment Analysis](#sentiment-analysis), [Multi-Exchange Integration](#exchange-integrations)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n- [src/tradingview_mcp/core/types.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/types.py)\n- [src/tradingview_mcp/core/services/indicators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators.py)\n- [src/tradingview_mcp/core/services/indicators_calc.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators_calc.py)\n- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n- [src/tradingview_mcp/core/services/yahoo_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/yahoo_service.py)\n \n\n# MCP Tools Reference\n\n## Overview\n\nThe MCP Tools Reference documents all available Model Context Protocol (MCP) tools exposed by the TradingView MCP Server. These tools enable AI assistants like Claude Desktop, Codex, and OpenClaw to perform real-time market data retrieval, technical analysis, and trading signal generation through a standardized tool-calling interface.\n\nThe tradingview-mcp server acts as a bridge between AI agents and TradingView's market data infrastructure, providing programmatic access to cryptocurrency, stock, and forex market information across multiple exchanges worldwide.\n\n**资料来源：** [README.md](README.md)\n\n---\n\n## Architecture Overview\n\n### System Components\n\n```mermaid\ngraph TD\n subgraph \"AI Agent Layer\"\n A[Claude Desktop / Codex / OpenClaw]\n end\n \n subgraph \"MCP Protocol Layer\"\n B[MCP Server
tradingview-mcp]\n C[Tool Registry]\n end\n \n subgraph \"Data Source Layer\"\n D[TradingView Screener API]\n E[Yahoo Finance API]\n F[Exchange APIs
Binance, KuCoin, NASDAQ...]\n end\n \n A -->|MCP Protocol| B\n B --> C\n C -->|Market Data| D\n C -->|Real-time Prices| E\n C -->|Bulk Queries| F\n \n style B fill:#4a90d9\n style C fill:#5ba85b\n```\n\n### Tool Categories\n\n| Category | Description | Number of Tools |\n|----------|-------------|-----------------|\n| **Market Data** | Real-time prices and snapshots | 5+ |\n| **Technical Analysis** | Indicators, patterns, decisions | 8+ |\n| **Screening** | Top gainers/losers, custom filters | 10+ |\n| **Backtesting** | Strategy comparison and metrics | 2 |\n| **Multi-Exchange** | Cross-exchange analysis | 6+ |\n\n**资料来源：** [README.md](README.md)\n\n---\n\n## Core Tool Types\n\n### Tool Definition Schema\n\nAll MCP tools follow a standardized type definition structure defined in `core/types.py`:\n\n```python\n@dataclass\nclass ToolDefinition:\n name: str\n description: str\n input_schema: dict\n handler: Callable\n```\n\n**资料来源：** [src/tradingview_mcp/core/types.py](src/tradingview_mcp/core/types.py)\n\n---\n\n## Market Data Tools\n\n### yahoo_price\n\nRetrieves real-time quote data for a single symbol including price, change percentage, 52-week range, and market state.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `symbol` | string | Yes | - | Ticker symbol (e.g., BTC-USD, AAPL) |\n| `exchange` | string | No | auto-detect | Exchange prefix (optional override) |\n\n**Returns:**\n```json\n{\n \"symbol\": \"BTC-USD\",\n \"price\": 67432.50,\n \"change_percent\": 2.34,\n \"52w_high\": 73000.00,\n \"52w_low\": 52000.00,\n \"market_state\": \"REGULAR\"\n}\n```\n\n**资料来源：** [src/tradingview_mcp/core/services/yahoo_service.py](src/tradingview_mcp/core/services/yahoo_service.py)\n\n---\n\n### market_snapshot\n\nProvides a global market overview combining multiple asset classes in a single response.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `include_crypto` | boolean | No | true |\n| `include_indices` | boolean | No | true |\n| `include_forex` | boolean | No | true |\n\n**Coverage:**\n- **Crypto:** BTC-USD, ETH-USD, SOL-USD, etc.\n- **Indices:** S&P 500, NASDAQ, DOW\n- **Forex:** EUR/USD, GBP/USD, USD/JPY\n\n**资料来源：** [src/tradingview_mcp/core/services/yahoo_service.py](src/tradingview_mcp/core/services/yahoo_service.py)\n\n---\n\n### get_prices_bulk\n\nRetrieves price data for multiple symbols in a single call.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `symbols` | string[] | Yes | - | Array of ticker symbols |\n| `exchange` | string | No | auto-detect | Exchange prefix |\n\n**资料来源：** [server.py:server.py](src/tradingview_mcp/server.py)\n\n---\n\n## Technical Analysis Tools\n\n### get_technical_analysis\n\nExecutes comprehensive technical analysis with 23+ indicators, returning BUY/SELL/HOLD signals with confluence scoring.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `symbol` | string | Yes | - | Ticker symbol |\n| `exchange` | string | No | KUCOIN | Exchange identifier |\n| `timeframe` | string | No | 1D | Time interval (1m, 5m, 15m, 1h, 4h, 1D, 1W) |\n| `indicators` | string[] | No | all | Specific indicators to calculate |\n\n**Included Indicators:**\n\n| Indicator | Type | Signal Logic |\n|-----------|------|--------------|\n| RSI (14) | Momentum | Oversold <30, Overbought >70 |\n| MACD | Trend | Signal line crossover |\n| Bollinger Bands | Volatility | Price near bands |\n| EMA Cross | Trend | 20/50 period crossover |\n| Supertrend | Trend | ATR-based reversal |\n| ATR | Volatility | Raw volatility measure |\n| ADX | Trend Strength | >25 indicates strong trend |\n\n**资料来源：** [src/tradingview_mcp/core/services/indicators.py](src/tradingview_mcp/core/services/indicators.py)\n\n---\n\n### get_bollinger_band_analysis\n\nProprietary Bollinger Band analysis with ±3 rating system for volatility and position assessment.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `symbol` | string | Yes | - |\n| `exchange` | string | No | KUCOIN |\n| `timeframe` | string | No | 1D |\n\n**Response Structure:**\n```python\n{\n \"bandwidth\": 0.0342,\n \"position\": \"upper_50_percent\",\n \"signal\": \"BUY\",\n \"rating\": 2 # -3 to +3 scale\n}\n```\n\n**Bandwidth Calculation:**\n```\nBBW = (Upper Band - Lower Band) / Middle Band\n```\n\n**资料来源：** [src/tradingview_mcp/core/services/indicators.py](src/tradingview_mcp/core/services/indicators.py), [CONTRIBUTING.md](CONTRIBUTING.md)\n\n---\n\n### get_multiple_analysis\n\nRuns technical analysis on multiple symbols simultaneously.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `symbols` | string[] | Yes | - |\n| `exchange` | string | No | KUCOIN |\n| `timeframe` | string | No | 1D |\n\n**资料来源：** [server.py](src/tradingview_mcp/server.py)\n\n---\n\n### get_stock_decision\n\nThree-layer decision engine combining ranking, trade setup, and quality scoring.\n\n**Layers:**\n1. **Ranking Score** - Relative strength vs market\n2. **Trade Setup** - Entry/exit signal alignment\n3. **Quality Score** - Overall confidence rating\n\n**资料来源：** [README.md](README.md)\n\n---\n\n### get_candlestick_patterns\n\nDetects 15+ candlestick patterns in historical price data.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `symbol` | string | Yes | - |\n| `exchange` | string | No | KUCOIN |\n| `timeframe` | string | No | 1D |\n| `pattern_type` | string | No | all |\n\n**Supported Patterns:**\n- Doji, Hammer, Engulfing, Morning Star\n- Harami, Shooting Star, Three White Soldiers\n- Dark Cloud Cover, Piercing Line\n\n**资料来源：** [server.py](src/tradingview_mcp/server.py)\n\n---\n\n### get_multi_timeframe_analysis\n\nAnalyzes the same symbol across multiple timeframes to identify aligned trends.\n\n**Timeframe Alignment:**\n\n```mermaid\ngraph LR\n W[Weekly] --> D[Daily]\n D --> H4[4H]\n H4 --> H1[1H]\n H1 --> M15[15m]\n \n style W fill:#4a90d9\n style M15 fill:#d94a4a\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `symbol` | string | Yes | - |\n| `exchange` | string | No | KUCOIN |\n| `timeframes` | string[] | No | [1D, 4H, 1H, 15m] |\n\n**资料来源：** [PR_BODY.md](PR_BODY.md), [README.md](README.md)\n\n---\n\n## Screening Tools\n\n### top_gainers\n\nScreens for top-performing assets by percentage gain on a specific exchange.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `exchange` | string | No | KUCOIN | Exchange identifier |\n| `timeframe` | string | No | 1D | Time interval |\n| `limit` | integer | No | 10 | Number of results (max 50) |\n\n**Supported Exchanges:**\n- **Crypto:** KUCOIN, BINANCE, BYBIT\n- **US Markets:** NASDAQ, NYSE\n- **Regional:** BIST, EGX, TWSE, TPEX\n\n**资料来源：** [src/tradingview_mcp/core/services/screener_service.py](src/tradingview_mcp/core/services/screener_service.py)\n\n---\n\n### top_losers\n\nScreens for worst-performing assets by percentage decline.\n\n**Parameters:** Identical to `top_gainers`\n\n**资料来源：** [server.py](src/tradingview_mcp/server.py)\n\n---\n\n### scan_by_signal\n\nScans markets filtered by predefined signal types.\n\n**Signal Types:**\n\n| Signal | Description |\n|--------|-------------|\n| `oversold` | RSI below 30 |\n| `overbought` | RSI above 70 |\n| `trending_up` | Strong upward momentum |\n| `trending_down` | Strong downward momentum |\n| `breakout` | Price breaking resistance |\n| `breakdown` | Price breaking support |\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `signal_type` | string | Yes | - |\n| `exchange` | string | No | KUCOIN |\n| `timeframe` | string | No | 1D |\n| `limit` | integer | No | 20 |\n\n**资料来源：** [server.py](src/tradingview_mcp/server.py)\n\n---\n\n### bollinger_scan\n\nScans for Bollinger Band squeeze patterns indicating potential volatility expansion.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `exchange` | string | No | KUCOIN |\n| `timeframe` | string | No | 1D |\n| `bbw_threshold` | float | No | 0.05 | Bandwidth threshold for squeeze detection |\n| `limit` | integer | No | 20 |\n\n**Squeeze Detection Logic:**\n```python\n# Squeeze detected when bandwidth < threshold\nif bandwidth < bbw_threshold:\n return \"SQZ\" # Potential breakout setup\n```\n\n**资料来源：** [EXAMPLES.md](EXAMPLES.md)\n\n---\n\n### consecutive_candles_scan\n\nDetects coins with consecutive bullish or bearish candles indicating sustained momentum.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `pattern_type` | string | No | bullish | bullish or bearish |\n| `timeframe` | string | No | 1h | Time interval |\n| `min_count` | integer | No | 3 | Minimum consecutive candles |\n| `exchange` | string | No | KUCOIN |\n\n**Example Response:**\n```\nSOLUSDT - 4 consecutive green candles (1h)\nTotal gain: +8.4%\nVolume increasing\n```\n\n**资料来源：** [EXAMPLES.md](EXAMPLES.md)\n\n---\n\n### screen_stocks\n\nMulti-criteria stock screener with 20+ filter parameters.\n\n**Filter Categories:**\n\n| Category | Filters |\n|----------|---------|\n| **Price** | price_min, price_max |\n| **Volume** | volume_min, volume_max |\n| **Technical** | rsi_above, rsi_below, sma_50_above, sma_200_below |\n| **Fundamentals** | market_cap_min, market_cap_max |\n| **Performance** | change_above, change_below |\n\n**资料来源：** [README.md](README.md)\n\n---\n\n## Backtesting Tools\n\n### backtest_strategy\n\nRuns historical backtest for a single trading strategy with institutional-grade metrics.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `symbol` | string | Yes | - |\n| `strategy` | string | Yes | - | Strategy name |\n| `period` | string | No | 1Y | Backtest period |\n| `initial_capital` | float | No | 10000 | Starting capital |\n| `commission` | float | No | 0.1 | Commission percentage |\n\n**Available Strategies:**\n\n| Strategy | Logic | Best For |\n|----------|-------|----------|\n| `rsi` | RSI oversold/overbought mean reversion | Range-bound markets |\n| `bollinger` | Bollinger Band bounce | Volatile markets |\n| `macd` | MACD golden/death cross | Trend changes |\n| `ema_cross` | EMA 20/50 crossover | Medium-term trends |\n| `supertrend` | ATR-based trend following | Strong trends |\n| `donchian` | Donchian Channel breakout | Momentum plays |\n\n**Metrics Returned:**\n\n| Metric | Description |\n|--------|-------------|\n| Win Rate | Percentage of profitable trades |\n| Total Return | Overall percentage gain/loss |\n| Sharpe Ratio | Risk-adjusted return |\n| Calmar Ratio | Return / Max drawdown |\n| Max Drawdown | Largest peak-to-trough decline |\n| Profit Factor | Gross profit / Gross loss |\n| Expectancy | Average expected return per trade |\n\n**资料来源：** [README.md](README.md)\n\n---\n\n### compare_strategies\n\nRuns all 6 strategies on the same symbol and ranks by performance.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `symbol` | string | Yes | - |\n| `period` | string | No | 1Y | Backtest period |\n| `limit` | integer | No | 10 | Number of top strategies to return |\n\n**Output Format:**\n```\n#1 Supertrend: +31.5% | Sharpe: 2.1 | WR: 62%\n#2 Bollinger: +18.3% | Sharpe: 3.4 | WR: 75%\n#3 Buy & Hold: -5.0%\n```\n\n**资料来源：** [README.md](README.md)\n\n---\n\n## Exchange-Specific Tools\n\n### Exchange Support Matrix\n\n| Exchange | Region | Screener | Price Data | Specific Tools |\n|----------|--------|----------|------------|----------------|\n| KUCOIN | Global Crypto | ✅ | ✅ | All tools |\n| BINANCE | Global Crypto | ✅ | ✅ | All tools |\n| BYBIT | Global Crypto | ✅ | ✅ | All tools |\n| NASDAQ | US Stocks | ✅ | ✅ | All tools |\n| NYSE | US Stocks | ✅ | ✅ | All tools |\n| BIST | Turkey | ✅ | ✅ | All tools |\n| EGX | Egypt | ✅ | ✅ | egx_* tools |\n| TWSE | Taiwan | ✅ | ✅ | - |\n| TPEX | Taiwan | ✅ | ✅ | - |\n\n### Symbol Construction\n\nTradingView requires properly formatted exchange-prefixed symbols:\n\n```\n{EXCHANGE}:{SYMBOL}\nExamples:\n- KUCOIN:SOLUSDT\n- BINANCE:BTCUSDT\n- NASDAQ:AAPL\n```\n\n**资料来源：** [src/tradingview_mcp/core/services/screener_service.py](src/tradingview_mcp/core/services/screener_service.py), [PR_BODY.md](PR_BODY.md)\n\n---\n\n## Tool Registration Flow\n\n```mermaid\nsequenceDiagram\n participant Server as MCP Server\n participant Registry as Tool Registry\n participant Handler as Tool Handler\n \n Server->>Registry: register_tools()\n Registry->>Handler: Instantiate tool class\n Handler->>Registry: Register name, schema, callback\n \n Note over Registry: All tools registered at startup\n \n Client->>Server: list_tools()\n Server->>Registry: get_all_tools()\n Registry-->>Client: Tool definitions\n \n Client->>Server: call_tool(name, params)\n Server->>Handler: execute(params)\n Handler-->>Server: Tool result\n Server-->>Client: JSON-RPC response\n```\n\n**资料来源：** [src/tradingview_mcp/server.py](src/tradingview_mcp/server.py)\n\n---\n\n## Response Format Standards\n\n### Success Response\n\n```json\n{\n \"result\": {\n \"status\": \"success\",\n \"data\": { ... },\n \"metadata\": {\n \"timestamp\": \"2024-01-15T10:30:00Z\",\n \"source\": \"tradingview-screener\",\n \"latency_ms\": 245\n }\n }\n}\n```\n\n### Error Response\n\n```json\n{\n \"error\": {\n \"code\": \"EXCHANGE_NOT_FOUND\",\n \"message\": \"Exchange 'INVALID' is not supported\",\n \"details\": {\n \"supported\": [\"KUCOIN\", \"BINANCE\", \"NASDAQ\", \"NYSE\"]\n }\n }\n}\n```\n\n---\n\n## Usage Examples\n\n### Basic Market Query\n\n```\nYou: \"Show me top 5 crypto gainers on KuCoin in 15 minutes\"\n\nAI: [Uses: top_gainers(exchange=\"KUCOIN\", timeframe=\"15\", limit=5)]\n\n🇰🇪 KuCoin Top Gainers (15m):\n\n1. **SOLUSDT** - $142.50 (+5.2%)\n2. **AVAXUSDT** - $34.20 (+4.1%)\n3. **MATICUSDT** - $0.82 (+3.8%)\n4. **LINKUSDT** - $14.50 (+3.2%)\n5. **DOTUSDT** - $6.80 (+2.9%)\n```\n\n### Technical Analysis Request\n\n```\nYou: \"Analyze Bitcoin with all technical indicators\"\n\nAI: [Uses: get_technical_analysis(symbol=\"BTC\", exchange=\"BINANCE\")]\n\n📊 BTC-USD Technical Analysis:\n\nRSI (14): 58.4 → NEUTRAL\nMACD: BULLISH CROSSOVER\nBollinger Bands: UPPER_50_PERCENT\nADX: 32.5 → STRONG TREND\n\nOverall Signal: BUY (Confluence Score: 7/10)\n```\n\n### Strategy Comparison\n\n```\nYou: \"Compare all strategies on BTC-USD for 2 years\"\n\nAI: [Uses: compare_strategies(symbol=\"BTC\", period=\"2Y\")]\n\n📈 Strategy Comparison Results:\n\n#1 Supertrend: +31.5% | Sharpe: 2.1 | WR: 62%\n#2 Bollinger: +18.3% | Sharpe: 3.4 | WR: 75%\n#3 MACD: +12.1% | Sharpe: 1.8 | WR: 55%\n#4 EMA Cross: +8.4% | Sharpe: 1.2 | WR: 52%\n#5 RSI: -2.1% | Sharpe: -0.3 | WR: 45%\n#6 Donchian: -8.5% | Sharpe: -1.1 | WR: 38%\n\nBuy & Hold: -5.0%\n```\n\n**资料来源：** [EXAMPLES.md](EXAMPLES.md), [README.md](README.md)\n\n---\n\n## Configuration\n\n### MCP Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp\": {\n \"command\": \"uv\",\n \"args\": [\n \"tool\",\n \"run\",\n \"--from\",\n \"git+https://github.com/atilaahmettaner/tradingview-mcp.git\",\n \"tradingview-mcp\"\n ]\n }\n }\n}\n```\n\n### Local Development Configuration\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"src/tradingview_mcp/server.py\"],\n \"cwd\": \"/path/to/tradingview-mcp\"\n }\n }\n}\n```\n\n**资料来源：** [INSTALLATION.md](INSTALLATION.md)\n\n---\n\n## See Also\n\n- [Installation Guide](INSTALLATION.md) - Setup instructions for MCP clients\n- [Contributing Guide](CONTRIBUTING.md) - Development standards and testing\n- [OpenClaw Integration](OPENCLAW.md) - Telegram/WhatsApp bot setup\n- [Examples](EXAMPLES.md) - Real-world usage scenarios\n\n---\n\n\n\n## Backtesting Engine\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [Service Architecture](#service-architecture)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/tradingview_mcp/core/services/backtest_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/backtest_service.py)\n- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n- [CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)\n- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n \n\n# Backtesting Engine\n\nThe Backtesting Engine is a core component of the `tradingview-mcp` project that provides automated strategy testing capabilities using historical market data. It enables traders and developers to validate trading strategies against real price data before deploying them in live markets.\n\n## Overview\n\nThe Backtesting Engine (v3, v0.7.0) is a pure Python implementation that requires no external backtesting libraries such as pandas or numpy. It fetches historical OHLCV (Open, High, Low, Close, Volume) data from Yahoo Finance and simulates trading strategies with realistic commission and slippage modeling.\n\n**Key Characteristics:**\n\n- Pure Python implementation with no pandas/numpy dependencies\n- 6 built-in trading strategies\n- Supports daily (1d) and hourly (1h) timeframes\n- Walk-forward analysis for overfitting detection\n- Full trade logging with detailed per-trade breakdowns\n- Equity curve generation for performance visualization\n\n资料来源：[backtest_service.py:1-20]()\n\n## Architecture\n\nThe Backtesting Engine follows a layered architecture with clear separation of concerns:\n\n```mermaid\ngraph TD\n subgraph \"MCP Tool Layer\"\n A[\"backtest_strategy\"]\n B[\"compare_strategies\"]\n C[\"walk_forward_backtest_strategy\"]\n end\n \n subgraph \"Service Layer\"\n D[\"backtest_service.py\"]\n E[\"indicators_calc.py\"]\n end\n \n subgraph \"Data Layer\"\n F[\"Yahoo Finance API\"]\n end\n \n A --> D\n B --> D\n C --> D\n D --> E\n D --> F\n E --> F\n```\n\n### Component Responsibilities\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| MCP Tool Layer | `server.py` | Exposes backtesting as MCP tools |\n| Service Layer | `backtest_service.py` | Core backtesting logic, trade simulation |\n| Indicators | `indicators_calc.py` | Technical indicator calculations |\n| External Data | Yahoo Finance API | OHLCV price data retrieval |\n\n资料来源：[server.py]() [backtest_service.py:1-50]()\n\n## Supported Strategies\n\nThe Backtesting Engine includes 6 pre-built trading strategies:\n\n| Strategy | Type | Description |\n|----------|------|-------------|\n| `rsi` | Mean Reversion | RSI oversold (<30) / overbought (>70) signals |\n| `bollinger` | Mean Reversion | Bollinger Band bounce trading |\n| `macd` | Momentum | MACD golden/death cross signals |\n| `ema_cross` | Trend Following | EMA 20/50 Golden/Death Cross |\n| `supertrend` | Trend Following | ATR-based Supertrend (🔥 most popular) |\n| `donchian` | Breakout | Donchian Channel breakout (Turtle Trader style) |\n\n资料来源：[backtest_service.py:15-22]()\n\n### Strategy Selection Flow\n\n```mermaid\ngraph TD\n A[\"Start Backtest\"] --> B{\"Strategy Valid?\"}\n B -->|No| E[\"Return Error: Unknown strategy\"]\n B -->|Yes| F[\"Fetch OHLCV Data\"]\n F --> G{\"Sufficient Data?\"}\n G -->|No| H[\"Return Error: Not enough data\"]\n G -->|Yes| I[\"Execute Strategy Logic\"]\n I --> J[\"Calculate Metrics\"]\n J --> K[\"Return Results\"]\n```\n\n资料来源：[backtest_service.py:100-140]()\n\n## MCP Tool Functions\n\nThe Backtesting Engine exposes three primary MCP tools through the server interface.\n\n### 1. backtest_strategy\n\nExecutes a single strategy backtest on a given symbol.\n\n**Function Signature:**\n```python\n@mcp.tool()\ndef backtest_strategy(\n symbol: str,\n strategy: str,\n period: str = \"1y\",\n initial_capital: float = 10000.0,\n commission_pct: float = 0.1,\n slippage_pct: float = 0.05,\n interval: str = \"1d\",\n include_trade_log: bool = False,\n include_equity_curve: bool = False,\n) -> dict\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `symbol` | str | Required | Yahoo Finance symbol (AAPL, BTC-USD, SPY...) |\n| `strategy` | str | Required | rsi, bollinger, macd, ema_cross, supertrend, donchian |\n| `period` | str | \"1y\" | 1mo, 3mo, 6mo, 1y, 2y |\n| `initial_capital` | float | 10000.0 | Starting capital in USD |\n| `commission_pct` | float | 0.1 | Per-trade commission % |\n| `slippage_pct` | float | 0.05 | Per-trade slippage % |\n| `interval` | str | \"1d\" | 1d (daily) or 1h (hourly) |\n| `include_trade_log` | bool | False | Include detailed trade log |\n| `include_equity_curve` | bool | False | Include equity curve data points |\n\n资料来源：[server.py]()\n\n### 2. compare_strategies\n\nRuns all 6 strategies on the same symbol and ranks by performance.\n\n**Function Signature:**\n```python\n@mcp.tool()\ndef compare_strategies(\n symbol: str,\n period: str = \"1y\",\n initial_capital: float = 10000.0,\n interval: str = \"1d\",\n) -> dict\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `symbol` | str | Required | Yahoo Finance symbol |\n| `period` | str | \"1y\" | 1mo, 3mo, 6mo, 1y, 2y |\n| `initial_capital` | float | 10000.0 | Starting capital in USD |\n| `interval` | str | \"1d\" | 1d (daily) or 1h (hourly) |\n\n资料来源：[server.py]()\n\n### 3. walk_forward_backtest_strategy\n\nWalk-forward backtesting to detect strategy overfitting.\n\n**Function Signature:**\n```python\n@mcp.tool()\ndef walk_forward_backtest_strategy(\n symbol: str,\n strategy: str,\n period: str = \"2y\",\n initial_capital: float = 10000.0,\n commission_pct: float = 0.1,\n slippage_pct: float = 0.05,\n n_splits: int = 3,\n train_ratio: float = 0.7,\n interval: str = \"1d\",\n) -> dict\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `symbol` | str | Required | Yahoo Finance symbol |\n| `strategy` | str | Required | rsi, bollinger, macd, ema_cross, supertrend, donchian |\n| `period` | str | \"2y\" | Recommended: 2y for walk-forward |\n| `n_splits` | int | 3 | Number of walk-forward folds (2-10) |\n| `train_ratio` | float | 0.7 | Fraction used for training |\n\n资料来源：[server.py]()\n\n## Walk-Forward Analysis\n\nWalk-forward analysis is a robust method for detecting strategy overfitting. It splits historical data into multiple train/test folds to validate strategy performance on unseen data.\n\n### Methodology\n\n```mermaid\ngraph LR\n subgraph \"Fold 1\"\n A1[\"Train 70%\"] --> B1[\"Test 30%\"]\n end\n subgraph \"Fold 2\"\n A2[\"Train 70%\"] --> B2[\"Test 30%\"]\n end\n subgraph \"Fold 3\"\n A3[\"Train 70%\"] --> B3[\"Test 30%\"]\n end\n```\n\n### Robustness Scoring\n\n| Score | Classification | Interpretation |\n|-------|----------------|-----------------|\n| ≥ 0.8 | ROBUST | No overfitting detected |\n| ≥ 0.5 | MODERATE | Some degradation expected |\n| ≥ 0.2 | WEAK | Likely overfitted |\n| < 0.2 | OVERFITTED | Do not trade live |\n\nThe robustness score is calculated as: `test_return / train_return`\n\n资料来源：[backtest_service.py:180-220]()\n\n## Return Metrics\n\nThe backtesting engine calculates comprehensive performance metrics:\n\n### Core Metrics\n\n| Metric | Description |\n|--------|-------------|\n| Total Return % | Overall strategy return |\n| Sharpe Ratio | Risk-adjusted return (annualized) |\n| Calmar Ratio | Return / Maximum Drawdown |\n| Max Drawdown % | Largest peak-to-trough decline |\n| Win Rate % | Percentage of profitable trades |\n| Profit Factor | Gross profit / Gross loss |\n| Expectancy | Average trade return including losses |\n| Best Trade % | Best single trade return |\n| Worst Trade % | Worst single trade return |\n\n### Interval-Aware Annualization\n\nSharpe ratio annualization adjusts based on timeframe:\n\n| Interval | Annualization Factor |\n|----------|---------------------|\n| 1d | 252 (trading days/year) |\n| 1h | 252 × 6 (trading hours/year) |\n\n资料来源：[backtest_service.py:30-32]()\n\n## Data Fetching\n\nThe engine retrieves OHLCV data from Yahoo Finance:\n\n**API Endpoint:**\n```\nhttps://query1.finance.yahoo.com/v8/finance/chart/{symbol}\n```\n\n**User Agent:**\n```\ntradingview-mcp/0.7.0 backtest-bot\n```\n\n**Validation Rules:**\n\n| Interval | Minimum Bars Required |\n|----------|----------------------|\n| 1d | 30 bars |\n| 1h | 100 bars |\n\n资料来源：[backtest_service.py:24-29]()\n\n## Trade Simulation\n\nThe trade simulation includes realistic trading costs:\n\n### Cost Components\n\n| Component | Default | Description |\n|-----------|---------|-------------|\n| Commission | 0.1% | Per-trade commission |\n| Slippage | 0.05% | Per-trade price slippage |\n\n### Trade Log Fields\n\nWhen `include_trade_log=True`, each trade includes:\n\n| Field | Description |\n|-------|-------------|\n| `entry_date` | Trade entry timestamp |\n| `exit_date` | Trade exit timestamp |\n| `entry_price` | Entry price |\n| `exit_price` | Exit price |\n| `holding_days` | Days held |\n| `gross_return_pct` | Gross return before costs |\n| `net_return_pct` | Net return after costs |\n| `cost_pct` | Total costs (commission + slippage) |\n| `capital_at_entry` | Capital at entry |\n| `capital_after_trade` | Capital after trade |\n| `cumulative_return` | Cumulative return at this point |\n\n### Equity Curve\n\nWhen `include_equity_curve=True`, returns data points at each trade exit:\n\n```python\n{\n \"equity_curve\": [\n {\"date\": \"2023-01-15\", \"capital\": 10500.00, \"drawdown_pct\": 0.0},\n {\"date\": \"2023-02-20\", \"capital\": 10200.00, \"drawdown_pct\": -2.86},\n ...\n ]\n}\n```\n\n资料来源：[backtest_service.py:140-180]()\n\n## Usage Examples\n\n### Basic Backtest\n```\nYou: \"Backtest RSI strategy for AAPL over 1 year\"\n→ backtest_strategy(symbol=\"AAPL\", strategy=\"rsi\", period=\"1y\")\n```\n\n### Strategy Comparison\n```\nYou: \"Compare all strategies on BTC-USD for 2 years\"\n→ compare_strategies(symbol=\"BTC-USD\", period=\"2y\")\n\nOutput:\n→ #1 Supertrend: +31.5% | Sharpe: 2.1 | WR: 62%\n→ #2 Bollinger: +18.3% | Sharpe: 3.4 | WR: 75%\n→ Buy & Hold: -5.0%\n```\n\n### Walk-Forward Analysis\n```\nYou: \"Is the RSI strategy overfitted for AAPL?\"\n→ walk_forward_backtest_strategy(\n symbol=\"AAPL\",\n strategy=\"rsi\",\n period=\"2y\",\n n_splits=3\n)\n```\n\n### Full Trade Log\n```\nYou: \"Show me the full trade log for the backtest\"\n→ backtest_strategy(\n symbol=\"AAPL\",\n strategy=\"supertrend\",\n period=\"1y\",\n include_trade_log=True\n)\n```\n\n资料来源：[README.md]()\n\n## Version History\n\n| Version | Date | Key Changes |\n|---------|------|-------------|\n| v0.7.0 | Latest | 1h timeframe, full trade log, equity curve, walk-forward |\n| v0.6.0 | 2026-03-29 | Initial backtesting engine with 6 strategies |\n\n资料来源：[CHANGELOG.md]()\n\n## Error Handling\n\n| Error Condition | Response |\n|-----------------|----------|\n| Unknown strategy | `{\"error\": \"Unknown strategy 'X'. Choose: rsi, bollinger...\"}` |\n| Invalid period | `{\"error\": \"Invalid period 'X'. Choose: 1mo, 3mo, 6mo, 1y, 2y\"}` |\n| Invalid interval | `{\"error\": \"Invalid interval 'X'. Choose: 1d or 1h\"}` |\n| Data fetch failure | `{\"error\": \"Failed to fetch data for 'X': {exception}\"}` |\n| Insufficient data | `{\"error\": \"Not enough data (N bars). Try a longer period.\"}` |\n\n资料来源：[backtest_service.py:100-150]()\n\n## Disclaimer\n\n⚠️ **Important:** Past performance does not guarantee future results. Backtested results include hypothetical trades that may not reflect actual market conditions including liquidity constraints, emotional decision-making, and execution delays.\n\n---\n\n\n\n## Sentiment Analysis\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [Service Architecture](#service-architecture)\n\n\nRelated Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/tradingview_mcp/core/services/sentiment_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/sentiment_service.py)\n- [src/tradingview_mcp/core/services/news_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/multi_agent_service.py)\n- [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)\n- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n- [openclaw/trading.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/openclaw/trading.py)\n- [src/tradingview_mcp/core/data/egx_sectors.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/data/egx_sectors.py)\n \n\n# Sentiment Analysis\n\nThe Sentiment Analysis module is a core component of the tradingview-mcp framework that aggregates social media sentiment data—primarily from Reddit—and converts it into actionable trading signals. This module works in conjunction with technical analysis and news feeds to provide a multi-signal confluence system that helps traders understand market mood and community consensus around specific assets.\n\n## Overview\n\nThe sentiment analysis system is designed to:\n\n- Fetch posts from Reddit across multiple subreddit categories\n- Score text content using a custom sentiment scoring algorithm\n- Categorize sentiment into actionable labels (Bullish, Bearish, Neutral)\n- Integrate with the broader multi-agent trading framework\n- Provide confidence scoring when combined with technical indicators\n\nThe module operates as part of a three-layer analytical system that includes:\n\n1. **Technical Analyst** — Bollinger Bands, RSI, MACD\n2. **Sentiment & Momentum Analyst** — Reddit community sentiment + price momentum\n3. **Risk Manager** — Volatility, drawdown risk, mean-reversion signals\n\n资料来源：[README.md:1-50]()\n\n## Architecture\n\nThe sentiment analysis system follows a layered architecture:\n\n```mermaid\ngraph TD\n A[analyze_sentiment API] --> B[Category Selection]\n B --> C[Subreddit Groups]\n C --> D[Per-Subreddit Fetch]\n D --> E[_fetch_reddit_posts]\n E --> F[Text Extraction]\n F --> G[_score_text]\n G --> H[Score Aggregation]\n H --> I[Result Construction]\n I --> J[Sentiment Label + Breakdown]\n```\n\n### Component Structure\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| `analyze_sentiment` | `sentiment_service.py` | Main public API entry point |\n| `_fetch_reddit_posts` | `sentiment_service.py` | Reddit API integration |\n| `_score_text` | `sentiment_service.py` | Sentiment scoring algorithm |\n| `analyze_confluence` | `server.py` | Combined technical + sentiment analysis |\n| `multi_agent_analysis` | `multi_agent_service.py` | Multi-agent trading decision system |\n\n资料来源：[src/tradingview_mcp/core/services/sentiment_service.py:1-100]()\n\n## Subreddit Configuration\n\nThe system uses a predefined configuration of subreddit groups organized by market category:\n\n### SUBREDDIT_GROUPS Structure\n\n| Category | Subreddits | Target Markets |\n|----------|------------|----------------|\n| `crypto` | r/CryptoCurrency, r/Bitcoin, r/ethereum, r/CryptocurrencyMarket, r/SatoshiStreetBets | Cryptocurrency |\n| `stocks` | r/wallstreetbets, r/stocks, r/investing, r/StockMarket | US Equities |\n| `all` | Combined crypto + stocks subreddits | Multi-asset |\n\n资料来源：[src/tradingview_mcp/core/services/sentiment_service.py:1-50]()\n\n## API Reference\n\n### `analyze_sentiment`\n\nThe primary function for retrieving and analyzing Reddit sentiment.\n\n```python\ndef analyze_sentiment(\n symbol: str,\n category: str = \"all\",\n limit: int = 20,\n) -> dict:\n```\n\n#### Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `symbol` | `str` | Required | Asset ticker/name (e.g., \"AAPL\", \"BTC\", \"ETH\", \"TSLA\", \"THYAO\") |\n| `category` | `str` | `\"all\"` | Subreddit group: `\"crypto\"` \\| `\"stocks\"` \\| `\"all\"` |\n| `limit` | `int` | `20` | Total number of posts to analyze across all subreddits |\n\n#### Return Value\n\n```python\n{\n \"sentiment_score\": float, # -1.0 to +1.0\n \"sentiment_label\": str, # \"Bullish\" | \"Bearish\" | \"Neutral\"\n \"posts_analyzed\": int, # Total posts processed\n \"posts\": List[dict], # Individual post details\n \"top_posts\": List[dict], # Highest-impact posts\n}\n```\n\n#### Post Object Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `title` | `str` | Post title (truncated to 120 chars) |\n| `upvotes` | `int` | Reddit upvotes |\n| `comments` | `int` | Number of comments |\n| `sentiment` | `str` | Per-post sentiment label |\n\n资料来源：[src/tradingview_mcp/core/services/sentiment_service.py:50-100]()\n\n## Sentiment Scoring Algorithm\n\n### Scoring Logic\n\nThe `_score_text` function processes raw text and returns a score:\n\n```mermaid\ngraph LR\n A[Raw Text Input] --> B[Tokenize]\n B --> C[Keyword Matching]\n C --> D{Keyword Type}\n D -->|Bullish| E[Positive Increment]\n D -->|Bearish| F[Negative Increment]\n D -->|Neutral| G[Zero Score]\n E --> H[Normalize to -1...+1]\n F --> H\n G --> H\n```\n\n### Scoring Thresholds\n\n| Score Range | Label | Description |\n|-------------|-------|-------------|\n| `> 0.15` | **Bullish** | Strong positive community sentiment |\n| `0.05 to 0.15` | **Slightly Bullish** | Mild positive sentiment |\n| `-0.05 to 0.05` | **Neutral** | Balanced or unclear sentiment |\n| `-0.15 to -0.05` | **Slightly Bearish** | Mild negative sentiment |\n| `< -0.15` | **Bearish** | Strong negative community sentiment |\n\n资料来源：[src/tradingview_mcp/core/services/sentiment_service.py:30-50]()\n\n## Multi-Agent Integration\n\nThe sentiment analysis module is a critical component of the multi-agent trading framework:\n\n```mermaid\ngraph TD\n subgraph \"Multi-Agent System\"\n A[Technical Analyst] --> D[Debate & Score]\n B[Sentiment Analyst] --> D\n C[Risk Manager] --> D\n end\n \n subgraph \"Sentiment Analyst (B)\"\n B1[analyze_sentiment] --> B2[Momentum Calculation]\n B2 --> B3[Sentiment Score]\n B3 --> B4[Bullish/Bearish Label]\n end\n \n D --> E[Framework Decision]\n E --> F[STRONG BUY / BUY / HOLD / SELL / STRONG SELL]\n```\n\n### Multi-Agent Output\n\nThe framework combines signals from all three agents to produce:\n\n| Output | Description |\n|--------|-------------|\n| `decision` | Final trading recommendation |\n| `confidence` | Confidence level based on agent agreement |\n| `scores` | Individual agent scores |\n| `reasoning` | Brief explanation of the decision |\n\n资料来源：[src/tradingview_mcp/core/services/multi_agent_service.py]()\n\n## Confluence System\n\nThe confluence system combines technical analysis with sentiment to provide higher-confidence signals:\n\n### Signal Agreement Matrix\n\n| Technical Signal | Sentiment Signal | Confluence | Confidence |\n|------------------|------------------|------------|------------|\n| Bullish | Bullish | Technical confirmed by Sentiment | HIGH |\n| Bearish | Bearish | Technical confirmed by Sentiment | HIGH |\n| Bullish | Bearish | Technical conflicts with Sentiment | MIXED |\n| Bearish | Bullish | Technical conflicts with Sentiment | MIXED |\n\n资料来源：[src/tradingview_mcp/server.py:1-50]()\n\n### Implementation\n\n```python\ndef analyze_confluence(symbol, exchange, timeframe):\n tech = get_technical_analysis(symbol, exchange, timeframe)\n cat = \"crypto\" if exchange.upper() in [\"BINANCE\", \"KUCOIN\", \"BYBIT\", \"MEXC\"] else \"stocks\"\n sentiment = analyze_sentiment(symbol, category=cat)\n \n tech_momentum = tech.get(\"market_sentiment\", {}).get(\"momentum\", \"\")\n tech_bullish = tech_momentum == \"Bullish\"\n sent_bullish = sentiment.get(\"sentiment_score\", 0) > 0.1\n signals_agree = tech_bullish == sent_bullish\n confidence = \"HIGH\" if signals_agree else \"MIXED\"\n```\n\n资料来源：[src/tradingview_mcp/server.py:50-100]()\n\n## Exchange-Specific Behavior\n\nThe sentiment analysis module adapts its subreddit selection based on the target exchange:\n\n| Exchange Category | Exchange Examples | Sentiment Category | Subreddits Used |\n|-------------------|-------------------|-------------------|-----------------|\n| Crypto | BINANCE, KUCOIN, BYBIT, MEXC | `crypto` | Bitcoin, ethereum, CryptoCurrency, etc. |\n| Stocks | NASDAQ, NYSE | `stocks` | wallstreetbets, stocks, investing |\n| Emerging Markets | EGX, BIST | Auto-detected | Appropriate regional subreddits |\n\n资料来源：[src/tradingview_mcp/core/services/egx_sectors.py]()\n\n## OpenClaw Integration\n\nThe sentiment analysis can be accessed via the OpenClaw Telegram bot integration:\n\n### Available Commands\n\n```bash\nsentiment # Analyze Reddit sentiment for a symbol\n```\n\n### OpenClaw Trading Wrapper\n\nThe `openclaw/trading.py` wrapper provides CLI access to sentiment analysis:\n\n```python\nelif cmd == \"sentiment\":\n print(json.dumps(analyze_sentiment(args[0]), indent=2))\n```\n\n资料来源：[openclaw/trading.py:1-50]()\n\n## Usage Examples\n\n### Basic Sentiment Analysis\n\n```python\nfrom tradingview_mcp.core.services.sentiment_service import analyze_sentiment\n\n# Analyze Bitcoin sentiment\nresult = analyze_sentiment(symbol=\"BTC\", category=\"crypto\", limit=20)\n\nprint(f\"Sentiment Score: {result['sentiment_score']}\")\nprint(f\"Label: {result['sentiment_label']}\")\nprint(f\"Posts Analyzed: {result['posts_analyzed']}\")\n```\n\n### Confluence Analysis\n\n```python\nfrom tradingview_mcp.server import analyze_confluence\n\n# Full confluence analysis for Apple stock\nresult = analyze_confluence(\n symbol=\"AAPL\",\n exchange=\"NASDAQ\",\n timeframe=\"1D\"\n)\n\nprint(f\"Confidence: {result['confluence']['confidence']}\")\nprint(f\"Recommendation: {result['confluence']['recommendation']}\")\n```\n\n### Multi-Agent Decision\n\n```python\nfrom tradingview_mcp.core.services.multi_agent_service import multi_agent_analysis\n\n# Get full multi-agent analysis\ndecision = multi_agent_analysis(symbol=\"ETH\", exchange=\"KUCOIN\")\n\nprint(f\"Decision: {decision['decision']}\")\nprint(f\"Confidence: {decision['confidence']}\")\n```\n\n## Limitations and Considerations\n\n| Aspect | Limitation | Mitigation |\n|--------|------------|------------|\n| Data Source | Reddit only | Future Twitter/X integration planned (roadmap) |\n| Real-time | Reddit API rate limits | Configurable limit parameter |\n| Regional Markets | Limited non-English subreddits | Regional market focus |\n| Sentiment Quality | Keyword-based scoring | Multi-agent verification system |\n\n资料来源：[README.md:100-150]()\n\n## Roadmap\n\nPlanned enhancements for sentiment analysis:\n\n- [ ] **Twitter/X market sentiment** — Expand data sources beyond Reddit\n- [ ] **Walk-forward backtesting** — Test sentiment signals against historical data\n- [ ] **Multi-language support** — Analyze non-English social media\n- [ ] **Real-time streaming** — WebSocket-based sentiment updates\n\n资料来源：[README.md:150-180]()\n\n## See Also\n\n- [Technical Analysis](technical_analysis.md) — RSI, MACD, Bollinger Bands integration\n- [Multi-Agent Framework](multi_agent_framework.md) — Complete agent debate system\n- [Backtesting Engine](backtesting.md) — Strategy validation with sentiment signals\n- [OpenClaw Integration](openclaw_integration.md) — Telegram bot deployment\n\n---\n\n\n\n## Multi-Exchange Integration\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tradingview_mcp/coinlist](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/coinlist)\n- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n- [src/tradingview_mcp/core/services/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)\n- [src/tradingview_mcp/core/services/coinlist.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/coinlist.py)\n \n\n# Multi-Exchange Integration\n\n## Overview\n\nThe Multi-Exchange Integration module enables the tradingview-mcp framework to query and analyze financial instruments across multiple global exchanges. It provides a unified abstraction layer that routes market data requests to the appropriate TradingView screener endpoint based on exchange type, symbol format, and market classification.\n\nThe system supports:\n- **Cryptocurrency exchanges**: Binance, KuCoin, Bybit, MEXC\n- **US stock markets**: NASDAQ, NYSE, AMEX (including NYSEARCA, PCX aliases)\n- **Taiwan markets**: TWSE, TPEX\n- **Egyptian Exchange**: EGX\n- **Turkish market**: BIST\n\n资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"API Layer\"\n A[Server Tools] --> B[Request Validation]\n end\n \n subgraph \"Exchange Routing\"\n B --> C[validators.py]\n C --> D{symbol_type?}\n D -->|Stock| E[EXCHANGE_SCREENER]\n D -->|Crypto| F[Direct Exchange]\n E --> G[get_tv_exchange_prefix]\n F --> H[Exchange Aliases]\n end\n \n subgraph \"Data Sources\"\n G --> I[screener_service.py]\n H --> J[coinlist.py]\n I --> K[TradingView Screener API]\n J --> L[Symbol Lists]\n end\n \n subgraph \"Market-Specific Services\"\n K --> M[egx_service.py]\n L --> N[EGX Sectors]\n end\n```\n\n## Exchange Classification System\n\n### Core Exchange Types\n\nThe framework classifies exchanges into two primary categories: stock exchanges and cryptocurrency exchanges.\n\n| Classification | Description | Examples |\n|----------------|-------------|----------|\n| `stock` | Traditional stock markets with symbol-based trading | NASDAQ, NYSE, TWSE, TPEX, EGX, BIST |\n| `crypto` | Cryptocurrency exchanges with pair-based trading | KUCOIN, BINANCE, BYBIT, MEXC |\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n### Exchange Registry\n\nThe `EXCHANGE_SCREENER` set contains all exchanges that work with the TradingView screener API:\n\n```python\nEXCHANGE_SCREENER = {\n \"binance\", \"kucoin\", \"bybit\", \"mexc\",\n \"nasdaq\", \"nyse\", \"amex\", \"nysearca\", \"pcx\",\n \"twse\", \"tpex\", \"egx\", \"bist\"\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:1-20](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n## Symbol Construction and Exchange Prefixes\n\n### TradingView Symbol Format\n\nTradingView requires symbols to be prefixed with the exchange code in the format `EXCHANGE:SYMBOL`. The framework uses the `get_tv_exchange_prefix()` function to map exchange aliases to their canonical TradingView prefix.\n\n```python\n_EXCHANGE_TV_PREFIX: Dict[str, str] = {\n \"nysearca\": \"AMEX\",\n \"pcx\": \"AMEX\",\n \"tpex\": \"TWSE\",\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n### Exchange Prefix Resolution\n\n```mermaid\ngraph LR\n A[Exchange Input] --> B{sanitized lowercased}\n B --> C{Exact Match?}\n C -->|Yes| D[Return Prefix]\n C -->|No| E[Fallback: UPPERCASE]\n \n subgraph \"Known Aliases\"\n F[nysearca] --> D\n G[pcx] --> D\n H[tpex] --> D\n end\n```\n\nThe resolution logic:\n1. Input is trimmed and lowercased\n2. Lookup in `_EXCHANGE_TV_PREFIX` dictionary\n3. Returns mapped prefix or uppercase fallback for unknown exchanges\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n### Screener Symbol Construction\n\nIn `screener_service.py`, the `analyze_coin` function constructs full TradingView symbols:\n\n```python\ndef analyze_coin(symbol: str, exchange: str = \"KUCOIN\") -> dict:\n # Get the TradingView exchange prefix\n tv_exchange = get_tv_exchange_prefix(exchange)\n \n # Construct full symbol for TradingView API\n if is_stock_exchange(exchange):\n tv_symbol = f\"{tv_exchange}:{symbol.upper()}\"\n else:\n tv_symbol = f\"{symbol.upper()}\"\n```\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n\n## Exchange Alias System\n\n### AMEX Aliases\n\nThe framework normalizes several exchange identifiers to AMEX for ETF and commodity trading:\n\n| Alias | Canonical Name | Use Case |\n|-------|----------------|----------|\n| `AMEX` | AMEX | American Stock Exchange ETFs |\n| `NYSEARCA` | AMEX | NYSE Arca ETFs |\n| `PCX` | AMEX | Arca ETF notation |\n\n资料来源：[PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n\n### Taiwan Exchange Aliases\n\nTaiwan stock symbols are routed to TWSE with the TPEX alias for OTC trading:\n\n| Alias | Canonical Name | Market |\n|-------|----------------|--------|\n| `TWSE` | TWSE | Taiwan Stock Exchange |\n| `TPEX` | TWSE | Taipei Exchange (OTC) |\n\n资料来源：[PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n\n## Supported Exchanges by Market\n\n### Cryptocurrency Exchanges\n\n| Exchange | Symbol Format | Supported Tools |\n|----------|---------------|-----------------|\n| Binance | `SYMBOL` | top_gainers, top_losers, bollinger_scan, coin_analysis |\n| KuCoin | `SYMBOL` | All crypto tools |\n| Bybit | `SYMBOL` | All crypto tools |\n| MEXC | `SYMBOL` | All crypto tools (420+ pairs) |\n\n资料来源：[CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)\n\n### Stock Markets\n\n| Market | Exchange Code | Currency | Symbol Format |\n|--------|---------------|----------|---------------|\n| US Stocks (NASDAQ) | `NASDAQ` | USD | `NASDAQ:AAPL` |\n| US Stocks (NYSE) | `NYSE` | USD | `NYSE:TSLA` |\n| US ETFs (AMEX) | `AMEX` | USD | `AMEX:SPY` |\n| Taiwan (TWSE) | `TWSE` | TWD | `TWSE:2330` |\n| Taiwan (TPEX) | `TWSE` | TWD | `TWSE:0050` |\n| Egypt (EGX) | `EGX` | EGP/USD | `EGX:COMI` |\n| Turkey (BIST) | `BIST` | TRY | `BIST:THYAO` |\n\n资料来源：[src/tradingview_mcp/core/data/egx_sectors.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/data/egx_sectors.py)\n\n## Exchange-Specific Services\n\n### Screener Service\n\nThe `ScreenerService` class provides unified access to TradingView screener data across all supported exchanges:\n\n```python\nclass ScreenerService:\n def analyze_coin(self, symbol: str, exchange: str = \"KUCOIN\") -> dict:\n \"\"\"Analyze a coin/stock across multiple timeframes.\"\"\"\n \n def screen_stocks(self, exchange: str = \"NASDAQ\", \n signal: str = \"strong_buy\") -> list:\n \"\"\"Screen stocks by signal type on specified exchange.\"\"\"\n```\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n\n### Coinlist Service\n\nManages exchange-specific symbol lists for quick lookups:\n\n```python\nclass CoinlistService:\n def get_exchange_symbols(self, exchange: str) -> List[str]:\n \"\"\"Return available symbols for an exchange.\"\"\"\n \n def validate_symbol(self, symbol: str, exchange: str) -> bool:\n \"\"\"Check if symbol exists on exchange.\"\"\"\n```\n\n资料来源：[src/tradingview_mcp/core/services/coinlist.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/coinlist.py)\n\n### EGX Service\n\nSpecialized service for Egyptian Exchange with sector classification:\n\n```python\nclass EgxService:\n def get_egx_sectors(self) -> Dict[str, List[str]]:\n \"\"\"Return EGX symbols grouped by sector.\"\"\"\n \n def get_currency(self, symbol: str) -> str:\n \"\"\"Return 'USD' or 'EGP' for EGX symbol.\"\"\"\n```\n\n资料来源：[src/tradingview_mcp/core/services/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Validator\n participant ScreenerService\n participant TV_API\n \n Client->>Server: analyze_coin(\"2330\", \"TWSE\")\n Server->>Validator: sanitize_exchange(\"TWSE\")\n Validator-->>Server: \"twse\"\n \n Server->>Validator: get_tv_exchange_prefix(\"twse\")\n Validator-->>Server: \"TWSE\"\n \n Server->>Validator: is_stock_exchange(\"twse\")\n Validator-->>Server: True\n \n Server->>ScreenerService: analyze_coin(\"2330\", \"TWSE\")\n ScreenerService->>TV_API: GET /screener?exchange=TWSE&symbol=2330\n \n TV_API-->>ScreenerService: OHLCV data + indicators\n ScreenerService-->>Server: Analysis result\n Server-->>Client: Rich analysis object\n```\n\n## Exchange Validation Functions\n\n### sanitize_exchange()\n\nNormalizes exchange input and validates against supported exchanges:\n\n```python\ndef sanitize_exchange(ex: str, default: str = \"kucoin\") -> str:\n \"\"\"Sanitize and validate exchange name.\n \n Args:\n ex: Exchange name to sanitize\n default: Default exchange if validation fails\n \n Returns:\n Validated exchange name in lowercase\n \"\"\"\n if not ex:\n return default\n exs = ex.strip().lower()\n return exs if exs in EXCHANGE_SCREENER else default\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n### is_stock_exchange()\n\nDetermines if an exchange represents a traditional stock market:\n\n```python\ndef is_stock_exchange(exchange: str) -> bool:\n \"\"\"Return True if the exchange is a stock market (not crypto).\"\"\"\n return exchange.strip().lower() in STOCK_EXCHANGES\n```\n\nWhere `STOCK_EXCHANGES` contains:\n```python\nSTOCK_EXCHANGES = {\n \"nasdaq\", \"nyse\", \"amex\", \"nysearca\", \"pcx\",\n \"twse\", \"tpex\", \"egx\", \"bist\"\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n## Coinlist Directory Structure\n\nSymbol lists are stored in `src/tradingview_mcp/coinlist/`:\n\n```\nsrc/tradingview_mcp/coinlist/\n├── binance.txt\n├── kucoin.txt\n├── bybit.txt\n├── mexc.txt\n├── twse.txt\n├── tpex.txt\n├── egx.txt\n├── bist.txt\n└── ...\n```\n\nEach file contains one symbol per line for fast lookup without API calls.\n\n资料来源：[src/tradingview_mcp/coinlist](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/coinlist)\n\n## Adding New Exchange Support\n\n### Step 1: Update Validators\n\nAdd the exchange to the core registry in `validators.py`:\n\n```python\n# Add to EXCHANGE_SCREENER\nEXCHANGE_SCREENER.add(\"NEW_EXCHANGE\")\n\n# Add to STOCK_EXCHANGES or leave out for crypto\nSTOCK_EXCHANGES.add(\"NEW_EXCHANGE\")\n\n# Add prefix mapping if needed\n_EXCHANGE_TV_PREFIX[\"new_exchange\"] = \"NEW_EXCHANGE\"\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n### Step 2: Create Symbol List\n\nCreate `src/tradingview_mcp/coinlist/new_exchange.txt` with one symbol per line.\n\n### Step 3: Add Tests\n\nAdd unit tests in `tests/unit/test_exchange_fixes.py`:\n\n```python\ndef test_new_exchange_in_registry():\n assert \"new_exchange\" in EXCHANGE_SCREENER\n \ndef test_new_exchange_symbol_construction():\n prefix = get_tv_exchange_prefix(\"new_exchange\")\n assert prefix == \"NEW_EXCHANGE\"\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n### Step 4: Integration Test\n\n```python\nfrom tradingview_mcp.core.services.screener_service import ScreenerService\n\nservice = ScreenerService()\nresult = service.screen_stocks(exchange=\"NEW_EXCHANGE\")\n```\n\n## Testing\n\n### Unit Tests\n\nThe test suite covers exchange routing with 69 tests:\n\n```\n73 passed in 0.17s (69 new + 4 pre-existing)\n```\n\nKey test files:\n- `tests/unit/test_exchange_fixes.py` - Exchange routing tests (32 tests)\n- `tests/unit/test_exchange_aliases.py` - Alias resolution tests (37 tests)\n\n资料来源：[PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n\n### Test Coverage Areas\n\n| Test Category | Description |\n|---------------|-------------|\n| Alias Resolution | TWSE/TPEX → TWSE, NYSEARCA/PCX → AMEX |\n| Symbol Construction | Correct format for stock vs crypto |\n| Registry Integrity | All aliases in EXCHANGE_SCREENER and STOCK_EXCHANGES |\n| Regression | NYSE, NASDAQ, KUCOIN, BINANCE unchanged |\n\n## Configuration Options\n\n### Server Configuration\n\nExchange settings are configured at server startup:\n\n```python\n# In server.py\nexchange = sanitize_exchange(request.exchange or \"kucoin\")\ntv_exchange = get_tv_exchange_prefix(exchange)\nis_stock = is_stock_exchange(exchange)\n```\n\n### Tool Parameters\n\nMost analysis tools accept an `exchange` parameter:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `exchange` | string | `\"KUCOIN\"` | Exchange identifier |\n| `symbol` | string | required | Trading symbol |\n| `timeframe` | string | `\"1D\"` | Chart timeframe |\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| Symbol not found | Wrong exchange | Verify symbol exists on target exchange |\n| Empty results | Exchange not in screener | Check EXCHANGE_SCREENER |\n| Wrong prefix | Missing alias mapping | Add to `_EXCHANGE_TV_PREFIX` |\n\n### Debugging Steps\n\n1. Check if exchange is in `EXCHANGE_SCREENER`\n2. Verify symbol format matches exchange type\n3. Test symbol construction with `get_tv_exchange_prefix()`\n4. Validate against TradingView website directly\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: atilaahmettaner/tradingview-mcp\n\nSummary: Found 10 potential pitfall items; 2 are high/blocking. Highest priority: installation - 来源证据：Complement idea: \"What happened next?\" via Chart Library.\n\n## 1. installation · 来源证据：Complement idea: \"What happened next?\" via Chart Library\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Complement idea: \"What happened next?\" via Chart Library\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_b89762244f5e4c498064918f30cd560b | https://github.com/atilaahmettaner/tradingview-mcp/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. security_permissions · 涉及密钥、隐私或敏感领域\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: 项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。\n- User impact: 金融、交易、隐私和密钥场景必须比普通工具更保守。\n- Suggested check: 补敏感数据流、密钥存储和权限边界审查。\n- Guardrail action: 敏感领域或密钥场景必须保守推荐并要求人工复核。\n- Evidence: packet_text.keyword_scan | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | matched secret / private key / privacy / trading / finance keyword\n\n## 3. installation · 来源证据：[HELP] Installation Issue:\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[HELP] Installation Issue:\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_dcb256f998e14be785fa2c939b9dba56 | https://github.com/atilaahmettaner/tradingview-mcp/issues/24 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | host_targets=mcp_host, claude, cursor, chatgpt\n\n## 5. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | README/documentation is current enough for a first validation pass.\n\n## 6. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | last_activity_observed missing\n\n## 7. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n\n## 8. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n\n## 9. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | issue_or_pr_quality=unknown\n\n## 10. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | release_recency=unknown\n\n\n",
"markdown_key": "tradingview-mcp",
"pages": "draft",
"source_refs": [
{
"evidence_id": "art_0685d97fbc1a4f92849cb69a812ccd46",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/atilaahmettaner/tradingview-mcp#readme"
}
],
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "tradingview-mcp 说明书",
"toc": [
"https://github.com/atilaahmettaner/tradingview-mcp 项目说明书",
"目录",
"Project Overview",
"Introduction",
"Purpose and Scope",
"Architecture Overview",
"Core Features",
"Supported Exchanges",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "92490ec264993537441c4e85b158f72925e9334e",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"Dockerfile",
"README.md",
"docker-compose.yml",
"uv.lock",
"src/tradingview_mcp/server.py",
"src/tradingview_mcp/__init__.py",
"src/tradingview_mcp/core/portfolio.py",
"src/tradingview_mcp/core/types.py",
"src/tradingview_mcp/core/services/options_service.py",
"src/tradingview_mcp/core/services/proxy_manager.py",
"src/tradingview_mcp/core/services/yahoo_finance_service.py",
"src/tradingview_mcp/core/services/sentiment_service.py",
"src/tradingview_mcp/core/services/bitcoin_market_service.py",
"src/tradingview_mcp/core/services/screener_provider.py",
"src/tradingview_mcp/core/services/scanner_service.py",
"src/tradingview_mcp/core/services/extended_hours_service.py",
"src/tradingview_mcp/core/services/screener_service.py",
"src/tradingview_mcp/core/services/multi_agent_service.py",
"src/tradingview_mcp/core/services/backtest_service.py",
"src/tradingview_mcp/core/services/coinlist.py",
"src/tradingview_mcp/core/services/egx_service.py",
"src/tradingview_mcp/core/services/indicators_calc.py",
"src/tradingview_mcp/core/services/news_service.py",
"src/tradingview_mcp/core/services/indicators.py",
"src/tradingview_mcp/core/data/egx_indices.py",
"src/tradingview_mcp/core/data/__init__.py",
"src/tradingview_mcp/core/data/egx_sectors.py",
"src/tradingview_mcp/core/utils/validators.py"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# tradingview-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 tradingview-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`openclaw/SKILL.md` Claim：`clm_0006` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`openclaw/SKILL.md` Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.codex-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `pip install tradingview-mcp-server` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `git clone https://github.com/atilaahmettaner/tradingview-mcp` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `uv tool install --python 3.13 tradingview-mcp-server` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `curl -LsSf https://astral.sh/uv/install.sh | sh && source ~/.bashrc` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `uv tool install tradingview-mcp-server` 证据：`README.md` Claim：`clm_0011` supported 0.86\n- `curl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/SKILL.md \\` 证据：`README.md` Claim：`clm_0012` supported 0.86\n- `curl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/trading.py \\` 证据：`README.md` Claim：`clm_0013` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`openclaw/SKILL.md` Claim：`clm_0006` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`openclaw/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.codex-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.codex-plugin/plugin.json`, `openclaw/SKILL.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.codex-plugin/plugin.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.codex-plugin/plugin.json`, `openclaw/SKILL.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.codex-plugin/plugin.json`, `README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`OPENCLAW.md`, `README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0014` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.codex-plugin/plugin.json` Claim：`clm_0015` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0016` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`openclaw/SKILL.md` Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.codex-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：76\n- 重要文件覆盖：23/76\n- 证据索引条目：23\n- 角色 / Skill 条目：1\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 tradingview-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 tradingview-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 tradingview-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **tradingview-mcp**（skill）：AI Trading Intelligence — live prices, 30+ technical indicators, backtesting 6 strategies , walk-forward overfitting detection, trade logs, equity curves, Reddit sentiment, news, and multi-market screener. Supports stocks, crypto, ETFs, indices, Turkish BIST , and Egyptian EGX markets. 激活提示：当用户任务与“tradingview-mcp”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`openclaw/SKILL.md`\n\n## 证据索引\n\n- 共索引 23 条证据。\n\n- **📈 AI Trading Intelligence Framework — MCP Server**（documentation）：📈 AI Trading Intelligence Framework — MCP Server 证据：`README.md`\n- **🤝 Contributing to TradingView MCP Server**（documentation）：🤝 Contributing to TradingView MCP Server 证据：`CONTRIBUTING.md`\n- **TradingView MCP — AI Trading Intelligence**（skill_instruction）：TradingView MCP — AI Trading Intelligence 证据：`openclaw/SKILL.md`\n- **Plugin**（structured_config）：{ \"name\": \"tradingview-mcp\", \"version\": \"0.7.1\", \"description\": \"TradingView MCP server for market prices, screeners, sentiment, backtesting, and technical analysis.\", \"author\": { \"name\": \"TradingView MCP contributors\" }, \"homepage\": \"https://github.com/atilaahmettaner/tradingview-mcp\", \"repository\": \"https://github.com/atilaahmettaner/tradingview-mcp\", \"license\": \"MIT\", \"keywords\": \"mcp\", \"tradingview\", \"market-data\", \"technical-analysis\", \"backtesting\" , \"mcpServers\": \"./.codex-mcp.json\", \"interface\": { \"displayName\": \"TradingView MCP\", \"shortDescription\": \"Market data and technical-analysis MCP tools\", \"longDescription\": \"TradingView MCP server for market prices, screeners, sentiment, ba… 证据：`.codex-plugin/plugin.json`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Changelog**（documentation）：All notable changes to this project will be documented in this file. 证据：`CHANGELOG.md`\n- **📚 Usage Examples - TradingView MCP Server**（documentation）：📚 Usage Examples - TradingView MCP Server 证据：`EXAMPLES.md`\n- **🛠️ Installation Guide - TradingView MCP Server**（documentation）：🛠️ Installation Guide - TradingView MCP Server 证据：`INSTALLATION.md`\n- **TradingView MCP × OpenClaw Integration**（documentation）：TradingView MCP × OpenClaw Integration 证据：`OPENCLAW.md`\n- **Summary**（documentation）：Fixes two confirmed bugs where the exchange parameter was ignored or incorrectly resolved when querying US ETFs GDX, GLD, XLE and other non-crypto assets. 证据：`PR_BODY.md`\n- **Security Policy**（documentation）：Use this section to tell people about which versions of your project are currently being supported with security updates. 证据：`SECURITY.md`\n- **🐛 Bug Description**（documentation）：🐛 Bug Description A clear and concise description of what the bug is. 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **🚀 Feature Request**（documentation）：🎯 Is your feature request related to a problem? A clear and concise description of what the problem is. Ex. I'm always frustrated when ... 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **🆘 Installation/Setup Help**（documentation）：📋 What are you trying to do? - Install for the first time - Update to newer version - Fix broken installation - Configure Claude Desktop - Troubleshoot connection issues - Other: 证据：`.github/ISSUE_TEMPLATE/installation_help.md`\n- **.Codex Mcp**（structured_config）：{ \"mcpServers\": { \"tradingview\": { \"command\": \"uvx\", \"args\": \"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\" } } } 证据：`.codex-mcp.json`\n- **Logs**（source_file）：Python pycache / .py cod .egg-info/ dist/ build/ .eggs/ 证据：`.dockerignore`\n- **=============================================================**（source_file）：============================================================= tradingview-mcp — Local Environment Configuration ============================================================= 1. Copy this file: cp .env.example .env 2. Fill in your values below 3. .env is in .gitignore — it will NEVER be committed to git ============================================================= 证据：`.env.example`\n- **GitHub Sponsors configuration**（source_file）：GitHub Sponsors configuration This file enables the \"Sponsor\" button on the repository page. Edit to add your preferred funding platforms. 证据：`.github/FUNDING.yml`\n- **C extensions**（source_file）：.venv/ pycache / .pyc .DS Store .idea/ .env pycache / .py codz $py.class 证据：`.gitignore`\n- **---- Stage 1: Build ----**（source_file）：---- Stage 1: Build ---- FROM python:3.11-slim AS builder 证据：`Dockerfile`\n- **Optional: Add any future API keys or environment variables here**（source_file）：services: tradingview-mcp: build: . image: atilaahmet/tradingview-mcp:latest container name: tradingview-mcp ports: - \"8080:8000\" restart: unless-stopped environment: Optional: Add any future API keys or environment variables here - PORT=8000 - HOST=0.0.0.0 证据：`docker-compose.yml`\n- **!/usr/bin/env python3**（source_file）：!/usr/bin/env python3 \"\"\" CLI wrapper for tradingview-mcp — called by OpenClaw agent via bash. 证据：`openclaw/trading.py`\n- **Entry point now points to packaged module**（source_file）：project name = \"tradingview-mcp-server\" version = \"0.7.1\" description = \"Advanced AI Trading Intelligence Framework — MCP server with walk-forward backtesting, trade logs, equity curves, 1h timeframe, sentiment, Yahoo Finance, and 30+ technical analysis tools\" readme = \"README.md\" requires-python = \" =3.10\" authors = { name = \"Atila Ahmettaner\" } urls = { Repository = \"https://github.com/atilaahmettaner/tradingview-mcp\" } keywords = \"mcp\", \"tradingview\", \"crypto\", \"technical analysis\", \"screener\", \"backtesting\", \"walk-forward\", \"sentiment\", \"yahoo-finance\", \"trading\", \"agents\", \"algorithmic-trading\", \"equity-curve\" classifiers = \"Programming Language :: Python :: 3\", \"License :: OSI Approve… 证据：`pyproject.toml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `CONTRIBUTING.md`, `openclaw/SKILL.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `CONTRIBUTING.md`, `openclaw/SKILL.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\nThe following material strengthens the Repomix/AI Context Pack body. Human Manual is only a reading skeleton; pitfall logs become hard operating constraints for the host AI.\n\n## Human Manual Skeleton\n\nUsage rule: this is only a reading path and salience signal, not factual authority. Concrete facts must still come from repo evidence / Claim Graph.\n\nHard rules for the host AI:\n- Do not treat page titles, order, summaries, or importance as project facts.\n- When explaining the Human Manual skeleton, state that it is only a reading path / salience signal.\n- Capability, installation, compatibility, runtime status, and risk judgments must cite repo evidence, source paths, or Claim Graph.\n\n- **Project Overview**：importance `high`\n - source_paths: README.md, pyproject.toml\n- **Installation Guide**：importance `high`\n - source_paths: INSTALLATION.md, pyproject.toml, .env.example\n- **Quick Start Guide**：importance `high`\n - source_paths: README.md, EXAMPLES.md\n- **System Architecture**：importance `high`\n - source_paths: assets/architecture.png, src/tradingview_mcp/server.py, src/tradingview_mcp/__init__.py\n- **MCP Protocol Integration**：importance `high`\n - source_paths: src/tradingview_mcp/server.py, .codex-mcp.json, .codex-plugin/plugin.json\n- **Service Architecture**：importance `high`\n - source_paths: src/tradingview_mcp/core/services/backtest_service.py, src/tradingview_mcp/core/services/sentiment_service.py, src/tradingview_mcp/core/services/indicators.py, src/tradingview_mcp/core/services/scanner_service.py, src/tradingview_mcp/core/services/screener_service.py\n- **MCP Tools Reference**：importance `high`\n - source_paths: src/tradingview_mcp/server.py, src/tradingview_mcp/core/types.py, src/tradingview_mcp/core/services/indicators.py, src/tradingview_mcp/core/services/indicators_calc.py\n- **Backtesting Engine**：importance `high`\n - source_paths: src/tradingview_mcp/core/services/backtest_service.py, src/tradingview_mcp/core/portfolio.py\n\n## Repo Inspection Evidence\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `92490ec264993537441c4e85b158f72925e9334e`\n- inspected_files: `pyproject.toml`, `Dockerfile`, `README.md`, `docker-compose.yml`, `uv.lock`, `src/tradingview_mcp/server.py`, `src/tradingview_mcp/__init__.py`, `src/tradingview_mcp/core/portfolio.py`, `src/tradingview_mcp/core/types.py`, `src/tradingview_mcp/core/services/options_service.py`, `src/tradingview_mcp/core/services/proxy_manager.py`, `src/tradingview_mcp/core/services/yahoo_finance_service.py`, `src/tradingview_mcp/core/services/sentiment_service.py`, `src/tradingview_mcp/core/services/bitcoin_market_service.py`, `src/tradingview_mcp/core/services/screener_provider.py`, `src/tradingview_mcp/core/services/scanner_service.py`, `src/tradingview_mcp/core/services/extended_hours_service.py`, `src/tradingview_mcp/core/services/screener_service.py`, `src/tradingview_mcp/core/services/multi_agent_service.py`, `src/tradingview_mcp/core/services/backtest_service.py`\n\nHard rules for the host AI:\n- Without repo_clone_verified=true, do not claim the source code has been read.\n- Without repo_inspection_verified=true, do not turn README/docs/package observations into facts.\n- Without quick_start_verified=true, do not claim the Quick Start has been successfully run.\n\n## Doramagic Pitfall Constraints\n\nThese rules come from Doramagic discovery, validation, or compilation pitfalls. The host AI must treat them as operating constraints, not general background notes.\n\n### Constraint 1: 来源证据：Complement idea: \"What happened next?\" via Chart Library\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Complement idea: \"What happened next?\" via Chart Library\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b89762244f5e4c498064918f30cd560b | https://github.com/atilaahmettaner/tradingview-mcp/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 2: 涉及密钥、隐私或敏感领域\n\n- Trigger: 项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。\n- Host AI rule: 补敏感数据流、密钥存储和权限边界审查。\n- Why it matters: 金融、交易、隐私和密钥场景必须比普通工具更保守。\n- Evidence: packet_text.keyword_scan | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | matched secret / private key / privacy / trading / finance keyword\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 3: 来源证据：[HELP] Installation Issue:\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[HELP] Installation Issue:\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_dcb256f998e14be785fa2c939b9dba56 | https://github.com/atilaahmettaner/tradingview-mcp/issues/24 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 4: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | host_targets=mcp_host, claude, cursor, chatgpt\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 5: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | README/documentation is current enough for a first validation pass.\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 6: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | last_activity_observed missing\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 7: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 8: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 9: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | issue_or_pr_quality=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 10: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | release_recency=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n",
"summary": "Context and operating boundaries for host AI agents.",
"title": "AI Context Pack"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card\n\nProject: atilaahmettaner/tradingview-mcp\n\n## Doramagic Trial Decision\n\nCurrent decision: it can enter pre-publication recommendation checks. First use should still start with least privilege, a temporary directory, and reversible configuration.\n\n## What The User Can Do Now\n\n- Read the Human Manual first to understand the project purpose and main workflows.\n- Use Prompt Preview for pre-install exploration; it validates interaction shape, not real execution.\n- Run official Quick Start commands only inside an isolated environment, not a primary setup.\n\n## Do Not Do Yet\n\n- Do not treat Prompt Preview as a real project execution result.\n- Do not treat metadata-only validation as sandbox installation validation.\n- Do not describe unverified capabilities as supported, working, or safe to install.\n- Do not provide production data, private files, real secrets, or primary host configuration on first trial.\n\n## Pre-Install Checklist\n\n- Host AI match: mcp_host, claude, cursor, chatgpt\n- Official installation entry status: official entry point found\n- Isolated temporary directory, temporary host, or container validation: required\n- Configuration rollback path: required\n- API keys, network access, file access, or host configuration changes: treat as high risk until confirmed\n- Installation command, actual output, and failure logs: must be recorded\n\n## Current Blockers\n\n- No blockers.\n\n## Project-Specific Pitfalls\n\n- 来源证据：Complement idea: \"What happened next?\" via Chart Library (high): 可能增加新用户试用和生产接入成本。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 涉及密钥、隐私或敏感领域 (high): 金融、交易、隐私和密钥场景必须比普通工具更保守。 Suggested check: 补敏感数据流、密钥存储和权限边界审查。\n- 来源证据：[HELP] Installation Issue: (medium): 可能增加新用户试用和生产接入成本。 Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 可能修改宿主 AI 配置 (medium): 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设 (medium): 假设不成立时，用户拿不到承诺的能力。 Suggested check: 将假设转成下游验证清单。\n\n## Risk And Permission Notes\n\n- no_demo: medium\n\n## Evidence Gaps\n\n- No structured evidence gaps are currently visible.\n",
"summary": "Installation, permission, validation, and pre-recommendation risks.",
"title": "Boundary & Risk Card"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/atilaahmettaner/tradingview-mcp 项目说明书\n\n生成时间：2026-05-15 15:23:45 UTC\n\n## 目录\n\n- [Project Overview](#overview)\n- [Installation Guide](#installation)\n- [Quick Start Guide](#quick-start)\n- [System Architecture](#system-architecture)\n- [MCP Protocol Integration](#mcp-protocol)\n- [Service Architecture](#service-architecture)\n- [MCP Tools Reference](#mcp-tools-reference)\n- [Backtesting Engine](#backtesting-engine)\n- [Sentiment Analysis](#sentiment-analysis)\n- [Multi-Exchange Integration](#exchange-integrations)\n\n\n\n## Project Overview\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [MCP Tools Reference](#mcp-tools-reference), [Installation Guide](#installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n- [OPENCLAW.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/OPENCLAW.md)\n- [src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n- [pyproject.toml](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/pyproject.toml)\n \n\n# Project Overview\n\n## Introduction\n\n**TradingView-MCP** is an open-source Model Context Protocol (MCP) server that bridges AI assistants (such as Claude Desktop, Codex, and OpenClaw) with TradingView's extensive market data, technical analysis tools, and financial data services.\n\nThe project enables AI agents to perform real-time market analysis, technical indicator calculations, stock screening, backtesting, and sentiment analysis through natural language interactions. 资料来源：[README.md:1]()\n\n## Purpose and Scope\n\nThe primary objectives of TradingView-MCP are:\n\n| Objective | Description |\n|-----------|-------------|\n| **Market Data Access** | Provide real-time and historical market data from multiple exchanges |\n| **Technical Analysis** | Calculate 30+ technical indicators with BUY/SELL/HOLD signals |\n| **Multi-Exchange Support** | Cover crypto (Binance, KuCoin, Bybit), US stocks (NASDAQ, NYSE, AMEX), and regional markets |\n| **Backtesting Engine** | Test 6 trading strategies with institutional-grade metrics |\n| **Sentiment Analysis** | Aggregate Reddit and news sentiment for informed decision-making |\n\n资料来源：[README.md:1-20]()\n\n## Architecture Overview\n\nTradingView-MCP follows a modular architecture with clear separation of concerns:\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n A[Claude Desktop] --> B[MCP Protocol]\n C[Codex] --> B\n D[OpenClaw] --> B\n E[Telegram/WhatsApp] --> F[OpenClaw Agent]\n F --> B\n end\n \n subgraph \"Server Layer\"\n B --> G[server.py]\n G --> H[Core Services]\n G --> I[Technical Indicators]\n G --> J[Utilities]\n end\n \n subgraph \"Data Sources\"\n H --> K[TradingView Screener API]\n H --> L[Yahoo Finance API]\n H --> M[Reddit API]\n H --> N[News RSS Feeds]\n end\n \n subgraph \"Exchanges\"\n K --> O[Binance]\n K --> P[KuCoin]\n K --> Q[NASDAQ/NYSE]\n K --> R[EGX/BIST]\n end\n```\n\n### Directory Structure\n\n```\ntradingview-mcp/\n├── src/tradingview_mcp/\n│ ├── server.py # Main MCP server entry point\n│ ├── core/\n│ │ ├── services/ # Market data services\n│ │ ├── utils/ # Utility functions (validators.py)\n│ │ └── indicators/ # Technical indicators\n│ └── coinlist/ # Exchange symbol lists\n├── tests/\n│ ├── unit/ # Unit tests\n│ └── integration/ # Integration tests\n├── openclaw/ # OpenClaw integration files\n└── pyproject.toml # Project configuration\n```\n\n资料来源：[CONTRIBUTING.md:40-55]()\n\n## Core Features\n\n### 1. Technical Analysis Engine\n\nThe server provides comprehensive technical analysis with 30+ indicators:\n\n| Category | Indicators |\n|----------|------------|\n| **Momentum** | RSI, Stochastic, CCI, Williams %R |\n| **Trend** | MACD, EMA Cross, Supertrend, ADX |\n| **Volatility** | Bollinger Bands, ATR, Standard Deviation |\n| **Volume** | OBV, Volume Profile, A/D Line |\n| **Patterns** | 15 Candlestick Pattern Detection |\n\n资料来源：[README.md:45-60]()\n\n### 2. Backtesting System\n\nThe backtesting engine supports 6 trading strategies:\n\n```mermaid\ngraph LR\n A[Strategy Selection] --> B[rsi]\n A --> C[bollinger]\n A --> D[macd]\n A --> E[ema_cross]\n A --> F[supertrend]\n A --> G[donchian]\n \n B --> H[Performance Metrics]\n C --> H\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I[Win Rate]\n H --> J[Sharpe Ratio]\n H --> K[Calmar Ratio]\n H --> L[Max Drawdown]\n H --> M[Profit Factor]\n```\n\n**Available Strategies:**\n\n| Strategy | Type | Description |\n|----------|------|-------------|\n| `rsi` | Mean Reversion | RSI oversold/overbought signals |\n| `bollinger` | Mean Reversion | Bollinger Band price band breakout |\n| `macd` | Trend Following | MACD golden/death cross |\n| `ema_cross` | Trend Following | EMA 20/50 Golden/Death Cross |\n| `supertrend` | Trend Following | ATR-based Supertrend |\n| `donchian` | Breakout | Donchian Channel breakout (Turtle style) |\n\n资料来源：[README.md:65-85]()\n\n### 3. Yahoo Finance Integration (v0.6.0)\n\nReal-time price data integration provides:\n\n| Tool | Function |\n|------|----------|\n| `yahoo_price` | Real-time quote with price, change %, 52w high/low, market state |\n| `market_snapshot` | Global overview: S&P500, NASDAQ, BTC, EUR/USD, etc. |\n| `get_prices_bulk` | Multi-symbol price lookup |\n\n资料来源：[README.md:95-105]()\n\n## Supported Exchanges\n\nTradingView-MCP supports multiple exchange types through the `EXCHANGE_SCREENER` mapping:\n\n```mermaid\ngraph TD\n subgraph \"Crypto Exchanges\"\n A[BINANCE]\n B[KUCOIN]\n C[BYBIT+]\n D[MEXC]\n end\n \n subgraph \"US Markets\"\n E[NASDAQ]\n F[NYSE]\n G[AMEX]\n H[NYSEARCA]\n I[PCX]\n end\n \n subgraph \"Regional Markets\"\n J[EGX - Egypt]\n K[BIST - Turkey]\n L[TWSE - Taiwan]\n M[TPEX - Taiwan]\n end\n```\n\n### Exchange Configuration\n\n| Exchange | Screener Type | Symbol Format |\n|----------|---------------|---------------|\n| `BINANCE` | `crypto` | `BINANCE:BTCUSDT` |\n| `KUCOIN` | `crypto` | `KUCOIN:BTCUSDT` |\n| `NASDAQ` | `america` | `NASDAQ:AAPL` |\n| `NYSE` | `america` | `NYSE:TSLA` |\n| `AMEX` | `america` | `AMEX:SPY` |\n| `NYSEARCA` | `america` | `AMEX:GLD` |\n| `EGX` | `egypt` | `EGX:COMI` |\n| `TWSE` | `Taiwan` | `TWSE:2330` |\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:80-100]()\n\n### Stock Exchange Classification\n\nThe system classifies exchanges using `STOCK_EXCHANGES`:\n\n```python\nSTOCK_EXCHANGES = frozenset({\n \"nyse\", \"nasdaq\", \"amex\", \"nysearca\", \"pcx\",\n \"twse\", \"tpex\", \"egx\"\n})\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:60-65]()\n\n## Available Tools\n\n### Market Data Tools\n\n| Tool | Description |\n|------|-------------|\n| `top_gainers` | Find top gaining assets |\n| `top_losers` | Find top losing assets |\n| `screen_stocks` | Multi-exchange screener with 20+ filter criteria |\n| `scan_by_signal` | Scan by signal type (oversold, trending, breakout) |\n| `coin_analysis` | Comprehensive coin/symbol analysis |\n\n### Technical Analysis Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_technical_analysis` | Full TA: RSI, MACD, Bollinger, 23 indicators |\n| `get_multiple_analysis` | Bulk TA for multiple symbols |\n| `get_bollinger_band_analysis` | Proprietary ±3 BB rating system |\n| `get_stock_decision` | 3-layer decision engine |\n| `get_candlestick_patterns` | 15 candlestick pattern detector |\n| `get_multi_timeframe_analysis` | Weekly→Daily→4H→1H→15m alignment |\n\n### Backtesting Tools\n\n| Tool | Description |\n|------|-------------|\n| `backtest_strategy` | Backtest 1 of 6 strategies with Sharpe, Calmar, Expectancy |\n| `compare_strategies` | Run all 6 strategies and rank by performance |\n\n### Sentiment & News Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_reddit_sentiment` | Reddit sentiment analysis |\n| `get_live_news` | Live financial news via RSS |\n\n资料来源：[README.md:30-70]()\n\n## Installation Methods\n\n### Method 1: UV Package Manager (Recommended)\n\n```bash\n# Install uv\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install from PyPI\nuv tool install tradingview-mcp-server\n```\n\n### Method 2: Claude Desktop Configuration\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:25-40]()\n\n### Method 3: Git Clone (Local Development)\n\n```bash\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\nuv sync\nuv run python src/tradingview_mcp/server.py\n```\n\n资料来源：[CONTRIBUTING.md:15-25]()\n\n## Configuration Reference\n\n### Claude Desktop Config (Windows)\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\\\\src\\\\tradingview_mcp\\\\server.py\"],\n \"cwd\": \"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\"\n }\n }\n}\n```\n\n### Python Version Compatibility\n\n| Python Version | Status | Notes |\n|----------------|--------|-------|\n| 3.13 | ✅ Recommended | Prebuilt pandas wheels available |\n| 3.14 | ⚠️ Warning | May timeout on first launch due to source build |\n\nFor Python 3.14 on Windows, pin to Python 3.13:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\"--python\", \"3.13\", \"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:45-55]()\n\n## OpenClaw Integration\n\nTradingView-MCP can be accessed via Telegram, WhatsApp, and Discord using OpenClaw:\n\n```mermaid\ngraph LR\n A[Telegram User] --> B[OpenClaw Gateway]\n B --> C[AI Agent]\n C --> D[trading.py Wrapper]\n D --> E[tradingview-mcp]\n E --> F[Yahoo Finance API]\n```\n\n资料来源：[OPENCLAW.md:1-20]()\n\n## Development Guidelines\n\n### Code Style\n\n| Aspect | Standard |\n|--------|----------|\n| Style | PEP 8 with customizations |\n| Linting | Ruff |\n| Type Hints | Required for all functions |\n| Docstrings | Required for public functions/classes |\n\n### Testing Standards\n\n| Test Type | Coverage Target | Framework |\n|-----------|-----------------|------------|\n| Unit Tests | Core functions | pytest |\n| Integration Tests | Real API calls | pytest |\n| Linting | All code | ruff |\n| Type Checking | All code | mypy |\n\n资料来源：[CONTRIBUTING.md:70-95]()\n\n## Project Roadmap\n\n```mermaid\ngantt\n title TradingView-MCP Roadmap\n dateFormat YYYY-MM\n section Completed\n Technical Analysis (30+ indicators) :done, 2024-01, 2024-06\n Multi-exchange support :done, 2024-02, 2024-08\n Yahoo Finance integration :done, 2024-06, 2024-09\n Backtesting engine :done, 2024-07, 2024-12\n section In Progress\n Walk-forward backtesting :active, 2025-01, 2025-06\n section Planned\n Twitter/X sentiment :todo, 2025-03, 2025-06\n Paper trading simulation :todo, 2025-04, 2025-09\n Managed cloud hosting :todo, 2025-06, 2025-12\n```\n\n资料来源：[README.md:150-165]()\n\n## License\n\nTradingView-MCP is released under the **MIT License**. See [LICENSE](LICENSE) for details.\n\n资料来源：[README.md:170-172]()\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n- [OPENCLAW.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/openclaw/OPENCLAW.md)\n- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n- [src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n \n\n# Installation Guide\n\nThis guide covers all supported methods for installing and configuring the TradingView MCP server. The server acts as a bridge between AI agents (Claude Desktop, Codex, OpenClaw) and TradingView market data, enabling real-time technical analysis, screening, and sentiment analysis through natural language commands.\n\n## Prerequisites\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| Python | 3.8+ (3.10+ recommended) | Required for all installation methods |\n| UV Package Manager | Latest | Fast Python package manager for dependency management |\n| MCP Client | Claude Desktop, Codex, or OpenClaw | The AI agent interface |\n| Internet Connection | Required | For TradingView data access |\n\n资料来源：[INSTALLATION.md:1-5]()\n\n## Installation Methods\n\n### Method 1: UV Package Manager (Recommended)\n\nUV is a fast Python package manager that handles all dependencies automatically. This is the recommended installation method for most users.\n\n#### Step 1: Install UV\n\n**macOS/Linux:**\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\n```\n\n**Windows:**\n```powershell\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\nVerify installation:\n```bash\nuv --version\n```\n\n资料来源：[INSTALLATION.md:15-30]()\n\n#### Step 2: Clone the Repository\n\n```bash\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n```\n\n#### Step 3: Install Dependencies\n\n```bash\nuv sync\n```\n\n资料来源：[INSTALLATION.md:35-40]()\n\n### Method 2: Python Virtual Environment\n\nFor users who prefer traditional Python environments without UV:\n\n**Windows:**\n```powershell\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\npython -m venv .venv\n.\\.venv\\Scripts\\activate\npip install -e .\n```\n\n**macOS/Linux:**\n```bash\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n```\n\n资料来源：[INSTALLATION.md:120-140]()\n\n### Method 3: PyPI Installation (uvx)\n\nFor quick testing without cloning:\n\n```bash\nuv tool install --python 3.13 tradingview-mcp-server\n```\n\n资料来源：[README.md:45-50]()\n\n## MCP Client Configuration\n\n### Claude Desktop\n\n#### Locate Configuration File\n\n| OS | Path |\n|----|------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n资料来源：[INSTALLATION.md:55-65]()\n\n#### Add Server Configuration\n\nOpen the config file and add the following:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp\": {\n \"command\": \"uv\",\n \"args\": [\n \"tool\",\n \"run\",\n \"--from\",\n \"git+https://github.com/atilaahmettaner/tradingview-mcp.git\",\n \"tradingview-mcp\"\n ]\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:70-85]()\n\n**Windows (Direct Python Path):**\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\\\\src\\\\tradingview_mcp\\\\server.py\"],\n \"cwd\": \"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\"\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:18-25]()\n\n**macOS/Linux (Using UV):**\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"src/tradingview_mcp/server.py\"],\n \"cwd\": \"/path/to/your/tradingview-mcp\"\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:105-112]()\n\n### Codex Plugin\n\nThe repository includes MCP-only Codex plugin metadata:\n\n- `.codex-plugin/plugin.json`\n- `.codex-mcp.json`\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\n \"--from\",\n \"tradingview-mcp-server\",\n \"tradingview-mcp\"\n ]\n }\n }\n}\n```\n\n资料来源：[README.md:65-78]()\n\nAfter enabling the plugin in Codex, restart Codex so the MCP server is loaded in the next session.\n\n### OpenClaw Integration\n\nOpenClaw routes messages from Telegram, WhatsApp, Discord, and 20+ messaging platforms to an AI agent that calls tradingview-mcp functions.\n\n```mermaid\ngraph LR\n A[Telegram/WhatsApp/Discord] --> B[OpenClaw Gateway]\n B --> C[AI Agent]\n C --> D[trading.py Wrapper]\n D --> E[tradingview-mcp]\n E --> F[Yahoo Finance]\n```\n\n资料来源：[OPENCLAW.md:1-15]()\n\n#### Step 1: Install Dependencies\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\nuv tool install tradingview-mcp-server\n```\n\n资料来源：[OPENCLAW.md:8-12]()\n\n#### Step 2: Configure Channel\n\nCreate or edit `~/.openclaw/openclaw.json`:\n\n```json5\n{\n channels: {\n telegram: {\n botToken: \"YOUR_BOT_TOKEN_HERE\",\n },\n },\n}\n```\n\n资料来源：[OPENCLAW.md:15-22]()\n\n#### Step 3: Install Skill and Tool\n\n```bash\nmkdir -p ~/.agents/skills/tradingview-mcp ~/.openclaw/tools\n\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/SKILL.md \\\n -o ~/.agents/skills/tradingview-mcp/SKILL.md\n\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/trading.py \\\n -o ~/.openclaw/tools/trading.py\nchmod +x ~/.openclaw/tools/trading.py\n```\n\n资料来源：[OPENCLAW.md:25-33]()\n\n#### Step 4: Restart OpenClaw\n\n```bash\nopenclaw gateway install\nsystemctl --user start openclaw-gateway.service\nopenclaw doctor\n```\n\n资料来源：[OPENCLAW.md:55-58]()\n\n## Development Setup\n\nFor contributors who want to modify the code or run locally:\n\n### 1. Clone and Setup\n\n```bash\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n```\n\n### 2. Install Development Dependencies\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nuv sync\nuv sync --dev\n```\n\n资料来源：[CONTRIBUTING.md:5-12]()\n\n### 3. Run Tests\n\n| Command | Purpose |\n|---------|---------|\n| `uv run pytest` | Run the test suite |\n| `uv run ruff check` | Run linting |\n| `uv run mypy src/` | Run type checking |\n\n资料来源：[CONTRIBUTING.md:15-20]()\n\n### 4. Test Locally\n\n```bash\n# Test the server locally\nuv run python src/tradingview_mcp/server.py\n\n# Test with MCP Inspector\nuv run mcp dev src/tradingview_mcp/server.py\n```\n\n资料来源：[CONTRIBUTING.md:23-28]()\n\n## Directory Structure\n\nThe project follows a modular architecture:\n\n```\ntradingview-mcp/\n├── src/tradingview_mcp/\n│ ├── server.py # Main MCP server\n│ ├── core/ # Core business logic\n│ │ ├── services/ # Market data services\n│ │ ├── utils/ # Utility functions\n│ │ └── indicators/ # Technical indicators\n│ └── coinlist/ # Exchange symbol lists\n├── tests/\n│ └── unit/ # Unit tests\n├── .codex-plugin/ # Codex plugin metadata\n└── pyproject.toml # Project configuration\n```\n\n资料来源：[CONTRIBUTING.md:35-48]()\n\n## Verification\n\nAfter installation, verify the setup by asking your AI agent:\n\n```\n\"Can you show me the available TradingView tools?\"\n```\n\nExpected tools include:\n\n| Category | Tools |\n|----------|-------|\n| Market Data | `top_gainers`, `top_losers`, `yahoo_price`, `market_snapshot` |\n| Technical Analysis | `bollinger_scan`, `consecutive_candles_scan`, `technical_analysis` |\n| Sentiment | `coin_analysis`, `reddit_sentiment` |\n| Backtesting | `backtest`, `compare_strategies` |\n\n资料来源：[README.md:80-90]()\n\n## Troubleshooting\n\n### Windows: MCP Timeout on First Launch\n\nSymptom: `MCP error -32001: Request timed out` in Claude Desktop logs shortly after adding config.\n\nSolution: Pre-install the package before launching Claude Desktop:\n\n```bash\nuv tool install --python 3.13 tradingview-mcp-server\n```\n\nThis warms the cache so the server starts instantly.\n\n资料来源：[README.md:45-55]()\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| UV not found | Add UV to PATH or restart terminal |\n| Config file not found | Create the directory and file if missing |\n| Server won't start | Check Python version (3.8+ required) |\n| Timeout errors | Pre-install with `uv tool install` |\n\n## Next Steps\n\nAfter successful installation:\n\n1. Explore available tools by asking your AI agent\n2. Try basic queries like \"Show me top gainers on Binance\"\n3. Run development tests with `uv run pytest`\n4. Review [CONTRIBUTING.md](CONTRIBUTING.md) for code standards\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [MCP Tools Reference](#mcp-tools-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n- [OPENCLAW.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/OPENCLAW.md)\n- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n- [EXAMPLES.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/EXAMPLES.md)\n \n\n# Quick Start Guide\n\nThis guide provides step-by-step instructions for setting up and running the `tradingview-mcp` server, enabling AI assistants like Claude Desktop, Codex, and OpenClaw to perform real-time market analysis, technical indicators, and stock screening.\n\n## Overview\n\nThe **tradingview-mcp** project is a Model Context Protocol (MCP) server that bridges AI assistants with TradingView's market data, Yahoo Finance real-time prices, and multi-exchange screening capabilities. 资料来源：[README.md:1]()\n\nThe Quick Start process involves three main stages:\n\n```mermaid\ngraph TD\n A[Install Dependencies] --> B[Configure AI Client]\n B --> C[Verify Installation]\n A --> D[Clone Repository]\n D --> B\n C --> E[Available Tools Ready]\n```\n\n## Prerequisites\n\nBefore beginning, ensure your system meets these requirements:\n\n| Requirement | Minimum | Recommended |\n|-------------|---------|-------------|\n| Python | 3.12+ | 3.13 |\n| UV Package Manager | Latest | Latest |\n| Operating System | Windows/macOS/Linux | Ubuntu 24.04 |\n| Network | Internet for market data | Stable internet connection |\n\n资料来源：[CONTRIBUTING.md:1-5]()\n\n## Installation Methods\n\nThe project supports multiple installation approaches depending on your use case.\n\n### Method 1: Quick Start with uvx\n\nThe fastest way to get started is using `uvx` which runs the package directly without manual installation:\n\n```bash\nuvx --from tradingview-mcp-server tradingview-mcp\n```\n\nThis method requires no local setup and pulls the latest version from PyPI automatically. 资料来源：[README.md:45-48]()\n\n### Method 2: Claude Desktop Configuration\n\nFor Claude Desktop integration, configure the MCP server in your client configuration file.\n\n#### Locating Configuration File\n\n| Platform | Path |\n|----------|------|\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n资料来源：[INSTALLATION.md:15-20]()\n\n#### Windows Configuration\n\nAdd the following to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\\\\src\\\\tradingview_mcp\\\\server.py\"],\n \"cwd\": \"C:\\\\Users\\\\YOUR_USERNAME\\\\tradingview-mcp\"\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:24-32]()\n\n#### macOS/Linux Configuration\n\nFor Unix-based systems, use `uv` with the run command:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"src/tradingview_mcp/server.py\"],\n \"cwd\": \"/path/to/your/tradingview-mcp\"\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:55-63]()\n\n#### Linux Full Path\n\nOn Linux systems, use the full path to uvx:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"/home/YOUR_USERNAME/.local/bin/uvx\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:60-66]()\n\n### Method 3: Local Development Setup\n\nFor development or customization, clone and run from source.\n\n#### Step 1: Clone Repository\n\n```bash\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n```\n\n#### Step 2: Install Dependencies\n\n```bash\n# Install UV if not present\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\n\n# Sync project dependencies\nuv sync\n\n# Install development dependencies\nuv sync --dev\n```\n\n#### Step 3: Verify Installation\n\n```bash\n# Test the server locally\nuv run python src/tradingview_mcp/server.py\n\n# Run the test suite\nuv run pytest\n\n# Run linting checks\nuv run ruff check\n\n# Run type checking\nuv run mypy src/\n```\n\n资料来源：[CONTRIBUTING.md:5-20]()\n\n### Method 4: Pre-installed Tool\n\nFor faster subsequent launches, pre-install the package:\n\n```bash\n# Run once before launching Claude Desktop\nuv tool install --python 3.13 tradingview-mcp-server\n```\n\nThis warms the cache so Claude Desktop starts instantly without downloading dependencies. 资料来源：[README.md:79-83]()\n\n## Python Version Considerations\n\nWhen using `uvx`, the default Python version may cause issues on Windows with Python 3.14 due to missing prebuilt `pandas` wheels.\n\n### Windows Timeout Fix\n\nIf you encounter `MCP error -32001: Request timed out` on first launch, pin Python 3.13:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\"--python\", \"3.13\", \"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:96-107]()\n\n## OpenClaw Integration\n\nFor connecting to Telegram, WhatsApp, or Discord, use the OpenClaw gateway.\n\n### Step 1: Install OpenClaw Dependencies\n\n```bash\n# Install uv if needed\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\n\n# Install tradingview-mcp-server as tool\nuv tool install tradingview-mcp-server\n```\n\n### Step 2: Configure Messaging Channel\n\nCreate or edit `~/.openclaw/openclaw.json`:\n\n```json5\n{\n channels: {\n telegram: {\n botToken: \"YOUR_BOT_TOKEN_HERE\",\n },\n },\n}\n```\n\n### Step 3: Install TradingView Skill\n\n```bash\nmkdir -p ~/.agents/skills/tradingview-mcp ~/.openclaw/tools\n\n# Download skill instructions\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/SKILL.md \\\n -o ~/.agents/skills/tradingview-mcp/SKILL.md\n\n# Download trading wrapper\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/trading.py \\\n -o ~/.openclaw/tools/trading.py\nchmod +x ~/.openclaw/tools/trading.py\n```\n\n### Step 4: Configure AI Model\n\nSet up OpenRouter with Gemini 3 Flash for optimal performance:\n\n```bash\nopenclaw config set acp.defaultAgent main\nopenclaw config set gateway.mode local\n```\n\n资料来源：[OPENCLAW.md:1-50]()\n\n## Verification and Testing\n\n### Test Claude Desktop\n\nAfter adding configuration and restarting Claude Desktop:\n\n```\n\"Can you show me the available TradingView tools?\"\n```\n\nExpected response includes tools like `top_gainers`, `top_losers`, `bollinger_scan`, `coin_analysis`, and `consecutive_candles_scan`. 资料来源：[INSTALLATION.md:68-74]()\n\n### Test OpenClaw Bot\n\nSend these commands to your Telegram bot:\n\n```\nmarket snapshot\nbacktest RSI strategy for AAPL, 1 year\ncompare all strategies for BTC-USD\n```\n\n### Available Tool Categories\n\n| Category | Tools |\n|----------|-------|\n| Market Data | `yahoo_price`, `market_snapshot`, `get_prices_bulk` |\n| Technical Analysis | `get_technical_analysis`, `get_bollinger_band_analysis`, `get_stock_decision` |\n| Screening | `screen_stocks`, `scan_by_signal`, `top_gainers`, `top_losers` |\n| Backtesting | `backtest_strategy`, `compare_strategies` |\n\n资料来源：[OPENCLAW.md:55-68]()\n\n## Example Usage\n\n### Market Snapshot\n\n```\nYou: \"Give me a full market snapshot right now\"\nAI: [market_snapshot] →\nBUY (Technical STRONG BUY + Bullish Reddit + Positive news)\n```\n\n### Strategy Backtest\n\n```\nYou: \"Compare all strategies on BTC-USD for 2 years\"\nAI: \n→ #1 Supertrend: +31.5% | Sharpe: 2.1 | WR: 62%\n→ #2 Bollinger: +18.3% | Sharpe: 3.4 | WR: 75%\n→ Buy & Hold: -5.0%\n```\n\n### Stock Screening\n\n```\nYou: \"Show me NASDAQ tech stocks that are oversold\"\nAI: [scan_by_signal(exchange=\"NASDAQ\", signal=\"oversold\")]\n```\n\n资料来源：[EXAMPLES.md:1-25]()\n\n## Troubleshooting\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| `MCP error -32001` on Windows | Python 3.14 has no prebuilt pandas | Pin to Python 3.13 in config |\n| Server won't start | Missing dependencies | Run `uv sync` in project directory |\n| Tools not showing | Claude Desktop not restarted | Fully quit and relaunch |\n| OpenClaw gateway won't start | `gateway.mode` missing | Set `openclaw config set gateway.mode local` |\n\n资料来源：[README.md:108-125]()\n\n## Next Steps\n\nAfter successful installation:\n\n1. Explore the [technical analysis tools](README.md#-technical-analysis-core) for indicator-based analysis\n2. Try the [backtesting engine](README.md#-backtesting-engine-new-in-v060) to test trading strategies\n3. Configure [multi-exchange screening](README.md#-multi-exchange-support) for global market coverage\n4. Review the [contribution guidelines](CONTRIBUTING.md) if you want to extend functionality\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[MCP Protocol Integration](#mcp-protocol), [Service Architecture](#service-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [assets/architecture.png](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/assets/architecture.png)\n- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n- [src/tradingview_mcp/__init__.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/__init__.py)\n- [src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n \n\n# System Architecture\n\n## Overview\n\nThe `tradingview-mcp` project is a Model Context Protocol (MCP) server that provides AI assistants (such as Claude Desktop) with real-time access to financial market data, technical analysis, and backtesting capabilities. It acts as a bridge between AI agents and TradingView's data infrastructure.\n\n**资料来源：** [README.md](README.md)\n\nThe server follows a layered architecture pattern with clear separation between the MCP protocol layer, business logic services, and data providers.\n\n---\n\n## High-Level Architecture\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n CLAUDE[\"Claude Desktop / AI Agent\"]\n TELEGRAM[\"Telegram Bot (OpenClaw)\"]\n CODEX[\"Codex Plugin\"]\n end\n \n subgraph \"MCP Protocol Layer\"\n SERVER[\"server.py
(MCP Server Entry)\"]\n end\n \n subgraph \"Service Layer\"\n TA[\"Technical Analysis
Indicators\"]\n SCREENER[\"Screener Service\"]\n BACKTEST[\"Backtesting Engine\"]\n YAHOO[\"Yahoo Finance API\"]\n SENTIMENT[\"Reddit Sentiment\"]\n end\n \n subgraph \"Data Provider Layer\"\n TV[\"TradingView Screener\"]\n YF[\"Yahoo Finance\"]\n RSS[\"Live News RSS\"]\n end\n \n CLAUDE --> SERVER\n TELEGRAM --> SERVER\n CODEX --> SERVER\n \n SERVER --> TA\n SERVER --> SCREENER\n SERVER --> BACKTEST\n \n SCREENER --> TV\n TA --> TV\n TA --> YF\n BACKTEST --> YAHOO\n```\n\n---\n\n## Directory Structure\n\nThe codebase is organized following Python best practices with a modular structure:\n\n```\ntradingview-mcp/\n├── src/tradingview_mcp/\n│ ├── server.py # Main MCP server entry point\n│ ├── __init__.py # Package initialization\n│ ├── core/\n│ │ ├── services/ # Market data services\n│ │ │ ├── screener_service.py # Stock/coin screening\n│ │ │ └── ...\n│ │ ├── utils/ # Utility functions\n│ │ │ ├── validators.py # Input validation & exchange mapping\n│ │ │ └── ...\n│ │ └── indicators/ # Technical indicators\n│ │ └── ... # RSI, MACD, Bollinger, etc.\n│ └── coinlist/ # Exchange symbol lists\n│ ├── binance.txt\n│ ├── kucoin.txt\n│ └── ...\n├── tests/\n│ └── unit/\n├── assets/\n│ └── architecture.png\n└── pyproject.toml\n```\n\n**资料来源：** [CONTRIBUTING.md - Code Organization](CONTRIBUTING.md)\n\n---\n\n## Core Components\n\n### MCP Server (`server.py`)\n\nThe main entry point that registers all tools as MCP resources and handlers. It exposes 30+ tools including:\n\n| Category | Tools |\n|----------|-------|\n| Backtesting | `backtest_strategy`, `compare_strategies` |\n| Technical Analysis | `get_technical_analysis`, `get_bollinger_band_analysis` |\n| Market Data | `top_gainers`, `top_losers`, `yahoo_price` |\n| Screening | `screen_stocks`, `scan_by_signal` |\n| Multi-Exchange | `egx_*`, `multi_timeframe_analysis` |\n\n**资料来源：** [src/tradingview_mcp/server.py](src/tradingview_mcp/server.py)\n\n### Validators Module\n\nThe `validators.py` module handles exchange routing and symbol validation:\n\n```python\nEXCHANGE_SCREENER = {\n \"BINANCE\": \"crypto\",\n \"KUCOIN\": \"crypto\", \n \"BYBIT\": \"crypto\",\n \"NASDAQ\": \"america\",\n \"NYSE\": \"america\",\n \"AMEX\": \"america\",\n \"TWSE\": \"Taiwan\",\n \"TPEX\": \"Taiwan\",\n \"BIST\": \"turkey\"\n}\n```\n\nKey functions include:\n- `sanitize_exchange()` - Normalizes exchange names\n- `get_tv_exchange_prefix()` - Maps exchanges to TradingView prefixes (e.g., `AMEX:GLD`)\n- Exchange alias support for `AMEX`, `NYSEARCA`, `PCX` → `AMEX`\n\n**资料来源：** [src/tradingview_mcp/core/utils/validators.py](src/tradingview_mcp/core/utils/validators.py)\n\n### Screener Service\n\nHandles multi-exchange stock and crypto screening with configurable filters:\n\n**资料来源：** [src/tradingview_mcp/core/services/screener_service.py](src/tradingview_mcp/core/services/screener_service.py)\n\n---\n\n## Backtesting Engine Architecture\n\nThe backtesting engine supports 6 trading strategies:\n\n```mermaid\ngraph LR\n A[Symbol Input] --> B[Strategy Selector]\n \n B --> C[rsi
RSI Mean Reversion]\n B --> D[bollinger
BB Mean Reversion]\n B --> E[macd
MACD Cross]\n B --> F[ema_cross
EMA 20/50]\n B --> G[supertrend
ATR Supertrend]\n B --> H[donchian
Donchian Breakout]\n \n C --> I[Metrics Calculator]\n D --> I\n E --> I\n F --> I\n G --> I\n H --> I\n \n I --> J[Win Rate, Sharpe,
Calmar, Drawdown]\n```\n\n**Performance Metrics:**\n- Win Rate, Total Return\n- Sharpe Ratio, Calmar Ratio\n- Max Drawdown, Profit Factor\n- Expectancy, Best/Worst Trade\n- Commission + slippage simulation\n\n**资料来源：** [README.md - Backtesting Engine](README.md)\n\n---\n\n## Integration Architecture\n\n### Claude Desktop Integration\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n**资料来源：** [README.md - Quick Start](README.md)\n\n### OpenClaw Integration\n\nFor Telegram/WhatsApp access:\n\n```\nTelegram → OpenClaw Agent → trading.py wrapper → tradingview-mcp → Yahoo Finance\n```\n\n**资料来源：** [OPENCLAW.md](OPENCLAW.md)\n\n---\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as MCP Server\n participant Service as Service Layer\n participant Provider as Data Provider\n \n User->>MCP: Request tool call\n MCP->>Service: Route to appropriate service\n Service->>Provider: Fetch market data\n Provider-->>Service: Raw data response\n Service-->>MCP: Processed/Formatted data\n MCP-->>User: Tool result response\n```\n\n---\n\n## Supported Exchanges\n\n| Exchange | Region | Type | Tools |\n|----------|--------|------|-------|\n| Binance | Global | Crypto | All crypto tools |\n| KuCoin | Global | Crypto | All crypto tools |\n| Bybit+ | Global | Crypto | All crypto tools |\n| NASDAQ | US | Stocks | Stock analysis, screening |\n| NYSE | US | Stocks | Stock analysis, screening |\n| AMEX | US | ETFs/Stocks | Stock analysis, screening |\n| TWSE | Taiwan | Stocks | Stock analysis, screening |\n| TPEX | Taiwan | Stocks | Stock analysis, screening |\n| BIST | Turkey | Stocks | Turkish market tools |\n| EGX | Egypt | Stocks | `egx_market_overview`, `egx_stock_screener` |\n\n**资料来源：** [src/tradingview_mcp/core/utils/validators.py](src/tradingview_mcp/core/utils/validators.py), [README.md](README.md)\n\n---\n\n## Development Architecture\n\n### Local Development Setup\n\n```bash\n# Clone and install\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\nuv sync\n\n# Test server\nuv run python src/tradingview_mcp/server.py\n\n# Run with MCP Inspector\nuv run mcp dev src/tradingview_mcp/server.py\n```\n\n### Testing Pipeline\n\n| Test Type | Command | Purpose |\n|-----------|---------|---------|\n| Unit Tests | `uv run pytest` | Core functionality |\n| Linting | `uv run ruff check` | Code style |\n| Type Checking | `uv run mypy src/` | Type safety |\n| Integration | `uv run python test_api.py` | End-to-end |\n\n**资料来源：** [CONTRIBUTING.md - Testing](CONTRIBUTING.md)\n\n---\n\n## Adding New Components\n\n### Adding a New Exchange\n\n1. **Update validators.py:**\n ```python\n EXCHANGE_SCREENER = {\n \"NEW_EXCHANGE\": \"screener_code\",\n # ... existing\n }\n STOCK_EXCHANGES.add(\"NEW_EXCHANGE\")\n ```\n\n2. **Add symbol list:**\n ```bash\n echo \"SYMBOL1\\nSYMBOL2\" > coinlist/new_exchange.txt\n ```\n\n3. **Test integration:**\n ```python\n result = top_gainers(exchange=\"NEW_EXCHANGE\")\n ```\n\n**资料来源：** [CONTRIBUTING.md - Adding New Exchange](CONTRIBUTING.md)\n\n### Adding Technical Indicators\n\n1. **Create indicator function in `core/indicators/`:**\n ```python\n def calculate_custom_indicator(prices: List[float]) -> float:\n \"\"\"Calculate custom technical indicator\"\"\"\n return result\n ```\n\n2. **Integrate in server.py:**\n ```python\n custom_value = calculate_custom_indicator(price_data)\n result[\"technical_indicators\"][\"custom\"] = custom_value\n ```\n\n**资料来源：** [CONTRIBUTING.md - Adding Technical Indicators](CONTRIBUTING.md)\n\n---\n\n## Deployment Options\n\n| Method | Use Case | Command/Config |\n|--------|----------|----------------|\n| **uvx (Recommended)** | Quick start, no local install | `uvx --from tradingview-mcp-server tradingview-mcp` |\n| **Local Clone** | Development/modification | `git clone && uv sync && uv run python src/tradingview_mcp/server.py` |\n| **Pre-installed Tool** | Reusable cache | `uv tool install --python 3.13 tradingview-mcp-server` |\n| **Virtual Environment** | Traditional Python | `python -m venv .venv && pip install -e .` |\n| **OpenClaw** | Telegram/WhatsApp | See [OPENCLAW.md](OPENCLAW.md) |\n\n**资料来源：** [INSTALLATION.md](INSTALLATION.md), [README.md](README.md)\n\n---\n\n## Configuration Reference\n\n### Claude Desktop Configuration\n\n**Windows (Direct Python Path):**\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp\": {\n \"command\": \"C:\\\\Users\\\\Username\\\\tradingview-mcp\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\"C:\\\\Users\\\\Username\\\\tradingview-mcp\\\\src\\\\tradingview_mcp\\\\server.py\"],\n \"cwd\": \"C:\\\\Users\\\\Username\\\\tradingview-mcp\"\n }\n }\n}\n```\n\n**macOS/Linux (Using UV):**\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"src/tradingview_mcp/server.py\"],\n \"cwd\": \"/path/to/tradingview-mcp\"\n }\n }\n}\n```\n\n**资料来源：** [INSTALLATION.md - Local Development Setup](INSTALLATION.md)\n\n---\n\n\n\n## MCP Protocol Integration\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [MCP Tools Reference](#mcp-tools-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n- [.codex-mcp.json](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/.codex-mcp.json)\n- [.codex-plugin/plugin.json](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/.codex-plugin/plugin.json)\n- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n \n\n# MCP Protocol Integration\n\n## Overview\n\nThe TradingView MCP Server implements the **Model Context Protocol (MCP)** to provide AI assistants with structured access to real-time market data, technical analysis, and screening tools. MCP serves as the communication bridge between AI clients (Claude Desktop, Codex) and the TradingView data infrastructure.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[AI Client
Claude Desktop / Codex] --> B[MCP Protocol Layer]\n B --> C[tradingview-mcp Server]\n C --> D[Core Services]\n C --> E[Technical Indicators]\n C --> F[Screener Services]\n D --> G[Yahoo Finance API]\n D --> H[TradingView API]\n F --> I[Exchange Symbol Lists
coinlist/]\n \n style B fill:#e1f5fe\n style C fill:#fff3e0\n```\n\n### Component Layers\n\n| Layer | Responsibility | Key Components |\n|-------|---------------|----------------|\n| **AI Client** | User interaction, natural language processing | Claude Desktop, Codex |\n| **MCP Protocol** | Standardized communication, tool discovery | JSON-RPC 2.0 messages |\n| **Server** | Request routing, tool registration | `server.py` |\n| **Services** | Business logic, data processing | Screener, Technical Analysis |\n| **Data Sources** | External API integration | Yahoo Finance, TradingView |\n\n## Server Implementation\n\nThe main server is implemented in `src/tradingview_mcp/server.py` and exposes TradingView tools as MCP resources.\n\n### Available Tools\n\nThe server registers the following tools for market analysis:\n\n| Tool Category | Tools |\n|--------------|-------|\n| **Market Screening** | `top_gainers`, `top_losers`, `screen_stocks`, `scan_by_signal` |\n| **Technical Analysis** | `get_technical_analysis`, `get_multiple_analysis`, `get_bollinger_band_analysis` |\n| **Pattern Detection** | `get_candlestick_patterns`, `consecutive_candles_scan`, `bollinger_scan` |\n| **Multi-Timeframe** | `get_multi_timeframe_analysis`, `coin_analysis` |\n| **Stock Decision** | `get_stock_decision` |\n\n### Server Initialization\n\n```python\n# Minimal MCP server setup pattern\nfrom mcp.server import Server\nfrom mcp.server.stdio import stdio_server\n\napp = Server(\"tradingview-mcp\")\n# Register tools and resources\n```\n\n## Client Configuration\n\n### Claude Desktop\n\nThe server integrates with Claude Desktop via the MCP configuration file:\n\n| Platform | Config Location |\n|----------|-----------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n**Configuration Schema:**\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp\": {\n \"command\": \"uv\",\n \"args\": [\n \"tool\",\n \"run\",\n \"--from\",\n \"git+https://github.com/atilaahmettaner/tradingview-mcp.git\",\n \"tradingview-mcp\"\n ]\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n\n### Codex Plugin\n\nThe repository includes dedicated Codex plugin metadata for seamless integration:\n\n**Plugin Configuration Files:**\n\n| File | Purpose |\n|------|---------|\n| `.codex-plugin/plugin.json` | Plugin manifest |\n| `.codex-mcp.json` | MCP server configuration |\n\n**Codex Configuration:**\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\n \"--from\",\n \"tradingview-mcp-server\",\n \"tradingview-mcp\"\n ]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n## Installation Methods\n\n### Method 1: Direct Installation via UV\n\n```bash\n# Install from PyPI\nuv tool install tradingview-mcp-server\n```\n\n资料来源：[INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n\n### Method 2: Source Installation\n\n```bash\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\nuv run tradingview-mcp\n```\n\n### Method 3: Pre-warm Cache (Windows)\n\nFor Windows users with Python 3.14, pre-install to avoid initialization timeout:\n\n```bash\nuv tool install --python 3.13 tradingview-mcp-server\n```\n\n资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n## Development Workflow\n\n```mermaid\ngraph LR\n A[Clone Repository] --> B[Install Dependencies
uv sync]\n B --> C[Run Server
uv run python src/tradingview_mcp/server.py]\n C --> D[Test with MCP Inspector
uv run mcp dev src/tradingview_mcp/server.py]\n D --> E[Submit PR]\n \n style A fill:#c8e6c9\n style E fill:#c8e6c9\n```\n\n### Development Commands\n\n| Command | Purpose |\n|---------|---------|\n| `uv sync` | Install all dependencies |\n| `uv sync --dev` | Install development dependencies |\n| `uv run pytest` | Execute test suite |\n| `uv run ruff check` | Run linting |\n| `uv run mypy src/` | Run type checking |\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n## OpenClaw Integration\n\nFor messaging platforms (Telegram, WhatsApp, Discord), OpenClaw provides an alternative integration path:\n\n```mermaid\ngraph LR\n A[Telegram / WhatsApp] --> B[OpenClaw Agent]\n B --> C[trading.py Wrapper]\n C --> D[tradingview-mcp]\n D --> E[Yahoo Finance]\n \n style B fill:#e1f5fe\n style D fill:#fff3e0\n```\n\n### OpenClaw Quick Setup\n\n```bash\n# Install dependencies\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nuv tool install tradingview-mcp-server\n\n# Configure channel\ncat > ~/.openclaw/openclaw.json << 'EOF'\n{\n channels: {\n telegram: {\n botToken: \"YOUR_BOT_TOKEN_HERE\",\n },\n },\n}\nEOF\n\n# Install skill and tool\nmkdir -p ~/.agents/skills/tradingview-mcp ~/.openclaw/tools\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/SKILL.md \\\n -o ~/.agents/skills/tradingview-mcp/SKILL.md\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/trading.py \\\n -o ~/.openclaw/tools/trading.py && chmod +x ~/.openclaw/tools/trading.py\n```\n\n资料来源：[OPENCLAW.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/OPENCLAW.md)\n\n## Troubleshooting\n\n### Windows Initialization Timeout\n\n**Issue:** `MCP error -32001: Request timed out` on first launch with Python 3.14\n\n**Root Cause:** pandas has no prebuilt wheel for Python 3.14, causing pip to fall back to source build which exceeds 60-second timeout.\n\n**Solution:** Pin to Python 3.13:\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\"--python\", \"3.13\", \"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n### Verification Steps\n\nAfter installation, verify the MCP server is operational:\n\n1. Restart the AI client completely\n2. Ask: \"Can you show me the available TradingView tools?\"\n3. Confirm tools like `top_gainers`, `bollinger_scan`, `coin_analysis` are available\n\n## Code Organization\n\n```\nsrc/tradingview_mcp/\n├── server.py # Main MCP server implementation\n├── core/ # Core business logic\n│ ├── services/ # Market data services\n│ ├── utils/ # Utility functions (validators, etc.)\n│ └── indicators/ # Technical indicators\n└── coinlist/ # Exchange symbol lists\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n## Next Steps\n\n- Review the [Technical Analysis documentation](technical-analysis) for available indicators\n- Explore the [Screening Tools](screening-tools) for market filtering\n- Configure your preferred AI client following the installation guide\n\n---\n\n\n\n## Service Architecture\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [MCP Tools Reference](#mcp-tools-reference), [Multi-Exchange Integration](#exchange-integrations)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tradingview_mcp/core/services/backtest_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/backtest_service.py)\n- [src/tradingview_mcp/core/services/sentiment_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/sentiment_service.py)\n- [src/tradingview_mcp/core/services/indicators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators.py)\n- [src/tradingview_mcp/core/services/scanner_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/scanner_service.py)\n- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n- [src/tradingview_mcp/core/services/news_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/news_service.py)\n- [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)\n- [src/tradingview_mcp/core/services/indicators_calc.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators_calc.py)\n \n\n# Service Architecture\n\nThe TradingView MCP (Model Context Protocol) server implements a **modular service-oriented architecture** that separates concerns across distinct functional domains. This design enables the system to provide comprehensive market analysis capabilities—including technical indicators, sentiment analysis, backtesting, and real-time price data—through a unified MCP interface.\n\n## Overview\n\nThe service architecture follows a **layered pattern** where the MCP server acts as the presentation layer, delegating business logic to specialized services. Each service is responsible for a specific domain of functionality, communicating through well-defined interfaces.\n\n### High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"MCP Server Layer\"\n SERVER[server.py - MCP Entry Point]\n end\n \n subgraph \"Service Layer\"\n BACKTEST[backtest_service.py]\n SENTIMENT[sentiment_service.py]\n NEWS[news_service.py]\n YAHOO[yahoo_finance_service.py]\n SCREENER[screener_service.py]\n SCANNER[scanner_service.py]\n INDICATORS[indicators.py]\n CALC[indicators_calc.py]\n end\n \n subgraph \"Data Sources\"\n TV[TradingView API]\n REDDIT[Reddit API]\n RSS[RSS Feeds]\n YAHOO_FIN[Yahoo Finance API]\n end\n \n SERVER --> BACKTEST\n SERVER --> SENTIMENT\n SERVER --> NEWS\n SERVER --> YAHOO\n SERVER --> SCREENER\n SERVER --> SCANNER\n SERVER --> INDICATORS\n \n INDICATORS --> CALC\n BACKTEST --> CALC\n SCREENER --> TV\n SENTIMENT --> REDDIT\n NEWS --> RSS\n YAHOO --> YAHOO_FIN\n```\n\n### Service Directory Structure\n\n```\nsrc/tradingview_mcp/core/services/\n├── backtest_service.py # Strategy backtesting engine\n├── indicators.py # Technical indicator orchestration\n├── indicators_calc.py # Low-level indicator calculations\n├── news_service.py # RSS news aggregation\n├── scanner_service.py # Pattern scanning and detection\n├── screener_service.py # Multi-exchange market screening\n├── sentiment_service.py # Reddit sentiment analysis\n└── yahoo_finance_service.py # Real-time price data\n```\n\n资料来源：[CONTRIBUTING.md:62-70]()\n\n## Service Components\n\n### 1. Backtest Service\n\nThe backtest service provides a comprehensive strategy testing framework with institutional-grade metrics.\n\n| Feature | Description |\n|---------|-------------|\n| Strategy Types | RSI, Bollinger Bands, MACD, EMA Cross, Supertrend, Donchian |\n| Metrics | Win Rate, Sharpe Ratio, Calmar Ratio, Max Drawdown, Profit Factor |\n| Commission Simulation | Realistic slippage and commission modeling |\n\n资料来源：[src/tradingview_mcp/core/services/backtest_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/backtest_service.py)\n\n### 2. Screener Service\n\nThe screener service aggregates market data from TradingView's screener across multiple exchanges.\n\n| Exchange | Screener Type |\n|----------|---------------|\n| Binance, KuCoin, Bybit+ | Crypto screener |\n| NASDAQ, NYSE | US stocks |\n| TWSE, TPEX | Taiwan stocks |\n| AMEX, NYSEARCA, PCX | ETFs and specialty securities |\n| EGX | Egyptian exchange |\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n\n### 3. Indicators Service\n\nThe indicators service orchestrates calculation of 30+ technical indicators.\n\n| Category | Indicators |\n|----------|------------|\n| Momentum | RSI, MACD, Stochastic, CCI, Williams %R |\n| Trend | EMA, SMA, Supertrend, ADX |\n| Volatility | Bollinger Bands, ATR, Standard Deviation |\n| Volume | OBV, Volume Profile |\n\n资料来源：[src/tradingview_mcp/core/services/indicators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators.py)\n\n### 4. Indicators Calculation Module\n\nThe `indicators_calc.py` module provides the underlying mathematical calculations for all technical indicators.\n\n```python\n# Example: RSI calculation pattern\ndef calculate_rsi(prices: List[float], period: int = 14) -> float:\n \"\"\"Calculate Relative Strength Index\"\"\"\n # Implementation uses Wilder's smoothing method\n return rsi_value\n```\n\n资料来源：[src/tradingview_mcp/core/services/indicators_calc.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators_calc.py)\n\n### 5. Sentiment Service\n\nThe sentiment service analyzes social media sentiment from Reddit communities.\n\n| Function | Purpose |\n|----------|---------|\n| Community Detection | Identifies relevant subreddits for symbols |\n| Sentiment Scoring | Quantifies bullish/bearish community sentiment |\n| Integration | Combines with technical analysis for confluence |\n\n资料来源：[src/tradingview_mcp/core/services/sentiment_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/sentiment_service.py)\n\n### 6. News Service\n\nThe news service aggregates financial news from RSS feeds for market sentiment and event analysis.\n\n| Feed Type | Content |\n|-----------|---------|\n| Financial News | Market news, earnings reports |\n| Sector News | Industry-specific developments |\n| Macro News | Economic indicators and Fed communications |\n\n资料来源：[src/tradingview_mcp/core/services/news_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/news_service.py)\n\n### 7. Yahoo Finance Service\n\nThe Yahoo Finance service provides real-time price quotes and market data.\n\n| Data Point | Description |\n|------------|-------------|\n| Price | Current and historical prices |\n| Changes | Daily, weekly, yearly change percentages |\n| 52-Week Range | High/low boundaries |\n| Market State | Pre-market, regular, after-hours |\n\n资料来源：[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)\n\n### 8. Scanner Service\n\nThe scanner service detects technical patterns and trading signals across markets.\n\n| Pattern Type | Detection |\n|--------------|-----------|\n| Candlestick | 15 candlestick patterns (Doji, Hammer, Engulfing, etc.) |\n| Technical | Bollinger Band breakouts, volume spikes |\n| Signal-based | Oversold/overbought conditions, trend detection |\n\n资料来源：[src/tradingview_mcp/core/services/scanner_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/scanner_service.py)\n\n## Data Flow Architecture\n\n### Request Processing Flow\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Server as server.py\n participant Service as Service Layer\n participant External as External APIs\n \n Client->>Server: Tool Request\n Server->>Service: Delegate to Domain Service\n Service->>External: Fetch Data\n External-->>Service: Raw Data\n Service-->>Server: Processed Result\n Server-->>Client: MCP Response\n```\n\n### Multi-Timeframe Analysis Flow\n\nThe `multi_timeframe_analysis` function demonstrates cross-service integration:\n\n```mermaid\ngraph LR\n A[Symbol Selection] --> B[Weekly Analysis]\n B --> C[Daily Analysis]\n C --> D[4H Analysis]\n D --> E[1H Analysis]\n E --> F[15m Analysis]\n F --> G[Confluence Decision]\n \n B --> H[indicators.py]\n C --> H\n D --> H\n E --> H\n F --> H\n```\n\n资料来源：[src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n\n## Service Configuration\n\n### Exchange Mappings\n\nThe system maintains exchange-to-screener mappings for routing:\n\n```python\nEXCHANGE_SCREENER = {\n \"NASDAQ\": \"america\",\n \"NYSE\": \"america\",\n \"KUCOIN\": \"crypto\",\n \"BINANCE\": \"crypto\",\n \"EGX\": \"egypt\",\n \"TWSE\": \"crypto\", # Taiwan Stock Exchange\n \"TPEX\": \"crypto\", # Taiwan OTC\n \"AMEX\": \"america\",\n \"NYSEARCA\": \"america\",\n \"PCX\": \"america\",\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n### Symbol List Management\n\nEach exchange maintains a symbol list file for supported trading pairs:\n\n```\ncoinlist/\n├── binance.txt\n├── kucoin.txt\n├── mexc.txt\n├── egx.txt\n└── bybit.txt\n```\n\n## Integration Patterns\n\n### Strategy Backtesting Integration\n\n```mermaid\ngraph TD\n A[backtest_strategy] --> B[Load Historical Data]\n B --> C[Initialize Strategy]\n C --> D[Generate Signals]\n D --> E[Calculate Metrics]\n E --> F[Generate Trade Log]\n F --> G[Return Results]\n \n D --> H[indicators_calc.py]\n E --> I[Sharpe Ratio]\n E --> J[Max Drawdown]\n E --> K[Profit Factor]\n```\n\n### Confluence Analysis Pattern\n\nThe system combines multiple data sources for decision-making:\n\n1. **Technical Analysis** → `indicators.py` + `indicators_calc.py`\n2. **Sentiment Analysis** → `sentiment_service.py`\n3. **News Analysis** → `news_service.py`\n4. **Price Data** → `yahoo_finance_service.py`\n\n资料来源：[openclaw/SKILL.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/openclaw/SKILL.md)\n\n## Testing Architecture\n\n### Unit Tests\n\nServices are validated through dedicated unit test files:\n\n| Test File | Coverage |\n|-----------|----------|\n| `tests/unit/test_exchange_fixes.py` | Exchange validation, symbol construction |\n| `tests/unit/test_exchange_aliases.py` | Alias mappings, TWSE/TPEX handling |\n\n### Integration Testing\n\nThe project includes integration tests for real market data:\n\n```bash\nuv run pytest\nuv run ruff check\nuv run mypy src/\n```\n\n资料来源：[CONTRIBUTING.md:30-38]()\n\n## Summary\n\nThe service architecture of tradingview-mcp is designed around:\n\n| Principle | Implementation |\n|-----------|----------------|\n| **Separation of Concerns** | Each service handles a single domain |\n| **Reusability** | Shared `indicators_calc.py` for all indicator calculations |\n| **Testability** | Independent services with clear interfaces |\n| **Extensibility** | Easy to add new exchanges or indicators |\n| **Composability** | Services combine for complex analyses like confluence |\n\nThis architecture enables the MCP server to expose 30+ tools while maintaining clean, maintainable code organized by functional responsibility.\n\n---\n\n\n\n## MCP Tools Reference\n\n### 相关页面\n\n相关主题：[Backtesting Engine](#backtesting-engine), [Sentiment Analysis](#sentiment-analysis), [Multi-Exchange Integration](#exchange-integrations)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n- [src/tradingview_mcp/core/types.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/types.py)\n- [src/tradingview_mcp/core/services/indicators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators.py)\n- [src/tradingview_mcp/core/services/indicators_calc.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/indicators_calc.py)\n- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n- [src/tradingview_mcp/core/services/yahoo_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/yahoo_service.py)\n \n\n# MCP Tools Reference\n\n## Overview\n\nThe MCP Tools Reference documents all available Model Context Protocol (MCP) tools exposed by the TradingView MCP Server. These tools enable AI assistants like Claude Desktop, Codex, and OpenClaw to perform real-time market data retrieval, technical analysis, and trading signal generation through a standardized tool-calling interface.\n\nThe tradingview-mcp server acts as a bridge between AI agents and TradingView's market data infrastructure, providing programmatic access to cryptocurrency, stock, and forex market information across multiple exchanges worldwide.\n\n**资料来源：** [README.md](README.md)\n\n---\n\n## Architecture Overview\n\n### System Components\n\n```mermaid\ngraph TD\n subgraph \"AI Agent Layer\"\n A[Claude Desktop / Codex / OpenClaw]\n end\n \n subgraph \"MCP Protocol Layer\"\n B[MCP Server
tradingview-mcp]\n C[Tool Registry]\n end\n \n subgraph \"Data Source Layer\"\n D[TradingView Screener API]\n E[Yahoo Finance API]\n F[Exchange APIs
Binance, KuCoin, NASDAQ...]\n end\n \n A -->|MCP Protocol| B\n B --> C\n C -->|Market Data| D\n C -->|Real-time Prices| E\n C -->|Bulk Queries| F\n \n style B fill:#4a90d9\n style C fill:#5ba85b\n```\n\n### Tool Categories\n\n| Category | Description | Number of Tools |\n|----------|-------------|-----------------|\n| **Market Data** | Real-time prices and snapshots | 5+ |\n| **Technical Analysis** | Indicators, patterns, decisions | 8+ |\n| **Screening** | Top gainers/losers, custom filters | 10+ |\n| **Backtesting** | Strategy comparison and metrics | 2 |\n| **Multi-Exchange** | Cross-exchange analysis | 6+ |\n\n**资料来源：** [README.md](README.md)\n\n---\n\n## Core Tool Types\n\n### Tool Definition Schema\n\nAll MCP tools follow a standardized type definition structure defined in `core/types.py`:\n\n```python\n@dataclass\nclass ToolDefinition:\n name: str\n description: str\n input_schema: dict\n handler: Callable\n```\n\n**资料来源：** [src/tradingview_mcp/core/types.py](src/tradingview_mcp/core/types.py)\n\n---\n\n## Market Data Tools\n\n### yahoo_price\n\nRetrieves real-time quote data for a single symbol including price, change percentage, 52-week range, and market state.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `symbol` | string | Yes | - | Ticker symbol (e.g., BTC-USD, AAPL) |\n| `exchange` | string | No | auto-detect | Exchange prefix (optional override) |\n\n**Returns:**\n```json\n{\n \"symbol\": \"BTC-USD\",\n \"price\": 67432.50,\n \"change_percent\": 2.34,\n \"52w_high\": 73000.00,\n \"52w_low\": 52000.00,\n \"market_state\": \"REGULAR\"\n}\n```\n\n**资料来源：** [src/tradingview_mcp/core/services/yahoo_service.py](src/tradingview_mcp/core/services/yahoo_service.py)\n\n---\n\n### market_snapshot\n\nProvides a global market overview combining multiple asset classes in a single response.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `include_crypto` | boolean | No | true |\n| `include_indices` | boolean | No | true |\n| `include_forex` | boolean | No | true |\n\n**Coverage:**\n- **Crypto:** BTC-USD, ETH-USD, SOL-USD, etc.\n- **Indices:** S&P 500, NASDAQ, DOW\n- **Forex:** EUR/USD, GBP/USD, USD/JPY\n\n**资料来源：** [src/tradingview_mcp/core/services/yahoo_service.py](src/tradingview_mcp/core/services/yahoo_service.py)\n\n---\n\n### get_prices_bulk\n\nRetrieves price data for multiple symbols in a single call.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `symbols` | string[] | Yes | - | Array of ticker symbols |\n| `exchange` | string | No | auto-detect | Exchange prefix |\n\n**资料来源：** [server.py:server.py](src/tradingview_mcp/server.py)\n\n---\n\n## Technical Analysis Tools\n\n### get_technical_analysis\n\nExecutes comprehensive technical analysis with 23+ indicators, returning BUY/SELL/HOLD signals with confluence scoring.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `symbol` | string | Yes | - | Ticker symbol |\n| `exchange` | string | No | KUCOIN | Exchange identifier |\n| `timeframe` | string | No | 1D | Time interval (1m, 5m, 15m, 1h, 4h, 1D, 1W) |\n| `indicators` | string[] | No | all | Specific indicators to calculate |\n\n**Included Indicators:**\n\n| Indicator | Type | Signal Logic |\n|-----------|------|--------------|\n| RSI (14) | Momentum | Oversold <30, Overbought >70 |\n| MACD | Trend | Signal line crossover |\n| Bollinger Bands | Volatility | Price near bands |\n| EMA Cross | Trend | 20/50 period crossover |\n| Supertrend | Trend | ATR-based reversal |\n| ATR | Volatility | Raw volatility measure |\n| ADX | Trend Strength | >25 indicates strong trend |\n\n**资料来源：** [src/tradingview_mcp/core/services/indicators.py](src/tradingview_mcp/core/services/indicators.py)\n\n---\n\n### get_bollinger_band_analysis\n\nProprietary Bollinger Band analysis with ±3 rating system for volatility and position assessment.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `symbol` | string | Yes | - |\n| `exchange` | string | No | KUCOIN |\n| `timeframe` | string | No | 1D |\n\n**Response Structure:**\n```python\n{\n \"bandwidth\": 0.0342,\n \"position\": \"upper_50_percent\",\n \"signal\": \"BUY\",\n \"rating\": 2 # -3 to +3 scale\n}\n```\n\n**Bandwidth Calculation:**\n```\nBBW = (Upper Band - Lower Band) / Middle Band\n```\n\n**资料来源：** [src/tradingview_mcp/core/services/indicators.py](src/tradingview_mcp/core/services/indicators.py), [CONTRIBUTING.md](CONTRIBUTING.md)\n\n---\n\n### get_multiple_analysis\n\nRuns technical analysis on multiple symbols simultaneously.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `symbols` | string[] | Yes | - |\n| `exchange` | string | No | KUCOIN |\n| `timeframe` | string | No | 1D |\n\n**资料来源：** [server.py](src/tradingview_mcp/server.py)\n\n---\n\n### get_stock_decision\n\nThree-layer decision engine combining ranking, trade setup, and quality scoring.\n\n**Layers:**\n1. **Ranking Score** - Relative strength vs market\n2. **Trade Setup** - Entry/exit signal alignment\n3. **Quality Score** - Overall confidence rating\n\n**资料来源：** [README.md](README.md)\n\n---\n\n### get_candlestick_patterns\n\nDetects 15+ candlestick patterns in historical price data.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `symbol` | string | Yes | - |\n| `exchange` | string | No | KUCOIN |\n| `timeframe` | string | No | 1D |\n| `pattern_type` | string | No | all |\n\n**Supported Patterns:**\n- Doji, Hammer, Engulfing, Morning Star\n- Harami, Shooting Star, Three White Soldiers\n- Dark Cloud Cover, Piercing Line\n\n**资料来源：** [server.py](src/tradingview_mcp/server.py)\n\n---\n\n### get_multi_timeframe_analysis\n\nAnalyzes the same symbol across multiple timeframes to identify aligned trends.\n\n**Timeframe Alignment:**\n\n```mermaid\ngraph LR\n W[Weekly] --> D[Daily]\n D --> H4[4H]\n H4 --> H1[1H]\n H1 --> M15[15m]\n \n style W fill:#4a90d9\n style M15 fill:#d94a4a\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `symbol` | string | Yes | - |\n| `exchange` | string | No | KUCOIN |\n| `timeframes` | string[] | No | [1D, 4H, 1H, 15m] |\n\n**资料来源：** [PR_BODY.md](PR_BODY.md), [README.md](README.md)\n\n---\n\n## Screening Tools\n\n### top_gainers\n\nScreens for top-performing assets by percentage gain on a specific exchange.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `exchange` | string | No | KUCOIN | Exchange identifier |\n| `timeframe` | string | No | 1D | Time interval |\n| `limit` | integer | No | 10 | Number of results (max 50) |\n\n**Supported Exchanges:**\n- **Crypto:** KUCOIN, BINANCE, BYBIT\n- **US Markets:** NASDAQ, NYSE\n- **Regional:** BIST, EGX, TWSE, TPEX\n\n**资料来源：** [src/tradingview_mcp/core/services/screener_service.py](src/tradingview_mcp/core/services/screener_service.py)\n\n---\n\n### top_losers\n\nScreens for worst-performing assets by percentage decline.\n\n**Parameters:** Identical to `top_gainers`\n\n**资料来源：** [server.py](src/tradingview_mcp/server.py)\n\n---\n\n### scan_by_signal\n\nScans markets filtered by predefined signal types.\n\n**Signal Types:**\n\n| Signal | Description |\n|--------|-------------|\n| `oversold` | RSI below 30 |\n| `overbought` | RSI above 70 |\n| `trending_up` | Strong upward momentum |\n| `trending_down` | Strong downward momentum |\n| `breakout` | Price breaking resistance |\n| `breakdown` | Price breaking support |\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `signal_type` | string | Yes | - |\n| `exchange` | string | No | KUCOIN |\n| `timeframe` | string | No | 1D |\n| `limit` | integer | No | 20 |\n\n**资料来源：** [server.py](src/tradingview_mcp/server.py)\n\n---\n\n### bollinger_scan\n\nScans for Bollinger Band squeeze patterns indicating potential volatility expansion.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `exchange` | string | No | KUCOIN |\n| `timeframe` | string | No | 1D |\n| `bbw_threshold` | float | No | 0.05 | Bandwidth threshold for squeeze detection |\n| `limit` | integer | No | 20 |\n\n**Squeeze Detection Logic:**\n```python\n# Squeeze detected when bandwidth < threshold\nif bandwidth < bbw_threshold:\n return \"SQZ\" # Potential breakout setup\n```\n\n**资料来源：** [EXAMPLES.md](EXAMPLES.md)\n\n---\n\n### consecutive_candles_scan\n\nDetects coins with consecutive bullish or bearish candles indicating sustained momentum.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `pattern_type` | string | No | bullish | bullish or bearish |\n| `timeframe` | string | No | 1h | Time interval |\n| `min_count` | integer | No | 3 | Minimum consecutive candles |\n| `exchange` | string | No | KUCOIN |\n\n**Example Response:**\n```\nSOLUSDT - 4 consecutive green candles (1h)\nTotal gain: +8.4%\nVolume increasing\n```\n\n**资料来源：** [EXAMPLES.md](EXAMPLES.md)\n\n---\n\n### screen_stocks\n\nMulti-criteria stock screener with 20+ filter parameters.\n\n**Filter Categories:**\n\n| Category | Filters |\n|----------|---------|\n| **Price** | price_min, price_max |\n| **Volume** | volume_min, volume_max |\n| **Technical** | rsi_above, rsi_below, sma_50_above, sma_200_below |\n| **Fundamentals** | market_cap_min, market_cap_max |\n| **Performance** | change_above, change_below |\n\n**资料来源：** [README.md](README.md)\n\n---\n\n## Backtesting Tools\n\n### backtest_strategy\n\nRuns historical backtest for a single trading strategy with institutional-grade metrics.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `symbol` | string | Yes | - |\n| `strategy` | string | Yes | - | Strategy name |\n| `period` | string | No | 1Y | Backtest period |\n| `initial_capital` | float | No | 10000 | Starting capital |\n| `commission` | float | No | 0.1 | Commission percentage |\n\n**Available Strategies:**\n\n| Strategy | Logic | Best For |\n|----------|-------|----------|\n| `rsi` | RSI oversold/overbought mean reversion | Range-bound markets |\n| `bollinger` | Bollinger Band bounce | Volatile markets |\n| `macd` | MACD golden/death cross | Trend changes |\n| `ema_cross` | EMA 20/50 crossover | Medium-term trends |\n| `supertrend` | ATR-based trend following | Strong trends |\n| `donchian` | Donchian Channel breakout | Momentum plays |\n\n**Metrics Returned:**\n\n| Metric | Description |\n|--------|-------------|\n| Win Rate | Percentage of profitable trades |\n| Total Return | Overall percentage gain/loss |\n| Sharpe Ratio | Risk-adjusted return |\n| Calmar Ratio | Return / Max drawdown |\n| Max Drawdown | Largest peak-to-trough decline |\n| Profit Factor | Gross profit / Gross loss |\n| Expectancy | Average expected return per trade |\n\n**资料来源：** [README.md](README.md)\n\n---\n\n### compare_strategies\n\nRuns all 6 strategies on the same symbol and ranks by performance.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `symbol` | string | Yes | - |\n| `period` | string | No | 1Y | Backtest period |\n| `limit` | integer | No | 10 | Number of top strategies to return |\n\n**Output Format:**\n```\n#1 Supertrend: +31.5% | Sharpe: 2.1 | WR: 62%\n#2 Bollinger: +18.3% | Sharpe: 3.4 | WR: 75%\n#3 Buy & Hold: -5.0%\n```\n\n**资料来源：** [README.md](README.md)\n\n---\n\n## Exchange-Specific Tools\n\n### Exchange Support Matrix\n\n| Exchange | Region | Screener | Price Data | Specific Tools |\n|----------|--------|----------|------------|----------------|\n| KUCOIN | Global Crypto | ✅ | ✅ | All tools |\n| BINANCE | Global Crypto | ✅ | ✅ | All tools |\n| BYBIT | Global Crypto | ✅ | ✅ | All tools |\n| NASDAQ | US Stocks | ✅ | ✅ | All tools |\n| NYSE | US Stocks | ✅ | ✅ | All tools |\n| BIST | Turkey | ✅ | ✅ | All tools |\n| EGX | Egypt | ✅ | ✅ | egx_* tools |\n| TWSE | Taiwan | ✅ | ✅ | - |\n| TPEX | Taiwan | ✅ | ✅ | - |\n\n### Symbol Construction\n\nTradingView requires properly formatted exchange-prefixed symbols:\n\n```\n{EXCHANGE}:{SYMBOL}\nExamples:\n- KUCOIN:SOLUSDT\n- BINANCE:BTCUSDT\n- NASDAQ:AAPL\n```\n\n**资料来源：** [src/tradingview_mcp/core/services/screener_service.py](src/tradingview_mcp/core/services/screener_service.py), [PR_BODY.md](PR_BODY.md)\n\n---\n\n## Tool Registration Flow\n\n```mermaid\nsequenceDiagram\n participant Server as MCP Server\n participant Registry as Tool Registry\n participant Handler as Tool Handler\n \n Server->>Registry: register_tools()\n Registry->>Handler: Instantiate tool class\n Handler->>Registry: Register name, schema, callback\n \n Note over Registry: All tools registered at startup\n \n Client->>Server: list_tools()\n Server->>Registry: get_all_tools()\n Registry-->>Client: Tool definitions\n \n Client->>Server: call_tool(name, params)\n Server->>Handler: execute(params)\n Handler-->>Server: Tool result\n Server-->>Client: JSON-RPC response\n```\n\n**资料来源：** [src/tradingview_mcp/server.py](src/tradingview_mcp/server.py)\n\n---\n\n## Response Format Standards\n\n### Success Response\n\n```json\n{\n \"result\": {\n \"status\": \"success\",\n \"data\": { ... },\n \"metadata\": {\n \"timestamp\": \"2024-01-15T10:30:00Z\",\n \"source\": \"tradingview-screener\",\n \"latency_ms\": 245\n }\n }\n}\n```\n\n### Error Response\n\n```json\n{\n \"error\": {\n \"code\": \"EXCHANGE_NOT_FOUND\",\n \"message\": \"Exchange 'INVALID' is not supported\",\n \"details\": {\n \"supported\": [\"KUCOIN\", \"BINANCE\", \"NASDAQ\", \"NYSE\"]\n }\n }\n}\n```\n\n---\n\n## Usage Examples\n\n### Basic Market Query\n\n```\nYou: \"Show me top 5 crypto gainers on KuCoin in 15 minutes\"\n\nAI: [Uses: top_gainers(exchange=\"KUCOIN\", timeframe=\"15\", limit=5)]\n\n🇰🇪 KuCoin Top Gainers (15m):\n\n1. **SOLUSDT** - $142.50 (+5.2%)\n2. **AVAXUSDT** - $34.20 (+4.1%)\n3. **MATICUSDT** - $0.82 (+3.8%)\n4. **LINKUSDT** - $14.50 (+3.2%)\n5. **DOTUSDT** - $6.80 (+2.9%)\n```\n\n### Technical Analysis Request\n\n```\nYou: \"Analyze Bitcoin with all technical indicators\"\n\nAI: [Uses: get_technical_analysis(symbol=\"BTC\", exchange=\"BINANCE\")]\n\n📊 BTC-USD Technical Analysis:\n\nRSI (14): 58.4 → NEUTRAL\nMACD: BULLISH CROSSOVER\nBollinger Bands: UPPER_50_PERCENT\nADX: 32.5 → STRONG TREND\n\nOverall Signal: BUY (Confluence Score: 7/10)\n```\n\n### Strategy Comparison\n\n```\nYou: \"Compare all strategies on BTC-USD for 2 years\"\n\nAI: [Uses: compare_strategies(symbol=\"BTC\", period=\"2Y\")]\n\n📈 Strategy Comparison Results:\n\n#1 Supertrend: +31.5% | Sharpe: 2.1 | WR: 62%\n#2 Bollinger: +18.3% | Sharpe: 3.4 | WR: 75%\n#3 MACD: +12.1% | Sharpe: 1.8 | WR: 55%\n#4 EMA Cross: +8.4% | Sharpe: 1.2 | WR: 52%\n#5 RSI: -2.1% | Sharpe: -0.3 | WR: 45%\n#6 Donchian: -8.5% | Sharpe: -1.1 | WR: 38%\n\nBuy & Hold: -5.0%\n```\n\n**资料来源：** [EXAMPLES.md](EXAMPLES.md), [README.md](README.md)\n\n---\n\n## Configuration\n\n### MCP Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp\": {\n \"command\": \"uv\",\n \"args\": [\n \"tool\",\n \"run\",\n \"--from\",\n \"git+https://github.com/atilaahmettaner/tradingview-mcp.git\",\n \"tradingview-mcp\"\n ]\n }\n }\n}\n```\n\n### Local Development Configuration\n\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"src/tradingview_mcp/server.py\"],\n \"cwd\": \"/path/to/tradingview-mcp\"\n }\n }\n}\n```\n\n**资料来源：** [INSTALLATION.md](INSTALLATION.md)\n\n---\n\n## See Also\n\n- [Installation Guide](INSTALLATION.md) - Setup instructions for MCP clients\n- [Contributing Guide](CONTRIBUTING.md) - Development standards and testing\n- [OpenClaw Integration](OPENCLAW.md) - Telegram/WhatsApp bot setup\n- [Examples](EXAMPLES.md) - Real-world usage scenarios\n\n---\n\n\n\n## Backtesting Engine\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [Service Architecture](#service-architecture)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/tradingview_mcp/core/services/backtest_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/backtest_service.py)\n- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n- [CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)\n- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n \n\n# Backtesting Engine\n\nThe Backtesting Engine is a core component of the `tradingview-mcp` project that provides automated strategy testing capabilities using historical market data. It enables traders and developers to validate trading strategies against real price data before deploying them in live markets.\n\n## Overview\n\nThe Backtesting Engine (v3, v0.7.0) is a pure Python implementation that requires no external backtesting libraries such as pandas or numpy. It fetches historical OHLCV (Open, High, Low, Close, Volume) data from Yahoo Finance and simulates trading strategies with realistic commission and slippage modeling.\n\n**Key Characteristics:**\n\n- Pure Python implementation with no pandas/numpy dependencies\n- 6 built-in trading strategies\n- Supports daily (1d) and hourly (1h) timeframes\n- Walk-forward analysis for overfitting detection\n- Full trade logging with detailed per-trade breakdowns\n- Equity curve generation for performance visualization\n\n资料来源：[backtest_service.py:1-20]()\n\n## Architecture\n\nThe Backtesting Engine follows a layered architecture with clear separation of concerns:\n\n```mermaid\ngraph TD\n subgraph \"MCP Tool Layer\"\n A[\"backtest_strategy\"]\n B[\"compare_strategies\"]\n C[\"walk_forward_backtest_strategy\"]\n end\n \n subgraph \"Service Layer\"\n D[\"backtest_service.py\"]\n E[\"indicators_calc.py\"]\n end\n \n subgraph \"Data Layer\"\n F[\"Yahoo Finance API\"]\n end\n \n A --> D\n B --> D\n C --> D\n D --> E\n D --> F\n E --> F\n```\n\n### Component Responsibilities\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| MCP Tool Layer | `server.py` | Exposes backtesting as MCP tools |\n| Service Layer | `backtest_service.py` | Core backtesting logic, trade simulation |\n| Indicators | `indicators_calc.py` | Technical indicator calculations |\n| External Data | Yahoo Finance API | OHLCV price data retrieval |\n\n资料来源：[server.py]() [backtest_service.py:1-50]()\n\n## Supported Strategies\n\nThe Backtesting Engine includes 6 pre-built trading strategies:\n\n| Strategy | Type | Description |\n|----------|------|-------------|\n| `rsi` | Mean Reversion | RSI oversold (<30) / overbought (>70) signals |\n| `bollinger` | Mean Reversion | Bollinger Band bounce trading |\n| `macd` | Momentum | MACD golden/death cross signals |\n| `ema_cross` | Trend Following | EMA 20/50 Golden/Death Cross |\n| `supertrend` | Trend Following | ATR-based Supertrend (🔥 most popular) |\n| `donchian` | Breakout | Donchian Channel breakout (Turtle Trader style) |\n\n资料来源：[backtest_service.py:15-22]()\n\n### Strategy Selection Flow\n\n```mermaid\ngraph TD\n A[\"Start Backtest\"] --> B{\"Strategy Valid?\"}\n B -->|No| E[\"Return Error: Unknown strategy\"]\n B -->|Yes| F[\"Fetch OHLCV Data\"]\n F --> G{\"Sufficient Data?\"}\n G -->|No| H[\"Return Error: Not enough data\"]\n G -->|Yes| I[\"Execute Strategy Logic\"]\n I --> J[\"Calculate Metrics\"]\n J --> K[\"Return Results\"]\n```\n\n资料来源：[backtest_service.py:100-140]()\n\n## MCP Tool Functions\n\nThe Backtesting Engine exposes three primary MCP tools through the server interface.\n\n### 1. backtest_strategy\n\nExecutes a single strategy backtest on a given symbol.\n\n**Function Signature:**\n```python\n@mcp.tool()\ndef backtest_strategy(\n symbol: str,\n strategy: str,\n period: str = \"1y\",\n initial_capital: float = 10000.0,\n commission_pct: float = 0.1,\n slippage_pct: float = 0.05,\n interval: str = \"1d\",\n include_trade_log: bool = False,\n include_equity_curve: bool = False,\n) -> dict\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `symbol` | str | Required | Yahoo Finance symbol (AAPL, BTC-USD, SPY...) |\n| `strategy` | str | Required | rsi, bollinger, macd, ema_cross, supertrend, donchian |\n| `period` | str | \"1y\" | 1mo, 3mo, 6mo, 1y, 2y |\n| `initial_capital` | float | 10000.0 | Starting capital in USD |\n| `commission_pct` | float | 0.1 | Per-trade commission % |\n| `slippage_pct` | float | 0.05 | Per-trade slippage % |\n| `interval` | str | \"1d\" | 1d (daily) or 1h (hourly) |\n| `include_trade_log` | bool | False | Include detailed trade log |\n| `include_equity_curve` | bool | False | Include equity curve data points |\n\n资料来源：[server.py]()\n\n### 2. compare_strategies\n\nRuns all 6 strategies on the same symbol and ranks by performance.\n\n**Function Signature:**\n```python\n@mcp.tool()\ndef compare_strategies(\n symbol: str,\n period: str = \"1y\",\n initial_capital: float = 10000.0,\n interval: str = \"1d\",\n) -> dict\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `symbol` | str | Required | Yahoo Finance symbol |\n| `period` | str | \"1y\" | 1mo, 3mo, 6mo, 1y, 2y |\n| `initial_capital` | float | 10000.0 | Starting capital in USD |\n| `interval` | str | \"1d\" | 1d (daily) or 1h (hourly) |\n\n资料来源：[server.py]()\n\n### 3. walk_forward_backtest_strategy\n\nWalk-forward backtesting to detect strategy overfitting.\n\n**Function Signature:**\n```python\n@mcp.tool()\ndef walk_forward_backtest_strategy(\n symbol: str,\n strategy: str,\n period: str = \"2y\",\n initial_capital: float = 10000.0,\n commission_pct: float = 0.1,\n slippage_pct: float = 0.05,\n n_splits: int = 3,\n train_ratio: float = 0.7,\n interval: str = \"1d\",\n) -> dict\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `symbol` | str | Required | Yahoo Finance symbol |\n| `strategy` | str | Required | rsi, bollinger, macd, ema_cross, supertrend, donchian |\n| `period` | str | \"2y\" | Recommended: 2y for walk-forward |\n| `n_splits` | int | 3 | Number of walk-forward folds (2-10) |\n| `train_ratio` | float | 0.7 | Fraction used for training |\n\n资料来源：[server.py]()\n\n## Walk-Forward Analysis\n\nWalk-forward analysis is a robust method for detecting strategy overfitting. It splits historical data into multiple train/test folds to validate strategy performance on unseen data.\n\n### Methodology\n\n```mermaid\ngraph LR\n subgraph \"Fold 1\"\n A1[\"Train 70%\"] --> B1[\"Test 30%\"]\n end\n subgraph \"Fold 2\"\n A2[\"Train 70%\"] --> B2[\"Test 30%\"]\n end\n subgraph \"Fold 3\"\n A3[\"Train 70%\"] --> B3[\"Test 30%\"]\n end\n```\n\n### Robustness Scoring\n\n| Score | Classification | Interpretation |\n|-------|----------------|-----------------|\n| ≥ 0.8 | ROBUST | No overfitting detected |\n| ≥ 0.5 | MODERATE | Some degradation expected |\n| ≥ 0.2 | WEAK | Likely overfitted |\n| < 0.2 | OVERFITTED | Do not trade live |\n\nThe robustness score is calculated as: `test_return / train_return`\n\n资料来源：[backtest_service.py:180-220]()\n\n## Return Metrics\n\nThe backtesting engine calculates comprehensive performance metrics:\n\n### Core Metrics\n\n| Metric | Description |\n|--------|-------------|\n| Total Return % | Overall strategy return |\n| Sharpe Ratio | Risk-adjusted return (annualized) |\n| Calmar Ratio | Return / Maximum Drawdown |\n| Max Drawdown % | Largest peak-to-trough decline |\n| Win Rate % | Percentage of profitable trades |\n| Profit Factor | Gross profit / Gross loss |\n| Expectancy | Average trade return including losses |\n| Best Trade % | Best single trade return |\n| Worst Trade % | Worst single trade return |\n\n### Interval-Aware Annualization\n\nSharpe ratio annualization adjusts based on timeframe:\n\n| Interval | Annualization Factor |\n|----------|---------------------|\n| 1d | 252 (trading days/year) |\n| 1h | 252 × 6 (trading hours/year) |\n\n资料来源：[backtest_service.py:30-32]()\n\n## Data Fetching\n\nThe engine retrieves OHLCV data from Yahoo Finance:\n\n**API Endpoint:**\n```\nhttps://query1.finance.yahoo.com/v8/finance/chart/{symbol}\n```\n\n**User Agent:**\n```\ntradingview-mcp/0.7.0 backtest-bot\n```\n\n**Validation Rules:**\n\n| Interval | Minimum Bars Required |\n|----------|----------------------|\n| 1d | 30 bars |\n| 1h | 100 bars |\n\n资料来源：[backtest_service.py:24-29]()\n\n## Trade Simulation\n\nThe trade simulation includes realistic trading costs:\n\n### Cost Components\n\n| Component | Default | Description |\n|-----------|---------|-------------|\n| Commission | 0.1% | Per-trade commission |\n| Slippage | 0.05% | Per-trade price slippage |\n\n### Trade Log Fields\n\nWhen `include_trade_log=True`, each trade includes:\n\n| Field | Description |\n|-------|-------------|\n| `entry_date` | Trade entry timestamp |\n| `exit_date` | Trade exit timestamp |\n| `entry_price` | Entry price |\n| `exit_price` | Exit price |\n| `holding_days` | Days held |\n| `gross_return_pct` | Gross return before costs |\n| `net_return_pct` | Net return after costs |\n| `cost_pct` | Total costs (commission + slippage) |\n| `capital_at_entry` | Capital at entry |\n| `capital_after_trade` | Capital after trade |\n| `cumulative_return` | Cumulative return at this point |\n\n### Equity Curve\n\nWhen `include_equity_curve=True`, returns data points at each trade exit:\n\n```python\n{\n \"equity_curve\": [\n {\"date\": \"2023-01-15\", \"capital\": 10500.00, \"drawdown_pct\": 0.0},\n {\"date\": \"2023-02-20\", \"capital\": 10200.00, \"drawdown_pct\": -2.86},\n ...\n ]\n}\n```\n\n资料来源：[backtest_service.py:140-180]()\n\n## Usage Examples\n\n### Basic Backtest\n```\nYou: \"Backtest RSI strategy for AAPL over 1 year\"\n→ backtest_strategy(symbol=\"AAPL\", strategy=\"rsi\", period=\"1y\")\n```\n\n### Strategy Comparison\n```\nYou: \"Compare all strategies on BTC-USD for 2 years\"\n→ compare_strategies(symbol=\"BTC-USD\", period=\"2y\")\n\nOutput:\n→ #1 Supertrend: +31.5% | Sharpe: 2.1 | WR: 62%\n→ #2 Bollinger: +18.3% | Sharpe: 3.4 | WR: 75%\n→ Buy & Hold: -5.0%\n```\n\n### Walk-Forward Analysis\n```\nYou: \"Is the RSI strategy overfitted for AAPL?\"\n→ walk_forward_backtest_strategy(\n symbol=\"AAPL\",\n strategy=\"rsi\",\n period=\"2y\",\n n_splits=3\n)\n```\n\n### Full Trade Log\n```\nYou: \"Show me the full trade log for the backtest\"\n→ backtest_strategy(\n symbol=\"AAPL\",\n strategy=\"supertrend\",\n period=\"1y\",\n include_trade_log=True\n)\n```\n\n资料来源：[README.md]()\n\n## Version History\n\n| Version | Date | Key Changes |\n|---------|------|-------------|\n| v0.7.0 | Latest | 1h timeframe, full trade log, equity curve, walk-forward |\n| v0.6.0 | 2026-03-29 | Initial backtesting engine with 6 strategies |\n\n资料来源：[CHANGELOG.md]()\n\n## Error Handling\n\n| Error Condition | Response |\n|-----------------|----------|\n| Unknown strategy | `{\"error\": \"Unknown strategy 'X'. Choose: rsi, bollinger...\"}` |\n| Invalid period | `{\"error\": \"Invalid period 'X'. Choose: 1mo, 3mo, 6mo, 1y, 2y\"}` |\n| Invalid interval | `{\"error\": \"Invalid interval 'X'. Choose: 1d or 1h\"}` |\n| Data fetch failure | `{\"error\": \"Failed to fetch data for 'X': {exception}\"}` |\n| Insufficient data | `{\"error\": \"Not enough data (N bars). Try a longer period.\"}` |\n\n资料来源：[backtest_service.py:100-150]()\n\n## Disclaimer\n\n⚠️ **Important:** Past performance does not guarantee future results. Backtested results include hypothetical trades that may not reflect actual market conditions including liquidity constraints, emotional decision-making, and execution delays.\n\n---\n\n\n\n## Sentiment Analysis\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [Service Architecture](#service-architecture)\n\n\nRelated Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/tradingview_mcp/core/services/sentiment_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/sentiment_service.py)\n- [src/tradingview_mcp/core/services/news_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/multi_agent_service.py)\n- [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)\n- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n- [openclaw/trading.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/openclaw/trading.py)\n- [src/tradingview_mcp/core/data/egx_sectors.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/data/egx_sectors.py)\n \n\n# Sentiment Analysis\n\nThe Sentiment Analysis module is a core component of the tradingview-mcp framework that aggregates social media sentiment data—primarily from Reddit—and converts it into actionable trading signals. This module works in conjunction with technical analysis and news feeds to provide a multi-signal confluence system that helps traders understand market mood and community consensus around specific assets.\n\n## Overview\n\nThe sentiment analysis system is designed to:\n\n- Fetch posts from Reddit across multiple subreddit categories\n- Score text content using a custom sentiment scoring algorithm\n- Categorize sentiment into actionable labels (Bullish, Bearish, Neutral)\n- Integrate with the broader multi-agent trading framework\n- Provide confidence scoring when combined with technical indicators\n\nThe module operates as part of a three-layer analytical system that includes:\n\n1. **Technical Analyst** — Bollinger Bands, RSI, MACD\n2. **Sentiment & Momentum Analyst** — Reddit community sentiment + price momentum\n3. **Risk Manager** — Volatility, drawdown risk, mean-reversion signals\n\n资料来源：[README.md:1-50]()\n\n## Architecture\n\nThe sentiment analysis system follows a layered architecture:\n\n```mermaid\ngraph TD\n A[analyze_sentiment API] --> B[Category Selection]\n B --> C[Subreddit Groups]\n C --> D[Per-Subreddit Fetch]\n D --> E[_fetch_reddit_posts]\n E --> F[Text Extraction]\n F --> G[_score_text]\n G --> H[Score Aggregation]\n H --> I[Result Construction]\n I --> J[Sentiment Label + Breakdown]\n```\n\n### Component Structure\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| `analyze_sentiment` | `sentiment_service.py` | Main public API entry point |\n| `_fetch_reddit_posts` | `sentiment_service.py` | Reddit API integration |\n| `_score_text` | `sentiment_service.py` | Sentiment scoring algorithm |\n| `analyze_confluence` | `server.py` | Combined technical + sentiment analysis |\n| `multi_agent_analysis` | `multi_agent_service.py` | Multi-agent trading decision system |\n\n资料来源：[src/tradingview_mcp/core/services/sentiment_service.py:1-100]()\n\n## Subreddit Configuration\n\nThe system uses a predefined configuration of subreddit groups organized by market category:\n\n### SUBREDDIT_GROUPS Structure\n\n| Category | Subreddits | Target Markets |\n|----------|------------|----------------|\n| `crypto` | r/CryptoCurrency, r/Bitcoin, r/ethereum, r/CryptocurrencyMarket, r/SatoshiStreetBets | Cryptocurrency |\n| `stocks` | r/wallstreetbets, r/stocks, r/investing, r/StockMarket | US Equities |\n| `all` | Combined crypto + stocks subreddits | Multi-asset |\n\n资料来源：[src/tradingview_mcp/core/services/sentiment_service.py:1-50]()\n\n## API Reference\n\n### `analyze_sentiment`\n\nThe primary function for retrieving and analyzing Reddit sentiment.\n\n```python\ndef analyze_sentiment(\n symbol: str,\n category: str = \"all\",\n limit: int = 20,\n) -> dict:\n```\n\n#### Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `symbol` | `str` | Required | Asset ticker/name (e.g., \"AAPL\", \"BTC\", \"ETH\", \"TSLA\", \"THYAO\") |\n| `category` | `str` | `\"all\"` | Subreddit group: `\"crypto\"` \\| `\"stocks\"` \\| `\"all\"` |\n| `limit` | `int` | `20` | Total number of posts to analyze across all subreddits |\n\n#### Return Value\n\n```python\n{\n \"sentiment_score\": float, # -1.0 to +1.0\n \"sentiment_label\": str, # \"Bullish\" | \"Bearish\" | \"Neutral\"\n \"posts_analyzed\": int, # Total posts processed\n \"posts\": List[dict], # Individual post details\n \"top_posts\": List[dict], # Highest-impact posts\n}\n```\n\n#### Post Object Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `title` | `str` | Post title (truncated to 120 chars) |\n| `upvotes` | `int` | Reddit upvotes |\n| `comments` | `int` | Number of comments |\n| `sentiment` | `str` | Per-post sentiment label |\n\n资料来源：[src/tradingview_mcp/core/services/sentiment_service.py:50-100]()\n\n## Sentiment Scoring Algorithm\n\n### Scoring Logic\n\nThe `_score_text` function processes raw text and returns a score:\n\n```mermaid\ngraph LR\n A[Raw Text Input] --> B[Tokenize]\n B --> C[Keyword Matching]\n C --> D{Keyword Type}\n D -->|Bullish| E[Positive Increment]\n D -->|Bearish| F[Negative Increment]\n D -->|Neutral| G[Zero Score]\n E --> H[Normalize to -1...+1]\n F --> H\n G --> H\n```\n\n### Scoring Thresholds\n\n| Score Range | Label | Description |\n|-------------|-------|-------------|\n| `> 0.15` | **Bullish** | Strong positive community sentiment |\n| `0.05 to 0.15` | **Slightly Bullish** | Mild positive sentiment |\n| `-0.05 to 0.05` | **Neutral** | Balanced or unclear sentiment |\n| `-0.15 to -0.05` | **Slightly Bearish** | Mild negative sentiment |\n| `< -0.15` | **Bearish** | Strong negative community sentiment |\n\n资料来源：[src/tradingview_mcp/core/services/sentiment_service.py:30-50]()\n\n## Multi-Agent Integration\n\nThe sentiment analysis module is a critical component of the multi-agent trading framework:\n\n```mermaid\ngraph TD\n subgraph \"Multi-Agent System\"\n A[Technical Analyst] --> D[Debate & Score]\n B[Sentiment Analyst] --> D\n C[Risk Manager] --> D\n end\n \n subgraph \"Sentiment Analyst (B)\"\n B1[analyze_sentiment] --> B2[Momentum Calculation]\n B2 --> B3[Sentiment Score]\n B3 --> B4[Bullish/Bearish Label]\n end\n \n D --> E[Framework Decision]\n E --> F[STRONG BUY / BUY / HOLD / SELL / STRONG SELL]\n```\n\n### Multi-Agent Output\n\nThe framework combines signals from all three agents to produce:\n\n| Output | Description |\n|--------|-------------|\n| `decision` | Final trading recommendation |\n| `confidence` | Confidence level based on agent agreement |\n| `scores` | Individual agent scores |\n| `reasoning` | Brief explanation of the decision |\n\n资料来源：[src/tradingview_mcp/core/services/multi_agent_service.py]()\n\n## Confluence System\n\nThe confluence system combines technical analysis with sentiment to provide higher-confidence signals:\n\n### Signal Agreement Matrix\n\n| Technical Signal | Sentiment Signal | Confluence | Confidence |\n|------------------|------------------|------------|------------|\n| Bullish | Bullish | Technical confirmed by Sentiment | HIGH |\n| Bearish | Bearish | Technical confirmed by Sentiment | HIGH |\n| Bullish | Bearish | Technical conflicts with Sentiment | MIXED |\n| Bearish | Bullish | Technical conflicts with Sentiment | MIXED |\n\n资料来源：[src/tradingview_mcp/server.py:1-50]()\n\n### Implementation\n\n```python\ndef analyze_confluence(symbol, exchange, timeframe):\n tech = get_technical_analysis(symbol, exchange, timeframe)\n cat = \"crypto\" if exchange.upper() in [\"BINANCE\", \"KUCOIN\", \"BYBIT\", \"MEXC\"] else \"stocks\"\n sentiment = analyze_sentiment(symbol, category=cat)\n \n tech_momentum = tech.get(\"market_sentiment\", {}).get(\"momentum\", \"\")\n tech_bullish = tech_momentum == \"Bullish\"\n sent_bullish = sentiment.get(\"sentiment_score\", 0) > 0.1\n signals_agree = tech_bullish == sent_bullish\n confidence = \"HIGH\" if signals_agree else \"MIXED\"\n```\n\n资料来源：[src/tradingview_mcp/server.py:50-100]()\n\n## Exchange-Specific Behavior\n\nThe sentiment analysis module adapts its subreddit selection based on the target exchange:\n\n| Exchange Category | Exchange Examples | Sentiment Category | Subreddits Used |\n|-------------------|-------------------|-------------------|-----------------|\n| Crypto | BINANCE, KUCOIN, BYBIT, MEXC | `crypto` | Bitcoin, ethereum, CryptoCurrency, etc. |\n| Stocks | NASDAQ, NYSE | `stocks` | wallstreetbets, stocks, investing |\n| Emerging Markets | EGX, BIST | Auto-detected | Appropriate regional subreddits |\n\n资料来源：[src/tradingview_mcp/core/services/egx_sectors.py]()\n\n## OpenClaw Integration\n\nThe sentiment analysis can be accessed via the OpenClaw Telegram bot integration:\n\n### Available Commands\n\n```bash\nsentiment # Analyze Reddit sentiment for a symbol\n```\n\n### OpenClaw Trading Wrapper\n\nThe `openclaw/trading.py` wrapper provides CLI access to sentiment analysis:\n\n```python\nelif cmd == \"sentiment\":\n print(json.dumps(analyze_sentiment(args[0]), indent=2))\n```\n\n资料来源：[openclaw/trading.py:1-50]()\n\n## Usage Examples\n\n### Basic Sentiment Analysis\n\n```python\nfrom tradingview_mcp.core.services.sentiment_service import analyze_sentiment\n\n# Analyze Bitcoin sentiment\nresult = analyze_sentiment(symbol=\"BTC\", category=\"crypto\", limit=20)\n\nprint(f\"Sentiment Score: {result['sentiment_score']}\")\nprint(f\"Label: {result['sentiment_label']}\")\nprint(f\"Posts Analyzed: {result['posts_analyzed']}\")\n```\n\n### Confluence Analysis\n\n```python\nfrom tradingview_mcp.server import analyze_confluence\n\n# Full confluence analysis for Apple stock\nresult = analyze_confluence(\n symbol=\"AAPL\",\n exchange=\"NASDAQ\",\n timeframe=\"1D\"\n)\n\nprint(f\"Confidence: {result['confluence']['confidence']}\")\nprint(f\"Recommendation: {result['confluence']['recommendation']}\")\n```\n\n### Multi-Agent Decision\n\n```python\nfrom tradingview_mcp.core.services.multi_agent_service import multi_agent_analysis\n\n# Get full multi-agent analysis\ndecision = multi_agent_analysis(symbol=\"ETH\", exchange=\"KUCOIN\")\n\nprint(f\"Decision: {decision['decision']}\")\nprint(f\"Confidence: {decision['confidence']}\")\n```\n\n## Limitations and Considerations\n\n| Aspect | Limitation | Mitigation |\n|--------|------------|------------|\n| Data Source | Reddit only | Future Twitter/X integration planned (roadmap) |\n| Real-time | Reddit API rate limits | Configurable limit parameter |\n| Regional Markets | Limited non-English subreddits | Regional market focus |\n| Sentiment Quality | Keyword-based scoring | Multi-agent verification system |\n\n资料来源：[README.md:100-150]()\n\n## Roadmap\n\nPlanned enhancements for sentiment analysis:\n\n- [ ] **Twitter/X market sentiment** — Expand data sources beyond Reddit\n- [ ] **Walk-forward backtesting** — Test sentiment signals against historical data\n- [ ] **Multi-language support** — Analyze non-English social media\n- [ ] **Real-time streaming** — WebSocket-based sentiment updates\n\n资料来源：[README.md:150-180]()\n\n## See Also\n\n- [Technical Analysis](technical_analysis.md) — RSI, MACD, Bollinger Bands integration\n- [Multi-Agent Framework](multi_agent_framework.md) — Complete agent debate system\n- [Backtesting Engine](backtesting.md) — Strategy validation with sentiment signals\n- [OpenClaw Integration](openclaw_integration.md) — Telegram bot deployment\n\n---\n\n\n\n## Multi-Exchange Integration\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tradingview_mcp/coinlist](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/coinlist)\n- [src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n- [src/tradingview_mcp/core/services/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)\n- [src/tradingview_mcp/core/services/coinlist.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/coinlist.py)\n \n\n# Multi-Exchange Integration\n\n## Overview\n\nThe Multi-Exchange Integration module enables the tradingview-mcp framework to query and analyze financial instruments across multiple global exchanges. It provides a unified abstraction layer that routes market data requests to the appropriate TradingView screener endpoint based on exchange type, symbol format, and market classification.\n\nThe system supports:\n- **Cryptocurrency exchanges**: Binance, KuCoin, Bybit, MEXC\n- **US stock markets**: NASDAQ, NYSE, AMEX (including NYSEARCA, PCX aliases)\n- **Taiwan markets**: TWSE, TPEX\n- **Egyptian Exchange**: EGX\n- **Turkish market**: BIST\n\n资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"API Layer\"\n A[Server Tools] --> B[Request Validation]\n end\n \n subgraph \"Exchange Routing\"\n B --> C[validators.py]\n C --> D{symbol_type?}\n D -->|Stock| E[EXCHANGE_SCREENER]\n D -->|Crypto| F[Direct Exchange]\n E --> G[get_tv_exchange_prefix]\n F --> H[Exchange Aliases]\n end\n \n subgraph \"Data Sources\"\n G --> I[screener_service.py]\n H --> J[coinlist.py]\n I --> K[TradingView Screener API]\n J --> L[Symbol Lists]\n end\n \n subgraph \"Market-Specific Services\"\n K --> M[egx_service.py]\n L --> N[EGX Sectors]\n end\n```\n\n## Exchange Classification System\n\n### Core Exchange Types\n\nThe framework classifies exchanges into two primary categories: stock exchanges and cryptocurrency exchanges.\n\n| Classification | Description | Examples |\n|----------------|-------------|----------|\n| `stock` | Traditional stock markets with symbol-based trading | NASDAQ, NYSE, TWSE, TPEX, EGX, BIST |\n| `crypto` | Cryptocurrency exchanges with pair-based trading | KUCOIN, BINANCE, BYBIT, MEXC |\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n### Exchange Registry\n\nThe `EXCHANGE_SCREENER` set contains all exchanges that work with the TradingView screener API:\n\n```python\nEXCHANGE_SCREENER = {\n \"binance\", \"kucoin\", \"bybit\", \"mexc\",\n \"nasdaq\", \"nyse\", \"amex\", \"nysearca\", \"pcx\",\n \"twse\", \"tpex\", \"egx\", \"bist\"\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:1-20](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n## Symbol Construction and Exchange Prefixes\n\n### TradingView Symbol Format\n\nTradingView requires symbols to be prefixed with the exchange code in the format `EXCHANGE:SYMBOL`. The framework uses the `get_tv_exchange_prefix()` function to map exchange aliases to their canonical TradingView prefix.\n\n```python\n_EXCHANGE_TV_PREFIX: Dict[str, str] = {\n \"nysearca\": \"AMEX\",\n \"pcx\": \"AMEX\",\n \"tpex\": \"TWSE\",\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n### Exchange Prefix Resolution\n\n```mermaid\ngraph LR\n A[Exchange Input] --> B{sanitized lowercased}\n B --> C{Exact Match?}\n C -->|Yes| D[Return Prefix]\n C -->|No| E[Fallback: UPPERCASE]\n \n subgraph \"Known Aliases\"\n F[nysearca] --> D\n G[pcx] --> D\n H[tpex] --> D\n end\n```\n\nThe resolution logic:\n1. Input is trimmed and lowercased\n2. Lookup in `_EXCHANGE_TV_PREFIX` dictionary\n3. Returns mapped prefix or uppercase fallback for unknown exchanges\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n### Screener Symbol Construction\n\nIn `screener_service.py`, the `analyze_coin` function constructs full TradingView symbols:\n\n```python\ndef analyze_coin(symbol: str, exchange: str = \"KUCOIN\") -> dict:\n # Get the TradingView exchange prefix\n tv_exchange = get_tv_exchange_prefix(exchange)\n \n # Construct full symbol for TradingView API\n if is_stock_exchange(exchange):\n tv_symbol = f\"{tv_exchange}:{symbol.upper()}\"\n else:\n tv_symbol = f\"{symbol.upper()}\"\n```\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n\n## Exchange Alias System\n\n### AMEX Aliases\n\nThe framework normalizes several exchange identifiers to AMEX for ETF and commodity trading:\n\n| Alias | Canonical Name | Use Case |\n|-------|----------------|----------|\n| `AMEX` | AMEX | American Stock Exchange ETFs |\n| `NYSEARCA` | AMEX | NYSE Arca ETFs |\n| `PCX` | AMEX | Arca ETF notation |\n\n资料来源：[PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n\n### Taiwan Exchange Aliases\n\nTaiwan stock symbols are routed to TWSE with the TPEX alias for OTC trading:\n\n| Alias | Canonical Name | Market |\n|-------|----------------|--------|\n| `TWSE` | TWSE | Taiwan Stock Exchange |\n| `TPEX` | TWSE | Taipei Exchange (OTC) |\n\n资料来源：[PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n\n## Supported Exchanges by Market\n\n### Cryptocurrency Exchanges\n\n| Exchange | Symbol Format | Supported Tools |\n|----------|---------------|-----------------|\n| Binance | `SYMBOL` | top_gainers, top_losers, bollinger_scan, coin_analysis |\n| KuCoin | `SYMBOL` | All crypto tools |\n| Bybit | `SYMBOL` | All crypto tools |\n| MEXC | `SYMBOL` | All crypto tools (420+ pairs) |\n\n资料来源：[CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)\n\n### Stock Markets\n\n| Market | Exchange Code | Currency | Symbol Format |\n|--------|---------------|----------|---------------|\n| US Stocks (NASDAQ) | `NASDAQ` | USD | `NASDAQ:AAPL` |\n| US Stocks (NYSE) | `NYSE` | USD | `NYSE:TSLA` |\n| US ETFs (AMEX) | `AMEX` | USD | `AMEX:SPY` |\n| Taiwan (TWSE) | `TWSE` | TWD | `TWSE:2330` |\n| Taiwan (TPEX) | `TWSE` | TWD | `TWSE:0050` |\n| Egypt (EGX) | `EGX` | EGP/USD | `EGX:COMI` |\n| Turkey (BIST) | `BIST` | TRY | `BIST:THYAO` |\n\n资料来源：[src/tradingview_mcp/core/data/egx_sectors.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/data/egx_sectors.py)\n\n## Exchange-Specific Services\n\n### Screener Service\n\nThe `ScreenerService` class provides unified access to TradingView screener data across all supported exchanges:\n\n```python\nclass ScreenerService:\n def analyze_coin(self, symbol: str, exchange: str = \"KUCOIN\") -> dict:\n \"\"\"Analyze a coin/stock across multiple timeframes.\"\"\"\n \n def screen_stocks(self, exchange: str = \"NASDAQ\", \n signal: str = \"strong_buy\") -> list:\n \"\"\"Screen stocks by signal type on specified exchange.\"\"\"\n```\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n\n### Coinlist Service\n\nManages exchange-specific symbol lists for quick lookups:\n\n```python\nclass CoinlistService:\n def get_exchange_symbols(self, exchange: str) -> List[str]:\n \"\"\"Return available symbols for an exchange.\"\"\"\n \n def validate_symbol(self, symbol: str, exchange: str) -> bool:\n \"\"\"Check if symbol exists on exchange.\"\"\"\n```\n\n资料来源：[src/tradingview_mcp/core/services/coinlist.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/coinlist.py)\n\n### EGX Service\n\nSpecialized service for Egyptian Exchange with sector classification:\n\n```python\nclass EgxService:\n def get_egx_sectors(self) -> Dict[str, List[str]]:\n \"\"\"Return EGX symbols grouped by sector.\"\"\"\n \n def get_currency(self, symbol: str) -> str:\n \"\"\"Return 'USD' or 'EGP' for EGX symbol.\"\"\"\n```\n\n资料来源：[src/tradingview_mcp/core/services/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Validator\n participant ScreenerService\n participant TV_API\n \n Client->>Server: analyze_coin(\"2330\", \"TWSE\")\n Server->>Validator: sanitize_exchange(\"TWSE\")\n Validator-->>Server: \"twse\"\n \n Server->>Validator: get_tv_exchange_prefix(\"twse\")\n Validator-->>Server: \"TWSE\"\n \n Server->>Validator: is_stock_exchange(\"twse\")\n Validator-->>Server: True\n \n Server->>ScreenerService: analyze_coin(\"2330\", \"TWSE\")\n ScreenerService->>TV_API: GET /screener?exchange=TWSE&symbol=2330\n \n TV_API-->>ScreenerService: OHLCV data + indicators\n ScreenerService-->>Server: Analysis result\n Server-->>Client: Rich analysis object\n```\n\n## Exchange Validation Functions\n\n### sanitize_exchange()\n\nNormalizes exchange input and validates against supported exchanges:\n\n```python\ndef sanitize_exchange(ex: str, default: str = \"kucoin\") -> str:\n \"\"\"Sanitize and validate exchange name.\n \n Args:\n ex: Exchange name to sanitize\n default: Default exchange if validation fails\n \n Returns:\n Validated exchange name in lowercase\n \"\"\"\n if not ex:\n return default\n exs = ex.strip().lower()\n return exs if exs in EXCHANGE_SCREENER else default\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n### is_stock_exchange()\n\nDetermines if an exchange represents a traditional stock market:\n\n```python\ndef is_stock_exchange(exchange: str) -> bool:\n \"\"\"Return True if the exchange is a stock market (not crypto).\"\"\"\n return exchange.strip().lower() in STOCK_EXCHANGES\n```\n\nWhere `STOCK_EXCHANGES` contains:\n```python\nSTOCK_EXCHANGES = {\n \"nasdaq\", \"nyse\", \"amex\", \"nysearca\", \"pcx\",\n \"twse\", \"tpex\", \"egx\", \"bist\"\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n## Coinlist Directory Structure\n\nSymbol lists are stored in `src/tradingview_mcp/coinlist/`:\n\n```\nsrc/tradingview_mcp/coinlist/\n├── binance.txt\n├── kucoin.txt\n├── bybit.txt\n├── mexc.txt\n├── twse.txt\n├── tpex.txt\n├── egx.txt\n├── bist.txt\n└── ...\n```\n\nEach file contains one symbol per line for fast lookup without API calls.\n\n资料来源：[src/tradingview_mcp/coinlist](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/coinlist)\n\n## Adding New Exchange Support\n\n### Step 1: Update Validators\n\nAdd the exchange to the core registry in `validators.py`:\n\n```python\n# Add to EXCHANGE_SCREENER\nEXCHANGE_SCREENER.add(\"NEW_EXCHANGE\")\n\n# Add to STOCK_EXCHANGES or leave out for crypto\nSTOCK_EXCHANGES.add(\"NEW_EXCHANGE\")\n\n# Add prefix mapping if needed\n_EXCHANGE_TV_PREFIX[\"new_exchange\"] = \"NEW_EXCHANGE\"\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n\n### Step 2: Create Symbol List\n\nCreate `src/tradingview_mcp/coinlist/new_exchange.txt` with one symbol per line.\n\n### Step 3: Add Tests\n\nAdd unit tests in `tests/unit/test_exchange_fixes.py`:\n\n```python\ndef test_new_exchange_in_registry():\n assert \"new_exchange\" in EXCHANGE_SCREENER\n \ndef test_new_exchange_symbol_construction():\n prefix = get_tv_exchange_prefix(\"new_exchange\")\n assert prefix == \"NEW_EXCHANGE\"\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n### Step 4: Integration Test\n\n```python\nfrom tradingview_mcp.core.services.screener_service import ScreenerService\n\nservice = ScreenerService()\nresult = service.screen_stocks(exchange=\"NEW_EXCHANGE\")\n```\n\n## Testing\n\n### Unit Tests\n\nThe test suite covers exchange routing with 69 tests:\n\n```\n73 passed in 0.17s (69 new + 4 pre-existing)\n```\n\nKey test files:\n- `tests/unit/test_exchange_fixes.py` - Exchange routing tests (32 tests)\n- `tests/unit/test_exchange_aliases.py` - Alias resolution tests (37 tests)\n\n资料来源：[PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n\n### Test Coverage Areas\n\n| Test Category | Description |\n|---------------|-------------|\n| Alias Resolution | TWSE/TPEX → TWSE, NYSEARCA/PCX → AMEX |\n| Symbol Construction | Correct format for stock vs crypto |\n| Registry Integrity | All aliases in EXCHANGE_SCREENER and STOCK_EXCHANGES |\n| Regression | NYSE, NASDAQ, KUCOIN, BINANCE unchanged |\n\n## Configuration Options\n\n### Server Configuration\n\nExchange settings are configured at server startup:\n\n```python\n# In server.py\nexchange = sanitize_exchange(request.exchange or \"kucoin\")\ntv_exchange = get_tv_exchange_prefix(exchange)\nis_stock = is_stock_exchange(exchange)\n```\n\n### Tool Parameters\n\nMost analysis tools accept an `exchange` parameter:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `exchange` | string | `\"KUCOIN\"` | Exchange identifier |\n| `symbol` | string | required | Trading symbol |\n| `timeframe` | string | `\"1D\"` | Chart timeframe |\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| Symbol not found | Wrong exchange | Verify symbol exists on target exchange |\n| Empty results | Exchange not in screener | Check EXCHANGE_SCREENER |\n| Wrong prefix | Missing alias mapping | Add to `_EXCHANGE_TV_PREFIX` |\n\n### Debugging Steps\n\n1. Check if exchange is in `EXCHANGE_SCREENER`\n2. Verify symbol format matches exchange type\n3. Test symbol construction with `get_tv_exchange_prefix()`\n4. Validate against TradingView website directly\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: atilaahmettaner/tradingview-mcp\n\nSummary: Found 10 potential pitfall items; 2 are high/blocking. Highest priority: installation - 来源证据：Complement idea: \"What happened next?\" via Chart Library.\n\n## 1. installation · 来源证据：Complement idea: \"What happened next?\" via Chart Library\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Complement idea: \"What happened next?\" via Chart Library\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_b89762244f5e4c498064918f30cd560b | https://github.com/atilaahmettaner/tradingview-mcp/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. security_permissions · 涉及密钥、隐私或敏感领域\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: 项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。\n- User impact: 金融、交易、隐私和密钥场景必须比普通工具更保守。\n- Suggested check: 补敏感数据流、密钥存储和权限边界审查。\n- Guardrail action: 敏感领域或密钥场景必须保守推荐并要求人工复核。\n- Evidence: packet_text.keyword_scan | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | matched secret / private key / privacy / trading / finance keyword\n\n## 3. installation · 来源证据：[HELP] Installation Issue:\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[HELP] Installation Issue:\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_dcb256f998e14be785fa2c939b9dba56 | https://github.com/atilaahmettaner/tradingview-mcp/issues/24 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | host_targets=mcp_host, claude, cursor, chatgpt\n\n## 5. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | README/documentation is current enough for a first validation pass.\n\n## 6. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | last_activity_observed missing\n\n## 7. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n\n## 8. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n\n## 9. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | issue_or_pr_quality=unknown\n\n## 10. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "Human Manual"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log\n\nProject: atilaahmettaner/tradingview-mcp\n\nSummary: Found 10 potential pitfall items; 2 are high/blocking. Highest priority: installation - 来源证据：Complement idea: \"What happened next?\" via Chart Library.\n\n## 1. installation · 来源证据：Complement idea: \"What happened next?\" via Chart Library\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Complement idea: \"What happened next?\" via Chart Library\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_b89762244f5e4c498064918f30cd560b | https://github.com/atilaahmettaner/tradingview-mcp/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. security_permissions · 涉及密钥、隐私或敏感领域\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: 项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。\n- User impact: 金融、交易、隐私和密钥场景必须比普通工具更保守。\n- Suggested check: 补敏感数据流、密钥存储和权限边界审查。\n- Guardrail action: 敏感领域或密钥场景必须保守推荐并要求人工复核。\n- Evidence: packet_text.keyword_scan | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | matched secret / private key / privacy / trading / finance keyword\n\n## 3. installation · 来源证据：[HELP] Installation Issue:\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[HELP] Installation Issue:\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_dcb256f998e14be785fa2c939b9dba56 | https://github.com/atilaahmettaner/tradingview-mcp/issues/24 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | host_targets=mcp_host, claude, cursor, chatgpt\n\n## 5. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | README/documentation is current enough for a first validation pass.\n\n## 6. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | last_activity_observed missing\n\n## 7. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n\n## 8. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n\n## 9. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | issue_or_pr_quality=unknown\n\n## 10. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | release_recency=unknown\n",
"summary": "Identity, installation, configuration, runtime, and safety pitfalls before user trial.",
"title": "Pitfall Log"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# tradingview-mcp - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for atilaahmettaner/tradingview-mcp.\n\nProject:\n- Name: tradingview-mcp\n- Repository: https://github.com/atilaahmettaner/tradingview-mcp\n- Summary: 📈 AI Trading Intelligence Framework — MCP Server\n- Host target: mcp_host, claude, cursor, chatgpt\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: 📈 AI Trading Intelligence Framework — MCP Server\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Project Overview. Produce one small intermediate artifact and wait for confirmation.\n2. quick-start: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. mcp-protocol: MCP Protocol Integration. Produce one small intermediate artifact and wait for confirmation.\n5. service-architecture: Service Architecture. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/atilaahmettaner/tradingview-mcp#readme\n- openclaw/SKILL.md\n- README.md\n- pyproject.toml\n- EXAMPLES.md\n- assets/architecture.png\n- src/tradingview_mcp/server.py\n- src/tradingview_mcp/__init__.py\n- .codex-mcp.json\n- .codex-plugin/plugin.json\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start\n\nProject: atilaahmettaner/tradingview-mcp\n\n## Official Entry Points\n\n### Python / pip · 官方安装入口\n\n```bash\npip install tradingview-mcp-server\n```\n\nSource：https://github.com/atilaahmettaner/tradingview-mcp#readme\n\n## Sources\n\n- docs: https://github.com/atilaahmettaner/tradingview-mcp#readme\n",
"summary": "Entry points extracted from official README or installation documentation.",
"title": "Quick Start"
}
},
"validation_id": "dval_d0a13c0259ce4029b8f69af93297e9d3"
}