README.md

metadata

title: MCP Stock Analysis Hackathon
emoji: 🚀
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
license: mit

🚀 MCP Stock Analysis - Hackathon Entry

Hugging Face Gradio MCP Hackathon Submission

A distributed Model Context Protocol (MCP) implementation for real-time stock analysis, showcasing the power of connecting Gradio frontends with cloud-hosted MCP servers.

🏆 Hackathon Details

• Event: Hugging Face Gradio MCP Hackathon
• Track: Track 1: MCP Tool / Server
• Submission Date: 10th June 2025

🏗️ Architecture

┌─────────────────────┐    HTTP/JSON    ┌──────────────────────┐
│   Gradio Frontend   │ ◄─────────────► │   Modal MCP Server   │
│  (Hugging Face)     │      REST API   │     (Backend)        │
│                     │                 │                      │
│ - User Interface    │                 │ - MCP Protocol       │
│ - Stock Lookup      │                 │ - Stock Analysis     │
│ - Results Display   │                 │ - yfinance Data      │
└─────────────────────┘                 └──────────────────────┘

✨ Features

🔍 MCP Tools Available

1. Stock Price Lookup - Real-time price, market cap, and company info
2. Comprehensive Analysis - Investment scoring with buy/hold/sell recommendations
3. Smart Ticker Search - Company name to ticker symbol conversion

📊 User Interface

• Intuitive Gradio Interface - Easy-to-use web interface
• Real-time Data - Live stock market information
• Error Handling - Robust error handling and user feedback
• Multiple Views - Tabbed interface for different functionalities

🛠️ Technical Implementation

• MCP Protocol - Full Model Context Protocol implementation
• Cloud Architecture - Scalable backend on Modal
• RESTful API - Standard HTTP/JSON communication
• Real-time Data - Uses yfinance for live market data

🚀 Live Demo

Try the live application: [Your Hugging Face Space URL]

Backend MCP Server: https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run

📋 Example Usage

Stock Symbols to Try:

• Tech: AAPL, GOOGL, MSFT, TSLA, META, NVDA
• Finance: JPM, BAC, WFC, GS
• Consumer: WMT, KO, PEP, NKE

Company Names:

• apple, microsoft, tesla, amazon, netflix, nvidia

🔧 Technical Stack

Frontend (Gradio)

• Framework: Gradio 4.0+
• Hosting: Hugging Face Spaces
• Language: Python
• UI Components: Tabs, JSON displays, status indicators

Backend (Modal MCP Server)

• Framework: FastAPI + Modal
• Protocol: Model Context Protocol (MCP)
• Data Source: yfinance
• Analysis: Custom investment scoring algorithm
• Hosting: Modal cloud platform

📡 API Endpoints

MCP Server Endpoints:

• GET /health - Server health check
• GET /tools - Available MCP tools discovery
• POST /call - Execute MCP tools
• GET / - Server information

Tool Execution Format:

{
  "name": "get_stock_price",
  "arguments": {
    "symbol": "AAPL"
  }
}

🏅 Hackathon Innovation

What Makes This Special:

1. Distributed MCP Architecture - Build on Modal.Separates frontend and backend for scalability
2. Cloud-Native Design - Leverages Modal for compute and HF Spaces for interface
3. Real-World Application - Practical stock analysis with investment recommendations
4. User-Friendly Interface - Makes MCP accessible to non-technical users
5. Robust Error Handling - Graceful handling of network and data issues

MCP Protocol Demonstration:

• Tool Discovery - Dynamic loading of available tools
• Tool Execution - Remote tool execution via HTTP
• Error Handling - Proper error propagation and user feedback
• Real-time Communication - Live data exchange between components

🔄 Development Workflow

1. Backend Development - Modal MCP server with stock analysis tools
2. API Testing - Validation of MCP protocol implementation
3. Frontend Creation - Gradio interface development
4. Integration Testing - End-to-end functionality verification
5. Deployment - Production deployment on both platforms

📈 Investment Analysis Algorithm

The comprehensive analysis includes:

• YTD Return Calculation - Year-to-date performance analysis
• PE Ratio Evaluation - Price-to-earnings ratio assessment
• Scoring System - 0-100 investment score
• Recommendations - Buy/Hold/Sell suggestions based on analysis

🤝 Contributing

This is a hackathon submission, but feedback and suggestions are welcome!

📄 License

MIT License - Feel free to use and modify for your own projects.

🙏 Acknowledgments

• Hugging Face - For hosting the Gradio frontend and organizing the hackathon
• Modal - For providing cloud compute credits and hosting the MCP server
• yfinance - For real-time stock market data
• MCP Community - For the Model Context Protocol specification

---

Built with ❤️ for the Hugging Face Gradio MCP Hackathon