Upload folder using huggingface_hub

.env.example

@@ -0,0 +1,7 @@
+# Stack Exchange API credentials
+STACK_EXCHANGE_API_KEY=your_api_key_here
+
+# Rate limiting configuration
+MAX_REQUEST_PER_WINDOW=30
+RATE_LIMIT_WINDOW_MS=60000
+RETRY_AFTER_MS=2000

.gitignore

@@ -0,0 +1,17 @@
+# Python cache directories
+__pycache__/
+.pytest_cache/
+*.py[cod]
+*$py.class
+
+# Virtual environment
+.venv/
+
+# IDE specific files
+.python-version
+
+# Package building artifacts
+*.egg-info/
+
+.env
+dist/

.gradio/certificate.pem

@@ -0,0 +1,31 @@
+-----BEGIN CERTIFICATE-----
+MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw
+TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
+cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4
+WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu
+ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY
+MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc
+h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+
+0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U
+A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW
+T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH
+B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC
+B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv
+KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn
+OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn
+jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw
+qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI
+rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV
+HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq
+hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL
+ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ
+3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK
+NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5
+ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur
+TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC
+jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc
+oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq
+4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA
+mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d
+emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=
+-----END CERTIFICATE-----

FINAL_SUBMISSION.md

@@ -0,0 +1,198 @@
+# 🏆 Stack Overflow MCP Server - Complete Hackathon Submission
+
+## 🎯 **DEMO SUMMARY**
+
+**✅ COMPLETED**: A fully functional Stack Overflow MCP Server with beautiful Gradio interface
+
+**🌐 LIVE DEMO**: [https://c44b366466c774a9d5.gradio.live](https://c44b366466c774a9d5.gradio.live)
+
+**🔗 MCP ENDPOINT**: `https://c44b366466c774a9d5.gradio.live/gradio_api/mcp/sse`
+
+---
+
+## 🚀 **WHAT WE BUILT**
+
+### 🎨 **Beautiful Web Interface**
+- **5 Specialized Search Tabs**: General Search, Error Search, Question Retrieval, Stack Trace Analysis, Advanced Search
+- **Interactive Examples**: Quick-start buttons with pre-configured searches
+- **Real-time Results**: Formatted markdown/JSON output with syntax highlighting
+- **Modern UI**: Clean Gradio interface with intuitive controls
+
+### 🤖 **Full MCP Server Integration**
+- **5 MCP Tools Available**: Complete toolkit for AI assistants
+- **SSE Transport**: Server-Sent Events for real-time communication
+- **Claude Desktop Ready**: Drop-in configuration for immediate use
+- **Standardized Protocol**: Full MCP compliance for interoperability
+
+### 🔍 **Comprehensive Search Capabilities**
+- **Smart Query Processing**: Natural language search with tag filtering
+- **Error-Specific Search**: Specialized debugging assistance
+- **Stack Trace Analysis**: Automated error pattern recognition
+- **Advanced Filtering**: Multi-criteria search with 15+ filter options
+- **High-Quality Results**: Score-based filtering and accepted answers
+
+---
+
+## 🛠️ **TECHNICAL ARCHITECTURE**
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Gradio UI     │    │   MCP Server    │    │ Stack Exchange  │
+│                 │    │                 │    │      API        │
+│ • 5 Search Tabs │◄──►│ • 5 MCP Tools   │◄──►│ • 300+ Sites   │
+│ • Examples      │    │ • SSE Transport │    │ • Rate Limited  │
+│ • Real-time     │    │ • Async Ops     │    │ • Rich Content  │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+**🔧 Tech Stack**:
+- **Frontend**: Gradio 5.33.1 with MCP support
+- **Backend**: FastMCP with AsyncIO
+- **API**: Stack Exchange API v2.3
+- **Transport**: Server-Sent Events (SSE)
+- **Package Manager**: UV for fast dependency management
+
+---
+
+## 🎮 **DEMO SCENARIOS**
+
+### 1. **👨‍💻 Developer Searches**
+```
+🔍 "Django pagination best practices" + tags:python,django
+🎯 Result: Top-rated Django pagination solutions with code examples
+```
+
+### 2. **🐛 Error Debugging**
+```
+🔍 "TypeError: 'NoneType' object has no attribute" + language:Python
+🎯 Result: Common NoneType error solutions with prevention tips
+```
+
+### 3. **📚 Famous Questions**
+```
+🔍 Question ID: 11227809
+🎯 Result: "Why is processing a sorted array faster?" (50K+ votes)
+```
+
+### 4. **📊 Stack Trace Analysis**
+```
+🔍 "ReferenceError: useState is not defined" + language:JavaScript
+🎯 Result: React hooks troubleshooting guide
+```
+
+### 5. **⚙️ Advanced Filtering**
+```
+🔍 Query:"memory optimization" + tags:c++,performance + min_score:50
+🎯 Result: High-quality C++ performance optimization answers
+```
+
+---
+
+## 🤖 **MCP CLIENT INTEGRATION**
+
+### Claude Desktop Configuration
+```json
+{
+  "mcpServers": {
+    "stackoverflow": {
+      "url": "https://c44b366466c774a9d5.gradio.live/gradio_api/mcp/sse"
+    }
+  }
+}
+```
+
+### Available MCP Tools
+| Tool Name | Description | Use Case |
+|-----------|-------------|----------|
+| `search_by_query_sync` | General search with tags | Find solutions by keywords |
+| `search_by_error_sync` | Error-specific search | Debug error messages |
+| `get_question_sync` | Get question by ID | Retrieve specific Q&A |
+| `analyze_stack_trace_sync` | Parse stack traces | Analyze runtime errors |
+| `advanced_search_sync` | Multi-criteria search | Complex filtering needs |
+
+### Example AI Prompts
+```
+🤖 "Search Stack Overflow for Django pagination best practices"
+🤖 "Find solutions for TypeError: NoneType object has no attribute"
+🤖 "Get the famous sorting performance question from Stack Overflow"
+🤖 "Analyze this JavaScript error: ReferenceError: useState is not defined"
+```
+
+---
+
+## 🏆 **HACKATHON HIGHLIGHTS**
+
+### 🌟 **Innovation Points**
+- **Dual Interface**: Both beautiful web UI and powerful MCP server
+- **Specialized Search**: 5 different search strategies for different use cases
+- **Real-world Utility**: Solves actual developer problems daily
+- **AI-Ready**: Immediate integration with AI assistants
+
+### 🎯 **Technical Excellence**
+- **Modern Stack**: Latest Gradio, FastMCP, UV package manager
+- **Async Architecture**: Non-blocking operations for scalability
+- **Rate Limiting**: Responsible API usage with built-in throttling
+- **Error Handling**: Graceful degradation and user feedback
+
+### 🚀 **User Experience**
+- **Zero Learning Curve**: Intuitive interface with guided examples
+- **Instant Results**: Fast search with formatted output
+- **Multiple Formats**: Both human-readable and machine-parseable output
+- **Progressive Enhancement**: Works great standalone, amazing with AI
+
+### 🔧 **Production Ready**
+- **Public Deployment**: Live demo with sharing links
+- **MCP Compliance**: Full protocol implementation
+- **Extensible Design**: Easy to add new search methods
+- **Documentation**: Comprehensive guides and examples
+
+---
+
+## 📊 **IMPACT & VALUE**
+
+### For Developers
+- **Time Saving**: Quickly find high-quality solutions
+- **Better Search**: Specialized search for different problem types
+- **Quality Filtering**: Focus on accepted answers and high scores
+
+### For AI Assistants
+- **Enhanced Capabilities**: Access to Stack Overflow's knowledge base
+- **Context-Aware**: Specialized tools for different coding scenarios
+- **Reliable Source**: Authoritative programming content
+
+### For the MCP Ecosystem
+- **Reference Implementation**: Shows best practices for MCP servers
+- **Real-world Use Case**: Practical demonstration of MCP value
+- **Community Contribution**: Open source for others to learn from
+
+---
+
+## 🎉 **FINAL RESULT**
+
+**✅ Working Gradio App**: [https://c44b366466c774a9d5.gradio.live](https://c44b366466c774a9d5.gradio.live)
+
+**✅ Live MCP Server**: `https://c44b366466c774a9d5.gradio.live/gradio_api/mcp/sse`
+
+**✅ 5 Search Methods**: General, Error, Question, Stack Trace, Advanced
+
+**✅ Beautiful Interface**: Modern, intuitive, example-driven
+
+**✅ MCP Integration**: Claude Desktop ready with full tool suite
+
+**✅ Production Quality**: Error handling, rate limiting, documentation
+
+---
+
+## 🚀 **TRY IT NOW**
+
+1. **Web Interface**: Visit [the live demo](https://c44b366466c774a9d5.gradio.live)
+2. **Click Examples**: Try the quick example buttons
+3. **Test Different Tabs**: Explore all 5 search methods
+4. **MCP Integration**: Add to Claude Desktop with provided config
+5. **AI Prompts**: Use the example prompts with Claude
+
+---
+
+**🏆 Built with ❤️ for the MCP Hackathon - Demonstrating the power of beautiful interfaces combined with powerful MCP server capabilities!**
+
+*The future of developer tools is AI-assisted, and this project shows how MCP makes that seamless.*

HACKATHON_DEMO.md

@@ -0,0 +1,163 @@
+# 🏆 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://a6f742bf182e4bae9b.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*

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Veritax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,12 +1,330 @@
 ---
-title: Stack Overflow MCP Server
-emoji: 🌍
-colorFrom: pink
-colorTo: green
+title: Stack_Overflow_MCP_Server
+app_file: app.py
 sdk: gradio
 sdk_version: 5.33.1
-app_file: app.py
-pinned: false
 ---
+# <div align="center">Stack Overflow MCP Server</div>
+
+<div align="center">
+
+[![Python Version][python-badge]][python-url]
+[![License][license-badge]][license-url]
+
+</div>
+
+This [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server enables AI assistants like Claude to search and access Stack Overflow content through a standardized protocol, providing seamless access to programming solutions, error handling, and technical knowledge.
+
+> [!NOTE]
+>
+> The Stack Overflow MCP Server is currently in Beta. We welcome your feedback and encourage you to report any bugs by opening an issue.
+
+## Features
+
+- 🔍 **Multiple Search Methods**: Search by query, error message, or specific question ID
+- 📊 **Advanced Filtering**: Filter results by tags, score, accepted answers, and more
+- 🧩 **Stack Trace Analysis**: Parse and find solutions for error stack traces
+- 📝 **Rich Formatting**: Get results in Markdown or JSON format
+- 💬 **Comments Support**: Optionally include question and answer comments
+- ⚡ **Rate Limiting**: Built-in protection to respect Stack Exchange API quotas
+
+### Example Prompts and Use Cases
+
+Here are some example prompts you can use with Claude when the Stack Overflow MCP server is integrated:
+
+| Tool                  | Example Prompt                                                                       | Description                                                                      |
+| --------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| `search_by_query`     | "Search Stack Overflow for Django pagination best practices"                         | Finds the most relevant questions and answers about Django pagination techniques |
+| `search_by_query`     | "Find Python asyncio examples with tags python and asyncio"                          | Searches for specific code examples filtering by multiple tags                   |
+| `search_by_error`     | "Why am I getting 'TypeError: object of type 'NoneType' has no len()' in Python?"    | Finds solutions for a common Python error                                        |
+| `get_question`        | "Get Stack Overflow question 53051465 about React hooks"                             | Retrieves a specific question by ID, including all answers                       |
+| `analyze_stack_trace` | "Fix this error: ReferenceError: useState is not defined at Component in javascript" | Analyzes JavaScript error to find relevant solutions                             |
+| `advanced_search`     | "Find highly rated answers about memory leaks in C++ with at least 10 upvotes"       | Uses advanced filtering to find high-quality answers                             |
+
+## Prerequisites
+
+Before using this MCP server, you need to:
+
+1. Get a Stack Exchange API key (see below)
+2. Have Python 3.10+ installed
+3. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended)
+
+### Getting a Stack Exchange API Key
+
+To use this server effectively, you'll need a Stack Exchange API key:
+
+1. Go to [Stack Apps OAuth Registration](https://stackapps.com/apps/oauth/register)
+2. Fill out the form with your application details:
+   - Name: "Stack Overflow MCP" (or your preferred name)
+   - Description: "MCP server for accessing Stack Overflow"
+   - OAuth Domain: "localhost" (for local usage)
+   - Application Website: Your website or leave blank
+3. Submit the form
+4. Copy your API Key (shown as "Key" on the next page)
+
+This API key is not considered a secret and may be safely embedded in client-side code or distributed binaries. It simply allows you to receive a higher request quota when making requests to the Stack Exchange API.
+
+## Installation
+
+### Installing from PyPI
+
+[Stackoverflow PyPI page](https://pypi.org/project/stackoverflow-mcp/0.1.3/)
+
+```bash
+# Using pip
+pip install stackoverflow-mcp
+
+# OR Using uv
+uv venv
+uv pip install stackoverflow-mcp
+
+# OR using uv wihtout an venv
+uv pip install stackoverflow-mcp --system
+```
+
+### Installing from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/stackoverflow-mcp-server.git
+cd stackoverflow-mcp-server
+
+# Install with uv
+uv venv
+uv pip install -e .
+```
+
+### Adding to Claude Desktop
+
+To run the Stack Overflow MCP server with Claude Desktop:
+
+1. Download [Claude Desktop](https://claude.ai/download).
+
+2. Launch Claude and navigate to: Settings > Developer > Edit Config.
+
+3. Update your `claude_desktop_config.json` file with the following configuration:
+
+```json
+{
+  "mcpServers": {
+    "stack-overflow": {
+      "command": "uv",
+      "args": ["run", "-m", "stackoverflow_mcp"],
+      "env": {
+        "STACK_EXCHANGE_API_KEY": "your_API_key"
+      }
+    }
+  }
+}
+```
+
+You can also specify a custom directory:
+
+```json
+{
+  "mcpServers": {
+    "stack-overflow": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/stackoverflow-mcp-server",
+        "run",
+        "main.py"
+      ],
+      "env": {
+        "STACK_EXCHANGE_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+The server can be configured using these environment variables:
+
+```bash
+# Required
+STACK_EXCHANGE_API_KEY=your_api_key_here
+
+# Optional
+MAX_REQUEST_PER_WINDOW=30     # Maximum requests per rate limit window
+RATE_LIMIT_WINDOW_MS=60000    # Rate limit window in milliseconds (1 minute)
+RETRY_AFTER_MS=2000           # Delay after hitting rate limit
+```
+
+### Using a .env File
+
+You can create a `.env` file in the project root:
+
+```
+STACK_EXCHANGE_API_KEY=your_api_key_here
+MAX_REQUEST_PER_WINDOW=30
+RATE_LIMIT_WINDOW_MS=60000
+RETRY_AFTER_MS=2000
+```
+
+## Usage
+
+### Available Tools
+
+The Stack Overflow MCP server provides the following tools:
+
+#### 1. search_by_query
+
+Search Stack Overflow for questions matching a query.
+
+```
+Parameters:
+- query: The search query
+- tags: Optional list of tags to filter by (e.g., ["python", "pandas"])
+- excluded_tags: Optional list of tags to exclude
+- min_score: Minimum score threshold for questions
+- has_accepted_answer: Whether questions must have an accepted answer
+- include_comments: Whether to include comments in results
+- response_format: Format of response ("json" or "markdown")
+- limit: Maximum number of results to return
+```
+
+#### 2. search_by_error
+
+Search Stack Overflow for solutions to an error message.
+
+```
+Parameters:
+- error_message: The error message to search for
+- language: Programming language (e.g., "python", "javascript")
+- technologies: Related technologies (e.g., ["react", "django"])
+- min_score: Minimum score threshold for questions
+- include_comments: Whether to include comments in results
+- response_format: Format of response ("json" or "markdown")
+- limit: Maximum number of results to return
+```
+
+#### 3. get_question
+
+Get a specific Stack Overflow question by ID.
+
+```
+Parameters:
+- question_id: The Stack Overflow question ID
+- include_comments: Whether to include comments in results
+- response_format: Format of response ("json" or "markdown")
+```
+
+#### 4. analyze_stack_trace
+
+Analyze a stack trace and find relevant solutions on Stack Overflow.
+
+```
+Parameters:
+- stack_trace: The stack trace to analyze
+- language: Programming language of the stack trace
+- include_comments: Whether to include comments in results
+- response_format: Format of response ("json" or "markdown")
+- limit: Maximum number of results to return
+```
+
+#### 5. advanced_search
+
+Advanced search for Stack Overflow questions with many filter options.
+
+```
+Parameters:
+- query: Free-form search query
+- tags: List of tags to filter by
+- excluded_tags: List of tags to exclude
+- min_score: Minimum score threshold
+- title: Text that must appear in the title
+- body: Text that must appear in the body
+- answers: Minimum number of answers
+- has_accepted_answer: Whether questions must have an accepted answer
+- sort_by: Field to sort by (activity, creation, votes, relevance)
+- include_comments: Whether to include comments in results
+- response_format: Format of response ("json" or "markdown")
+- limit: Maximum number of results to return
+```
+
+## Development
+
+This section is for contributors who want to develop or extend the Stack Overflow MCP server.
+
+### Setting Up Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/stackoverflow-mcp-server.git
+cd stackoverflow-mcp-server
+
+# Install dev dependencies
+uv pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test modules
+pytest tests/test_formatter.py
+pytest tests/test_server.py
+
+# Run tests with coverage report
+pytest --cov=stackoverflow_mcp
+```
+
+### Project Structure
+
+```
+stackoverflow-mcp-server/
+├── stackoverflow_mcp/          # Main package
+│   ├── __init__.py
+|   |── __main__.py             # Entry point
+│   ├── api.py                  # Stack Exchange API client
+│   ├── env.py                  # Environment configuration
+│   ├── formatter.py            # Response formatting utilities
+│   ├── server.py               # MCP server implementation
+│   └── types.py                # Data classes
+├── tests/                      # Test suite
+│   ├── api/
+│   │   └── test_search.py      # API search tests
+│   ├── test_formatter.py       # Formatter tests
+│   ├── test_general_api_health.py  # API health tests
+│   └── test_server.py          # Server tests
+├── pyproject.toml              # Package configuration
+├── api_query.py                # testing stackexchange outside of MCP context
+├── LICENSE                     # License file
+└── README.md                   # This file
+```
+
+## Contributing
+
+Contributions are welcome! Here's how you can contribute:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Commit your changes: `git commit -am 'Add new feature'`
+4. Push to the branch: `git push origin feature/my-feature`
+5. Submit a pull request
+
+Please make sure to update tests as appropriate and follow the project's coding style.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+---
+
+<p align="center">
+Stack Overflow MCP Server: AI-accessible programming knowledge
+</p>
+
+<!-- Badges -->
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+[python-badge]: https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg
+[python-url]: https://www.python.org/downloads/
+[license-badge]: https://img.shields.io/badge/license-MIT-green.svg
+[license-url]: LICENSE

README_SPACES.md

@@ -0,0 +1,52 @@
+---
+title: Stack Overflow MCP Server
+emoji: 🔍
+colorFrom: orange
+colorTo: purple
+sdk: gradio
+sdk_version: "5.33.1"
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# Stack Overflow MCP Server 🚀
+
+A powerful Gradio app that serves as both a web interface and MCP (Model Context Protocol) server for Stack Overflow search capabilities.
+
+## 🌟 Features
+
+- **Web Interface**: Interactive search with 5 specialized tabs
+- **MCP Server**: Expose 5 MCP tools for AI assistants
+- **API Key Support**: Add your Stack Exchange API key for higher quotas
+- **Real-time Search**: Fast and accurate Stack Overflow searches
+
+## 🔧 MCP Integration
+
+This app serves as an MCP server at the `/gradio_api/mcp/sse` endpoint. Connect your AI assistant using:
+
+```json
+{
+  "mcpServers": {
+    "stackoverflow": {
+      "url": "https://YOUR_SPACE_URL/gradio_api/mcp/sse"
+    }
+  }
+}
+```
+
+## 🎯 Available MCP Tools
+
+1. **search_by_query_sync** - General Stack Overflow search
+2. **search_by_error_sync** - Error-specific search  
+3. **get_question_sync** - Get specific question by ID
+4. **analyze_stack_trace_sync** - Analyze stack traces
+5. **advanced_search_sync** - Advanced search with filters
+
+## 💡 Usage
+
+1. **Web Interface**: Use the tabs to search Stack Overflow
+2. **MCP Server**: Connect AI assistants to the MCP endpoint
+3. **API Key**: Add your Stack Exchange API key for 10,000 requests/day
+
+Built with ❤️ for the MCP Hackathon

api_query.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""
+Stack Exchange API Query Tool
+
+This script allows you to directly call the Stack Exchange API with various parameters
+and see the results. It's useful for testing queries and seeing the raw results.
+
+Usage:
+    python api_query.py search "python pandas dataframe" --tags python,pandas --min-score 10
+    python api_query.py question 12345
+    python api_query.py error "TypeError: cannot use a string pattern" --language python
+"""
+
+import os
+import sys
+import json
+import asyncio
+import argparse
+from dotenv import load_dotenv
+
+from stackoverflow_mcp.api import StackExchangeAPI
+from stackoverflow_mcp.formatter import format_response
+
+
+def setup_environment():
+    """Load environment variables from .env file"""
+    if os.path.exists(".env"):
+        load_dotenv(".env")
+    elif os.path.exists(".env.test"):
+        load_dotenv(".env.test")
+    else:
+        print("Warning: No .env or .env.test file found. Using default settings.")
+
+
+async def run_search_query(api, args):
+    """Run a search query with the given arguments"""
+    tags = args.tags.split(',') if args.tags else None
+    
+    excluded_tags = args.excluded_tags.split(',') if args.excluded_tags else None
+    
+    print(f"\nRunning search query: '{args.query}'")
+    if args.title:
+        print(f"Running search with title containing: '{args.title}'")
+    if args.body:
+        print(f"Running search with body containing: '{args.body}'")
+    print(f"Tags: {tags}")
+    print(f"Excluded tags: {excluded_tags}")
+    print(f"Min score: {args.min_score}")
+    print(f"Limit: {args.limit}")
+    print(f"Include comments: {args.comments}\n")
+    
+    try:
+        results = await api.search_by_query(
+            query=args.query,
+            tags=tags,
+            title=args.title,
+            body=args.body,
+            excluded_tags=excluded_tags,
+            min_score=args.min_score,
+            limit=args.limit,
+            include_comments=args.comments
+        )
+        
+        print(f"Found {len(results)} results")
+        
+        if args.raw:
+            for i, result in enumerate(results):
+                print(f"\n--- Result {i+1} ---")
+                print(f"Question ID: {result.question.question_id}")
+                print(f"Title: {result.question.title}")
+                print(f"Score: {result.question.score}")
+                print(f"Tags: {result.question.tags}")
+                print(f"Link: {result.question.link}")
+                print(f"Answers: {len(result.answers)}")
+                if result.comments:
+                    print(f"Question comments: {len(result.comments.question)}")
+        else:
+            formatted = format_response(results, args.format)
+            print(formatted)
+        
+    except Exception as e:
+        print(f"Error during search: {str(e)}")
+
+
+async def run_question_query(api, args):
+    """Get a specific question by ID"""
+    try:
+        print(f"\nFetching question ID: {args.question_id}")
+        print(f"Include comments: {args.comments}\n")
+        
+        result = await api.get_question(
+            question_id=args.question_id,
+            include_comments=args.comments
+        )
+        
+        if args.raw:
+            print(f"Question ID: {result.question.question_id}")
+            print(f"Title: {result.question.title}")
+            print(f"Score: {result.question.score}")
+            print(f"Tags: {result.question.tags}")
+            print(f"Link: {result.question.link}")
+            print(f"Answers: {len(result.answers)}")
+            if result.comments:
+                print(f"Question comments: {len(result.comments.question)}")
+        else:
+            formatted = format_response([result], args.format)
+            print(formatted)
+        
+    except Exception as e:
+        print(f"Error fetching question: {str(e)}")
+
+
+async def run_error_query(api, args):
+    """Search for an error message with optional language filter"""
+    technologies = args.technologies.split(',') if args.technologies else None
+    
+    try:
+        print(f"\nSearching for error: '{args.error}'")
+        print(f"Language: {args.language}")
+        print(f"Technologies: {technologies}")
+        if args.title:
+            print(f"Title containing: '{args.title}'")
+        if args.body:
+            print(f"Body containing: '{args.body}'")
+        print(f"Min score: {args.min_score}")
+        print(f"Limit: {args.limit}")
+        print(f"Include comments: {args.comments}\n")
+        
+        tags = []
+        if args.language:
+            tags.append(args.language.lower())
+        if technologies:
+            tags.extend([t.lower() for t in technologies])
+        
+        results = await api.search_by_query(
+            query=args.error,
+            title=args.title,
+            body=args.body,
+            tags=tags if tags else None,
+            min_score=args.min_score,
+            limit=args.limit,
+            include_comments=args.comments
+        )
+        
+        print(f"Found {len(results)} results")
+        
+        if args.raw:
+            for i, result in enumerate(results):
+                print(f"\n--- Result {i+1} ---")
+                print(f"Question ID: {result.question.question_id}")
+                print(f"Title: {result.question.title}")
+                print(f"Score: {result.question.score}")
+                print(f"Tags: {result.question.tags}")
+                print(f"Link: {result.question.link}")
+                print(f"Answers: {len(result.answers)}")
+                if result.comments:
+                    print(f"Question comments: {len(result.comments.question)}")
+        else:
+            formatted = format_response(results, args.format)
+            print(formatted)
+        
+    except Exception as e:
+        print(f"Error searching for error: {str(e)}")
+
+
+async def main():
+    """Parse arguments and run the appropriate query"""
+    parser = argparse.ArgumentParser(description="Stack Exchange API Query Tool")
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+    
+    # Search command
+    search_parser = subparsers.add_parser("search", help="Search Stack Overflow")
+    search_parser.add_argument("query", help="Search query")
+    search_parser.add_argument("--tags", help="Comma-separated list of tags")
+    search_parser.add_argument("--title", help="Word(s) that must appear in the question title")
+    search_parser.add_argument("--body", help="Word(s) that must appear in the body of the question")
+    search_parser.add_argument("--excluded-tags", help="Comma-separated list of tags to exclude")
+    search_parser.add_argument("--min-score", type=int, default=0, help="Minimum score")
+    search_parser.add_argument("--limit", type=int, default=5, help="Maximum number of results")
+    search_parser.add_argument("--comments", action="store_true", help="Include comments")
+    search_parser.add_argument("--format", choices=["markdown", "json"], default="markdown", help="Output format")
+    search_parser.add_argument("--raw", action="store_true", help="Print raw data structure")
+    
+    # Question command
+    question_parser = subparsers.add_parser("question", help="Get a specific question")
+    question_parser.add_argument("question_id", type=int, help="Question ID")
+    question_parser.add_argument("--comments", action="store_true", help="Include comments")
+    question_parser.add_argument("--format", choices=["markdown", "json"], default="markdown", help="Output format")
+    question_parser.add_argument("--raw", action="store_true", help="Print raw data structure")
+    
+    # Error command
+    error_parser = subparsers.add_parser("error", help="Search for an error message")
+    error_parser.add_argument("error", help="Error message")
+    error_parser.add_argument("--title", help="Word(s) that must appear in the question title")
+    error_parser.add_argument("--body", help="Word(s) that must appear in the body of the question")
+    error_parser.add_argument("--language", help="Programming language")
+    error_parser.add_argument("--technologies", help="Comma-separated list of technologies")
+    error_parser.add_argument("--min-score", type=int, default=0, help="Minimum score")
+    error_parser.add_argument("--limit", type=int, default=5, help="Maximum number of results")
+    error_parser.add_argument("--comments", action="store_true", help="Include comments")
+    error_parser.add_argument("--format", choices=["markdown", "json"], default="markdown", help="Output format")
+    error_parser.add_argument("--raw", action="store_true", help="Print raw data structure")
+    
+    args = parser.parse_args()
+    
+    if not args.command:
+        parser.print_help()
+        return 1
+    
+    setup_environment()
+    
+    api_key = os.getenv("STACK_EXCHANGE_API_KEY")
+    
+    if not api_key:
+        print("Warning: No API key found. Requests may be rate limited.")
+    
+    api = StackExchangeAPI(api_key=api_key)
+    
+    try:
+        if args.command == "search":
+            await run_search_query(api, args)
+        elif args.command == "question":
+            await run_question_query(api, args)
+        elif args.command == "error":
+            await run_error_query(api, args)
+        
+    except Exception as e:
+        print(f"Error: {str(e)}")
+        return 1
+        
+    finally:
+        await api.close()
+    
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(main()))

app.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""
+Stack Overflow MCP Server - Hugging Face Spaces App
+A web interface and MCP server that provides Stack Overflow search capabilities.
+"""
+
+# Import everything from the main gradio_app
+from gradio_app import *
+
+if __name__ == "__main__":
+    # Launch the app for Hugging Face Spaces
+    demo.launch(
+        mcp_server=True,
+        server_name="0.0.0.0",
+        server_port=7860,
+        show_error=True,
+        share=False
+    )

demo_mcp_client.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""
+MCP Client Demo for Stack Overflow Server
+Demonstrates how to interact with the Stack Overflow MCP server programmatically.
+"""
+
+import asyncio
+import json
+from typing import Dict, Any
+
+# This is a demonstration of how an MCP client would interact with our server
+# In practice, you would use a proper MCP client library
+
+async def demo_mcp_calls():
+    """
+    Demonstrate various MCP calls to the Stack Overflow server.
+    This simulates what an AI assistant like Claude would do.
+    """
+    
+    print("🤖 Stack Overflow MCP Server Demo")
+    print("=" * 50)
+    
+    # Demo 1: General Search
+    print("\n1️⃣ GENERAL SEARCH DEMO")
+    print("Query: 'Django pagination best practices'")
+    print("Tags: ['python', 'django']")
+    print("Expected: High-quality Django pagination solutions")
+    
+    # Demo 2: Error Search  
+    print("\n2️⃣ ERROR SEARCH DEMO")
+    print("Error: 'TypeError: NoneType object has no attribute'")
+    print("Language: Python")
+    print("Expected: Common solutions for NoneType errors")
+    
+    # Demo 3: Question Retrieval
+    print("\n3️⃣ QUESTION RETRIEVAL DEMO")
+    print("Question ID: 11227809")
+    print("Expected: Famous 'Why is processing a sorted array faster?' question")
+    
+    # Demo 4: Stack Trace Analysis
+    print("\n4️⃣ STACK TRACE ANALYSIS DEMO")
+    print("Stack Trace: 'ReferenceError: useState is not defined'")
+    print("Language: JavaScript")
+    print("Expected: React hooks solutions")
+    
+    # Demo 5: Advanced Search
+    print("\n5️⃣ ADVANCED SEARCH DEMO")
+    print("Query: 'memory optimization'")
+    print("Tags: ['c++', 'performance']")
+    print("Min Score: 50")
+    print("Expected: High-quality C++ performance answers")
+    
+    print("\n" + "=" * 50)
+    print("🎯 All demos completed!")
+    print("💡 These are the types of searches our MCP server can handle")
+    print("🚀 Try them in the web interface or via MCP client!")
+
+def demo_gradio_api_calls():
+    """
+    Demonstrate how the Gradio API exposes the MCP functionality.
+    """
+    
+    print("\n🎨 GRADIO API INTEGRATION")
+    print("=" * 50)
+    
+    # Show the available API endpoints
+    api_endpoints = {
+        "search_by_query_sync": {
+            "description": "General Stack Overflow search",
+            "inputs": ["query", "tags", "min_score", "has_accepted_answer", "limit", "response_format"],
+            "example": {
+                "query": "Django pagination best practices",
+                "tags": "python,django", 
+                "min_score": 5,
+                "has_accepted_answer": True,
+                "limit": 5,
+                "response_format": "markdown"
+            }
+        },
+        "search_by_error_sync": {
+            "description": "Error-specific search",
+            "inputs": ["error_message", "language", "technologies", "min_score", "has_accepted_answer", "limit", "response_format"],
+            "example": {
+                "error_message": "TypeError: 'NoneType' object has no attribute",
+                "language": "python",
+                "technologies": "flask,sqlalchemy",
+                "min_score": 0,
+                "has_accepted_answer": True,
+                "limit": 5,
+                "response_format": "markdown"
+            }
+        },
+        "get_question_sync": {
+            "description": "Get specific question by ID",
+            "inputs": ["question_id", "include_comments", "response_format"],
+            "example": {
+                "question_id": "11227809",
+                "include_comments": True,
+                "response_format": "markdown"  
+            }
+        },
+        "analyze_stack_trace_sync": {
+            "description": "Analyze stack traces",
+            "inputs": ["stack_trace", "language", "min_score", "has_accepted_answer", "limit", "response_format"],
+            "example": {
+                "stack_trace": "ReferenceError: useState is not defined\n    at Component.render",
+                "language": "javascript",
+                "min_score": 5,
+                "has_accepted_answer": True,
+                "limit": 3,
+                "response_format": "markdown"
+            }
+        },
+        "advanced_search_sync": {
+            "description": "Advanced search with comprehensive filters",
+            "inputs": ["query", "tags", "excluded_tags", "min_score", "title", "body", "min_answers", "has_accepted_answer", "min_views", "sort_by", "limit", "response_format"],
+            "example": {
+                "query": "memory optimization",
+                "tags": "c++,performance",
+                "excluded_tags": "beginner",
+                "min_score": 50,
+                "title": "",
+                "body": "",
+                "min_answers": 1,
+                "has_accepted_answer": False,
+                "min_views": 1000,
+                "sort_by": "votes",
+                "limit": 5,
+                "response_format": "markdown"
+            }
+        }
+    }
+    
+    for endpoint, info in api_endpoints.items():
+        print(f"\n🔧 {endpoint}")
+        print(f"   📝 {info['description']}")
+        print(f"   📊 Example:")
+        for key, value in info['example'].items():
+            print(f"      {key}: {value}")
+
+def demo_mcp_integration():
+    """
+    Show how to integrate with MCP clients like Claude Desktop.
+    """
+    
+    print("\n🔗 MCP CLIENT INTEGRATION")
+    print("=" * 50)
+    {
+
+}
+    
+    claude_config = {
+         "mcpServers": {
+    "stackoverflow": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://c44b366466c774a9d5.gradio.live/gradio_api/mcp/sse"
+      ]
+    }
+  }
+    }
+    
+    print("💻 Claude Desktop Configuration:")
+    print(json.dumps(claude_config, indent=2))
+    
+    print("\n🤖 Example AI Assistant Prompts:")
+    prompts = [
+        "Search Stack Overflow for Django pagination best practices",
+        "Find solutions for the error 'TypeError: NoneType object has no attribute'",
+        "Get Stack Overflow question 11227809",
+        "Analyze this JavaScript error: ReferenceError: useState is not defined", 
+        "Find high-scored C++ memory optimization questions"
+    ]
+    
+    for i, prompt in enumerate(prompts, 1):
+        print(f"   {i}. {prompt}")
+
+if __name__ == "__main__":
+    print("🚀 Starting Stack Overflow MCP Server Demo...")
+    
+    # Run the async demo
+    asyncio.run(demo_mcp_calls())
+    
+    # Show Gradio API integration
+    demo_gradio_api_calls()
+    
+    # Show MCP client integration
+    demo_mcp_integration()
+    
+    print("\n🎯 Demo completed! Visit the web interface to try it live:")
+    print("🌐 https://c44b366466c774a9d5.gradio.live")
+    print("🔗 MCP Endpoint: https://c44b366466c774a9d5.gradio.live/gradio_api/mcp/sse")

gradio_app.py

@@ -0,0 +1,810 @@
+#!/usr/bin/env python3
+"""
+Gradio MCP Server for Stack Overflow Search
+A web interface and MCP server that provides Stack Overflow search capabilities.
+"""
+
+import asyncio
+import os
+from typing import List, Optional, Tuple
+import gradio as gr
+from datetime import datetime
+
+from stackoverflow_mcp.api import StackExchangeAPI
+from stackoverflow_mcp.formatter import format_response
+from stackoverflow_mcp.env import STACK_EXCHANGE_API_KEY
+
+# Initialize a default API client (can be overridden with user's key)
+default_api = StackExchangeAPI(api_key=STACK_EXCHANGE_API_KEY)
+
+def get_api_client(api_key: str = "") -> StackExchangeAPI:
+    """Get API client with user's key or fallback to default."""
+    if api_key and api_key.strip():
+        return StackExchangeAPI(api_key=api_key.strip())
+    return default_api
+
+def search_by_query_sync(
+    query: str,
+    tags: str = "",
+    min_score: int = 0,
+    has_accepted_answer: bool = False,
+    limit: int = 5,
+    response_format: str = "markdown",
+    api_key: str = ""
+) -> str:
+    """
+    Search Stack Overflow for questions matching a query.
+
+    Args:
+        query (str): The search query
+        tags (str): Comma-separated list of tags to filter by (e.g., "python,pandas")
+        min_score (int): Minimum score threshold for questions
+        has_accepted_answer (bool): Whether questions must have an accepted answer
+        limit (int): Maximum number of results to return (1-20)
+        response_format (str): Format of response ("json" or "markdown")
+
+    Returns:
+        str: Formatted search results
+    """
+    if not query.strip():
+        return "❌ Please enter a search query."
+    
+    # Convert tags string to list
+    tags_list = [tag.strip() for tag in tags.split(",") if tag.strip()] if tags else None
+    
+    # Limit the range
+    limit = max(1, min(limit, 20))
+    
+    try:
+        # Get API client with user's key
+        api = get_api_client(api_key)
+        
+        # Run the async function safely
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_closed():
+                raise RuntimeError("Event loop is closed")
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+        
+        results = loop.run_until_complete(
+            api.search_by_query(
+                query=query,
+                tags=tags_list,
+                min_score=min_score if min_score > 0 else None,
+                has_accepted_answer=has_accepted_answer if has_accepted_answer else None,
+                limit=limit
+            )
+        )
+        
+        if not results:
+            return f"🔍 No results found for query: '{query}'"
+        
+        return format_response(results, response_format)
+    
+    except Exception as e:
+        return f"❌ Error searching Stack Overflow: {str(e)}"
+
+
+def search_by_error_sync(
+    error_message: str,
+    language: str = "",
+    technologies: str = "",
+    min_score: int = 0,
+    has_accepted_answer: bool = False,
+    limit: int = 5,
+    response_format: str = "markdown",
+    api_key: str = ""
+) -> str:
+    """
+    Search Stack Overflow for solutions to an error message.
+
+    Args:
+        error_message (str): The error message to search for
+        language (str): Programming language (e.g., "python", "javascript")
+        technologies (str): Comma-separated related technologies (e.g., "react,django")
+        min_score (int): Minimum score threshold for questions
+        has_accepted_answer (bool): Whether questions must have an accepted answer
+        limit (int): Maximum number of results to return (1-20)
+        response_format (str): Format of response ("json" or "markdown")
+
+    Returns:
+        str: Formatted search results
+    """
+    if not error_message.strip():
+        return "❌ Please enter an error message."
+    
+    # Build tags list
+    tags = []
+    if language.strip():
+        tags.append(language.strip().lower())
+    if technologies.strip():
+        tags.extend([tech.strip().lower() for tech in technologies.split(",") if tech.strip()])
+    
+    # Limit the range
+    limit = max(1, min(limit, 20))
+    
+    try:
+        # Get API client with user's key
+        api = get_api_client(api_key)
+        
+        # Run the async function safely
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_closed():
+                raise RuntimeError("Event loop is closed")
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+        
+        results = loop.run_until_complete(
+            api.search_by_query(
+                query=error_message,
+                tags=tags if tags else None,
+                min_score=min_score if min_score > 0 else None,
+                has_accepted_answer=has_accepted_answer if has_accepted_answer else None,
+                limit=limit
+            )
+        )
+        
+        if not results:
+            return f"🔍 No results found for error: '{error_message}'"
+        
+        return format_response(results, response_format)
+    
+    except Exception as e:
+        return f"❌ Error searching Stack Overflow: {str(e)}"
+
+
+def get_question_sync(
+    question_id: str,
+    include_comments: bool = True,
+    response_format: str = "markdown",
+    api_key: str = ""
+) -> str:
+    """
+    Get a specific Stack Overflow question by ID.
+
+    Args:
+        question_id (str): The Stack Overflow question ID
+        include_comments (bool): Whether to include comments in results
+        response_format (str): Format of response ("json" or "markdown")
+
+    Returns:
+        str: Formatted question details
+    """
+    if not question_id.strip():
+        return "❌ Please enter a question ID."
+    
+    try:
+        # Convert to int
+        q_id = int(question_id.strip())
+        
+        # Get API client with user's key
+        api = get_api_client(api_key)
+        
+        # Run the async function safely
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_closed():
+                raise RuntimeError("Event loop is closed")
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+        
+        result = loop.run_until_complete(
+            api.get_question(
+                question_id=q_id,
+                include_comments=include_comments
+            )
+        )
+        
+        return format_response([result], response_format)
+    
+    except ValueError:
+        return "❌ Question ID must be a number."
+    except Exception as e:
+        return f"❌ Error fetching question: {str(e)}"
+
+
+def analyze_stack_trace_sync(
+    stack_trace: str,
+    language: str,
+    min_score: int = 0,
+    has_accepted_answer: bool = False,
+    limit: int = 3,
+    response_format: str = "markdown",
+    api_key: str = ""
+) -> str:
+    """
+    Analyze a stack trace and find relevant solutions on Stack Overflow.
+
+    Args:
+        stack_trace (str): The stack trace to analyze
+        language (str): Programming language of the stack trace
+        min_score (int): Minimum score threshold for questions
+        has_accepted_answer (bool): Whether questions must have an accepted answer
+        limit (int): Maximum number of results to return (1-10)
+        response_format (str): Format of response ("json" or "markdown")
+
+    Returns:
+        str: Formatted search results
+    """
+    if not stack_trace.strip():
+        return "❌ Please enter a stack trace."
+    
+    if not language.strip():
+        return "❌ Please specify the programming language."
+    
+    # Limit the range
+    limit = max(1, min(limit, 10))
+    
+    # Extract the first line as the main error
+    error_lines = stack_trace.strip().split("\n")
+    error_message = error_lines[0]
+    
+    try:
+        # Get API client with user's key
+        api = get_api_client(api_key)
+        
+        # Run the async function safely
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_closed():
+                raise RuntimeError("Event loop is closed")
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+        
+        results = loop.run_until_complete(
+            api.search_by_query(
+                query=error_message,
+                tags=[language.strip().lower()],
+                min_score=min_score if min_score > 0 else None,
+                has_accepted_answer=has_accepted_answer if has_accepted_answer else None,
+                limit=limit
+            )
+        )
+        
+        if not results:
+            return f"🔍 No results found for stack trace error: '{error_message}'"
+        
+        return format_response(results, response_format)
+    
+    except Exception as e:
+        return f"❌ Error analyzing stack trace: {str(e)}"
+
+
+def advanced_search_sync(
+    query: str = "",
+    tags: str = "",
+    excluded_tags: str = "",
+    min_score: int = 0,
+    title: str = "",
+    body: str = "",
+    min_answers: int = 0,
+    has_accepted_answer: bool = False,
+    min_views: int = 0,
+    sort_by: str = "votes",
+    limit: int = 5,
+    response_format: str = "markdown",
+    api_key: str = ""
+) -> str:
+    """
+    Advanced search for Stack Overflow questions with comprehensive filters.
+
+    Args:
+        query (str): Free-form search query
+        tags (str): Comma-separated list of tags to filter by
+        excluded_tags (str): Comma-separated list of tags to exclude
+        min_score (int): Minimum score threshold
+        title (str): Text that must appear in the title
+        body (str): Text that must appear in the body
+        min_answers (int): Minimum number of answers
+        has_accepted_answer (bool): Whether questions must have an accepted answer
+        min_views (int): Minimum number of views
+        sort_by (str): Field to sort by (activity, creation, votes, relevance)
+        limit (int): Maximum number of results to return (1-20)
+        response_format (str): Format of response ("json" or "markdown")
+
+    Returns:
+        str: Formatted search results
+    """
+    if not query.strip() and not tags.strip() and not title.strip() and not body.strip():
+        return "❌ Please provide at least one search criteria (query, tags, title, or body)."
+    
+    # Convert tags strings to lists
+    tags_list = [tag.strip() for tag in tags.split(",") if tag.strip()] if tags else None
+    excluded_tags_list = [tag.strip() for tag in excluded_tags.split(",") if tag.strip()] if excluded_tags else None
+    
+    # Limit the range
+    limit = max(1, min(limit, 20))
+    
+    try:
+        # Get API client with user's key
+        api = get_api_client(api_key)
+        
+        # Run the async function safely
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_closed():
+                raise RuntimeError("Event loop is closed")
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+        
+        results = loop.run_until_complete(
+            api.advanced_search(
+                query=query.strip() if query.strip() else None,
+                tags=tags_list,
+                excluded_tags=excluded_tags_list,
+                min_score=min_score if min_score > 0 else None,
+                title=title.strip() if title.strip() else None,
+                body=body.strip() if body.strip() else None,
+                answers=min_answers if min_answers > 0 else None,
+                has_accepted_answer=has_accepted_answer if has_accepted_answer else None,
+                views=min_views if min_views > 0 else None,
+                sort_by=sort_by,
+                limit=limit
+            )
+        )
+        
+        if not results:
+            return "🔍 No results found with the specified criteria."
+        
+        return format_response(results, response_format)
+    
+    except Exception as e:
+        return f"❌ Error performing advanced search: {str(e)}"
+
+
+# Helper functions for example buttons (not exposed as MCP tools)
+def _set_django_example():
+    return ("Django pagination best practices", "python,django", 5, True, 5, "markdown")
+
+def _set_async_example():
+    return ("Python asyncio concurrency patterns", "python,asyncio", 10, True, 5, "markdown")
+
+def _set_react_example():
+    return ("React hooks useState useEffect", "javascript,reactjs", 15, True, 5, "markdown")
+
+def _set_sql_example():
+    return ("SQL INNER JOIN vs LEFT JOIN performance", "sql,join", 20, True, 5, "markdown")
+
+
+# Create the Gradio interface with multiple tabs
+with gr.Blocks(
+    title="Stack Overflow MCP Server",
+    theme=gr.themes.Soft(),
+    css="""
+    .gradio-container {
+        max-width: 1200px !important;
+    }
+    .tab-nav button {
+        font-size: 16px !important;
+    }
+    """
+) as demo:
+    
+    gr.Markdown("""
+    # 🔍 Stack Overflow MCP Server
+    
+    **A powerful interface to search Stack Overflow and analyze programming errors**
+    
+    This application serves as both a web interface and an MCP (Model Context Protocol) server, 
+    allowing AI assistants like Claude to search Stack Overflow programmatically.
+    
+    💡 **MCP Server URL**: Use this URL in your MCP client: `{SERVER_URL}/gradio_api/mcp/sse`
+    
+    ## 🚀 Quick Start Examples
+    
+    Try these example searches to get started:
+    - **General Search**: "Django pagination best practices" with tags "python,django"
+    - **Error Search**: "TypeError: 'NoneType' object has no attribute" in Python
+    - **Question ID**: 11227809 (famous "Why is processing a sorted array faster?" question)
+    - **Stack Trace**: JavaScript TypeError examples
+    - **Advanced**: High-scored Python questions with accepted answers
+    """)
+    
+    # Global API Key Input
+    with gr.Row():
+        with gr.Column(scale=3):
+            gr.Markdown("### 🔑 Stack Exchange API Key (Optional)")
+            gr.Markdown("""
+            **Why provide an API key?**
+            - Higher request quotas (10,000 vs 300 requests/day)
+            - Faster responses and better reliability
+            - API keys are **not secret** - safe to share publicly
+            
+            **How to get one:**
+            1. Visit [Stack Apps OAuth Registration](https://stackapps.com/apps/oauth/register)
+            2. Fill in basic info (name: "Stack Overflow MCP", domain: "localhost")
+            3. Copy your API key from the results page
+            """)
+        
+        with gr.Column(scale=2):
+            api_key_input = gr.Textbox(
+                label="Stack Exchange API Key",
+                placeholder="Enter your API key here (optional)",
+                value="",
+                type="password",
+                info="Optional: Provides higher quotas and better performance"
+            )
+    
+    with gr.Tabs():
+        
+        # Tab 1: General Search
+        with gr.Tab("🔍 General Search", id="search"):
+            gr.Markdown("### Search Stack Overflow by query and filters")
+            
+            with gr.Row():
+                with gr.Column(scale=2):
+                    query_input = gr.Textbox(
+                        label="Search Query",
+                        placeholder="e.g., 'Django pagination best practices'",
+                        value="python list comprehension"
+                    )
+                    
+                with gr.Column(scale=1):
+                    tags_input = gr.Textbox(
+                        label="Tags (comma-separated)",
+                        placeholder="e.g., python,pandas",
+                        value=""
+                    )
+            
+            with gr.Row():
+                min_score_input = gr.Slider(
+                    label="Minimum Score",
+                    minimum=0,
+                    maximum=100,
+                    value=0,
+                    step=1
+                )
+                
+                has_accepted_input = gr.Checkbox(
+                    label="Must have accepted answer",
+                    value=False
+                )
+                
+                limit_input = gr.Slider(
+                    label="Number of Results",
+                    minimum=1,
+                    maximum=20,
+                    value=5,
+                    step=1
+                )
+                
+                format_input = gr.Dropdown(
+                    label="Response Format",
+                    choices=["markdown", "json"],
+                    value="markdown"
+                )
+            
+            search_btn = gr.Button("🔍 Search", variant="primary", size="lg")
+            
+            # Example buttons
+            with gr.Row():
+                gr.Markdown("**Quick Examples:**")
+            with gr.Row():
+                example1_btn = gr.Button("Django Pagination", size="sm")
+                example2_btn = gr.Button("Python Async", size="sm") 
+                example3_btn = gr.Button("React Hooks", size="sm")
+                example4_btn = gr.Button("SQL JOIN", size="sm")
+            
+            # Example button click handlers
+            example1_btn.click(
+                lambda: ("Django pagination best practices", "python,django", 5, True, 5, "markdown"),
+                outputs=[query_input, tags_input, min_score_input, has_accepted_input, limit_input, format_input]
+            )
+            example2_btn.click(
+                lambda: ("Python asyncio concurrency patterns", "python,asyncio", 10, True, 5, "markdown"),
+                outputs=[query_input, tags_input, min_score_input, has_accepted_input, limit_input, format_input]
+            )
+            example3_btn.click(
+                lambda: ("React hooks useState useEffect", "javascript,reactjs", 15, True, 5, "markdown"),
+                outputs=[query_input, tags_input, min_score_input, has_accepted_input, limit_input, format_input]
+            )
+            example4_btn.click(
+                lambda: ("SQL INNER JOIN vs LEFT JOIN performance", "sql,join", 20, True, 5, "markdown"),
+                outputs=[query_input, tags_input, min_score_input, has_accepted_input, limit_input, format_input]
+            )
+            
+            search_output = gr.Markdown(label="Search Results", height=400)
+            
+            search_btn.click(
+                fn=search_by_query_sync,
+                inputs=[query_input, tags_input, min_score_input, has_accepted_input, limit_input, format_input, api_key_input],
+                outputs=search_output
+            )
+        
+        # Tab 2: Error Search
+        with gr.Tab("🐛 Error Search", id="error"):
+            gr.Markdown("### Find solutions for specific error messages")
+            
+            with gr.Row():
+                with gr.Column(scale=2):
+                    error_input = gr.Textbox(
+                        label="Error Message",
+                        placeholder="e.g., 'TypeError: object of type 'NoneType' has no len()'",
+                        value="TypeError: 'NoneType' object has no attribute"
+                    )
+                
+                with gr.Column(scale=1):
+                    language_input = gr.Textbox(
+                        label="Programming Language",
+                        placeholder="e.g., python",
+                        value="python"
+                    )
+            
+            tech_input = gr.Textbox(
+                label="Related Technologies (comma-separated)",
+                placeholder="e.g., django,flask",
+                value=""
+            )
+            
+            with gr.Row():
+                error_min_score = gr.Slider(
+                    label="Minimum Score",
+                    minimum=0,
+                    maximum=100,
+                    value=0,
+                    step=1
+                )
+                
+                error_accepted = gr.Checkbox(
+                    label="Must have accepted answer",
+                    value=True
+                )
+                
+                error_limit = gr.Slider(
+                    label="Number of Results",
+                    minimum=1,
+                    maximum=20,
+                    value=5,
+                    step=1
+                )
+                
+                error_format = gr.Dropdown(
+                    label="Response Format",
+                    choices=["markdown", "json"],
+                    value="markdown"
+                )
+            
+            error_search_btn = gr.Button("🐛 Search for Solutions", variant="primary", size="lg")
+            error_output = gr.Markdown(label="Error Solutions", height=400)
+            
+            error_search_btn.click(
+                fn=search_by_error_sync,
+                inputs=[error_input, language_input, tech_input, error_min_score, error_accepted, error_limit, error_format, api_key_input],
+                outputs=error_output
+            )
+        
+        # Tab 3: Get Specific Question
+        with gr.Tab("📄 Get Question", id="question"):
+            gr.Markdown("### Retrieve a specific Stack Overflow question by ID")
+            
+            with gr.Row():
+                question_id_input = gr.Textbox(
+                    label="Question ID",
+                    placeholder="e.g., 11227809",
+                    value="11227809"
+                )
+                
+                question_comments = gr.Checkbox(
+                    label="Include Comments",
+                    value=True
+                )
+                
+                question_format = gr.Dropdown(
+                    label="Response Format",
+                    choices=["markdown", "json"],
+                    value="markdown"
+                )
+            
+            question_btn = gr.Button("📄 Get Question", variant="primary", size="lg")
+            question_output = gr.Markdown(label="Question Details", height=400)
+            
+            question_btn.click(
+                fn=get_question_sync,
+                inputs=[question_id_input, question_comments, question_format, api_key_input],
+                outputs=question_output
+            )
+        
+        # Tab 4: Stack Trace Analysis
+        with gr.Tab("📊 Stack Trace Analysis", id="trace"):
+            gr.Markdown("### Analyze stack traces and find relevant solutions")
+            
+            stack_trace_input = gr.Textbox(
+                label="Stack Trace",
+                placeholder="Paste your full stack trace here...",
+                lines=8,
+                value="TypeError: Cannot read property 'length' of undefined\n    at Array.map (<anonymous>)\n    at Component.render (app.js:42:18)"
+            )
+            
+            with gr.Row():
+                trace_language = gr.Textbox(
+                    label="Programming Language",
+                    placeholder="e.g., javascript",
+                    value="javascript"
+                )
+                
+                trace_min_score = gr.Slider(
+                    label="Minimum Score",
+                    minimum=0,
+                    maximum=100,
+                    value=5,
+                    step=1
+                )
+                
+                trace_accepted = gr.Checkbox(
+                    label="Must have accepted answer",
+                    value=True
+                )
+                
+                trace_limit = gr.Slider(
+                    label="Number of Results",
+                    minimum=1,
+                    maximum=10,
+                    value=3,
+                    step=1
+                )
+                
+                trace_format = gr.Dropdown(
+                    label="Response Format",
+                    choices=["markdown", "json"],
+                    value="markdown"
+                )
+            
+            trace_btn = gr.Button("📊 Analyze Stack Trace", variant="primary", size="lg")
+            trace_output = gr.Markdown(label="Stack Trace Analysis", height=400)
+            
+            trace_btn.click(
+                fn=analyze_stack_trace_sync,
+                inputs=[stack_trace_input, trace_language, trace_min_score, trace_accepted, trace_limit, trace_format, api_key_input],
+                outputs=trace_output
+            )
+        
+        # Tab 5: Advanced Search
+        with gr.Tab("⚙️ Advanced Search", id="advanced"):
+            gr.Markdown("### Advanced search with comprehensive filtering options")
+            
+            with gr.Row():
+                with gr.Column():
+                    adv_query_input = gr.Textbox(
+                        label="Search Query (optional)",
+                        placeholder="e.g., 'memory management'",
+                        value=""
+                    )
+                    
+                    adv_title_input = gr.Textbox(
+                        label="Title Contains (optional)",
+                        placeholder="Text that must appear in the title",
+                        value=""
+                    )
+                    
+                    adv_body_input = gr.Textbox(
+                        label="Body Contains (optional)",
+                        placeholder="Text that must appear in the body",
+                        value=""
+                    )
+                
+                with gr.Column():
+                    adv_tags_input = gr.Textbox(
+                        label="Include Tags (comma-separated)",
+                        placeholder="e.g., python,django,performance",
+                        value=""
+                    )
+                    
+                    adv_excluded_tags_input = gr.Textbox(
+                        label="Exclude Tags (comma-separated)",
+                        placeholder="e.g., beginner,homework",
+                        value=""
+                    )
+                    
+                    adv_sort_input = gr.Dropdown(
+                        label="Sort By",
+                        choices=["votes", "activity", "creation", "relevance"],
+                        value="votes"
+                    )
+            
+            with gr.Row():
+                adv_min_score = gr.Slider(
+                    label="Minimum Score",
+                    minimum=0,
+                    maximum=500,
+                    value=10,
+                    step=5
+                )
+                
+                adv_min_answers = gr.Slider(
+                    label="Minimum Answers",
+                    minimum=0,
+                    maximum=50,
+                    value=1,
+                    step=1
+                )
+                
+                adv_min_views = gr.Slider(
+                    label="Minimum Views",
+                    minimum=0,
+                    maximum=10000,
+                    value=0,
+                    step=100
+                )
+            
+            with gr.Row():
+                adv_accepted = gr.Checkbox(
+                    label="Must have accepted answer",
+                    value=False
+                )
+                
+                adv_limit = gr.Slider(
+                    label="Number of Results",
+                    minimum=1,
+                    maximum=20,
+                    value=5,
+                    step=1
+                )
+                
+                adv_format = gr.Dropdown(
+                    label="Response Format",
+                    choices=["markdown", "json"],
+                    value="markdown"
+                )
+            
+            adv_search_btn = gr.Button("⚙️ Advanced Search", variant="primary", size="lg")
+            adv_output = gr.Markdown(label="Advanced Search Results", height=400)
+            
+            adv_search_btn.click(
+                fn=advanced_search_sync,
+                inputs=[
+                    adv_query_input, adv_tags_input, adv_excluded_tags_input, 
+                    adv_min_score, adv_title_input, adv_body_input, adv_min_answers,
+                    adv_accepted, adv_min_views, adv_sort_input, adv_limit, adv_format, api_key_input
+                ],
+                outputs=adv_output
+            )
+    
+    # Footer with MCP information
+    gr.Markdown("""
+    ---
+    
+    ## 🤖 MCP Integration
+    
+    This app also functions as an **MCP (Model Context Protocol) Server**! 
+    
+    To use with AI assistants like Claude Desktop, add this configuration:
+    
+    ```json
+    {
+      "mcpServers": {
+        "stackoverflow": {
+          "url": "YOUR_DEPLOYED_URL/gradio_api/mcp/sse"
+        }
+      }
+    }
+    ```
+    
+    **Available MCP Tools:**
+    - `search_by_query_sync` - General Stack Overflow search
+    - `search_by_error_sync` - Error-specific search
+    - `get_question_sync` - Get specific question by ID
+    - `analyze_stack_trace_sync` - Analyze stack traces
+    - `advanced_search_sync` - Advanced search with comprehensive filters
+    
+    **💡 Pro Tip:** Add your Stack Exchange API key above for higher quotas (10,000 vs 300 requests/day)!
+    
+    Built with ❤️ for the MCP Hackathon
+    """)
+
+
+if __name__ == "__main__":
+    # Launch with MCP server enabled
+    demo.launch(
+        mcp_server=True,
+        share=True,  # Create a public link for testing
+        server_name="0.0.0.0",  # Allow external connections
+        server_port=7860,  # Standard Gradio port
+        show_error=True
+    )

pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling>=1.0.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stackoverflow-mcp"
+version = "0.1.3"
+description = "Stack Overflow MCP server for LLM applications"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+authors = [
+    {name = "Mark Nawar", email = "[email protected]"},
+]
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "httpx>=0.24.0",
+    "python-dotenv>=1.0.0",
+    "mcp>=0.7.0",
+    "gradio[mcp]>=5.33.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/CodexVeritax/stackoverflow-mcp-server"
+Issues = "https://github.com/CodexVeritax/stackoverflow-mcp-server/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["stackoverflow_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "stackoverflow_mcp",
+    "LICENSE",
+    "README.md",
+    "pyproject.toml",
+]
+
+[project.scripts]
+stackoverflow-mcp = "stackoverflow_mcp.__main__:main"
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"

requirements.txt

@@ -0,0 +1,4 @@
+httpx>=0.24.0
+python-dotenv>=1.0.0
+mcp>=0.7.0
+gradio[mcp]>=5.33.1

stackoverflow_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""Veritax Stackoverflow MCP Server.
+
+A Model Context Protocol (MCP) server for accessing Stackoverflow question.
+"""
+
+__version__ = "0.1.3" 

stackoverflow_mcp/__main__.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python
+from stackoverflow_mcp.server import mcp
+
+def main():
+    """Entry point for the Stack Overflow MCP server."""
+    print("Starting Stack Overflow MCP Server...")
+    mcp.run()
+
+if __name__ == "__main__":
+    main()

stackoverflow_mcp/api.py

@@ -0,0 +1,477 @@
+import httpx
+import time
+from typing import Dict, List, Optional, Any, Union
+import json
+from dataclasses import asdict
+import asyncio
+from datetime import datetime
+from itertools import islice
+
+from .types import (
+    StackOverflowQuestion,
+    StackOverflowAnswer,
+    StackOverflowComment,
+    SearchResult,
+    SearchResultComments
+)
+
+from .env import (
+    MAX_REQUEST_PER_WINDOW,
+    RATE_LIMIT_WINDOW_MS,
+    RETRY_AFTER_MS
+)
+
+STACKOVERFLOW_API = "https://api.stackexchange.com/2.3"
+BATCH_SIZE = 100  # API limit for batch requests
+
+class StackExchangeAPI:
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key
+        self.request_timestamps = []
+        self.client = httpx.AsyncClient(timeout=30.0)
+    
+    async def close(self):
+        await self.client.aclose()
+    
+    def _check_rate_limit(self) -> bool:
+        now = time.time() * 1000
+                
+        self.request_timestamps = [
+            ts for ts in self.request_timestamps
+            if now - ts < RATE_LIMIT_WINDOW_MS
+        ]
+        
+        if len(self.request_timestamps) >= MAX_REQUEST_PER_WINDOW:
+            return False
+        
+        self.request_timestamps.append(now)
+        return True
+    
+    async def _with_rate_limit(self, func, *args, retries=3, attempts=10, **kwargs):
+        """Execute a function with rate limiting.
+
+        Args:
+            func (_type_): Function to execute with rate limiting
+            retries (int, optional): Number of retries after API rate limit error. Defaults to 3.
+            attempts (int, optional): Number of times to retry after hitting local rate limit. Defaults to 10.
+
+        Raises:
+            Exception: When maximum rate limiting attempts are exceeded
+            e: Original error if retries are exhausted
+
+        Returns:
+            Any: Result from the function
+        """
+        if retries is None:
+            retries = 3
+        
+        if attempts <= 0:
+            raise Exception("Maximum rate limiting attempts exceeded")
+    
+        if not self._check_rate_limit():
+            print("Rate limit exceeded, waiting before retry")
+            await asyncio.sleep(RETRY_AFTER_MS / 1000)
+            return await self._with_rate_limit(func, *args, retries=retries, attempts=attempts-1, **kwargs)
+        
+        try: 
+            return await func(*args, **kwargs)
+        except httpx.HTTPStatusError as e:
+            if retries > 0 and e.response.status_code == 429:
+                print("Rate limit hit (429), retrying after delay...")
+                await asyncio.sleep(RETRY_AFTER_MS/1000)
+                return await self._with_rate_limit(func, *args, retries=retries-1, attempts=attempts, **kwargs)
+            raise e
+    
+    async def fetch_batch_answers(self, question_ids: List[int]) -> Dict[int, List[StackOverflowAnswer]]:
+        """Fetch answers for multiple questions in a single API call.
+        
+        Args:
+            question_ids (List[int]): List of Stack Overflow question IDs
+            
+        Returns:
+            Dict[int, List[StackOverflowAnswer]]: Dictionary mapping question IDs to their answers
+        """
+        if not question_ids:
+            return {}
+        
+        result = {}
+        
+        # Process in batches of BATCH_SIZE (API limit)
+        for i in range(0, len(question_ids), BATCH_SIZE):
+            batch = question_ids[i:i+BATCH_SIZE]
+            ids_string = ";".join(str(qid) for qid in batch)
+            
+            params = {
+                "site": "stackoverflow",
+                "sort": "votes",
+                "order": "desc",
+                "filter": "withbody",
+                "pagesize": "100"
+            }
+            
+            if self.api_key:
+                params["key"] = self.api_key
+            
+            async def _do_fetch():
+                response = await self.client.get(
+                    f"{STACKOVERFLOW_API}/questions/{ids_string}/answers",
+                    params=params
+                )
+                response.raise_for_status()
+                return response.json()
+            
+            data = await self._with_rate_limit(_do_fetch)
+            
+            for answer_data in data.get("items", []):
+                question_id = answer_data.get("question_id")
+                if question_id not in result:
+                    result[question_id] = []
+                
+                answer = StackOverflowAnswer(
+                    answer_id=answer_data.get("answer_id"),
+                    question_id=question_id,
+                    score=answer_data.get("score", 0),
+                    is_accepted=answer_data.get("is_accepted", False),
+                    body=answer_data.get("body", ""),
+                    creation_date=answer_data.get("creation_date", 0),
+                    last_activity_date=answer_data.get("last_activity_date", 0),
+                    link=answer_data.get("link", ""),
+                    owner=answer_data.get("owner")
+                )
+                result[question_id].append(answer)
+        
+        return result
+    
+    async def fetch_batch_comments(self, post_ids: List[int]) -> Dict[int, List[StackOverflowComment]]:
+        """Fetch comments for multiple posts in a single API call.
+        
+        Args:
+            post_ids (List[int]): List of Stack Overflow post IDs (questions or answers)
+            
+        Returns:
+            Dict[int, List[StackOverflowComment]]: Dictionary mapping post IDs to their comments
+        """
+        if not post_ids:
+            return {}
+        
+        result = {}
+        
+        # Process in batches of BATCH_SIZE (API limit)
+        for i in range(0, len(post_ids), BATCH_SIZE):
+            batch = post_ids[i:i+BATCH_SIZE]
+            ids_string = ";".join(str(pid) for pid in batch)
+            
+            params = {
+                "site": "stackoverflow",
+                "sort": "votes",
+                "order": "desc",
+                "filter": "withbody",
+                "pagesize": "100" 
+            }
+            
+            if self.api_key:
+                params["key"] = self.api_key
+            
+            async def _do_fetch():
+                response = await self.client.get(
+                    f"{STACKOVERFLOW_API}/posts/{ids_string}/comments",
+                    params=params
+                )
+                response.raise_for_status()
+                return response.json()
+            
+            data = await self._with_rate_limit(_do_fetch)
+            
+            for comment_data in data.get("items", []):
+                post_id = comment_data.get("post_id")
+                if post_id not in result:
+                    result[post_id] = []
+                
+                comment = StackOverflowComment(
+                    comment_id=comment_data.get("comment_id"),
+                    post_id=post_id,
+                    score=comment_data.get("score", 0),
+                    body=comment_data.get("body", ""),
+                    creation_date=comment_data.get("creation_date", 0),
+                    owner=comment_data.get("owner")
+                )
+                result[post_id].append(comment)
+        
+        return result
+    
+    async def advanced_search(
+        self,
+        query: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        excluded_tags: Optional[List[str]] = None,
+        min_score: Optional[int] = None,
+        title: Optional[str] = None,
+        body: Optional[str] = None,
+        answers: Optional[int] = None,
+        has_accepted_answer: Optional[bool] = None,
+        views: Optional[int] = None,
+        url: Optional[str] = None,
+        user_id: Optional[int] = None,
+        is_closed: Optional[bool] = None,
+        is_wiki: Optional[bool] = None,
+        is_migrated: Optional[bool] = None,
+        has_notice: Optional[bool] = None,
+        from_date: Optional[datetime] = None,
+        to_date: Optional[datetime] = None,
+        sort_by: Optional[str] = "votes",
+        limit: Optional[int] = 5,
+        include_comments: bool = False,
+        retries: Optional[int] = 3
+    ) -> List[SearchResult]:
+        """Advanced search for Stack Overflow questions with many filter options."""
+        params = {
+            "site": "stackoverflow",
+            "sort": sort_by,
+            "order": "desc",
+            "filter": "withbody"
+        }
+        
+        if query:
+            params["q"] = query
+            
+        if tags:
+            params["tagged"] = ";".join(tags)
+            
+        if excluded_tags:
+            params["nottagged"] = ";".join(excluded_tags)
+            
+        if title:
+            params["title"] = title
+            
+        if body:
+            params["body"] = body
+            
+        if answers is not None:
+            params["answers"] = str(answers)
+            
+        if has_accepted_answer is not None:
+            params["accepted"] = "true" if has_accepted_answer else "false"
+            
+        if views is not None:
+            params["views"] = str(views)
+            
+        if url:
+            params["url"] = url
+            
+        if user_id is not None:
+            params["user"] = str(user_id)
+            
+        if is_closed is not None:
+            params["closed"] = "true" if is_closed else "false"
+            
+        if is_wiki is not None:
+            params["wiki"] = "true" if is_wiki else "false"
+            
+        if is_migrated is not None:
+            params["migrated"] = "true" if is_migrated else "false"
+            
+        if has_notice is not None:
+            params["notice"] = "true" if has_notice else "false"
+            
+        if from_date:
+            params["fromdate"] = str(int(from_date.timestamp()))
+            
+        if to_date:
+            params["todate"] = str(int(to_date.timestamp()))
+            
+        if limit:
+            params["pagesize"] = str(limit)
+        
+        if self.api_key:
+            params["key"] = self.api_key
+            
+        async def _do_search():
+            response = await self.client.get(f"{STACKOVERFLOW_API}/search/advanced", params=params)
+            response.raise_for_status()
+            return response.json()
+        
+        data = await self._with_rate_limit(_do_search, retries=retries)
+        
+        questions = []
+        question_ids = []
+        
+        for question_data in data.get("items", []):
+            if min_score is not None and question_data.get("score", 0) < min_score:
+                continue
+            
+            question = StackOverflowQuestion(
+                question_id=question_data.get("question_id"),
+                title=question_data.get("title", ""),
+                body=question_data.get("body", ""),
+                score=question_data.get("score", 0),
+                answer_count=question_data.get("answer_count", 0),
+                is_answered=question_data.get("is_answered", False),
+                accepted_answer_id=question_data.get("accepted_answer_id"),
+                creation_date=question_data.get("creation_date", 0),
+                last_activity_date=question_data.get("last_activity_date", 0),
+                view_count=question_data.get("view_count", 0),
+                tags=question_data.get("tags", []),
+                link=question_data.get("link", ""),
+                is_closed=question_data.get("closed_date") is not None,
+                owner=question_data.get("owner")
+            )
+            questions.append(question)
+            question_ids.append(question.question_id)
+            
+        answers_by_question = await self.fetch_batch_answers(question_ids)
+        
+        results = []
+        
+        if include_comments:
+            all_post_ids = question_ids.copy()
+            for qid, answers in answers_by_question.items():
+                all_post_ids.extend([a.answer_id for a in answers])
+            
+            # Batch fetch all comments
+            all_comments = await self.fetch_batch_comments(all_post_ids)
+            
+            # Construct results with comments
+            for question in questions:
+                question_answers = answers_by_question.get(question.question_id, [])
+                
+                # Create comment structure
+                question_comments = all_comments.get(question.question_id, [])
+                answer_comments = {}
+                
+                for answer in question_answers:
+                    answer_comments[answer.answer_id] = all_comments.get(answer.answer_id, [])
+                
+                comments = SearchResultComments(
+                    question=question_comments,
+                    answers=answer_comments
+                )
+                
+                results.append(SearchResult(
+                    question=question,
+                    answers=question_answers,
+                    comments=comments
+                ))
+        else:
+            for question in questions:
+                question_answers = answers_by_question.get(question.question_id, [])
+                results.append(SearchResult(
+                    question=question,
+                    answers=question_answers,
+                    comments=None
+                ))
+                
+        return results
+    
+    async def search_by_query(
+        self, 
+        query: str,
+        tags: Optional[List[str]] = None,
+        excluded_tags: Optional[List[str]] = None,
+        min_score: Optional[int] = None,
+        title: Optional[str] = None,
+        body: Optional[str] = None,
+        has_accepted_answer: Optional[bool] = None,
+        answers: Optional[int] = None,
+        sort_by: Optional[str] = "votes",
+        limit: Optional[int] = 5,
+        include_comments: bool = False,
+        retries: Optional[int] = 3
+    ) -> List[SearchResult]:
+        """Search Stack Overflow for questions matching a query with additional filters."""
+        return await self.advanced_search(
+            query=query,
+            tags=tags,
+            excluded_tags=excluded_tags,
+            min_score=min_score,
+            title=title,
+            body=body,
+            has_accepted_answer=has_accepted_answer,
+            answers=answers,
+            sort_by=sort_by,
+            limit=limit,
+            include_comments=include_comments,
+            retries=retries
+        )
+    
+    async def fetch_answers(self, question_id: int) -> List[StackOverflowAnswer]:
+        """Fetch answers for a specific question.
+        
+        Note: This is kept for backward compatibility, but new code should
+        use fetch_batch_answers for better performance.
+        """
+        answers_dict = await self.fetch_batch_answers([question_id])
+        return answers_dict.get(question_id, [])
+    
+    async def fetch_comments(self, post_id: int) -> List[StackOverflowComment]:
+        """Fetch comments for a specific post.
+        
+        Note: This is kept for backward compatibility, but new code should
+        use fetch_batch_comments for better performance.
+        """
+        comments_dict = await self.fetch_batch_comments([post_id])
+        return comments_dict.get(post_id, [])
+    
+    async def get_question(self, question_id: int, include_comments: bool = True) -> SearchResult:
+        """Get a specific question by ID."""
+        params = {
+            "site": "stackoverflow",
+            "filter": "withbody"
+        }
+        
+        if self.api_key:
+            params["key"] = self.api_key
+        
+        async def _do_fetch():
+            response = await self.client.get(
+                f"{STACKOVERFLOW_API}/questions/{question_id}", 
+                params=params
+            )
+            response.raise_for_status()
+            return response.json()
+        
+        data = await self._with_rate_limit(_do_fetch)
+        
+        if not data.get("items"):
+            raise ValueError(f"Question with ID {question_id} not found")
+        
+        question_data = data["items"][0]
+        question = StackOverflowQuestion(
+            question_id=question_data.get("question_id"),
+            title=question_data.get("title", ""),
+            body=question_data.get("body", ""),
+            score=question_data.get("score", 0),
+            answer_count=question_data.get("answer_count", 0),
+            is_answered=question_data.get("is_answered", False),
+            accepted_answer_id=question_data.get("accepted_answer_id"),
+            creation_date=question_data.get("creation_date", 0),
+            last_activity_date=question_data.get("last_activity_date", 0),
+            view_count=question_data.get("view_count", 0),
+            tags=question_data.get("tags", []),
+            link=question_data.get("link", ""),
+            is_closed=question_data.get("closed_date") is not None,
+            owner=question_data.get("owner")
+        )
+        
+        answers = await self.fetch_answers(question.question_id)
+        
+        comments = None
+        if include_comments:
+            post_ids = [question.question_id] + [answer.answer_id for answer in answers]
+            all_comments = await self.fetch_batch_comments(post_ids)
+            
+            question_comments = all_comments.get(question.question_id, [])
+            answer_comments = {}
+            
+            for answer in answers:
+                answer_comments[answer.answer_id] = all_comments.get(answer.answer_id, [])
+            
+            comments = SearchResultComments(
+                question=question_comments,
+                answers=answer_comments
+            )
+        
+        return SearchResult(
+            question=question,
+            answers=answers,
+            comments=comments
+        )

stackoverflow_mcp/env.py

@@ -0,0 +1,10 @@
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+STACK_EXCHANGE_API_KEY = os.getenv("STACK_EXCHANGE_API_KEY")
+
+MAX_REQUEST_PER_WINDOW = int(os.getenv("MAX_REQUEST_PER_WINDOW" , "30"))
+RATE_LIMIT_WINDOW_MS = int(os.getenv("RATE_LIMIT_WINDOW_MS" , "60000"))
+RETRY_AFTER_MS = int(os.getenv("RETRY_AFTER_MS" , "2000"))

stackoverflow_mcp/formatter.py

@@ -0,0 +1,106 @@
+import json
+from typing import List
+from dataclasses import asdict
+import re
+
+from .types import SearchResult, StackOverflowAnswer, StackOverflowComment
+
+
+def format_response(results: List[SearchResult], format_type: str = "markdown") -> str:
+    """Format search results as either JSON or Markdown.
+
+    Args:
+        results (List[SearchResult]): List of search results to format
+        format_type (str, optional): Output format type - either "json" or "markdown". Defaults to "markdown".
+
+    Returns:
+        str: Formatted string representation of the search results
+    """
+    
+    if format_type == "json":
+        def _convert_to_dict(obj):
+            if hasattr(obj, "__dataclass_fields__"):
+                return asdict(obj)
+            return obj
+        
+        class DataClassJSONEncoder(json.JSONEncoder):
+            def default(self, obj):
+                if hasattr(obj, "__dataclass_fields__"):
+                    return asdict(obj)
+                return super().default(obj)
+            
+        return json.dumps(results, cls=DataClassJSONEncoder, indent=2)
+    
+    if not results:
+        return "No results found."
+    
+    markdown = ""
+    
+    for result in results:
+        markdown += f"# {result.question.title}\n\n"
+        markdown += f"**Score:** {result.question.score} | **Answers:** {result.question.answer_count}\n\n"
+        
+        question_body = clean_html(result.question.body)
+        markdown += f"## Question\n\n{question_body}\n\n"
+        
+        if result.comments and result.comments.question:
+            markdown += "### Question Comments\n\n"
+            for comment in result.comments.question:
+                markdown += f"- {clean_html(comment.body)} *(Score: {comment.score})*\n"
+            markdown += "\n"
+            
+        markdown += "## Answers\n\n"
+        for answer in result.answers:
+            markdown += f"### {'✓ ' if answer.is_accepted else ''}Answer (Score: {answer.score})\n\n"
+            answer_body = clean_html(answer.body)
+            markdown += f"{answer_body}\n\n"
+            
+            if (result.comments and 
+                result.comments.answers and
+                answer.answer_id in result.comments.answers and
+                result.comments.answers[answer.answer_id]
+                ):
+                markdown += "#### Answer Comments\n\n"
+                for comment in result.comments.answers[answer.answer_id]:
+                    markdown += f"- {clean_html(comment.body)} *(Score: {comment.score})*\n"
+                
+                markdown += "/n"
+                
+        markdown += f"---\n\n[View on Stack Overflow]({result.question.link})\n\n"
+        
+    return markdown
+
+def clean_html(html_text: str) -> str:
+    """Clean HTML tags from text while preserving code blocks.
+
+    Args:
+        html_text (str): HTML text to be cleaned
+
+    Returns:
+        str: Cleaned text with HTML tags removed and code blocks preserved
+    """
+    
+    code_blocks = []
+    
+    def replace_code_block(match):
+        code = match.group(1) or match.group(2)
+        code_blocks.append(code)
+        return f"CODE_BLOCK_{len(code_blocks)-1}"
+    
+    html_without_code = re.sub(r'<pre><code>(.*?)</code></pre>|<code>(.*?)</code>', replace_code_block, html_text, flags=re.DOTALL)
+    
+    text_without_html = re.sub(r'<[^>]+>', '', html_without_code)
+    
+    for i, code in enumerate(code_blocks):
+        if '\n' in code or len(code) > 80:
+            text_without_html = text_without_html.replace(f"CODE_BLOCK_{i}", f"```\n{code}\n```")
+        else:
+            text_without_html = text_without_html.replace(f"CODE_BLOCK_{i}", f"`{code}`")
+            
+    
+    text_without_html = text_without_html.replace("&lt;", "<")
+    text_without_html = text_without_html.replace("&gt;", ">")
+    text_without_html = text_without_html.replace("&amp;", "&")
+    text_without_html = text_without_html.replace("&quot;", "\"")
+    
+    return text_without_html

stackoverflow_mcp/server.py

@@ -0,0 +1,376 @@
+import asyncio
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import AsyncIterator, List, Optional, Dict, Any
+from datetime import datetime
+
+from mcp.server.fastmcp import FastMCP, Context
+# Instead of importing Error from mcp.server.fastmcp.tools, we'll define our own Error class
+# or we can use standard exceptions for now
+
+from .api import StackExchangeAPI
+from .types import (
+    SearchByQueryInput,
+    SearchByErrorInput,
+    GetQuestionInput,
+    AdvancedSearchInput,
+    SearchResult
+)
+
+from .formatter import format_response
+from .env import STACK_EXCHANGE_API_KEY
+
+@dataclass
+class AppContext:
+    api: StackExchangeAPI
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
+    """Manage application lifecycle with the Stack Exchange API client.
+
+    Args:
+        server (FastMCP): The FastMCP server instance
+
+    Returns:
+        AsyncIterator[AppContext]: Context containing the API client
+    """
+    
+    api = StackExchangeAPI(
+        api_key=STACK_EXCHANGE_API_KEY,
+    )
+    try:
+        yield AppContext(api=api)
+    finally:
+        await api.close()
+        
+mcp = FastMCP(
+    "Stack Overflow MCP",
+    lifespan=app_lifespan,
+    dependencies=["httpx", "python-dotenv"]
+)
+
+@mcp.tool()
+async def advanced_search(
+    query: Optional[str] = None,
+    tags: Optional[List[str]] = None,
+    excluded_tags: Optional[List[str]] = None,
+    min_score: Optional[int] = None,
+    title: Optional[str] = None,
+    body: Optional[str] = None,
+    answers: Optional[int] = None,
+    has_accepted_answer: Optional[bool] = None,
+    views: Optional[int] = None,
+    url: Optional[str] = None,
+    user_id: Optional[int] = None,
+    is_closed: Optional[bool] = None,
+    is_wiki: Optional[bool] = None,
+    is_migrated: Optional[bool] = None,
+    has_notice: Optional[bool] = None,
+    from_date: Optional[datetime] = None,
+    to_date: Optional[datetime] = None,
+    sort_by: Optional[str] = "votes",
+    include_comments: Optional[bool] = False,
+    response_format: Optional[str] = "markdown",
+    limit: Optional[int] = 5,
+    ctx: Context = None
+) -> str:
+    """Advanced search for Stack Overflow questions with many filter options.
+    
+    Args:
+        query (Optional[str]): Free-form search query
+        tags (Optional[List[str]]): List of tags to filter by
+        excluded_tags (Optional[List[str]]): List of tags to exclude
+        min_score (Optional[int]): Minimum score threshold
+        title (Optional[str]): Text that must appear in the title
+        body (Optional[str]): Text that must appear in the body
+        answers (Optional[int]): Minimum number of answers
+        has_accepted_answer (Optional[bool]): Whether questions must have an accepted answer
+        views (Optional[int]): Minimum number of views
+        url (Optional[str]): URL that must be contained in the post
+        user_id (Optional[int]): ID of the user who must own the questions
+        is_closed (Optional[bool]): Whether to return only closed or open questions
+        is_wiki (Optional[bool]): Whether to return only community wiki questions
+        is_migrated (Optional[bool]): Whether to return only migrated questions
+        has_notice (Optional[bool]): Whether to return only questions with post notices
+        from_date (Optional[datetime]): Earliest creation date
+        to_date (Optional[datetime]): Latest creation date
+        sort_by (Optional[str]): Field to sort by (activity, creation, votes, relevance)
+        include_comments (Optional[bool]): Whether to include comments in results
+        response_format (Optional[str]): Format of response ("json" or "markdown")
+        limit (Optional[int]): Maximum number of results to return
+        ctx (Context): The context is passed automatically by the MCP
+        
+    Returns:
+        str: Formatted search results
+    """
+    try:
+        api = ctx.request_context.lifespan_context.api
+        
+        ctx.debug(f"Performing advanced search on Stack Overflow")
+        if query:
+            ctx.debug(f"Query: {query}")
+        if body:
+            ctx.debug(f"Body: {body}")
+        if tags:
+            ctx.debug(f"Tags: {', '.join(tags)}")
+        if excluded_tags:
+            ctx.debug(f"Excluded tags: {', '.join(excluded_tags)}")
+        
+        results = await api.advanced_search(
+            query=query,
+            tags=tags,
+            excluded_tags=excluded_tags,
+            min_score=min_score,
+            title=title,
+            body=body,
+            answers=answers,
+            has_accepted_answer=has_accepted_answer,
+            views=views,
+            url=url,
+            user_id=user_id,
+            is_closed=is_closed,
+            is_wiki=is_wiki,
+            is_migrated=is_migrated,
+            has_notice=has_notice,
+            from_date=from_date,
+            to_date=to_date,
+            sort_by=sort_by,
+            limit=limit,
+            include_comments=include_comments
+        )
+        
+        ctx.debug(f"Found {len(results)} results")
+        
+        return format_response(results, response_format)
+    
+    except Exception as e:
+        ctx.error(f"Error performing advanced search on Stack Overflow: {str(e)}")
+        raise RuntimeError(f"Failed to search Stack Overflow: {str(e)}")
+
+@mcp.tool()
+async def search_by_query(
+    query: str,
+    tags: Optional[List[str]] = None,
+    excluded_tags: Optional[List[str]] = None,
+    min_score: Optional[int] = None,
+    title: Optional[str] = None,
+    body: Optional[str] = None,
+    has_accepted_answer: Optional[bool] = None,
+    answers: Optional[int] = None,
+    sort_by: Optional[str] = "votes",
+    include_comments: Optional[bool] = False,
+    response_format: Optional[str] = "markdown",
+    limit: Optional[int] = 5,
+    ctx: Context = None 
+) -> str:
+    """Search Stack Overflow for questions matching a query.
+
+    Args:
+        query (str): The search query
+        tags (Optional[List[str]]): Optional list of tags to filter by (e.g., ["python", "pandas"])
+        excluded_tags (Optional[List[str]]): Optional list of tags to exclude
+        min_score (Optional[int]): Minimum score threshold for questions
+        title (Optional[str]): Text that must appear in the title
+        body (Optional[str]): Text that must appear in the body
+        has_accepted_answer (Optional[bool]): Whether questions must have an accepted answer
+        answers (Optional[int]): Minimum number of answers
+        sort_by (Optional[str]): Field to sort by (activity, creation, votes, relevance)
+        include_comments (Optional[bool]): Whether to include comments in results
+        response_format (Optional[str]): Format of response ("json" or "markdown")
+        limit (Optional[int]): Maximum number of results to return
+        ctx (Context): The context is passed automatically by the MCP
+
+    Returns:
+        str: Formatted search results
+    """
+    try:
+        api = ctx.request_context.lifespan_context.api
+        
+        ctx.debug(f"Searching Stack Overflow for: {query}")
+        
+        if tags: 
+            ctx.debug(f"Filtering by tags: {', '.join(tags)}")
+        if excluded_tags:
+            ctx.debug(f"Excluding tags: {', '.join(excluded_tags)}")
+        
+        results = await api.search_by_query(
+            query=query,
+            tags=tags,
+            excluded_tags=excluded_tags,
+            min_score=min_score,
+            title=title,
+            body=body,
+            has_accepted_answer=has_accepted_answer,
+            answers=answers,
+            sort_by=sort_by,
+            limit=limit,
+            include_comments=include_comments
+        )
+        
+        ctx.debug(f"Found {len(results)} results")
+        
+        return format_response(results, response_format)
+    
+    except Exception as e:
+        ctx.error(f"Error searching Stack Overflow: {str(e)}")
+        raise RuntimeError(f"Failed to search Stack Overflow: {str(e)}")
+
+
+@mcp.tool()
+async def search_by_error(
+    error_message: str,
+    language: Optional[str] = None,
+    technologies: Optional[List[str]] = None,
+    excluded_tags: Optional[List[str]] = None,
+    min_score: Optional[int] = None,
+    has_accepted_answer: Optional[bool] = None,
+    answers: Optional[int] = None,
+    include_comments: Optional[bool] = False,
+    response_format: Optional[str] = "markdown",
+    limit: Optional[int] = 5,
+    ctx: Context = None
+) -> str:
+    """Search Stack Overflow for solutions to an error message
+
+    Args:
+        error_message (str): The error message to search for
+        language (Optional[str]): Programming language (e.g., "python", "javascript")
+        technologies (Optional[List[str]]): Related technologies (e.g., ["react", "django"])
+        excluded_tags (Optional[List[str]]): Optional list of tags to exclude
+        min_score (Optional[int]): Minimum score threshold for questions
+        has_accepted_answer (Optional[bool]): Whether questions must have an accepted answer
+        answers (Optional[int]): Minimum number of answers
+        include_comments (Optional[bool]): Whether to include comments in results
+        response_format (Optional[str]): Format of response ("json" or "markdown")
+        limit (Optional[int]): Maximum number of results to return
+        ctx (Context): The context is passed automatically by the MCP
+
+    Returns:
+        str: Formatted search results
+    """
+    try:
+        api = ctx.request_context.lifespan_context.api
+        
+        tags = []
+        if language:
+            tags.append(language.lower())
+        if technologies:
+            tags.extend([t.lower() for t in technologies])
+            
+        ctx.debug(f"Searching Stack Overflow for error: {error_message}")
+        
+        if tags:
+            ctx.debug(f"Using tags: {', '.join(tags)}")
+        if excluded_tags:
+            ctx.debug(f"Excluding tags: {', '.join(excluded_tags)}")
+        
+        results = await api.search_by_query(
+            query=error_message,
+            tags=tags if tags else None,
+            excluded_tags=excluded_tags,
+            min_score=min_score,
+            has_accepted_answer=has_accepted_answer,
+            answers=answers,
+            limit=limit,
+            include_comments=include_comments
+        )
+        ctx.debug(f"Found {len(results)} results")
+        
+        return format_response(results, response_format)
+    except Exception as e: 
+        ctx.error(f"Error searching Stack Overflow: {str(e)}")
+        raise RuntimeError(f"Failed to search Stack Overflow: {str(e)}")
+    
+@mcp.tool()
+async def get_question(
+    question_id: int,
+    include_comments: Optional[bool] = True,
+    response_format: Optional[str] = "markdown",
+    ctx: Context = None
+) -> str:
+    """Get a specific Stack Overflow question by ID.
+
+    Args:
+        question_id (int): The Stack Overflow question ID
+        include_comments (Optional[bool]): Whether to include comments in results
+        response_format (Optional[str]): Format of response ("json" or "markdown")
+        ctx (Context): The context is passed automatically by the MCP
+
+    Returns:
+        str: Formatted question details
+    """
+    try:
+        api = ctx.request_context.lifespan_context.api 
+        
+        ctx.debug(f"Fetching Stack Overflow question: {question_id}")
+        
+        result = await api.get_question(
+            question_id=question_id,
+            include_comments=include_comments
+        )
+        
+        return format_response([result], response_format)
+    
+    except Exception as e:
+        ctx.error(f"Error fetching Stack Overflow question: {str(e)}")
+        raise RuntimeError(f"Failed to fetch Stack Overflow question: {str(e)}")
+
+@mcp.tool()
+async def analyze_stack_trace(
+    stack_trace: str,
+    language: str,
+    excluded_tags: Optional[List[str]] = None,
+    min_score: Optional[int] = None,
+    has_accepted_answer: Optional[bool] = None,
+    answers: Optional[int] = None,
+    include_comments: Optional[bool] = True,
+    response_format: Optional[str] = "markdown",
+    limit: Optional[int] = 3,
+    ctx: Context = None
+) -> str:
+    """Analyze a stack trace and find relevant solutions on Stack Overflow.
+    
+    Args:
+        stack_trace (str): The stack trace to analyze
+        language (str): Programming language of the stack trace
+        excluded_tags (Optional[List[str]]): Optional list of tags to exclude
+        min_score (Optional[int]): Minimum score threshold for questions
+        has_accepted_answer (Optional[bool]): Whether questions must have an accepted answer
+        answers (Optional[int]): Minimum number of answers
+        include_comments (Optional[bool]): Whether to include comments in results
+        response_format (Optional[str]): Format of response ("json" or "markdown")
+        limit (Optional[int]): Maximum number of results to return
+        ctx (Context): The context is passed automatically by the MCP
+        
+    Returns:
+        str: Formatted search results
+    """
+    try:
+        api = ctx.request_context.lifespan_context.api
+        
+        error_lines = stack_trace.split("\n")
+        error_message = error_lines[0]
+        
+        ctx.debug(f"Analyzing stack trace: {error_message}")
+        ctx.debug(f"Language: {language}")
+        
+        results = await api.search_by_query(
+            query=error_message,
+            tags=[language.lower()],
+            excluded_tags=excluded_tags,
+            min_score=min_score,
+            has_accepted_answer=has_accepted_answer,
+            answers=answers,
+            limit=limit,
+            include_comments=include_comments
+        )
+        
+        ctx.debug(f"Found {len(results)} results")
+        
+        return format_response(results, response_format)
+    except Exception as e:
+        ctx.error(f"Error analyzing stack trace: {str(e)}")
+        raise RuntimeError(f"Failed to analyze stack trace: {str(e)}")
+
+if __name__ == "__main__":
+    mcp.run()

stackoverflow_mcp/types.py

@@ -0,0 +1,110 @@
+from dataclasses import dataclass
+from typing import List, Dict, Optional, Union, Literal
+from datetime import datetime
+
+@dataclass
+class AdvancedSearchInput:
+    query: Optional[str] = None
+    tags: Optional[List[str]] = None
+    excluded_tags: Optional[List[str]] = None
+    min_score: Optional[int] = None
+    title: Optional[str] = None
+    body: Optional[str] = None
+    answers: Optional[int] = None
+    has_accepted_answer: Optional[bool] = None
+    views: Optional[int] = None
+    url: Optional[str] = None
+    user_id: Optional[int] = None
+    is_closed: Optional[bool] = None
+    is_wiki: Optional[bool] = None
+    is_migrated: Optional[bool] = None
+    has_notice: Optional[bool] = None
+    from_date: Optional[datetime] = None
+    to_date: Optional[datetime] = None
+    sort_by: Optional[Literal["activity", "creation", "votes", "relevance"]] = "activity"
+    include_comments: Optional[bool] = False
+    response_format: Optional[Literal["json", "markdown"]] = "markdown"
+    limit: Optional[int] = 5
+
+@dataclass
+class SearchByQueryInput:
+    query: str
+    tags: Optional[List[str]] = None
+    excluded_tags: Optional[List[str]] = None
+    min_score: Optional[int] = None
+    title: Optional[str] = None
+    body: Optional[str] = None
+    has_accepted_answer: Optional[bool] = None
+    answers: Optional[int] = None
+    sort_by: Optional[Literal["activity", "creation", "votes", "relevance"]] = "votes"
+    include_comments: Optional[bool] = False
+    response_format: Optional[Literal["json","markdown"]] = "markdown"
+    limit: Optional[int] = 5
+
+@dataclass
+class SearchByErrorInput:
+    error_message: str
+    language: Optional[str] = None
+    technologies: Optional[List[str]] = None
+    excluded_tags: Optional[List[str]] = None
+    min_score: Optional[int] = None
+    has_accepted_answer: Optional[bool] = None
+    answers: Optional[int] = None
+    include_comments: Optional[bool] = False
+    response_format: Optional[Literal["json", "markdown"]] = "markdown"
+    limit: Optional[int] = 5
+
+@dataclass
+class GetQuestionInput:
+    question_id: int
+    include_comments: Optional[bool] = True
+    response_format: Optional[Literal["json", "markdown"]] = "markdown"
+
+@dataclass
+class StackOverflowQuestion:
+    question_id: int
+    title: str
+    body: str
+    score: int
+    answer_count: int
+    is_answered: bool
+    accepted_answer_id: Optional[int] = None
+    creation_date: int = 0
+    last_activity_date: int = 0
+    view_count: int = 0
+    tags: List[str] = None
+    link: str = ""
+    is_closed: bool = False
+    owner: Optional[Dict] = None
+
+@dataclass
+class StackOverflowAnswer:
+    answer_id: int
+    question_id: int
+    score: int
+    is_accepted: bool
+    body: str
+    creation_date: int = 0
+    last_activity_date: int = 0
+    link: str = ""
+    owner: Optional[Dict] = None
+
+@dataclass
+class StackOverflowComment:
+    comment_id: int
+    post_id: int
+    score: int
+    body: str
+    creation_date: int = 0
+    owner: Optional[Dict] = None
+
+@dataclass
+class SearchResultComments:
+    question: List[StackOverflowComment]
+    answers: Dict[int, List[StackOverflowComment]]
+    
+@dataclass
+class SearchResult:
+    question: StackOverflowQuestion
+    answers: List[StackOverflowAnswer]
+    comments: Optional[SearchResultComments] = None

test_live_demo.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""
+Live Demo Test - Stack Overflow MCP Server
+This script makes actual API calls to demonstrate the working functionality.
+"""
+
+import sys
+import os
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+
+from gradio_app import search_by_query_sync, search_by_error_sync, get_question_sync
+
+def test_live_functionality():
+    """Test the actual functionality of our Stack Overflow MCP server."""
+    
+    print("🧪 LIVE FUNCTIONALITY TEST")
+    print("=" * 60)
+    
+    # Test 1: General Search
+    print("\n1️⃣ Testing General Search...")
+    print("Query: 'python list comprehension'")
+    print("Tags: 'python'")
+    print("-" * 40)
+    
+    try:
+        result = search_by_query_sync(
+            query="python list comprehension", 
+            tags="python",
+            min_score=10,
+            has_accepted_answer=True,
+            limit=2,
+            response_format="markdown"
+        )
+        print("✅ SUCCESS:")
+        print(result[:500] + "..." if len(result) > 500 else result)
+    except Exception as e:
+        print(f"❌ ERROR: {e}")
+    
+    print("\n" + "=" * 60)
+    
+    # Test 2: Error Search
+    print("\n2️⃣ Testing Error Search...")
+    print("Error: 'TypeError: NoneType'")
+    print("Language: 'python'")
+    print("-" * 40)
+    
+    try:
+        result = search_by_error_sync(
+            error_message="TypeError: NoneType object has no attribute",
+            language="python",
+            technologies="",
+            min_score=5,
+            has_accepted_answer=True,
+            limit=2,
+            response_format="markdown"
+        )
+        print("✅ SUCCESS:")
+        print(result[:500] + "..." if len(result) > 500 else result)
+    except Exception as e:
+        print(f"❌ ERROR: {e}")
+    
+    print("\n" + "=" * 60)
+    
+    # Test 3: Get Question
+    print("\n3️⃣ Testing Get Question...")
+    print("Question ID: 11227809 (Famous sorting question)")
+    print("-" * 40)
+    
+    try:
+        result = get_question_sync(
+            question_id="11227809",
+            include_comments=False,
+            response_format="markdown"
+        )
+        print("✅ SUCCESS:")
+        print(result[:500] + "..." if len(result) > 500 else result)
+    except Exception as e:
+        print(f"❌ ERROR: {e}")
+    
+    print("\n" + "=" * 60)
+    print("🎯 Live functionality test completed!")
+    print("🚀 All functions are working and connected to Stack Overflow API")
+
+if __name__ == "__main__":
+    test_live_functionality()

tests/api/test_search.py

@@ -0,0 +1,243 @@
+import os
+import pytest
+import asyncio
+import httpx
+from unittest.mock import patch, MagicMock, AsyncMock
+from dotenv import load_dotenv
+
+from stackoverflow_mcp.api import StackExchangeAPI
+from stackoverflow_mcp.types import SearchResult
+
+# Load test environment variables
+load_dotenv(".env.test")
+
+
+@pytest.fixture
+def api_key():
+    """Return API key from environment or None."""
+    return os.getenv("STACK_EXCHANGE_API_KEY")
+
+
+@pytest.fixture
+def api(api_key):
+    """Create a StackExchangeAPI instance for testing."""
+    api = StackExchangeAPI(api_key=api_key)
+    yield api
+    # Clean up
+    asyncio.run(api.close())
+
+
+@pytest.fixture
+def mock_search_response():
+    """Create a mock search response."""
+    response = MagicMock()
+    response.raise_for_status = MagicMock()
+    response.json = MagicMock(return_value={
+        "items": [
+            {
+                "question_id": 12345,
+                "title": "How to unittest a Flask application?",
+                "body": "<p>I'm trying to test my Flask application with unittest.</p>",
+                "score": 25,
+                "answer_count": 3,
+                "is_answered": True,
+                "accepted_answer_id": 54321,
+                "creation_date": 1609459200,
+                "last_activity_date": 1609459200,
+                "view_count": 1000,
+                "tags": ["python", "flask", "testing", "unittest"],
+                "link": "https://stackoverflow.com/q/12345",
+                "closed_date": None,
+                "owner": {
+                    "user_id": 101,
+                    "display_name": "Test User",
+                    "reputation": 1000
+                }
+            }
+        ],
+        "has_more": False,
+        "quota_max": 300,
+        "quota_remaining": 299
+    })
+    return response
+
+
+# REAL API TESTS
+
+@pytest.mark.asyncio
+@pytest.mark.real_api
+async def test_search_by_query_real(api):
+    """Test searching by query using real API."""
+    # Skip if no API key
+    if not os.getenv("STACK_EXCHANGE_API_KEY"):
+        pytest.skip("API key required for real API tests")
+    
+    results = await api.search_by_query(
+        query="python unittest flask",
+        tags=["python", "flask"],
+        limit=3
+    )
+    
+    # Basic validation
+    assert isinstance(results, list)
+    if results:  # May be empty if no results match
+        assert isinstance(results[0], SearchResult)
+        assert results[0].question.title is not None
+        assert "python" in [tag.lower() for tag in results[0].question.tags]
+
+
+@pytest.mark.asyncio
+@pytest.mark.real_api
+async def test_advanced_search_real(api):
+    """Test advanced search using real API."""
+    # Skip if no API key
+    if not os.getenv("STACK_EXCHANGE_API_KEY"):
+        pytest.skip("API key required for real API tests")
+    
+    results = await api.advanced_search(
+        query="database connection",
+        tags=["python"],
+        min_score=10,
+        has_accepted_answer=True,
+        limit=2
+    )
+    
+    # Basic validation
+    assert isinstance(results, list)
+    if results:  # May be empty if no results match
+        assert isinstance(results[0], SearchResult)
+        assert results[0].question.score >= 10
+        assert "python" in [tag.lower() for tag in results[0].question.tags]
+
+
+# MOCK TESTS
+
+@pytest.mark.asyncio
+async def test_search_by_query_mock(api, mock_search_response):
+    """Test searching by query with mocked response."""
+    with patch.object(httpx.AsyncClient, 'get', return_value=mock_search_response):
+        results = await api.search_by_query(
+            query="flask unittest",
+            tags=["python", "flask"],
+            min_score=10,
+            limit=5
+        )
+        
+        assert len(results) == 1
+        assert results[0].question.question_id == 12345
+        assert results[0].question.title == "How to unittest a Flask application?"
+        assert "python" in results[0].question.tags
+        assert "flask" in results[0].question.tags
+
+
+@pytest.mark.asyncio
+async def test_empty_search_results(api):
+    """Test empty search results handling."""
+    empty_response = MagicMock()
+    empty_response.raise_for_status = MagicMock()
+    empty_response.json = MagicMock(return_value={"items": []})
+    
+    with patch.object(httpx.AsyncClient, 'get', return_value=empty_response):
+        results = await api.search_by_query(
+            query="definitely will not find anything 89797979",
+            limit=1
+        )
+        
+        assert isinstance(results, list)
+        assert len(results) == 0
+
+
+@pytest.mark.asyncio
+async def test_search_with_min_score_filtering(api, mock_search_response):
+    """Test that min_score parameter properly filters results."""
+    with patch.object(httpx.AsyncClient, 'get', return_value=mock_search_response):
+        # Should return results (mock score is 25)
+        results_included = await api.search_by_query(
+            query="flask unittest",
+            min_score=20,
+            limit=5
+        )
+        assert len(results_included) == 1
+        
+        # Should filter out results
+        results_filtered = await api.search_by_query(
+            query="flask unittest",
+            min_score=30,
+            limit=5
+        )
+        assert len(results_filtered) == 0
+
+
+@pytest.mark.asyncio
+async def test_search_with_multiple_tags(api, mock_search_response):
+    """Test searching with multiple tags."""
+    with patch.object(httpx.AsyncClient, 'get', return_value=mock_search_response):
+        results = await api.search_by_query(
+            query="test",
+            tags=["python", "flask", "django"],
+            limit=5
+        )
+        
+        # Verify the tags were properly passed to the request
+        call_args = httpx.AsyncClient.get.call_args
+        params = call_args[1]['params']
+        assert 'tagged' in params
+        assert params['tagged'] == "python;flask;django"
+
+
+@pytest.mark.asyncio
+async def test_search_with_excluded_tags(api, mock_search_response):
+    """Test searching with excluded tags."""
+    with patch.object(httpx.AsyncClient, 'get', return_value=mock_search_response):
+        results = await api.search_by_query(
+            query="test",
+            excluded_tags=["javascript", "c#"],
+            limit=5
+        )
+        
+        # Verify the excluded tags were properly passed to the request
+        call_args = httpx.AsyncClient.get.call_args
+        params = call_args[1]['params']
+        assert 'nottagged' in params
+        assert params['nottagged'] == "javascript;c#"
+
+
+@pytest.mark.asyncio
+async def test_search_with_advanced_parameters(api, mock_search_response):
+    """Test advanced search with multiple parameters."""
+    with patch.object(httpx.AsyncClient, 'get', return_value=mock_search_response):
+        results = await api.advanced_search(
+            query="flask test",
+            tags=["python"],
+            title="unittest",
+            has_accepted_answer=True,
+            sort_by="relevance",
+            limit=5
+        )
+        
+        # Verify parameters were properly passed
+        call_args = httpx.AsyncClient.get.call_args
+        params = call_args[1]['params']
+        assert params['q'] == "flask test"
+        assert params['tagged'] == "python"
+        assert params['title'] == "unittest"
+        assert params['accepted'] == "true"
+        assert params['sort'] == "relevance"
+        assert params['pagesize'] == "5"
+
+
+@pytest.mark.asyncio
+async def test_search_api_error(api):
+    """Test handling of API errors."""
+    error_response = MagicMock()
+    error_response.raise_for_status = MagicMock(
+        side_effect=httpx.HTTPStatusError(
+            "500 Internal Server Error",
+            request=MagicMock(),
+            response=MagicMock(status_code=500)
+        )
+    )
+    
+    with patch.object(httpx.AsyncClient, 'get', return_value=error_response):
+        with pytest.raises(httpx.HTTPStatusError):
+            await api.search_by_query("test query")

tests/test_formatter.py

@@ -0,0 +1,109 @@
+import pytest
+from stackoverflow_mcp.formatter import format_response, clean_html
+from stackoverflow_mcp.types import (
+    SearchResult, 
+    StackOverflowQuestion, 
+    StackOverflowAnswer,
+    StackOverflowComment,
+    SearchResultComments
+)
+
+@pytest.fixture
+def sample_result():
+    """Create a sample search result for testing."""
+    question = StackOverflowQuestion(
+        question_id=12345,
+        title="How to test Python code?",
+        body="<p>I'm trying to test my <code>Python</code> code.</p><pre><code>def test():\n    pass</code></pre>",
+        score=10,
+        answer_count=2,
+        is_answered=True,
+        accepted_answer_id=54321,
+        tags=["python", "testing"],
+        link="https://stackoverflow.com/q/12345"
+    )
+    
+    answers = [
+        StackOverflowAnswer(
+            answer_id=54321,
+            question_id=12345,
+            score=5,
+            is_accepted=True,
+            body="<p>You should use <code>pytest</code>.</p>",
+            link="https://stackoverflow.com/a/54321"
+        ),
+        StackOverflowAnswer(
+            answer_id=67890,
+            question_id=12345,
+            score=3,
+            is_accepted=False,
+            body="<p>Another option is <code>unittest</code>.</p>",
+            link="https://stackoverflow.com/a/67890"
+        )
+    ]
+    
+    comments = SearchResultComments(
+        question=[
+            StackOverflowComment(
+                comment_id=111,
+                post_id=12345,
+                score=2,
+                body="Have you tried pytest?"
+            )
+        ],
+        answers={
+            54321: [
+                StackOverflowComment(
+                    comment_id=222,
+                    post_id=54321,
+                    score=1,
+                    body="Great answer!"
+                )
+            ],
+            67890: []
+        }
+    )
+    
+    return SearchResult(
+        question=question,
+        answers=answers,
+        comments=comments
+    )
+
+def test_clean_html():
+    """Test HTML cleaning."""
+    html = "<p>This is <b>bold</b> and <i>italic</i>.</p><code>inline code</code><pre><code>def function():\n    return True</code></pre>"
+    cleaned = clean_html(html)
+    
+    assert "<p>" not in cleaned
+    assert "<b>" not in cleaned
+    assert "<i>" not in cleaned
+    assert "This is bold and italic." in cleaned
+    assert "`inline code`" in cleaned
+    assert "```\ndef function():\n    return True\n```" in cleaned
+
+def test_format_response_markdown(sample_result):
+    """Test formatting as Markdown."""
+    markdown = format_response([sample_result], "markdown")
+    
+    assert "# How to test Python code?" in markdown
+    assert "**Score:** 10" in markdown
+    assert "## Question" in markdown
+    assert "I'm trying to test my `Python` code." in markdown
+    assert "```\ndef test():\n    pass\n```" in markdown
+    assert "### Question Comments" in markdown
+    assert "- Have you tried pytest?" in markdown
+    assert "### ✓ Answer (Score: 5)" in markdown
+    assert "You should use `pytest`." in markdown
+    assert "### Answer (Score: 3)" in markdown
+    assert "Another option is `unittest`." in markdown
+    assert "[View on Stack Overflow](https://stackoverflow.com/q/12345)" in markdown
+
+def test_format_response_json(sample_result):
+    """Test formatting as JSON."""
+    json_str = format_response([sample_result], "json")
+    
+    assert "How to test Python code?" in json_str
+    assert "question_id" in json_str
+    assert "answers" in json_str
+    assert "comments" in json_str

tests/test_general_api_health.py

@@ -0,0 +1,91 @@
+import time
+import pytest
+import asyncio
+import httpx
+from unittest.mock import patch, MagicMock
+from stackoverflow_mcp.api import StackExchangeAPI
+from stackoverflow_mcp.types import StackOverflowQuestion, StackOverflowAnswer, SearchResult
+
+
+@pytest.fixture
+def api():
+    """Create A StackExchangeAPI instance for testing
+    """
+    return StackExchangeAPI(api_key="test_key")
+
+@pytest.fixture
+def mock_response():
+    """Create a mock response for httpx."""
+    
+    response = MagicMock()
+    response.raise_for_status = MagicMock()
+    response.json = MagicMock(return_value={
+        "items" : [
+                        {
+                "question_id": 12345,
+                "title": "Test Question",
+                "body": "Test body",
+                "score": 10,
+                "answer_count": 2,
+                "is_answered": True,
+                "accepted_answer_id": 54321,
+                "creation_date": 1609459200,
+                "tags": ["python", "testing"],
+                "link": "https://stackoverflow.com/q/12345"
+            }
+        ]
+    })
+    return response
+
+@pytest.mark.asyncio
+async def test_search_by_query(api, mock_response):
+    """Test searching by query."""
+    with patch.object(httpx.AsyncClient, 'get', return_value=mock_response):
+        results = await api.search_by_query("test query")
+        
+        assert len(results) == 1
+        assert results[0].question.question_id == 12345
+        assert results[0].question.title == "Test Question"
+        assert isinstance(results[0], SearchResult)
+
+@pytest.mark.asyncio
+async def test_get_question(api, mock_response):
+    """Test getting a specific question."""
+    with patch.object(httpx.AsyncClient, 'get', return_value=mock_response):
+        result = await api.get_question(12345)
+        
+        assert result.question.question_id == 12345
+        assert result.question.title == "Test Question"
+        assert isinstance(result, SearchResult)
+
+@pytest.mark.asyncio
+async def test_rate_limiting(api):
+    """Test rate limiting mechanism."""
+    mock_resp = MagicMock()
+    mock_resp.raise_for_status = MagicMock()
+    mock_resp.json = MagicMock(return_value={"items": []})
+    
+    with patch.object(httpx.AsyncClient, 'get', return_value=mock_resp):
+        api.request_timestamps = [time.time() * 1000  * 1000 for _ in range(30)]
+                
+        with patch('asyncio.sleep') as mock_sleep:
+            try:
+                await api.search_by_query("test")
+            except Exception as e:
+                assert str(e) == "Maximum rate limiting attempts exceeded"
+            mock_sleep.assert_called()
+
+@pytest.mark.asyncio
+async def test_retry_after_429(api):
+    """Test retry behavior after hitting rate limit."""
+    error_resp = MagicMock()
+    error_resp.raise_for_status.side_effect = httpx.HTTPStatusError("Rate limited", request=MagicMock(), response=MagicMock(status_code=429))
+    
+    success_resp = MagicMock()
+    success_resp.raise_for_status = MagicMock()
+    success_resp.json = MagicMock(return_value={"items": []})
+    
+    with patch.object(httpx.AsyncClient, 'get', side_effect=[error_resp, success_resp]):
+        with patch('asyncio.sleep') as mock_sleep:
+            await api.search_by_query("test", retries=1)
+            mock_sleep.assert_called_once()

tests/test_server.py

@@ -0,0 +1,147 @@
+import pytest
+import asyncio
+from unittest.mock import patch, MagicMock, AsyncMock 
+
+from stackoverflow_mcp.server import mcp, search_by_query, search_by_error, get_question, analyze_stack_trace
+from stackoverflow_mcp.types import StackOverflowQuestion, StackOverflowAnswer, SearchResult
+from mcp.server.fastmcp import Context
+
+@pytest.fixture
+def mock_context():
+    """Create a mock context for testing"""
+    context = MagicMock(spec=Context)
+    
+    context.debug = MagicMock()
+    context.info = MagicMock()
+    context.error = MagicMock()
+    context.request_context.lifespan_context.api = AsyncMock()
+   
+    
+    return context
+
+@pytest.fixture
+def mock_search_result():
+    """Create a mock search result for testing"""
+    question = StackOverflowQuestion(
+        question_id=12345,
+        title="Test Question",
+        body="Test body",
+        score=10,
+        answer_count=2,
+        is_answered=True,
+        accepted_answer_id=54321,
+        creation_date=1609459200,
+        tags=["python", "testing"],
+        link="https://stackoverflow.com/q/12345"
+    )
+    
+    answer = StackOverflowAnswer(
+        answer_id=54321,
+        question_id=12345,
+        score=5,
+        is_accepted=True,
+        body="Test answer",
+        creation_date=1609459300,
+        link="https://stackoverflow.com/a/54321"
+    )
+    
+    return SearchResult(
+        question=question,
+        answers=[answer],
+        comments=None
+    )
+
+@pytest.mark.asyncio
+async def test_search_by_query(mock_context, mock_search_result):
+    """Test search by query function"""
+    mock_context.request_context.lifespan_context.api.search_by_query.return_value = [mock_search_result]
+    
+    
+    result = await search_by_query(
+        query="test query",
+        tags=["python"],
+        min_score=5,
+        include_comments=False,
+        response_format="markdown",
+        limit=5,
+        ctx=mock_context
+    )
+    
+    mock_context.request_context.lifespan_context.api.search_by_query.assert_called_once_with(
+        query="test query",
+        tags=["python"],
+        min_score=5,
+        limit=5,
+        include_comments=False
+    )
+    
+    assert "Test Question" in result
+
+@pytest.mark.asyncio
+async def test_search_by_error(mock_context, mock_search_result):
+    """Test search by error function"""
+    mock_context.request_context.lifespan_context.api.search_by_query.return_value = [mock_search_result]
+    
+    result = await search_by_error(
+        error_message="test error",
+        language="python",
+        technologies=["django"],
+        min_score=5,
+        include_comments=False,
+        response_format="markdown",
+        limit=5,
+        ctx=mock_context
+    )
+    
+    mock_context.request_context.lifespan_context.api.search_by_query.assert_called_once_with(
+        query="test error",
+        tags=["python", "django"],
+        min_score=5,
+        limit=5,
+        include_comments=False
+    )
+    
+    assert "Test Question" in result
+
+@pytest.mark.asyncio
+async def test_get_question(mock_context, mock_search_result):
+    """Test get question function"""
+    mock_context.request_context.lifespan_context.api.get_question.return_value = mock_search_result
+    
+    result = await get_question(
+        question_id=12345,
+        include_comments=True,
+        response_format="markdown",
+        ctx=mock_context
+    )
+    
+    mock_context.request_context.lifespan_context.api.get_question.assert_called_once_with(
+        question_id=12345,
+        include_comments=True
+    )
+    
+    assert "Test Question" in result
+
+@pytest.mark.asyncio
+async def test_analyze_stack_trace(mock_context, mock_search_result):
+    """Test analyze stack trace function"""
+    mock_context.request_context.lifespan_context.api.search_by_query.return_value = [mock_search_result]
+    
+    result = await analyze_stack_trace(
+        stack_trace="Error: Something went wrong\n  at Function.Module._resolveFilename",
+        language="javascript",
+        include_comments=True,
+        response_format="markdown",
+        limit=3,
+        ctx=mock_context
+    )
+    
+    mock_context.request_context.lifespan_context.api.search_by_query.assert_called_once_with(
+        query="Error: Something went wrong",
+        tags=["javascript"],
+        min_score=0,
+        limit=3,
+        include_comments=True
+    )
+    
+    assert "Test Question" in result