Hsi MCP Server

HSI MCP服务器

一种模型上下文协议（MCP）服务器 仅供个人使用 从AAStocks检索恒生指数（HSI）数据和新闻头条，用于研究和教育目的。此服务器使用FastAPI构建 fastapi-mcp 用于健壮的基于HTTP的通信的库。

⚠️ 重要免责声明

此项目仅供个人使用。 不隶属于AAStocks（www.AAStocks.com）。用户有责任确保遵守AAStocks的服务条款和适用法律。

特性

• 实时HSI数据：当前指数点、每日变化、营业额和时间戳。
• AI驱动的新闻摘要：Gemini 2.0 Flash摘要的头条新闻。
• MCP标准合规性：通过HTTP与任何兼容MCP的客户端（Cline、Claude Desktop、MCP Inspector等）配合使用。
• 统一MCP端点：通过单一网络提供简单且可流式传输的HTTP /mcp 终点。
• 强大的Web抓取：用于可靠数据提取的多种回退方法。

先决条件

• Python 3.10或更高版本
• 启用Vertex AI API的谷歌云项目
• 已配置应用程序默认凭据（ADC）

快速谷歌云设置

# Enable Vertex AI API
gcloud services enable aiplatform.googleapis.com

# Set up Application Default Credentials
gcloud auth application-default login

安装

1. 克隆存储库:

   git clone https://github.com/0nri/hsi-mcp-server
   cd hsi-mcp-server

1. 安装依赖项:

   pip install -e .

1. 配置环境:

   cp .env.example .env

编辑 .env 使用您的设置：

   GOOGLE_CLOUD_PROJECT=your-project-id
   GEMINI_LOCATION=us-central1
   GEMINI_MODEL=gemini-2.0-flash-lite-001
   LOG_LEVEL=INFO
   PORT=8080 # Port for the server, Cloud Run will override this

用法

此服务器旨在作为HTTP服务运行，非常适合使用Docker进行本地测试或部署到Google Cloud run等服务。

本地运行

1. 启动服务器:

   python -m src.hsi_server.main

服务器将在以下时间运行 http://localhost:8080.

1. 与MCP客户端连接:

使用MCP客户端（如MCP检查器）与服务器交互。创建配置文件（例如。， mcp_config.json)内容如下：

   {
     "mcpServers": {
       "hsi-server": {
         "type": "streamable-http",
         "url": "http://localhost:8080/mcp",
         "useTLS": false
       }
     }
   }

然后，运行检查器：

   npx @modelcontextprotocol/inspector --config mcp_config.json --server hsi-server

现在，您可以在以下位置与服务器交互 http://127.0.0.1:6274.

部署到云运行

提供了一个使用Docker和Google Cloud Build的部署脚本。

1. 配置 deploy.sh:

编辑顶部的配置变量 deploy.sh 使用您的GCP项目ID和所需区域编写脚本。

1. 运行脚本:

   chmod +x deploy.sh
   ./deploy.sh

该脚本将使用Cloud build构建Docker镜像，将其推送到Artifact Registry，并将其部署到Cloud Run。

1. 配置您的客户端:

部署后，脚本将输出服务URL。在MCP客户端配置中使用此URL：

   {
     "mcpServers": {
       "hsi-server-cloud": {
         "type": "streamable-http",
         "url": "YOUR_CLOUD_RUN_SERVICE_URL/mcp",
         "useTLS": true
       }
     }
   }

可用工具

get_hsi_data

检索当前恒生指数数据。

示例响应:

{
  "success": true,
  "data": {
    "current_point": 19234.56,
    "daily_change_point": 123.45,
    "daily_change_percent": 0.65,
    "turnover": 87500000000,
    "timestamp": "2024-01-15T15:30:00.123456",
    "source": "AAStocks"
  }
}

get_hsi_news_summary

使用AI生成的摘要检索新闻标题。

参数:

• limit （可选）：标题数量（1-20，默认值：10）

get_stock_quote

检索香港上市公司的当前股票报价数据。

参数:

• symbol_or_company （必填）：香港股票代码（如“00005”、“388”）或公司名称（如“汇丰控股”）

示例响应:

{
  "success": true,
  "data": {
    "symbol": "00005",
    "company_name": "HSBC Holdings plc",
    "current_price": 65.50,
    "price_change": 1.25,
    "price_change_percent": 1.94,
    "turnover": "542.3M",
    "last_updated_time": "2024-01-15T15:30:00.123456",
    "source": "AAStocks",
    "url": "https://www.aastocks.com/en/stocks/quote/detail-quote.aspx?symbol=00005"
  }
}

备注：该工具支持股票代码和公司名称，这要归功于使用Gemini的人工智能符号查找。

故障排除

常见问题

1. “GOOGLE_CLOUD_PROJECT环境变量是必需的”

- 确保您的 .env 文件配置了您的Google Cloud项目ID。

1. “初始化Gemini客户端失败”

- 检查Vertex AI API是否已启用： gcloud services enable aiplatform.googleapis.com - 验证ADC设置： gcloud auth application-default login

调试模式

集 LOG_LEVEL=DEBUG 在你的 .env 详细日志记录文件。

许可证

该项目根据MIT许可证获得许可。