🚀 金融建模指南

本项目提供了金融建模所需的工具和服务，涵盖数据获取、处理、测试等多个方面，帮助开发者更高效地进行金融建模工作。

🚀 快速开始

本项目提供了两种安装方式，分别是使用 Docker 和虚拟环境，你可以根据自己的需求选择合适的方式进行安装。

📦 安装指南

使用 Docker

1. 拉取镜像：

   docker pull ghcr.io/cdtait/fmp-mcp-server:latest
   

2. 运行容器：

   docker run -it --rm \
     -p 8000:8000 \
     -v "$PWD:/app" \
     ghcr.io/cdtait/fmp-mcp-server:latest
   

3. 参数说明：
   • -it：保持交互模式并分配终端。
   • --rm：容器退出后自动删除。
   • -p 8000:8000：映射端口，使容器内的服务可在主机上访问。
   • -v "$PWD:/app"：将当前目录挂载到容器的 /app 路径。

使用虚拟环境

1. 克隆仓库：

   git clone https://github.com/cdtait/fmp-mcp-server.git
   cd fmp-mcp-server
   

2. 创建并激活虚拟环境（推荐使用 Python 3.8+）：
   • 在项目根目录下运行：

     python -m venv .venv && source ./.venv/bin/activate
     

   • 或者，如果已经安装了 poetry，可以运行：

     poetry install
     

3. 安装依赖项：

   pip install -r requirements.txt
   

4. 启动服务：

   python main.py
   

✨ 主要特性

数据获取

• 股票数据接口：可获取股票的历史数据。

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)

📚 详细文档

配置指南

环境变量配置

建议在项目根目录下创建一个 .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

测试与验证

单元测试

运行单元测试：

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)

CI/CD 流程

自动化测试

1. 单元测试：

   pytest tests/unit_tests/ --cov --report=
   

2. 集成测试：

   pytest tests/integration_tests/ --cov --report=
   

3. 代码覆盖率报告：

   coverage run -m pytest tests/ && coverage report
   

自动化构建与发布

1. 构建 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"]
   

2. 发布到 Docker Hub：

   docker build -t cdtait/fmp-mcp-server:latest .
   docker push cdtait/fmp-mcp-server:latest
   

贡献指南

提交代码

1. 创建功能分支：

   git checkout -b feature/new-feature
   

2. 提交更改：

   git add .
   git commit -m "Add new feature"
   

3. 推送到远程仓库：

   git push origin feature/new-feature
   

4. 创建 Pull Request 到主分支。

容器 registry

Docker Hub 仓库

docker pull ghcr.io/cdtait/fmp-mcp-server:latest

本地构建与测试

1. 构建镜像：

   docker build -t local/fmp-mcp-server .
   

2. 运行容器：

   docker run -it --rm -p 8000:8000 local/fmp-mcp-server
   

开发规范

代码风格

遵循 PEP 8 编码规范。

版本控制

使用 semver 进行版本管理：

• 主版本号：重大功能更新或不兼容更改。
• 次版本号：新增功能或改进。
• 修正版本号：修复错误或漏洞。

文档编写

用户指南

1. 安装
   • Docker 安装文档
   • 虚拟环境配置说明
2. 使用步骤
   • 快速上手指南
   • 示例代码演示
3. 配置选项
   • 环境变量详解
   • 参数配置说明

开发文档

1. 代码结构
   • 项目目录树
   • 模块功能介绍
2. 接口定义
   • 第三方库 API 文档
   • 自定义函数接口说明
3. 测试用例
   • 单元测试方法
   • 集成测试策略

疑问与支持

提问题

在 github 仓库页面提交 Issues： https://github.com/cdtait/fmp-mcp-server/issues

联系我们

• 邮箱：support@fmp-mcp-server.com
• 社交媒体链接

💻 使用示例

基础用法

示例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())

高级用法

暂未提供高级用法示例，可根据项目的具体需求进行拓展。

项目结构

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