0nri/hsi-mcp-server

HSI MCP Server

A Model Context Protocol (MCP) server for personal use only that retrieves Hang Seng Index (HSI) data and news headlines from AAStocks for research and educational purposes. This server is built with FastAPI and the fastapi-mcp library for robust HTTP-based communication.

⚠️ Important Disclaimer

This project is for personal use only. Not affiliated with AAStocks (www.aastocks.com). Users are responsible for ensuring compliance with AAStocks' terms of service and applicable laws.

Features

• Real-time HSI Data: Current index point, daily change, turnover, and timestamp.
• AI-Powered News Summary: Top headlines with Gemini 2.0 Flash summary.
• MCP Standard Compliance: Works with any MCP-compatible client (Cline, Claude Desktop, MCP Inspector, etc.) over HTTP.
• Unified MCP Endpoint: Provides both simple and streamable HTTP transport over a single /mcp endpoint.
• Robust Web Scraping: Multiple fallback methods for reliable data extraction.

Prerequisites

• Python 3.10 or higher
• Google Cloud Project with Vertex AI API enabled
• Application Default Credentials (ADC) configured

Quick Google Cloud Setup

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

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

Installation

1. Clone the repository:

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

2. Install dependencies:

   pip install -e .
   

3. Configure environment:

   cp .env.example .env
   

   Edit .env with your settings:

   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
   

Usage

This server is designed to run as an HTTP service, perfect for local testing with Docker or for deploying to services like Google Cloud Run.

Running Locally

1. Start the server:

   python -m src.hsi_server.main
   

   The server will be running at http://localhost:8080.

2. Connect with an MCP Client: Use an MCP client like the MCP Inspector to interact with the server. Create a configuration file (e.g., mcp_config.json) with the following content:

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

   Then, run the inspector:

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

   You can now interact with the server at http://127.0.0.1:6274.

Deploying to Cloud Run

A deployment script using Docker and Google Cloud Build is provided.

1. Configure deploy.sh: Edit the configuration variables at the top of the deploy.sh script with your GCP Project ID and desired regions.

2. Run the script:

   chmod +x deploy.sh
   ./deploy.sh
   

   The script will build the Docker image using Cloud Build, push it to Artifact Registry, and deploy it to Cloud Run.

3. Configure your client: After deployment, the script will output the service URL. Use this URL in your MCP client configuration:

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

Available Tools

get_hsi_data

Retrieves current Hang Seng Index data.

Example Response:

{
  "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

Retrieves news headlines with an AI-generated summary.

Parameters:

• limit (optional): Number of headlines (1-20, default: 10)

get_stock_quote

Retrieves current stock quote data for a Hong Kong listed company.

Parameters:

• symbol_or_company (required): Either a HK stock symbol (e.g., "00005", "388") or company name (e.g., "HSBC Holdings")

Example Response:

{
  "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"
  }
}

Note: The tool supports both stock symbols and company names thanks to AI-powered symbol lookup using Gemini.

Troubleshooting

Common Issues

1. "GOOGLE_CLOUD_PROJECT environment variable is required"

   • Ensure your .env file is configured with your Google Cloud project ID.

2. "Failed to initialize Gemini client"

   • Check that the Vertex AI API is enabled: gcloud services enable aiplatform.googleapis.com
   • Verify your ADC setup: gcloud auth application-default login

Debug Mode

Set LOG_LEVEL=DEBUG in your .env file for detailed logging.

License

This project is licensed under the MIT License.