README.md

---
title: Open Floor Protocol <> MCP Bridge
emoji: 🌉
colorFrom: yellow
colorTo: pink
sdk: gradio
sdk_version: 5.35.0
app_file: app.py
pinned: false
short_description: A Bridge between Open Floor Agents and MCP
license: apache-2.0
---

# Open Floor Protocol <> MCP Bridge

An MCP server that bridges [Model Control Protocol](https://modelcontextprotocol.io/) with [Open Floor](https://github.com/open-voice-interoperability/openfloor-docs) agents, enabling dynamic agent discovery and capability-based routing.

## Overview

This bridge automatically discovers Open Floor agents (from an ENV var or HTTP header), retrieves their manifests, and provides intelligent routing through a fixed set of MCP tools that dynamically select the best agent based on capabilities.

## Features

- **🔍 Dynamic Agent Discovery**: Automatically finds and registers Open Floor agents
- **🧠 Smart Routing**: Built-in floor manager selects optimal agents based on discovered capabilities  
- **⚡ Capability-Based Matching**: Fixed MCP tools that route tasks using real agent manifest data
- **🌐 Flexible Deployment**: Environment variables + request headers support
- **📡 Open Floor Compliant**: Proper envelope handling for manifest/utterance events

## Quick Start

### Installation

```bash
pip install -r requirements.txt
```

### Configuration

Set your Open Floor agents via environment variable:

```bash
export OPENFLOOR_AGENTS="https://agent1.com,https://agent2.com,https://agent3.com"
```

### Launch MCP Server

```bash
python app.py
```

The MCP server will be available at: `http://localhost:7860/gradio_api/mcp/sse`

### Claude Desktop Setup

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "openfloor-bridge": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:7860/gradio_api/mcp/sse",
        "--transport",
        "sse-only"
      ]
    }
  }
}
```

## Available Agents

The bridge works with any Open Floor-compliant agent. Example agents:

- **Pete** (`https://beaconforge.pythonanywhere.com`) - General purpose assistant for daily tasks
- **Verity** (`https://secondassistant.pythonanywhere.com/verity`) - Fact-checking and hallucination detection  
- **Athena** (`...`) - Book and literature information specialist

## MCP Tools

The bridge exposes these MCP tools for agent interaction:

| Tool | Description |
|------|-------------|
| `discover_openfloor_agents` | Find and list all available agents with capabilities |
| `send_to_best_openfloor_agent` | Smart routing - sends task to most suitable agent |
| `execute_agent_capability` | Target agents with specific capability keywords |
| `list_all_agent_capabilities` | Show detailed capabilities of all agents |
| `send_message_to_openfloor_agent` | Direct communication with specific agent |
| `send_task_to_agents_with_keywords` | Broadcast to all agents matching keywords |

## Usage Examples

### Smart Routing
```
"I need help with Shakespeare's Hamlet analysis"
→ Automatically routes to Athena (literature specialist)
```

### Capability-Based Selection
```
Keywords: "fact,check,verify"  
Task: "Is this statement accurate?"
→ Routes to Verity (fact-checking agent)
```

### Direct Agent Communication
```
Agent: https://example.com
Message: "Tell me how much pounds is 1kg"
→ Direct communication with the agent
```

## Technical Details

### Architecture
- **Floor Manager**: Intelligent agent selection based on discovered capabilities
- **Manifest Caching**: Runtime discovery and matching of agent capabilities
- **Session Isolation**: Independent conversations per user

### Open Floor Compliance
- Proper envelope construction with conversation IDs
- Manifest discovery via `GetManifestsEvent`
- Utterance handling via `UtteranceEvent`

### Environment Variables
- `OPENFLOOR_AGENTS`: Comma-separated list of agent URLs
- 
---

**Demo**: Try it live at [Hugging Face Spaces](https://huggingface.co/spaces/azettl/ofp_mcp) 🚀