---
title: VOYAGER AI
emoji: 🌍
colorFrom: gray
colorTo: green
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
short_description: "AI MCP client: intelligent task decomposition & agents"
tags:
  - agent-demo-track
---

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

# 💻 Enhanced MCP Client - AI-Powered Task Decomposition Interface

A sophisticated AI-enhanced client application that connects to MCP servers and provides intelligent task decomposition, agent coordination, and a beautiful Gradio web interface.

## 🎯 **What is this?**

This is an **AI-powered MCP client** that transforms how you interact with MCP (Model Context Protocol) servers by providing:

- 🧠 **AI Task Decomposition** - Claude Sonnet 4 analyzes complex queries
- 🎯 **Smart Agent Routing** - Intelligent assignment of tasks to specialized agents
- 📊 **Performance Monitoring** - Real-time tracking of agent usage and response times
- 🎨 **Modern Gradio UI** - Beautiful, intuitive web interface
- 🔄 **MCP Protocol Support** - Native connectivity to any MCP server
- 💡 **Query Insights** - See how your queries are analyzed and processed

## ✨ **Key Features**

### **🧠 AI-Powered Intelligence**
- **Claude Sonnet 4 Integration**: Advanced query understanding and decomposition
- **Dynamic Task Analysis**: Automatically breaks down complex multi-part queries
- **Context Awareness**: Understands intent, location, and complexity
- **Confidence Scoring**: Evaluates task assignment reliability

### **🤖 Specialized Agent System**
- **Sentiment Agent**: Analyzes text emotion and sentiment
- **Place Agent**: Finds hotels, accommodations, and lodging
- **Restaurant Agent**: Discovers dining options and restaurants  
- **Hiking Agent**: Locates trails and outdoor activities
- **Web Agent**: Searches the internet for information

### **📊 Advanced Coordination**
- **Enhanced Coordinator**: Orchestrates multiple agents intelligently
- **Performance Tracking**: Monitors response times and success rates
- **Parallel Execution**: Handles multiple tasks simultaneously
- **Error Handling**: Graceful degradation and retry logic

## 🚀 **Quick Start**

### 1. **Install Dependencies**
```bash
pip install -r requirements.txt
```

### 2. **Set Up Environment Variables**
```bash
# Required for AI features
export ANTHROPIC_API_KEY="your_anthropic_api_key"

# Optional for enhanced location services
export FOURSQUARE_API_KEY="your_foursquare_api_key"
```

### 3. **Start the Client**
```bash
python client.py
```

### 4. **Access the Web Interface**
Open your browser to: `http://localhost:7860`

## 🎨 **Web Interface**

### **💬 Enhanced Chat Tab**
- **Smart Query Processing**: Enter natural language queries
- **Real-time Analysis**: See how your query is decomposed
- **Rich Responses**: Beautiful formatted results from multiple agents
- **Example Queries**: Pre-built examples to get started

### **🛠️ MCP Tools Tab**
- **Direct Tool Access**: Execute MCP tools directly
- **Tool Discovery**: Browse available MCP server tools
- **Parameter Input**: JSON-based tool parameter configuration
- **Real-time Results**: Immediate tool execution feedback

### **📊 Performance Dashboard**
- **Agent Statistics**: Usage patterns and performance metrics
- **Response Times**: Average execution times per agent
- **Success Rates**: Reliability tracking across agents
- **MCP Connection Status**: Monitor server connectivity

### **⚙️ Advanced Settings**
- **Model Configuration**: Select AI models (currently Anthropic)
- **MCP Server Setup**: Configure connection to any MCP server
- **Connection Management**: Reconnect and test connections

## 🔧 **Configuration**

### **Command Line Options**
```bash
python client.py --help

Options:
  --model {anthropic}     AI model to use (default: anthropic)
  --server-url TEXT       MCP server URL (default: http://localhost:7861/gradio_api/mcp/sse)
```

### **Environment Variables**
- `ANTHROPIC_API_KEY` - **Required** for AI task decomposition
- `FOURSQUARE_API_KEY` - Optional for enhanced place search

### **MCP Server Connection**
The client can connect to any MCP-compatible server:
```bash
# Local server
python client.py --server-url "http://localhost:7861/gradio_api/mcp/sse"

# Remote server
python client.py --server-url "http://remote-host:7861/gradio_api/mcp/sse"

# Custom configuration
python client.py --model anthropic --server-url "http://custom-server:8080/mcp"
```

## 🏗️ **Architecture**

```
mcp_client/
├── client.py                   # Main application with LLM integration
├── app.py                      # HuggingFace Spaces entry point
├── agents/                     # AI Agent System
│   ├── enhanced_coordinator.py # Smart coordination logic
│   ├── task_analyzer.py       # AI-powered query analysis
│   ├── sentiment_agent.py     # Sentiment analysis
│   ├── place_agent.py         # Place/hotel search
│   ├── restaurant_agent.py    # Restaurant search
│   ├── hiking_agent.py        # Hiking trail search
│   ├── web_agent.py           # Web search
│   └── base_agent.py          # Agent foundation
├── services/                   # Backend Services
│   ├── place_service.py       # Place search API
│   ├── restaurant_service.py  # Restaurant search API
│   └── hiking_service.py      # Hiking trail API
└── utils/
    └── api_config.py          # Configuration management
```

