fix readme

README.md

@@ -10,63 +10,109 @@ pinned: false
 short_description: A minimal Gradio MCP server that provides timezone-aware dat
 ---
 
-# Berlin Time MCP Server
+# Berlin Time & World Time MCP Servers
 
-A simple MCP (Model Context Protocol) server built with Gradio that provides current Berlin time to AI agents.
+This directory contains two example MCP (Model Context Protocol) servers built with Gradio.
 
-## What is this?
+## 📂 Available Servers
 
-This is a demonstration MCP server that exposes a single tool: `get_berlin_time`. AI agents can connect to this server and call this tool when they need to know the current time in Berlin, Germany.
+### 1. Simple Berlin Time (`app_time_mcp_server.py`)
+- **Function:** Returns current time in Berlin.
+- **Complexity:** Simple, no parameters.
+- **Port:** 7860
+- **Best for:** Learning the basics of MCP.
 
-## Local Testing
+### 2. World Time (`app_world_time_mcp_server.py`)
+- **Function:** Returns current time for 25+ major cities.
+- **Complexity:** Takes a `city` parameter (e.g., "Tokyo", "New York").
+- **Port:** 7860 (when deployed) / 7861 (local dev).
+- **Best for:** Demonstrating tool arguments and dynamic responses.
+
+---
+
+## 🚀 Local Testing
 
 1. Install dependencies:
 ```bash
 pip install -r requirements.txt
 ```
 
-2. Run the server:
+2. Run the server of your choice:
+
+**Option A: Berlin Time**
 ```bash
 python app_time_mcp_server.py
+# Runs on http://localhost:7860
+```
+
+**Option B: World Time**
+```bash
+python app_world_time_mcp_server.py
+# Runs on http://localhost:7861 (to avoid conflict)
 ```
 
-3. Open your browser to `http://localhost:7860` to test the tool manually.
+3. Open the URL in your browser to test the UI manually.
+
+---
 
