Hugging Face's logo

Spaces:
MCP-1st-Birthday
/
ecomcp
Running

App Files Community
ecomcp / docs /README_ENHANCED.md
vinhnx90's picture
vinhnx90
docs: Remove `docs/` and `../` prefixes from internal links across documentation files.
d12052d
preview code
|
raw
history blame contribute delete
11.5 kB

A newer version of the Gradio SDK is available: 6.1.0

Upgrade
metadata
title: MCP Research Server - Building MCP Track
emoji: null
colorFrom: indigo
colorTo: red
sdk: gradio
pinned: true
tags:
  - building-mcp-track-consumer
  - mcp
  - agents
  - gradio6

MCP Research Server

A fully functional Model Context Protocol (MCP) server demonstrating real-time research workflows with multiple integrated tools, seamless Claude Desktop integration, and a polished Gradio 6 interface.

Project Overview

This submission for the MCP 1st Birthday Hackathon - Track 1: Building MCP showcases a production-ready MCP server that can:

  • Execute complex research workflows using multiple coordinated tools
  • Integrate directly with Claude Desktop and other MCP clients
  • Stream real-time progress updates through Gradio
  • Handle asynchronous tool orchestration efficiently

Track Information

  • Track: Building MCP (Track 1)
  • Category: Consumer Applications
  • Track Tag: building-mcp-track-consumer
  • Hackathon: MCP 1st Birthday (Nov 14-30, 2025)

Key Features

Functional MCP Server

  • JSON-RPC 2.0 Protocol - Complete compliance with MCP standards
  • Stdio Transport - Standard MCP transport mechanism for client integration
  • Tool Discovery - Dynamic capability advertisement to clients
  • Async Processing - Efficient non-blocking execution of tools

Integrated Tools (4 Core Tools)

  1. Web Search Tool (web_search)

    • Search for information on any topic
    • Returns structured results with titles, URLs, and snippets
    • Configurable result limit (1-10 results)

  2. Content Analysis Tool (analyze_content)

    • Multiple analysis types: summary, keypoints, sentiment, entities
    • Extract key insights from documents
    • Intelligent entity recognition

  3. Content Synthesis Tool (synthesize_sources)

    • Combine insights from multiple sources
    • Maintain context and relationships
    • Generate coherent narratives

  4. Report Generator Tool (generate_report)

    • Create structured, formatted reports
    • Support for multiple output formats (Markdown, HTML, Plain Text)
    • Professional report formatting

Modern UI/UX

  • Gradio 6 Interface - Latest Gradio features and responsive design
  • Real-time Streaming - Live progress updates during research
  • Tool Visualization - Clear display of tool execution steps
  • Example Queries - Pre-built examples for easy exploration
  • Mobile Responsive - Works seamlessly on all devices

Multi-Client Integration

  • Claude Desktop - Full integration with configuration guide
  • Cursor IDE - Can be configured as custom MCP server
  • Standard MCP Clients - Compatible with any MCP-compliant client
  • Easy Setup - Simple configuration files provided

Architecture

System Components 


                     MCP Clients                             
  (Claude Desktop, Cursor, Gradio, Custom Clients)          

                        ↓
                   (JSON-RPC 2.0)
                        ↓

                  MCP Server Core                            
  (mcp_server.py - Async JSON-RPC Handler)                 

                        ↓
        
        ↓               ↓               ↓
            
      Web        Document      Content  
     Search      Analyzer     Synthesizer
            
        ↓
    
       Report   
     Generator

Request Flow 

Query Input
   ↓
[MCP Client] Initialize Connection
   ↓
Request Tool List
   ↓
Call Tool: web_search
   ↓
Call Tool: analyze_content
   ↓
Call Tool: synthesize_sources
   ↓
Call Tool: generate_report
   ↓
Stream Response Back to Client

Technology Stack

  • Language: Python 3.9+
  • MCP Protocol: JSON-RPC 2.0 over stdio
  • Framework: Gradio 6.0+
  • Async Runtime: asyncio
  • Type Safety: Pydantic
  • Transport: Standard process stdio

Quick Start

Installation 

# Clone the repository
git clone <your-repo-url>
cd ecomcp

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Run the Gradio Interface 

python app_enhanced.py

Then open http://localhost:7860 in your browser.

Standalone MCP Server 

python mcp_server.py

Server will start listening on stdin for JSON-RPC messages.

Claude Desktop Integration

  1. Follow the detailed guide in CLAUDE_DESKTOP_SETUP.md
  2. Update your Claude configuration file
  3. Restart Claude Desktop
  4. Start using research tools directly in conversations

Demo & Usage