## 💡 **Usage Examples**

### **Complex Multi-Agent Queries**
```
"Find hotels and restaurants in Paris with hiking trails nearby"
```
**What happens:**
1. 🔍 **Claude Sonnet 4** breaks down the query into 3 components
2. 🏨 **Place Agent** finds hotels in Paris
3. 🍽️ **Restaurant Agent** discovers dining options
4. 🥾 **Hiking Agent** locates nearby trails
5. 🧠 **Coordinator** combines and formats results

### **Simple Single-Agent Tasks**
```
"What's the weather like in Tokyo today?"
```
**What happens:**
1. 🔍 **Claude Sonnet 4** identifies this as a web search task
2. 🌐 **Web Agent** searches for Tokyo weather information
3. 📊 **Coordinator** returns formatted weather data

### **Sentiment Analysis**
```
"Analyze sentiment: This product is absolutely amazing and exceeded all my expectations!"
```
**What happens:**
1. 🔍 **Claude Sonnet 4** identifies sentiment analysis task
2. 😊 **Sentiment Agent** analyzes the emotional tone
3. 📈 **Returns** detailed sentiment breakdown with confidence scores

## 🎯 **Smart Features**

### **🧠 AI Query Analysis**
The task analyzer provides insights into:
- **Query Complexity**: Simple, moderate, or complex
- **Primary Intent**: Main goal of the query
- **Location Detection**: Automatic location extraction
- **Agent Assignment**: Which agents should handle which parts
- **Confidence Scores**: Reliability of task assignments

### **📊 Performance Monitoring**
Track real-time metrics:
- **Total Queries Processed**: Overall usage statistics
- **Success/Failure Rates**: Reliability tracking
- **Average Response Times**: Performance monitoring
- **Agent Usage Patterns**: Most/least used agents
- **Error Analysis**: Common failure modes

## 🛠️ **Customization**

### **Adding New Agents**
1. Create a new agent class inheriting from `BaseAgent`
2. Implement the required methods
3. Add to the agent list in `client.py`

### **Connecting to Different MCP Servers**
The client is designed to work with any MCP-compatible server:
- Standard MCP protocol support
- Automatic tool discovery
- Dynamic schema adaptation
- Error handling for server differences

### **UI Customization**
The Gradio interface can be customized:
- Themes and styling
- Additional tabs and components
- Custom visualizations
- Branding and layout

## 🐛 **Troubleshooting**

### **Common Issues**

1. **Client won't start**
   - Check Python version (3.8+ required)
   - Install dependencies: `pip install -r requirements.txt`
   - Verify Anthropic API key is set

2. **AI features not working**
   - Ensure `ANTHROPIC_API_KEY` is configured
   - Check internet connectivity
   - Verify API key has sufficient credits

3. **MCP server connection fails**
   - Check MCP server is running
   - Verify server command path
   - Test with `--mcp-server` parameter

4. **Agents return errors**
   - Check individual API keys (Foursquare, etc.)
   - Verify internet connection
   - Review agent-specific error messages

### **Debug Mode**
```bash
# Start with verbose logging
python client.py --debug
```

## 📦 **Dependencies**

### **Core Dependencies**
- `gradio` - Web interface framework
- `smolagents` - AI agent framework with MCP support
- `anthropic` - Claude AI integration
- `requests` - HTTP client for APIs
- `asyncio` - Async programming support

### **Optional Dependencies**
- `foursquare` - Enhanced place search
- `beautifulsoup4` - Web scraping (for web agent)
- `selenium` - Advanced web automation

## 🤝 **Integration**

### **MCP Server Compatibility**
Works with any server implementing MCP protocol:
- ✅ Standard MCP servers
- ✅ Custom MCP implementations
- ✅ Third-party MCP services
- ✅ Cloud-hosted MCP servers

### **AI Model Support**
Currently supports:
- ✅ **Anthropic Claude Sonnet 4** (primary)
- 🔄 **Additional models** (coming soon)

### **Extension Points**
- Custom agent development
- Additional AI model backends
- Enhanced UI components
- Custom MCP server adapters

## 📄 **License**

MIT License - Free to use and modify!

## 🔗 **Related Resources**

- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
- [Anthropic AI Documentation](https://docs.anthropic.com/)
- [Gradio Documentation](https://gradio.app/docs/)
- [SmoLAgents Framework](https://github.com/huggingface/smolagents)

## 🎬 **Demo & Videos**

- [📺 VOYAGER AI Demo Video](https://www.youtube.com/watch?v=yrfhYyy0nIo) - Watch the application in action!

---

**Experience the future of AI-powered task coordination with MCP!** 🚀