Deploy Echo Universal Host

README.md

@@ -1,13 +1,68 @@
 ---
-title: Echo Agent
-emoji: 📉
-colorFrom: yellow
-colorTo: yellow
+title: Echo - Universal MCP Host
+emoji: 🔊
+colorFrom: gray
+colorTo: gray
 sdk: gradio
-sdk_version: 6.0.1
+sdk_version: 5.0.0
 app_file: app.py
 pinned: false
-short_description: A Bidirectional MCP Client & Visual Manager.
+tags:
+  - mcp-in-action-track-consumer
+  - agents
+  - mcp
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Echo: The Universal MCP Host
+
+**"Visualize the Invisible."**
+
+Echo is a Neo-Brutalist, bidirectional Web Client for the Model Context Protocol (MCP). It acts as a "Universal Host" that can load any MCP Server and give it a UI.
+
+## 🏆 Hackathon Submission (Track 2)
+*   **Track**: MCP in Action (Consumer)
+*   **Tag**: `mcp-in-action-track-consumer`
+
+## 🚀 Key Features
+
+### 1. Visual MCP Manager
+Replacing `mcp.json` editing with a GUI.
+*   **App Store Style**: Visualize your tools as cards.
+*   **One-Click Connect**: Instant connection to MCP servers.
+*   **Status Monitoring**: Real-time connection health.
+
+### 2. Bidirectional State Protocol (Innovation)
+Standard MCP is request/response. Echo introduces **Client State Broadcasting**.
+*   **Protocol Inspector**: Visualize JSON-RPC traffic in real-time.
+*   **Blocking State**: Echo broadcasts when it is blocked (e.g., waiting for user confirmation).
+*   **Proactive Voice**: Connected AgentBell servers can listen for this state and speak *before* acting.
+
+### 3. Universal Host
+Echo is server-agnostic.
+*   It connects to `stdio` servers (like `server-memory`).
+*   It connects to python servers (like `agentbell`).
+*   It provides a standard LLM interface (OpenAI) to interact with tools.
+
+---
+
+## 🛠️ How to Use
+
+1.  **Enter your OpenAI API Key** in the settings (or via Environment Variable).
+2.  **Go to TOOLS**: See available servers.
+3.  **Click Connect** on "agentbell-voice" or "memory".
+4.  **Go to SESSION**: Chat with the agent.
+    *   Try: "Create a memory entity called Test" (Tool Call)
+    *   Try: "Delete all entities" (Triggers Blocking State -> Inspector Highlight)
+5.  **Open INSPECTOR**: Watch the JSON-RPC traffic live.
+
+---
+
+## 📦 Setup (Local)
+
+```bash
+git clone https://huggingface.co/spaces/MCP-1st-Birthday/echo-agent
+cd echo-agent
+pip install -r requirements.txt
+python app.py
+```
+

app.py

@@ -0,0 +1,17 @@
+import sys
+import os
+from dotenv import load_dotenv
+
+# Load environment variables from .env file if present
+load_dotenv()
+    
+# Ensure 'src' is in the Python path so we can import our modules
+sys.path.append(os.path.join(os.path.dirname(__file__), "src"))
+
+from ui.layout import create_ui
+
+if __name__ == "__main__":
+    # Launch the application
+    # server_name="0.0.0.0" allows external access if needed
+    ui = create_ui()
+    ui.launch(server_port=7860)

mcp.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json.schemastore.org/mcp.json",
+  "$comment": "Echo Universal Host - MCP Server Configuration",
+  "mcpServers": {
+    "agentbell-voice": {
+      "command": "python",
+      "args": [
+        "services/mcp_server/server.py"
+      ],
+      "env": {
+        "PYTHONUNBUFFERED": "1",
+        "PYTHONPATH": "."
+      },
+      "_description": "AgentBell Voice MCP Server - Provides voice notification tools"
+    },
+    "memory": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-memory"
+      ],
+      "_description": "Simple in-memory key-value store for testing MCP connections"
+    }
+  }
+}

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=5.0.0
+mcp[cli]
+openai
+python-dotenv
+requests

services/mcp_server/__init__.py

@@ -0,0 +1,2 @@
+"""AgentBell MCP server package."""
+

services/mcp_server/audio_store/__init__.py

@@ -0,0 +1,3 @@
+"""Audio storage helpers."""
+"""Audio storage helpers."""
+

services/mcp_server/audio_store/storage.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+from uuid import uuid4
+
+AUDIO_DIR = Path(__file__).resolve().parents[1] / "static" / "audio"
+AUDIO_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def save_audio_bytes(audio_bytes: bytes, prefix: str = "notification") -> str:
+    """
+    Persist audio bytes to disk and return the accessible URL path.
+
+    Returns:
+        str: Relative URL (e.g., /static/audio/xxx.mp3)
+    """
+
+    filename = f"{prefix}-{uuid4().hex}.mp3"
+    filepath = AUDIO_DIR / filename
+    filepath.write_bytes(audio_bytes)
+    return f"/static/audio/{filename}"
+