-## Deploying to HuggingFace Spaces
+## ☁️ Deploying to HuggingFace Spaces
 
 1. Create a new Space at [huggingface.co/spaces](https://huggingface.co/spaces)
-2. Choose "Gradio" as the SDK
-3. Upload these files:
-   - `app_time_mcp_server.py` (rename to `app.py` for HF Spaces)
-   - `requirements.txt`
-4. Your Space will automatically deploy!
+2. Choose **Gradio** as the SDK.
+3. Upload your files.
 
-## Using with AI Agents
+### ⚠️ IMPORTANT: Deployment Checklist
 
-Once deployed, AI agents can connect to this MCP server and use the `get_berlin_time` tool.
+#### 1. Configure the Entry File (The "Pro" Way)
+Instead of renaming your file to `app.py`, you can tell HuggingFace which file to run by editing the **YAML Header** at the very top of your `README.md` in the Space.
 
-### Example with LangGraph
+**For Berlin Time:**
+```yaml
+---
+title: Berlin Time MCP
+emoji: 🕐
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: 5.0.0
+app_file: app_time_mcp_server.py  <-- CHANGE THIS
+pinned: false
+---
+```
 
-See the main guide for detailed integration instructions.
+**For World Time:**
+```yaml
+---
+title: World Time MCP
+emoji: 🌍
+colorFrom: green
+colorTo: blue
+sdk: gradio
+sdk_version: 5.0.0
+app_file: app_world_time_mcp_server.py  <-- CHANGE THIS
+pinned: false
+---
+```
+
+#### 2. Check the Port
+HuggingFace Spaces **REQUIRES** the app to run on port **7860**.
+- If you use `app_world_time_mcp_server.py`, **change `server_port=7861` to `server_port=7860`** in the code before deploying.
+- If you don't do this, you will get an `OSError: Cannot find empty port`.
 
-## Tool Details
+### Configuration for Your Agent
 
-**Function:** `get_berlin_time()`
+Once deployed, update your `src/config/settings.py`:
 
-**Returns:**
-```json
-{
-  "time": "2025-12-04 17:00:57 CET",
-  "timezone": "Europe/Berlin",
-  "timestamp": "2025-12-04T17:00:57+01:00",
-  "utc_offset": "+0100",
-  "day_of_week": "Wednesday",
-  "is_dst": false
+```python
+servers["berlin_time"] = {
+    "url": "https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME/gradio_api/mcp/",
+    "transport": "sse"
 }
 ```
 
-## Future Improvements
+---
+
+## 📚 Documentation
 
-- Add support for multiple timezones
-- Add time conversion tools
-- Add timezone difference calculator
+- [Step-by-Step Guide](STEP_BY_STEP_GUIDE.md): Detailed teaching guide.
+- [MCP Connection Flow](../.gemini/antigravity/brain/26cb67ea-9995-44cc-8251-52a912873dc8/mcp_connection_flow.md): Visual diagram of how it works.

STEP_BY_STEP_GUIDE.md

@@ -1,339 +1,159 @@
-# Step-by-Step Guide: Berlin Time MCP Server
+# Step-by-Step Guide: Building & Deploying MCP Servers
 
 ## ✅ What We've Built
 
-You now have a complete, working MCP server in `external_mcp_servers/` with:
-- `app_time_mcp_server.py` - The main server application
-- `requirements.txt` - Dependencies (gradio, pytz)
-- `README.md` - Documentation
-- `.gitignore` - Git configuration
+You now have **two** working MCP server examples in `external_mcp_servers/`:
 
-## 🎯 Current Status
+1. **`app_time_mcp_server.py`** (Original)
+   - Simple, parameter-less tool.
+   - Returns Berlin time only.
+   - Great for first-time understanding.
 
-**Server is running at:** http://localhost:7860
-
-The server is now:
-1. ✅ Providing a web UI for manual testing
-2. ✅ Exposing an MCP endpoint at: `http://localhost:7860/gradio_api/mcp/`
-3. ✅ Ready to be called by AI agents
+2. **`app_world_time_mcp_server.py`** (Upgraded)
+   - Accepts a `city` parameter.
+   - Returns time for 25+ cities.
+   - Demonstrates how LLMs pass arguments to tools.
 
 ---
 
-## 📚 Understanding Each Component
+## 📚 Understanding the Components
 
-### 1. The Core Function: `get_berlin_time()`
+### 1. The Core Function
 
+**Simple (Berlin):**
 ```python
 def get_berlin_time():
-    berlin_tz = pytz.timezone('Europe/Berlin')
-    current_time = datetime.now(berlin_tz)
-    # ... returns structured data
+    # No arguments needed
+    return {"time": "..."}
 ```
 
-**What it does:**
-- Creates a timezone object for Berlin
-- Gets the current time in that timezone
-- Returns a dictionary with multiple time formats
-
-**Why return a dictionary?**
-- AI agents can choose which format they need
-- Includes both human-readable and machine-readable formats
-- Provides extra context (day of week, DST status)
+**Advanced (World):**
+```python
+def get_time_for_city(city: str = "Berlin"):
+    # Takes an argument!
+    # LLM will send: {"city": "Tokyo"}
+    return {"city": "Tokyo", "time": "..."}
+```
 
 ### 2. The Gradio Interface
 
 ```python
 demo = gr.Interface(
-    fn=get_berlin_time,
-    inputs=None,
-    outputs=gr.JSON(label="Berlin Time Information"),
-    ...
+    fn=get_time_for_city,
+    inputs=gr.Textbox(...),  # Defines input schema for MCP
+    outputs=gr.JSON(...),
+    api_name="get_time_for_city"
 )
 ```
 
-**What this does:**
-- `fn=get_berlin_time` - The function to expose
-- `inputs=None` - No parameters needed (simple tool)
-- `outputs=gr.JSON()` - Returns JSON data
-- Creates both a UI and an API endpoint
-
-### 3. The MCP Magic: `mcp_server=True`
+### 3. The MCP Magic
 
 ```python
 demo.launch(mcp_server=True)
 ```
-
-**This single parameter:**
-- Starts the normal Gradio UI (for testing)
-- **ALSO** starts an MCP protocol server
-- Automatically creates MCP tool definitions
-- Handles all MCP communication
-
-**What happens behind the scenes:**
-1. Gradio analyzes your function signature
-2. Creates an MCP tool definition with:
-   - Tool name: `get_berlin_time`
-   - Input schema: (none in this case)
-   - Output schema: (JSON object)
-3. Exposes an MCP endpoint that AI agents can connect to
-
----
-
-## 🧪 Testing Locally
-
-### Method 1: Web UI (Manual Testing)
-
-1. **Server is already running** at http://localhost:7860
-2. Open your browser to that URL
-3. Click the "Submit" button
-4. You'll see JSON output like:
-```json
-{
-  "time": "2025-12-04 17:00:57 CET",
-  "timezone": "Europe/Berlin",
-  "timestamp": "2025-12-04T17:00:57+01:00",
-  "utc_offset": "+0100",
-  "day_of_week": "Wednesday",
-  "is_dst": false
-}
-```
-
-### Method 2: MCP Protocol (AI Agent Testing)
-
-The MCP endpoint is at: `http://localhost:7860/gradio_api/mcp/`
-
-AI agents can connect to this endpoint and:
-1. Discover available tools
-2. Call `get_berlin_time`
-3. Receive the structured response
+This single line turns your web app into an AI tool server!
 
 ---
 
-## 🚀 Deploying to HuggingFace Spaces
+## 🚀 Deploying to HuggingFace Spaces (Critical Details)
 
-### Step 1: Prepare Files
+Deploying is easy, but there are **two common pitfalls** to watch out for.
 
-When deploying to HF Spaces, you need to rename `app_time_mcp_server.py` to `app.py`:
+### Step 1: Configure the Entry File
 
-```bash
-# In the external_mcp_servers directory
-cp app_time_mcp_server.py app.py
-```
-
-### Step 2: Create a HuggingFace Space
-
-1. Go to https://huggingface.co/spaces
-2. Click "Create new Space"
-3. Fill in:
-   - **Name:** `berlin-time-mcp` (or your choice)
-   - **License:** Choose one (e.g., MIT)
-   - **SDK:** Select **Gradio**
-   - **Visibility:** Public or Private
-
-### Step 3: Upload Files
+You don't need to rename your file to `app.py`! You can tell HuggingFace which file to run.
 
-You have two options:
+1. Go to your Space's **Files** tab.
+2. Click on `README.md` to edit it.
+3. Look at the **YAML Header** (the metadata at the top between `---`).
+4. Change the `app_file` line:
 
-**Option A: Git Push (Recommended)**
-```bash
-cd external_mcp_servers
-git init
-git add app.py requirements.txt README.md
-git commit -m "Initial MCP server"
-git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/berlin-time-mcp
-git push hf main
+**For Berlin Time:**
+```yaml
+app_file: app_time_mcp_server.py
 ```
 
-**Option B: Web Upload**
-1. In your Space, click "Files" tab
-2. Upload:
-   - `app.py` (renamed from app_time_mcp_server.py)
-   - `requirements.txt`
-   - `README.md` (optional)
-
-### Step 4: Automatic Deployment
-
-HuggingFace will:
-1. Detect it's a Gradio app (from `requirements.txt`)
-2. Install dependencies
-3. Run `app.py`
-4. Provide a public URL: `https://huggingface.co/spaces/YOUR_USERNAME/berlin-time-mcp`
-
-### Step 5: Verify Deployment
-
-Once deployed, you'll see:
-- The Gradio UI at the Space URL
-- MCP endpoint at: `https://huggingface.co/spaces/YOUR_USERNAME/berlin-time-mcp/gradio_api/mcp/`
-
----
-
-## 🔗 Integrating with Your LangGraph Agent
-
-### Prerequisites
-
-```bash
-pip install mcp langchain-mcp
+**For World Time:**
+```yaml
+app_file: app_world_time_mcp_server.py
 ```
 
-### Step 1: Create MCP Client Connection
+This is much cleaner than renaming files!
 
-Create a new file in your project: `src/tools/mcp_tools.py`
+### Step 2: ⚠️ Check the Port Number
 
-```python
-from mcp import ClientSession, StdioServerParameters
-from mcp.client.stdio import stdio_client
-from langchain.tools import Tool
-import asyncio
+**This is the most common error!**
 
-async def connect_to_berlin_time_mcp():
-    """Connect to the Berlin Time MCP server"""
-    
-    # For local testing
-    server_params = StdioServerParameters(
-        command="python",
-        args=["external_mcp_servers/app_time_mcp_server.py"]
-    )
-    
-    # Or for deployed version:
-    # server_params = HttpServerParameters(
-    #     url="https://huggingface.co/spaces/YOUR_USERNAME/berlin-time-mcp/gradio_api/mcp/"
-    # )
-    
-    async with stdio_client(server_params) as (read, write):
-        async with ClientSession(read, write) as session:
-            await session.initialize()
-            tools = await session.list_tools()
-            return session, tools
-
-def create_berlin_time_tool():
-    """Create a LangChain tool from the MCP server"""
-    
-    async def get_time():
-        session, _ = await connect_to_berlin_time_mcp()
-        result = await session.call_tool("get_berlin_time", {})
-        return result
-    
-    return Tool(
-        name="get_berlin_time",
-        func=lambda: asyncio.run(get_time()),
-        description="Get the current date and time in Berlin, Germany. "
-                    "Returns time in multiple formats including ISO 8601."
-    )
-```
+HuggingFace Spaces **must** run on port **7860**.
 
-### Step 2: Add to Your Agent
+- `app_time_mcp_server.py` is already set to 7860. ✅
+- `app_world_time_mcp_server.py` is set to **7861** (for local testing). ❌
 
-In your main agent file (e.g., `app_v4.py`):
+**You MUST change this line in `app.py` before deploying:**
 
 ```python
-from src.tools.mcp_tools import create_berlin_time_tool
-
-# Add to your existing tools
-berlin_time_tool = create_berlin_time_tool()
+# CHANGE THIS:
+server_port=7861
 
-# Include in your agent's tool list
-tools = [
-    # ... your existing tools ...
-    berlin_time_tool
-]
+# TO THIS:
+server_port=7860
 ```
 
-### Step 3: Test the Integration
+If you forget this, you will see: `OSError: Cannot find empty port`.
 
-Ask your agent:
-- "What time is it in Berlin?"
-- "What's the current date and time in Berlin?"
-- "Is it daytime in Berlin right now?"
+### Step 3: Upload to Spaces
 
-The agent will:
-1. Recognize it needs Berlin time
-2. Call the MCP tool
-3. Receive the structured response
-4. Format it nicely for the user
+1. Create a new Space (SDK: **Gradio**).
+2. Upload:
+   - `app.py` (your chosen server)
+   - `requirements.txt`
+3. Wait for "Running" status.
 
 ---
 
-## 🎓 Teaching This to Colleagues
-
-### Key Points to Emphasize:
+## 🔗 Connecting Your Agent
 
-1. **MCP is a Protocol, Not a Library**
-   - It's a standard way for AI to talk to tools
-   - Like HTTP for web, MCP for AI tools
+Once deployed, your agent needs to know where to look.
 
-2. **Gradio Makes It Easy**
-   - One parameter: `mcp_server=True`
-   - Handles all the protocol complexity
-   - Provides both UI and API
+### Update `src/config/settings.py`
 
-3. **Deployment is Simple**
-   - Works locally for development
-   - Deploy to HF Spaces for production
-   - No server management needed
-
-4. **Reusable Across AI Systems**
-   - Write once, use in any MCP-compatible AI
-   - Not locked to one framework
-   - Easy to share and discover
+```python
+servers["berlin_time"] = {
+    # 1. Use your Space URL
+    # Format: https://huggingface.co/spaces/USERNAME/SPACE_NAME/gradio_api/mcp/
+    "url": "https://gfiamon-date-time-mpc-server-tool.hf.space/gradio_api/mcp/",
+    
+    # 2. Use 'sse' transport (Server-Sent Events)
+    "transport": "sse"
+}
+```
 
-### Demo Flow for Colleagues:
+### How It Works
 
-1. **Show the code** - Point out how simple it is
-2. **Run locally** - Demonstrate the UI
-3. **Explain MCP endpoint** - Show the protocol URL
-4. **Deploy to HF** - Show the public version
-5. **Integrate with AI** - Demonstrate agent using it
+1. **Agent Starts:** Connects to that URL via SSE.
+2. **Discovery:** Asks "What tools do you have?"
+3. **World Time:** Server replies "I have `get_time_for_city` which takes a `city` string".
+4. **User Asks:** "Time in Tokyo?"
+5. **LLM:** "Call `get_time_for_city(city='Tokyo')`"
+6. **Agent:** Sends command to HF Space -> Gets result -> Shows user.
 
 ---
 
-## 🔄 Next Steps & Improvements
-
-### Immediate Next Steps:
-1. ✅ Test the local server (currently running)
-2. ⏭️ Deploy to HuggingFace Spaces
-3. ⏭️ Integrate with your LangGraph agent
-4. ⏭️ Test end-to-end with your agent
+## 🎓 Teaching This to Colleagues
 
-### Future Enhancements:
+**Key Teaching Points:**
 
-**1. Multiple Timezones**
-```python
-def get_time_for_timezone(timezone_name: str = "Europe/Berlin"):
-    # Allow AI to specify any timezone
-```
+1. **One Codebase, Two Interfaces:**
+   - **Humans** use the Web UI (click buttons).
+   - **AI Agents** use the MCP API (hidden endpoint).
+   - Both are powered by the *same Python function*.
 
-**2. Time Conversions**
-```python
-def convert_time(time_str: str, from_tz: str, to_tz: str):
-    # Convert between timezones
-```
+2. **Deployment Simplicity:**
+   - No Docker, no Nginx, no complex config.
+   - Just `app.py` + `requirements.txt` on HF Spaces.
 
-**3. Business Hours Check**
-```python
-def is_business_hours(timezone: str = "Europe/Berlin"):
-    # Check if it's business hours (9-5)
-```
-
-**4. Multiple Tools in One Server**
-```python
-# Create multiple gr.Interface instances
-# Combine them with gr.TabbedInterface
-```
-
----
+3. **The "Port Trap":**
+   - Remind them: Local dev can use any port, but HF Spaces enforces port 7860.
 
-## 📝 Summary
-
-You now have:
-- ✅ A working MCP server with Berlin time tool
-- ✅ Complete understanding of how MCP works
-- ✅ Local testing capability
-- ✅ Deployment instructions for HF Spaces
-- ✅ Integration guide for LangGraph
-- ✅ Teaching materials for colleagues
-
-**The beauty of this approach:**
-- Simple Python function → Gradio interface → MCP server
-- One line (`mcp_server=True`) enables AI integration
-- Deploy anywhere Gradio runs
-- Use with any MCP-compatible AI system
+4. **Dynamic Discovery:**
+   - Show them how you can update the tool on HF (e.g., add "Mars Time"), restart the agent, and it *instantly* knows about the new feature without changing agent code.