README.md•19.9 kB
# 财务报告生成项目 - MCP学习实践
## 项目概述
这是一个用于学习Model Context Protocol (MCP)的财务报告生成项目。通过这个项目,您将学习如何使用MCP来构建智能的财务报告生成系统,并集成AI模型实现智能化分析。
## 项目目标
- 学习MCP的基本概念和架构
- 实现财务数据的获取和处理
- 构建智能报告生成系统
- 集成多种数据源和工具
- 创建可扩展的MCP服务器
- 集成本地AI模型(Ollama deepseek-r1:7b)
## 核心功能
- ✅ **交互式公司财报生成**: 支持选择或输入公司代码生成详细财报
- ✅ **多公司支持**: 支持NVDA, AAPL, MSFT, GOOGL, TSLA, AMZN, META, NFLX, AMD, INTC等10家公司
- ✅ **多种报告类型**: basic(基础), comprehensive(综合), financial_analysis(财务分析)
- ✅ **批量生成**: 支持同时生成多个公司的财报
- ✅ **MCP协议**: 标准MCP工具和资源支持
- ✅ **AI增强功能**: 集成Ollama deepseek-r1:7b模型,提供智能财务分析
- ✅ **本地AI支持**: 支持本地部署的AI模型,无需外部API密钥
## AI功能特性
### Ollama集成
- 🎯 **本地AI模型**: 支持本地部署的deepseek-r1:7b模型
- 🤖 **智能分析**: AI驱动的公司财务分析和投资建议
- 📊 **智能报告**: AI生成的财务报告和投资分析
- 🔄 **灵活切换**: 支持在Ollama和OpenAI之间切换
- ⚡ **快速响应**: 本地模型,响应速度快
### AI功能列表
- **AI公司分析**: 使用AI分析公司财务状况和投资价值
- **AI报告生成**: 使用AI生成智能财务报告
- **AI投资建议**: 使用AI提供投资建议和风险评估
## 重要说明
### 🚨 演示程序使用本地数据
**当前版本使用的是模拟数据,不是真实的财务数据!**
- **数据来源**: 所有财务数据都是程序内部生成的模拟数据
- **用途**: 仅用于学习和演示MCP功能,不构成投资参考
- **真实性**: 股价、财务比率、公司信息等都是模拟值
- **学习价值**: 重点在于学习MCP工具的实现和使用方法
### 🔧 如果要接入真实API,需要修改的地方
#### 1. 修改数据源配置
```python
# 文件: src/mcp_server/tools/company_report_generator.py
# 方法: _get_mock_financial_data()
# 当前代码(模拟数据):
def _get_mock_financial_data(self, symbol: str) -> Dict[str, Any]:
# 返回模拟数据...
# 修改为(真实API):
def _get_real_financial_data(self, symbol: str) -> Dict[str, Any]:
# 调用真实财务API
# 例如: Alpha Vantage, Yahoo Finance, IEX Cloud等
api_key = "your_api_key"
url = f"https://api.example.com/stock/{symbol}"
# 发送HTTP请求获取真实数据...
```
#### 2. 添加API配置
```python
# 文件: config/financial_config.yaml
# 添加真实API配置:
api_providers:
alpha_vantage:
api_key: "your_alpha_vantage_key"
base_url: "https://www.alphavantage.co/query"
yahoo_finance:
api_key: "your_yahoo_key"
base_url: "https://query1.finance.yahoo.com"
```
#### 3. 安装必要的依赖
```bash
# 添加到 requirements.txt
requests>=2.25.0
yfinance>=0.1.70
alpha_vantage>=2.3.1
```
#### 4. 处理API限制和错误
```python
# 添加错误处理和重试机制
import time
from requests.exceptions import RequestException
def get_financial_data_with_retry(self, symbol: str, max_retries: int = 3):
for attempt in range(max_retries):
try:
# 调用API
response = requests.get(url, timeout=10)
response.raise_for_status()
return response.json()
except RequestException as e:
if attempt == max_retries - 1:
raise e
time.sleep(2 ** attempt) # 指数退避
```
## MCP学习步骤
### 第一步:环境准备
1. 安装Python 3.8+
2. 安装MCP相关依赖
3. 配置开发环境
4. 安装Ollama(可选,用于AI功能)
### 第二步:理解MCP基础概念
- MCP协议概述
- 服务器-客户端架构
- 工具(Tools)和资源(Resources)概念
- 消息格式和通信协议
### 第三步:实现基础MCP服务器
- 创建MCP服务器框架
- 实现基本的工具注册
- 处理客户端请求
### 第四步:开发财务数据工具
- 实现数据获取工具
- 实现数据处理工具
- 实现报告生成工具
### 第五步:集成外部数据源
- 连接财务API
- 处理CSV/Excel文件
- 数据库集成
### 第六步:高级功能实现
- 智能报告生成
- 数据可视化
- 报告模板系统
- AI模型集成
### 第七步:测试和优化
- 单元测试
- 集成测试
- 性能优化
## 快速开始
### 1. 安装依赖
```bash
pip install -r requirements.txt
```
### 2. 安装Ollama(可选,用于AI功能)
```bash
# 下载并安装Ollama
# 访问 https://ollama.ai 下载安装包
# 安装deepseek-r1模型
ollama pull deepseek-r1:7b
```
### 3. 运行演示
#### 纯MCP功能演示
```bash
# 运行纯MCP功能演示(包含交互式选择)
python interactive_company_demo_real.py
```
#### AI+MCP集成演示
```bash
# 运行AI+MCP集成演示(需要Ollama服务运行)
python ai_mcp_demo.py
```
### 4. 启动MCP服务器
```bash
# 启动纯MCP服务器
python -m src.mcp_server.server
# 或者直接运行交互式演示,其中包含服务器启动选项
```
## AI功能使用
### 前置条件
1. 安装Ollama服务
2. 下载deepseek-r1:7b模型:`ollama pull deepseek-r1:7b`
3. 启动Ollama服务:`ollama serve`
### 使用AI功能
```python
from mcp_server.tools.ai_enhanced_report_generator import AIEnhancedReportGenerator
# 初始化AI工具(使用Ollama)
ai_tool = AIEnhancedReportGenerator(
ollama_url="http://localhost:11434",
ollama_model="deepseek-r1:7b",
use_ollama=True
)
# 使用AI分析公司
result = await ai_tool.call_tool(CallToolRequest(
method="tools/call",
params={
"name": "ai_analyze_company",
"arguments": {
"symbol": "NVDA",
"analysis_type": "comprehensive"
}
}
))
```
## 项目结构
```
financial-report/
├── README.md # 项目说明
├── requirements.txt # Python依赖
├── interactive_company_demo_real.py # 纯MCP功能演示(交互式)
├── ai_mcp_demo.py # AI+MCP集成演示
├── config/ # 配置文件
│ ├── mcp_config.json # MCP配置
│ ├── financial_config.yaml # 财务数据配置
│ └── ollama_config.yaml # Ollama配置
├── src/ # 源代码
│ └── mcp_server/ # MCP服务器实现
│ ├── server.py # 主服务器
│ ├── tools/ # MCP工具
│ │ ├── company_report_generator.py # 公司财报生成工具
│ │ ├── financial_data.py # 财务数据工具
│ │ ├── report_generator.py # 报告生成工具
│ │ ├── ai_enhanced_report_generator.py # AI增强报告生成器
│ │ └── ollama_client.py # Ollama客户端
│ └── resources/ # MCP资源
│ └── financial_reports.py # 财务报告资源
├── output/ # 输出目录
│ └── reports/ # 生成的报告
└── docs/ # 文档
└── README.md # 详细文档
```
## 关键学习点
1. **MCP协议理解**: 学习MCP的请求-响应模式
2. **工具开发**: 实现自定义MCP工具
3. **资源管理**: 处理MCP资源
4. **错误处理**: 实现健壮的错误处理机制
5. **性能优化**: 优化MCP服务器性能
## 使用示例
### 纯MCP功能演示
1. 运行 `python interactive_company_demo_real.py`
2. 选择功能:`1` (生成单个公司财报)
3. 选择公司:输入公司代码(如 `NVDA`)或数字(如 `1`)
4. 选择报告类型:`1`(基础), `2`(综合), `3`(财务分析)
5. 查看生成的报告
### 批量生成财报
1. 选择功能:`2` (批量生成多个公司财报)
2. 输入公司代码:`NVDA,AAPL,MSFT`
3. 选择报告类型
4. 等待批量生成完成
### AI+MCP集成演示
1. 确保Ollama服务运行:`ollama serve`
2. 运行 `python ai_mcp_demo.py`
3. 查看AI功能演示:
- AI公司分析
- AI报告生成
- AI投资建议
- AI与MCP工具协作
## 支持的公司
| 代码 | 公司名称 | 行业 |
|------|----------|------|
| NVDA | NVIDIA Corporation | 半导体 |
| AAPL | Apple Inc. | 消费电子 |
| MSFT | Microsoft Corporation | 软件 |
| GOOGL | Alphabet Inc. | 互联网服务 |
| TSLA | Tesla Inc. | 汽车 |
| AMZN | Amazon.com Inc. | 电子商务 |
| META | Meta Platforms Inc. | 社交媒体 |
| NFLX | Netflix Inc. | 流媒体 |
| AMD | Advanced Micro Devices | 半导体 |
| INTC | Intel Corporation | 半导体 |
## 报告内容详解
### 报告类型说明
#### 1. **basic** - 基础财报
- 基本信息(公司名称、股票代码、行业分类)
- 财务数据摘要(股价、市值、收入、利润等)
- 基本财务比率(资产负债率、利润率等)
#### 2. **comprehensive** - 综合财报(推荐)
- 完整财务数据
- 详细财务比率分析
- 业务分析(核心业务、增长驱动因素、竞争优势)
- 风险因素分析
- 投资建议
- 技术分析(52周高低点、均线、RSI)
- 市场表现(收益率数据)
#### 3. **financial_analysis** - 财务分析报告
- 深度财务分析
- 行业对比
- 趋势分析
- 投资风险评估
### 报告内容示例
#### NVIDIA (NVDA) 综合财报示例
```
NVIDIA Corporation (NVDA) 财务报告
============================================================
基本信息:
- 公司名称: NVIDIA Corporation
- 股票代码: NVDA
- 行业分类: Technology - Semiconductors
- 报告类型: comprehensive
- 报告期间: latest
- 生成时间: 2025-08-08 08:23:11
财务数据摘要:
- 当前股价: $450.25
- 市值: $1.1T
- 营业收入: $60.9B
- 净利润: $29.8B
- 总资产: $106.1B
- 总负债: $25.3B
财务比率分析:
- 资产负债率: 24.00%
- 净利润率: 49.00%
- 资产收益率: 28.00%
- 股本收益率: 89.00%
- 市盈率: 15.10
- 市净率: 13.40
业务分析:
NVIDIA是全球领先的图形处理器(GPU)和人工智能计算平台提供商。
核心业务:
- GPU业务: 游戏、数据中心、专业可视化
- AI计算: 数据中心GPU、自动驾驶、机器人
- 软件平台: CUDA、AI框架、开发工具
增长驱动因素:
- AI革命推动数据中心GPU需求激增
- 游戏市场持续增长
- 自动驾驶和机器人技术发展
- 云计算和边缘计算扩张
竞争优势:
- 技术领先优势明显
- 强大的生态系统和开发者网络
- 专利组合和知识产权保护
- 与主要云服务提供商的深度合作
风险因素:
主要风险因素:
1. 宏观经济风险: 经济周期波动可能影响需求
2. 竞争风险: 行业竞争加剧可能影响市场份额
3. 技术风险: 技术变革可能影响产品竞争力
4. 监管风险: 政策变化可能影响业务运营
5. 供应链风险: 供应链中断可能影响生产和交付
6. 汇率风险: 汇率波动可能影响国际业务
7. 市场风险: 股票价格波动风险
投资建议:
投资建议: 买入
理由: 估值适中,财务状况稳定,具有投资价值
风险提示:
- 本报告仅供参考,不构成投资建议
- 投资有风险,入市需谨慎
- 请根据自身情况做出投资决策
- 建议咨询专业投资顾问
技术分析:
- 52周最高: $505.48
- 52周最低: $138.84
- 50日均线: $435.2
- 200日均线: $320.15
- 相对强弱指数(RSI): 65.80
市场表现:
- 年初至今收益率: 85.00%
- 过去一年收益率: 225.00%
- 过去三年收益率: 450.00%
```
## 使用方法详解
### 方法一:自动演示版本
```bash
python interactive_company_demo.py
```
- 自动演示所有功能
- 无需用户输入
- 适合快速了解功能
### 方法二:真正交互式版本
```bash
python interactive_company_demo_real.py
```
- 需要用户实际输入
- 支持单个和批量生成
- 完整的交互体验
## 使用步骤详解
### 单个公司财报生成
1. **启动程序**
```bash
python interactive_company_demo_real.py
```
2. **选择功能**
```
📋 请选择功能:
1. 生成单个公司财报
2. 批量生成多个公司财报
3. 退出
```
3. **查看公司列表**
```
📋 正在获取可用公司列表...
NVDA: NVIDIA Corporation
AAPL: Apple Inc.
MSFT: Microsoft Corporation
...
```
4. **选择公司**
- 输入公司代码:`NVDA`
- 或输入数字:`1` (选择NVIDIA)
5. **选择报告类型**
```
1. basic - 基础财报
2. comprehensive - 综合财报 (推荐)
3. financial_analysis - 财务分析报告
```
6. **生成报告**
```
🚀 正在生成 NVDA 的 comprehensive 财报...
✅ 财报生成成功!
```
### 批量公司财报生成
1. **选择批量功能**
```
2. 批量生成多个公司财报
```
2. **输入公司代码**
```
请输入要生成财报的公司代码,用逗号分隔 (如: NVDA,AAPL,MSFT):
公司代码: NVDA,AAPL,MSFT
```
3. **选择报告类型**
```
1. basic - 基础财报
2. comprehensive - 综合财报
3. financial_analysis - 财务分析报告
```
4. **批量生成**
```
🚀 开始批量生成 3 个公司的 comprehensive 财报...
[1/3] 正在生成 NVDA 的财报...
✅ NVDA 财报生成成功!
[2/3] 正在生成 AAPL 的财报...
✅ AAPL 财报生成成功!
[3/3] 正在生成 MSFT 的财报...
✅ MSFT 财报生成成功!
```
## 输出文件
所有生成的报告都会自动保存到 `output/` 目录:
```
output/
├── company_report_NVDA_20250808_082311.txt
├── company_report_AAPL_20250808_082312.txt
├── company_report_MSFT_20250808_082313.txt
└── ...
```
文件命名格式:`company_report_{公司代码}_{时间戳}.txt`
## 注意事项
- 当前版本使用模拟数据,实际应用中可集成真实财务API
- 报告中的投资建议仅供参考,不构成实际投资建议
- 所有报告自动保存到 `output/` 目录
- `interactive_company_demo_real.py` 是已发布的公众号文章基础,请勿修改
- AI功能需要本地Ollama服务支持,确保模型名称正确(deepseek-r1:7b)
## 故障排除
### 常见问题
1. **导入错误**
```
ImportError: attempted relative import with no known parent package
```
- 解决方案:确保在项目根目录运行脚本
2. **公司代码错误**
```
ValueError: 不支持的公司代码: XXX
```
- 解决方案:检查公司代码是否正确,参考支持的公司列表
3. **文件保存失败**
```
PermissionError: [Errno 13] Permission denied
```
- 解决方案:检查output目录权限,或手动创建output目录
4. **Ollama连接失败**
```
ConnectionError: Cannot connect to Ollama service
```
- 解决方案:确保Ollama服务运行,检查端口11434是否开放
### 获取帮助
如果遇到问题,请:
1. 检查错误信息
2. 确认运行环境
3. 查看日志文件
4. 参考本文档
## 扩展功能
### 添加新公司
在 `src/mcp_server/tools/company_report_generator.py` 中的 `companies` 字典添加新公司:
```python
self.companies = {
"NEW": {"name": "New Company", "sector": "Technology", "industry": "Software"},
# ... 其他公司
}
```
### 自定义报告模板
修改 `_create_company_report` 方法来自定义报告格式和内容。
### 集成真实数据
替换 `_get_mock_financial_data` 方法,集成真实的财务数据API。
## 贡献指南
欢迎提交Issue和Pull Request来改进这个项目。
## Demo文件说明
### 简化后的文件结构
项目已经简化为两个核心演示文件:
#### 1. `interactive_company_demo_real.py` - 纯MCP功能演示
- **功能**: 展示纯MCP工具的核心能力
- **特点**:
- 交互式用户输入
- 支持单个和批量财报生成
- 多种报告类型选择
- 完整的MCP工具演示
- **用途**: 学习MCP基础概念和工具使用
- **注意**: 此文件是已发布公众号文章的基础,请勿修改
#### 2. `ai_mcp_demo.py` - AI+MCP集成演示
- **功能**: 展示AI模型与MCP工具的完美结合
- **特点**:
- 集成Ollama deepseek-r1:7b模型
- AI驱动的财务分析
- 智能报告生成
- AI投资建议
- AI与MCP工具协作演示
- **用途**: 学习AI模型与MCP工具的集成方法
- **前置条件**: 需要运行Ollama服务
### 使用建议
1. **初学者**: 先运行 `interactive_company_demo_real.py` 学习MCP基础
2. **进阶用户**: 运行 `ai_mcp_demo.py` 体验AI增强功能
3. **开发学习**: 查看 `src/` 目录下的源代码实现
## 部署指南
### Vercel 部署
#### 项目概述
这是一个包含Python MCP服务器和Next.js Web界面的财务报告系统。
#### 部署配置
##### 1. 项目设置
- **Framework Preset**: Next.js
- **Root Directory**: `./web-interface`
- **Build Command**: `npm run build`
- **Output Directory**: `.next`
- **Install Command**: `npm install`
##### 2. 环境变量配置
在Vercel项目设置中添加以下环境变量(如果需要):
```bash
# 数据库连接(如果有)
DATABASE_URL=your_database_url
# API密钥(如果需要)
API_KEY=your_api_key
# 其他配置
NODE_ENV=production
```
##### 3. 部署步骤
###### 步骤1: 连接GitHub仓库
1. 在Vercel中点击"New Project"
2. 选择GitHub仓库: `KennanYang/financial-report`
3. 选择分支: `master`
###### 步骤2: 配置项目
- **Project Name**: `financial-report` (或您喜欢的名称)
- **Framework Preset**: `Next.js`
- **Root Directory**: `./web-interface`
- **Build Command**: `npm run build` (自动检测)
- **Output Directory**: `.next` (自动检测)
###### 步骤3: 环境变量
根据需要在"Environment Variables"部分添加配置
###### 步骤4: 部署
点击"Deploy"按钮开始部署
##### 4. 项目结构说明
```
financial-report/
├── web-interface/ # Next.js前端应用(Vercel部署目标)
│ ├── src/
│ │ ├── app/ # Next.js App Router
│ │ ├── components/ # React组件
│ │ └── lib/ # 工具函数和常量
│ ├── package.json
│ ├── next.config.ts
│ └── vercel.json # Vercel配置文件(在web-interface目录中)
├── src/ # Python MCP服务器(不在Vercel部署)
└── config/ # 配置文件
```
##### 5. 注意事项
1. **Python后端**: MCP服务器部分不会部署到Vercel,Vercel只部署Next.js前端
2. **API路由**: Next.js API路由位于 `web-interface/src/app/api/`
3. **静态资源**: 公共文件位于 `web-interface/public/`
4. **构建输出**: 构建后的文件位于 `web-interface/.next/`
##### 6. 自定义域名(可选)
部署成功后,您可以在Vercel项目设置中配置自定义域名。
##### 7. 自动部署
每次推送到 `master` 分支时,Vercel会自动触发新的部署。
#### 故障排除
##### 常见问题
1. **构建失败**: 检查 `npm run build` 是否在本地成功
2. **依赖问题**: 确保 `package.json` 中的依赖版本兼容
3. **环境变量**: 检查必要的环境变量是否已配置
##### 本地测试
在部署前,建议在本地测试:
```bash
cd web-interface
npm install
npm run build
npm start
```
#### 支持
如果遇到部署问题,请检查:
1. Vercel部署日志
2. 本地构建是否成功
3. 环境变量配置
4. 项目依赖版本兼容性
## 许可证
MIT License