README.md

---
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](https://www.youtube.com/watch?v=3BKmaAKmGJ4)**

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**
```bash
pip install -r requirements.txt
```

### 2. **Set Up Environment Variables**
```bash
# 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**
```bash
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
```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "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**
```bash
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**
```python
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**
```bash
# Via MCP client
{
  "method": "tools/call",
  "params": {
    "name": "sentiment_analysis",
    "arguments": {
      "text": "This product is absolutely amazing!"
    }
  }
}
```

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

### **Restaurant Search**
```bash
# 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**
```bash
# 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](https://spec.modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Anthropic MCP Documentation](https://docs.anthropic.com/mcp)

---

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