first commit

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.env
+.DS_Store

README.md

@@ -5,9 +5,68 @@ colorFrom: purple
 colorTo: blue
 sdk: gradio
 sdk_version: 6.0.2
-app_file: app.py
+app_file: app_time_mcp_server.py
 pinned: false
 short_description: A minimal Gradio MCP server that provides timezone-aware dat
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Berlin Time MCP Server
+
+A simple MCP (Model Context Protocol) server built with Gradio that provides current Berlin time to AI agents.
+
+## What is this?
+
+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.
+
+## Local Testing
+
+1. Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+2. Run the server:
+```bash
+python app_time_mcp_server.py
+```
+
+3. Open your browser to `http://localhost:7860` to test the tool manually.
+
+## 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!
+
+## Using with AI Agents
+
+Once deployed, AI agents can connect to this MCP server and use the `get_berlin_time` tool.
+
+### Example with LangGraph
+
+See the main guide for detailed integration instructions.
+
+## Tool Details
+
+**Function:** `get_berlin_time()`
+
+**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
+}
+```
+
+## Future Improvements
+
+- Add support for multiple timezones
+- Add time conversion tools
+- Add timezone difference calculator

STEP_BY_STEP_GUIDE.md

@@ -0,0 +1,339 @@
+# Step-by-Step Guide: Berlin Time MCP Server
+
+## ✅ 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
+
+## 🎯 Current Status
+
+**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
+
+---
+
+## 📚 Understanding Each Component
+
+### 1. The Core Function: `get_berlin_time()`
+
+```python
+def get_berlin_time():
+    berlin_tz = pytz.timezone('Europe/Berlin')
+    current_time = datetime.now(berlin_tz)
+    # ... returns structured data
+```
+
+**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)
+
+### 2. The Gradio Interface
+
+```python
+demo = gr.Interface(
+    fn=get_berlin_time,
+    inputs=None,
+    outputs=gr.JSON(label="Berlin Time Information"),
+    ...
+)
+```
+
+**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`
+
+```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
+
+---
+
+## 🚀 Deploying to HuggingFace Spaces
+
+### Step 1: Prepare Files
+
+When deploying to HF Spaces, you need to rename `app_time_mcp_server.py` to `app.py`:
+
+```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 have two options:
+
+**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
+```
+
+**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
+```
+
+### Step 1: Create MCP Client Connection
+
+Create a new file in your project: `src/tools/mcp_tools.py`
+
+```python
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from langchain.tools import Tool
+import asyncio
+
+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."
+    )
+```
+
+### Step 2: Add to Your Agent
+
+In your main agent file (e.g., `app_v4.py`):
+
+```python
+from src.tools.mcp_tools import create_berlin_time_tool
+
+# Add to your existing tools
+berlin_time_tool = create_berlin_time_tool()
+
+# Include in your agent's tool list
+tools = [
+    # ... your existing tools ...
+    berlin_time_tool
+]
+```
+
+### Step 3: Test the Integration
+
+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?"
+
+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
+
+---
+
+## 🎓 Teaching This to Colleagues
+
+### Key Points to Emphasize:
+
+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
+
+2. **Gradio Makes It Easy**
+   - One parameter: `mcp_server=True`
+   - Handles all the protocol complexity
+   - Provides both UI and API
+
+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
+
+### Demo Flow for Colleagues:
+
+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
+
+---
+
+## 🔄 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
+
+### Future Enhancements:
+
+**1. Multiple Timezones**
+```python
+def get_time_for_timezone(timezone_name: str = "Europe/Berlin"):
+    # Allow AI to specify any timezone
+```
+
+**2. Time Conversions**
+```python
+def convert_time(time_str: str, from_tz: str, to_tz: str):
+    # Convert between timezones
+```
+
+**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
+```
+
+---
+
+## 📝 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

app_time_mcp_server.py

@@ -0,0 +1,77 @@
+"""
+Berlin Time MCP Server - A Gradio-based MCP server example
+===========================================================
+
+This is a simple MCP (Model Context Protocol) server that provides
+a tool for getting the current time in Berlin timezone.
+
+MCP servers allow AI agents to discover and use tools in a standardized way.
+"""
+
+from datetime import datetime
+import pytz
+import gradio as gr
+
+
+def get_berlin_time():
+    """
+    Get the current date and time in Berlin timezone.
+    
+    This function will be exposed as an MCP tool that AI agents can call
+    when they need to know the current time in Berlin.
+    
+    Returns:
+        dict: A dictionary containing:
+            - time: Human-readable formatted time string
+            - timezone: The timezone name (Europe/Berlin)
+            - timestamp: ISO 8601 formatted timestamp
+            - utc_offset: Current UTC offset for Berlin
+    """
+    # Create Berlin timezone object
+    berlin_tz = pytz.timezone('Europe/Berlin')
+    
+    # Get current time in Berlin
+    current_time = datetime.now(berlin_tz)
+    
+    # Format the time in a human-readable way
+    formatted_time = current_time.strftime("%Y-%m-%d %H:%M:%S %Z")
+    
+    # Get UTC offset (e.g., +01:00 or +02:00 depending on DST)
+    utc_offset = current_time.strftime("%z")
+    
+    # Return structured data
+    return {
+        "time": formatted_time,
+        "timezone": "Europe/Berlin",
+        "timestamp": current_time.isoformat(),
+        "utc_offset": utc_offset,
+        "day_of_week": current_time.strftime("%A"),
+        "is_dst": bool(current_time.dst())
+    }
+
+
+# Simple Interface - just like the example you showed
+demo = gr.Interface(
+    fn=get_berlin_time,
+    inputs=[],  # Empty list = no inputs needed
+    outputs=gr.JSON(label="Berlin Time Information"),
+    title="🕐 Berlin Time MCP Server",
+    description="""
+    This is an MCP (Model Context Protocol) server that provides the current time in Berlin.
+    
+    **For Testing:** Click 'Submit' below to see the current Berlin time.
+    
+    **For AI Agents:** This server exposes the `get_berlin_time` tool via MCP protocol.
+    AI agents can connect to this server and call this tool when they need Berlin time.
+    """,
+    api_name="get_berlin_time"
+)
+
+if __name__ == "__main__":
+    # Launch with MCP server enabled
+    demo.launch(
+        mcp_server=True,
+        share=False,
+        server_name="0.0.0.0",
+        server_port=7860
+    )

requirements.txt

@@ -0,0 +1,2 @@
+gradio
+pytz