Stock Info (AKShare)

🚀 股票信息服務中心

本項目是一個基於 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 格式返回，部分接口還支持分頁查詢。使用前請仔細閱讀接口文檔，確保正確使用參數和返回值。服務運行時可能會產生一定開銷，請根據實際情況配置資源限制。

💡 使用建議

在開發過程中，請嚴格遵循開發規範，確保代碼質量。提交代碼前務必運行測試用例，避免引入新的問題。