🚀 股票信息服务中心

本项目是一个基于 FastMCP 的股票数据服务平台，它为用户提供了丰富的股票相关信息，涵盖历史股价数据、公司基本面信息以及新闻资讯等，能满足用户多方面的股票信息查询需求。

🚀 快速开始

环境要求

• Python 版本：3.10 及以上
• 依赖包：
  • fastmcp
  • akshare
  • pandas
  • pydantic
  • pydantic-settings

MCP 客户端配置步骤

1. 拉取代码
2. 使用 uv 创建虚拟环境，要求 Python 3.10+ 版本
3. 使用本地目录方式配置 MCP 服务

以下为示例配置：

{  
  "mcpServers": {  
     "stock-info": {  
      "isActive": true,  
      "command": "uv",  
      "args": [  
        "--directory",  
        "\\path\\to\\sock_info\\src",  
        "run",  
        "server.py"  
      ]  
    }  
  }  
}  

安装部署

1. 创建虚拟环境：

python -m venv .venv  

2. 激活虚拟环境：

   • Windows 系统：.venv\Scripts\activate
   • Linux/macOS 系统：source .venv/bin/activate

3. 安装依赖包：

pip install -r requirements.txt  

启动服务

1. 使用默认配置启动：

python src/server.py  

2. 使用 HTTP 协议启动：

uvicorn stock_info.app:app --reload  

✨ 主要特性

• 获取股票历史数据
• 查询股票基本信息
• 获取风险警示股票列表
• 查看个股新闻
• 获取财经新闻（支持分页）
• 获取股票主营业务信息
• .....后续逐渐增加

📦 安装指南

环境准备

确保你的 Python 版本为 3.10 及以上，并安装好所需的依赖包。

配置 MCP 客户端

按照上述 MCP 客户端配置步骤进行操作，并参考示例配置文件。

安装依赖

创建并激活虚拟环境后，使用 pip install -r requirements.txt 安装项目依赖。

💻 使用示例

基础用法

以下是调用部分接口的示例代码：

# 获取股票历史数据
from stock_info.service.stock_service import get_stock_history_data
history_data = get_stock_history_data('stock_code')
print(history_data)

# 查询股票基本信息
from stock_info.service.stock_service import get_stock_info
stock_info = get_stock_info('stock_code')
print(stock_info)

高级用法

# 获取财经新闻并进行分页查询
from stock_info.service.stock_service import get_financial_news
page = 2
page_size = 10
financial_news = get_financial_news(page=page, page_size=page_size)
print(financial_news)

📚 详细文档

工具说明

以下是服务提供的一些主要功能及其用途：

项目特点

1. 模块化设计：代码结构清晰，便于维护和扩展。
2. 统一异常处理：通过 exceptions.py 实现了统一的错误捕获与处理机制。
3. 数据访问层：使用 repository 层实现数据操作的封装，提升代码复用性。
4. 依赖管理：通过 pyproject.toml 和 requirements.txt 管理项目依赖，确保环境一致性。

开发规范

1. 遵循 PEP 8 编码规范，保持代码风格统一。
2. 使用黑体（black）进行代码格式化，确保代码可读性。
3. 使用 ruff 工具进行代码检查和 linting，保证代码质量。
4. 在提交代码前，请先运行测试用例并确保所有检查通过。

错误处理

服务在遇到错误时会返回如下的 JSON 格式响应：

{  
  "error": {  
    "code": " ErrorCode ",  
    "message": " Error Message "  
  }  
}  

以下是主要的错误代码和对应的含义：

• 400: 参数错误（Bad Request）
• 401: 未授权访问（Unauthorized）
• 403: 禁止访问（Forbidden）
• 404: 资源未找到（Not Found）
• 500: 内部服务器错误（Internal Server Error）

🔧 技术细节

项目结构

stock-info/
├── src/
│   ├── config/           # 配置管理
│   │   └── settings.py
│   ├── core/            # 核心功能
│   │   └── exceptions.py
│   ├── models/          # 数据模型
│   │   └── stock.py
│   ├── repository/      # 数据访问层
│   │   └── stock_repository.py
│   ├── service/         # 业务逻辑层
│   │   └── stock_service.py
│   └── server.py        # 服务入口
├── pyproject.toml       # 项目配置
└── README.md           # 项目文档

设计思路

本项目采用模块化设计，将不同功能模块分离，提高了代码的可维护性和可扩展性。通过统一异常处理机制，确保服务在遇到错误时能返回规范的错误信息。数据访问层的封装提升了代码的复用性，依赖管理工具保证了项目环境的一致性。

📄 许可证

文档中未提及许可证相关信息，若有需要请补充。

注意事项

⚠️ 重要提示

所有 API 接口均支持 JSON 格式返回，部分接口还支持分页查询。使用前请仔细阅读接口文档，确保正确使用参数和返回值。服务运行时可能会产生一定开销，请根据实际情况配置资源限制。

💡 使用建议

在开发过程中，请严格遵循开发规范，确保代码质量。提交代码前务必运行测试用例，避免引入新的问题。