{
"canonical_name": "atilaahmettaner/tradingview-mcp",
"compilation_id": "pack_77e3985b7dc948da92ab128cef14dceb",
"created_at": "2026-05-11T19:50:37.294646+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": 563,
"github_stars": 2613,
"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": "Visual Workflow Orchestration",
"label_zh": "视觉工作流编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-visual-workflow-orchestration",
"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": "项目文本出现 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": "项目面向 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 sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | No sandbox install has been executed yet; downstream must verify before user use."
],
"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": "发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": null,
"forks": 563,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 2613,
"open_issues": 7,
"pushed_at": "2026-05-07T07:53:45.000Z"
},
"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> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 tradingview-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude / Cursor / chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-overview：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation-guide：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-components：核心组件。围绕“核心组件”模拟一次用户任务，不展示安装或运行结果。\n5. page-backtesting-engine：回测引擎。围绕“回测引擎”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-overview\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation-guide\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-components\n输入：用户提供的“核心组件”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-backtesting-engine\n输入：用户提供的“回测引擎”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-overview：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation-guide：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-components：Step 4 必须围绕“核心组件”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-backtesting-engine：Step 5 必须围绕“回测引擎”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/atilaahmettaner/tradingview-mcp#readme\n- openclaw/SKILL.md\n- README.md\n- pyproject.toml\n- CHANGELOG.md\n- INSTALLATION.md\n- .env.example\n- src/tradingview_mcp/server.py\n- src/tradingview_mcp/__init__.py\n- assets/architecture.png\n- src/tradingview_mcp/core/types.py\n- src/tradingview_mcp/core/portfolio.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 tradingview-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\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-11 19:46:48 UTC\n\n## 目录\n\n- [项目概览](#page-project-overview)\n- [安装指南](#page-installation-guide)\n- [系统架构](#page-architecture)\n- [核心组件](#page-core-components)\n- [回测引擎](#page-backtesting-engine)\n- [技术分析服务](#page-technical-analysis)\n- [情感分析与新闻服务](#page-sentiment-analysis)\n- [Yahoo Finance 集成](#page-yahoo-finance)\n- [数据源与货币列表](#page-data-sources)\n- [多交易所支持](#page-exchange-support)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation-guide), [系统架构](#page-architecture)\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- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n- [OPENCLAW.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/OPENCLAW.md)\n- [EXAMPLES.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/EXAMPLES.md)\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 \n\n# 项目概览\n\n## 什么是 tradingview-mcp\n\n**tradingview-mcp** 是一个基于 Model Context Protocol (MCP) 的服务器，专为 AI 助手（如 Claude Desktop、OpenClaw、Codex）提供金融市场数据访问能力。该项目充当 AI 与 TradingView、Yahoo Finance 等数据源之间的桥梁，使 AI 能够执行技术分析、选股扫描、情绪分析、回测策略等任务。 资料来源：[README.md:1-15]()\n\n该项目完全开源，采用 MIT 许可证，支持 Windows、macOS 和 Linux 多平台运行。开发者可以自由修改代码、集成新功能，或将其部署在个人服务器上。 资料来源：[README.md:LICENSE]()\n\n## 核心架构\n\ntradingview-mcp 采用模块化服务架构，核心组件包括以下几个部分：\n\n```mermaid\ngraph TD\n A[AI 助手
Claude/Codex/OpenClaw] --> B[MCP Server
server.py]\n B --> C[服务层]\n C --> D[screener_service
选股服务]\n C --> E[technical_service
技术分析服务]\n C --> F[sentiment_service
情绪分析服务]\n C --> G[news_service
新闻服务]\n C --> H[backtest_service
回测服务]\n C --> I[egx_service
埃及交易所服务]\n D --> J[TradingView API
tradingview_ta]\n E --> J\n G --> K[Reddit API]\n H --> J\n J --> L[Yahoo Finance]\n```\n\n### 目录结构\n\n```\nsrc/tradingview_mcp/\n├── server.py # MCP 主服务器入口\n├── core/\n│ ├── services/ # 核心业务逻辑服务\n│ │ ├── screener_service.py # 选股扫描服务\n│ │ ├── technical_service.py # 技术分析服务\n│ │ ├── sentiment_service.py # 情绪分析服务\n│ │ ├── news_service.py # 新闻服务\n│ │ ├── backtest_service.py # 回测服务\n│ │ └── egx_service.py # EGX 埃及交易所服务\n│ ├── utils/ # 工具函数\n│ │ └── validators.py # 验证器和常量定义\n│ └── indicators/ # 技术指标计算\n├── coinlist/ # 各交易所交易对列表\n└── __init__.py\n```\n\n资料来源：[CONTRIBUTING.md:代码组织]()\n\n## 核心功能\n\n### 技术分析引擎\n\ntradingview-mcp 提供超过 **30 种技术指标** 的实时计算能力，包括 RSI、MACD、布林带、EMA、SMA、ATR 等。每项指标都会生成对应的交易信号（BUY/SELL/HOLD）并附带评分。 资料来源：[README.md:技术分析核心]()\n\n| 指标类型 | 包含指标 |\n|---------|---------|\n| 趋势指标 | EMA、SMA、MACD、ADX、Ichimoku、Supertrend |\n| 动量指标 | RSI、CCI、 Stochastic、Momentum、ROC |\n| 波动性指标 | 布林带（BB）、ATR、 标准差 |\n| 成交量指标 | OBV、VWMA、Volume |\n\n### 选股扫描器\n\n支持多交易所的股票/加密货币筛选，可按涨幅、跌幅、技术信号等多种条件过滤：\n\n- `top_gainers` — 涨幅榜\n- `top_losers` — 跌幅榜 \n- `scan_by_signal` — 按信号类型筛选（超买、超卖、趋势、突破）\n- `screen_stocks` — 多条件组合筛选（支持 20+ 过滤条件） 资料来源：[README.md:筛选器]()\n\n### 回测引擎\n\n内置 **6 种交易策略** 的回测功能，支持机构级指标分析：\n\n| 策略名称 | 类型 | 说明 |\n|---------|------|------|\n| `rsi` | 均值回归 | RSI 超买超卖策略 |\n| `bollinger` | 均值回归 | 布林带策略 |\n| `macd` | 趋势 | MACD 金叉死叉 |\n| `ema_cross` | 趋势 | EMA 20/50 金叉死叉 |\n| `supertrend` | 趋势跟踪 | ATR-based Supertrend |\n| `donchian` | 趋势跟踪 | 唐奇安通道（海龟交易法则风格） |\n\n回测提供以下核心指标：\n\n- 胜率 (Win Rate)\n- 总收益率 (Total Return)\n- 夏普比率 (Sharpe Ratio)\n- 卡玛比率 (Calmar Ratio)\n- 最大回撤 (Max Drawdown)\n- 利润因子 (Profit Factor)\n- 期望值 (Expectancy) 资料来源：[README.md:回测引擎]()\n\n### 情绪与新闻分析\n\n| 功能 | 数据源 | 说明 |\n|-----|-------|------|\n| Reddit 情绪分析 | Reddit API | 分析 subreddits 帖子情绪 |\n| 实时新闻 | RSS 订阅源 | 财经新闻聚合 |\n| 蜡烛图形态识别 | TradingView | 识别 15 种 K 线形态 |\n\n资料来源：[README.md:情绪与新闻]()\n\n## 支持的交易所\n\ntradingview-mcp 支持全球多个主要交易所，涵盖加密货币和传统股票市场： 资料来源：[README.md:多交易所支持]()\n\n### 加密货币交易所\n\n| 交易所 | 代码 | 支持功能 |\n|-------|------|---------|\n| Binance | BINANCE | 全交易对筛选、技术分析 |\n| KuCoin | KUCOIN | 全交易对筛选、技术分析 |\n| Bybit+ | BYBIT | 全交易对筛选、技术分析 |\n| MEXC | MEXC | 全交易对筛选、技术分析 |\n\n### 传统股票市场\n\n| 交易所 | 代码 | 支持功能 |\n|-------|------|---------|\n| 纳斯达克 | NASDAQ | 美股筛选、技术分析 |\n| 纽约证券交易所 | NYSE | 美股筛选、技术分析 |\n| 纽约证券交易所高增长 | NYSEARCA | ETF 筛选 |\n| 美国证券交易所 | AMEX | 美股筛选 |\n| 台湾证券交易所 | TWSE | 台股筛选 |\n| 台湾柜台买卖中心 | TPEX | 台股筛选 |\n| 土耳其伊斯坦布尔证交所 | BIST | 土股筛选 |\n| 埃及证券交易所 | EGX | 专用 EGX 服务（Fibonacci、止损推荐等） |\n\n资料来源：[PR_BODY.md:TWSE和TPEX支持]()\n\n## 可用工具列表\n\n### 市场数据工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `yahoo_price` | 实时报价：价格、涨跌幅、52 周高低、市场状态 |\n| `market_snapshot` | 全球市场概览：标普 500、纳斯达克、BTC、EUR/USD 等 |\n| `get_prices_bulk` | 多标的批量价格查询 |\n\n### 技术分析工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `get_technical_analysis` | 完整技术分析：RSI、MACD、布林带等 23 项指标 |\n| `get_multiple_analysis` | 批量多标的分析 |\n| `get_bollinger_band_analysis` | 专有 ±3 布林带评级系统 |\n| `get_stock_decision` | 三层决策引擎（排名 + 交易设置 + 质量评分） |\n| `scan_by_signal` | 按信号类型扫描（超卖、趋势、突破...） |\n| `get_candlestick_patterns` | 15 种蜡烛图形态检测 |\n| `get_multi_timeframe_analysis` | 周线→日线→4H→1H→15m 多时间框架对齐分析 |\n| `consecutive_candles_scan` | 连续 K 线扫描（检测持续性涨跌） |\n\n### 回测工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `backtest_strategy` | 回测单一策略并输出机构级指标 |\n| `compare_strategies` | 对比全部 6 种策略在同一标的上，按表现排名 |\n\n### 情绪新闻工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `get_reddit_sentiment` | Reddit 指定主题情绪分析 |\n| `get_news` | 实时财经新闻 |\n\n### EGX 专用工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `egx_market_overview` | 埃及股市整体概览 |\n| `egx_stock_screener` | EGX 股票筛选器 |\n| `egx_trade_plan` | 止损/止盈推荐 |\n| `egx_fibonacci_retracement` | 斐波那契回撤分析 |\n\n资料来源：[README.md:完整工具列表]()\n\n## 安装方式\n\n### 方式一：Claude Desktop（推荐）\n\n在 `claude_desktop_config.json` 中添加配置：\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\nWindows 用户需使用完整路径：\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"%USERPROFILE%\\\\.local\\\\bin\\\\uvx.exe\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:Claude Desktop配置]()\n\n### 方式二：从源码安装\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资料来源：[INSTALLATION.md:本地开发设置]()\n\n### 方式三：通过 OpenClaw 连接 Telegram\n\ntradingview-mcp 可与 OpenClaw 集成，通过 Telegram、WhatsApp、Discord 等 20+ 平台访问：\n\n```\nTelegram → OpenClaw agent (AI model) → trading.py → tradingview-mcp → Yahoo Finance\n```\n\n资料来源：[OPENCLAW.md:工作原理]()\n\n## 开发指南\n\n### 开发环境搭建\n\n```bash\n# 安装依赖\nuv sync\n\n# 安装开发依赖\nuv sync --dev\n\n# 运行测试\nuv run pytest\n\n# 代码检查\nuv run ruff check\n\n# 类型检查\nuv run mypy src/\n```\n\n资料来源：[CONTRIBUTING.md:开发环境]()\n\n### 代码规范\n\n| 规范类型 | 要求 |\n|---------|------|\n| Python 风格 | 遵循 PEP 8 |\n| 代码格式化 | 使用 Ruff |\n| 类型注解 | 所有公共函数需添加类型提示 |\n| 文档字符串 | 公共函数和类必须包含 docstring |\n| 函数命名 | snake_case（如 `get_top_gainers`） |\n| 类命名 | PascalCase（如 `MarketAnalyzer`） |\n| 常量命名 | UPPER_SNAKE_CASE（如 `DEFAULT_LIMIT`） |\n\n资料来源：[CONTRIBUTING.md:代码规范]()\n\n### 添加新交易所\n\n1. 更新验证器中的交易所映射：\n ```python\n # src/tradingview_mcp/core/utils/validators.py\n EXCHANGE_SCREENER = {\n \"NEW_EXCHANGE\": \"screener_code\",\n }\n ```\n\n2. 添加交易对列表文件：\n ```bash\n echo \"BTCUSDT\\nETHUSDT\\n...\" > coinlist/new_exchange.txt\n ```\n\n3. 测试集成：\n ```python\n result = top_gainers(exchange=\"NEW_EXCHANGE\")\n ```\n\n资料来源：[CONTRIBUTING.md:添加新交易所]()\n\n### 测试覆盖\n\n项目要求测试覆盖率 >80%，需同时测试成功路径和错误路径。 资料来源：[CONTRIBUTING.md:测试覆盖]()\n\n## 版本管理\n\n项目遵循语义化版本规范 (Semantic Versioning)：\n\n| 版本类型 | 说明 | 示例 |\n|---------|------|------|\n| 主版本 (X.0.0) | 破坏性变更 | 2.0.0 |\n| 次版本 (0.X.0) | 新功能，向后兼容 | 1.1.0 |\n| 补丁版本 (0.0.X) | Bug 修复，向后兼容 | 1.0.1 |\n\n## 路线图\n\n| 功能 | 状态 |\n|-----|------|\n| TradingView 技术分析（30+ 指标） | ✅ 已完成 |\n| 多交易所筛选（Binance、KuCoin、美股等） | ✅ 已完成 |\n| Reddit 情绪分析 | ✅ 已完成 |\n| Yahoo Finance 实时价格 | ✅ 已完成 |\n| 回测引擎（6 种策略 + 机构指标） | ✅ 已完成 |\n| 前向优化回测（过拟合检测） | 🔄 开发中 |\n| Twitter/X 市场情绪 | 📋 计划中 |\n| 模拟交易 | 📋 计划中 |\n| 云端托管服务 | 📋 计划中 |\n\n资料来源：[README.md:路线图]()\n\n## 项目统计\n\n- **开源协议**: MIT License\n- **平台支持**: Windows、macOS、Linux\n- **Python 版本**: 3.13（推荐）\n- **包管理**: UV\n- **主要依赖**: tradingview_ta、requests、beautifulsoup4\n\n## 相关链接\n\n| 资源 | 链接 |\n|-----|------|\n| GitHub 仓库 | https://github.com/atilaahmettaner/tradingview-mcp |\n| 问题反馈 | https://github.com/atilaahmettaner/tradingview-mcp/issues |\n| 赞助项目 | https://github.com/sponsors/atilaahmettaner |\n\n---\n\n\n\n## 安装指南\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.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- [PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n \n\n# 安装指南\n\n## 概述\n\n`tradingview-mcp` 是一个连接 TradingView 金融数据与 AI 代理的 MCP（Model Context Protocol）服务器项目。该项目支持实时市场数据、技术指标分析、加密货币筛选、股票筛选、回测等功能。\n\n安装指南涵盖了三种主要的安装方式：快速启动（Claude Desktop）、本地开发环境配置、以及传统的 Python 虚拟环境安装。同时支持 Windows、macOS 和 Linux 三大平台。\n\n## 系统架构\n\n```mermaid\ngraph TD\n A[用户 AI 客户端] --> B[MCP Server]\n B --> C[tradingview-mcp 核心]\n C --> D[TradingView API]\n C --> E[Yahoo Finance API]\n C --> F[Reddit API]\n C --> G[RSS 新闻源]\n \n H[Claude Desktop] --> B\n I[Codex] --> B\n J[OpenClaw] --> B\n```\n\n## 前置条件\n\n### 必要软件\n\n| 软件 | 版本要求 | 用途 |\n|------|----------|------|\n| Python | 3.13+ | 运行环境 |\n| Git | 最新版 | 代码版本管理 |\n| UV | 最新版 | 包管理器（推荐） |\n\n### UV 包管理器安装\n\nUV 是一个高性能的 Python 包管理器，建议优先使用。\n\n**Windows PowerShell：**\n```powershell\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n资料来源：[INSTALLATION.md:2]()\n\n**macOS/Linux：**\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\n```\n资料来源：[OPENCLAW.md:7]()\n\n## 安装方法一：快速启动（Claude Desktop）\n\n这是最简便的安装方式，适合不想修改代码只想直接使用工具的用户。\n\n### 步骤 1：克隆仓库\n\n```powershell\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n```\n资料来源：[INSTALLATION.md:6-7]()\n\n### 步骤 2：安装依赖\n\n```powershell\nuv sync\n```\n资料来源：[INSTALLATION.md:9]()\n\n### 步骤 3：配置 Claude Desktop\n\n定位配置文件路径：\n\n| 操作系统 | 路径 |\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\nWindows 用户可按 `Win + R`，输入 `%APPDATA%\\Claude` 并回车快速访问。\n\n### 步骤 4：编辑配置文件\n\n在 `claude_desktop_config.json` 中添加以下配置（将 `YOUR_USERNAME` 替换为实际用户名）：\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资料来源：[INSTALLATION.md:15-20]()\n\n### 步骤 5：验证安装\n\n1. 完全退出 Claude Desktop\n2. 重新启动应用程序\n3. 等待初始化完成（首次启动可能需要 30-60 秒）\n4. 询问 Claude：`\"Can you show me the available TradingView tools?\"`\n\n预期应看到以下工具：\n- `top_gainers`\n- `top_losers`\n- `bollinger_scan`\n- `coin_analysis`\n- `consecutive_candles_scan`\n\n## 安装方法二：本地开发环境\n\n适用于需要修改代码或进行二次开发的用户。\n\n### 标准开发流程\n\n```bash\n# 克隆仓库\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n\n# 安装依赖\nuv sync\n\n# 安装开发依赖\nuv sync --dev\n```\n资料来源：[CONTRIBUTING.md:6-12]()\n\n### 测试服务器\n\n```bash\n# 直接运行服务器\nuv run python src/tradingview_mcp/server.py\n\n# 使用 MCP Inspector 测试\nuv run mcp dev src/tradingview_mcp/server.py\n\n# 运行集成测试\nuv run python test_api.py\n```\n资料来源：[CONTRIBUTING.md:14-20]()\n\n### Claude Desktop 配置（本地开发）\n\n**Windows：**\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"C:\\\\Users\\\\YourUsername\\\\tradingview-mcp\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\"C:\\\\Users\\\\YourUsername\\\\tradingview-mcp\\\\src\\\\tradingview_mcp\\\\server.py\"],\n \"cwd\": \"C:\\\\Users\\\\YourUsername\\\\tradingview-mcp\"\n }\n }\n}\n```\n\n**macOS/Linux：**\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资料来源：[INSTALLATION.md:53-73]()\n\n## 安装方法三：Python 虚拟环境\n\n适用于偏好传统 Python 环境的用户。\n\n### Windows\n\n```powershell\n# 克隆仓库\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n\n# 创建虚拟环境\npython -m venv .venv\n.\\.venv\\Scripts\\activate\n\n# 安装依赖\npip install -e .\n\n# 运行服务器\npython src/tradingview_mcp/server.py\n```\n资料来源：[INSTALLATION.md:91-100]()\n\n### macOS/Linux\n\n```bash\n# 克隆仓库\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n\n# 创建虚拟环境\npython -m venv .venv\nsource .venv/bin/activate\n\n# 安装依赖\npip install -e .\n\n# 运行服务器\npython src/tradingview_mcp/server.py\n```\n\n## Codex 插件安装\n\n该项目包含专门的 Codex 插件元数据配置：\n\n- `.codex-plugin/plugin.json`\n- `.codex-mcp.json`\n\n### Codex 配置\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n资料来源：[README.md:90-99]()\n\n启用插件后需重启 Codex 以加载 MCP 服务器。\n\n## OpenClaw 集成安装\n\nOpenClaw 允许通过 Telegram、WhatsApp、Discord 等 20+ 消息平台连接本服务。\n\n### 工作原理\n\n```mermaid\ngraph LR\n A[Telegram/WhatsApp] --> B[OpenClaw Agent]\n B --> C[AI 模型]\n C --> D[trading.py wrapper]\n D --> E[tradingview-mcp]\n E --> F[Yahoo Finance]\n```\n\n### 安装步骤\n\n```bash\n# 安装 uv\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\n\n# 安装 tradingview-mcp-server\nuv tool install tradingview-mcp-server\n```\n资料来源：[OPENCLAW.md:4-10]()\n\n### Telegram 配置\n\n创建或编辑 `~/.openclaw/openclaw.json`：\n\n```json5\n{\n channels: {\n telegram: {\n botToken: \"YOUR_BOT_TOKEN_HERE\",\n },\n },\n}\n```\n\n### 下载交易工具\n\n```bash\nmkdir -p ~/.agents/skills/tradingview-mcp ~/.openclaw/tools\n\n# 下载 TradingView skill\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/SKILL.md \\\n -o ~/.agents/skills/tradingview-mcp/SKILL.md\n\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资料来源：[OPENCLAW.md:18-28]()\n\n### 启动 OpenClaw\n\n```bash\nopenclaw gateway install\nsystemctl --user start openclaw-gateway.service\nopenclaw doctor\n```\n\n## 平台特定说明\n\n### Windows 注意事项\n\n| 问题 | 解决方案 |\n|------|----------|\n| 直接 Python 路径更可靠 | 使用 `.venv\\Scripts\\python.exe` 而非 `uvx` |\n| 首次启动超时 | 检查 `%APPDATA%\\Claude\\logs` 中的详细日志 |\n| 路径分隔符 | 使用反斜杠 `\\` 或双斜杠 `\\\\` |\n\n**Windows 用户请注意：** 将 `YourUsername` 替换为实际的 Windows 用户名，并根据实际情况调整路径。\n\n### macOS 注意事项\n\n使用 uvx 时需指定完整路径：\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"/Users/YOUR_USERNAME/.local/bin/uvx\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n资料来源：[README.md:66-72]()\n\n### Linux 注意事项\n\n路径格式为 `/home/YOUR_USERNAME`：\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## 故障排除\n\n### Windows 首次启动超时错误\n\n**症状：** 在 Claude Desktop 日志中看到 `MCP error -32001: Request timed out`\n\n**解决方案：**\n1. 使用直接 Python 路径替代 uvx\n2. 首次启动等待 30-60 秒\n3. 检查防火墙和网络设置\n\n### uvx 找不到\n\n**Windows：** 使用 `%USERPROFILE%\\.local\\bin\\uvx.exe`\n\n**macOS：** 使用 `/Users/YOUR_USERNAME/.local/bin/uvx`\n\n**Linux：** 使用 `/home/YOUR_USERNAME/.local/bin/uvx`\n\n### 预热缓存（可选优化）\n\n在启动 Claude Desktop 前预先安装可加快首次响应速度：\n\n```bash\nuv tool install --python 3.13 tradingview-mcp-server\n```\n资料来源：[README.md:56-62]()\n\n## 验证清单\n\n| 检查项 | 预期结果 |\n|--------|----------|\n| 服务启动 | 无错误日志 |\n| MCP 连接 | Claude Desktop 显示连接成功 |\n| 工具列表 | 返回 20+ TradingView 工具 |\n| 数据获取 | 成功获取实时价格或分析数据 |\n\n## 开发环境测试\n\n```bash\n# 运行测试套件\nuv run pytest\n\n# 运行代码检查\nuv run ruff check\n\n# 运行类型检查\nuv run mypy src/\n```\n资料来源：[CONTRIBUTING.md:14-16]()\n\n## 目录结构\n\n```\ntradingview-mcp/\n├── src/tradingview_mcp/\n│ ├── server.py # 主 MCP 服务器\n│ ├── core/ # 核心业务逻辑\n│ │ ├── services/ # 市场数据服务\n│ │ ├── utils/ # 工具函数\n│ │ └── indicators/ # 技术指标\n│ └── coinlist/ # 交易所符号列表\n├── tests/ # 测试文件\n├── openclaw/ # OpenClaw 集成\n├── .codex-plugin/ # Codex 插件元数据\n└── pyproject.toml # 项目配置\n```\n资料来源：[CONTRIBUTING.md:26-34]()\n\n## 后续步骤\n\n安装完成后，可尝试以下操作：\n\n1. **获取市场快照：** 询问 `\"Give me a full market snapshot right now\"`\n2. **技术分析：** 使用 `get_technical_analysis` 分析具体股票或加密货币\n3. **回测策略：** 使用 `backtest_strategy` 测试交易策略表现\n4. **市场筛选：** 使用 `top_gainers` 或 `screen_stocks` 筛选标的\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心组件](#page-core-components), [回测引擎](#page-backtesting-engine)\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- [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/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\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- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n \n\n# 系统架构\n\n## 概述\n\ntradingview-mcp 是一个基于 Model Context Protocol (MCP) 的服务器项目，旨在为 AI 助手提供 TradingView 金融市场的数据访问能力。该项目通过 MCP 协议将 TradingView 的技术分析、市场筛选、价格查询等功能封装为可调用的工具，使 AI 代理能够获取实时市场数据并进行技术分析决策。\n\n项目采用模块化架构设计，核心业务逻辑集中在 `src/tradingview_mcp/core/` 目录下，分为服务层（services）、工具层（utils）和指标层（indicators）。资料来源：[CONTRIBUTING.md]()\n\n## 架构分层\n\n系统采用经典的三层架构模式，各层职责明确、边界清晰：\n\n```mermaid\ngraph TD\n A[MCP 客户端
Claude Desktop / Codex] --> B[MCP 服务器层
server.py]\n B --> C[业务逻辑层
core/services]\n B --> D[工具层
core/utils]\n C --> E[数据源
tradingview_ta
Yahoo Finance]\n C --> F[指标计算层
core/indicators]\n```\n\n### MCP 服务器层\n\nMCP 服务器层是整个系统的入口点，负责处理 MCP 协议通信并将客户端请求路由到相应的业务逻辑。\n\n**核心职责：**\n- 初始化 MCP 服务器并注册所有工具\n- 处理请求参数验证和错误处理\n- 返回格式化的 JSON 响应\n\n**主要组件：**\n\n| 组件 | 文件路径 | 描述 |\n|------|----------|------|\n| 服务器入口 | `src/tradingview_mcp/server.py` | MCP 服务器主程序 |\n| 工具注册 | server.py | 使用 `@server.list_tool()` 装饰器注册工具 |\n\n资料来源：[src/tradingview_mcp/server.py]()\n\n### 业务逻辑层\n\n业务逻辑层位于 `src/tradingview_mcp/core/services/` 目录下，包含核心的数据处理和业务规则。\n\n**服务模块：**\n\n| 服务名称 | 文件 | 核心功能 |\n|----------|------|----------|\n| ScreenerService | screener_service.py | 市场筛选、技术指标计算、K线形态分析 |\n| ExchangeValidator | validators.py | 交易所名称验证和前缀处理 |\n\n**核心数据结构：**\n\n```python\n# 多时间框架数据结构\nMultiRow(symbol=str, changes=dict, base_indicators=IndicatorMap)\n\n# 指标映射结构\nIndicatorMap(open, close, SMA20, BB_upper, BB_lower, volume)\n```\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py:1-50]()\n\n### 工具层\n\n工具层位于 `src/tradingview_mcp/core/utils/` 目录下，提供数据验证、格式化和辅助功能。\n\n**核心工具：**\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `sanitize_exchange()` | 验证并标准化交易所名称 |\n| `sanitize_timeframe()` | 验证并标准化时间周期 |\n| `is_stock_exchange()` | 判断是否为股票交易所 |\n| `get_tv_exchange_prefix()` | 获取 TradingView 交易所前缀 |\n| `get_market_type()` | 获取市场类型 |\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n## 核心组件设计\n\n### 交易所验证器\n\n交易所验证器是系统的关键组件，负责将用户输入的交易所名称映射到 TradingView 可识别的格式。\n\n**交易所映射表：**\n\n| 用户输入 | 内部存储 | TradingView 前缀 |\n|----------|----------|------------------|\n| NYSEARCA | nysearca | AMEX |\n| PCX | pcx | AMEX |\n| AMEX | amex | AMEX |\n| NYSE | nyse | NYSE |\n| NASDAQ | nasdaq | NASDAQ |\n| TWSE | twse | TWSE |\n| TPEX | tpex | TPEX |\n| KUCOIN | kucoin | KUCOIN |\n| BINANCE | binance | BINANCE |\n\n**关键函数实现：**\n\n```python\ndef get_tv_exchange_prefix(exchange: str) -> str:\n \"\"\"将交易所名称转换为 TradingView 格式前缀\"\"\"\n return _EXCHANGE_TV_PREFIX.get(exchange.strip().lower(), exchange.upper())\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n### 技术指标计算器\n\n技术指标计算器集成在 screener_service.py 中，支持 30+ 技术指标的计算。\n\n**支持的指标类型：**\n\n| 指标类别 | 具体指标 |\n|----------|----------|\n| 趋势指标 | SMA、EMA、MACD、Supertrend、Donchian |\n| 动量指标 | RSI、CCI、ADX |\n| 波动率指标 | Bollinger Bands、ATR、Standard Deviation |\n| 成交量指标 | OBV、Volume、Volume Profile |\n\n**K线形态识别：**\n\n系统内置 15 种 K 线形态识别模式，通过 `calculate_candle_pattern_score()` 函数进行评分计算。\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py:40-80]()\n\n## 数据流架构\n\n### 请求处理流程\n\n```mermaid\ngraph LR\n A[用户请求] --> B[参数验证
sanitize_exchange]\n B --> C[交易所映射
get_tv_exchange_prefix]\n C --> D[TradingView API
tradingview_ta]\n D --> E[数据解析
IndicatorMap]\n E --> F[指标计算
technical_analysis]\n F --> G[结果格式化
JSON Response]\n```\n\n### 数据源集成\n\n系统支持多个数据源，以满足不同市场的数据需求：\n\n| 数据源 | 用途 | 数据类型 |\n|--------|------|----------|\n| TradingView (tradingview_ta) | 技术分析、K线数据 | 30+ 指标、价格数据 |\n| Yahoo Finance | 实时价格、市场快照 | 实时报价、52 周高低 |\n\n资料来源：[README.md]()\n\n## 工具生态\n\n### MCP 工具分类\n\n| 类别 | 工具数量 | 代表工具 |\n|------|----------|----------|\n| 市场数据 | 5+ | `yahoo_price`, `market_snapshot`, `get_prices_bulk` |\n| 技术分析 | 7+ | `get_technical_analysis`, `get_bollinger_band_analysis` |\n| 市场筛选 | 4+ | `top_gainers`, `top_losers`, `screen_stocks` |\n| 形态识别 | 2+ | `get_candlestick_patterns`, `scan_by_signal` |\n| 回测系统 | 6+ | `backtest_strategy`, `compare_strategies` |\n\n资料来源：[README.md]()\n\n### 交易所支持矩阵\n\n| 交易所 | 代码 | 支持功能 |\n|--------|------|----------|\n| Binance | BINANCE | 加密货币全品种 |\n| KuCoin | KUCOIN | 加密货币筛选 |\n| Bybit | BYBIT | 加密货币筛选 |\n| MEXC | MEXC | 加密货币筛选 |\n| NASDAQ | NASDAQ | 美国股票 |\n| NYSE | NYSE | 美国股票 |\n| NYSE ARCA | NYSEARCA | ETF、黄金、白银 |\n| AMEX | AMEX | 美国股票 |\n| TWSE | TWSE | 台湾股票 |\n| TPEX | TPEX | 台湾兴柜 |\n| EGX | EGX | 埃及股票 |\n| BIST | BIST | 土耳其股票 |\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n## 项目结构\n\n```\ntradingview-mcp/\n├── src/tradingview_mcp/\n│ ├── __init__.py # 包初始化\n│ ├── server.py # MCP 服务器入口\n│ ├── core/\n│ │ ├── services/ # 业务服务层\n│ │ │ └── screener_service.py\n│ │ ├── utils/ # 工具函数\n│ │ │ └── validators.py\n│ │ └── indicators/ # 技术指标\n│ ├── coinlist/ # 交易所符号列表\n│ └── ... # 其他模块\n├── tests/\n│ └── unit/ # 单元测试\n├── assets/\n│ └── architecture.png # 架构图\n└── pyproject.toml # 项目配置\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 安装与部署架构\n\n### 部署模式\n\n系统支持多种部署方式，以适应不同的使用场景：\n\n| 部署方式 | 适用场景 | 配置复杂度 |\n|----------|----------|------------|\n| PyPI 安装 | 生产环境快速部署 | 低 |\n| 源码开发 | 需要修改代码 | 中 |\n| OpenClaw 集成 | Telegram/WhatsApp 接入 | 中 |\n| Claude Desktop | 个人使用 | 低 |\n\n### Claude Desktop 配置\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资料来源：[INSTALLATION.md]()\n\n## 扩展机制\n\n### 添加新交易所\n\n1. 在 `validators.py` 的 `EXCHANGE_SCREENER` 中添加交易所代码\n2. 在 `_EXCHANGE_TV_PREFIX` 中添加前缀映射\n3. 如需符号列表，在 `coinlist/` 目录添加对应文件\n\n### 添加新指标\n\n1. 在 `core/indicators/` 目录创建指标计算函数\n2. 在 `screener_service.py` 中集成新指标\n3. 更新工具返回值结构\n\n资料来源：[CONTRIBUTING.md]()\n\n## 测试架构\n\n系统采用多层次测试策略确保代码质量：\n\n| 测试类型 | 覆盖范围 | 测试工具 |\n|----------|----------|----------|\n| 单元测试 | 独立函数、工具函数 | pytest |\n| 集成测试 | API 调用、数据流 | pytest + 实际 API |\n| Linting | 代码风格 | ruff |\n| 类型检查 | 类型注解 | mypy |\n\n**测试命令：**\n\n```bash\nuv run pytest # 运行测试套件\nuv run ruff check # 代码风格检查\nuv run mypy src/ # 类型检查\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 安全考量\n\n### 敏感数据处理\n\n- API 密钥不存储在代码仓库中\n- 通过环境变量或配置文件注入\n- Claude Desktop 配置中的凭证需妥善保管\n\n### 输入验证\n\n所有用户输入均通过验证器进行清理：\n\n```python\nexchange = sanitize_exchange(user_input) # 防止注入攻击\ntimeframe = sanitize_timeframe(user_input) # 防止恶意时间周期\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n## 版本管理\n\n项目遵循语义化版本控制 (Semantic Versioning)：\n\n| 版本类型 | 触发条件 |\n|----------|----------|\n| Major (X.0.0) | 破坏性 API 变更 |\n| Minor (0.X.0) | 新增功能，向后兼容 |\n| Patch (0.0.X) | Bug 修复，向后兼容 |\n\n资料来源：[CONTRIBUTING.md]()\n\n## 相关资源\n\n- 官方文档：[GitHub Repository](https://github.com/atilaahmettaner/tradingview-mcp)\n- 问题反馈：[Issue Tracker](https://github.com/atilaahmettaner/tradingview-mcp/issues)\n- 赞助项目：[GitHub Sponsors](https://github.com/sponsors/atilaahmettaner)\n\n---\n\n\n\n## 核心组件\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [技术分析服务](#page-technical-analysis)\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- [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/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\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- [PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n \n\n# 核心组件\n\n## 概述\n\n`tradingview-mcp` 是一个基于 Model Context Protocol (MCP) 的交易分析工具，通过 MCP 协议与 Claude Desktop、Codex 等 AI 助手集成，为用户提供实时市场数据、技术分析和交易策略回测功能。\n\n核心组件架构遵循模块化设计原则，将业务逻辑、数据服务、工具函数分离，便于维护和扩展。\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n## 系统架构\n\n```mermaid\ngraph TD\n A[MCP Client
Claude Desktop/Codex] --> B[MCP Server
server.py]\n B --> C[核心业务逻辑层]\n C --> D[Services
数据服务层]\n C --> E[Indicators
指标计算层]\n C --> F[Utils
工具函数层]\n D --> G[TradingView API]\n D --> H[Yahoo Finance API]\n D --> I[Reddit/News RSS]\n```\n\n### 目录结构\n\n```\nsrc/tradingview_mcp/\n├── server.py # MCP 主服务器入口\n├── core/ # 核心业务逻辑\n│ ├── services/ # 市场数据服务\n│ │ ├── screener_service.py # 筛选器服务\n│ │ └── egx_service.py # 埃及交易所服务\n│ ├── utils/ # 工具函数\n│ │ └── validators.py # 验证器\n│ └── indicators/ # 技术指标\n├── coinlist/ # 交易所符号列表\n└── __init__.py\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n## MCP 服务器 (server.py)\n\n`server.py` 是整个项目的入口点，负责：\n\n1. **注册 MCP 工具** - 将所有分析功能暴露为 AI 可调用的工具\n2. **处理请求路由** - 将客户端请求分发到对应的服务层\n3. **返回格式化结果** - 将数据分析结果转换为可读格式\n\n### 主要工具类别\n\n| 类别 | 工具数量 | 功能描述 |\n|------|---------|---------|\n| 市场数据 | 5+ | 实时价格、行情快照、多交易所支持 |\n| 技术分析 | 7+ | RSI、MACD、布林带等30+指标 |\n| 筛选器 | 6+ | 按涨跌幅、信号类型筛选标的 |\n| 回测引擎 | 2 | 6种策略回测与对比 |\n| 情绪分析 | 2 | Reddit情绪、新闻摘要 |\n\n资料来源：[README.md:1-50](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n## 验证器模块 (validators.py)\n\n`validators.py` 负责交易所标识符的规范化处理，是多交易所支持的核心基础设施。\n\n### 核心功能\n\n#### 1. 交易所名称规范化\n\n```python\nsanitize_exchange(exchange: str) -> str\n```\n\n将用户输入的交易所别名转换为标准名称：\n\n| 输入别名 | 输出标准名 | 用途 |\n|---------|-----------|------|\n| `AMEX` | `AMEX` | 美国股票 |\n| `NYSEARCA` | `AMEX` | AMEX 交易所 |\n| `PCX` | `AMEX` | Polygon 分类 |\n| `NYSE` | `NYSE` | 纽约证券交易所 |\n| `NASDAQ` | `NASDAQ` | 纳斯达克 |\n| `KUCOIN` | `KUCOIN` | KuCoin 交易所 |\n\n#### 2. TradingView 前缀映射\n\n```python\nget_tv_exchange_prefix(exchange: str, symbol: str) -> str\n```\n\n为符号生成正确的 TradingView 交易所前缀格式：\n\n- 股票符号：`AMEX:GDX` → `AMEX:GDX`\n- 加密货币：`KUCOIN:SOLUSDT` → `KUCOIN:SOLUSDT`\n\n#### 3. 支持的交易所配置\n\n```python\nSTOCK_EXCHANGES = {\"NYSE\", \"NASDAQ\", \"AMEX\", \"TWSE\", \"TPEX\"}\nEXCHANGE_SCREENER = {\n \"NYSE\": \"NYSE\",\n \"NASDAQ\": \"NASDAQ\", \n \"AMEX\": \"AMEX\",\n \"KUCOIN\": \"Crypto\",\n \"BINANCE\": \"Crypto\",\n \"TWSE\": \"Taiwan\",\n \"TPEX\": \"Taiwan\"\n}\n```\n\n资料来源：[PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n\n## 筛选器服务 (screener_service.py)\n\n`screener_service.py` 实现市场数据筛选和技术分析功能。\n\n### 核心数据结构\n\n```python\nclass IndicatorMap:\n \"\"\"技术指标数据映射\"\"\"\n open: float\n close: float\n SMA20: float\n BB_upper: float\n BB_lower: float\n volume: float\n\nclass MultiRow:\n \"\"\"多周期行数据\"\"\"\n symbol: str\n changes: dict # 各周期涨跌幅\n base_indicators: IndicatorMap\n```\n\n### 主要分析函数\n\n#### 1. 蜡烛图形态评分\n\n```python\ndef calculate_candle_pattern_score(\n indicators: dict,\n pattern_length: int,\n min_increase: float,\n) -> dict\n```\n\n评估蜡烛图形态强度，考虑因素：\n\n- **实体比例** - 开盘价与收盘价的差异\n- **动量** - 价格变化幅度\n- **成交量** - 交易量确认\n- **RSI** - 相对强弱指标\n\n返回结构：\n```python\n{\n \"detected\": bool, # 是否检测到形态\n \"score\": int, # 形态强度评分\n \"details\": list, # 详细分析\n \"rsi\": float # RSI 值\n}\n```\n\n#### 2. 多周期分析\n\n支持的时间周期：\n\n| 周期代码 | 描述 |\n|---------|------|\n| `1m` | 1分钟 |\n| `5m` | 5分钟 |\n| `15m` | 15分钟 |\n| `1h` | 1小时 |\n| `4h` | 4小时 |\n| `1D` | 日线 |\n| `1W` | 周线 |\n\n资料来源：[screener_service.py:1-80](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n\n## 埃及交易所服务 (egx_service.py)\n\n`egx_service.py` 专门处理埃及证券交易所 (EGX) 的数据和分析需求。\n\n### 主要功能\n\n#### 1. EGX 股票筛选器\n\n基于动量和质量评分的股票筛选：\n\n| 评分维度 | 阈值 | 说明 |\n|---------|------|------|\n| 动量评分 (ss) | ≥70 | 价格动能强度 |\n| 质量评分 (tq) | ≥65 | 财务质量指标 |\n| 相对强度 (rr2) | ≥2.0 | 行业相对表现 |\n\n#### 2. 推荐等级\n\n| 推荐等级 | 条件 | 含义 |\n|---------|------|------|\n| `QUALIFIED` | ss≥70 AND tq≥65 AND rr2≥2.0 | 强烈推荐 |\n| `CONDITIONAL` | ss≥70 AND tq≥50 | 有条件推荐 |\n| `WATCHLIST` | ss≥55 | 关注观察 |\n| `AVOID` | 其他 | 不建议 |\n\n#### 3. 斐波那契回撤分析\n\n```python\ndef analyze_egx_fibonacci(\n symbol: str,\n lookback: str = \"52W\",\n timeframe: str = \"1D\",\n) -> dict\n```\n\n支持回溯周期：\n\n- `1M` - 1个月\n- `3M` - 3个月\n- `6M` - 6个月\n- `52W` - 52周（默认）\n- `ALL` - 全时段\n\n资料来源：[egx_service.py:1-100](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)\n\n## 命名规范\n\n项目遵循统一的命名约定，确保代码可读性：\n\n| 类型 | 规范 | 示例 |\n|-----|------|------|\n| 函数 | `snake_case` | `get_top_gainers` |\n| 类 | `PascalCase` | `MarketAnalyzer` |\n| 常量 | `UPPER_SNAKE_CASE` | `DEFAULT_LIMIT` |\n| 文件 | `snake_case.py` | `market_utils.py` |\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n## 工具注册与调用流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant MCP as MCP Server\n participant Service as Service Layer\n participant API as External API\n \n User->>MCP: \"分析 BTC-USDT 的技术指标\"\n MCP->>MCP: 路由到 get_technical_analysis\n MCP->>Service: 调用 screener_service\n Service->>API: TradingView Screener API\n API-->>Service: 原始指标数据\n Service-->>MCP: 计算后的分析结果\n MCP-->>User: 格式化响应\n```\n\n## 依赖关系\n\n项目依赖以下核心包：\n\n| 包名 | 用途 | 来源 |\n|-----|------|------|\n| `tradingview_ta` | TradingView 技术分析 | PyPI |\n| `yfinance` | Yahoo Finance 数据 | PyPI |\n| `mcp` | MCP 协议实现 | PyPI |\n| `fastapi` | HTTP 服务框架 | PyPI |\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n## 扩展指南\n\n### 添加新的技术指标\n\n1. 在 `core/indicators/` 目录下创建指标函数\n2. 在 `server.py` 中注册为 MCP 工具\n3. 添加单元测试\n\n### 添加新交易所支持\n\n1. 更新 `validators.py` 中的交易所映射\n2. 在 `EXCHANGE_SCREENER` 添加对应条目\n3. 测试符号构造：`get_tv_exchange_prefix(\"NEW_EX\", \"SYMBOL\")`\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n---\n\n\n\n## 回测引擎\n\n### 相关页面\n\n相关主题：[技术分析服务](#page-technical-analysis), [核心组件](#page-core-components)\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- [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/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/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n- [CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)\n- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n \n\n# 回测引擎\n\n## 概述\n\n回测引擎（Backtesting Engine）是 tradingview-mcp 项目中负责历史数据验证交易策略的核心模块。该引擎通过加载历史价格数据，模拟策略在实际市场中的表现，帮助交易者和开发者评估策略的有效性、风险特征和潜在收益。\n\n回测引擎的主要职责包括：\n\n- **策略回测**：对单个交易策略进行历史数据回测\n- **多策略比较**：并排运行多个策略并按性能排名\n- **Walk-Forward 分析**：使用样本外数据验证策略稳定性\n- **指标计算**：提供机构级别的评估指标（Sharpe、Calmar、胜率等）\n\n## 架构设计\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ MCP Server │\n│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │\n│ │ backtest_ │ │ compare_ │ │ walk_forward_ │ │\n│ │ strategy │ │ strategies │ │ backtest_strategy │ │\n│ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ │\n└─────────┼─────────────────┼────────────────────┼───────────────┘\n │ │ │\n ▼ ▼ ▼\n┌─────────────────────────────────────────────────────────────────┐\n│ backtest_service.py │\n│ ┌─────────────────────────────────────────────────────────────┐│\n│ │ Strategy Engine ││\n│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ ││\n│ │ │ RSI │ │Bollinger│ │ MACD │ │EMA Cross│ │Super.. │ ││\n│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └────────┘ ││\n│ └─────────────────────────────────────────────────────────────┘│\n│ ┌─────────────────────────────────────────────────────────────┐│\n│ │ Metrics Calculator ││\n│ │ Sharpe | Calmar | Win Rate | Max DD | Profit Factor ││\n│ └─────────────────────────────────────────────────────────────┘│\n└─────────────────────────────────────────────────────────────────┘\n```\n\n## 支持的交易策略\n\n回测引擎内置 **6 种交易策略**，涵盖均值回归、趋势跟踪和突破策略三大类别。\n\n### 策略类型一览\n\n| 策略标识 | 中文名称 | 策略类别 | 核心逻辑 |\n|----------|----------|----------|----------|\n| `rsi` | RSI 策略 | 均值回归 | RSI 超卖买入，超买卖出 |\n| `bollinger` | 布林带策略 | 均值回归 | 价格触及下轨买入，上轨卖出 |\n| `macd` | MACD 策略 | 趋势跟踪 | MACD 金叉买入，死叉卖出 |\n| `ema_cross` | EMA 交叉策略 | 趋势跟踪 | EMA 20/50 黄金交叉买入，死亡交叉卖出 |\n| `supertrend` | Supertrend 策略 | 趋势跟踪 | ATR 计算动态止损，顺势交易 |\n| `donchian` | 唐奇安通道策略 | 突破策略 | 价格突破通道高点买入，跌破低点卖出 |\n\n### 策略详情\n\n#### RSI 均值回归策略\n\n```python\n# 核心逻辑伪代码\nif rsi < 30: # 超卖区域 → 买入信号\n signal = \"BUY\"\nelif rsi > 70: # 超买区域 → 卖出信号\n signal = \"SELL\"\n```\n\n#### 布林带策略\n\n```python\n# 核心逻辑伪代码\nif price < lower_band: # 触及下轨 → 买入信号\n signal = \"BUY\"\nelif price > upper_band: # 触及上轨 → 卖出信号\n signal = \"SELL\"\n```\n\n#### Supertrend 策略（最受欢迎）\n\n```python\n# 核心逻辑伪代码\natr_value = calculate_atr(high, low, close, period=10)\nupper_band = (high + low) / 2 + multiplier * atr_value\nlower_band = (high + low) / 2 - multiplier * atr_value\n\nif close > upper_band: # 上穿通道 → 买入信号\n signal = \"BUY\"\nelif close < lower_band: # 下穿通道 → 卖出信号\n signal = \"SELL\"\n```\n\n资料来源：[README.md](README.md)\n\n## MCP 工具接口\n\n### 1. backtest_strategy — 单策略回测\n\n对单个策略进行完整的回测分析，返回详细的绩效指标和交易记录。\n\n**参数列表**\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| `symbol` | string | 是 | — | 交易标的符号（如 `BTC-USD`、`AAPL`） |\n| `strategy` | string | 是 | — | 策略名称：`rsi`、`bollinger`、`macd`、`ema_cross`、`supertrend`、`donchian` |\n| `period` | string | 否 | `\"1y\"` | 回测周期：`1mo`、`3mo`、`6mo`、`1y`、`2y` |\n| `interval` | string | 否 | `\"1d\"` | K线周期：`1h`（小时）、`1d`（日线） |\n| `include_trade_log` | boolean | 否 | `false` | 是否包含完整交易明细 |\n| `include_equity_curve` | boolean | 否 | `false` | 是否包含权益曲线数据 |\n\n**返回值结构**\n\n```json\n{\n \"strategy\": \"supertrend\",\n \"symbol\": \"BTC-USD\",\n \"period\": \"2y\",\n \"interval\": \"1d\",\n \"metrics\": {\n \"total_return\": 31.5,\n \"win_rate\": 62.0,\n \"sharpe_ratio\": 2.1,\n \"calmar_ratio\": 1.8,\n \"max_drawdown\": -12.3,\n \"profit_factor\": 2.4,\n \"expectancy\": 1.25,\n \"total_trades\": 45,\n \"best_trade\": 8.5,\n \"worst_trade\": -3.2,\n \"vs_buy_hold\": 15.2\n },\n \"recent_trades\": [...],\n \"trade_log\": [...],\n \"equity_curve\": [...]\n}\n```\n\n资料来源：[CHANGELOG.md](CHANGELOG.md)\n\n### 2. compare_strategies — 多策略比较\n\n在相同标的上同时运行全部 6 种策略，按性能指标综合排名。\n\n**参数列表**\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| `symbol` | string | 是 | — | 交易标的符号 |\n| `period` | string | 否 | `\"1y\"` | 回测周期 |\n| `interval` | string | 否 | `\"1d\"` | K线周期 |\n\n**返回值示例**\n\n```\n#1 Supertrend: +31.5% | Sharpe: 2.1 | WR: 62%\n#2 Bollinger: +18.3% | Sharpe: 3.4 | WR: 75%\n#3 EMA Cross: +12.1% | Sharpe: 1.9 | WR: 58%\n#4 MACD: +8.7% | Sharpe: 1.5 | WR: 52%\n#5 RSI: +5.2% | Sharpe: 1.2 | WR: 48%\n#6 Donchian: -2.1% | Sharpe: 0.8 | WR: 42%\n\nBuy & Hold: -5.0%\n```\n\n资料来源：[README.md](README.md)\n\n### 3. walk_forward_backtest_strategy — Walk-Forward 分析\n\n将数据分为训练集和测试集，在样本外数据上验证策略的泛化能力。\n\n**参数列表**\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| `symbol` | string | 是 | — | 交易标的符号 |\n| `strategy` | string | 是 | — | 策略名称 |\n| `n_splits` | integer | 否 | 5 | 分割次数（2-10） |\n| `train_ratio` | float | 否 | 0.7 | 训练集比例（0.5-0.9） |\n| `interval` | string | 否 | `\"1d\"` | K线周期 |\n\n**输出内容**\n\n- **样本内指标**：训练集上的平均 Sharpe、胜率、最大回撤、总收益\n- **样本外指标**：测试集上的平均表现\n- **稳定性评估**：样本内外指标的差异程度\n\n## 绩效指标说明\n\n### 机构级指标定义\n\n| 指标 | 英文名 | 计算方式 | 理想值 |\n|------|--------|----------|--------|\n| 总收益率 | Total Return | (期末净值 - 期初净值) / 期初净值 × 100% | > 0 |\n| 胜率 | Win Rate | 盈利交易数 / 总交易数 × 100% | > 50% |\n| Sharpe 比率 | Sharpe Ratio | (策略收益 - 无风险收益) / 策略波动率 | > 1.5 |\n| Calmar 比率 | Calmar Ratio | 年化收益 / 最大回撤 | > 2.0 |\n| 最大回撤 | Max Drawdown | 历史最高点到最低点的最大跌幅 | < 20% |\n| 利润因子 | Profit Factor | 总盈利 / 总亏损 | > 1.5 |\n| 期望值 | Expectancy | (胜率 × 平均盈利) - (败率 × 平均亏损) | > 0 |\n\n### Sharpe 比率年化因子\n\n引擎会根据不同的时间周期自动调整 Sharpe 比率的年化计算：\n\n| 周期 | 年化因子 |\n|------|----------|\n| 日线 (`1d`) | 252（交易日） |\n| 小时线 (`1h`) | 252 × 6（每日交易小时） |\n\n```python\n# Sharpe 计算逻辑示例\nif interval == \"1h\":\n annualization_factor = 252 * 6 # 修正小时线年化\nelse:\n annualization_factor = 252\n```\n\n资料来源：[CHANGELOG.md](CHANGELOG.md)\n\n## 交易记录与权益曲线\n\n### 交易明细（Trade Log）\n\n启用 `include_trade_log=True` 后，返回完整的每笔交易记录：\n\n```json\n{\n \"trade_log\": [\n {\n \"entry_date\": \"2024-01-15\",\n \"exit_date\": \"2024-01-28\",\n \"entry_price\": 41250.00,\n \"exit_price\": 43580.00,\n \"holding_days\": 13,\n \"gross_return\": 5.65,\n \"net_return\": 5.42,\n \"commission_cost\": 0.23,\n \"running_capital\": 10542.00,\n \"cumulative_return\": 5.42\n }\n ]\n}\n```\n\n### 权益曲线（Equity Curve）\n\n启用 `include_equity_curve=True` 后，返回每个交易退出时点的权益变化：\n\n```json\n{\n \"equity_curve\": [\n {\n \"date\": \"2024-01-28\",\n \"capital_value\": 10542.00,\n \"drawdown_pct\": -2.1\n },\n {\n \"date\": \"2024-02-15\",\n \"capital_value\": 11280.00,\n \"drawdown_pct\": 0\n }\n ]\n}\n```\n\n### 快速预览机制\n\n即使未启用完整交易日志，引擎始终返回最近 **5 笔交易**（`recent_trades`）供快速检查：\n\n```json\n{\n \"recent_trades\": [\n {\"symbol\": \"BTC-USD\", \"entry\": 42100, \"exit\": 43500, \"pnl\": 3.3},\n {\"symbol\": \"BTC-USD\", \"entry\": 43500, \"exit\": 42800, \"pnl\": -1.6},\n {\"symbol\": \"BTC-USD\", \"entry\": 42800, \"exit\": 44200, \"pnl\": 3.3}\n ]\n}\n```\n\n资料来源：[CHANGELOG.md](CHANGELOG.md)\n\n## 使用示例\n\n### 基础回测\n\n```python\n# 回测 BTC 的 Supertrend 策略\nresult = backtest_strategy(\n symbol=\"BTC-USD\",\n strategy=\"supertrend\",\n period=\"1y\",\n interval=\"1d\"\n)\n```\n\n### 完整交易分析\n\n```python\n# 包含交易明细和权益曲线\nresult = backtest_strategy(\n symbol=\"AAPL\",\n strategy=\"bollinger\",\n period=\"2y\",\n interval=\"1d\",\n include_trade_log=True,\n include_equity_curve=True\n)\n```\n\n### 策略比较\n\n```python\n# 比较所有策略\nresult = compare_strategies(\n symbol=\"ETH-USD\",\n period=\"1y\"\n)\n```\n\n### Walk-Forward 验证\n\n```python\n# 使用 5 折交叉验证\nresult = walk_forward_backtest_strategy(\n symbol=\"BTC-USD\",\n strategy=\"rsi\",\n n_splits=5,\n train_ratio=0.7,\n interval=\"1d\"\n)\n```\n\n## 与多代理系统的集成\n\n回测引擎可与 `multi_agent_service.py` 中的技术分析代理协同工作：\n\n```mermaid\ngraph LR\n A[用户请求] --> B{分析类型}\n B -->|技术分析| C[Technical Analyst]\n B -->|回测请求| D[Backtest Engine]\n B -->|综合决策| E[Multi-Agent Hub]\n \n C --> F[技术指标]\n D --> G[绩效指标]\n \n E --> H[情绪分析]\n E --> I[风险评估]\n \n F --> J[综合评分]\n G --> J\n H --> J\n I --> J\n \n J --> K[最终建议]\n```\n\n多代理系统包含三个专业代理：\n\n| 代理 | 职责 | 输出 |\n|------|------|------|\n| 技术分析师 | 布林带(±3评级)、RSI、MACD | 技术信号 |\n| 情绪分析师 | Reddit 社区情绪、价格动量 | 情绪评分 |\n| 风险管理器 | 波动性、回撤风险、均值回归信号 | 风险评估 |\n\n**最终输出**：`STRONG BUY` / `BUY` / `HOLD` / `SELL` / `STRONG SELL` 附置信度评分\n\n资料来源：[server.py](src/tradingview_mcp/server.py)、[README.md](README.md)\n\n## 模拟参数说明\n\n### 佣金与滑点\n\n回测引擎包含**现实的佣金和滑点模拟**：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| 佣金率 | 0.1% | 每笔交易的手续费 |\n| 滑点 | 模拟 | 订单执行时的价格偏差 |\n\n### 初始资金\n\n默认使用模拟资金进行计算，盈亏以百分比形式呈现，便于不同规模账户的对比。\n\n## 注意事项与限制\n\n### ⚠️ 重要声明\n\n> **⚠️ 过去表现不保证未来结果**\n>\n> 所有回测结果仅供历史参考，实际交易中可能出现与回测显著不同的结果。市场条件、流动性、执行质量等因素均会影响策略表现。\n\n### 技术限制\n\n1. **数据延迟**：依赖历史数据，非实时价格\n2. **流动性假设**：未考虑大额订单对市场的影响\n3. **执行假设**：按收盘价成交，实际可能存在滑点\n4. **过拟合风险**：过度优化可能导致样本内表现优异、样本外失效\n\n### Walk-Forward 分析的价值\n\n为降低过拟合风险，建议：\n\n- 使用 Walk-Forward 分析验证策略稳定性\n- 样本外 Sharpe 比率应接近样本内水平\n- 避免过度追求单一指标的最优值\n\n## 文件结构\n\n```\nsrc/tradingview_mcp/\n├── server.py # MCP 工具入口\n└── core/services/\n ├── backtest_service.py # 回测引擎核心实现\n └── multi_agent_service.py # 多代理分析服务\n```\n\n资料来源：[server.py](src/tradingview_mcp/server.py)\n\n## 版本历史\n\n| 版本 | 发布日期 | 主要更新 |\n|------|----------|----------|\n| 0.7.0 | 2026-04 | Walk-Forward 分析、交易明细、权益曲线 |\n| 0.6.0 | 2026-03-29 | Backtesting Engine v2、6 种策略、机构级指标 |\n\n资料来源：[CHANGELOG.md](CHANGELOG.md)\n\n---\n\n\n\n## 技术分析服务\n\n### 相关页面\n\n相关主题：[回测引擎](#page-backtesting-engine), [数据源与货币列表](#page-data-sources)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\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- [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/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/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.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# 技术分析服务\n\n## 概述\n\n技术分析服务是 `tradingview-mcp` 项目的核心模块，负责从 TradingView 获取市场数据并计算各种技术指标。该服务集成了 30+ 技术指标，包括 RSI、MACD、布林带等主流分析工具，为 AI 交易代理提供实时市场分析能力。\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph \"技术分析服务架构\"\n A[server.py
MCP接口层] --> B[技术分析服务层]\n B --> C[screener_service.py
筛选服务]\n B --> D[scanner_service.py
扫描服务]\n B --> E[indicators.py
指标定义]\n B --> F[indicators_calc.py
指标计算]\n B --> G[egx_service.py
埃及交易所服务]\n \n C --> H[tradingview_ta
数据源]\n D --> H\n F --> H\n end\n \n subgraph \"输出层\"\n B --> I[技术分析结果]\n B --> J[筛选/扫描结果]\n B --> K[斐波那契分析]\n end\n```\n\n## 核心服务组件\n\n### 1. 筛选服务 (screener_service.py)\n\n筛选服务负责从 TradingView 获取市场筛选数据，支持多交易所、多时间周期的市场扫描。\n\n#### 关键数据结构\n\n| 数据结构 | 用途 | 主要字段 |\n|---------|------|---------|\n| `MultiRow` | 单个标的的多时间周期数据 | symbol, changes, base_indicators |\n| `IndicatorMap` | 技术指标映射 | open, close, SMA20, BB_upper, BB_lower, volume |\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py:1-30]()\n\n#### 烛台模式分析\n\n`screener_service.py` 中的 `calculate_candle_pattern_score` 函数提供了烛台形态评分功能：\n\n```python\ndef calculate_candle_pattern_score(\n indicators: dict,\n pattern_length: int,\n min_increase: float,\n) -> dict\n```\n\n**功能说明：**\n- 根据价格形态、身体比率、动量、成交量和 RSI 进行综合评分\n- 返回检测结果、得分、明细列表及计算字段\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| indicators | dict | 来自 tradingview_ta 的原始指标数据 |\n| pattern_length | int | 分析的连续周期数 |\n| min_increase | float | 最小价格变化百分比阈值 |\n\n**返回值结构：**\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| detected | bool | 是否检测到有效形态 |\n| score | int | 形态强度评分 |\n| details | list | 详细分析结果 |\n| 计算字段 | float | open_price, close_price, high_price, low_price, volume, rsi |\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py:56-85]()\n\n### 2. 扫描服务 (scanner_service.py)\n\n扫描服务提供市场扫描功能，支持按信号类型、连续烛台、技术指标等维度进行市场筛选。\n\n```mermaid\ngraph LR\n A[扫描请求] --> B[信号类型过滤]\n B --> C[连续烛台检测]\n C --> D[技术指标筛选]\n D --> E[扫描结果输出]\n```\n\n**支持的扫描类型：**\n\n| 扫描类型 | 说明 | 应用场景 |\n|---------|------|---------|\n| `oversold` | 超卖信号扫描 | RSI < 30 的标的 |\n| `overbought` | 超买信号扫描 | RSI > 70 的标的 |\n| `bullish` | 看涨形态扫描 | 连续阳线、突破形态 |\n| `bearish` | 看跌形态扫描 | 连续阴线、跌破形态 |\n| `breakout` | 突破扫描 | 突破布林带上轨/阻力位 |\n\n### 3. 指标计算服务 (indicators_calc.py)\n\n指标计算服务封装了所有技术指标的计算逻辑，提供标准化的事件分析接口。\n\n#### 支持的指标类型\n\n| 指标类别 | 包含指标 | 用途 |\n|---------|---------|------|\n| 趋势类 | SMA, EMA, MACD, Supertrend | 判断市场趋势方向 |\n| 振荡类 | RSI, Stochastic, CCI, Williams %R | 判断超买超卖 |\n| 波动类 | Bollinger Bands, ATR, Donchian | 衡量价格波动幅度 |\n| 成交量类 | OBV, Volume SMA | 分析成交量与价格关系 |\n| 形态类 | 15种烛台形态识别 | 价格反转信号 |\n\n### 4. 埃及交易所专用服务 (egx_service.py)\n\nEGX 服务为埃及证券交易所提供专业分析工具，包括斐波那契回撤分析和股票评分系统。\n\n#### 斐波那契回撤分析\n\n```python\ndef analyze_egx_fibonacci(\n symbol: str,\n lookback: str = \"52W\",\n timeframe: str = \"1D\",\n) -> dict\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| symbol | str | 必需 | EGX 股票代码（如 'COMI'） |\n| lookback | str | \"52W\" | 回溯周期：'1M', '3M', '6M', '52W', 'ALL' |\n| timeframe | str | \"1D\" | TradingView 时间周期 |\n\n**返回字段：**\n\n| 字段 | 说明 |\n|-----|------|\n| fib_levels | 斐波那契回撤/扩展价位 |\n| price_position | 当前价格在回撤中的位置 |\n| swing_high/low | 周期内最高/最低价 |\n| context | 市场背景分析 |\n\n资料来源：[src/tradingview_mcp/core/services/egx_service.py:100-150]()\n\n#### 股票评分系统\n\nEGX 服务包含多维度股票评分引擎：\n\n```mermaid\ngraph TD\n A[股票评分输入] --> B[技术强度 SS]\n A --> C[交易质量 TQ]\n A --> D[趋势确认 RR2]\n \n B --> E{评分规则引擎}\n C --> E\n D --> E\n \n E --> F{综合判断}\n F -->|SS>=70, TQ>=65, RR2>=2.0| G[QUALIFIED
强信号]\n F -->|SS>=70, TQ>=50| H[CONDITIONAL
条件信号]\n F -->|SS>=55| I[WATCHLIST
观察名单]\n F -->|SS<55| J[AVOID
回避]\n```\n\n**评分维度：**\n\n| 维度 | 缩写 | 阈值 | 说明 |\n|-----|------|-----|------|\n| 技术强度 | SS | 0-100 | 技术指标综合得分 |\n| 交易质量 | TQ | 0-100 | 价格结构与成交量质量 |\n| 趋势确认 | RR2 | >2.0 | 风险回报比确认 |\n\n**推荐等级：**\n\n| 推荐等级 | 触发条件 | 含义 |\n|---------|---------|------|\n| QUALIFIED | SS≥70, TQ≥65, RR2≥2.0 | 强信号，操作性强的标的 |\n| CONDITIONAL | SS≥70, TQ≥50 | 好标的但需改进设置 |\n| WATCHLIST | SS≥55 | 需监控等待更好入场点 |\n| AVOID | SS<55 | 不满足动量/质量标准 |\n\n资料来源：[src/tradingview_mcp/core/services/egx_service.py:1-100]()\n\n## 多交易所支持\n\n技术分析服务支持多个交易所的行情数据获取：\n\n```mermaid\ngraph TD\n A[分析请求] --> B{交易所识别}\n \n B -->|加密货币| C[BINANCE/KUCOIN/BYBIT]\n B -->|美国股票| D[NYSE/NASDAQ/AMEX]\n B -->|埃及股票| E[EGX]\n B -->|台湾股票| F[TWSE/TPEX]\n B -->|土耳其股票| G[BIST]\n \n C --> H[统一数据格式]\n D --> H\n E --> H\n F --> H\n G --> H\n```\n\n**支持的交易所映射：**\n\n| 市场类型 | 交易所代码 | 说明 |\n|---------|-----------|------|\n| 加密货币 | BINANCE, KUCOIN, BYBIT, MEXC | 数字资产交易 |\n| 美国股票 | NYSE, NASDAQ, AMEX, NYSEARCA | 美股市场 |\n| 台湾股票 | TWSE, TPEX | 台湾证券交易所 |\n| 埃及股票 | EGX | 埃及证券交易所 |\n| 土耳其股票 | BIST | 伊斯坦布尔证券交易所 |\n\n## 数据流向\n\n```mermaid\nsequenceDiagram\n participant U as 用户请求\n participant S as Server层\n participant SC as Screener服务\n participant TV as TradingView API\n participant IC as 指标计算\n participant R as 结果返回\n \n U->>S: 调用分析工具\n S->>SC: 请求市场数据\n SC->>TV: 获取原始数据\n TV-->>SC: 原始OHLCV数据\n SC->>IC: 计算技术指标\n IC-->>SC: 指标结果\n SC-->>S: 格式化结果\n S-->>U: 返回分析报告\n```\n\n## 与 MCP Server 的集成\n\n技术分析服务通过 `server.py` 暴露为 MCP 工具：\n\n| MCP 工具 | 功能 | 底层服务 |\n|---------|------|---------|\n| `get_technical_analysis` | 完整技术分析 | indicators.py |\n| `get_bollinger_band_analysis` | 布林带专有分析 | indicators_calc.py |\n| `screen_stocks` | 多条件筛选 | screener_service.py |\n| `scan_by_signal` | 信号扫描 | scanner_service.py |\n| `egx_fibonacci_retracement` | 斐波那契分析 | egx_service.py |\n| `get_candlestick_patterns` | 烛台形态检测 | screener_service.py |\n\n## 货币与部门数据\n\nEGX 服务提供股票货币和部门分类：\n\n**货币类型判断：**\n\n| 货币 | 适用股票 | 示例 |\n|-----|---------|------|\n| EGP | 大多数EGX股票 | COMI, ORWE, ETEL |\n| USD | 特定国际股票 | FAITA, VLMR, EGSA |\n\n资料来源：[src/tradingview_mcp/core/data/egx_sectors.py:1-50]()\n\n**部门分类：** 涵盖银行业、保险业、电信业、制造业等 20+ 行业部门。\n\n## 错误处理\n\n| 错误类型 | 返回格式 | 处理方式 |\n|---------|---------|---------|\n| API连接失败 | `{\"error\": \"description\"}` | 记录日志，返回错误信息 |\n| 无效标的 | `{\"error\": \"Invalid symbol\"}` | 验证输入后返回 |\n| 数据缺失 | 字段为0或空 | 使用默认值处理 |\n\n## 扩展指南\n\n### 添加新指标\n\n1. 在 `indicators_calc.py` 中实现计算函数\n2. 注册到指标映射表\n3. 在 `server.py` 中暴露为 MCP 工具\n\n### 添加新交易所\n\n1. 更新 `EXCHANGE_SCREENER` 映射表\n2. 添加交易所符号列表到 `coinlist/` 目录\n3. 测试数据获取和格式化\n\n## 参考链接\n\n- 项目主页：[tradingview-mcp](https://github.com/atilaahmettaner/tradingview-mcp)\n- 技术分析文档：[README.md](README.md)\n- 贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md)\n\n---\n\n\n\n## 情感分析与新闻服务\n\n### 相关页面\n\n相关主题：[技术分析服务](#page-technical-analysis), [数据源与货币列表](#page-data-sources)\n\n\n相关源码文件
\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/news_service.py)\n- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.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/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)\n \n\n# 情感分析与新闻服务\n\n## 概述\n\n情感分析与新闻服务是 tradingview-mcp 框架的核心模块之一，旨在为交易决策提供多维度的市场情绪和资讯数据支持。该服务通过整合 Reddit 社区情感分析和实时金融新闻（RSS），帮助用户从社交媒体情绪和新闻事件两个维度评估资产走势。\n\n**核心功能定位：**\n\n| 功能模块 | 用途 | 数据来源 |\n|---------|------|---------|\n| 情感分析服务 | 评估市场参与者的社区情绪 | Reddit 社区帖子 |\n| 新闻服务 | 聚合实时财经新闻 | RSS 订阅源 |\n\n资料来源：[server.py:1-50]()\n\n## 架构设计\n\n### 服务组件结构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ MCP Server (server.py) │\n├─────────────────────────────────────────────────────────────┤\n│ ┌─────────────────┐ ┌─────────────────┐ │\n│ │ Sentiment │ │ News │ │\n│ │ Service │ │ Service │ │\n│ └────────┬────────┘ └────────┬────────┘ │\n│ │ │ │\n│ ▼ ▼ │\n│ ┌─────────────────┐ ┌─────────────────┐ │\n│ │ Reddit API │ │ RSS Feeds │ │\n│ │ (情感抓取) │ │ (新闻聚合) │ │\n│ └─────────────────┘ └─────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 情感分析流程\n\n```mermaid\ngraph TD\n A[请求分析: symbol + category] --> B[Reddit 搜索]\n B --> C{找到相关帖子?}\n C -->|是| D[解析帖子内容]\n C -->|否| E[返回空结果]\n D --> F[计算情感得分]\n F --> G[生成情感标签]\n G --> H[输出完整情感报告]\n```\n\n资料来源：[server.py:token-analysis-call]()\n\n## 情感分析服务\n\n### 功能说明\n\n`analyze_sentiment` 函数是情感分析的核心入口，负责从 Reddit 社区抓取与指定标的相关的讨论帖子，并计算情感得分。\n\n**函数签名：**\n\n```python\nanalyze_sentiment(symbol: str, category: str = \"crypto\") -> dict\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| symbol | str | 必填 | 交易标的符号（如 BTC-USD、AAPL） |\n| category | str | \"crypto\" | 标的类别，可选 \"crypto\" 或 \"stocks\" |\n\n资料来源：[server.py:analyze_sentiment-def]()\n\n### 情感分析输出结构\n\n```python\n{\n \"sentiment_score\": float, # 情感得分（-1 到 1）\n \"sentiment_label\": str, # 情感标签（Bullish/Bearish/Neutral）\n \"posts_analyzed\": int, # 分析的帖子数量\n \"mentions\": int, # 提及次数\n \"key_themes\": List[str], # 关键主题\n \"confidence\": str # 置信度（High/Medium/Low）\n}\n```\n\n### 情感标签映射\n\n| 情感得分范围 | 标签 | 含义 |\n|-------------|------|------|\n| > 0.1 | Bullish | 看涨情绪 |\n| -0.1 ~ 0.1 | Neutral | 中性情绪 |\n| < -0.1 | Bearish | 看跌情绪 |\n\n资料来源：[server.py:sentiment_label-conditional]()\n\n## 新闻服务\n\n### 功能说明\n\n`fetch_news_summary` 函数从多个 RSS 订阅源聚合与指定标的相关的最新财经新闻。\n\n**函数签名：**\n\n```python\nfetch_news_summary(symbol: str, category: str = \"crypto\", limit: int = 5) -> dict\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| symbol | str | 必填 | 交易标的符号 |\n| category | str | \"crypto\" | 标的类别 |\n| limit | int | 5 | 返回的新闻条目数量上限 |\n\n资料来源：[server.py:fetch_news_summary-def]()\n\n### 新闻输出结构\n\n```python\n{\n \"count\": int, # 获取的新闻总数\n \"items\": [ # 新闻条目列表\n {\n \"title\": str, # 新闻标题\n \"link\": str, # 新闻链接\n \"pub_date\": str, # 发布日期\n \"source\": str # 新闻来源\n }\n ]\n}\n```\n\n## 情绪共振分析\n\n### 合流决策引擎\n\n`sentiment_news_confluence` 函数将技术分析、情感分析和新闻数据三者结合，生成综合交易建议。\n\n**函数签名：**\n\n```python\nsentiment_news_confluence(symbol: str, exchange: str, timeframe: str = \"1h\") -> dict\n```\n\n**分析流程：**\n\n```mermaid\ngraph TD\n A[输入: symbol + exchange + timeframe] --> B[技术分析]\n A --> C[情感分析]\n A --> D[新闻汇总]\n B --> E{技术信号}\n C --> F{情感得分 > 0.1?}\n E -->|Bullish/Bearish| G[信号对齐检查]\n F -->|True| G\n G --> H{信号一致?}\n H -->|是| I[confidence: HIGH]\n H -->|否| J[confidence: MIXED]\n I --> K[recommendation: 技术信号 confirmed by 情感]\n J --> L[recommendation: 技术信号 conflicts with 情感]\n```\n\n资料来源：[server.py:confluence-analysis]()\n\n### 合流输出字段\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| symbol | str | 交易标的 |\n| exchange | str | 交易所 |\n| timeframe | str | 分析时间周期 |\n| technical | dict | 技术分析完整结果 |\n| sentiment | dict | 情感分析结果 |\n| news | dict | 新闻摘要（数量 + 最新3条） |\n| confluence | dict | 合流分析结果 |\n\n**合流置信度判定：**\n\n| 条件 | 置信度 | 建议格式 |\n|------|--------|---------|\n| 技术信号 == 情感信号 | HIGH | \"Technical {signal} confirmed by {sentiment}\" |\n| 技术信号 != 情感信号 | MIXED | \"Technical {signal} conflicts with {sentiment}\" |\n\n资料来源：[server.py:confidence-calculation]()\n\n## EGX 交易所特殊处理\n\n### 埃及股市情绪分析\n\nEGX（埃及证券交易所）服务提供专门的市场情绪和板块轮动分析功能。\n\n**指数分析函数：**\n\n```python\nanalyze_egx_index(index: str = \"EGX30\", timeframe: str = \"1D\", limit: int = 30) -> dict\n```\n\n**支持的指数：**\n\n| 指数代码 | 名称 | 说明 |\n|---------|------|------|\n| EGX30 | EGX 30 指数 | 埃及主板30强 |\n| EGX70 | EGX 70 指数 | 中盘股指数 |\n| EGX100 | EGX 100 指数 | 综合指数 |\n| SHARIAH33 | 伊斯兰指数 | 符合伊斯兰法规的股票 |\n| EGX35LV | 低波动指数 | 低波动精选股 |\n| TAMAYUZ | Tamayuz 指数 | 主题指数 |\n\n资料来源：[egx_service.py:analyze_egx_index-def]()\n\n### 市场情绪生成\n\n`_generate_rotation_signals` 函数分析板块轮动信号，判断资金流向。\n\n**情绪类型映射：**\n\n```python\nrotation_signals = {\n \"strong_sectors\": List[str], # 强势板块\n \"weak_sectors\": List[str], # 弱势板块\n \"rotation_direction\": str, # 轮动方向\n \"momentum_score\": float # 动量得分\n}\n```\n\n资料来源：[egx_service.py:_generate_rotation_signals]()\n\n### 板块热度图\n\n`generate_sector_heatmap` 函数计算各板块的相对强弱，生成权重分析。\n\n**输出结构：**\n\n```python\n{\n \"exchange\": \"EGX\",\n \"timeframe\": str,\n \"total_sectors\": int,\n \"total_stocks_scanned\": int,\n \"weighted_market_view\": {\n \"weighted_change_pct\": float,\n \"weighted_rsi\": float,\n \"weighted_momentum\": float,\n \"market_sentiment\": str\n },\n \"sector_heatmap\": dict,\n \"sector_top_picks\": dict,\n \"rotation_signals\": dict\n}\n```\n\n资料来源：[egx_service.py:generate_sector_heatmap-return]()\n\n## 使用示例\n\n### 基础情感分析\n\n```python\n# 加密货币情感分析\nresult = analyze_sentiment(symbol=\"BTC-USD\", category=\"crypto\")\n\n# 美股情感分析\nresult = analyze_sentiment(symbol=\"AAPL\", category=\"stocks\")\n```\n\n### 综合新闻获取\n\n```python\n# 获取币安相关最新新闻\nnews = fetch_news_summary(symbol=\"BNB\", category=\"crypto\", limit=10)\n```\n\n### 合流决策分析\n\n```python\n# 完整分析示例\nconfluence = sentiment_news_confluence(\n symbol=\"BTC-USD\",\n exchange=\"BINANCE\",\n timeframe=\"1h\"\n)\n\n# 输出示例\n# {\n# \"confidence\": \"HIGH\",\n# \"signals_agree\": True,\n# \"recommendation\": \"Technical STRONG BUY confirmed by Bullish Reddit sentiment (142 posts analyzed)\"\n# }\n```\n\n资料来源：[server.py:confluence-example]()\n\n## 技术指标与情感关联\n\n### 多指标协同分析\n\n系统支持将情感数据与其他技术指标结合使用：\n\n| 指标类型 | 工具函数 | 用途 |\n|---------|---------|------|\n| 价格数据 | `yahoo_price` | 实时价格 |\n| 技术分析 | `get_technical_analysis` | 30+ 技术指标 |\n| 情感分析 | `analyze_sentiment` | Reddit 情绪 |\n| 新闻汇总 | `fetch_news_summary` | RSS 新闻 |\n| K线形态 | `get_candlestick_patterns` | 15 种形态识别 |\n\n资料来源：[README.md:tools-table]()\n\n### 信号对齐矩阵\n\n```\n 技术分析信号\n BUY SELL HOLD\n情感 ┌─────────────┬─────────────┬─────────────┐\n Bullish │ HIGH ✅ │ MIXED ⚠️ │ MIXED ⚠️ │\n ├─────────────┼─────────────┼─────────────┤\n情感 │ MIXED ⚠️ │ HIGH ✅ │ MIXED ⚠️ │\n Bearish │ │ │ │\n ├─────────────┼─────────────┼─────────────┤\n情感 │ MIXED ⚠️ │ MIXED ⚠️ │ MEDIUM 🔄 │\n Neutral │ │ │ │\n └─────────────┴─────────────┴─────────────┘\n```\n\n## 配置与扩展\n\n### 情感分析数据源配置\n\nReddit 数据源目前使用公开 API 接口，支持的主题分类：\n\n| category | 适用标的 | 搜索范围 |\n|----------|---------|---------|\n| crypto | 加密货币 | r/CryptoCurrency, r/Bitcoin 等 |\n| stocks | 股票 | r/stocks, r/wallstreetbets 等 |\n\n### 新闻服务 RSS 配置\n\n新闻服务支持多源 RSS 订阅，可扩展的订阅源：\n\n| 来源类型 | 内容范围 | 更新频率 |\n|---------|---------|---------|\n| 财经媒体 | 主流财经新闻 | 实时 |\n| 交易所公告 | 官方公告和更新 | 事件驱动 |\n| 社区讨论 | 社交媒体摘要 | 定期聚合 |\n\n## 注意事项\n\n1. **免责声明**：所有情感和新闻分析仅供教育和参考用途，不构成投资建议\n2. **数据延迟**：RSS 新闻源可能存在几分钟到几小时的延迟\n3. **情感局限性**：Reddit 情感分析可能受到炒作和操控影响\n4. **API 限制**：外部 API 调用频率受限于服务提供商的策略\n\n资料来源：[egx_service.py:disclaimer]()\n\n## 相关资源\n\n- [项目主页](../README.md)\n- [安装指南](../INSTALLATION.md)\n- [OpenClaw 集成指南](../OPENCLAW.md)\n- [示例对话](../EXAMPLES.md)\n\n---\n\n\n\n## Yahoo Finance 集成\n\n### 相关页面\n\n相关主题：[数据源与货币列表](#page-data-sources), [技术分析服务](#page-technical-analysis)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\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- [src/tradingview_mcp/core/services/extended_hours_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/extended_hours_service.py)\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- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n \n\n# Yahoo Finance 集成\n\n## 概述\n\nYahoo Finance 集成是 tradingview-mcp 项目在 **v0.6.0** 版本中新增的核心功能模块，为用户提供实时金融市场数据查询能力。该模块通过封装 Yahoo Finance API，实现了股票、加密货币、ETF、指数、外汇等多资产类别的实时行情获取。\n\n**主要功能包括：**\n\n- `yahoo_price`：获取任意标的的实时报价\n- `market_snapshot`：生成全球市场概览快照\n\n资料来源：[CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)\n\n---\n\n## 架构设计\n\n### 服务层结构\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ server.py │\n│ (MCP 工具入口层) │\n│ ┌─────────────────┐ ┌─────────────────────────────┐ │\n│ │ yahoo_price │ │ market_snapshot │ │\n│ └────────┬────────┘ └──────────────┬──────────────┘ │\n└───────────┼──────────────────────────┼──────────────────┘\n │ │\n ▼ ▼\n┌─────────────────────────────────────────────────────────┐\n│ yahoo_finance_service.py │\n│ (核心服务层) │\n│ ┌─────────────────┐ ┌─────────────────────────────┐ │\n│ │ 实时行情获取 │ │ 市场快照生成 │ │\n│ │ │ │ 14 instruments │ │\n│ │ price_data() │ │ 4 asset classes │ │\n│ └─────────────────┘ └─────────────────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ extended_hours_service.py │\n│ (盘后服务层) │\n│ ┌─────────────────┐ ┌─────────────────────────────┐ │\n│ │ 盘前盘后检测 │ │ 市场状态判定 │ │\n│ │ extended_hours │ │ market_state │ │\n│ └─────────────────┘ └─────────────────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ Yahoo Finance API │\n│ (外部数据源) │\n└─────────────────────────────────────────────────────────┘\n```\n\n### 支持的资产类别\n\n| 资产类别 | 示例标的 | 数据内容 |\n|---------|---------|---------|\n| **股票** | AAPL, TSLA, NVDA | 价格、涨跌幅、52周高低 |\n| **加密货币** | BTC-USD, ETH-USD | 实时报价、24h变化 |\n| **ETF** | SPY, QQQ | 实时行情 |\n| **指数** | S&P500, NASDAQ, VIX | 市场指数点位 |\n| **外汇** | EUR/USD | 汇率报价 |\n| **土耳其股票** | THYAO.IS, SASA.IS | 本地市场报价 |\n\n资料来源：[CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)\n\n---\n\n## 核心服务模块\n\n### yahoo_finance_service.py\n\n`yahoo_finance_service.py` 是 Yahoo Finance 集成的核心服务模块，负责与 Yahoo Finance API 交互并返回结构化的市场数据。\n\n#### 主要功能\n\n| 功能 | 说明 |\n|-----|-----|\n| `get_yahoo_price()` | 获取单个标的的实时行情 |\n| `get_market_snapshot()` | 生成全球市场概览（14个标的） |\n| `get_prices_bulk()` | 批量获取多标的报价 |\n\n#### yahoo_price 工具\n\n`yahoo_price` 是 MCP 工具的核心入口，调用 `yahoo_finance_service.py` 中的函数获取实时数据。\n\n**返回值结构：**\n\n```json\n{\n \"symbol\": \"AAPL\",\n \"price\": 175.30,\n \"change\": 3.62,\n \"change_percent\": 2.11,\n \"52_week_high\": 198.23,\n \"52_week_low\": 124.17,\n \"market_state\": \"REGULAR\"\n}\n```\n\n#### market_snapshot 工具\n\n`market_snapshot` 提供全球市场概览，覆盖 **14 个标的** 和 **4 个资产类别**。\n\n**快照覆盖范围：**\n\n| 资产类别 | 标的数量 | 代表标的 |\n|---------|---------|---------|\n| 股票指数 | 3 | S&P 500, NASDAQ, VIX |\n| 加密货币 | 2 | BTC, ETH |\n| 外汇 | 2 | EUR/USD, GBP/USD |\n| 商品期货 | 1 | 黄金/石油 |\n\n资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n---\n\n### extended_hours_service.py\n\n`extended_hours_service.py` 负责处理美股盘前盘后交易时段的检测与市场状态判定。\n\n#### 市场状态定义\n\n| 状态 | 说明 | 时间范围（美东时间） |\n|-----|------|---------------------|\n| `PRE_MARKET` | 盘前交易 | 04:00 - 09:30 |\n| `REGULAR` | 常规交易时段 | 09:30 - 16:00 |\n| `AFTER_HOURS` | 盘后交易 | 16:00 - 20:00 |\n| `CLOSED` | 市场关闭 | 周末/节假日 |\n\n#### 服务流程\n\n```mermaid\ngraph TD\n A[请求行情数据] --> B{检查标的类型}\n B -->|美股| C[调用 extended_hours_service]\n B -->|非美股| D[直接返回报价]\n C --> E[获取当前时间]\n E --> F{判定市场状态}\n F -->|盘前| G[返回 PRE_MARKET]\n F -->|盘中| H[返回 REGULAR]\n F -->|盘后| I[返回 AFTER_HOURS]\n F -->|非交易时段| J[返回 CLOSED]\n G --> K[附加盘前/盘后数据]\n H --> L[返回实时价格]\n I --> M[附加盘后数据]\n J --> N[返回最后收盘价]\n K --> O[合并到最终响应]\n L --> O\n M --> O\n N --> O\n```\n\n---\n\n## MCP 工具接口\n\n### 工具清单\n\n| 工具名 | 功能 | 适用资产 |\n|-------|------|---------|\n| `yahoo_price` | 单标的实时报价 | 股票、加密货币、ETF、外汇 |\n| `market_snapshot` | 全球市场概览 | 14个核心标的 |\n| `get_prices_bulk` | 批量价格查询 | 多标的 |\n\n资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n### yahoo_price 参数说明\n\n| 参数 | 类型 | 必需 | 说明 | 示例 |\n|-----|------|-----|------|-----|\n| `symbol` | string | 是 | 标的代码 | `AAPL`、`BTC-USD` |\n| `include_extended` | boolean | 否 | 是否包含盘后数据 | `true` |\n\n### market_snapshot 参数说明\n\n| 参数 | 类型 | 必需 | 说明 |\n|-----|------|-----|------|\n| 无 | - | - | 无参数，返回全球市场概览 |\n\n---\n\n## 数据流处理\n\n### 实时报价获取流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant MCP as MCP Server\n participant YFS as Yahoo Finance Service\n participant EHS as Extended Hours Service\n participant YF as Yahoo Finance API\n\n User->>MCP: yahoo_price(\"AAPL\")\n MCP->>YFS: get_yahoo_price(\"AAPL\")\n YFS->>YF: 请求 AAPL 报价\n YF-->>YFS: 返回 OHLCV 数据\n YFS->>EHS: 检测市场状态\n EHS-->>YFS: 返回 market_state\n YFS-->>MCP: 构造响应数据\n MCP-->>User: 返回完整报价\n\n User->>MCP: market_snapshot()\n MCP->>YFS: get_market_snapshot()\n loop 14个标的\n YFS->>YF: 批量请求\n YF-->>YFS: 返回数据\n end\n YFS-->>MCP: 返回市场概览\n MCP-->>User: 返回全球市场快照\n```\n\n### 数据处理逻辑\n\n```python\n# 伪代码示例\ndef get_yahoo_price(symbol: str) -> dict:\n # 1. 调用 Yahoo Finance API\n raw_data = yahoo_finance_api.get_quote(symbol)\n \n # 2. 检测盘前盘后状态\n market_state = detect_market_state(symbol)\n \n # 3. 计算涨跌幅\n change = raw_data['current_price'] - raw_data['previous_close']\n change_percent = (change / raw_data['previous_close']) * 100\n \n # 4. 构造返回值\n return {\n \"symbol\": symbol,\n \"price\": raw_data['current_price'],\n \"change\": change,\n \"change_percent\": change_percent,\n \"52_week_high\": raw_data['fifty_two_week_high'],\n \"52_week_low\": raw_data['fifty_two_week_low'],\n \"market_state\": market_state\n }\n```\n\n---\n\n## 与其他模块的集成\n\n### 集成关系图\n\n```mermaid\ngraph LR\n A[Yahoo Finance 集成] --> B[server.py]\n A --> C[Technical Analysis]\n A --> D[Backtesting Engine]\n A --> E[Market Screener]\n \n B -->|MCP 工具| F[Claude Desktop]\n B -->|MCP 工具| G[OpenClaw]\n \n C -->|price_data| H[RSI 计算]\n C -->|price_data| I[MACD 计算]\n C -->|price_data| J[Bollinger Bands]\n \n D -->|历史数据| K[策略回测]\n D -->|历史数据| L[Compare Strategies]\n \n E -->|symbol| M[Top Gainers]\n E -->|symbol| N[Top Losers]\n```\n\n---\n\n## 版本历史\n\n| 版本 | 日期 | 更新内容 |\n|-----|------|---------|\n| 0.6.0 | 2026-03-29 | **初始集成**：yahoo_price、market_snapshot、get_prices_bulk |\n\n资料来源：[CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)\n\n---\n\n## 使用示例\n\n### 获取单只股票报价\n\n```python\n# MCP 工具调用示例\nyahoo_price(symbol=\"AAPL\")\n\n# 返回\n{\n \"symbol\": \"AAPL\",\n \"price\": 175.30,\n \"change\": 3.62,\n \"change_percent\": 2.11,\n \"52_week_high\": 198.23,\n \"52_week_low\": 124.17,\n \"market_state\": \"REGULAR\"\n}\n```\n\n### 获取全球市场概览\n\n```python\n# MCP 工具调用示例\nmarket_snapshot()\n\n# 返回概览包含：\n# - S&P 500、NASDAQ、VIX 指数\n# - BTC、ETH 加密货币\n# - EUR/USD、GBP/USD 外汇\n# - 黄金/石油商品\n```\n\n### 获取土耳其股票\n\n```python\n# 土耳其股票使用 .IS 后缀\nyahoo_price(symbol=\"THYAO.IS\")\nyahoo_price(symbol=\"SASA.IS\")\n```\n\n---\n\n## 错误处理与限制\n\n### 常见问题\n\n| 问题 | 原因 | 解决方案 |\n|-----|------|---------|\n| 返回空数据 | 标的代码错误 | 检查 Yahoo Finance 格式 |\n| 盘后数据缺失 | 非美股标的 | 确认标的为美股 |\n| 限流 | 请求过于频繁 | 添加延迟或使用缓存 |\n\n### 速率限制\n\n- Yahoo Finance API 有隐式速率限制\n- 建议批量查询使用 `get_prices_bulk` 而非循环调用 `yahoo_price`\n\n---\n\n## 相关文件\n\n| 文件路径 | 功能 |\n|---------|------|\n| `src/tradingview_mcp/core/services/yahoo_finance_service.py` | Yahoo Finance API 封装 |\n| `src/tradingview_mcp/core/services/extended_hours_service.py` | 盘前盘后检测服务 |\n| `src/tradingview_mcp/server.py` | MCP 工具定义与路由 |\n| `CHANGELOG.md` | 版本更新记录 |\n| `README.md` | 项目文档 |\n\n---\n\n\n\n## 数据源与货币列表\n\n### 相关页面\n\n相关主题：[多交易所支持](#page-exchange-support), [Yahoo Finance 集成](#page-yahoo-finance)\n\n\n相关源码文件
\n\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- [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- [src/tradingview_mcp/coinlist/binance.txt](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/coinlist/binance.txt)\n- [src/tradingview_mcp/coinlist/all.txt](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/coinlist/all.txt)\n \n\n# 数据源与货币列表\n\n## 概述\n\n`tradingview-mcp` 是一个基于 Model Context Protocol (MCP) 的 TradingView 技术分析服务器。该项目的数据源与货币列表系统负责管理交易所交易对信息、货币符号映射以及市场类型识别，为整个系统提供标准化的数据输入源。\n\n项目采用文本文件存储货币列表，并通过专门的 Python 服务模块进行读取和管理，支持多种加密货币交易所和股票市场。\n\n---\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[用户请求] --> B[server.py 入口]\n B --> C{市场类型判断}\n C -->|加密货币| D[coinlist_service.py]\n C -->|股票/ETF| E[validators.py 交易所映射]\n D --> F[coinlist/ 目录]\n E --> G[TradingView Screener API]\n F --> H[binance.txt]\n F --> I[kucoin.txt]\n F --> J[all.txt]\n D --> K[proxy_manager.py 代理管理]\n G --> L[返回分析结果]\n H --> D\n I --> D\n J --> D\n```\n\n### 货币列表目录结构\n\n```\nsrc/tradingview_mcp/\n├── coinlist/\n│ ├── all.txt # 全交易所合并货币列表\n│ ├── binance.txt # Binance 交易对\n│ ├── kucoin.txt # KuCoin 交易对\n│ ├── mexc.txt # MEXC 交易对\n│ ├── bybit.txt # Bybit 交易对\n│ └── 其他交易所文件...\n└── core/\n └── services/\n ├── coinlist.py # 货币列表服务\n └── screener_service.py # 筛选器服务\n```\n\n---\n\n## 货币列表服务 (coinlist_service.py)\n\n### 核心功能\n\n`coinlist_service.py` 是货币列表的核心管理模块，负责加载、缓存和查询各交易所的货币符号列表。\n\n资料来源：[src/tradingview_mcp/core/services/coinlist.py]()\n\n### 主要函数\n\n| 函数 | 功能描述 |\n|------|----------|\n| `load_coinlist(exchange)` | 加载指定交易所的货币列表 |\n| `get_coinlist(exchange)` | 获取货币列表（带缓存） |\n| `get_all_symbols()` | 获取所有交易所的合并列表 |\n| `filter_by_exchange()` | 按交易所筛选货币 |\n\n### 目录路径解析\n\n```python\n# validators.py 中的路径计算逻辑\n_this_file = __file__ # core/utils/validators.py\n_utils_dir = os.path.dirname(_this_file) # core/utils\n_core_dir = os.path.dirname(_utils_dir) # core\n_package_dir = os.path.dirname(_core_dir) # tradingview_mcp\nCOINLIST_DIR = os.path.join(_package_dir, 'coinlist') # tradingview_mcp/coinlist\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:20-25]()\n\n---\n\n## 交易所映射系统\n\n### 交易所筛选器配置\n\n```python\nEXCHANGE_SCREENER = {\n \"binance\": \"BINANCE\",\n \"kucoin\": \"KUCOIN\",\n \"bybit\": \"BYBIT\",\n \"mexc\": \"MEXC\",\n \"NYSE\": \"NYSE\",\n \"NASDAQ\": \"NASDAQ\",\n \"AMEX\": \"AMEX\",\n \"NYSEARCA\": \"AMEX\",\n \"PCX\": \"AMEX\",\n \"TWSE\": \"TWSE\",\n \"TPEX\": \"TPEX\",\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n### 股票交易所标识\n\n```python\nSTOCK_EXCHANGES = {\n \"nyse\", \"nasdaq\", \"amex\", \"tsx\", \"lse\",\n \"jpx\", \"hkex\", \"sse\", \"szse\", \"twse\",\n \"tpex\", \"krx\", \"asx\", \"bse\", \"nse\",\n \"egx\", \"etr\", \"vse\", \"wse\", \"lsis\"\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n### 交易所前缀映射\n\n对于某些特殊交易所，系统需要将不同别名映射到统一前缀：\n\n```python\n_EXCHANGE_TV_PREFIX = {\n \"nysearca\": \"AMEX\",\n \"pcx\": \"AMEX\",\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n---\n\n## 数据源类型\n\n### 加密货币数据源\n\n| 交易所 | 数据格式 | 支持的交易对类型 |\n|--------|----------|------------------|\n| Binance | `SYMBOLUSDT` | USDT 永续合约为主 |\n| KuCoin | `SYMBOLUSDT` | USDT 永续合约 |\n| Bybit | `SYMBOLUSDT` | USDT 永续合约 |\n| MEXC | `SYMBOLUSDT` | USDT 永续合约 |\n\n### 股票/ETF 数据源\n\n| 市场 | 交易所代码 | 示例符号 |\n|------|------------|----------|\n| 美国主板 | `NYSE` | AAPL, TSLA, NVDA |\n| 纳斯达克 | `NASDAQ` | MSFT, GOOGL, AMZN |\n| 美国ETF | `AMEX` | SPY, QQQ, GLD, GDX |\n| 台湾上市 | `TWSE` | 2330, 0050, 0056 |\n| 台湾上柜 | `TPEX` | 指数成分股 |\n| 埃及 | `EGX` | 当地上市公司 |\n\n---\n\n## 符号构建与验证流程\n\n### 加密货币符号构建\n\n```mermaid\ngraph LR\n A[用户输入: BTC] --> B[sanitize_symbol]\n B --> C{交易所类型}\n C -->|加密货币| D[直接使用: BTCUSDT]\n C -->|股票/ETF| E[添加前缀: AMEX:GLD]\n D --> F[返回完整符号]\n E --> F\n```\n\n### 函数调用链\n\n```python\n# 1. 符号清理\nsanitize_symbol(symbol, exchange)\n\n# 2. 交易所验证\nsanitize_exchange(exchange, default=\"kucoin\")\n\n# 3. 市场类型判断\nis_stock_exchange(exchange) # 返回 True/False\n\n# 4. 前缀映射\nget_tv_exchange_prefix(exchange) # NYSEARCA -> AMEX\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n---\n\n## 代理管理系统 (proxy_manager.py)\n\n对于需要代理访问的数据源，项目提供了代理管理功能。\n\n### 代理配置存储\n\n- 代理配置通常存储在环境变量或配置文件中\n- 支持 HTTP/HTTPS/SOCKS5 代理协议\n- 代理轮换机制用于避免请求频率限制\n\n资料来源：[src/tradingview_mcp/core/services/proxy_manager.py]()\n\n---\n\n## 筛选器服务 (screener_service.py)\n\n### analyze_coin 函数\n\n`screener_service.py` 中的 `analyze_coin` 函数是核心分析入口：\n\n```python\nasync def analyze_coin(\n symbol: str,\n exchange: str = \"KUCOIN\",\n timeframe: str = \"1h\"\n) -> dict:\n \"\"\"分析单个交易品种的技术指标\"\"\"\n # 使用 get_tv_exchange_prefix 获取正确前缀\n # 构建 TradingView 格式符号: EXCHANGE:SYMBOL\n # 调用技术指标计算\n # 返回分析结果\n```\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py]()\n\n---\n\n## 时间周期别名映射\n\n项目支持灵活的时间周期输入：\n\n```python\n_TIMEFRAME_ALIASES = {\n \"1m\": \"1m\", \"3m\": \"3m\", \"5m\": \"5m\", \n \"15m\": \"15m\", \"30m\": \"30m\",\n \"1h\": \"1h\", \"2h\": \"2h\", \"4h\": \"4h\",\n \"6h\": \"6h\", \"8h\": \"8h\", \"12h\": \"12h\",\n \"1d\": \"1D\", \"1w\": \"1W\",\n # 中文别名\n \"日线\": \"1D\", \"周线\": \"1W\",\n \"1小时\": \"1h\", \"4小时\": \"4h\"\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n---\n\n## 配置文件\n\n### pyproject.toml 依赖\n\n```toml\n[project]\ndependencies = [\n \"tradingview-screener>=0.3.0\",\n \"yfinance>=0.2.0\",\n \"httpx>=0.27.0\",\n]\n```\n\n### 开发依赖\n\n```toml\n[tool.uv]\ndev-dependencies = [\n \"pytest>=8.0.0\",\n \"ruff>=0.4.0\",\n \"mypy>=1.8.0\",\n]\n```\n\n---\n\n## 测试覆盖\n\n项目为数据源和交易所功能提供了完整的单元测试：\n\n### 测试文件\n\n| 文件 | 测试数量 | 覆盖范围 |\n|------|----------|----------|\n| `tests/unit/test_exchange_fixes.py` | 32 | 交易所别名、前缀映射、符号构建 |\n| `tests/unit/test_exchange_aliases.py` | 37 | TWSE/TPEX 符号构造、预合格符号保护 |\n\n### 测试运行\n\n```bash\n# 运行所有测试\nuv run pytest\n\n# 运行特定测试文件\nuv run pytest tests/unit/test_exchange_fixes.py\n\n# 测试结果\n73 passed in 0.17s (69 new + 4 pre-existing)\n```\n\n资料来源：[PR_BODY.md]()\n\n---\n\n## 常见使用场景\n\n### 场景1：获取加密货币列表\n\n```python\nfrom tradingview_mcp.core.services.coinlist import get_coinlist\n\n# 获取 Binance 交易对\nbinance_coins = get_coinlist(\"binance\")\nprint(f\"Binance 支持 {len(binance_coins)} 个交易对\")\n```\n\n### 场景2：验证股票符号\n\n```python\nfrom tradingview_mcp.core.utils.validators import (\n sanitize_exchange,\n is_stock_exchange,\n get_tv_exchange_prefix\n)\n\n# 验证交易所\nexchange = sanitize_exchange(\"NYSEARCA\") # 返回 \"amex\"\nis_stock = is_stock_exchange(\"NYSE\") # 返回 True\n\n# 获取 TradingView 前缀\nprefix = get_tv_exchange_prefix(\"NYSEARCA\") # 返回 \"AMEX\"\n```\n\n### 场景3：构建完整交易符号\n\n```python\n# 股票ETF: AMEX:GLD\n# 加密货币: BTCUSDT (无前缀)\n\ndef build_tradingview_symbol(symbol: str, exchange: str) -> str:\n \"\"\"根据交易所类型构建 TradingView 格式符号\"\"\"\n if is_stock_exchange(exchange):\n prefix = get_tv_exchange_prefix(exchange)\n return f\"{prefix}:{symbol}\"\n return f\"{symbol}USDT\" # 加密货币默认USDT交易对\n```\n\n---\n\n## 总结\n\n数据源与货币列表系统是 `tradingview-mcp` 的基础设施组件，通过以下方式实现统一的数据访问：\n\n1. **文件式货币列表** - 使用纯文本文件存储，便于维护和扩展\n2. **交易所抽象层** - 统一的交易所标识和映射机制\n3. **智能符号构建** - 自动根据市场类型添加正确前缀\n4. **完整测试覆盖** - 确保交易所映射的准确性和稳定性\n\n---\n\n\n\n## 多交易所支持\n\n### 相关页面\n\n相关主题：[数据源与货币列表](#page-data-sources), [技术分析服务](#page-technical-analysis)\n\n\n相关源码文件
\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- [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/screener_provider.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_provider.py)\n- [src/tradingview_mcp/core/data/egx_indices.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/data/egx_indices.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- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n- [tests/unit/test_exchange_fixes.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/tests/unit/test_exchange_fixes.py)\n- [tests/unit/test_exchange_aliases.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/tests/unit/test_exchange_aliases.py)\n \n\n# 多交易所支持\n\n## 概述\n\n`tradingview-mcp` 项目提供了一套完整的多交易所支持架构，允许用户通过统一的接口访问全球多个金融市场的实时数据和技术分析。该系统支持加密货币交易所、传统股票交易所以及区域性市场，通过模块化的服务层实现交易所无关的数据获取和处理逻辑。\n\n多交易所支持的核心价值在于：\n\n- **统一 API 接口**：无论底层交易所类型如何，用户通过相同的函数调用获取数据\n- **交易所特定适配**：每种交易所类型都有专属的筛选器配置和数据格式处理\n- **符号标准化**：实现了 `sanitize_exchange` 和 `get_tv_exchange_prefix` 等函数确保符号在 TradingView 格式下正确路由\n- **市场类型识别**：通过 `is_stock_exchange` 和 `get_market_type` 等函数区分股票市场和加密货币市场\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:1-100]()\n\n---\n\n## 架构设计\n\n### 组件关系图\n\n```mermaid\ngraph TD\n subgraph \"表现层\"\n SERVER[server.py - MCP接口]\n end\n \n subgraph \"服务层\"\n SCREENER[screener_service.py
通用筛选器服务]\n EGX[egx_service.py
埃及交易所专用服务]\n SCREENER_PROVIDER[screener_provider.py
筛选器提供者]\n end\n \n subgraph \"数据层\"\n VALIDATORS[validators.py
交易所验证与规范化]\n EGX_INDICES[egx_indices.py
EGX指数数据]\n EGX_SECTORS[egx_sectors.py
EGX板块数据]\n COINLIST[coinlist/
交易所符号列表]\n end\n \n subgraph \"外部数据源\"\n TV[TradingView Screener API]\n YAHOO[Yahoo Finance API]\n end\n \n SERVER --> SCREENER\n SERVER --> EGX\n SCREENER --> SCREENER_PROVIDER\n SCREENER_PROVIDER --> VALIDATORS\n EGX --> VALIDATORS\n SCREENER_PROVIDER --> YAHOO\n EGX --> TV\n VALIDATORS --> COINLIST\n```\n\n### 交易所分类体系\n\n系统将支持的交易所分为两大类别：\n\n| 类别 | 说明 | 识别方式 |\n|------|------|----------|\n| **股票市场** | 传统证券交易所（NYSE、NASDAQ、TWSE 等） | `is_stock_exchange()` 返回 `True` |\n| **加密货币交易所** | 加密货币交易平台（KUCOIN、BINANCE 等） | 不在 `STOCK_EXCHANGES` 中 |\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:30-50]()\n\n---\n\n## 交易所配置与管理\n\n### 核心配置常量\n\n`validators.py` 文件定义了多个关键的交易所配置常量：\n\n```python\nEXCHANGE_SCREENER = {\n \"binance\": \"BINANCE\",\n \"kucoin\": \"KUCOIN\",\n \"bybit\": \"BYBIT\",\n \"mexc\": \"MEXC\",\n \"okx\": \"OKX\",\n \"coinbase\": \"COINBASE\",\n \"nasdaq\": \"NASDAQ\",\n \"nyse\": \"NYSE\",\n \"amex\": \"AMEX\",\n \"nysearca\": \"AMEX\",\n \"pcx\": \"AMEX\",\n \"twse\": \"TWSE\",\n \"tpex\": \"TPEX\",\n \"egx\": \"EGX\",\n \"bist\": \"BIST\",\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:1-50]()\n\n### 交易所别名映射\n\n系统通过 `EXCHANGE_SCREENER` 字典实现交易所别名到标准名称的映射：\n\n| 别名 | 标准名称 | 说明 |\n|------|----------|------|\n| `nysearca` | `AMEX` | NYSE Arca 交易所 |\n| `pcx` | `AMEX` | Arca 交易所（Pacific Exchange） |\n| `amex` | `AMEX` | 美国证券交易所 |\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:10-20]()\n\n### TradingView 前缀映射\n\n`get_tv_exchange_prefix()` 函数将交易所名称转换为 TradingView 符号格式：\n\n```python\n_EXCHANGE_TV_PREFIX = {\n \"amex\": \"AMEX\",\n \"nysearca\": \"AMEX\",\n \"pcx\": \"AMEX\",\n \"nyse\": \"NYSE\",\n \"nasdaq\": \"NASDAQ\",\n \"twse\": \"TWSE\",\n \"tpex\": \"TPEX\",\n}\n```\n\n该函数的工作流程如下：\n\n```mermaid\ngraph LR\n A[输入交易所名称] --> B{是否为已知别名?}\n B -->|是| C[返回映射的标准前缀]\n B -->|否| D[返回大写的原名称]\n C --> E[如: NYSEARCA → AMEX]\n D --> F[如: KUCOIN → KUCOIN]\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:50-80]()\n\n---\n\n## 服务层实现\n\n### 通用筛选器服务\n\n`screener_service.py` 提供了跨交易所的统一筛选功能：\n\n```python\nasync def analyze_coin(\n symbol: str,\n exchange: str = \"KUCOIN\",\n timeframe: str = \"1h\",\n screener: str = \"CRYPTO\"\n) -> dict:\n # 使用 get_tv_exchange_prefix 处理符号\n tv_prefix = get_tv_exchange_prefix(exchange)\n full_symbol = f\"{tv_prefix}:{symbol.upper()}\"\n```\n\n关键功能包括：\n\n- **符号构造**：将交易所前缀与交易对符号组合为完整 TradingView 符号\n- **时间框架规范化**：通过 `sanitize_timeframe` 统一处理时间框架参数\n- **交易所验证**：通过 `sanitize_exchange` 确保只使用支持的交易所\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py:1-100]()\n\n### 筛选器提供者\n\n`screener_provider.py` 负责根据不同交易所类型选择合适的数据源：\n\n```mermaid\ngraph TD\n A[请求筛选数据] --> B{交易所类型?}\n B -->|加密货币| C[使用 CoinGecko/CoinMarketCap]\n B -->|美国股票| D[使用 Yahoo Finance]\n B -->|TWSE/TPEX| E[使用 TradingView]\n B -->|EGX| F[使用 egx_service]\n C --> G[返回标准化数据]\n D --> G\n E --> G\n F --> G\n```\n\n---\n\n## 区域性市场支持\n\n### 埃及交易所 (EGX)\n\n埃及交易所是项目重点支持的区域性市场之一，提供完整的专用服务：\n\n#### EGX 服务组件\n\n| 组件 | 文件 | 功能 |\n|------|------|------|\n| `egx_service.py` | 核心服务 | EGX 特定的市场概览、股票筛选、交易计划 |\n| `egx_indices.py` | 指数数据 | EGX 主要指数成分和权重 |\n| `egx_sectors.py` | 板块数据 | EGX 行业板块分类 |\n\n资料来源：[src/tradingview_mcp/core/services/egx_service.py:1-50]()\n\n#### EGX 指数配置\n\n```python\nEGX_INDICES = {\n \"EGX30\": {\n \"name\": \"EGX 30 Index\",\n \"description\": \"Primary index tracking top 30 companies\",\n \"constituents\": [\"COMI\", \"MRDY\", \"ETEL\", ...]\n },\n \"EGX70\": {\n \"name\": \"EGX 70 Index\",\n \"description\": \"Broader index tracking mid-cap companies\"\n }\n}\n```\n\n资料来源：[src/tradingview_mcp/core/data/egx_indices.py:1-100]()\n\n#### EGX 板块分类\n\n```python\nEGX_SECTORS = {\n \"banking\": [\"CIB\", \"SAUD\", \"HDBK\"],\n \"telecom\": [\"WE\", \"ETEL\", \"OCDI\"],\n \"real_estate\": [\"TMGH\", \"EAST\", \"SKIP\"],\n \"industrial\": [\"PRMH\", \"LOX\", \"ALCN\"],\n \"tourism\": [\"EGAL\", \"EURN\", \"TOBA\"],\n}\n```\n\n资料来源：[src/tradingview_mcp/core/data/egx_sectors.py:1-100]()\n\n### 台湾交易所 (TWSE/TPEX)\n\n台湾股票市场通过 TradingView 筛选器直接支持：\n\n| 市场 | 交易所代码 | 示例股票 |\n|------|-----------|----------|\n| 台湾证券交易所 | `TWSE` | 2330 (台积电)、0050 (元大台50) |\n| 台湾柜台买卖中心 | `TPEX` | 0056 (元大高股息) |\n\n这些股票已预先配置在 `EXCHANGE_SCREENER` 中，可直接使用筛选器功能。\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:10-15]()\n\n---\n\n## 符号构造与规范化\n\n### 符号构造流程\n\n在 `server.py` 的 `multi_timeframe_analysis` 函数中展示了完整的符号构造流程：\n\n```python\nasync def multi_timeframe_analysis(\n symbol: str,\n exchange: str = \"KUCOIN\",\n timeframes: list[str] = None\n) -> dict:\n # 1. 规范化交易所名称\n tv_prefix = get_tv_exchange_prefix(exchange)\n \n # 2. 构造完整 TradingView 符号\n full_symbol = f\"{tv_prefix}:{symbol.upper()}\"\n \n # 3. 从多个时间框架获取数据\n results = {}\n for tf in timeframes:\n data = await get_technical_analysis(\n symbol=full_symbol,\n exchange=exchange,\n timeframe=tf\n )\n results[tf] = data\n```\n\n资料来源：[src/tradingview_mcp/server.py:1-100]()\n\n### 符号格式对照表\n\n| 交易所 | 符号前缀 | 示例符号 |\n|--------|----------|----------|\n| KuCoin | `KUCOIN` | `KUCOIN:BTCUSDT` |\n| Binance | `BINANCE` | `BINANCE:BNBUSDT` |\n| NYSE | `NYSE` | `NYSE:AAPL` |\n| NASDAQ | `NASDAQ` | `NASDAQ:TSLA` |\n| AMEX | `AMEX` | `AMEX:GDX` |\n| TWSE | `TWSE` | `TWSE:2330` |\n| TPEX | `TPEX` | `TPEX:0056` |\n\n---\n\n## 测试覆盖\n\n### 交易所修复测试\n\n项目通过完整的单元测试确保多交易所支持的正确性：\n\n| 测试文件 | 测试数量 | 覆盖范围 |\n|----------|----------|----------|\n| `test_exchange_fixes.py` | 32 个测试 | AMEX/NYSEARCA/PCX 别名、符号构造、回归测试 |\n| `test_exchange_aliases.py` | 37 个测试 | TWSE/TPEX 符号构造、预校验符号保护 |\n\n#### 测试覆盖的关键场景\n\n```python\n# test_exchange_fixes.py 示例测试\ndef test_get_tv_exchange_prefix_nysearca():\n \"\"\"NYSEARCA 应映射到 AMEX\"\"\"\n assert get_tv_exchange_prefix(\"NYSEARCA\") == \"AMEX\"\n\ndef test_sanitize_exchange_valid():\n \"\"\"有效交易所应保持不变\"\"\"\n assert sanitize_exchange(\"AMEX\") == \"amex\"\n\ndef test_symbol_construction_gdx():\n \"\"\"GDX ETF 应正确构造为 AMEX:GDX\"\"\"\n tv_prefix = get_tv_exchange_prefix(\"NYSEARCA\")\n assert f\"{tv_prefix}:GDX\" == \"AMEX:GDX\"\n```\n\n资料来源：[tests/unit/test_exchange_fixes.py:1-100]()\n\n#### 回归测试\n\n测试套件确保现有功能不受影响：\n\n```python\ndef test_regression_nyse():\n assert get_tv_exchange_prefix(\"NYSE\") == \"NYSE\"\n\ndef test_regression_twse():\n assert get_tv_exchange_prefix(\"TWSE\") == \"TWSE\"\n\ndef test_regression_kucoin():\n assert get_tv_exchange_prefix(\"KUCOIN\") == \"KUCOIN\"\n```\n\n**测试结果**：73 个测试通过（69 个新增 + 4 个既有测试），耗时 0.17 秒。\n\n资料来源：[PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n\n---\n\n## 支持的交易所汇总\n\n### 加密货币交易所\n\n| 交易所 | 代码 | 筛选器支持 | 实时价格 |\n|--------|------|------------|----------|\n| KuCoin | `KUCOIN` | ✅ | ✅ |\n| Binance | `BINANCE` | ✅ | ✅ |\n| Bybit | `BYBIT` | ✅ | ✅ |\n| MEXC | `MEXC` | ✅ | ✅ |\n| OKX | `OKX` | ✅ | ✅ |\n| Coinbase | `COINBASE` | ✅ | ✅ |\n\n### 美国股票交易所\n\n| 交易所 | 代码 | 筛选器支持 | 符号示例 |\n|--------|------|------------|----------|\n| 纽约证券交易所 | `NYSE` | ✅ | AAPL, JPM, XOM |\n| 纳斯达克 | `NASDAQ` | ✅ | TSLA, NVDA, AMZN |\n| 美国证券交易所 | `AMEX` | ✅ | GDX, GLD, XLE |\n| NYSE Arca | `NYSEARCA` | ✅ | 同 AMEX |\n| Arca (Pacific) | `PCX` | ✅ | 同 AMEX |\n\n### 区域性股票交易所\n\n| 市场 | 交易所 | 代码 | 专用服务 |\n|------|--------|------|----------|\n| 台湾 | 台湾证券交易所 | `TWSE` | - |\n| 台湾 | 台湾柜买中心 | `TPEX` | - |\n| 埃及 | 埃及证券交易所 | `EGX` | ✅ |\n| 土耳其 | 伊斯坦布尔证券交易所 | `BIST` | ✅ |\n\n---\n\n## 扩展新的交易所\n\n### 步骤 1：更新配置常量\n\n在 `validators.py` 中添加新的交易所映射：\n\n```python\n# 添加到 EXCHANGE_SCREENER\nEXCHANGE_SCREENER[\"new_exchange\"] = \"NEW_EXCHANGE\"\n\n# 如果有别名，添加映射\nEXCHANGE_SCREENER[\"alias\"] = \"NEW_EXCHANGE\"\n\n# 如果需要特殊前缀映射\n_EXCHANGE_TV_PREFIX[\"new_exchange\"] = \"NEW_EXCHANGE\"\n```\n\n### 步骤 2：添加符号列表（如需要）\n\n```bash\n# 创建新的符号列表文件\ntouch src/tradingview_mcp/coinlist/new_exchange.txt\n# 每行添加一个交易对符号\n```\n\n### 步骤 3：验证实现\n\n```bash\n# 运行测试\nuv run pytest tests/unit/test_exchange_fixes.py\n\n# 测试符号构造\nuv run python -c \"\nfrom src.tradingview_mcp.core.utils.validators import get_tv_exchange_prefix, sanitize_exchange\nprint(get_tv_exchange_prefix('NEW_EXCHANGE'))\nprint(sanitize_exchange('new_exchange'))\n\"\n```\n\n---\n\n## 最佳实践\n\n### 交易所名称处理\n\n始终使用 `sanitize_exchange()` 函数处理用户输入：\n\n```python\n# 好的做法\nexchange = sanitize_exchange(user_input)\ntv_prefix = get_tv_exchange_prefix(exchange)\n\n# 避免的做法\nexchange = user_input.upper() # 可能导致验证失败\n```\n\n### 符号构造\n\n使用 `get_tv_exchange_prefix()` 确保符号格式正确：\n\n```python\n# 正确示例\nsymbol = f\"{get_tv_exchange_prefix(exchange)}:{ticker.upper()}\"\n\n# 对于加密货币，原有名称保持不变\nif is_stock_exchange(exchange):\n symbol = f\"{get_tv_exchange_prefix(exchange)}:{ticker.upper()}\"\nelse:\n symbol = f\"{exchange.upper()}:{ticker.upper()}\"\n```\n\n### 时间框架规范化\n\n```python\ntf = sanitize_timeframe(timeframe, default=\"1h\")\n```\n\n---\n\n## 相关文档\n\n- [安装指南](../setup/installation.md) - 如何配置多交易所环境\n- [API 参考](../api/reference.md) - 各交易所函数完整参数说明\n- [故障排除](../troubleshooting.md) - 常见交易所连接问题\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：atilaahmettaner/tradingview-mcp\n\n摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。\n\n## 1. 安全/权限坑 · 涉及密钥、隐私或敏感领域\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。\n- 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。\n- 建议检查：补敏感数据流、密钥存储和权限边界审查。\n- 防护动作：敏感领域或密钥场景必须保守推荐并要求人工复核。\n- 证据：packet_text.keyword_scan | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | matched secret / private key / privacy / trading / finance keyword\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | host_targets=mcp_host, claude, cursor, chatgpt\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：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 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "tradingview-mcp 说明书",
"toc": [
"https://github.com/atilaahmettaner/tradingview-mcp 项目说明书",
"目录",
"项目概览",
"什么是 tradingview-mcp",
"核心架构",
"核心功能",
"支持的交易所",
"可用工具列表",
"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": "412cbc94be060dd708b1bc42861da7222eaa86df",
"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/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\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概览**：importance `high`\n - source_paths: README.md, pyproject.toml, CHANGELOG.md\n- **安装指南**：importance `high`\n - source_paths: INSTALLATION.md, .env.example, pyproject.toml\n- **系统架构**：importance `high`\n - source_paths: src/tradingview_mcp/server.py, src/tradingview_mcp/__init__.py, assets/architecture.png\n- **核心组件**：importance `high`\n - source_paths: src/tradingview_mcp/core/types.py, src/tradingview_mcp/core/portfolio.py, src/tradingview_mcp/core/utils/validators.py, src/tradingview_mcp/server.py\n- **回测引擎**：importance `high`\n - source_paths: src/tradingview_mcp/core/services/backtest_service.py, src/tradingview_mcp/core/services/multi_agent_service.py\n- **技术分析服务**：importance `high`\n - source_paths: src/tradingview_mcp/core/services/indicators.py, src/tradingview_mcp/core/services/indicators_calc.py, src/tradingview_mcp/core/services/screener_service.py, src/tradingview_mcp/core/services/scanner_service.py\n- **情感分析与新闻服务**：importance `medium`\n - source_paths: src/tradingview_mcp/core/services/sentiment_service.py, src/tradingview_mcp/core/services/news_service.py\n- **Yahoo Finance 集成**：importance `medium`\n - source_paths: src/tradingview_mcp/core/services/yahoo_finance_service.py, src/tradingview_mcp/core/services/extended_hours_service.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `412cbc94be060dd708b1bc42861da7222eaa86df`\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/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`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 涉及密钥、隐私或敏感领域\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: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 可能修改宿主 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: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 能力判断依赖假设\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: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 维护活跃度未知\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: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 下游验证发现风险项\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: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 存在评分风险\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: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 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: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 发布节奏不明确\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: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：atilaahmettaner/tradingview-mcp\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude, cursor, chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 涉及密钥、隐私或敏感领域（high）：金融、交易、隐私和密钥场景必须比普通工具更保守。 建议检查：补敏感数据流、密钥存储和权限边界审查。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"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-11 19:46:48 UTC\n\n## 目录\n\n- [项目概览](#page-project-overview)\n- [安装指南](#page-installation-guide)\n- [系统架构](#page-architecture)\n- [核心组件](#page-core-components)\n- [回测引擎](#page-backtesting-engine)\n- [技术分析服务](#page-technical-analysis)\n- [情感分析与新闻服务](#page-sentiment-analysis)\n- [Yahoo Finance 集成](#page-yahoo-finance)\n- [数据源与货币列表](#page-data-sources)\n- [多交易所支持](#page-exchange-support)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation-guide), [系统架构](#page-architecture)\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- [CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n- [OPENCLAW.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/OPENCLAW.md)\n- [EXAMPLES.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/EXAMPLES.md)\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 \n\n# 项目概览\n\n## 什么是 tradingview-mcp\n\n**tradingview-mcp** 是一个基于 Model Context Protocol (MCP) 的服务器，专为 AI 助手（如 Claude Desktop、OpenClaw、Codex）提供金融市场数据访问能力。该项目充当 AI 与 TradingView、Yahoo Finance 等数据源之间的桥梁，使 AI 能够执行技术分析、选股扫描、情绪分析、回测策略等任务。 资料来源：[README.md:1-15]()\n\n该项目完全开源，采用 MIT 许可证，支持 Windows、macOS 和 Linux 多平台运行。开发者可以自由修改代码、集成新功能，或将其部署在个人服务器上。 资料来源：[README.md:LICENSE]()\n\n## 核心架构\n\ntradingview-mcp 采用模块化服务架构，核心组件包括以下几个部分：\n\n```mermaid\ngraph TD\n A[AI 助手
Claude/Codex/OpenClaw] --> B[MCP Server
server.py]\n B --> C[服务层]\n C --> D[screener_service
选股服务]\n C --> E[technical_service
技术分析服务]\n C --> F[sentiment_service
情绪分析服务]\n C --> G[news_service
新闻服务]\n C --> H[backtest_service
回测服务]\n C --> I[egx_service
埃及交易所服务]\n D --> J[TradingView API
tradingview_ta]\n E --> J\n G --> K[Reddit API]\n H --> J\n J --> L[Yahoo Finance]\n```\n\n### 目录结构\n\n```\nsrc/tradingview_mcp/\n├── server.py # MCP 主服务器入口\n├── core/\n│ ├── services/ # 核心业务逻辑服务\n│ │ ├── screener_service.py # 选股扫描服务\n│ │ ├── technical_service.py # 技术分析服务\n│ │ ├── sentiment_service.py # 情绪分析服务\n│ │ ├── news_service.py # 新闻服务\n│ │ ├── backtest_service.py # 回测服务\n│ │ └── egx_service.py # EGX 埃及交易所服务\n│ ├── utils/ # 工具函数\n│ │ └── validators.py # 验证器和常量定义\n│ └── indicators/ # 技术指标计算\n├── coinlist/ # 各交易所交易对列表\n└── __init__.py\n```\n\n资料来源：[CONTRIBUTING.md:代码组织]()\n\n## 核心功能\n\n### 技术分析引擎\n\ntradingview-mcp 提供超过 **30 种技术指标** 的实时计算能力，包括 RSI、MACD、布林带、EMA、SMA、ATR 等。每项指标都会生成对应的交易信号（BUY/SELL/HOLD）并附带评分。 资料来源：[README.md:技术分析核心]()\n\n| 指标类型 | 包含指标 |\n|---------|---------|\n| 趋势指标 | EMA、SMA、MACD、ADX、Ichimoku、Supertrend |\n| 动量指标 | RSI、CCI、 Stochastic、Momentum、ROC |\n| 波动性指标 | 布林带（BB）、ATR、 标准差 |\n| 成交量指标 | OBV、VWMA、Volume |\n\n### 选股扫描器\n\n支持多交易所的股票/加密货币筛选，可按涨幅、跌幅、技术信号等多种条件过滤：\n\n- `top_gainers` — 涨幅榜\n- `top_losers` — 跌幅榜 \n- `scan_by_signal` — 按信号类型筛选（超买、超卖、趋势、突破）\n- `screen_stocks` — 多条件组合筛选（支持 20+ 过滤条件） 资料来源：[README.md:筛选器]()\n\n### 回测引擎\n\n内置 **6 种交易策略** 的回测功能，支持机构级指标分析：\n\n| 策略名称 | 类型 | 说明 |\n|---------|------|------|\n| `rsi` | 均值回归 | RSI 超买超卖策略 |\n| `bollinger` | 均值回归 | 布林带策略 |\n| `macd` | 趋势 | MACD 金叉死叉 |\n| `ema_cross` | 趋势 | EMA 20/50 金叉死叉 |\n| `supertrend` | 趋势跟踪 | ATR-based Supertrend |\n| `donchian` | 趋势跟踪 | 唐奇安通道（海龟交易法则风格） |\n\n回测提供以下核心指标：\n\n- 胜率 (Win Rate)\n- 总收益率 (Total Return)\n- 夏普比率 (Sharpe Ratio)\n- 卡玛比率 (Calmar Ratio)\n- 最大回撤 (Max Drawdown)\n- 利润因子 (Profit Factor)\n- 期望值 (Expectancy) 资料来源：[README.md:回测引擎]()\n\n### 情绪与新闻分析\n\n| 功能 | 数据源 | 说明 |\n|-----|-------|------|\n| Reddit 情绪分析 | Reddit API | 分析 subreddits 帖子情绪 |\n| 实时新闻 | RSS 订阅源 | 财经新闻聚合 |\n| 蜡烛图形态识别 | TradingView | 识别 15 种 K 线形态 |\n\n资料来源：[README.md:情绪与新闻]()\n\n## 支持的交易所\n\ntradingview-mcp 支持全球多个主要交易所，涵盖加密货币和传统股票市场： 资料来源：[README.md:多交易所支持]()\n\n### 加密货币交易所\n\n| 交易所 | 代码 | 支持功能 |\n|-------|------|---------|\n| Binance | BINANCE | 全交易对筛选、技术分析 |\n| KuCoin | KUCOIN | 全交易对筛选、技术分析 |\n| Bybit+ | BYBIT | 全交易对筛选、技术分析 |\n| MEXC | MEXC | 全交易对筛选、技术分析 |\n\n### 传统股票市场\n\n| 交易所 | 代码 | 支持功能 |\n|-------|------|---------|\n| 纳斯达克 | NASDAQ | 美股筛选、技术分析 |\n| 纽约证券交易所 | NYSE | 美股筛选、技术分析 |\n| 纽约证券交易所高增长 | NYSEARCA | ETF 筛选 |\n| 美国证券交易所 | AMEX | 美股筛选 |\n| 台湾证券交易所 | TWSE | 台股筛选 |\n| 台湾柜台买卖中心 | TPEX | 台股筛选 |\n| 土耳其伊斯坦布尔证交所 | BIST | 土股筛选 |\n| 埃及证券交易所 | EGX | 专用 EGX 服务（Fibonacci、止损推荐等） |\n\n资料来源：[PR_BODY.md:TWSE和TPEX支持]()\n\n## 可用工具列表\n\n### 市场数据工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `yahoo_price` | 实时报价：价格、涨跌幅、52 周高低、市场状态 |\n| `market_snapshot` | 全球市场概览：标普 500、纳斯达克、BTC、EUR/USD 等 |\n| `get_prices_bulk` | 多标的批量价格查询 |\n\n### 技术分析工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `get_technical_analysis` | 完整技术分析：RSI、MACD、布林带等 23 项指标 |\n| `get_multiple_analysis` | 批量多标的分析 |\n| `get_bollinger_band_analysis` | 专有 ±3 布林带评级系统 |\n| `get_stock_decision` | 三层决策引擎（排名 + 交易设置 + 质量评分） |\n| `scan_by_signal` | 按信号类型扫描（超卖、趋势、突破...） |\n| `get_candlestick_patterns` | 15 种蜡烛图形态检测 |\n| `get_multi_timeframe_analysis` | 周线→日线→4H→1H→15m 多时间框架对齐分析 |\n| `consecutive_candles_scan` | 连续 K 线扫描（检测持续性涨跌） |\n\n### 回测工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `backtest_strategy` | 回测单一策略并输出机构级指标 |\n| `compare_strategies` | 对比全部 6 种策略在同一标的上，按表现排名 |\n\n### 情绪新闻工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `get_reddit_sentiment` | Reddit 指定主题情绪分析 |\n| `get_news` | 实时财经新闻 |\n\n### EGX 专用工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `egx_market_overview` | 埃及股市整体概览 |\n| `egx_stock_screener` | EGX 股票筛选器 |\n| `egx_trade_plan` | 止损/止盈推荐 |\n| `egx_fibonacci_retracement` | 斐波那契回撤分析 |\n\n资料来源：[README.md:完整工具列表]()\n\n## 安装方式\n\n### 方式一：Claude Desktop（推荐）\n\n在 `claude_desktop_config.json` 中添加配置：\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\nWindows 用户需使用完整路径：\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"%USERPROFILE%\\\\.local\\\\bin\\\\uvx.exe\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n\n资料来源：[INSTALLATION.md:Claude Desktop配置]()\n\n### 方式二：从源码安装\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资料来源：[INSTALLATION.md:本地开发设置]()\n\n### 方式三：通过 OpenClaw 连接 Telegram\n\ntradingview-mcp 可与 OpenClaw 集成，通过 Telegram、WhatsApp、Discord 等 20+ 平台访问：\n\n```\nTelegram → OpenClaw agent (AI model) → trading.py → tradingview-mcp → Yahoo Finance\n```\n\n资料来源：[OPENCLAW.md:工作原理]()\n\n## 开发指南\n\n### 开发环境搭建\n\n```bash\n# 安装依赖\nuv sync\n\n# 安装开发依赖\nuv sync --dev\n\n# 运行测试\nuv run pytest\n\n# 代码检查\nuv run ruff check\n\n# 类型检查\nuv run mypy src/\n```\n\n资料来源：[CONTRIBUTING.md:开发环境]()\n\n### 代码规范\n\n| 规范类型 | 要求 |\n|---------|------|\n| Python 风格 | 遵循 PEP 8 |\n| 代码格式化 | 使用 Ruff |\n| 类型注解 | 所有公共函数需添加类型提示 |\n| 文档字符串 | 公共函数和类必须包含 docstring |\n| 函数命名 | snake_case（如 `get_top_gainers`） |\n| 类命名 | PascalCase（如 `MarketAnalyzer`） |\n| 常量命名 | UPPER_SNAKE_CASE（如 `DEFAULT_LIMIT`） |\n\n资料来源：[CONTRIBUTING.md:代码规范]()\n\n### 添加新交易所\n\n1. 更新验证器中的交易所映射：\n ```python\n # src/tradingview_mcp/core/utils/validators.py\n EXCHANGE_SCREENER = {\n \"NEW_EXCHANGE\": \"screener_code\",\n }\n ```\n\n2. 添加交易对列表文件：\n ```bash\n echo \"BTCUSDT\\nETHUSDT\\n...\" > coinlist/new_exchange.txt\n ```\n\n3. 测试集成：\n ```python\n result = top_gainers(exchange=\"NEW_EXCHANGE\")\n ```\n\n资料来源：[CONTRIBUTING.md:添加新交易所]()\n\n### 测试覆盖\n\n项目要求测试覆盖率 >80%，需同时测试成功路径和错误路径。 资料来源：[CONTRIBUTING.md:测试覆盖]()\n\n## 版本管理\n\n项目遵循语义化版本规范 (Semantic Versioning)：\n\n| 版本类型 | 说明 | 示例 |\n|---------|------|------|\n| 主版本 (X.0.0) | 破坏性变更 | 2.0.0 |\n| 次版本 (0.X.0) | 新功能，向后兼容 | 1.1.0 |\n| 补丁版本 (0.0.X) | Bug 修复，向后兼容 | 1.0.1 |\n\n## 路线图\n\n| 功能 | 状态 |\n|-----|------|\n| TradingView 技术分析（30+ 指标） | ✅ 已完成 |\n| 多交易所筛选（Binance、KuCoin、美股等） | ✅ 已完成 |\n| Reddit 情绪分析 | ✅ 已完成 |\n| Yahoo Finance 实时价格 | ✅ 已完成 |\n| 回测引擎（6 种策略 + 机构指标） | ✅ 已完成 |\n| 前向优化回测（过拟合检测） | 🔄 开发中 |\n| Twitter/X 市场情绪 | 📋 计划中 |\n| 模拟交易 | 📋 计划中 |\n| 云端托管服务 | 📋 计划中 |\n\n资料来源：[README.md:路线图]()\n\n## 项目统计\n\n- **开源协议**: MIT License\n- **平台支持**: Windows、macOS、Linux\n- **Python 版本**: 3.13（推荐）\n- **包管理**: UV\n- **主要依赖**: tradingview_ta、requests、beautifulsoup4\n\n## 相关链接\n\n| 资源 | 链接 |\n|-----|------|\n| GitHub 仓库 | https://github.com/atilaahmettaner/tradingview-mcp |\n| 问题反馈 | https://github.com/atilaahmettaner/tradingview-mcp/issues |\n| 赞助项目 | https://github.com/sponsors/atilaahmettaner |\n\n---\n\n\n\n## 安装指南\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.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- [PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n \n\n# 安装指南\n\n## 概述\n\n`tradingview-mcp` 是一个连接 TradingView 金融数据与 AI 代理的 MCP（Model Context Protocol）服务器项目。该项目支持实时市场数据、技术指标分析、加密货币筛选、股票筛选、回测等功能。\n\n安装指南涵盖了三种主要的安装方式：快速启动（Claude Desktop）、本地开发环境配置、以及传统的 Python 虚拟环境安装。同时支持 Windows、macOS 和 Linux 三大平台。\n\n## 系统架构\n\n```mermaid\ngraph TD\n A[用户 AI 客户端] --> B[MCP Server]\n B --> C[tradingview-mcp 核心]\n C --> D[TradingView API]\n C --> E[Yahoo Finance API]\n C --> F[Reddit API]\n C --> G[RSS 新闻源]\n \n H[Claude Desktop] --> B\n I[Codex] --> B\n J[OpenClaw] --> B\n```\n\n## 前置条件\n\n### 必要软件\n\n| 软件 | 版本要求 | 用途 |\n|------|----------|------|\n| Python | 3.13+ | 运行环境 |\n| Git | 最新版 | 代码版本管理 |\n| UV | 最新版 | 包管理器（推荐） |\n\n### UV 包管理器安装\n\nUV 是一个高性能的 Python 包管理器，建议优先使用。\n\n**Windows PowerShell：**\n```powershell\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n资料来源：[INSTALLATION.md:2]()\n\n**macOS/Linux：**\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\n```\n资料来源：[OPENCLAW.md:7]()\n\n## 安装方法一：快速启动（Claude Desktop）\n\n这是最简便的安装方式，适合不想修改代码只想直接使用工具的用户。\n\n### 步骤 1：克隆仓库\n\n```powershell\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n```\n资料来源：[INSTALLATION.md:6-7]()\n\n### 步骤 2：安装依赖\n\n```powershell\nuv sync\n```\n资料来源：[INSTALLATION.md:9]()\n\n### 步骤 3：配置 Claude Desktop\n\n定位配置文件路径：\n\n| 操作系统 | 路径 |\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\nWindows 用户可按 `Win + R`，输入 `%APPDATA%\\Claude` 并回车快速访问。\n\n### 步骤 4：编辑配置文件\n\n在 `claude_desktop_config.json` 中添加以下配置（将 `YOUR_USERNAME` 替换为实际用户名）：\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资料来源：[INSTALLATION.md:15-20]()\n\n### 步骤 5：验证安装\n\n1. 完全退出 Claude Desktop\n2. 重新启动应用程序\n3. 等待初始化完成（首次启动可能需要 30-60 秒）\n4. 询问 Claude：`\"Can you show me the available TradingView tools?\"`\n\n预期应看到以下工具：\n- `top_gainers`\n- `top_losers`\n- `bollinger_scan`\n- `coin_analysis`\n- `consecutive_candles_scan`\n\n## 安装方法二：本地开发环境\n\n适用于需要修改代码或进行二次开发的用户。\n\n### 标准开发流程\n\n```bash\n# 克隆仓库\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n\n# 安装依赖\nuv sync\n\n# 安装开发依赖\nuv sync --dev\n```\n资料来源：[CONTRIBUTING.md:6-12]()\n\n### 测试服务器\n\n```bash\n# 直接运行服务器\nuv run python src/tradingview_mcp/server.py\n\n# 使用 MCP Inspector 测试\nuv run mcp dev src/tradingview_mcp/server.py\n\n# 运行集成测试\nuv run python test_api.py\n```\n资料来源：[CONTRIBUTING.md:14-20]()\n\n### Claude Desktop 配置（本地开发）\n\n**Windows：**\n```json\n{\n \"mcpServers\": {\n \"tradingview-mcp-local\": {\n \"command\": \"C:\\\\Users\\\\YourUsername\\\\tradingview-mcp\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\"C:\\\\Users\\\\YourUsername\\\\tradingview-mcp\\\\src\\\\tradingview_mcp\\\\server.py\"],\n \"cwd\": \"C:\\\\Users\\\\YourUsername\\\\tradingview-mcp\"\n }\n }\n}\n```\n\n**macOS/Linux：**\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资料来源：[INSTALLATION.md:53-73]()\n\n## 安装方法三：Python 虚拟环境\n\n适用于偏好传统 Python 环境的用户。\n\n### Windows\n\n```powershell\n# 克隆仓库\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n\n# 创建虚拟环境\npython -m venv .venv\n.\\.venv\\Scripts\\activate\n\n# 安装依赖\npip install -e .\n\n# 运行服务器\npython src/tradingview_mcp/server.py\n```\n资料来源：[INSTALLATION.md:91-100]()\n\n### macOS/Linux\n\n```bash\n# 克隆仓库\ngit clone https://github.com/atilaahmettaner/tradingview-mcp.git\ncd tradingview-mcp\n\n# 创建虚拟环境\npython -m venv .venv\nsource .venv/bin/activate\n\n# 安装依赖\npip install -e .\n\n# 运行服务器\npython src/tradingview_mcp/server.py\n```\n\n## Codex 插件安装\n\n该项目包含专门的 Codex 插件元数据配置：\n\n- `.codex-plugin/plugin.json`\n- `.codex-mcp.json`\n\n### Codex 配置\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n资料来源：[README.md:90-99]()\n\n启用插件后需重启 Codex 以加载 MCP 服务器。\n\n## OpenClaw 集成安装\n\nOpenClaw 允许通过 Telegram、WhatsApp、Discord 等 20+ 消息平台连接本服务。\n\n### 工作原理\n\n```mermaid\ngraph LR\n A[Telegram/WhatsApp] --> B[OpenClaw Agent]\n B --> C[AI 模型]\n C --> D[trading.py wrapper]\n D --> E[tradingview-mcp]\n E --> F[Yahoo Finance]\n```\n\n### 安装步骤\n\n```bash\n# 安装 uv\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\n\n# 安装 tradingview-mcp-server\nuv tool install tradingview-mcp-server\n```\n资料来源：[OPENCLAW.md:4-10]()\n\n### Telegram 配置\n\n创建或编辑 `~/.openclaw/openclaw.json`：\n\n```json5\n{\n channels: {\n telegram: {\n botToken: \"YOUR_BOT_TOKEN_HERE\",\n },\n },\n}\n```\n\n### 下载交易工具\n\n```bash\nmkdir -p ~/.agents/skills/tradingview-mcp ~/.openclaw/tools\n\n# 下载 TradingView skill\ncurl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/SKILL.md \\\n -o ~/.agents/skills/tradingview-mcp/SKILL.md\n\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资料来源：[OPENCLAW.md:18-28]()\n\n### 启动 OpenClaw\n\n```bash\nopenclaw gateway install\nsystemctl --user start openclaw-gateway.service\nopenclaw doctor\n```\n\n## 平台特定说明\n\n### Windows 注意事项\n\n| 问题 | 解决方案 |\n|------|----------|\n| 直接 Python 路径更可靠 | 使用 `.venv\\Scripts\\python.exe` 而非 `uvx` |\n| 首次启动超时 | 检查 `%APPDATA%\\Claude\\logs` 中的详细日志 |\n| 路径分隔符 | 使用反斜杠 `\\` 或双斜杠 `\\\\` |\n\n**Windows 用户请注意：** 将 `YourUsername` 替换为实际的 Windows 用户名，并根据实际情况调整路径。\n\n### macOS 注意事项\n\n使用 uvx 时需指定完整路径：\n\n```json\n{\n \"mcpServers\": {\n \"tradingview\": {\n \"command\": \"/Users/YOUR_USERNAME/.local/bin/uvx\",\n \"args\": [\"--from\", \"tradingview-mcp-server\", \"tradingview-mcp\"]\n }\n }\n}\n```\n资料来源：[README.md:66-72]()\n\n### Linux 注意事项\n\n路径格式为 `/home/YOUR_USERNAME`：\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## 故障排除\n\n### Windows 首次启动超时错误\n\n**症状：** 在 Claude Desktop 日志中看到 `MCP error -32001: Request timed out`\n\n**解决方案：**\n1. 使用直接 Python 路径替代 uvx\n2. 首次启动等待 30-60 秒\n3. 检查防火墙和网络设置\n\n### uvx 找不到\n\n**Windows：** 使用 `%USERPROFILE%\\.local\\bin\\uvx.exe`\n\n**macOS：** 使用 `/Users/YOUR_USERNAME/.local/bin/uvx`\n\n**Linux：** 使用 `/home/YOUR_USERNAME/.local/bin/uvx`\n\n### 预热缓存（可选优化）\n\n在启动 Claude Desktop 前预先安装可加快首次响应速度：\n\n```bash\nuv tool install --python 3.13 tradingview-mcp-server\n```\n资料来源：[README.md:56-62]()\n\n## 验证清单\n\n| 检查项 | 预期结果 |\n|--------|----------|\n| 服务启动 | 无错误日志 |\n| MCP 连接 | Claude Desktop 显示连接成功 |\n| 工具列表 | 返回 20+ TradingView 工具 |\n| 数据获取 | 成功获取实时价格或分析数据 |\n\n## 开发环境测试\n\n```bash\n# 运行测试套件\nuv run pytest\n\n# 运行代码检查\nuv run ruff check\n\n# 运行类型检查\nuv run mypy src/\n```\n资料来源：[CONTRIBUTING.md:14-16]()\n\n## 目录结构\n\n```\ntradingview-mcp/\n├── src/tradingview_mcp/\n│ ├── server.py # 主 MCP 服务器\n│ ├── core/ # 核心业务逻辑\n│ │ ├── services/ # 市场数据服务\n│ │ ├── utils/ # 工具函数\n│ │ └── indicators/ # 技术指标\n│ └── coinlist/ # 交易所符号列表\n├── tests/ # 测试文件\n├── openclaw/ # OpenClaw 集成\n├── .codex-plugin/ # Codex 插件元数据\n└── pyproject.toml # 项目配置\n```\n资料来源：[CONTRIBUTING.md:26-34]()\n\n## 后续步骤\n\n安装完成后，可尝试以下操作：\n\n1. **获取市场快照：** 询问 `\"Give me a full market snapshot right now\"`\n2. **技术分析：** 使用 `get_technical_analysis` 分析具体股票或加密货币\n3. **回测策略：** 使用 `backtest_strategy` 测试交易策略表现\n4. **市场筛选：** 使用 `top_gainers` 或 `screen_stocks` 筛选标的\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心组件](#page-core-components), [回测引擎](#page-backtesting-engine)\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- [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/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\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- [INSTALLATION.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/INSTALLATION.md)\n \n\n# 系统架构\n\n## 概述\n\ntradingview-mcp 是一个基于 Model Context Protocol (MCP) 的服务器项目，旨在为 AI 助手提供 TradingView 金融市场的数据访问能力。该项目通过 MCP 协议将 TradingView 的技术分析、市场筛选、价格查询等功能封装为可调用的工具，使 AI 代理能够获取实时市场数据并进行技术分析决策。\n\n项目采用模块化架构设计，核心业务逻辑集中在 `src/tradingview_mcp/core/` 目录下，分为服务层（services）、工具层（utils）和指标层（indicators）。资料来源：[CONTRIBUTING.md]()\n\n## 架构分层\n\n系统采用经典的三层架构模式，各层职责明确、边界清晰：\n\n```mermaid\ngraph TD\n A[MCP 客户端
Claude Desktop / Codex] --> B[MCP 服务器层
server.py]\n B --> C[业务逻辑层
core/services]\n B --> D[工具层
core/utils]\n C --> E[数据源
tradingview_ta
Yahoo Finance]\n C --> F[指标计算层
core/indicators]\n```\n\n### MCP 服务器层\n\nMCP 服务器层是整个系统的入口点，负责处理 MCP 协议通信并将客户端请求路由到相应的业务逻辑。\n\n**核心职责：**\n- 初始化 MCP 服务器并注册所有工具\n- 处理请求参数验证和错误处理\n- 返回格式化的 JSON 响应\n\n**主要组件：**\n\n| 组件 | 文件路径 | 描述 |\n|------|----------|------|\n| 服务器入口 | `src/tradingview_mcp/server.py` | MCP 服务器主程序 |\n| 工具注册 | server.py | 使用 `@server.list_tool()` 装饰器注册工具 |\n\n资料来源：[src/tradingview_mcp/server.py]()\n\n### 业务逻辑层\n\n业务逻辑层位于 `src/tradingview_mcp/core/services/` 目录下，包含核心的数据处理和业务规则。\n\n**服务模块：**\n\n| 服务名称 | 文件 | 核心功能 |\n|----------|------|----------|\n| ScreenerService | screener_service.py | 市场筛选、技术指标计算、K线形态分析 |\n| ExchangeValidator | validators.py | 交易所名称验证和前缀处理 |\n\n**核心数据结构：**\n\n```python\n# 多时间框架数据结构\nMultiRow(symbol=str, changes=dict, base_indicators=IndicatorMap)\n\n# 指标映射结构\nIndicatorMap(open, close, SMA20, BB_upper, BB_lower, volume)\n```\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py:1-50]()\n\n### 工具层\n\n工具层位于 `src/tradingview_mcp/core/utils/` 目录下，提供数据验证、格式化和辅助功能。\n\n**核心工具：**\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `sanitize_exchange()` | 验证并标准化交易所名称 |\n| `sanitize_timeframe()` | 验证并标准化时间周期 |\n| `is_stock_exchange()` | 判断是否为股票交易所 |\n| `get_tv_exchange_prefix()` | 获取 TradingView 交易所前缀 |\n| `get_market_type()` | 获取市场类型 |\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n## 核心组件设计\n\n### 交易所验证器\n\n交易所验证器是系统的关键组件，负责将用户输入的交易所名称映射到 TradingView 可识别的格式。\n\n**交易所映射表：**\n\n| 用户输入 | 内部存储 | TradingView 前缀 |\n|----------|----------|------------------|\n| NYSEARCA | nysearca | AMEX |\n| PCX | pcx | AMEX |\n| AMEX | amex | AMEX |\n| NYSE | nyse | NYSE |\n| NASDAQ | nasdaq | NASDAQ |\n| TWSE | twse | TWSE |\n| TPEX | tpex | TPEX |\n| KUCOIN | kucoin | KUCOIN |\n| BINANCE | binance | BINANCE |\n\n**关键函数实现：**\n\n```python\ndef get_tv_exchange_prefix(exchange: str) -> str:\n \"\"\"将交易所名称转换为 TradingView 格式前缀\"\"\"\n return _EXCHANGE_TV_PREFIX.get(exchange.strip().lower(), exchange.upper())\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n### 技术指标计算器\n\n技术指标计算器集成在 screener_service.py 中，支持 30+ 技术指标的计算。\n\n**支持的指标类型：**\n\n| 指标类别 | 具体指标 |\n|----------|----------|\n| 趋势指标 | SMA、EMA、MACD、Supertrend、Donchian |\n| 动量指标 | RSI、CCI、ADX |\n| 波动率指标 | Bollinger Bands、ATR、Standard Deviation |\n| 成交量指标 | OBV、Volume、Volume Profile |\n\n**K线形态识别：**\n\n系统内置 15 种 K 线形态识别模式，通过 `calculate_candle_pattern_score()` 函数进行评分计算。\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py:40-80]()\n\n## 数据流架构\n\n### 请求处理流程\n\n```mermaid\ngraph LR\n A[用户请求] --> B[参数验证
sanitize_exchange]\n B --> C[交易所映射
get_tv_exchange_prefix]\n C --> D[TradingView API
tradingview_ta]\n D --> E[数据解析
IndicatorMap]\n E --> F[指标计算
technical_analysis]\n F --> G[结果格式化
JSON Response]\n```\n\n### 数据源集成\n\n系统支持多个数据源，以满足不同市场的数据需求：\n\n| 数据源 | 用途 | 数据类型 |\n|--------|------|----------|\n| TradingView (tradingview_ta) | 技术分析、K线数据 | 30+ 指标、价格数据 |\n| Yahoo Finance | 实时价格、市场快照 | 实时报价、52 周高低 |\n\n资料来源：[README.md]()\n\n## 工具生态\n\n### MCP 工具分类\n\n| 类别 | 工具数量 | 代表工具 |\n|------|----------|----------|\n| 市场数据 | 5+ | `yahoo_price`, `market_snapshot`, `get_prices_bulk` |\n| 技术分析 | 7+ | `get_technical_analysis`, `get_bollinger_band_analysis` |\n| 市场筛选 | 4+ | `top_gainers`, `top_losers`, `screen_stocks` |\n| 形态识别 | 2+ | `get_candlestick_patterns`, `scan_by_signal` |\n| 回测系统 | 6+ | `backtest_strategy`, `compare_strategies` |\n\n资料来源：[README.md]()\n\n### 交易所支持矩阵\n\n| 交易所 | 代码 | 支持功能 |\n|--------|------|----------|\n| Binance | BINANCE | 加密货币全品种 |\n| KuCoin | KUCOIN | 加密货币筛选 |\n| Bybit | BYBIT | 加密货币筛选 |\n| MEXC | MEXC | 加密货币筛选 |\n| NASDAQ | NASDAQ | 美国股票 |\n| NYSE | NYSE | 美国股票 |\n| NYSE ARCA | NYSEARCA | ETF、黄金、白银 |\n| AMEX | AMEX | 美国股票 |\n| TWSE | TWSE | 台湾股票 |\n| TPEX | TPEX | 台湾兴柜 |\n| EGX | EGX | 埃及股票 |\n| BIST | BIST | 土耳其股票 |\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n## 项目结构\n\n```\ntradingview-mcp/\n├── src/tradingview_mcp/\n│ ├── __init__.py # 包初始化\n│ ├── server.py # MCP 服务器入口\n│ ├── core/\n│ │ ├── services/ # 业务服务层\n│ │ │ └── screener_service.py\n│ │ ├── utils/ # 工具函数\n│ │ │ └── validators.py\n│ │ └── indicators/ # 技术指标\n│ ├── coinlist/ # 交易所符号列表\n│ └── ... # 其他模块\n├── tests/\n│ └── unit/ # 单元测试\n├── assets/\n│ └── architecture.png # 架构图\n└── pyproject.toml # 项目配置\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 安装与部署架构\n\n### 部署模式\n\n系统支持多种部署方式，以适应不同的使用场景：\n\n| 部署方式 | 适用场景 | 配置复杂度 |\n|----------|----------|------------|\n| PyPI 安装 | 生产环境快速部署 | 低 |\n| 源码开发 | 需要修改代码 | 中 |\n| OpenClaw 集成 | Telegram/WhatsApp 接入 | 中 |\n| Claude Desktop | 个人使用 | 低 |\n\n### Claude Desktop 配置\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资料来源：[INSTALLATION.md]()\n\n## 扩展机制\n\n### 添加新交易所\n\n1. 在 `validators.py` 的 `EXCHANGE_SCREENER` 中添加交易所代码\n2. 在 `_EXCHANGE_TV_PREFIX` 中添加前缀映射\n3. 如需符号列表，在 `coinlist/` 目录添加对应文件\n\n### 添加新指标\n\n1. 在 `core/indicators/` 目录创建指标计算函数\n2. 在 `screener_service.py` 中集成新指标\n3. 更新工具返回值结构\n\n资料来源：[CONTRIBUTING.md]()\n\n## 测试架构\n\n系统采用多层次测试策略确保代码质量：\n\n| 测试类型 | 覆盖范围 | 测试工具 |\n|----------|----------|----------|\n| 单元测试 | 独立函数、工具函数 | pytest |\n| 集成测试 | API 调用、数据流 | pytest + 实际 API |\n| Linting | 代码风格 | ruff |\n| 类型检查 | 类型注解 | mypy |\n\n**测试命令：**\n\n```bash\nuv run pytest # 运行测试套件\nuv run ruff check # 代码风格检查\nuv run mypy src/ # 类型检查\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 安全考量\n\n### 敏感数据处理\n\n- API 密钥不存储在代码仓库中\n- 通过环境变量或配置文件注入\n- Claude Desktop 配置中的凭证需妥善保管\n\n### 输入验证\n\n所有用户输入均通过验证器进行清理：\n\n```python\nexchange = sanitize_exchange(user_input) # 防止注入攻击\ntimeframe = sanitize_timeframe(user_input) # 防止恶意时间周期\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n## 版本管理\n\n项目遵循语义化版本控制 (Semantic Versioning)：\n\n| 版本类型 | 触发条件 |\n|----------|----------|\n| Major (X.0.0) | 破坏性 API 变更 |\n| Minor (0.X.0) | 新增功能，向后兼容 |\n| Patch (0.0.X) | Bug 修复，向后兼容 |\n\n资料来源：[CONTRIBUTING.md]()\n\n## 相关资源\n\n- 官方文档：[GitHub Repository](https://github.com/atilaahmettaner/tradingview-mcp)\n- 问题反馈：[Issue Tracker](https://github.com/atilaahmettaner/tradingview-mcp/issues)\n- 赞助项目：[GitHub Sponsors](https://github.com/sponsors/atilaahmettaner)\n\n---\n\n\n\n## 核心组件\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [技术分析服务](#page-technical-analysis)\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- [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/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\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- [PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n \n\n# 核心组件\n\n## 概述\n\n`tradingview-mcp` 是一个基于 Model Context Protocol (MCP) 的交易分析工具，通过 MCP 协议与 Claude Desktop、Codex 等 AI 助手集成，为用户提供实时市场数据、技术分析和交易策略回测功能。\n\n核心组件架构遵循模块化设计原则，将业务逻辑、数据服务、工具函数分离，便于维护和扩展。\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n## 系统架构\n\n```mermaid\ngraph TD\n A[MCP Client
Claude Desktop/Codex] --> B[MCP Server
server.py]\n B --> C[核心业务逻辑层]\n C --> D[Services
数据服务层]\n C --> E[Indicators
指标计算层]\n C --> F[Utils
工具函数层]\n D --> G[TradingView API]\n D --> H[Yahoo Finance API]\n D --> I[Reddit/News RSS]\n```\n\n### 目录结构\n\n```\nsrc/tradingview_mcp/\n├── server.py # MCP 主服务器入口\n├── core/ # 核心业务逻辑\n│ ├── services/ # 市场数据服务\n│ │ ├── screener_service.py # 筛选器服务\n│ │ └── egx_service.py # 埃及交易所服务\n│ ├── utils/ # 工具函数\n│ │ └── validators.py # 验证器\n│ └── indicators/ # 技术指标\n├── coinlist/ # 交易所符号列表\n└── __init__.py\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n## MCP 服务器 (server.py)\n\n`server.py` 是整个项目的入口点，负责：\n\n1. **注册 MCP 工具** - 将所有分析功能暴露为 AI 可调用的工具\n2. **处理请求路由** - 将客户端请求分发到对应的服务层\n3. **返回格式化结果** - 将数据分析结果转换为可读格式\n\n### 主要工具类别\n\n| 类别 | 工具数量 | 功能描述 |\n|------|---------|---------|\n| 市场数据 | 5+ | 实时价格、行情快照、多交易所支持 |\n| 技术分析 | 7+ | RSI、MACD、布林带等30+指标 |\n| 筛选器 | 6+ | 按涨跌幅、信号类型筛选标的 |\n| 回测引擎 | 2 | 6种策略回测与对比 |\n| 情绪分析 | 2 | Reddit情绪、新闻摘要 |\n\n资料来源：[README.md:1-50](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n## 验证器模块 (validators.py)\n\n`validators.py` 负责交易所标识符的规范化处理，是多交易所支持的核心基础设施。\n\n### 核心功能\n\n#### 1. 交易所名称规范化\n\n```python\nsanitize_exchange(exchange: str) -> str\n```\n\n将用户输入的交易所别名转换为标准名称：\n\n| 输入别名 | 输出标准名 | 用途 |\n|---------|-----------|------|\n| `AMEX` | `AMEX` | 美国股票 |\n| `NYSEARCA` | `AMEX` | AMEX 交易所 |\n| `PCX` | `AMEX` | Polygon 分类 |\n| `NYSE` | `NYSE` | 纽约证券交易所 |\n| `NASDAQ` | `NASDAQ` | 纳斯达克 |\n| `KUCOIN` | `KUCOIN` | KuCoin 交易所 |\n\n#### 2. TradingView 前缀映射\n\n```python\nget_tv_exchange_prefix(exchange: str, symbol: str) -> str\n```\n\n为符号生成正确的 TradingView 交易所前缀格式：\n\n- 股票符号：`AMEX:GDX` → `AMEX:GDX`\n- 加密货币：`KUCOIN:SOLUSDT` → `KUCOIN:SOLUSDT`\n\n#### 3. 支持的交易所配置\n\n```python\nSTOCK_EXCHANGES = {\"NYSE\", \"NASDAQ\", \"AMEX\", \"TWSE\", \"TPEX\"}\nEXCHANGE_SCREENER = {\n \"NYSE\": \"NYSE\",\n \"NASDAQ\": \"NASDAQ\", \n \"AMEX\": \"AMEX\",\n \"KUCOIN\": \"Crypto\",\n \"BINANCE\": \"Crypto\",\n \"TWSE\": \"Taiwan\",\n \"TPEX\": \"Taiwan\"\n}\n```\n\n资料来源：[PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n\n## 筛选器服务 (screener_service.py)\n\n`screener_service.py` 实现市场数据筛选和技术分析功能。\n\n### 核心数据结构\n\n```python\nclass IndicatorMap:\n \"\"\"技术指标数据映射\"\"\"\n open: float\n close: float\n SMA20: float\n BB_upper: float\n BB_lower: float\n volume: float\n\nclass MultiRow:\n \"\"\"多周期行数据\"\"\"\n symbol: str\n changes: dict # 各周期涨跌幅\n base_indicators: IndicatorMap\n```\n\n### 主要分析函数\n\n#### 1. 蜡烛图形态评分\n\n```python\ndef calculate_candle_pattern_score(\n indicators: dict,\n pattern_length: int,\n min_increase: float,\n) -> dict\n```\n\n评估蜡烛图形态强度，考虑因素：\n\n- **实体比例** - 开盘价与收盘价的差异\n- **动量** - 价格变化幅度\n- **成交量** - 交易量确认\n- **RSI** - 相对强弱指标\n\n返回结构：\n```python\n{\n \"detected\": bool, # 是否检测到形态\n \"score\": int, # 形态强度评分\n \"details\": list, # 详细分析\n \"rsi\": float # RSI 值\n}\n```\n\n#### 2. 多周期分析\n\n支持的时间周期：\n\n| 周期代码 | 描述 |\n|---------|------|\n| `1m` | 1分钟 |\n| `5m` | 5分钟 |\n| `15m` | 15分钟 |\n| `1h` | 1小时 |\n| `4h` | 4小时 |\n| `1D` | 日线 |\n| `1W` | 周线 |\n\n资料来源：[screener_service.py:1-80](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_service.py)\n\n## 埃及交易所服务 (egx_service.py)\n\n`egx_service.py` 专门处理埃及证券交易所 (EGX) 的数据和分析需求。\n\n### 主要功能\n\n#### 1. EGX 股票筛选器\n\n基于动量和质量评分的股票筛选：\n\n| 评分维度 | 阈值 | 说明 |\n|---------|------|------|\n| 动量评分 (ss) | ≥70 | 价格动能强度 |\n| 质量评分 (tq) | ≥65 | 财务质量指标 |\n| 相对强度 (rr2) | ≥2.0 | 行业相对表现 |\n\n#### 2. 推荐等级\n\n| 推荐等级 | 条件 | 含义 |\n|---------|------|------|\n| `QUALIFIED` | ss≥70 AND tq≥65 AND rr2≥2.0 | 强烈推荐 |\n| `CONDITIONAL` | ss≥70 AND tq≥50 | 有条件推荐 |\n| `WATCHLIST` | ss≥55 | 关注观察 |\n| `AVOID` | 其他 | 不建议 |\n\n#### 3. 斐波那契回撤分析\n\n```python\ndef analyze_egx_fibonacci(\n symbol: str,\n lookback: str = \"52W\",\n timeframe: str = \"1D\",\n) -> dict\n```\n\n支持回溯周期：\n\n- `1M` - 1个月\n- `3M` - 3个月\n- `6M` - 6个月\n- `52W` - 52周（默认）\n- `ALL` - 全时段\n\n资料来源：[egx_service.py:1-100](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)\n\n## 命名规范\n\n项目遵循统一的命名约定，确保代码可读性：\n\n| 类型 | 规范 | 示例 |\n|-----|------|------|\n| 函数 | `snake_case` | `get_top_gainers` |\n| 类 | `PascalCase` | `MarketAnalyzer` |\n| 常量 | `UPPER_SNAKE_CASE` | `DEFAULT_LIMIT` |\n| 文件 | `snake_case.py` | `market_utils.py` |\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n## 工具注册与调用流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant MCP as MCP Server\n participant Service as Service Layer\n participant API as External API\n \n User->>MCP: \"分析 BTC-USDT 的技术指标\"\n MCP->>MCP: 路由到 get_technical_analysis\n MCP->>Service: 调用 screener_service\n Service->>API: TradingView Screener API\n API-->>Service: 原始指标数据\n Service-->>MCP: 计算后的分析结果\n MCP-->>User: 格式化响应\n```\n\n## 依赖关系\n\n项目依赖以下核心包：\n\n| 包名 | 用途 | 来源 |\n|-----|------|------|\n| `tradingview_ta` | TradingView 技术分析 | PyPI |\n| `yfinance` | Yahoo Finance 数据 | PyPI |\n| `mcp` | MCP 协议实现 | PyPI |\n| `fastapi` | HTTP 服务框架 | PyPI |\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n## 扩展指南\n\n### 添加新的技术指标\n\n1. 在 `core/indicators/` 目录下创建指标函数\n2. 在 `server.py` 中注册为 MCP 工具\n3. 添加单元测试\n\n### 添加新交易所支持\n\n1. 更新 `validators.py` 中的交易所映射\n2. 在 `EXCHANGE_SCREENER` 添加对应条目\n3. 测试符号构造：`get_tv_exchange_prefix(\"NEW_EX\", \"SYMBOL\")`\n\n资料来源：[CONTRIBUTING.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CONTRIBUTING.md)\n\n---\n\n\n\n## 回测引擎\n\n### 相关页面\n\n相关主题：[技术分析服务](#page-technical-analysis), [核心组件](#page-core-components)\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- [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/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/core/utils/validators.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/utils/validators.py)\n- [CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)\n- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n \n\n# 回测引擎\n\n## 概述\n\n回测引擎（Backtesting Engine）是 tradingview-mcp 项目中负责历史数据验证交易策略的核心模块。该引擎通过加载历史价格数据，模拟策略在实际市场中的表现，帮助交易者和开发者评估策略的有效性、风险特征和潜在收益。\n\n回测引擎的主要职责包括：\n\n- **策略回测**：对单个交易策略进行历史数据回测\n- **多策略比较**：并排运行多个策略并按性能排名\n- **Walk-Forward 分析**：使用样本外数据验证策略稳定性\n- **指标计算**：提供机构级别的评估指标（Sharpe、Calmar、胜率等）\n\n## 架构设计\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ MCP Server │\n│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │\n│ │ backtest_ │ │ compare_ │ │ walk_forward_ │ │\n│ │ strategy │ │ strategies │ │ backtest_strategy │ │\n│ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ │\n└─────────┼─────────────────┼────────────────────┼───────────────┘\n │ │ │\n ▼ ▼ ▼\n┌─────────────────────────────────────────────────────────────────┐\n│ backtest_service.py │\n│ ┌─────────────────────────────────────────────────────────────┐│\n│ │ Strategy Engine ││\n│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ ││\n│ │ │ RSI │ │Bollinger│ │ MACD │ │EMA Cross│ │Super.. │ ││\n│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └────────┘ ││\n│ └─────────────────────────────────────────────────────────────┘│\n│ ┌─────────────────────────────────────────────────────────────┐│\n│ │ Metrics Calculator ││\n│ │ Sharpe | Calmar | Win Rate | Max DD | Profit Factor ││\n│ └─────────────────────────────────────────────────────────────┘│\n└─────────────────────────────────────────────────────────────────┘\n```\n\n## 支持的交易策略\n\n回测引擎内置 **6 种交易策略**，涵盖均值回归、趋势跟踪和突破策略三大类别。\n\n### 策略类型一览\n\n| 策略标识 | 中文名称 | 策略类别 | 核心逻辑 |\n|----------|----------|----------|----------|\n| `rsi` | RSI 策略 | 均值回归 | RSI 超卖买入，超买卖出 |\n| `bollinger` | 布林带策略 | 均值回归 | 价格触及下轨买入，上轨卖出 |\n| `macd` | MACD 策略 | 趋势跟踪 | MACD 金叉买入，死叉卖出 |\n| `ema_cross` | EMA 交叉策略 | 趋势跟踪 | EMA 20/50 黄金交叉买入，死亡交叉卖出 |\n| `supertrend` | Supertrend 策略 | 趋势跟踪 | ATR 计算动态止损，顺势交易 |\n| `donchian` | 唐奇安通道策略 | 突破策略 | 价格突破通道高点买入，跌破低点卖出 |\n\n### 策略详情\n\n#### RSI 均值回归策略\n\n```python\n# 核心逻辑伪代码\nif rsi < 30: # 超卖区域 → 买入信号\n signal = \"BUY\"\nelif rsi > 70: # 超买区域 → 卖出信号\n signal = \"SELL\"\n```\n\n#### 布林带策略\n\n```python\n# 核心逻辑伪代码\nif price < lower_band: # 触及下轨 → 买入信号\n signal = \"BUY\"\nelif price > upper_band: # 触及上轨 → 卖出信号\n signal = \"SELL\"\n```\n\n#### Supertrend 策略（最受欢迎）\n\n```python\n# 核心逻辑伪代码\natr_value = calculate_atr(high, low, close, period=10)\nupper_band = (high + low) / 2 + multiplier * atr_value\nlower_band = (high + low) / 2 - multiplier * atr_value\n\nif close > upper_band: # 上穿通道 → 买入信号\n signal = \"BUY\"\nelif close < lower_band: # 下穿通道 → 卖出信号\n signal = \"SELL\"\n```\n\n资料来源：[README.md](README.md)\n\n## MCP 工具接口\n\n### 1. backtest_strategy — 单策略回测\n\n对单个策略进行完整的回测分析，返回详细的绩效指标和交易记录。\n\n**参数列表**\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| `symbol` | string | 是 | — | 交易标的符号（如 `BTC-USD`、`AAPL`） |\n| `strategy` | string | 是 | — | 策略名称：`rsi`、`bollinger`、`macd`、`ema_cross`、`supertrend`、`donchian` |\n| `period` | string | 否 | `\"1y\"` | 回测周期：`1mo`、`3mo`、`6mo`、`1y`、`2y` |\n| `interval` | string | 否 | `\"1d\"` | K线周期：`1h`（小时）、`1d`（日线） |\n| `include_trade_log` | boolean | 否 | `false` | 是否包含完整交易明细 |\n| `include_equity_curve` | boolean | 否 | `false` | 是否包含权益曲线数据 |\n\n**返回值结构**\n\n```json\n{\n \"strategy\": \"supertrend\",\n \"symbol\": \"BTC-USD\",\n \"period\": \"2y\",\n \"interval\": \"1d\",\n \"metrics\": {\n \"total_return\": 31.5,\n \"win_rate\": 62.0,\n \"sharpe_ratio\": 2.1,\n \"calmar_ratio\": 1.8,\n \"max_drawdown\": -12.3,\n \"profit_factor\": 2.4,\n \"expectancy\": 1.25,\n \"total_trades\": 45,\n \"best_trade\": 8.5,\n \"worst_trade\": -3.2,\n \"vs_buy_hold\": 15.2\n },\n \"recent_trades\": [...],\n \"trade_log\": [...],\n \"equity_curve\": [...]\n}\n```\n\n资料来源：[CHANGELOG.md](CHANGELOG.md)\n\n### 2. compare_strategies — 多策略比较\n\n在相同标的上同时运行全部 6 种策略，按性能指标综合排名。\n\n**参数列表**\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| `symbol` | string | 是 | — | 交易标的符号 |\n| `period` | string | 否 | `\"1y\"` | 回测周期 |\n| `interval` | string | 否 | `\"1d\"` | K线周期 |\n\n**返回值示例**\n\n```\n#1 Supertrend: +31.5% | Sharpe: 2.1 | WR: 62%\n#2 Bollinger: +18.3% | Sharpe: 3.4 | WR: 75%\n#3 EMA Cross: +12.1% | Sharpe: 1.9 | WR: 58%\n#4 MACD: +8.7% | Sharpe: 1.5 | WR: 52%\n#5 RSI: +5.2% | Sharpe: 1.2 | WR: 48%\n#6 Donchian: -2.1% | Sharpe: 0.8 | WR: 42%\n\nBuy & Hold: -5.0%\n```\n\n资料来源：[README.md](README.md)\n\n### 3. walk_forward_backtest_strategy — Walk-Forward 分析\n\n将数据分为训练集和测试集，在样本外数据上验证策略的泛化能力。\n\n**参数列表**\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| `symbol` | string | 是 | — | 交易标的符号 |\n| `strategy` | string | 是 | — | 策略名称 |\n| `n_splits` | integer | 否 | 5 | 分割次数（2-10） |\n| `train_ratio` | float | 否 | 0.7 | 训练集比例（0.5-0.9） |\n| `interval` | string | 否 | `\"1d\"` | K线周期 |\n\n**输出内容**\n\n- **样本内指标**：训练集上的平均 Sharpe、胜率、最大回撤、总收益\n- **样本外指标**：测试集上的平均表现\n- **稳定性评估**：样本内外指标的差异程度\n\n## 绩效指标说明\n\n### 机构级指标定义\n\n| 指标 | 英文名 | 计算方式 | 理想值 |\n|------|--------|----------|--------|\n| 总收益率 | Total Return | (期末净值 - 期初净值) / 期初净值 × 100% | > 0 |\n| 胜率 | Win Rate | 盈利交易数 / 总交易数 × 100% | > 50% |\n| Sharpe 比率 | Sharpe Ratio | (策略收益 - 无风险收益) / 策略波动率 | > 1.5 |\n| Calmar 比率 | Calmar Ratio | 年化收益 / 最大回撤 | > 2.0 |\n| 最大回撤 | Max Drawdown | 历史最高点到最低点的最大跌幅 | < 20% |\n| 利润因子 | Profit Factor | 总盈利 / 总亏损 | > 1.5 |\n| 期望值 | Expectancy | (胜率 × 平均盈利) - (败率 × 平均亏损) | > 0 |\n\n### Sharpe 比率年化因子\n\n引擎会根据不同的时间周期自动调整 Sharpe 比率的年化计算：\n\n| 周期 | 年化因子 |\n|------|----------|\n| 日线 (`1d`) | 252（交易日） |\n| 小时线 (`1h`) | 252 × 6（每日交易小时） |\n\n```python\n# Sharpe 计算逻辑示例\nif interval == \"1h\":\n annualization_factor = 252 * 6 # 修正小时线年化\nelse:\n annualization_factor = 252\n```\n\n资料来源：[CHANGELOG.md](CHANGELOG.md)\n\n## 交易记录与权益曲线\n\n### 交易明细（Trade Log）\n\n启用 `include_trade_log=True` 后，返回完整的每笔交易记录：\n\n```json\n{\n \"trade_log\": [\n {\n \"entry_date\": \"2024-01-15\",\n \"exit_date\": \"2024-01-28\",\n \"entry_price\": 41250.00,\n \"exit_price\": 43580.00,\n \"holding_days\": 13,\n \"gross_return\": 5.65,\n \"net_return\": 5.42,\n \"commission_cost\": 0.23,\n \"running_capital\": 10542.00,\n \"cumulative_return\": 5.42\n }\n ]\n}\n```\n\n### 权益曲线（Equity Curve）\n\n启用 `include_equity_curve=True` 后，返回每个交易退出时点的权益变化：\n\n```json\n{\n \"equity_curve\": [\n {\n \"date\": \"2024-01-28\",\n \"capital_value\": 10542.00,\n \"drawdown_pct\": -2.1\n },\n {\n \"date\": \"2024-02-15\",\n \"capital_value\": 11280.00,\n \"drawdown_pct\": 0\n }\n ]\n}\n```\n\n### 快速预览机制\n\n即使未启用完整交易日志，引擎始终返回最近 **5 笔交易**（`recent_trades`）供快速检查：\n\n```json\n{\n \"recent_trades\": [\n {\"symbol\": \"BTC-USD\", \"entry\": 42100, \"exit\": 43500, \"pnl\": 3.3},\n {\"symbol\": \"BTC-USD\", \"entry\": 43500, \"exit\": 42800, \"pnl\": -1.6},\n {\"symbol\": \"BTC-USD\", \"entry\": 42800, \"exit\": 44200, \"pnl\": 3.3}\n ]\n}\n```\n\n资料来源：[CHANGELOG.md](CHANGELOG.md)\n\n## 使用示例\n\n### 基础回测\n\n```python\n# 回测 BTC 的 Supertrend 策略\nresult = backtest_strategy(\n symbol=\"BTC-USD\",\n strategy=\"supertrend\",\n period=\"1y\",\n interval=\"1d\"\n)\n```\n\n### 完整交易分析\n\n```python\n# 包含交易明细和权益曲线\nresult = backtest_strategy(\n symbol=\"AAPL\",\n strategy=\"bollinger\",\n period=\"2y\",\n interval=\"1d\",\n include_trade_log=True,\n include_equity_curve=True\n)\n```\n\n### 策略比较\n\n```python\n# 比较所有策略\nresult = compare_strategies(\n symbol=\"ETH-USD\",\n period=\"1y\"\n)\n```\n\n### Walk-Forward 验证\n\n```python\n# 使用 5 折交叉验证\nresult = walk_forward_backtest_strategy(\n symbol=\"BTC-USD\",\n strategy=\"rsi\",\n n_splits=5,\n train_ratio=0.7,\n interval=\"1d\"\n)\n```\n\n## 与多代理系统的集成\n\n回测引擎可与 `multi_agent_service.py` 中的技术分析代理协同工作：\n\n```mermaid\ngraph LR\n A[用户请求] --> B{分析类型}\n B -->|技术分析| C[Technical Analyst]\n B -->|回测请求| D[Backtest Engine]\n B -->|综合决策| E[Multi-Agent Hub]\n \n C --> F[技术指标]\n D --> G[绩效指标]\n \n E --> H[情绪分析]\n E --> I[风险评估]\n \n F --> J[综合评分]\n G --> J\n H --> J\n I --> J\n \n J --> K[最终建议]\n```\n\n多代理系统包含三个专业代理：\n\n| 代理 | 职责 | 输出 |\n|------|------|------|\n| 技术分析师 | 布林带(±3评级)、RSI、MACD | 技术信号 |\n| 情绪分析师 | Reddit 社区情绪、价格动量 | 情绪评分 |\n| 风险管理器 | 波动性、回撤风险、均值回归信号 | 风险评估 |\n\n**最终输出**：`STRONG BUY` / `BUY` / `HOLD` / `SELL` / `STRONG SELL` 附置信度评分\n\n资料来源：[server.py](src/tradingview_mcp/server.py)、[README.md](README.md)\n\n## 模拟参数说明\n\n### 佣金与滑点\n\n回测引擎包含**现实的佣金和滑点模拟**：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| 佣金率 | 0.1% | 每笔交易的手续费 |\n| 滑点 | 模拟 | 订单执行时的价格偏差 |\n\n### 初始资金\n\n默认使用模拟资金进行计算，盈亏以百分比形式呈现，便于不同规模账户的对比。\n\n## 注意事项与限制\n\n### ⚠️ 重要声明\n\n> **⚠️ 过去表现不保证未来结果**\n>\n> 所有回测结果仅供历史参考，实际交易中可能出现与回测显著不同的结果。市场条件、流动性、执行质量等因素均会影响策略表现。\n\n### 技术限制\n\n1. **数据延迟**：依赖历史数据，非实时价格\n2. **流动性假设**：未考虑大额订单对市场的影响\n3. **执行假设**：按收盘价成交，实际可能存在滑点\n4. **过拟合风险**：过度优化可能导致样本内表现优异、样本外失效\n\n### Walk-Forward 分析的价值\n\n为降低过拟合风险，建议：\n\n- 使用 Walk-Forward 分析验证策略稳定性\n- 样本外 Sharpe 比率应接近样本内水平\n- 避免过度追求单一指标的最优值\n\n## 文件结构\n\n```\nsrc/tradingview_mcp/\n├── server.py # MCP 工具入口\n└── core/services/\n ├── backtest_service.py # 回测引擎核心实现\n └── multi_agent_service.py # 多代理分析服务\n```\n\n资料来源：[server.py](src/tradingview_mcp/server.py)\n\n## 版本历史\n\n| 版本 | 发布日期 | 主要更新 |\n|------|----------|----------|\n| 0.7.0 | 2026-04 | Walk-Forward 分析、交易明细、权益曲线 |\n| 0.6.0 | 2026-03-29 | Backtesting Engine v2、6 种策略、机构级指标 |\n\n资料来源：[CHANGELOG.md](CHANGELOG.md)\n\n---\n\n\n\n## 技术分析服务\n\n### 相关页面\n\n相关主题：[回测引擎](#page-backtesting-engine), [数据源与货币列表](#page-data-sources)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\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- [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/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/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.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# 技术分析服务\n\n## 概述\n\n技术分析服务是 `tradingview-mcp` 项目的核心模块，负责从 TradingView 获取市场数据并计算各种技术指标。该服务集成了 30+ 技术指标，包括 RSI、MACD、布林带等主流分析工具，为 AI 交易代理提供实时市场分析能力。\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph \"技术分析服务架构\"\n A[server.py
MCP接口层] --> B[技术分析服务层]\n B --> C[screener_service.py
筛选服务]\n B --> D[scanner_service.py
扫描服务]\n B --> E[indicators.py
指标定义]\n B --> F[indicators_calc.py
指标计算]\n B --> G[egx_service.py
埃及交易所服务]\n \n C --> H[tradingview_ta
数据源]\n D --> H\n F --> H\n end\n \n subgraph \"输出层\"\n B --> I[技术分析结果]\n B --> J[筛选/扫描结果]\n B --> K[斐波那契分析]\n end\n```\n\n## 核心服务组件\n\n### 1. 筛选服务 (screener_service.py)\n\n筛选服务负责从 TradingView 获取市场筛选数据，支持多交易所、多时间周期的市场扫描。\n\n#### 关键数据结构\n\n| 数据结构 | 用途 | 主要字段 |\n|---------|------|---------|\n| `MultiRow` | 单个标的的多时间周期数据 | symbol, changes, base_indicators |\n| `IndicatorMap` | 技术指标映射 | open, close, SMA20, BB_upper, BB_lower, volume |\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py:1-30]()\n\n#### 烛台模式分析\n\n`screener_service.py` 中的 `calculate_candle_pattern_score` 函数提供了烛台形态评分功能：\n\n```python\ndef calculate_candle_pattern_score(\n indicators: dict,\n pattern_length: int,\n min_increase: float,\n) -> dict\n```\n\n**功能说明：**\n- 根据价格形态、身体比率、动量、成交量和 RSI 进行综合评分\n- 返回检测结果、得分、明细列表及计算字段\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| indicators | dict | 来自 tradingview_ta 的原始指标数据 |\n| pattern_length | int | 分析的连续周期数 |\n| min_increase | float | 最小价格变化百分比阈值 |\n\n**返回值结构：**\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| detected | bool | 是否检测到有效形态 |\n| score | int | 形态强度评分 |\n| details | list | 详细分析结果 |\n| 计算字段 | float | open_price, close_price, high_price, low_price, volume, rsi |\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py:56-85]()\n\n### 2. 扫描服务 (scanner_service.py)\n\n扫描服务提供市场扫描功能，支持按信号类型、连续烛台、技术指标等维度进行市场筛选。\n\n```mermaid\ngraph LR\n A[扫描请求] --> B[信号类型过滤]\n B --> C[连续烛台检测]\n C --> D[技术指标筛选]\n D --> E[扫描结果输出]\n```\n\n**支持的扫描类型：**\n\n| 扫描类型 | 说明 | 应用场景 |\n|---------|------|---------|\n| `oversold` | 超卖信号扫描 | RSI < 30 的标的 |\n| `overbought` | 超买信号扫描 | RSI > 70 的标的 |\n| `bullish` | 看涨形态扫描 | 连续阳线、突破形态 |\n| `bearish` | 看跌形态扫描 | 连续阴线、跌破形态 |\n| `breakout` | 突破扫描 | 突破布林带上轨/阻力位 |\n\n### 3. 指标计算服务 (indicators_calc.py)\n\n指标计算服务封装了所有技术指标的计算逻辑，提供标准化的事件分析接口。\n\n#### 支持的指标类型\n\n| 指标类别 | 包含指标 | 用途 |\n|---------|---------|------|\n| 趋势类 | SMA, EMA, MACD, Supertrend | 判断市场趋势方向 |\n| 振荡类 | RSI, Stochastic, CCI, Williams %R | 判断超买超卖 |\n| 波动类 | Bollinger Bands, ATR, Donchian | 衡量价格波动幅度 |\n| 成交量类 | OBV, Volume SMA | 分析成交量与价格关系 |\n| 形态类 | 15种烛台形态识别 | 价格反转信号 |\n\n### 4. 埃及交易所专用服务 (egx_service.py)\n\nEGX 服务为埃及证券交易所提供专业分析工具，包括斐波那契回撤分析和股票评分系统。\n\n#### 斐波那契回撤分析\n\n```python\ndef analyze_egx_fibonacci(\n symbol: str,\n lookback: str = \"52W\",\n timeframe: str = \"1D\",\n) -> dict\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| symbol | str | 必需 | EGX 股票代码（如 'COMI'） |\n| lookback | str | \"52W\" | 回溯周期：'1M', '3M', '6M', '52W', 'ALL' |\n| timeframe | str | \"1D\" | TradingView 时间周期 |\n\n**返回字段：**\n\n| 字段 | 说明 |\n|-----|------|\n| fib_levels | 斐波那契回撤/扩展价位 |\n| price_position | 当前价格在回撤中的位置 |\n| swing_high/low | 周期内最高/最低价 |\n| context | 市场背景分析 |\n\n资料来源：[src/tradingview_mcp/core/services/egx_service.py:100-150]()\n\n#### 股票评分系统\n\nEGX 服务包含多维度股票评分引擎：\n\n```mermaid\ngraph TD\n A[股票评分输入] --> B[技术强度 SS]\n A --> C[交易质量 TQ]\n A --> D[趋势确认 RR2]\n \n B --> E{评分规则引擎}\n C --> E\n D --> E\n \n E --> F{综合判断}\n F -->|SS>=70, TQ>=65, RR2>=2.0| G[QUALIFIED
强信号]\n F -->|SS>=70, TQ>=50| H[CONDITIONAL
条件信号]\n F -->|SS>=55| I[WATCHLIST
观察名单]\n F -->|SS<55| J[AVOID
回避]\n```\n\n**评分维度：**\n\n| 维度 | 缩写 | 阈值 | 说明 |\n|-----|------|-----|------|\n| 技术强度 | SS | 0-100 | 技术指标综合得分 |\n| 交易质量 | TQ | 0-100 | 价格结构与成交量质量 |\n| 趋势确认 | RR2 | >2.0 | 风险回报比确认 |\n\n**推荐等级：**\n\n| 推荐等级 | 触发条件 | 含义 |\n|---------|---------|------|\n| QUALIFIED | SS≥70, TQ≥65, RR2≥2.0 | 强信号，操作性强的标的 |\n| CONDITIONAL | SS≥70, TQ≥50 | 好标的但需改进设置 |\n| WATCHLIST | SS≥55 | 需监控等待更好入场点 |\n| AVOID | SS<55 | 不满足动量/质量标准 |\n\n资料来源：[src/tradingview_mcp/core/services/egx_service.py:1-100]()\n\n## 多交易所支持\n\n技术分析服务支持多个交易所的行情数据获取：\n\n```mermaid\ngraph TD\n A[分析请求] --> B{交易所识别}\n \n B -->|加密货币| C[BINANCE/KUCOIN/BYBIT]\n B -->|美国股票| D[NYSE/NASDAQ/AMEX]\n B -->|埃及股票| E[EGX]\n B -->|台湾股票| F[TWSE/TPEX]\n B -->|土耳其股票| G[BIST]\n \n C --> H[统一数据格式]\n D --> H\n E --> H\n F --> H\n G --> H\n```\n\n**支持的交易所映射：**\n\n| 市场类型 | 交易所代码 | 说明 |\n|---------|-----------|------|\n| 加密货币 | BINANCE, KUCOIN, BYBIT, MEXC | 数字资产交易 |\n| 美国股票 | NYSE, NASDAQ, AMEX, NYSEARCA | 美股市场 |\n| 台湾股票 | TWSE, TPEX | 台湾证券交易所 |\n| 埃及股票 | EGX | 埃及证券交易所 |\n| 土耳其股票 | BIST | 伊斯坦布尔证券交易所 |\n\n## 数据流向\n\n```mermaid\nsequenceDiagram\n participant U as 用户请求\n participant S as Server层\n participant SC as Screener服务\n participant TV as TradingView API\n participant IC as 指标计算\n participant R as 结果返回\n \n U->>S: 调用分析工具\n S->>SC: 请求市场数据\n SC->>TV: 获取原始数据\n TV-->>SC: 原始OHLCV数据\n SC->>IC: 计算技术指标\n IC-->>SC: 指标结果\n SC-->>S: 格式化结果\n S-->>U: 返回分析报告\n```\n\n## 与 MCP Server 的集成\n\n技术分析服务通过 `server.py` 暴露为 MCP 工具：\n\n| MCP 工具 | 功能 | 底层服务 |\n|---------|------|---------|\n| `get_technical_analysis` | 完整技术分析 | indicators.py |\n| `get_bollinger_band_analysis` | 布林带专有分析 | indicators_calc.py |\n| `screen_stocks` | 多条件筛选 | screener_service.py |\n| `scan_by_signal` | 信号扫描 | scanner_service.py |\n| `egx_fibonacci_retracement` | 斐波那契分析 | egx_service.py |\n| `get_candlestick_patterns` | 烛台形态检测 | screener_service.py |\n\n## 货币与部门数据\n\nEGX 服务提供股票货币和部门分类：\n\n**货币类型判断：**\n\n| 货币 | 适用股票 | 示例 |\n|-----|---------|------|\n| EGP | 大多数EGX股票 | COMI, ORWE, ETEL |\n| USD | 特定国际股票 | FAITA, VLMR, EGSA |\n\n资料来源：[src/tradingview_mcp/core/data/egx_sectors.py:1-50]()\n\n**部门分类：** 涵盖银行业、保险业、电信业、制造业等 20+ 行业部门。\n\n## 错误处理\n\n| 错误类型 | 返回格式 | 处理方式 |\n|---------|---------|---------|\n| API连接失败 | `{\"error\": \"description\"}` | 记录日志，返回错误信息 |\n| 无效标的 | `{\"error\": \"Invalid symbol\"}` | 验证输入后返回 |\n| 数据缺失 | 字段为0或空 | 使用默认值处理 |\n\n## 扩展指南\n\n### 添加新指标\n\n1. 在 `indicators_calc.py` 中实现计算函数\n2. 注册到指标映射表\n3. 在 `server.py` 中暴露为 MCP 工具\n\n### 添加新交易所\n\n1. 更新 `EXCHANGE_SCREENER` 映射表\n2. 添加交易所符号列表到 `coinlist/` 目录\n3. 测试数据获取和格式化\n\n## 参考链接\n\n- 项目主页：[tradingview-mcp](https://github.com/atilaahmettaner/tradingview-mcp)\n- 技术分析文档：[README.md](README.md)\n- 贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md)\n\n---\n\n\n\n## 情感分析与新闻服务\n\n### 相关页面\n\n相关主题：[技术分析服务](#page-technical-analysis), [数据源与货币列表](#page-data-sources)\n\n\n相关源码文件
\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/news_service.py)\n- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.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/egx_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/egx_service.py)\n \n\n# 情感分析与新闻服务\n\n## 概述\n\n情感分析与新闻服务是 tradingview-mcp 框架的核心模块之一，旨在为交易决策提供多维度的市场情绪和资讯数据支持。该服务通过整合 Reddit 社区情感分析和实时金融新闻（RSS），帮助用户从社交媒体情绪和新闻事件两个维度评估资产走势。\n\n**核心功能定位：**\n\n| 功能模块 | 用途 | 数据来源 |\n|---------|------|---------|\n| 情感分析服务 | 评估市场参与者的社区情绪 | Reddit 社区帖子 |\n| 新闻服务 | 聚合实时财经新闻 | RSS 订阅源 |\n\n资料来源：[server.py:1-50]()\n\n## 架构设计\n\n### 服务组件结构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ MCP Server (server.py) │\n├─────────────────────────────────────────────────────────────┤\n│ ┌─────────────────┐ ┌─────────────────┐ │\n│ │ Sentiment │ │ News │ │\n│ │ Service │ │ Service │ │\n│ └────────┬────────┘ └────────┬────────┘ │\n│ │ │ │\n│ ▼ ▼ │\n│ ┌─────────────────┐ ┌─────────────────┐ │\n│ │ Reddit API │ │ RSS Feeds │ │\n│ │ (情感抓取) │ │ (新闻聚合) │ │\n│ └─────────────────┘ └─────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 情感分析流程\n\n```mermaid\ngraph TD\n A[请求分析: symbol + category] --> B[Reddit 搜索]\n B --> C{找到相关帖子?}\n C -->|是| D[解析帖子内容]\n C -->|否| E[返回空结果]\n D --> F[计算情感得分]\n F --> G[生成情感标签]\n G --> H[输出完整情感报告]\n```\n\n资料来源：[server.py:token-analysis-call]()\n\n## 情感分析服务\n\n### 功能说明\n\n`analyze_sentiment` 函数是情感分析的核心入口，负责从 Reddit 社区抓取与指定标的相关的讨论帖子，并计算情感得分。\n\n**函数签名：**\n\n```python\nanalyze_sentiment(symbol: str, category: str = \"crypto\") -> dict\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| symbol | str | 必填 | 交易标的符号（如 BTC-USD、AAPL） |\n| category | str | \"crypto\" | 标的类别，可选 \"crypto\" 或 \"stocks\" |\n\n资料来源：[server.py:analyze_sentiment-def]()\n\n### 情感分析输出结构\n\n```python\n{\n \"sentiment_score\": float, # 情感得分（-1 到 1）\n \"sentiment_label\": str, # 情感标签（Bullish/Bearish/Neutral）\n \"posts_analyzed\": int, # 分析的帖子数量\n \"mentions\": int, # 提及次数\n \"key_themes\": List[str], # 关键主题\n \"confidence\": str # 置信度（High/Medium/Low）\n}\n```\n\n### 情感标签映射\n\n| 情感得分范围 | 标签 | 含义 |\n|-------------|------|------|\n| > 0.1 | Bullish | 看涨情绪 |\n| -0.1 ~ 0.1 | Neutral | 中性情绪 |\n| < -0.1 | Bearish | 看跌情绪 |\n\n资料来源：[server.py:sentiment_label-conditional]()\n\n## 新闻服务\n\n### 功能说明\n\n`fetch_news_summary` 函数从多个 RSS 订阅源聚合与指定标的相关的最新财经新闻。\n\n**函数签名：**\n\n```python\nfetch_news_summary(symbol: str, category: str = \"crypto\", limit: int = 5) -> dict\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| symbol | str | 必填 | 交易标的符号 |\n| category | str | \"crypto\" | 标的类别 |\n| limit | int | 5 | 返回的新闻条目数量上限 |\n\n资料来源：[server.py:fetch_news_summary-def]()\n\n### 新闻输出结构\n\n```python\n{\n \"count\": int, # 获取的新闻总数\n \"items\": [ # 新闻条目列表\n {\n \"title\": str, # 新闻标题\n \"link\": str, # 新闻链接\n \"pub_date\": str, # 发布日期\n \"source\": str # 新闻来源\n }\n ]\n}\n```\n\n## 情绪共振分析\n\n### 合流决策引擎\n\n`sentiment_news_confluence` 函数将技术分析、情感分析和新闻数据三者结合，生成综合交易建议。\n\n**函数签名：**\n\n```python\nsentiment_news_confluence(symbol: str, exchange: str, timeframe: str = \"1h\") -> dict\n```\n\n**分析流程：**\n\n```mermaid\ngraph TD\n A[输入: symbol + exchange + timeframe] --> B[技术分析]\n A --> C[情感分析]\n A --> D[新闻汇总]\n B --> E{技术信号}\n C --> F{情感得分 > 0.1?}\n E -->|Bullish/Bearish| G[信号对齐检查]\n F -->|True| G\n G --> H{信号一致?}\n H -->|是| I[confidence: HIGH]\n H -->|否| J[confidence: MIXED]\n I --> K[recommendation: 技术信号 confirmed by 情感]\n J --> L[recommendation: 技术信号 conflicts with 情感]\n```\n\n资料来源：[server.py:confluence-analysis]()\n\n### 合流输出字段\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| symbol | str | 交易标的 |\n| exchange | str | 交易所 |\n| timeframe | str | 分析时间周期 |\n| technical | dict | 技术分析完整结果 |\n| sentiment | dict | 情感分析结果 |\n| news | dict | 新闻摘要（数量 + 最新3条） |\n| confluence | dict | 合流分析结果 |\n\n**合流置信度判定：**\n\n| 条件 | 置信度 | 建议格式 |\n|------|--------|---------|\n| 技术信号 == 情感信号 | HIGH | \"Technical {signal} confirmed by {sentiment}\" |\n| 技术信号 != 情感信号 | MIXED | \"Technical {signal} conflicts with {sentiment}\" |\n\n资料来源：[server.py:confidence-calculation]()\n\n## EGX 交易所特殊处理\n\n### 埃及股市情绪分析\n\nEGX（埃及证券交易所）服务提供专门的市场情绪和板块轮动分析功能。\n\n**指数分析函数：**\n\n```python\nanalyze_egx_index(index: str = \"EGX30\", timeframe: str = \"1D\", limit: int = 30) -> dict\n```\n\n**支持的指数：**\n\n| 指数代码 | 名称 | 说明 |\n|---------|------|------|\n| EGX30 | EGX 30 指数 | 埃及主板30强 |\n| EGX70 | EGX 70 指数 | 中盘股指数 |\n| EGX100 | EGX 100 指数 | 综合指数 |\n| SHARIAH33 | 伊斯兰指数 | 符合伊斯兰法规的股票 |\n| EGX35LV | 低波动指数 | 低波动精选股 |\n| TAMAYUZ | Tamayuz 指数 | 主题指数 |\n\n资料来源：[egx_service.py:analyze_egx_index-def]()\n\n### 市场情绪生成\n\n`_generate_rotation_signals` 函数分析板块轮动信号，判断资金流向。\n\n**情绪类型映射：**\n\n```python\nrotation_signals = {\n \"strong_sectors\": List[str], # 强势板块\n \"weak_sectors\": List[str], # 弱势板块\n \"rotation_direction\": str, # 轮动方向\n \"momentum_score\": float # 动量得分\n}\n```\n\n资料来源：[egx_service.py:_generate_rotation_signals]()\n\n### 板块热度图\n\n`generate_sector_heatmap` 函数计算各板块的相对强弱，生成权重分析。\n\n**输出结构：**\n\n```python\n{\n \"exchange\": \"EGX\",\n \"timeframe\": str,\n \"total_sectors\": int,\n \"total_stocks_scanned\": int,\n \"weighted_market_view\": {\n \"weighted_change_pct\": float,\n \"weighted_rsi\": float,\n \"weighted_momentum\": float,\n \"market_sentiment\": str\n },\n \"sector_heatmap\": dict,\n \"sector_top_picks\": dict,\n \"rotation_signals\": dict\n}\n```\n\n资料来源：[egx_service.py:generate_sector_heatmap-return]()\n\n## 使用示例\n\n### 基础情感分析\n\n```python\n# 加密货币情感分析\nresult = analyze_sentiment(symbol=\"BTC-USD\", category=\"crypto\")\n\n# 美股情感分析\nresult = analyze_sentiment(symbol=\"AAPL\", category=\"stocks\")\n```\n\n### 综合新闻获取\n\n```python\n# 获取币安相关最新新闻\nnews = fetch_news_summary(symbol=\"BNB\", category=\"crypto\", limit=10)\n```\n\n### 合流决策分析\n\n```python\n# 完整分析示例\nconfluence = sentiment_news_confluence(\n symbol=\"BTC-USD\",\n exchange=\"BINANCE\",\n timeframe=\"1h\"\n)\n\n# 输出示例\n# {\n# \"confidence\": \"HIGH\",\n# \"signals_agree\": True,\n# \"recommendation\": \"Technical STRONG BUY confirmed by Bullish Reddit sentiment (142 posts analyzed)\"\n# }\n```\n\n资料来源：[server.py:confluence-example]()\n\n## 技术指标与情感关联\n\n### 多指标协同分析\n\n系统支持将情感数据与其他技术指标结合使用：\n\n| 指标类型 | 工具函数 | 用途 |\n|---------|---------|------|\n| 价格数据 | `yahoo_price` | 实时价格 |\n| 技术分析 | `get_technical_analysis` | 30+ 技术指标 |\n| 情感分析 | `analyze_sentiment` | Reddit 情绪 |\n| 新闻汇总 | `fetch_news_summary` | RSS 新闻 |\n| K线形态 | `get_candlestick_patterns` | 15 种形态识别 |\n\n资料来源：[README.md:tools-table]()\n\n### 信号对齐矩阵\n\n```\n 技术分析信号\n BUY SELL HOLD\n情感 ┌─────────────┬─────────────┬─────────────┐\n Bullish │ HIGH ✅ │ MIXED ⚠️ │ MIXED ⚠️ │\n ├─────────────┼─────────────┼─────────────┤\n情感 │ MIXED ⚠️ │ HIGH ✅ │ MIXED ⚠️ │\n Bearish │ │ │ │\n ├─────────────┼─────────────┼─────────────┤\n情感 │ MIXED ⚠️ │ MIXED ⚠️ │ MEDIUM 🔄 │\n Neutral │ │ │ │\n └─────────────┴─────────────┴─────────────┘\n```\n\n## 配置与扩展\n\n### 情感分析数据源配置\n\nReddit 数据源目前使用公开 API 接口，支持的主题分类：\n\n| category | 适用标的 | 搜索范围 |\n|----------|---------|---------|\n| crypto | 加密货币 | r/CryptoCurrency, r/Bitcoin 等 |\n| stocks | 股票 | r/stocks, r/wallstreetbets 等 |\n\n### 新闻服务 RSS 配置\n\n新闻服务支持多源 RSS 订阅，可扩展的订阅源：\n\n| 来源类型 | 内容范围 | 更新频率 |\n|---------|---------|---------|\n| 财经媒体 | 主流财经新闻 | 实时 |\n| 交易所公告 | 官方公告和更新 | 事件驱动 |\n| 社区讨论 | 社交媒体摘要 | 定期聚合 |\n\n## 注意事项\n\n1. **免责声明**：所有情感和新闻分析仅供教育和参考用途，不构成投资建议\n2. **数据延迟**：RSS 新闻源可能存在几分钟到几小时的延迟\n3. **情感局限性**：Reddit 情感分析可能受到炒作和操控影响\n4. **API 限制**：外部 API 调用频率受限于服务提供商的策略\n\n资料来源：[egx_service.py:disclaimer]()\n\n## 相关资源\n\n- [项目主页](../README.md)\n- [安装指南](../INSTALLATION.md)\n- [OpenClaw 集成指南](../OPENCLAW.md)\n- [示例对话](../EXAMPLES.md)\n\n---\n\n\n\n## Yahoo Finance 集成\n\n### 相关页面\n\n相关主题：[数据源与货币列表](#page-data-sources), [技术分析服务](#page-technical-analysis)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\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- [src/tradingview_mcp/core/services/extended_hours_service.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/extended_hours_service.py)\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- [README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n \n\n# Yahoo Finance 集成\n\n## 概述\n\nYahoo Finance 集成是 tradingview-mcp 项目在 **v0.6.0** 版本中新增的核心功能模块，为用户提供实时金融市场数据查询能力。该模块通过封装 Yahoo Finance API，实现了股票、加密货币、ETF、指数、外汇等多资产类别的实时行情获取。\n\n**主要功能包括：**\n\n- `yahoo_price`：获取任意标的的实时报价\n- `market_snapshot`：生成全球市场概览快照\n\n资料来源：[CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)\n\n---\n\n## 架构设计\n\n### 服务层结构\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ server.py │\n│ (MCP 工具入口层) │\n│ ┌─────────────────┐ ┌─────────────────────────────┐ │\n│ │ yahoo_price │ │ market_snapshot │ │\n│ └────────┬────────┘ └──────────────┬──────────────┘ │\n└───────────┼──────────────────────────┼──────────────────┘\n │ │\n ▼ ▼\n┌─────────────────────────────────────────────────────────┐\n│ yahoo_finance_service.py │\n│ (核心服务层) │\n│ ┌─────────────────┐ ┌─────────────────────────────┐ │\n│ │ 实时行情获取 │ │ 市场快照生成 │ │\n│ │ │ │ 14 instruments │ │\n│ │ price_data() │ │ 4 asset classes │ │\n│ └─────────────────┘ └─────────────────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ extended_hours_service.py │\n│ (盘后服务层) │\n│ ┌─────────────────┐ ┌─────────────────────────────┐ │\n│ │ 盘前盘后检测 │ │ 市场状态判定 │ │\n│ │ extended_hours │ │ market_state │ │\n│ └─────────────────┘ └─────────────────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ Yahoo Finance API │\n│ (外部数据源) │\n└─────────────────────────────────────────────────────────┘\n```\n\n### 支持的资产类别\n\n| 资产类别 | 示例标的 | 数据内容 |\n|---------|---------|---------|\n| **股票** | AAPL, TSLA, NVDA | 价格、涨跌幅、52周高低 |\n| **加密货币** | BTC-USD, ETH-USD | 实时报价、24h变化 |\n| **ETF** | SPY, QQQ | 实时行情 |\n| **指数** | S&P500, NASDAQ, VIX | 市场指数点位 |\n| **外汇** | EUR/USD | 汇率报价 |\n| **土耳其股票** | THYAO.IS, SASA.IS | 本地市场报价 |\n\n资料来源：[CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)\n\n---\n\n## 核心服务模块\n\n### yahoo_finance_service.py\n\n`yahoo_finance_service.py` 是 Yahoo Finance 集成的核心服务模块，负责与 Yahoo Finance API 交互并返回结构化的市场数据。\n\n#### 主要功能\n\n| 功能 | 说明 |\n|-----|-----|\n| `get_yahoo_price()` | 获取单个标的的实时行情 |\n| `get_market_snapshot()` | 生成全球市场概览（14个标的） |\n| `get_prices_bulk()` | 批量获取多标的报价 |\n\n#### yahoo_price 工具\n\n`yahoo_price` 是 MCP 工具的核心入口，调用 `yahoo_finance_service.py` 中的函数获取实时数据。\n\n**返回值结构：**\n\n```json\n{\n \"symbol\": \"AAPL\",\n \"price\": 175.30,\n \"change\": 3.62,\n \"change_percent\": 2.11,\n \"52_week_high\": 198.23,\n \"52_week_low\": 124.17,\n \"market_state\": \"REGULAR\"\n}\n```\n\n#### market_snapshot 工具\n\n`market_snapshot` 提供全球市场概览，覆盖 **14 个标的** 和 **4 个资产类别**。\n\n**快照覆盖范围：**\n\n| 资产类别 | 标的数量 | 代表标的 |\n|---------|---------|---------|\n| 股票指数 | 3 | S&P 500, NASDAQ, VIX |\n| 加密货币 | 2 | BTC, ETH |\n| 外汇 | 2 | EUR/USD, GBP/USD |\n| 商品期货 | 1 | 黄金/石油 |\n\n资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n---\n\n### extended_hours_service.py\n\n`extended_hours_service.py` 负责处理美股盘前盘后交易时段的检测与市场状态判定。\n\n#### 市场状态定义\n\n| 状态 | 说明 | 时间范围（美东时间） |\n|-----|------|---------------------|\n| `PRE_MARKET` | 盘前交易 | 04:00 - 09:30 |\n| `REGULAR` | 常规交易时段 | 09:30 - 16:00 |\n| `AFTER_HOURS` | 盘后交易 | 16:00 - 20:00 |\n| `CLOSED` | 市场关闭 | 周末/节假日 |\n\n#### 服务流程\n\n```mermaid\ngraph TD\n A[请求行情数据] --> B{检查标的类型}\n B -->|美股| C[调用 extended_hours_service]\n B -->|非美股| D[直接返回报价]\n C --> E[获取当前时间]\n E --> F{判定市场状态}\n F -->|盘前| G[返回 PRE_MARKET]\n F -->|盘中| H[返回 REGULAR]\n F -->|盘后| I[返回 AFTER_HOURS]\n F -->|非交易时段| J[返回 CLOSED]\n G --> K[附加盘前/盘后数据]\n H --> L[返回实时价格]\n I --> M[附加盘后数据]\n J --> N[返回最后收盘价]\n K --> O[合并到最终响应]\n L --> O\n M --> O\n N --> O\n```\n\n---\n\n## MCP 工具接口\n\n### 工具清单\n\n| 工具名 | 功能 | 适用资产 |\n|-------|------|---------|\n| `yahoo_price` | 单标的实时报价 | 股票、加密货币、ETF、外汇 |\n| `market_snapshot` | 全球市场概览 | 14个核心标的 |\n| `get_prices_bulk` | 批量价格查询 | 多标的 |\n\n资料来源：[README.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/README.md)\n\n### yahoo_price 参数说明\n\n| 参数 | 类型 | 必需 | 说明 | 示例 |\n|-----|------|-----|------|-----|\n| `symbol` | string | 是 | 标的代码 | `AAPL`、`BTC-USD` |\n| `include_extended` | boolean | 否 | 是否包含盘后数据 | `true` |\n\n### market_snapshot 参数说明\n\n| 参数 | 类型 | 必需 | 说明 |\n|-----|------|-----|------|\n| 无 | - | - | 无参数，返回全球市场概览 |\n\n---\n\n## 数据流处理\n\n### 实时报价获取流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant MCP as MCP Server\n participant YFS as Yahoo Finance Service\n participant EHS as Extended Hours Service\n participant YF as Yahoo Finance API\n\n User->>MCP: yahoo_price(\"AAPL\")\n MCP->>YFS: get_yahoo_price(\"AAPL\")\n YFS->>YF: 请求 AAPL 报价\n YF-->>YFS: 返回 OHLCV 数据\n YFS->>EHS: 检测市场状态\n EHS-->>YFS: 返回 market_state\n YFS-->>MCP: 构造响应数据\n MCP-->>User: 返回完整报价\n\n User->>MCP: market_snapshot()\n MCP->>YFS: get_market_snapshot()\n loop 14个标的\n YFS->>YF: 批量请求\n YF-->>YFS: 返回数据\n end\n YFS-->>MCP: 返回市场概览\n MCP-->>User: 返回全球市场快照\n```\n\n### 数据处理逻辑\n\n```python\n# 伪代码示例\ndef get_yahoo_price(symbol: str) -> dict:\n # 1. 调用 Yahoo Finance API\n raw_data = yahoo_finance_api.get_quote(symbol)\n \n # 2. 检测盘前盘后状态\n market_state = detect_market_state(symbol)\n \n # 3. 计算涨跌幅\n change = raw_data['current_price'] - raw_data['previous_close']\n change_percent = (change / raw_data['previous_close']) * 100\n \n # 4. 构造返回值\n return {\n \"symbol\": symbol,\n \"price\": raw_data['current_price'],\n \"change\": change,\n \"change_percent\": change_percent,\n \"52_week_high\": raw_data['fifty_two_week_high'],\n \"52_week_low\": raw_data['fifty_two_week_low'],\n \"market_state\": market_state\n }\n```\n\n---\n\n## 与其他模块的集成\n\n### 集成关系图\n\n```mermaid\ngraph LR\n A[Yahoo Finance 集成] --> B[server.py]\n A --> C[Technical Analysis]\n A --> D[Backtesting Engine]\n A --> E[Market Screener]\n \n B -->|MCP 工具| F[Claude Desktop]\n B -->|MCP 工具| G[OpenClaw]\n \n C -->|price_data| H[RSI 计算]\n C -->|price_data| I[MACD 计算]\n C -->|price_data| J[Bollinger Bands]\n \n D -->|历史数据| K[策略回测]\n D -->|历史数据| L[Compare Strategies]\n \n E -->|symbol| M[Top Gainers]\n E -->|symbol| N[Top Losers]\n```\n\n---\n\n## 版本历史\n\n| 版本 | 日期 | 更新内容 |\n|-----|------|---------|\n| 0.6.0 | 2026-03-29 | **初始集成**：yahoo_price、market_snapshot、get_prices_bulk |\n\n资料来源：[CHANGELOG.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/CHANGELOG.md)\n\n---\n\n## 使用示例\n\n### 获取单只股票报价\n\n```python\n# MCP 工具调用示例\nyahoo_price(symbol=\"AAPL\")\n\n# 返回\n{\n \"symbol\": \"AAPL\",\n \"price\": 175.30,\n \"change\": 3.62,\n \"change_percent\": 2.11,\n \"52_week_high\": 198.23,\n \"52_week_low\": 124.17,\n \"market_state\": \"REGULAR\"\n}\n```\n\n### 获取全球市场概览\n\n```python\n# MCP 工具调用示例\nmarket_snapshot()\n\n# 返回概览包含：\n# - S&P 500、NASDAQ、VIX 指数\n# - BTC、ETH 加密货币\n# - EUR/USD、GBP/USD 外汇\n# - 黄金/石油商品\n```\n\n### 获取土耳其股票\n\n```python\n# 土耳其股票使用 .IS 后缀\nyahoo_price(symbol=\"THYAO.IS\")\nyahoo_price(symbol=\"SASA.IS\")\n```\n\n---\n\n## 错误处理与限制\n\n### 常见问题\n\n| 问题 | 原因 | 解决方案 |\n|-----|------|---------|\n| 返回空数据 | 标的代码错误 | 检查 Yahoo Finance 格式 |\n| 盘后数据缺失 | 非美股标的 | 确认标的为美股 |\n| 限流 | 请求过于频繁 | 添加延迟或使用缓存 |\n\n### 速率限制\n\n- Yahoo Finance API 有隐式速率限制\n- 建议批量查询使用 `get_prices_bulk` 而非循环调用 `yahoo_price`\n\n---\n\n## 相关文件\n\n| 文件路径 | 功能 |\n|---------|------|\n| `src/tradingview_mcp/core/services/yahoo_finance_service.py` | Yahoo Finance API 封装 |\n| `src/tradingview_mcp/core/services/extended_hours_service.py` | 盘前盘后检测服务 |\n| `src/tradingview_mcp/server.py` | MCP 工具定义与路由 |\n| `CHANGELOG.md` | 版本更新记录 |\n| `README.md` | 项目文档 |\n\n---\n\n\n\n## 数据源与货币列表\n\n### 相关页面\n\n相关主题：[多交易所支持](#page-exchange-support), [Yahoo Finance 集成](#page-yahoo-finance)\n\n\n相关源码文件
\n\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- [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- [src/tradingview_mcp/coinlist/binance.txt](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/coinlist/binance.txt)\n- [src/tradingview_mcp/coinlist/all.txt](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/coinlist/all.txt)\n \n\n# 数据源与货币列表\n\n## 概述\n\n`tradingview-mcp` 是一个基于 Model Context Protocol (MCP) 的 TradingView 技术分析服务器。该项目的数据源与货币列表系统负责管理交易所交易对信息、货币符号映射以及市场类型识别，为整个系统提供标准化的数据输入源。\n\n项目采用文本文件存储货币列表，并通过专门的 Python 服务模块进行读取和管理，支持多种加密货币交易所和股票市场。\n\n---\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[用户请求] --> B[server.py 入口]\n B --> C{市场类型判断}\n C -->|加密货币| D[coinlist_service.py]\n C -->|股票/ETF| E[validators.py 交易所映射]\n D --> F[coinlist/ 目录]\n E --> G[TradingView Screener API]\n F --> H[binance.txt]\n F --> I[kucoin.txt]\n F --> J[all.txt]\n D --> K[proxy_manager.py 代理管理]\n G --> L[返回分析结果]\n H --> D\n I --> D\n J --> D\n```\n\n### 货币列表目录结构\n\n```\nsrc/tradingview_mcp/\n├── coinlist/\n│ ├── all.txt # 全交易所合并货币列表\n│ ├── binance.txt # Binance 交易对\n│ ├── kucoin.txt # KuCoin 交易对\n│ ├── mexc.txt # MEXC 交易对\n│ ├── bybit.txt # Bybit 交易对\n│ └── 其他交易所文件...\n└── core/\n └── services/\n ├── coinlist.py # 货币列表服务\n └── screener_service.py # 筛选器服务\n```\n\n---\n\n## 货币列表服务 (coinlist_service.py)\n\n### 核心功能\n\n`coinlist_service.py` 是货币列表的核心管理模块，负责加载、缓存和查询各交易所的货币符号列表。\n\n资料来源：[src/tradingview_mcp/core/services/coinlist.py]()\n\n### 主要函数\n\n| 函数 | 功能描述 |\n|------|----------|\n| `load_coinlist(exchange)` | 加载指定交易所的货币列表 |\n| `get_coinlist(exchange)` | 获取货币列表（带缓存） |\n| `get_all_symbols()` | 获取所有交易所的合并列表 |\n| `filter_by_exchange()` | 按交易所筛选货币 |\n\n### 目录路径解析\n\n```python\n# validators.py 中的路径计算逻辑\n_this_file = __file__ # core/utils/validators.py\n_utils_dir = os.path.dirname(_this_file) # core/utils\n_core_dir = os.path.dirname(_utils_dir) # core\n_package_dir = os.path.dirname(_core_dir) # tradingview_mcp\nCOINLIST_DIR = os.path.join(_package_dir, 'coinlist') # tradingview_mcp/coinlist\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:20-25]()\n\n---\n\n## 交易所映射系统\n\n### 交易所筛选器配置\n\n```python\nEXCHANGE_SCREENER = {\n \"binance\": \"BINANCE\",\n \"kucoin\": \"KUCOIN\",\n \"bybit\": \"BYBIT\",\n \"mexc\": \"MEXC\",\n \"NYSE\": \"NYSE\",\n \"NASDAQ\": \"NASDAQ\",\n \"AMEX\": \"AMEX\",\n \"NYSEARCA\": \"AMEX\",\n \"PCX\": \"AMEX\",\n \"TWSE\": \"TWSE\",\n \"TPEX\": \"TPEX\",\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n### 股票交易所标识\n\n```python\nSTOCK_EXCHANGES = {\n \"nyse\", \"nasdaq\", \"amex\", \"tsx\", \"lse\",\n \"jpx\", \"hkex\", \"sse\", \"szse\", \"twse\",\n \"tpex\", \"krx\", \"asx\", \"bse\", \"nse\",\n \"egx\", \"etr\", \"vse\", \"wse\", \"lsis\"\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n### 交易所前缀映射\n\n对于某些特殊交易所，系统需要将不同别名映射到统一前缀：\n\n```python\n_EXCHANGE_TV_PREFIX = {\n \"nysearca\": \"AMEX\",\n \"pcx\": \"AMEX\",\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n---\n\n## 数据源类型\n\n### 加密货币数据源\n\n| 交易所 | 数据格式 | 支持的交易对类型 |\n|--------|----------|------------------|\n| Binance | `SYMBOLUSDT` | USDT 永续合约为主 |\n| KuCoin | `SYMBOLUSDT` | USDT 永续合约 |\n| Bybit | `SYMBOLUSDT` | USDT 永续合约 |\n| MEXC | `SYMBOLUSDT` | USDT 永续合约 |\n\n### 股票/ETF 数据源\n\n| 市场 | 交易所代码 | 示例符号 |\n|------|------------|----------|\n| 美国主板 | `NYSE` | AAPL, TSLA, NVDA |\n| 纳斯达克 | `NASDAQ` | MSFT, GOOGL, AMZN |\n| 美国ETF | `AMEX` | SPY, QQQ, GLD, GDX |\n| 台湾上市 | `TWSE` | 2330, 0050, 0056 |\n| 台湾上柜 | `TPEX` | 指数成分股 |\n| 埃及 | `EGX` | 当地上市公司 |\n\n---\n\n## 符号构建与验证流程\n\n### 加密货币符号构建\n\n```mermaid\ngraph LR\n A[用户输入: BTC] --> B[sanitize_symbol]\n B --> C{交易所类型}\n C -->|加密货币| D[直接使用: BTCUSDT]\n C -->|股票/ETF| E[添加前缀: AMEX:GLD]\n D --> F[返回完整符号]\n E --> F\n```\n\n### 函数调用链\n\n```python\n# 1. 符号清理\nsanitize_symbol(symbol, exchange)\n\n# 2. 交易所验证\nsanitize_exchange(exchange, default=\"kucoin\")\n\n# 3. 市场类型判断\nis_stock_exchange(exchange) # 返回 True/False\n\n# 4. 前缀映射\nget_tv_exchange_prefix(exchange) # NYSEARCA -> AMEX\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n---\n\n## 代理管理系统 (proxy_manager.py)\n\n对于需要代理访问的数据源，项目提供了代理管理功能。\n\n### 代理配置存储\n\n- 代理配置通常存储在环境变量或配置文件中\n- 支持 HTTP/HTTPS/SOCKS5 代理协议\n- 代理轮换机制用于避免请求频率限制\n\n资料来源：[src/tradingview_mcp/core/services/proxy_manager.py]()\n\n---\n\n## 筛选器服务 (screener_service.py)\n\n### analyze_coin 函数\n\n`screener_service.py` 中的 `analyze_coin` 函数是核心分析入口：\n\n```python\nasync def analyze_coin(\n symbol: str,\n exchange: str = \"KUCOIN\",\n timeframe: str = \"1h\"\n) -> dict:\n \"\"\"分析单个交易品种的技术指标\"\"\"\n # 使用 get_tv_exchange_prefix 获取正确前缀\n # 构建 TradingView 格式符号: EXCHANGE:SYMBOL\n # 调用技术指标计算\n # 返回分析结果\n```\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py]()\n\n---\n\n## 时间周期别名映射\n\n项目支持灵活的时间周期输入：\n\n```python\n_TIMEFRAME_ALIASES = {\n \"1m\": \"1m\", \"3m\": \"3m\", \"5m\": \"5m\", \n \"15m\": \"15m\", \"30m\": \"30m\",\n \"1h\": \"1h\", \"2h\": \"2h\", \"4h\": \"4h\",\n \"6h\": \"6h\", \"8h\": \"8h\", \"12h\": \"12h\",\n \"1d\": \"1D\", \"1w\": \"1W\",\n # 中文别名\n \"日线\": \"1D\", \"周线\": \"1W\",\n \"1小时\": \"1h\", \"4小时\": \"4h\"\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py]()\n\n---\n\n## 配置文件\n\n### pyproject.toml 依赖\n\n```toml\n[project]\ndependencies = [\n \"tradingview-screener>=0.3.0\",\n \"yfinance>=0.2.0\",\n \"httpx>=0.27.0\",\n]\n```\n\n### 开发依赖\n\n```toml\n[tool.uv]\ndev-dependencies = [\n \"pytest>=8.0.0\",\n \"ruff>=0.4.0\",\n \"mypy>=1.8.0\",\n]\n```\n\n---\n\n## 测试覆盖\n\n项目为数据源和交易所功能提供了完整的单元测试：\n\n### 测试文件\n\n| 文件 | 测试数量 | 覆盖范围 |\n|------|----------|----------|\n| `tests/unit/test_exchange_fixes.py` | 32 | 交易所别名、前缀映射、符号构建 |\n| `tests/unit/test_exchange_aliases.py` | 37 | TWSE/TPEX 符号构造、预合格符号保护 |\n\n### 测试运行\n\n```bash\n# 运行所有测试\nuv run pytest\n\n# 运行特定测试文件\nuv run pytest tests/unit/test_exchange_fixes.py\n\n# 测试结果\n73 passed in 0.17s (69 new + 4 pre-existing)\n```\n\n资料来源：[PR_BODY.md]()\n\n---\n\n## 常见使用场景\n\n### 场景1：获取加密货币列表\n\n```python\nfrom tradingview_mcp.core.services.coinlist import get_coinlist\n\n# 获取 Binance 交易对\nbinance_coins = get_coinlist(\"binance\")\nprint(f\"Binance 支持 {len(binance_coins)} 个交易对\")\n```\n\n### 场景2：验证股票符号\n\n```python\nfrom tradingview_mcp.core.utils.validators import (\n sanitize_exchange,\n is_stock_exchange,\n get_tv_exchange_prefix\n)\n\n# 验证交易所\nexchange = sanitize_exchange(\"NYSEARCA\") # 返回 \"amex\"\nis_stock = is_stock_exchange(\"NYSE\") # 返回 True\n\n# 获取 TradingView 前缀\nprefix = get_tv_exchange_prefix(\"NYSEARCA\") # 返回 \"AMEX\"\n```\n\n### 场景3：构建完整交易符号\n\n```python\n# 股票ETF: AMEX:GLD\n# 加密货币: BTCUSDT (无前缀)\n\ndef build_tradingview_symbol(symbol: str, exchange: str) -> str:\n \"\"\"根据交易所类型构建 TradingView 格式符号\"\"\"\n if is_stock_exchange(exchange):\n prefix = get_tv_exchange_prefix(exchange)\n return f\"{prefix}:{symbol}\"\n return f\"{symbol}USDT\" # 加密货币默认USDT交易对\n```\n\n---\n\n## 总结\n\n数据源与货币列表系统是 `tradingview-mcp` 的基础设施组件，通过以下方式实现统一的数据访问：\n\n1. **文件式货币列表** - 使用纯文本文件存储，便于维护和扩展\n2. **交易所抽象层** - 统一的交易所标识和映射机制\n3. **智能符号构建** - 自动根据市场类型添加正确前缀\n4. **完整测试覆盖** - 确保交易所映射的准确性和稳定性\n\n---\n\n\n\n## 多交易所支持\n\n### 相关页面\n\n相关主题：[数据源与货币列表](#page-data-sources), [技术分析服务](#page-technical-analysis)\n\n\n相关源码文件
\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- [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/screener_provider.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/services/screener_provider.py)\n- [src/tradingview_mcp/core/data/egx_indices.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/core/data/egx_indices.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- [src/tradingview_mcp/server.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/src/tradingview_mcp/server.py)\n- [tests/unit/test_exchange_fixes.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/tests/unit/test_exchange_fixes.py)\n- [tests/unit/test_exchange_aliases.py](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/tests/unit/test_exchange_aliases.py)\n \n\n# 多交易所支持\n\n## 概述\n\n`tradingview-mcp` 项目提供了一套完整的多交易所支持架构，允许用户通过统一的接口访问全球多个金融市场的实时数据和技术分析。该系统支持加密货币交易所、传统股票交易所以及区域性市场，通过模块化的服务层实现交易所无关的数据获取和处理逻辑。\n\n多交易所支持的核心价值在于：\n\n- **统一 API 接口**：无论底层交易所类型如何，用户通过相同的函数调用获取数据\n- **交易所特定适配**：每种交易所类型都有专属的筛选器配置和数据格式处理\n- **符号标准化**：实现了 `sanitize_exchange` 和 `get_tv_exchange_prefix` 等函数确保符号在 TradingView 格式下正确路由\n- **市场类型识别**：通过 `is_stock_exchange` 和 `get_market_type` 等函数区分股票市场和加密货币市场\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:1-100]()\n\n---\n\n## 架构设计\n\n### 组件关系图\n\n```mermaid\ngraph TD\n subgraph \"表现层\"\n SERVER[server.py - MCP接口]\n end\n \n subgraph \"服务层\"\n SCREENER[screener_service.py
通用筛选器服务]\n EGX[egx_service.py
埃及交易所专用服务]\n SCREENER_PROVIDER[screener_provider.py
筛选器提供者]\n end\n \n subgraph \"数据层\"\n VALIDATORS[validators.py
交易所验证与规范化]\n EGX_INDICES[egx_indices.py
EGX指数数据]\n EGX_SECTORS[egx_sectors.py
EGX板块数据]\n COINLIST[coinlist/
交易所符号列表]\n end\n \n subgraph \"外部数据源\"\n TV[TradingView Screener API]\n YAHOO[Yahoo Finance API]\n end\n \n SERVER --> SCREENER\n SERVER --> EGX\n SCREENER --> SCREENER_PROVIDER\n SCREENER_PROVIDER --> VALIDATORS\n EGX --> VALIDATORS\n SCREENER_PROVIDER --> YAHOO\n EGX --> TV\n VALIDATORS --> COINLIST\n```\n\n### 交易所分类体系\n\n系统将支持的交易所分为两大类别：\n\n| 类别 | 说明 | 识别方式 |\n|------|------|----------|\n| **股票市场** | 传统证券交易所（NYSE、NASDAQ、TWSE 等） | `is_stock_exchange()` 返回 `True` |\n| **加密货币交易所** | 加密货币交易平台（KUCOIN、BINANCE 等） | 不在 `STOCK_EXCHANGES` 中 |\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:30-50]()\n\n---\n\n## 交易所配置与管理\n\n### 核心配置常量\n\n`validators.py` 文件定义了多个关键的交易所配置常量：\n\n```python\nEXCHANGE_SCREENER = {\n \"binance\": \"BINANCE\",\n \"kucoin\": \"KUCOIN\",\n \"bybit\": \"BYBIT\",\n \"mexc\": \"MEXC\",\n \"okx\": \"OKX\",\n \"coinbase\": \"COINBASE\",\n \"nasdaq\": \"NASDAQ\",\n \"nyse\": \"NYSE\",\n \"amex\": \"AMEX\",\n \"nysearca\": \"AMEX\",\n \"pcx\": \"AMEX\",\n \"twse\": \"TWSE\",\n \"tpex\": \"TPEX\",\n \"egx\": \"EGX\",\n \"bist\": \"BIST\",\n}\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:1-50]()\n\n### 交易所别名映射\n\n系统通过 `EXCHANGE_SCREENER` 字典实现交易所别名到标准名称的映射：\n\n| 别名 | 标准名称 | 说明 |\n|------|----------|------|\n| `nysearca` | `AMEX` | NYSE Arca 交易所 |\n| `pcx` | `AMEX` | Arca 交易所（Pacific Exchange） |\n| `amex` | `AMEX` | 美国证券交易所 |\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:10-20]()\n\n### TradingView 前缀映射\n\n`get_tv_exchange_prefix()` 函数将交易所名称转换为 TradingView 符号格式：\n\n```python\n_EXCHANGE_TV_PREFIX = {\n \"amex\": \"AMEX\",\n \"nysearca\": \"AMEX\",\n \"pcx\": \"AMEX\",\n \"nyse\": \"NYSE\",\n \"nasdaq\": \"NASDAQ\",\n \"twse\": \"TWSE\",\n \"tpex\": \"TPEX\",\n}\n```\n\n该函数的工作流程如下：\n\n```mermaid\ngraph LR\n A[输入交易所名称] --> B{是否为已知别名?}\n B -->|是| C[返回映射的标准前缀]\n B -->|否| D[返回大写的原名称]\n C --> E[如: NYSEARCA → AMEX]\n D --> F[如: KUCOIN → KUCOIN]\n```\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:50-80]()\n\n---\n\n## 服务层实现\n\n### 通用筛选器服务\n\n`screener_service.py` 提供了跨交易所的统一筛选功能：\n\n```python\nasync def analyze_coin(\n symbol: str,\n exchange: str = \"KUCOIN\",\n timeframe: str = \"1h\",\n screener: str = \"CRYPTO\"\n) -> dict:\n # 使用 get_tv_exchange_prefix 处理符号\n tv_prefix = get_tv_exchange_prefix(exchange)\n full_symbol = f\"{tv_prefix}:{symbol.upper()}\"\n```\n\n关键功能包括：\n\n- **符号构造**：将交易所前缀与交易对符号组合为完整 TradingView 符号\n- **时间框架规范化**：通过 `sanitize_timeframe` 统一处理时间框架参数\n- **交易所验证**：通过 `sanitize_exchange` 确保只使用支持的交易所\n\n资料来源：[src/tradingview_mcp/core/services/screener_service.py:1-100]()\n\n### 筛选器提供者\n\n`screener_provider.py` 负责根据不同交易所类型选择合适的数据源：\n\n```mermaid\ngraph TD\n A[请求筛选数据] --> B{交易所类型?}\n B -->|加密货币| C[使用 CoinGecko/CoinMarketCap]\n B -->|美国股票| D[使用 Yahoo Finance]\n B -->|TWSE/TPEX| E[使用 TradingView]\n B -->|EGX| F[使用 egx_service]\n C --> G[返回标准化数据]\n D --> G\n E --> G\n F --> G\n```\n\n---\n\n## 区域性市场支持\n\n### 埃及交易所 (EGX)\n\n埃及交易所是项目重点支持的区域性市场之一，提供完整的专用服务：\n\n#### EGX 服务组件\n\n| 组件 | 文件 | 功能 |\n|------|------|------|\n| `egx_service.py` | 核心服务 | EGX 特定的市场概览、股票筛选、交易计划 |\n| `egx_indices.py` | 指数数据 | EGX 主要指数成分和权重 |\n| `egx_sectors.py` | 板块数据 | EGX 行业板块分类 |\n\n资料来源：[src/tradingview_mcp/core/services/egx_service.py:1-50]()\n\n#### EGX 指数配置\n\n```python\nEGX_INDICES = {\n \"EGX30\": {\n \"name\": \"EGX 30 Index\",\n \"description\": \"Primary index tracking top 30 companies\",\n \"constituents\": [\"COMI\", \"MRDY\", \"ETEL\", ...]\n },\n \"EGX70\": {\n \"name\": \"EGX 70 Index\",\n \"description\": \"Broader index tracking mid-cap companies\"\n }\n}\n```\n\n资料来源：[src/tradingview_mcp/core/data/egx_indices.py:1-100]()\n\n#### EGX 板块分类\n\n```python\nEGX_SECTORS = {\n \"banking\": [\"CIB\", \"SAUD\", \"HDBK\"],\n \"telecom\": [\"WE\", \"ETEL\", \"OCDI\"],\n \"real_estate\": [\"TMGH\", \"EAST\", \"SKIP\"],\n \"industrial\": [\"PRMH\", \"LOX\", \"ALCN\"],\n \"tourism\": [\"EGAL\", \"EURN\", \"TOBA\"],\n}\n```\n\n资料来源：[src/tradingview_mcp/core/data/egx_sectors.py:1-100]()\n\n### 台湾交易所 (TWSE/TPEX)\n\n台湾股票市场通过 TradingView 筛选器直接支持：\n\n| 市场 | 交易所代码 | 示例股票 |\n|------|-----------|----------|\n| 台湾证券交易所 | `TWSE` | 2330 (台积电)、0050 (元大台50) |\n| 台湾柜台买卖中心 | `TPEX` | 0056 (元大高股息) |\n\n这些股票已预先配置在 `EXCHANGE_SCREENER` 中，可直接使用筛选器功能。\n\n资料来源：[src/tradingview_mcp/core/utils/validators.py:10-15]()\n\n---\n\n## 符号构造与规范化\n\n### 符号构造流程\n\n在 `server.py` 的 `multi_timeframe_analysis` 函数中展示了完整的符号构造流程：\n\n```python\nasync def multi_timeframe_analysis(\n symbol: str,\n exchange: str = \"KUCOIN\",\n timeframes: list[str] = None\n) -> dict:\n # 1. 规范化交易所名称\n tv_prefix = get_tv_exchange_prefix(exchange)\n \n # 2. 构造完整 TradingView 符号\n full_symbol = f\"{tv_prefix}:{symbol.upper()}\"\n \n # 3. 从多个时间框架获取数据\n results = {}\n for tf in timeframes:\n data = await get_technical_analysis(\n symbol=full_symbol,\n exchange=exchange,\n timeframe=tf\n )\n results[tf] = data\n```\n\n资料来源：[src/tradingview_mcp/server.py:1-100]()\n\n### 符号格式对照表\n\n| 交易所 | 符号前缀 | 示例符号 |\n|--------|----------|----------|\n| KuCoin | `KUCOIN` | `KUCOIN:BTCUSDT` |\n| Binance | `BINANCE` | `BINANCE:BNBUSDT` |\n| NYSE | `NYSE` | `NYSE:AAPL` |\n| NASDAQ | `NASDAQ` | `NASDAQ:TSLA` |\n| AMEX | `AMEX` | `AMEX:GDX` |\n| TWSE | `TWSE` | `TWSE:2330` |\n| TPEX | `TPEX` | `TPEX:0056` |\n\n---\n\n## 测试覆盖\n\n### 交易所修复测试\n\n项目通过完整的单元测试确保多交易所支持的正确性：\n\n| 测试文件 | 测试数量 | 覆盖范围 |\n|----------|----------|----------|\n| `test_exchange_fixes.py` | 32 个测试 | AMEX/NYSEARCA/PCX 别名、符号构造、回归测试 |\n| `test_exchange_aliases.py` | 37 个测试 | TWSE/TPEX 符号构造、预校验符号保护 |\n\n#### 测试覆盖的关键场景\n\n```python\n# test_exchange_fixes.py 示例测试\ndef test_get_tv_exchange_prefix_nysearca():\n \"\"\"NYSEARCA 应映射到 AMEX\"\"\"\n assert get_tv_exchange_prefix(\"NYSEARCA\") == \"AMEX\"\n\ndef test_sanitize_exchange_valid():\n \"\"\"有效交易所应保持不变\"\"\"\n assert sanitize_exchange(\"AMEX\") == \"amex\"\n\ndef test_symbol_construction_gdx():\n \"\"\"GDX ETF 应正确构造为 AMEX:GDX\"\"\"\n tv_prefix = get_tv_exchange_prefix(\"NYSEARCA\")\n assert f\"{tv_prefix}:GDX\" == \"AMEX:GDX\"\n```\n\n资料来源：[tests/unit/test_exchange_fixes.py:1-100]()\n\n#### 回归测试\n\n测试套件确保现有功能不受影响：\n\n```python\ndef test_regression_nyse():\n assert get_tv_exchange_prefix(\"NYSE\") == \"NYSE\"\n\ndef test_regression_twse():\n assert get_tv_exchange_prefix(\"TWSE\") == \"TWSE\"\n\ndef test_regression_kucoin():\n assert get_tv_exchange_prefix(\"KUCOIN\") == \"KUCOIN\"\n```\n\n**测试结果**：73 个测试通过（69 个新增 + 4 个既有测试），耗时 0.17 秒。\n\n资料来源：[PR_BODY.md](https://github.com/atilaahmettaner/tradingview-mcp/blob/main/PR_BODY.md)\n\n---\n\n## 支持的交易所汇总\n\n### 加密货币交易所\n\n| 交易所 | 代码 | 筛选器支持 | 实时价格 |\n|--------|------|------------|----------|\n| KuCoin | `KUCOIN` | ✅ | ✅ |\n| Binance | `BINANCE` | ✅ | ✅ |\n| Bybit | `BYBIT` | ✅ | ✅ |\n| MEXC | `MEXC` | ✅ | ✅ |\n| OKX | `OKX` | ✅ | ✅ |\n| Coinbase | `COINBASE` | ✅ | ✅ |\n\n### 美国股票交易所\n\n| 交易所 | 代码 | 筛选器支持 | 符号示例 |\n|--------|------|------------|----------|\n| 纽约证券交易所 | `NYSE` | ✅ | AAPL, JPM, XOM |\n| 纳斯达克 | `NASDAQ` | ✅ | TSLA, NVDA, AMZN |\n| 美国证券交易所 | `AMEX` | ✅ | GDX, GLD, XLE |\n| NYSE Arca | `NYSEARCA` | ✅ | 同 AMEX |\n| Arca (Pacific) | `PCX` | ✅ | 同 AMEX |\n\n### 区域性股票交易所\n\n| 市场 | 交易所 | 代码 | 专用服务 |\n|------|--------|------|----------|\n| 台湾 | 台湾证券交易所 | `TWSE` | - |\n| 台湾 | 台湾柜买中心 | `TPEX` | - |\n| 埃及 | 埃及证券交易所 | `EGX` | ✅ |\n| 土耳其 | 伊斯坦布尔证券交易所 | `BIST` | ✅ |\n\n---\n\n## 扩展新的交易所\n\n### 步骤 1：更新配置常量\n\n在 `validators.py` 中添加新的交易所映射：\n\n```python\n# 添加到 EXCHANGE_SCREENER\nEXCHANGE_SCREENER[\"new_exchange\"] = \"NEW_EXCHANGE\"\n\n# 如果有别名，添加映射\nEXCHANGE_SCREENER[\"alias\"] = \"NEW_EXCHANGE\"\n\n# 如果需要特殊前缀映射\n_EXCHANGE_TV_PREFIX[\"new_exchange\"] = \"NEW_EXCHANGE\"\n```\n\n### 步骤 2：添加符号列表（如需要）\n\n```bash\n# 创建新的符号列表文件\ntouch src/tradingview_mcp/coinlist/new_exchange.txt\n# 每行添加一个交易对符号\n```\n\n### 步骤 3：验证实现\n\n```bash\n# 运行测试\nuv run pytest tests/unit/test_exchange_fixes.py\n\n# 测试符号构造\nuv run python -c \"\nfrom src.tradingview_mcp.core.utils.validators import get_tv_exchange_prefix, sanitize_exchange\nprint(get_tv_exchange_prefix('NEW_EXCHANGE'))\nprint(sanitize_exchange('new_exchange'))\n\"\n```\n\n---\n\n## 最佳实践\n\n### 交易所名称处理\n\n始终使用 `sanitize_exchange()` 函数处理用户输入：\n\n```python\n# 好的做法\nexchange = sanitize_exchange(user_input)\ntv_prefix = get_tv_exchange_prefix(exchange)\n\n# 避免的做法\nexchange = user_input.upper() # 可能导致验证失败\n```\n\n### 符号构造\n\n使用 `get_tv_exchange_prefix()` 确保符号格式正确：\n\n```python\n# 正确示例\nsymbol = f\"{get_tv_exchange_prefix(exchange)}:{ticker.upper()}\"\n\n# 对于加密货币，原有名称保持不变\nif is_stock_exchange(exchange):\n symbol = f\"{get_tv_exchange_prefix(exchange)}:{ticker.upper()}\"\nelse:\n symbol = f\"{exchange.upper()}:{ticker.upper()}\"\n```\n\n### 时间框架规范化\n\n```python\ntf = sanitize_timeframe(timeframe, default=\"1h\")\n```\n\n---\n\n## 相关文档\n\n- [安装指南](../setup/installation.md) - 如何配置多交易所环境\n- [API 参考](../api/reference.md) - 各交易所函数完整参数说明\n- [故障排除](../troubleshooting.md) - 常见交易所连接问题\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：atilaahmettaner/tradingview-mcp\n\n摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。\n\n## 1. 安全/权限坑 · 涉及密钥、隐私或敏感领域\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。\n- 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。\n- 建议检查：补敏感数据流、密钥存储和权限边界审查。\n- 防护动作：敏感领域或密钥场景必须保守推荐并要求人工复核。\n- 证据：packet_text.keyword_scan | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | matched secret / private key / privacy / trading / finance keyword\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | host_targets=mcp_host, claude, cursor, chatgpt\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：atilaahmettaner/tradingview-mcp\n\n摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。\n\n## 1. 安全/权限坑 · 涉及密钥、隐私或敏感领域\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。\n- 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。\n- 建议检查：补敏感数据流、密钥存储和权限边界审查。\n- 防护动作：敏感领域或密钥场景必须保守推荐并要求人工复核。\n- 证据：packet_text.keyword_scan | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | matched secret / private key / privacy / trading / finance keyword\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | host_targets=mcp_host, claude, cursor, chatgpt\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | no_demo; severity=medium\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_0685d97fbc1a4f92849cb69a812ccd46 | https://github.com/atilaahmettaner/tradingview-mcp#readme | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# tradingview-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 tradingview-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude / Cursor / chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-overview：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation-guide：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-components：核心组件。围绕“核心组件”模拟一次用户任务，不展示安装或运行结果。\n5. page-backtesting-engine：回测引擎。围绕“回测引擎”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-overview\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation-guide\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-components\n输入：用户提供的“核心组件”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-backtesting-engine\n输入：用户提供的“回测引擎”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-overview：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation-guide：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-components：Step 4 必须围绕“核心组件”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-backtesting-engine：Step 5 必须围绕“回测引擎”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/atilaahmettaner/tradingview-mcp#readme\n- openclaw/SKILL.md\n- README.md\n- pyproject.toml\n- CHANGELOG.md\n- INSTALLATION.md\n- .env.example\n- src/tradingview_mcp/server.py\n- src/tradingview_mcp/__init__.py\n- assets/architecture.png\n- src/tradingview_mcp/core/types.py\n- src/tradingview_mcp/core/portfolio.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 tradingview-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：atilaahmettaner/tradingview-mcp\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install tradingview-mcp-server\n```\n\n来源：https://github.com/atilaahmettaner/tradingview-mcp#readme\n\n## 来源\n\n- docs: https://github.com/atilaahmettaner/tradingview-mcp#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_d0a13c0259ce4029b8f69af93297e9d3"
}