services/mcp_server/core/__init__.py

@@ -0,0 +1,2 @@
+"""Core utilities for the MCP server."""
+

services/mcp_server/core/actions.py

@@ -0,0 +1,30 @@
+import logging
+from .config import Config
+from .tts import generate_speech
+from .player import play_audio_bytes
+
+logger = logging.getLogger("agentbell.core")
+
+def perform_voice_notify(text: str, config: Config) -> str:
+    """
+    Core logic for voice notification:
+    1. Validates config.
+    2. Generates speech (TTS).
+    3. Plays audio locally.
+    """
+    if not config.tts_configured:
+        logger.error("TTS not configured")
+        raise RuntimeError("ELEVENLABS_API_KEY not configured.")
+
+    try:
+        # 1. Generate Audio
+        audio_bytes = generate_speech(text, config)
+        
+        # 2. Play Locally
+        play_audio_bytes(audio_bytes)
+        
+        return "Voice notification played successfully."
+    except Exception as e:
+        logger.exception("Error in voice_notify core logic")
+        raise e
+

services/mcp_server/core/config.py

@@ -0,0 +1,27 @@
+import os
+from dataclasses import dataclass
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+@dataclass
+class Config:
+    """Holds runtime configuration for the MCP server."""
+
+    elevenlabs_api_key: str | None
+    elevenlabs_voice_id: str
+
+    @property
+    def tts_configured(self) -> bool:
+        return bool(self.elevenlabs_api_key)
+
+
+def load_config() -> Config:
+    """Load configuration from environment variables."""
+    return Config(
+        elevenlabs_api_key=os.getenv("ELEVENLABS_API_KEY"),
+        elevenlabs_voice_id=os.getenv("ELEVENLABS_VOICE_ID", "21m00Tcm4TlvDq8ikWAM"),
+    )
+

services/mcp_server/core/player.py

@@ -0,0 +1,61 @@
+import logging
+import os
+import platform
+import subprocess
+import tempfile
+import threading
+import time
+
+logger = logging.getLogger(__name__)
+
+
+def _play_and_cleanup(cmd: list, temp_path: str):
+    """Helper function to run the player command and cleanup afterwards."""
+    try:
+        # This blocks this background thread, but not the main server thread
+        subprocess.run(cmd, check=True)
+    except Exception as e:
+        logger.error(f"Background playback failed: {e}")
+    finally:
+        # Give a small buffer ensuring file handle is released
+        time.sleep(0.5)
+        if os.path.exists(temp_path):
+            try:
+                os.unlink(temp_path)
+            except Exception:
+                pass
+    
+
+def play_audio_bytes(audio_data: bytes, **kwargs) -> None:
+    """
+    Play audio bytes (MP3 or other supported formats) in a non-blocking way.
+    This ensures the MCP server responds immediately, allowing the Agent UI
+    to update (show buttons) WHILE the voice is starting to speak.
+    """
+    with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as tf:
+        tf.write(audio_data)
+        temp_path = tf.name
+
+    system = platform.system()
+    cmd = []
+
+    if system == "Darwin":
+        cmd = ["afplay", temp_path]
+    elif system == "Linux":
+        if subprocess.call(["which", "paplay"], stdout=subprocess.DEVNULL) == 0:
+            cmd = ["paplay", temp_path]
+        elif subprocess.call(["which", "aplay"], stdout=subprocess.DEVNULL) == 0:
+            cmd = ["aplay", temp_path]
+    elif system == "Windows":
+        # Windows Powershell sound player might be tricky in background threads due to COM
+        # but let's try standard command execution
+        ps_cmd = f"(New-Object Media.SoundPlayer '{temp_path}').PlaySync()"
+        cmd = ["powershell", "-c", ps_cmd]
+
+    if cmd:
+        logger.info(f"Starting background playback on {system}...")
+        # Launch in a separate thread so we don't block the API response
+        thread = threading.Thread(target=_play_and_cleanup, args=(cmd, temp_path))
+        thread.start()
+    else:
+        logger.warning("No suitable player found, skipping playback.")

services/mcp_server/core/tts.py

