使用说明

📊 MCP金融市场分析工具

一个由人工智能驱动的财务分析平台，结合了 模型上下文协议（MCP）, 小智能体, 快速API，以及溪流提供专业级的投资分析报告。该系统使用大型语言模型来编排交易策略工具并解释财务数据，将原始市场数据转化为可操作的投资见解。

🎯 概述

此应用程序提供 5种不同的分析类型 通过现代网络界面：

分析类型	描述	用例
📈 技术分析	单一股票的4种交易策略	深入了解价格模式
🔍 市场扫描器	同时比较多只股票	寻找最佳机会
💰 基本面	财务报表解释	评估公司健康状况
🌐 多部门分析	跨部门比较	投资组合多样化
🔄 综合分析	技术+基础结合	完整的投资论文

是什么让这与众不同？

与仅显示数字的传统分析工具不同，该系统使用 AI来解释 数据：

Traditional Tool: "RSI = 28.5, MACD = -2.3, P/E = 15.2"

This Application: "AAPL shows oversold conditions with RSI at 28.5, suggesting 
                   a potential mean reversion opportunity. Combined with strong 
                   fundamentals (P/E of 15.2 below sector average), this presents 
                   a BUY signal with high conviction..."

🤖 两种代理架构

此应用程序支持 两种不同的AI代理类型，每个都有独特的优势：

🔧 工具调用代理（原件）

LLM输出JSON以一次调用一个工具的传统方法。

🐍 CodeAgent（新增-推荐）

LLM编写Python代码以调用工具、启用循环和变量的高级方法。

⚖️ 代理比较：ToolCallingAgent与CodeAgent

它们是如何工作的

方面	🔧 工具调用代理	🐍 CodeAgent
输出格式	JSON工具调用	Python代码
工具调用	`{"tool": "analyze", "args": {...}}`	`result = analyze(symbol="AAPL")`
多工具	每LLM轮一次调用	可以使用循环进行批处理
变量	❌ 无法存储结果	✅ 可以使用变量
循环	❌ 不支持	✅ `for stock in stocks:`
条件	❌ 不支持	✅ `if signal == "BUY":`

示例：分析5只股票

ToolCallingAgent方法：

Round 1: LLM → "Call analyze(AAPL)" → Result
Round 2: LLM → "Call analyze(MSFT)" → Result  
Round 3: LLM → "Call analyze(GOOGL)" → Result
Round 4: LLM → "Call analyze(META)" → Result
Round 5: LLM → "Call analyze(NVDA)" → Result
Round 6: LLM → Synthesize all results → Report

Total: 6 LLM calls

CodeAgent方法：

# LLM generates this code in ONE round:
results = {}
for stock in ["AAPL", "MSFT", "GOOGL", "META", "NVDA"]:
    results[stock] = analyze(symbol=stock, period="1y")

# Calculate consensus
buy_signals = sum(1 for r in results.values() if "BUY" in r)
report = f"Consensus: {buy_signals}/5 stocks show BUY signals..."

final_answer(report)

Total: 1-2 LLM calls

性能比较

场景	工具调用代理	代码代理	改进
1个库存，4个工具	~45秒	~40秒	~10%快
5支股票，每支4个工具	~3分钟	~1.5分钟	~50%更快
3个行业，30只股票	~15分钟	~5分钟	~66%更快

优缺点

🔧 工具调用代理

✅ 优点	❌ 缺点
简单且可预测	每轮LLM一次工具调用
无代码执行风险	更多LLM API调用=成本更高
更容易调试	多股票分析速度较慢
适用于任何LLM	无法组合复杂逻辑
久经考验的方法	仅限于顺序执行

最适合：

单一股票分析
简单查询
具有严格安全性的生产环境
代码生成较弱的LLM

🐍 CodeAgent

✅ 优点	❌ 缺点
多股票的高效循环	需要代码执行沙盒
LLM调用更少=成本更低	调试更复杂
可以存储和重用结果	需要具有良好Python技能的LLM
基于代码的自然推理	安全考虑
更适合复杂分析	可能生成无效代码

最适合：

多库存扫描
多部门分析
复杂的比较分析
开发环境
注重成本的使用

安全注意事项

执行者	安全级别	用例
`local`	⚠️ 低	仅开发
`e2b`	✅ 高	生产（云沙盒）
`docker`	✅ 高	生产（自托管）

# Development (local execution)
agent = CodeAgent(tools=tools, model=model, executor_type="local")

# Production (E2B sandbox)
agent = CodeAgent(tools=tools, model=model, executor_type="e2b")

# Production (Docker sandbox)
agent = CodeAgent(tools=tools, model=model, executor_type="docker")

何时使用Which

