README.md

metadata

title: VOYAGER AI mcp server
emoji: 🐠
colorFrom: pink
colorTo: gray
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
short_description: 'AI MCP server: sentiment, places, dining, hiking, web search'
tags:
  - mcp-server-track

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

🖥️ MCP Server - Model Context Protocol Server

A powerful MCP (Model Context Protocol) server that exposes 5 specialized tools for AI agents and applications.

🎯 What is this?

This is a pure MCP protocol server that provides AI agents with access to:

• 😊 Sentiment Analysis - Analyze text sentiment and emotion
• 🏨 Place Search - Find hotels and accommodations
• 🍽️ Restaurant Search - Discover restaurants and dining options
• 🥾 Hiking Trails - Find outdoor activities and hiking trails
• 🌐 Web Search - Search the internet for information

🎬 Demo Video

🎥 Watch the MCP Server Demo on YouTube

See the MCP Server in action! This demo showcases all 5 tools and how they work with AI agents through the Model Context Protocol.

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Set Up Environment Variables

# Required for web search and place services
export ANTHROPIC_API_KEY="your_anthropic_api_key"
export FOURSQUARE_API_KEY="your_foursquare_api_key"  # Optional

3. Start the Server

python start_server.py

The server will start and listen for MCP protocol connections via stdio.

🛠️ Available Tools

1. Sentiment Analysis (sentiment_analysis)

Purpose: Analyze the emotional tone and sentiment of text

{
  "name": "sentiment_analysis",
  "description": "Analyze sentiment and emotion in text",
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string",
        "description": "Text to analyze"
      }
    },
    "required": ["text"]
  }
}

2. Place Search (place_search)

Purpose: Find hotels, accommodations, and lodging

{
  "name": "place_search",
  "description": "Search for hotels and accommodations",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "Location to search for places"
      },
      "max_distance": {
        "type": "integer",
        "description": "Maximum distance in miles",
        "default": 10
      }
    },
    "required": ["location"]
  }
}

3. Restaurant Search (restaurant_search)

Purpose: Find restaurants and dining options

{
  "name": "restaurant_search",
  "description": "Search for restaurants and dining options",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "Location to search for restaurants"
      },
      "cuisine": {
        "type": "string",
        "description": "Type of cuisine (optional)"
      }
    },
    "required": ["location"]
  }
}

4. Hiking Search (hiking_search)

Purpose: Find hiking trails and outdoor activities

{
  "name": "hiking_search",
  "description": "Search for hiking trails and outdoor activities",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "Location to search for hiking trails"
      },
      "difficulty": {
        "type": "string",
        "description": "Difficulty level: Easy, Moderate, Hard, Very Hard",
        "default": "All"
      },
      "max_distance": {
        "type": "integer",
        "description": "Maximum distance in miles",
        "default": 50
      }
    },
    "required": ["location"]
  }
}

5. Web Search (web_search)

Purpose: Search the internet for information

{
  "name": "web_search",
  "description": "Search the web for information",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "max_results": {
        "type": "integer",
        "description": "Maximum number of results",
        "default": 5
      }
    },
    "required": ["query"]
  }
}

🔧 Configuration

Environment Variables

• ANTHROPIC_API_KEY - Required for AI-powered features
• FOURSQUARE_API_KEY - Optional, for enhanced place search

Command Line Options

python start_server.py --info    # Show server information

🏗️ Architecture

mcp_server/
├── server.py              # Main MCP server implementation
├── start_server.py        # Startup script
├── tools/                 # Tool implementations
│   ├── sentiment_tool.py  # Sentiment analysis
│   ├── place_tool.py      # Place search
│   ├── restaurant_tool.py # Restaurant search
│   ├── hiking_tool.py     # Hiking search
│   └── web_search_tool.py # Web search
└── utils/
    └── api_config.py      # API configuration

📡 MCP Protocol Details

This server implements the Model Context Protocol (MCP) using:

• Transport: stdio (standard input/output)
• Protocol: JSON-RPC based MCP messages
• Capabilities: Tool calling, resource listing

Connection Example

from smolagents.mcp_client import MCPClient

# Connect to this server
client = MCPClient()
await client.connect("python server.py")

# List available tools
tools = await client.list_tools()

# Call a tool
result = await client.call_tool("sentiment_analysis", {"text": "I love this!"})

🔍 Usage Examples

Sentiment Analysis

# Via MCP client
{
  "method": "tools/call",
  "params": {
    "name": "sentiment_analysis",
    "arguments": {
      "text": "This product is absolutely amazing!"
    }
  }
}

Place Search

# Find hotels in Paris
{
  "method": "tools/call",
  "params": {
    "name": "place_search",
    "arguments": {
      "location": "Paris",
      "max_distance": 5
    }
  }
}

Restaurant Search

# Find Italian restaurants in New York
{
  "method": "tools/call",
  "params": {
    "name": "restaurant_search",
    "arguments": {
      "location": "New York",
      "cuisine": "Italian"
    }
  }
}

🚦 Server Status

The server provides health checks and status information:

• ✅ Running: Server is active and accepting connections
• 🛠️ Tools: 5 tools available and functional
• 🔑 APIs: Configuration status for external APIs

🐛 Troubleshooting

Common Issues

1. Server won't start

   • Check Python version (3.8+ required)
   • Verify dependencies: pip install -r requirements.txt

2. Tool execution fails

   • Check API keys are set correctly
   • Verify internet connection for external APIs

3. MCP client can't connect

   • Ensure server is running
   • Check the server command path

Debug Mode

# Start with verbose output
python server.py --debug

📦 Dependencies

• mcp - Model Context Protocol library
• asyncio - Async programming support
• requests - HTTP client for external APIs
• json - JSON handling
• os - Environment variable access

🤝 Integration

This MCP server can be used with:

• MCP Clients - Any application supporting MCP protocol
• AI Agents - Claude, GPT, or custom agents
• Gradio Apps - With built-in MCP support
• Custom Applications - Via MCP client libraries

📄 License

MIT License - Feel free to use and modify!

🔗 Related

• Model Context Protocol Specification
• MCP Python SDK
• Anthropic MCP Documentation

---

Ready to expose powerful tools to AI agents via the Model Context Protocol! 🚀