@@ -0,0 +1,46 @@
+import logging
+from typing import Optional
+
+import requests
+
+from .config import Config
+
+logger = logging.getLogger(__name__)
+
+
+class TTSNotConfiguredError(RuntimeError):
+    """Raised when text-to-speech is not configured properly."""
+
+
+def generate_speech(text: str, config: Config) -> bytes:
+    """
+    Generate speech audio bytes using ElevenLabs.
+
+    Raises:
+        TTSNotConfiguredError: If the API key is missing.
+        requests.exceptions.RequestException: If the HTTP request fails.
+    """
+
+    if not config.elevenlabs_api_key:
+        raise TTSNotConfiguredError("ELEVENLABS_API_KEY is not set.")
+
+    logger.info("Calling ElevenLabs TTS for text: %s", text)
+
+    tts_url = (
+        f"https://api.elevenlabs.io/v1/text-to-speech/{config.elevenlabs_voice_id}"
+    )
+    headers = {
+        "Accept": "audio/mpeg",
+        "Content-Type": "application/json",
+        "xi-api-key": config.elevenlabs_api_key,
+    }
+    payload = {
+        "text": text,
+        "model_id": "eleven_multilingual_v2",
+        "voice_settings": {"stability": 0.5, "similarity_boost": 0.75},
+    }
+
+    response = requests.post(tts_url, json=payload, headers=headers, timeout=30)
+    response.raise_for_status()
+    return response.content
+

services/mcp_server/main.py

@@ -0,0 +1,47 @@
+import logging
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from .core.config import load_config
+from .routes.mcp import get_router
+from .websocket.manager import ConnectionManager
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("agentbell.mcp")
+
+
+def create_app() -> FastAPI:
+    config = load_config()
+    app = FastAPI(
+        title="AgentBell MCP Server",
+        description="A Model Context Protocol (MCP) server for real-time voice notifications.",
+        version="1.0.0",
+    )
+
+    static_dir = Path(__file__).resolve().parent / "static"
+    static_dir.mkdir(parents=True, exist_ok=True)
+    app.mount("/static", StaticFiles(directory=static_dir), name="static")
+
+    manager = ConnectionManager()
+
+    app.include_router(get_router(config, manager))
+
+    if not config.tts_configured:
+        logger.warning(
+            "ELEVENLABS_API_KEY is not configured. /invoke calls will return an error."
+        )
+
+    @app.websocket("/ws")
+    async def websocket_endpoint(websocket):
+        await manager.handle_connection(websocket)
+
+    @app.get("/")
+    async def root():
+        return {"message": "AgentBell MCP Server is running."}
+
+    return app
+
+
+app = create_app()

services/mcp_server/requirements.txt

@@ -0,0 +1,5 @@
+fastapi
+uvicorn
+requests
+python-dotenv
+websockets

services/mcp_server/routes/__init__.py

@@ -0,0 +1,2 @@
+"""API routes for the MCP server."""
+

services/mcp_server/routes/mcp.py

@@ -0,0 +1,79 @@
+import logging
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from ..core.config import Config
+from ..core.actions import perform_voice_notify
+from ..websocket.manager import ConnectionManager
+
+logger = logging.getLogger(__name__)
+
+
+class InvokeRequest(BaseModel):
+    tool_id: str
+    parameters: dict
+
+
+class InvokeResponse(BaseModel):
+    content: str
+    content_type: str = "text/plain"
+
+
+def get_router(config: Config, manager: ConnectionManager) -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/health")
+    async def health_check():
+        return {"status": "ok"}
+
+    @router.get("/tools")
+    async def get_tools():
+        # Keeping description consistent with server.py but optimized for JSON response
+        return {
+            "tools": [
+                {
+                    "id": "voice_notify",
+                    "description": (
+                        "Speak a message to the user via local audio. "
+                        "CRITICAL: Use this tool BEFORE ANY action that requires user confirmation/clicking "
+                        "(e.g., file edits, deletes, terminal commands) regardless of task length. "
+                        "Narrate your steps. Style: Concise (5-15 words), human-like, no raw code."
+                    ),
+                    "parameters": [
+                        {
+                            "name": "text",
+                            "type": "string",
+                            "description": "The text to be spoken to the user.",
+                            "required": True,
+                        }
+                    ],
+                }
+            ]
+        }
+
+    @router.post("/invoke", response_model=InvokeResponse)
+    async def invoke_tool(request: InvokeRequest):
+        if request.tool_id != "voice_notify":
+            return {"content": f"Error: Tool '{request.tool_id}' not found."}
+
+        text_to_speak = request.parameters.get("text")
+        if not text_to_speak:
+            return {"content": "Error: 'text' parameter is required."}
+
+        logger.info("Processing voice notification: %s", text_to_speak)
+
+        try:
+            # 1. Play Audio (Core Logic)
+            result_msg = perform_voice_notify(text_to_speak, config)
+            
+            # 2. Broadcast Event (For Gradio/Web Client)
+            # We fire and forget the websocket event
+            await manager.broadcast_event("voice_start", {"text": text_to_speak})
+            
+            return {"content": result_msg}
+            
+        except Exception as exc:
+            logger.exception("Failed to process speech: %s", exc)
+            return {"content": f"Error: Failed to process speech. Details: {exc}"}
+
+    return router

