# 📊 FinanceMCP-Alpha

[![npm version](https://img.shields.io/npm/v/finance-mcp-alpha.svg)](https://www.npmjs.com/package/finance-mcp-alpha)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

A powerful **Model Context Protocol (MCP)** server for calculating **WorldQuant 101 Alpha factors** using real-time Chinese stock market data from Tushare. Built with TypeScript and designed for quantitative trading analysis and research.

## ✨ Features

- 🎯 **7 Alpha Factors**: Alpha3, Alpha13, Alpha15, Alpha16, Alpha44, Alpha50, Alpha55
- 📈 **Real-time Data**: Integrates with Tushare API for A-share market data
- 🔒 **Secure**: Token-based authentication via HTTP headers
- 🚀 **Streamable HTTP**: Modern MCP protocol support
- 📊 **Comprehensive Analysis**: Detailed factor statistics and trading signals
- 🎨 **Beautiful Reports**: Markdown-formatted analysis with visual indicators

## 🏗️ Architecture

```
src/
├── index.ts              # MCP server entry point
├── tools/
│   └── calculate_alpha.ts # Alpha calculation tool
├── alphas/
│   └── index.ts          # Alpha factor implementations
└── utils/
    ├── tushare.ts        # Tushare API client
    └── operators.ts      # Mathematical operators
```

## 📦 Installation

### Option 1: Use as npm package

```bash
npm install finance-mcp-alpha
```

### Option 2: Clone and build locally

```bash
git clone https://github.com/guangxiangdebizi/FinanceMCP-Alpha.git
cd FinanceMCP-Alpha
npm install
npm run build
```

## 🚀 Quick Start

### 1. Start the Server

```bash
npm start
```

The server will start on `http://localhost:3000` by default.

```
🚀 FinanceMCP-Alpha Server Started
=====================================
Transport: Streamable HTTP
MCP Endpoint: http://localhost:3000/mcp
Health Check: http://localhost:3000/health
=====================================
```

### 2. Configure MCP Client

Add to your MCP client configuration (e.g., `mcp.json` or Claude Desktop config):

```json
{
  "mcpServers": {
    "finance-alpha": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-Tushare-Token": "YOUR_TUSHARE_TOKEN_HERE"
      },
      "timeout": 600
    }
  }
}
```

**⚠️ Important**: Get your free Tushare token at [https://tushare.pro/register](https://tushare.pro/register)

### 3. Use the Tool

Once connected, you can use the `calculate_alpha` tool:

```
Calculate Alpha factors for stock 000001.SZ from 20240101 to 20241011 
with factors Alpha3, Alpha13, Alpha50
```

## 📖 Alpha Factors

This package implements the following WorldQuant 101 Alpha factors:

### Alpha#3
**Formula**: `(-1 * correlation(rank(open), rank(volume), 10))`  
**Use Case**: Measures negative correlation between opening price ranks and volume ranks. High values suggest contrarian price-volume behavior.

### Alpha#13
**Formula**: `(-1 * rank(covariance(rank(close), rank(volume), 5)))`  
**Use Case**: Captures ranked covariance between closing prices and volume. Identifies price-volume anomalies.

### Alpha#15
**Formula**: `(-1 * sum(rank(correlation(rank(high), rank(volume), 3)), 3))`  
**Use Case**: Sum of ranked correlations between high prices and volume. Detects short-term momentum shifts.

### Alpha#16
**Formula**: `(-1 * rank(covariance(rank(high), rank(volume), 5)))`  
**Use Case**: Similar to Alpha13 but focuses on intraday volatility patterns using high prices.

### Alpha#44
**Formula**: `(-1 * correlation(high, rank(volume), 5))`  
**Use Case**: Negative correlation between high prices and volume ranks. Identifies volume divergence from price peaks.

### Alpha#50
**Formula**: `(-1 * ts_max(rank(correlation(rank(volume), rank(vwap), 5)), 5))`  
**Use Case**: Maximum ranked correlation between volume and VWAP. Measures volume-price efficiency.

### Alpha#55
**Formula**: `(-1 * correlation(rank((close - ts_min(low, 12)) / (ts_max(high, 12) - ts_min(low, 12))), rank(volume), 6))`  
**Use Case**: Correlation between normalized price position and volume. Captures momentum-volume relationships.

## 🔧 Tool Parameters

### `calculate_alpha`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `stock_code` | string | ✅ | Stock code in Tushare format (e.g., `000001.SZ`, `600000.SH`) |
| `start_date` | string | ✅ | Start date in `YYYYMMDD` format (e.g., `20240101`) |
| `end_date` | string | ✅ | End date in `YYYYMMDD` format (e.g., `20241011`) |
| `factors` | array | ✅ | List of factors: `["Alpha3", "Alpha13", "Alpha15", "Alpha16", "Alpha44", "Alpha50", "Alpha55"]` |

### Stock Code Format

- **Shenzhen Stock Exchange**: `XXXXXX.SZ` (e.g., `000001.SZ` - Ping An Bank)
- **Shanghai Stock Exchange**: `XXXXXX.SH` (e.g., `600000.SH` - SPD Bank)

## 📊 Output Format

The tool returns a comprehensive Markdown report including:

- 📈 **Factor Summary Table**: Current values, percentiles, and signals
- 🔍 **Detailed Analysis**: Statistical metrics for each factor
- 💡 **Trading Signals**: Buy/Sell/Hold recommendations based on percentile analysis
- 🎯 **Overall Recommendation**: Aggregated signal from all factors

### Signal Interpretation

| Percentile | Signal | Emoji | Action |
|------------|--------|-------|--------|
| ≥ 80% | STRONG BUY | 🟢 | Strong buying opportunity |
| 60-80% | BUY | 🟢 | Moderate buying opportunity |
| 40-60% | HOLD | 🟡 | Neutral, wait for clearer signal |
| 20-40% | SELL | 🔴 | Moderate selling pressure |
| < 20% | STRONG SELL | 🔴 | Strong selling pressure |

## 🔐 Security Notes

- **Never commit** your Tushare token to version control
- Store tokens securely in your MCP client configuration
- Use environment variables for server configuration
- Token is passed via HTTP header, not stored in server

## 🛠️ Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Start production server
npm start
```

## 📝 Environment Variables

Create a `.env` file (optional):

```env
PORT=3000
```

## 🧪 Testing

Test the health endpoint:

```bash
curl http://localhost:3000/health
```

Expected response:
```json
{
  "status": "healthy",
  "transport": "streamable-http",
  "activeSessions": 0,
  "serverInfo": {
    "name": "FinanceMCP-Alpha",
    "version": "1.0.0"
  }
}
```

## 📚 Use Cases

- **Quantitative Trading**: Integrate alpha factors into your trading strategies
- **Research**: Analyze factor effectiveness across different stocks and time periods
- **Portfolio Management**: Use factor signals for position sizing and rebalancing
- **Market Analysis**: Understand price-volume relationships and market microstructure
- **AI-Assisted Trading**: Leverage LLMs with real-time factor calculations

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## ⚠️ Disclaimer

**This software is for educational and research purposes only.** Alpha factors are statistical indicators and should not be the sole basis for investment decisions. Past performance does not guarantee future results. Always conduct thorough research and consult with financial professionals before making investment decisions.

## 👤 Author

**Xingyu Chen**

- 🌐 GitHub: [@guangxiangdebizi](https://github.com/guangxiangdebizi)
- 💼 LinkedIn: [Xingyu Chen](https://www.linkedin.com/in/xingyu-chen-b5b3b0313/)
- 📦 npm: [@xingyuchen](https://www.npmjs.com/~xingyuchen)
- 📧 Email: guangxiangdebizi@gmail.com

## 🙏 Acknowledgments

- **WorldQuant**: For the Alpha101 factor formulas
- **Tushare**: For providing comprehensive Chinese stock market data
- **Model Context Protocol**: For the amazing MCP framework

## 📖 References

- [WorldQuant 101 Formulaic Alphas](https://arxiv.org/abs/1601.00991)
- [Tushare Pro API Documentation](https://tushare.pro/document/2)
- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)

---

⭐ If you find this project helpful, please consider giving it a star on GitHub!

**Happy Trading! 📈**