Deploy Gradio MCP client from GitHub Codespaces

README.md

@@ -1,231 +1,19 @@
-# MCP Client Agent
-
-A conversational AI agent powered by [Smolagents](https://github.com/huggingface/smolagents) that connects to remote [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers to access specialized tools. This application provides a user-friendly chat interface built with [Gradio](https://www.gradio.app/) for interacting with AI-powered tools.
-
-## Overview
-
-This application demonstrates how to build an intelligent agent that:
-- Connects to remote MCP servers to discover and use custom tools
-- Uses a large language model (LLM) to reason about which tools to use
-- Executes multi-step reasoning chains to answer complex questions
-- Provides results through an intuitive web-based chat interface
-
-By default, it connects to a sentiment analysis MCP server, but can be configured to work with any MCP server.
-
-## Features
-
-- 🤖 **AI Agent Reasoning**: Uses a code-executing agent to solve complex problems
-- 🔌 **MCP Server Integration**: Dynamically discovers and uses tools from remote MCP servers
-- 💬 **Chat Interface**: Clean, conversational UI powered by Gradio
-- 🔐 **Secure Authentication**: Integrates with Hugging Face Hub for model access
-- ⚡ **GPU Acceleration**: Supports GPU execution for faster inference
-- 🛡️ **Error Handling**: Comprehensive error messages and graceful failure handling
-- 🔄 **Connection Management**: Proper initialization and cleanup of long-lived connections
-
-## Prerequisites
-
-- Python 3.10+ (ZeroGPU supports Python 3.10.13 and 3.12.12)
-- Hugging Face account with API access
-- HF_TOKEN environment variable or local Hugging Face authentication
-
-## Installation
-
-1. **Clone the repository**
-   ```bash
-   git clone <repository-url>
-   cd mcp-client-agent
-   ```
-
-2. **Install dependencies**
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-3. **Set up Hugging Face authentication**
-   ```bash
-   # Option 1: Set environment variable
-   export HF_TOKEN=your_hugging_face_token
-
-   # Option 2: Use Hugging Face CLI
-   huggingface-cli login
-   ```
-
-## Configuration
-
-Configure the application through environment variables:
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `HF_TOKEN` | _(required)_ | Hugging Face API token for model inference |
-| `MCP_SERVER_URL` | `https://zlysunshine-mcp-sentiment.hf.space/gradio_api/mcp/` | URL of the remote MCP server |
-| `MODEL_ID` | `Qwen/Qwen3-Next-80B-A3B-Thinking` | Language model to use for the agent |
-
-### Example Configuration
-
-```bash
-export HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxx"
-export MCP_SERVER_URL="https://your-mcp-server.hf.space/gradio_api/mcp/"
-export MODEL_ID="meta-llama/Llama-3-70b-chat-hf"
-```
-
-## Usage
-
-### Running Locally
-
-```bash
-python app.py
-```
-
-The application will start a Gradio server at `http://localhost:7860`
-
-### Running on Hugging Face Spaces
-
-**Step-by-step deployment guide:**
-
-1. **Create a new Space**
-   - Go to [huggingface.co/spaces](https://huggingface.co/spaces)
-   - Click "Create new Space"
-   - Choose a name for your Space (e.g., `mcp-client-agent`)
-   - Select **Gradio** as the Space SDK
-   - Choose "Public" or "Private" visibility
-   - Click "Create Space"
-
-2. **Upload the repository content**
-   - Clone or download this repository
-   - Push the code to your Space repository:
-     ```bash
-     git clone https://huggingface.co/spaces/[your-username]/[your-space-name]
-     cd [your-space-name]
-     # Copy files from mcp-client-agent
-     cp /path/to/mcp-client-agent/* .
-     git add .
-     git commit -m "Initial commit: MCP client agent"
-     git push
-     ```
-
-3. **Configure secrets**
-   - Go to your Space's Settings → Secrets and variables
-   - Add a new secret:
-     - **Name**: `HF_TOKEN`
-     - **Value**: Your Hugging Face user access token
-   - (Optional) Add other environment variables:
-     - `MCP_SERVER_URL`: Custom MCP server endpoint
-     - `MODEL_ID`: Alternative model for inference
-
-4. **Optional: Configure Space settings**
-   - **Hardware**: Recommend at least CPU, or GPU for faster inference
-   - **Persistent storage**: Enable if you need to save data
-   - **Environment variables**: Add any additional config (see Configuration section)
-
-5. **Deployment**
-   - The Space will automatically build and deploy when you push code
-   - Monitor the build logs in the Space's "Build" tab
-   - Once deployed, your app will be live at `https://huggingface.co/spaces/[your-username]/[your-space-name]`
-
-**Important notes:**
-- ZeroGPU: If you have access to ZeroGPU, the `@spaces.GPU(duration=20)` decorator in `app.py` will automatically use it for faster inference
-- Token security: Never commit your HF_TOKEN to the repository—always use Secrets
-- Server connectivity: Ensure the MCP server URL is accessible from the Space environment
-
-### Interacting with the Agent
-
-1. Open the chat interface
-2. Ask questions that require using the MCP server's tools
-3. The agent will automatically:
-   - Analyze your question
-   - Choose appropriate tools from the MCP server
-   - Execute the tools
-   - Return the results
-
-**Example queries:**
-- "You must use the sentiment_analysis tool to analyze: 'This MCP course is excellent, but deployment was frustrating.'"
-- "Call the sentiment tool for: 'I am happy that the application finally works.'"
-
-## How It Works
-
-### Architecture
-
-```
-User Input
-    ↓
-Gradio Chat Interface
-    ↓
-CodeAgent (Smolagents)
-    ↓
-MCP Client ←→ Remote MCP Server
-    ↓
-Tool Discovery & Execution
-    ↓
-LLM Processing
-    ↓
-Response to User
-```
-
-### Key Components
-
-1. **Gradio Interface**: Provides the web-based chat UI
-2. **CodeAgent**: Orchestrates tool selection and execution
-3. **MCPClient**: Connects to and communicates with MCP servers
-4. **InferenceClientModel**: Interfaces with Hugging Face models for inference
-5. **Tool Discovery**: Automatically discovers available tools from the MCP server
-
-### Process Flow
-
-1. User submits a message through the chat interface
-2. The agent receives the message and available tools
-3. The LLM decides which tools are needed to answer the question
-4. Tools are executed with appropriate parameters
-5. Results are processed and returned to the user
-6. Response is displayed in the chat interface
-
-## Dependencies
-
-- **gradio[mcp]**: Web UI framework with MCP support
-- **smolagents[mcp]**: AI agent library with MCP integration
-- **spaces**: Hugging Face Spaces integration
-- **huggingface_hub**: Hugging Face API client
-
-See `requirements.txt` for version details.
-
-## Troubleshooting
-
-### "No Hugging Face token was found"
-- Ensure `HF_TOKEN` environment variable is set
-- Or run `huggingface-cli login` to save credentials locally
-
-### "The MCP server connected successfully but returned no tools"
-- Verify the `MCP_SERVER_URL` is correct and accessible
-- Check that the MCP server is running and serving tools
-
-### "The MCP client could not complete the request"
-- Check the error details in the response
-- Verify internet connectivity
-- Ensure the MCP server is still running
-- Check that your HF_TOKEN has inference API access
-
-## Development
-
-### Running with Custom MCP Server
-
-```python
-export MCP_SERVER_URL="http://your-server:8000/mcp/"
-python app.py
-```
-
-### Adjusting Agent Parameters
-
-Edit `app.py` to modify:
-- `max_steps`: Maximum reasoning steps (default: 4)
-- `max_tokens`: Maximum token output (default: 1200)
-- `timeout`: Request timeout in seconds (default: 120)
-
-## License
-
-See [LICENSE](LICENSE) for details.
-
-## Resources
-
-- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
-- [Smolagents Documentation](https://huggingface.co/docs/smolagents)
-- [Gradio Documentation](https://www.gradio.app/docs)
-- [Hugging Face Spaces](https://huggingface.co/spaces)
+---
+title: Gradio MCP Client Agent
+emoji: 🤖
+colorFrom: purple
+colorTo: blue
+sdk: gradio
+sdk_version: "6.20.0"
+python_version: "3.10"
+app_file: app.py
+pinned: false
+short_description: A Gradio agent that consumes tools from a remote MCP server.
+tags:
+  - mcp
+  - gradio
+  - smolagents
+  - agent
+---
+
+# -mcp-client-agent