┌─────────────────────────────────────────────────────────────────┐
│                    DECISION FLOWCHART                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Analyzing single stock?                                        │
│      │                                                          │
│      ├── YES → Either agent works fine                          │
│      │                                                          │
│      └── NO (multiple stocks)                                   │
│              │                                                  │
│              └── Use CodeAgent (2-3x faster)                    │
│                                                                 │
│  Production environment?                                        │
│      │                                                          │
│      ├── YES + Security critical → ToolCallingAgent             │
│      │                                                          │
│      ├── YES + Performance critical → CodeAgent + e2b/docker    │
│      │                                                          │
│      └── NO (development) → CodeAgent + local                   │
│                                                                 │
│  LLM has weak Python skills?                                    │
│      │                                                          │
│      └── YES → ToolCallingAgent (more reliable)                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

🏗️ 架构概述

文件夹结构

mcp_financial_markets_analysis_tool/
│
├── server/                          # MCP Server (Financial Tools)
│   ├── main.py                      # Server entry point
│   ├── strategies/                  # Trading strategy implementations
│   │   ├── bollinger_fibonacci.py   # Bollinger + Fibonacci
│   │   ├── macd_donchian.py         # MACD + Donchian Channel
│   │   ├── connors_zscore.py        # Connors RSI + Z-Score
│   │   ├── dual_moving_average.py   # 50/200 EMA Crossover
│   │   ├── bollinger_zscore.py      # Bollinger + Z-Score
│   │   ├── fundamental_analysis.py  # Financial Statements (70+ row aliases)
│   │   ├── performance_tools.py     # Backtesting Tools
│   │   └── unified_market_scanner.py# Multi-Stock Scanner
│   ├── utils/
│   │   └── yahoo_finance_tools.py   # Data & Indicator Calculations
│   └── README.md                    # 📚 Detailed Server Documentation
│
├── stock_analyzer_bot/              # Smolagents Bot (AI Orchestration)
│   ├── __init__.py
│   ├── main.py                      # ToolCallingAgent implementation
│   ├── main_codeagent.py            # CodeAgent implementation (NEW)
│   ├── api.py                       # FastAPI REST endpoints
│   ├── tools.py                     # Smolagents tool wrappers
│   ├── mcp_client.py                # MCP connection manager
│   └── README.md                    # 📚 Detailed Bot Documentation
│
├── docs/
│   ├── architecture.svg             # ToolCallingAgent diagram
│   ├── architecture_codeagent.svg   # CodeAgent diagram (NEW)
│   └── SECTORS_REFERENCE.md         # Sector symbols reference
│
├── streamlit_app.py                 # Web UI (5 Analysis Tabs)
├── .env                             # Environment variables
├── requirements.txt                 # Python dependencies
└── README.md                        # 📚 This file

数据流摘要

这两种代理类型遵循相同的高级流程：

溪流 → 用户与web界面交互
快速API → REST API接收请求，选择代理类型
代理 → ToolCallingAgent或CodeAgent处理请求
API有限责任公司 → OpenAI/HuggingFace指导工具选择
MCP客户端 → 将代理连接到MCP服务器
MCP服务器 → 执行财务分析工具
策略 → 计算技术指标
雅虎财经 → 提供市场数据

🤖 了解斯莫尔特工

斯莫尔特工是什么？

斯莫尔特工 是Hugging Face的一个开源Python库，可以轻松构建可以使用工具的AI代理。

“smolagents旨在使用几行代码轻松构建和运行代理。” -拥抱的脸

为什么推荐CodeAgent

根据拥抱面部研究:

“多篇研究论文表明，让LLM用代码编写动作比当前工具调用的标准格式要好得多，后者是将动作以JSON形式编写的不同层次。”

代码更好，因为：

可组合性：嵌套函数、使用循环、创建可重用逻辑
对象管理：将输出存储在变量中以供以后使用
普遍性：表示任何计算，而不仅仅是工具调用
训练数据LLMs在培训中看到了很多Python代码

📱 流媒体接口

代理选择切换

侧边栏现在包括一个代理类型选择器：

┌─────────────────────────────────────┐
│  ⚙️ Settings                        │
│                                     │
│  🤖 Agent Type                      │
│  ○ 🔧 ToolCallingAgent (Original)   │
│  ● 🐍 CodeAgent (New - Faster)      │
│                                     │
│  Code Executor: [local ▼]           │
│                                     │
└─────────────────────────────────────┘

5种分析类型

选项卡	描述	推荐代理
📈 技术	单一股票，4种策略	两者皆有
🔍 扫描仪	多股票比较（5种策略）	🐍 CodeAgent
💰 基本面	财务报表	两者皆有
🌐 多部门	跨部门分析	🐍 CodeAgent
🔄 组合	技术+基础	两者皆有

