HACKATHON_DEMO.md

# 🏆 Stack Overflow MCP Server - Hackathon Demo

## 🎯 Project Overview

This project demonstrates a **Stack Overflow MCP (Model Context Protocol) Server** built with Gradio for a hackathon. It provides both a beautiful web interface and an MCP server that AI assistants like Claude can use to programmatically search and analyze Stack Overflow content.

## 🌟 Key Features

### 🔍 **Multiple Search Methods**
- **General Search**: Query-based search with tag filtering
- **Error Search**: Specialized search for error messages and debugging
- **Question Retrieval**: Get specific questions by ID
- **Stack Trace Analysis**: Analyze stack traces to find solutions
- **Advanced Search**: Comprehensive filtering with multiple criteria

### 🎨 **Beautiful Web Interface**
- Clean, modern Gradio interface
- Multiple tabs for different search types
- Quick example buttons for easy testing
- Real-time search results with formatted output
- Support for both Markdown and JSON output formats

### 🤖 **MCP Server Integration**
- Full MCP compatibility for AI assistants
- SSE (Server-Sent Events) endpoint for real-time communication
- 5 available MCP tools for different search scenarios
- Easy integration with Claude Desktop and other MCP clients

## 🚀 Live Demo

**🌐 Web Interface**: [https://c44b366466c774a9d5.gradio.live](https://c44b366466c774a9d5.gradio.live)

**🔗 MCP Server Endpoint**: `https://c44b366466c774a9d5.gradio.live/gradio_api/mcp/sse`

## 🛠️ Available MCP Tools

| Tool | Description | Use Case |
|------|-------------|----------|
| `search_by_query_sync` | General Stack Overflow search | Find solutions by keywords and tags |
| `search_by_error_sync` | Error-specific search | Debug specific error messages |
| `get_question_sync` | Retrieve specific question by ID | Get detailed question information |
| `analyze_stack_trace_sync` | Analyze stack traces | Find solutions for runtime errors |
| `advanced_search_sync` | Advanced search with filters | Complex queries with multiple criteria |

## 📊 Demo Scenarios

### 1. **General Programming Search**
```
Query: "Django pagination best practices"
Tags: python,django
Filters: Minimum score 5, Must have accepted answer
```

### 2. **Error Debugging**
```
Error: "TypeError: 'NoneType' object has no attribute 'length'"
Language: Python
Technologies: flask,sqlalchemy
```

### 3. **Stack Trace Analysis**
```
Stack Trace: "ReferenceError: useState is not defined"
Language: JavaScript
```

### 4. **Advanced Search**
```
Query: "memory optimization"
Include Tags: c++,performance
Exclude Tags: beginner
Min Score: 50
Sort By: votes
```

## 🔧 Technical Architecture

### Frontend (Gradio)
- **Framework**: Gradio 5.33.1 with MCP support
- **Interface**: Multi-tab design with intuitive controls
- **Features**: Real-time search, example buttons, format selection

### Backend (Stack Overflow MCP Server)
- **API Integration**: Stack Exchange API with rate limiting
- **MCP Protocol**: Full MCP compatibility with SSE transport
- **Search Engine**: Multiple search strategies and filtering options
- **Response Formatting**: Markdown and JSON output formats

### Infrastructure
- **Package Manager**: UV for fast dependency management
- **Deployment**: Gradio sharing with public URLs
- **MCP Server**: Integrated MCP server with Gradio

## 🎮 How to Test

### Web Interface Testing
1. Visit the [live demo](https://a6f742bf182e4bae9b.gradio.live)
2. Try the different tabs:
   - **General Search**: Use example buttons or enter custom queries
   - **Error Search**: Test with common error messages
   - **Get Question**: Try question ID `11227809`
   - **Stack Trace Analysis**: Use the pre-filled JavaScript example
   - **Advanced Search**: Experiment with complex filters

### MCP Client Testing
Configure your MCP client (like Claude Desktop) with:
```json
{
  "mcpServers": {
    "stackoverflow": {
      "url": "https://c44b366466c774a9d5.gradio.live/gradio_api/mcp/sse"
    }
  }
}
```

## 🏗️ Local Development

```bash
# Clone and setup
git clone <repository>
cd gradio_stack_overflow_client

# Install dependencies
uv add "gradio[mcp]"

# Set your Stack Exchange API key
export STACK_EXCHANGE_API_KEY="your_api_key_here"

# Run the application
uv run python gradio_app.py
```

## 🎯 Hackathon Highlights

### Innovation
- **Dual Interface**: Both web UI and MCP server in one application
- **Smart Search**: Multiple specialized search strategies
- **User Experience**: Intuitive interface with quick examples

### Technical Excellence
- **Modern Stack**: UV, Gradio 5.33+, FastMCP integration
- **Robust API**: Rate limiting, error handling, async operations  
- **MCP Compliance**: Full protocol implementation with SSE transport

### Practical Value
- **Real-world Utility**: Solves actual developer problems
- **AI Integration**: Ready for AI assistant workflows
- **Extensible**: Easy to add new search methods and filters

## 🚀 Future Enhancements

- **Authentication**: User-specific search history
- **Caching**: Redis caching for faster responses
- **Analytics**: Search pattern analysis and recommendations
- **Multi-platform**: GitHub, GitLab, and other developer platforms
- **AI Features**: Semantic search and intelligent filtering

---

**Built with ❤️ for the MCP Hackathon**

*Demonstrating the power of combining beautiful web interfaces with powerful MCP server capabilities*