财务报告生成项目 - 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. 修改数据源配置
# 文件: 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配置
# 文件: 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. 安装必要的依赖
# 添加到 requirements.txt
requests>=2.25.0
yfinance>=0.1.70
alpha_vantage>=2.3.1
4. 处理API限制和错误
# 添加错误处理和重试机制
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学习步骤
第一步：环境准备
- 安装Python 3.8+
- 安装MCP相关依赖
- 配置开发环境
- 安装Ollama（可选，用于AI功能）
第二步：理解MCP基础概念
- MCP协议概述
- 服务器-客户端架构
- 工具(Tools)和资源(Resources)概念
- 消息格式和通信协议
第三步：实现基础MCP服务器
- 创建MCP服务器框架
- 实现基本的工具注册
- 处理客户端请求
第四步：开发财务数据工具
- 实现数据获取工具
- 实现数据处理工具
- 实现报告生成工具
第五步：集成外部数据源
- 连接财务API
- 处理CSV/Excel文件
- 数据库集成
第六步：高级功能实现
- 智能报告生成
- 数据可视化
- 报告模板系统
- AI模型集成
第七步：测试和优化
- 单元测试
- 集成测试
- 性能优化
快速开始
1. 安装依赖
pip install -r requirements.txt
2. 安装Ollama（可选，用于AI功能）
# 下载并安装Ollama
# 访问 https://ollama.ai 下载安装包
# 安装deepseek-r1模型
ollama pull deepseek-r1:7b
3. 运行演示
纯MCP功能演示
# 运行纯MCP功能演示（包含交互式选择）
python interactive_company_demo_real.py
AI+MCP集成演示
# 运行AI+MCP集成演示（需要Ollama服务运行）
python ai_mcp_demo.py
4. 启动MCP服务器
# 启动纯MCP服务器
python -m src.mcp_server.server
# 或者直接运行交互式演示，其中包含服务器启动选项
AI功能使用
前置条件
- 安装Ollama服务
- 下载deepseek-r1:7b模型：
ollama pull deepseek-r1:7b - 启动Ollama服务：
ollama serve
使用AI功能
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 # 详细文档
关键学习点
- MCP协议理解: 学习MCP的请求-响应模式
- 工具开发: 实现自定义MCP工具
- 资源管理: 处理MCP资源
- 错误处理: 实现健壮的错误处理机制
- 性能优化: 优化MCP服务器性能
使用示例
纯MCP功能演示
- 运行
python interactive_company_demo_real.py - 选择功能：
1(生成单个公司财报) - 选择公司：输入公司代码（如
NVDA）或数字（如1） - 选择报告类型：
1(基础),2(综合),3(财务分析) - 查看生成的报告
批量生成财报
- 选择功能：
2(批量生成多个公司财报) - 输入公司代码：
NVDA,AAPL,MSFT - 选择报告类型
- 等待批量生成完成
AI+MCP集成演示
- 确保Ollama服务运行：
ollama serve - 运行
python ai_mcp_demo.py - 查看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%
使用方法详解
方法一：自动演示版本
python interactive_company_demo.py
- 自动演示所有功能
- 无需用户输入
- 适合快速了解功能
方法二：真正交互式版本
python interactive_company_demo_real.py
- 需要用户实际输入
- 支持单个和批量生成
- 完整的交互体验
使用步骤详解
单个公司财报生成
-
启动程序
python interactive_company_demo_real.py -
选择功能
📋 请选择功能: 1. 生成单个公司财报 2. 批量生成多个公司财报 3. 退出 -
查看公司列表
📋 正在获取可用公司列表... NVDA: NVIDIA Corporation AAPL: Apple Inc. MSFT: Microsoft Corporation ... -
选择公司
- 输入公司代码：
NVDA - 或输入数字：
1(选择NVIDIA)
- 输入公司代码：
-
选择报告类型
1. basic - 基础财报 2. comprehensive - 综合财报 (推荐) 3. financial_analysis - 财务分析报告 -
生成报告
🚀 正在生成 NVDA 的 comprehensive 财报... ✅ 财报生成成功!
批量公司财报生成
-
选择批量功能
2. 批量生成多个公司财报 -
输入公司代码
请输入要生成财报的公司代码，用逗号分隔 (如: NVDA,AAPL,MSFT): 公司代码: NVDA,AAPL,MSFT -
选择报告类型
1. basic - 基础财报 2. comprehensive - 综合财报 3. financial_analysis - 财务分析报告 -
批量生成
🚀 开始批量生成 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）
故障排除
常见问题
-
导入错误
ImportError: attempted relative import with no known parent package- 解决方案：确保在项目根目录运行脚本
-
公司代码错误
ValueError: 不支持的公司代码: XXX- 解决方案：检查公司代码是否正确，参考支持的公司列表
-
文件保存失败
PermissionError: [Errno 13] Permission denied- 解决方案：检查output目录权限，或手动创建output目录
-
Ollama连接失败
ConnectionError: Cannot connect to Ollama service- 解决方案：确保Ollama服务运行，检查端口11434是否开放
获取帮助
如果遇到问题，请：
- 检查错误信息
- 确认运行环境
- 查看日志文件
- 参考本文档
扩展功能
添加新公司
在 src/mcp_server/tools/company_report_generator.py 中的 companies 字典添加新公司：
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服务
使用建议
- 初学者: 先运行
interactive_company_demo_real.py学习MCP基础 - 进阶用户: 运行
ai_mcp_demo.py体验AI增强功能 - 开发学习: 查看
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项目设置中添加以下环境变量（如果需要）：
# 数据库连接（如果有）
DATABASE_URL=your_database_url
# API密钥（如果需要）
API_KEY=your_api_key
# 其他配置
NODE_ENV=production
3. 部署步骤
步骤1: 连接GitHub仓库
- 在Vercel中点击"New Project"
- 选择GitHub仓库:
KennanYang/financial-report - 选择分支:
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. 注意事项
- Python后端: MCP服务器部分不会部署到Vercel，Vercel只部署Next.js前端
- API路由: Next.js API路由位于
web-interface/src/app/api/ - 静态资源: 公共文件位于
web-interface/public/ - 构建输出: 构建后的文件位于
web-interface/.next/
6. 自定义域名（可选）
部署成功后，您可以在Vercel项目设置中配置自定义域名。
7. 自动部署
每次推送到 master 分支时，Vercel会自动触发新的部署。
故障排除
常见问题
- 构建失败: 检查
npm run build是否在本地成功 - 依赖问题: 确保
package.json中的依赖版本兼容 - 环境变量: 检查必要的环境变量是否已配置
本地测试
在部署前，建议在本地测试：
cd web-interface
npm install
npm run build
npm start
支持
如果遇到部署问题，请检查：
- Vercel部署日志
- 本地构建是否成功
- 环境变量配置
- 项目依赖版本兼容性
许可证
MIT License