🚀 快速开始

先决条件

Python 3.10+
OpenAI API密钥（推荐）或HuggingFace令牌
互联网连接（雅虎财经数据）

安装

# Clone the repository
git clone <repository-url>
cd mcp_financial_markets_analysis_tool

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
.\venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

环境设置

创建 .env 项目根目录中的文件：

# Required - LLM API Key (choose one)
OPENAI_API_KEY=sk-your-openai-key-here
# OR
HF_TOKEN=hf_your-huggingface-token

# Model Configuration
SMOLAGENT_MODEL_ID=gpt-4o           # Recommended for CodeAgent
SMOLAGENT_MODEL_PROVIDER=litellm     # litellm or inference

# Agent Configuration
SMOLAGENT_AGENT_TYPE=code_agent      # tool_calling or code_agent
SMOLAGENT_EXECUTOR=local             # local, e2b, or docker
SMOLAGENT_MAX_STEPS=25               # Max reasoning steps
SMOLAGENT_TEMPERATURE=0.1            # Low for deterministic outputs
SMOLAGENT_MAX_TOKENS=8192            # Prevents output truncation

# Optional - Defaults
DEFAULT_ANALYSIS_PERIOD=1y
DEFAULT_SCANNER_SYMBOLS=AAPL,MSFT,GOOGL,AMZN

运行应用程序

# Terminal 1: Start the FastAPI backend
uvicorn stock_analyzer_bot.api:app --reload --port 8000

# Terminal 2: Start the Streamlit frontend
streamlit run streamlit_app.py

打开浏览器 http://localhost:8501

🔧 核心组件

1.MCP服务器(`server/`)

这 模型上下文协议服务器 提供所有财务分析工具。

主要特点：

5技术分析策略
使用指标进行性能回溯测试
基于70+行别名的稳健财务数据提取基础分析
多股票统一市场扫描器

📚 详细文件： 服务器/README.md

2.库存分析机器人(`stock_analyzer_bot/`)

这 烟雾动力编排层 具有双代理支持。

关键文件：

main.py -ToolCallingAgent实现（高级工具）
main_codeagent.py -CodeAgent实现（低级工具）
api.py -带代理选择的FastAPI端点
tools.py -MCP工具包装

📚 详细文件： stock_analyzer_bot/README.md

3.流线型前端(`streamlit_app.py`)

这 web界面 带有代理切换和5个分析选项卡。

📡 API 参考

代理商选择

所有端点现在都接受 agent_type 参数：

{
  "symbol": "AAPL",
  "period": "1y",
  "agent_type": "code_agent",
  "executor_type": "local"
}

可用端点

端点	方法	描述
`/health`	GET	健康检查，显示可用代理
`/technical`	POST	单一股票，4种策略
`/scanner`	POST	多库存比较
`/fundamental`	POST	财务报表分析
`/multisector`	POST	跨部门分析
`/combined`	POST	技术+基础

响应格式

{
  "report": "# AAPL Comprehensive Technical Analysis\n...",
  "symbol": "AAPL",
  "analysis_type": "technical",
  "duration_seconds": 35.2,
  "agent_type": "code_agent",
  "tools_approach": "LOW-LEVEL tools (4 strategies + Python code orchestration)"
}

⚙️ 配置

环境变量

# LLM Configuration
OPENAI_API_KEY=sk-...           # Required for OpenAI models
HF_TOKEN=hf_...                 # Required for HuggingFace models
OPENAI_BASE_URL=                # Optional: Custom endpoint

# Model Settings
SMOLAGENT_MODEL_ID=gpt-4o       # Model to use
SMOLAGENT_MODEL_PROVIDER=litellm # litellm (OpenAI) or inference (HuggingFace)
SMOLAGENT_TEMPERATURE=0.1       # Low value for deterministic outputs
SMOLAGENT_MAX_TOKENS=8192       # Prevents output truncation

# Agent Settings
SMOLAGENT_AGENT_TYPE=code_agent  # tool_calling or code_agent
SMOLAGENT_EXECUTOR=local         # local, e2b, or docker
SMOLAGENT_MAX_STEPS=25           # Max reasoning steps

# Analysis Defaults
DEFAULT_ANALYSIS_PERIOD=1y
DEFAULT_SCANNER_SYMBOLS=AAPL,MSFT,GOOGL,AMZN

支持的LLM模型

提供程序	型号ID	CodeAgent支持
OpenAI	`gpt-4o`	✅ 太好了
OpenAI	`gpt-4o-mini`	✅ 很好
OpenAI	`gpt-4-turbo`	✅ 太好了
拥抱的脸	`meta-llama/Llama-3.1-70B-Instruct`	⚠️ 变量

