# 🚀 Modal MCP Stock Analysis Server

A cloud-hosted Model Context Protocol (MCP) server for real-time stock analysis, built with Modal and FastAPI.

## 📋 Overview

This MCP server provides stock analysis tools through a RESTful API, demonstrating how to implement the Model Context Protocol in a distributed, cloud-native architecture.

### 🏗️ Architecture
- **Backend**: Modal serverless platform
- **Framework**: FastAPI for HTTP endpoints
- **Protocol**: Model Context Protocol (MCP) implementation
- **Data Source**: yfinance for real-time stock market data

## ✨ Features

### 🔧 MCP Tools Available:
1. **`get_stock_price`** - Retrieve current stock price and basic company information
2. **`analyze_stock_comprehensive`** - Complete investment analysis with scoring algorithm
3. **`smart_ticker_search`** - Convert company names to ticker symbols

### 📊 Analysis Capabilities:
- Real-time stock price lookup
- YTD return calculations
- P/E ratio analysis
- Investment scoring (0-100 scale)
- Buy/Hold/Sell recommendations
- Smart company name → ticker conversion

## 🚀 Quick Start

### Prerequisites
- Python 3.11+
- Modal account ([modal.com](https://modal.com))
- Modal CLI installed

### Installation & Setup

1. **Clone the repository**
   ```bash
   git clone <your-repo-url>
   cd modal-mcp-server
   ```

2. **Install Modal CLI**
   ```bash
   pip install modal
   ```

3. **Authenticate with Modal**
   ```bash
   modal token new
   ```

4. **Deploy the MCP server**
   ```bash
   modal deploy modal_mcp_complete.py
   ```

## 📡 API Endpoints

### Base URL
```
https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run

```

### Available Endpoints:

#### **GET /** - Server Information
```bash
curl https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/
```

#### **GET /health** - Health Check
```bash
curl https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/health
```

#### **GET /tools** - MCP Tools Discovery
```bash
curl https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/tools
```

#### **POST /call** - Execute MCP Tool
```bash
curl -X POST https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/call \
  -H "Content-Type: application/json" \
  -d '{"name": "TOOL_NAME", "arguments": {"key": "value"}}'
```

## 🛠️ Usage Examples

### Stock Price Lookup
```bash
curl -X POST https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/call \
  -H "Content-Type: application/json" \
  -d '{"name": "get_stock_price", "arguments": {"symbol": "AAPL"}}'
```

**Response:**
```json
{
  "success": true,
  "tool": "get_stock_price",
  "result": [{
    "symbol": "TSLA",
    "company_name": "Tesla, Inc.",
    "current_price": 248.50,
    "market_cap": 790000000000,
    "sector": "Consumer Cyclical"
  }],
  "timestamp": "2025-06-10T..."
}
```

### Comprehensive Analysis
```bash
curl -X POST https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/call \
  -H "Content-Type: application/json" \
  -d '{"name": "analyze_stock_comprehensive", "arguments": {"symbol": "AAPL"}
  }'
```

**Response:**
```json
{
  "success": true,
  "tool": "analyze_stock_comprehensive",
  "result": [{
    "symbol": "AAPL",
    "company_name": "Apple Inc.",
    "current_price": 185.50,
    "ytd_return": 12.5,
    "pe_ratio": 28.5,
    "investment_score": 75,
    "recommendation": "Buy",
    "sector": "Technology"
  }],
  "timestamp": "2025-06-10T..."
}
```

### Smart Ticker Search
```bash
curl -X POST https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "smart_ticker_search",
    "arguments": {"query": "microsoft"}
  }'
```

## 🔧 Configuration

### Environment Variables
- `MCP_SERVER_SECRET` - Optional server secret for authentication

### Modal Secrets
The server can optionally use Modal secrets for configuration:
```python
stock_secrets = modal.Secret.from_name("Stock-api-config")
```

## 📁 Project Structure

```
modal-mcp-server/
├── modal_mcp_complete.py     # Main MCP server implementation
├── README.md                 # This file
└── requirements.txt          # Dependencies (handled by Modal)
```

## 🧠 Investment Scoring Algorithm

The comprehensive analysis uses a proprietary scoring algorithm:

```python
score = 50  # Base score
if ytd_return > 15: score += 25
elif ytd_return > 5: score += 15
elif ytd_return > 0: score += 5

if 10 < pe_ratio < 25: score += 15

# Final score: 0-100
recommendation = "Buy" if score >= 70 else "Hold" if score >= 50 else "Sell"
```

## 🎯 Supported Stock Symbols

### Direct Ticker Symbols:
- **Tech**: AAPL, GOOGL, MSFT, TSLA, META, NVDA, AMD, INTC
- **Finance**: JPM, BAC, WFC, GS
- **Consumer**: WMT, KO, PEP, NKE, MCD
- **ETFs**: SPY, QQQ

### Company Name Mapping:
- apple → AAPL
- microsoft → MSFT  
- google/alphabet → GOOGL
- amazon → AMZN
- tesla → TSLA
- meta/facebook → META
- netflix → NFLX
- nvidia → NVDA

## 🚀 Development

### Local Testing
```bash
# Test health endpoint
curl http://localhost:8000/health

# Test tools discovery
curl http://localhost:8000/tools

# Test tool execution
curl -X POST http://localhost:8000/call \
  -H "Content-Type: application/json" \
  -d '{"name": "get_stock_price", "arguments": {"symbol": "AAPL"}}'
```

### Deployment
```bash
# Deploy to Modal
modal deploy modal_mcp_complete.py

# Check deployment status
modal app list

# View logs
modal logs <app-id>
```

## 🔍 Monitoring & Debugging

### Health Checks
Monitor server health via the `/health` endpoint:
```bash
curl https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/health
```

### Error Handling
The server provides detailed error responses:
```json
{
  "error": "No data available for INVALID",
  "success": false,
  "timestamp": "2025-06-10T..."
}
```

## 📚 MCP Protocol Implementation

This server implements the Model Context Protocol specification:

- **Tool Discovery**: `GET /tools` returns available MCP tools
- **Tool Execution**: `POST /call` executes tools with proper request/response format
- **Error Handling**: Standardized error responses
- **Type Safety**: JSON schema validation for tool inputs

## 🤝 Integration Examples

### Python Client
```python
import requests

def call_mcp_tool(tool_name, arguments):
    response = requests.post(
        "https://your-modal-url/call",
        json={"name": tool_name, "arguments": arguments}
    )
    return response.json()

# Get stock price
result = call_mcp_tool("get_stock_price", {"symbol": "AAPL"})
```

### JavaScript Client
```javascript
async function callMCPTool(toolName, arguments) {
  const response = await fetch('https://your-modal-url/call', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: toolName, arguments })
  });
  return response.json();
}

// Analyze stock
const analysis = await callMCPTool('analyze_stock_comprehensive', { symbol: 'TSLA' });
```

## 📄 License

MIT License - see LICENSE file for details.

## 🙏 Acknowledgments

- **Modal** - For serverless cloud infrastructure
- **Hugging Face** - For hackathon organization
- **yfinance** - For stock market data
- **FastAPI** - For web framework
- **MCP Community** - For protocol specification

## 🔗 Related Links

- **Frontend Interface**: [Gradio MCP Client] (https://huggingface.co/spaces/Agents-MCP-Hackathon/mcp-stock-analysis-hackathon)
- **Modal Platform**: [modal.com](https://modal.com)
- **MCP Specification**: [Model Context Protocol](https://spec.modelcontextprotocol.io/)

---

**Built for the Hugging Face Gradio MCP Hackathon** 🚀