🚀 金融建模指南
本指南为金融建模项目提供全面的安装、配置、使用、测试、开发等方面的详细说明，帮助用户快速上手并高效使用该项目。
🚀 快速开始
本项目提供了两种安装方式，分别是使用 Docker 和虚拟环境，你可以根据自己的需求进行选择。
📦 安装指南
使用 Docker
- 拉取镜像：
docker pull ghcr.io/cdtait/fmp-mcp-server:latest - 运行容器：
docker run -it --rm \ -p 8000:8000 \ -v "$PWD:/app" \ ghcr.io/cdtait/fmp-mcp-server:latest - 参数说明：
-it：保持交互模式并分配终端。--rm：容器退出后自动删除。-p 8000:8000：映射端口，使容器内的服务可在主机上访问。-v "$PWD:/app"：将当前目录挂载到容器的/app路径。
使用虚拟环境
- 克隆仓库：
git clone https://github.com/cdtait/fmp-mcp-server.git cd fmp-mcp-server - 创建并激活虚拟环境（推荐使用 Python 3.8+）：
- 在项目根目录下运行：
python -m venv .venv && source ./.venv/bin/activate - 或者，如果已经安装了
poetry，可以运行：poetry install
- 在项目根目录下运行：
- 安装依赖项：
pip install -r requirements.txt - 启动服务：
python main.py
📚 配置指南
环境变量配置
建议在项目根目录下创建一个 .env 文件，用于存储敏感信息和自定义设置。例如：
# Example .env file contents
FMP_API_KEY=your_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
PORT=9000
TEST_MODE=true # For testing with mock data
启动参数
可以通过命令行参数覆盖 .env 文件中的默认值：
python main.py --port 8001 --test_mode false
✨ 功能模块
数据获取
股票数据接口
from fmpsdk import get_stock_data
# 示例：获取苹果股票的历史数据
data = get_stock_data(symbol="AAPL", api_key=api_key)
print(data.head())
外汇数据接口
from fmpsdk import get_fx_rate
# 示例：获取欧元对美元的汇率
rate = get_fx_rate(cross="EURUSD", api_key=api_key)
print(rate)
数据处理
数据清洗
from utils.data_cleaning import clean_stock_data
# 示例：清洗股票数据
cleaned_data = clean_stock_data(data, fillna=True)
💻 使用示例
基础用法
示例1：获取并清洗股票数据
from fmpsdk import get_stock_data
from utils.data_cleaning import clean_stock_data
# 获取股票数据
data = get_stock_data(symbol="AAPL", api_key=api_key)
# 清洗数据
cleaned_data = clean_stock_data(data, fillna=True)
print(cleaned_data.head())
高级用法
示例2：计算技术指标
from utils.technical_indicators import calculate_moving_average
# 示例：计算简单移动平均线（SMA）
sma_50 = calculate_moving_average(close_prices, window=50)
print(sma_50.tail())
🔧 测试与验证
单元测试
运行单元测试：
pytest tests/unit_tests/ --cov --report=
集成测试
运行集成测试：
pytest tests/integration_tests/ --cov --report=
性能测试
使用 benchmark 库进行性能测试：
import pytest_benchmark
from fmpsdk import get_stock_data
@pytest.mark.benchmark
def test_get_stock_data(benchmark):
benchmark(get_stock_data, symbol="AAPL", api_key=api_key)
📚 详细文档
项目结构
fmp-mcp-server/
├── main.py # 主程序入口
├── config/ # 配置文件和环境变量管理
│ └── settings.py
├── data/ # 数据存储和处理逻辑
│ ├── raw_data/
│ └── processed_data/
├── fmpsdk/ # 第三方库接口封装
│ ├── __init__.py
│ └── api.py # API 请求处理
└── tests/ # 测试用例
├── unit_tests/
│ └── test_api.py
└── integration_tests/
└── test_data_cleaning.py
文档编写
用户指南
- 安装
- Docker 安装文档
- 虚拟环境配置说明
- 使用步骤
- 快速上手指南
- 示例代码演示
- 配置选项
- 环境变量详解
- 参数配置说明
开发文档
- 代码结构
- 项目目录树
- 模块功能介绍
- 接口定义
- 第三方库 API 文档
- 自定义函数接口说明
- 测试用例
- 单元测试方法
- 集成测试策略
🚀 CI/CD 流程
自动化测试
- 单元测试：
pytest tests/unit_tests/ --cov --report= - 集成测试：
pytest tests/integration_tests/ --cov --report= - 代码覆盖率报告：
coverage run -m pytest tests/ && coverage report
自动化构建与发布
- 构建 Docker 镜像：
FROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD ["python", "main.py"] - 发布到 Docker Hub：
docker build -t cdtait/fmp-mcp-server:latest . docker push cdtait/fmp-mcp-server:latest
🤝 贡献指南
提交代码
- 创建功能分支：
git checkout -b feature/new-feature - 提交更改：
git add . git commit -m "Add new feature" - 推送到远程仓库：
git push origin feature/new-feature - 创建 Pull Request 到主分支。
📦 容器 registry
Docker Hub 仓库
docker pull ghcr.io/cdtait/fmp-mcp-server:latest
本地构建与测试
- 构建镜像：
docker build -t local/fmp-mcp-server . - 运行容器：
docker run -it --rm -p 8000:8000 local/fmp-mcp-server
📋 开发规范
代码风格
遵循 PEP 8 编码规范。
版本控制
使用 semver 进行版本管理：
- 主版本号：重大功能更新或不兼容更改。
- 次版本号：新增功能或改进。
- 修正版本号：修复错误或漏洞。
❓ 疑问与支持
提问题
在 github 仓库页面提交 Issues：
https://github.com/cdtait/fmp-mcp-server/issues
联系我们
- 邮箱：support@fmp-mcp-server.com
- 社交媒体链接