agentic MCP financial markets analysis tool

📊 MCP金融市场分析工具

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

______________________________________________________________________

🎯 概述

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

是什么让这与众不同？

与仅显示数字的传统分析工具不同，该系统使用 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

它们是如何工作的

示例：分析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

性能比较

优缺点

🔧 工具调用代理

最适合：

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

🐍 CodeAgent

最适合：

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

安全注意事项

# 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

数据流摘要

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

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

______________________________________________________________________

🤖 了解斯莫尔特工

斯莫尔特工是什么？

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

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

为什么推荐CodeAgent

根据 拥抱面部研究:

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

代码更好，因为：

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

______________________________________________________________________

📱 流媒体接口

代理选择切换

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

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

5种分析类型

______________________________________________________________________

🚀 快速开始

先决条件

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

安装

# Clone the repository
git clone 
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"
}

可用端点

响应格式

{
  "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模型

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

分析期

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

______________________________________________________________________

📝 输出格式规则

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

按分析类型统计策略

市场扫描策略：

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

______________________________________________________________________

🧪 测试两种试剂

快速比较

# 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

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

______________________________________________________________________

🔒 安全与免责声明

代码执行安全

使用CodeAgent时：

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

财务免责声明

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

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

______________________________________________________________________

🛠️ 故障排除

______________________________________________________________________

🔄 最近更改

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参数

______________________________________________________________________

📚 其他文件

______________________________________________________________________

🤝 贡献

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

添加新代理类型

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

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

______________________________________________________________________

📄 许可证

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

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

______________________________________________________________________

🙏 致谢

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

______________________________________________________________________