注： CodeAgent最适合具有强大Python代码生成能力的模型。建议使用GPT-4o。

分析期

有效期： 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max

📝 输出格式规则

所有分析输出都遵循严格的格式准则，以实现清晰的渲染：

规则	描述
货币	使用“USD”前缀而不是“$”（避免Streamlit中的LaTeX解释）
表格	避免在markdown表中使用管道字符（在UI中呈现不佳）
数据点	为清楚起见，每个指标都有自己的行
标头	具有清晰层次结构的编号部分
没有意大利语	避免 `text` 格式化

按分析类型统计策略

分析类型	使用的工具	策略
技术分析	`comprehensive_performance_report`	4战略
市场扫描器	`unified_market_scanner`	5战略
多部门	`unified_market_scanner`	5战略

市场扫描策略：

布林带Z分数
布林带和斐波那契回撤
MACD-Donchian组合
Connors RSI和Z评分组合
双重移动平均线交叉

🧪 测试两种试剂

快速比较

# Test both agents on same stock
python test_codeagent.py AAPL

# Test on market scanner
python test_codeagent.py AAPL --mode scanner --symbols "AAPL,MSFT,GOOGL"

在Streamlit

运行技术分析 工具调用代理
注意历史记录中的持续时间
切换到 CodeAgent 在侧边栏中
运行相同的分析
比较时间

🔒 安全与免责声明

代码执行安全

使用CodeAgent时：

发展: local 遗嘱执行人很好
生产：使用 e2b 或 docker 用于沙盒执行
切勿在本地执行器中运行不受信任的代码

财务免责声明

⚠️ 重要： 此软件用于 仅用于教育和研究目的.

所有分析结果应独立验证
过去的表现并不能保证未来的结果
这不是财务建议
投资前咨询持牌财务顾问

🛠️ 故障排除

问题	解决方案
“CodeAgent不可用”	确保 `main_codeagent.py` 存在于 `stock_analyzer_bot/`
“代码执行失败”	检查LLM输出中的Python语法，尝试gpt-4o模型
“找不到MCP服务器”	验证 `server/main.py` 存在于项目根目录
“连接被拒绝”	使用启动FastAPI `uvicorn stock_analyzer_bot.api:app --port 8000`
“超时”	减少库存或增加超时；使用CodeAgent进行多股票交易
“代理提前停止”	增加 `max_steps` 参数
“截断输出”	增加 `SMOLAGENT_MAX_TOKENS` 至8192+
“LaTeX格式错误”	确保代码使用USD前缀而不是$符号
“扫描仪中缺少策略”	验证unified_market_scanner是否使用“详细”输出格式

🔄 最近更改

v2.3.0-输出格式和稳定性

温度配置： 设置为0.1以获得更确定的输出
令牌限制： 将默认值增加到8192以防止截断
货币格式： 从“$”改为“USD”前缀（避免LaTeX问题）
市场扫描器： 修复了缺失的MACD Donchian和Connors RSI ZScore策略
模板转义： 修复了提示模板中的Python格式冲突
响应格式： 添加 format_agent_result() 清洁输出助手

v2.2.0-基本面分析改进

行别名： 扩展到70多个别名，用于稳健的财务数据提取
多层匹配： 精确→ 别名→ 模糊子字符串匹配
财务比率： 增加了4个类别的全面计算
回退处理： 数据提取失败时性能下降

v2.1.0-双代理架构

代码代理： 添加Python代码执行，实现高效的多股票循环
执行器选项： 支持本地、e2b和docker沙盒
工具类别： 分离的高级和低级工具集合
代理选择： 用于选择每个请求的代理类型的API参数

📚 其他文件

文档	描述
服务器/README.md	MCP服务器工具、策略、参数
stock_analyzer_bot/README.md	代理实现，API端点
文档/部门_参考.md	扇区符号和配置
拥抱面部烟雾剂	官方烟雾文件
安全代码执行	CodeAgent安全指南

🤝 贡献

分叉存储库
创建要素分支
实施您的更改
如果适用，添加测试
提交拉取请求

添加新代理类型

该架构支持添加新的代理类型：

在中创建新模块 stock_analyzer_bot/
实现与相同的函数签名 main.py
注册 api.py 具有新的代理类型选项
在中更新UI streamlit_app.py

📄 许可证

这个项目是为了教育目的而提供的。用户必须遵守：

雅虎金融服务条款
OpenAI/HuggingFace服务条款
适用的当地金融法规

🙏 致谢

斯莫尔特工通过拥抱脸
FastMCP MCP框架
雅虎财经市场数据
快速API 用于REST API
溪流用于web界面