Example Queries

  1. "Research the latest advances in quantum computing"

    • Demonstrates web search tool
    • Shows content analysis
    • Generates comprehensive report

  2. "Find information about renewable energy and synthesize findings"

    • Multiple source integration
    • Content synthesis
    • Professional report output

  3. "Analyze AI ethics and create a structured report"

    • Full workflow demonstration
    • Report generation
    • Real-time progress updates

Using in Claude Desktop 

You: "Search for information about machine learning in healthcare and create a research report."

Claude: [Uses web_search tool to find sources]
Claude: [Uses analyze_content to extract insights]
Claude: [Uses synthesize_sources to combine findings]
Claude: [Uses generate_report to create formatted output]

Claude: "Here's your research report on machine learning in healthcare..."

Project Structure 

ecomcp/
 mcp_server.py                 # Standalone MCP server implementation
 app_enhanced.py               # Main Gradio 6 web interface
 app.py                        # Original implementation (legacy)
 requirements.txt              # Python dependencies
 README.md                     # This file
 CLAUDE_DESKTOP_SETUP.md       # Claude Desktop integration guide
 DEPLOYMENT_GUIDE.md           # Deployment instructions
 docs/
    implementation.md         # Technical implementation details
 tests/                        # Test suite (optional)
 utils/                        # Utility modules (optional)

Configuration

Environment Variables

Create a .env file for optional configuration:

# MCP Server settings
MCP_MAX_RESULTS=10
MCP_TIMEOUT=30
MCP_DEBUG=False

# Logging
LOG_LEVEL=INFO
LOG_FILE=mcp_server.log

# API Keys (if using real APIs in production)
OPENAI_API_KEY=your_key_here
SERPAPI_KEY=your_key_here

Claude Desktop Configuration

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "research": {
      "command": "python",
      "args": ["/path/to/ecomcp/mcp_server.py"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Documentation

User Guide

Technical Documentation

Development

Demo Video

Watch the 3-minute demo video

The demo shows:

  1. MCP server initialization
  2. Gradio interface in action
  3. Real research workflow execution
  4. Claude Desktop integration
  5. Report generation

Social Media

Share your thoughts about this project:

Original Post: [Link to your social media post]

Testing

Manual Testing 

# Test MCP server directly
python mcp_server.py

# In another terminal, send a test request:
echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | python -m json.tool

Test with Gradio Interface 

python app_enhanced.py
# Try the example queries in the interface

Test Claude Desktop Integration

  1. Ensure MCP server is configured correctly
  2. Restart Claude Desktop
  3. Ask Claude to "search for..." or "research..."
  4. Monitor tool execution

Troubleshooting

MCP Server Won't Start

  • Check Python version (3.9+ required)
  • Verify all dependencies: pip install -r requirements.txt
  • Check for syntax errors: python -m py_compile mcp_server.py

Gradio Interface Issues

  • Ensure port 7860 is available
  • Try: python app_enhanced.py --share
  • Check browser console for errors

Claude Desktop Integration Not Working

  • Verify config file path and syntax
  • Check the actual Python executable path
  • Review Claude logs in ~/.config/Claude/logs/
  • Restart Claude Desktop after configuration changes

Tool Execution Fails

  • Check network connectivity (for actual APIs)
  • Verify tool parameters match schema
  • Review server logs for detailed errors

Hackathon Submission

Requirements Met

  • Functioning MCP Server: Full JSON-RPC 2.0 implementation
  • Multiple Tools: 4 integrated tools with clear specifications
  • Gradio Interface: Modern Gradio 6 web application
  • Claude Desktop Integration: Complete setup guide
  • Demo Video: Shows server in action with client integration
  • Documentation: Comprehensive guides and API docs
  • Real-world Impact: Applicable for research, analysis, and content creation

Evaluation Criteria

  • Design/UX: Polished Gradio 6 interface with responsive design
  • Functionality: Full MCP protocol compliance and multi-tool orchestration
  • Creativity: Novel approach to tool chaining and synthesis
  • Documentation: Extensive guides and technical documentation
  • Real-world Impact: Enterprise and consumer research applications

Contributing

Contributions are welcome! To contribute:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Commit (git commit -m 'Add amazing feature')
  5. Push to branch (git push origin feature/amazing-feature)
  6. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Anthropic - For creating the Model Context Protocol
  • Hugging Face - For hosting and the Gradio framework
  • Gradio Team - For Gradio 6 with enhanced capabilities
  • MCP Community - For inspiration and support

Support

Links

Project Status: Complete and Production-Ready

Last Updated: November 2025

Version: 1.0.0

Built for the MCP 1st Birthday Hackathon - Track 1: Building MCP