services/mcp_server/server.py

@@ -0,0 +1,50 @@
+import logging
+from mcp.server.fastmcp import FastMCP
+from services.mcp_server.core.config import load_config
+from services.mcp_server.core.actions import perform_voice_notify
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("agentbell.mcp")
+
+# Create FastMCP server
+mcp = FastMCP("AgentBell")
+
+
+@mcp.tool()
+def voice_notify(text: str) -> str:
+    """
+    Speak a message to the user via local audio.
+    
+    Use this tool to act as a "Voice Companion" for the user. 
+    You should narrate your key steps, status, and requests for attention.
+
+    USAGE PROTOCOL:
+    1. WHEN TO SPEAK:
+       - **Before Actions**: BEFORE running terminal commands, editing files, or calling other tools, speak a concise summary of what you are about to do.
+       - **Start of Task**: When receiving a new request, briefly acknowledge the plan.
+       - **End of Task**: When a task is complete, summarize the result.
+       - **Blocks/Confirmations**: If an action might require user approval (e.g. `rm`, `install`), you MUST speak BEFORE calling that tool.
+
+    2. CONTENT GUIDELINES:
+       - **Language**: ALWAYS match the language of the user's last message/prompt.
+       - **Style**: Human-like, concise (5-15 words), intelligent summary.
+       - **Forbidden**: Do NOT read raw filenames, paths, URLs, or code blocks. Use general terms.
+
+    3. CRITICAL TIMING (PREVENT DEADLOCKS):
+       - You MUST call `voice_notify`, **WAIT** for it to return, and ONLY THEN call the subsequent action tool.
+       - **NEVER** call `voice_notify` and a blocking tool (like `run_terminal_cmd`) in the same parallel execution block.
+    """
+    logger.info(f"AgentBell triggered: {text}")
+    config = load_config()
+
+    try:
+        return perform_voice_notify(text, config)
+    except RuntimeError as e:
+        return f"Error: {e}"
+    except Exception as e:
+        return f"Error playing voice: {e}"
+
+
+if __name__ == "__main__":
+    mcp.run()

services/mcp_server/websocket/__init__.py

@@ -0,0 +1,3 @@
+"""WebSocket management utilities."""
+"""WebSocket management utilities."""
+

services/mcp_server/websocket/manager.py

@@ -0,0 +1,49 @@
+import logging
+from typing import List, Dict, Any
+
+from fastapi import WebSocket, WebSocketDisconnect
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectionManager:
+    """Tracks active websocket connections and broadcasts events."""
+
+    def __init__(self) -> None:
+        self.active_connections: List[WebSocket] = []
+
+    async def register(self, websocket: WebSocket) -> None:
+        await websocket.accept()
+        self.active_connections.append(websocket)
+        logger.info("WebSocket connected. Total clients: %s", len(self.active_connections))
+
+    def unregister(self, websocket: WebSocket) -> None:
+        if websocket in self.active_connections:
+            self.active_connections.remove(websocket)
+        logger.info("WebSocket disconnected. Total clients: %s", len(self.active_connections))
+
+    async def broadcast_event(self, event_type: str, data: Dict[str, Any]) -> None:
+        """Broadcast a generic JSON event to all clients."""
+        payload = {
+            "type": event_type,
+            **data
+        }
+        stale_connections: list[WebSocket] = []
+        for connection in self.active_connections:
+            try:
+                await connection.send_json(payload)
+            except Exception as exc:  # pragma: no cover
+                logger.warning("Failed sending payload to websocket: %s", exc)
+                stale_connections.append(connection)
+        for connection in stale_connections:
+            self.unregister(connection)
+
+    async def handle_connection(self, websocket: WebSocket) -> None:
+        """Accept and keep the websocket connection alive."""
+        await self.register(websocket)
+        try:
+            while True:
+                # We keep the websocket open; we do not expect client messages yet.
+                await websocket.receive_text()
+        except WebSocketDisconnect:
+            self.unregister(websocket)

src/__init__.py

@@ -0,0 +1,2 @@
+# Echo Universal MCP Host - Source Package
+

src/core/__init__.py

@@ -0,0 +1,20 @@
+# Core Module - MCP Connection, LLM, State Management
+from .state import (
+    # Connection Management
+    get_connection, 
+    ensure_connection, 
+    get_all_connections,
+    connect_server,
+    disconnect_server,
+    is_connected,
+    # Inspector
+    get_inspector_logs,
+    add_inspector_log,
+    # Bidirectional Protocol
+    ClientState,
+    broadcast_client_state,
+    get_current_state
+)
+from .mcp_client import MCPConnection, create_connection_from_config
+from .llm import get_llm, LLMRouter
+