MCP IDE Bridge

Un servidor de mensajería de código abierto para comunicación entre clientes utilizando mensajería MCP HTTP Streamable.

Documentación

MCP IDE Bridge

🎬 Video de Demostración

APLICACIÓN WEB FRONTEND CURSOR IDE	API BACKEND CURSOR IDE

¡Haz clic en la imagen de arriba para ver la demostración en vivo de MCP IDE Bridge en acción!
Esto muestra dos Cursor IDEs (frontend y backend) colaborando en tiempo real a través de IDE Bridge.

Un servidor MCP (Model Context Protocol) HTTP Streamable, de código abierto y sin estado, que permite la comunicación cliente-a-cliente entre IDEs y herramientas de desarrollo. Esto abre una nueva dimensión de colaboración más allá de las interacciones tradicionales cliente-servidor de MCP.

🚀 Perfecto para: Colaboración entre IDEs, flujos de trabajo de desarrollo en equipo, coordinación de agentes de IA e integración fluida de herramientas.

🌟 ¿Qué Hace Esto Especial?

MCP Tradicional vs MCP IDE Bridge

MCP Tradicional	MCP IDE Bridge
Cliente ↔ Servidor	Cliente ↔ Servidor ↔ Cliente
Comunicación unidireccional	Mensajería bidireccional
Solo ejecución de herramientas	Colaboración en tiempo real
Enfoque en un solo IDE	Coordinación multi-IDE

Casos de Uso en el Mundo Real

🎯 Colaboración entre IDEs

Cursor ↔ Cursor: Comparte fragmentos de código, sesiones de depuración o programación en pareja
Cursor ↔ VS Code: Comunicación entre editores e intercambio de archivos
Windsurf ↔ Cualquier IDE: Coordinación de agentes de IA en diferentes entornos de desarrollo
Flujos de Trabajo en Equipo: Coordina múltiples desarrolladores trabajando en el mismo proyecto

🤖 Coordinación de Agentes de IA

Comunicación agente-a-agente para flujos de trabajo complejos
Procesamiento distribuido de IA entre múltiples herramientas
Colaboración humano-en-el-bucle con asistentes de IA

🏗️ Arquitectura

Comunicación Cliente-a-Cliente

IDE A (Cursor)  ←→  MCP IDE Bridge  ←→  IDE B (VS Code)
     ↑                    ↑                    ↑
  MCP Client         Message Relay        MCP Client

Componentes Clave

Retransmisión de Mensajes: Servidor sin estado que enruta mensajes entre clientes
Registro de Clientes: Descubrimiento y registro dinámico de clientes
Colas de Mensajes: Colas por destinatario con expiración automática
HTTP Streamable: Último transporte MCP para comunicación en tiempo real

🚀 Inicio Rápido

1. Iniciar el Servidor

Docker (Recomendado):

docker run -d --name mcp-ide-bridge -p 8111:8111 mcp-messaging-server

Configuración Predeterminada:

Puerto: 8111 (tanto externo como interno)
Host: 0.0.0.0 (acepta conexiones desde cualquier interfaz)
Transporte: HTTP Streamable (última versión de MCP)
Verificación de Salud: Monitoreo de endpoint integrado

Python (Configuración de Desarrollo):

# First-time setup (see Local Development section for full instructions)
pip install -r requirements.txt && pip install -e .

# Run server
python -m mcp_messaging.server --port 8111

2. Configurar Tu IDE

Crea mcp_recipients.json en la raíz de tu proyecto. Cada proyecto recibe UN archivo con su propio ID único y una lista de destinatarios con los que puede comunicarse:

{
  "my_id": "myproject_cursor",
  "recipients": {
    "teammate_vscode": {
      "name": "Teammate's Project",
      "description": "My teammate's project in VS Code"
    },
    "aiagent_windsurf": {
      "name": "AI Agent Project", 
      "description": "AI agent development in Windsurf"
    }
  },
  "server_info": {
    "url": "http://localhost:8111/mcp/",
    "transport": "http_streamable"
  }
}

🤖 Generación por Agente de IA: ¡El agente de IA de tu IDE puede generar este archivo! Simplemente pregunta:

Cursor: "Genera un mcp_recipients.json para mi proyecto"
VS Code: "Crea la configuración mcp_recipients.json para mi equipo"
Windsurf: "Ayúdame a configurar mcp_recipients.json para colaboración"

📁 Ejemplos Multi-Proyecto: Consulta examples/multi-project-setup/ para ver ejemplos de cómo se comunican diferentes proyectos. Cada archivo de proyecto debe llamarse mcp_recipients.json - los nombres de archivo de ejemplo en esa carpeta son solo de referencia.

3. Conectar Tu IDE

Cursor IDE:

Crea .cursor/mcp.json:

{
  "mcpServers": {
    "messaging-server": {
      "url": "http://localhost:8111/mcp/",
      "type": "streamable-http",
      "description": "MCP HTTP Streamable messaging server for client-to-client communication"
    }
  }
}

Abre la Paleta de Comandos (Cmd/Ctrl + Shift + P)
Busca "MCP: Connect to Server"
Ingresa: http://localhost:8111/mcp/

VS Code:

Instala la extensión MCP desde el marketplace
Crea mcp_recipients.json en la raíz del proyecto
Configura los ajustes de MCP en las preferencias de VS Code
Usa los comandos MCP para conectarte y colaborar

Windsurf:

Crea mcp_recipients.json en la raíz del proyecto
Abre la configuración de Windsurf → configuración de MCP
Agrega la URL del servidor: http://localhost:8111/mcp/
Comienza a enviar mensajes con otros IDEs

Claude Desktop:

Crea mcp_recipients.json en la raíz del proyecto
Abre la configuración de Claude Desktop → configuración de MCP
Agrega la URL del servidor: http://localhost:8111/mcp/
Usa la integración MCP de Claude para comunicarte

IDEs JetBrains (IntelliJ, PyCharm, etc.):

Instala el plugin MCP desde el marketplace de plugins
Crea mcp_recipients.json en la raíz del proyecto
Configura el servidor MCP en los ajustes del plugin
Usa las herramientas MCP desde el IDE

Nota: Cada IDE requiere tanto mcp_recipients.json (para mensajería) como la configuración MCP específica del IDE (para la conexión). Cada proyecto recibe UN archivo mcp_recipients.json con su propio ID único y lista de destinatarios. El archivo debe llamarse exactamente mcp_recipients.json y colocarse en la raíz del proyecto para que los agentes del IDE lo encuentren fácilmente. Consulta examples/multi-project-setup/README.md para instrucciones detalladas de configuración.

🔗 Clientes No-IDE (LangChain, mcp-use, Aplicaciones Personalizadas)

Descripción General

Los clientes no-IDE usan el mismo protocolo MCP exacto que los clientes IDE. La única diferencia es cómo proporcionan su configuración:

Clientes IDE: Leen mcp_recipients.json desde el sistema de archivos local
Clientes no-IDE: Proporcionan recipients_config como parámetro a las herramientas MCP

Sin registro, sin endpoints REST, sin configuración especial - ¡solo inyección de parámetros!

Esto permite una integración fluida con frameworks como LangChain, mcp-use, scripts personalizados de Python y aplicaciones web.

Arquitectura

Non-IDE Client (LangChain/mcp-use)
         ↓
    Client wrapper adds recipients_config parameter
         ↓  
    Standard MCP Tools (same as IDE clients)
         ↓
    MCP IDE Bridge ←→ IDE Clients

Configuración - Enfoque de Wrapper de Cliente

Crea un wrapper que inyecte automáticamente tu configuración:

Integración con LangChain:

from mcp import Client

class MCPClientWrapper:
    def __init__(self, mcp_url, recipients_config):
        self.client = Client(mcp_url)
        self.recipients_config = recipients_config
        self.my_id = recipients_config.get("my_id")
    
    def get_my_identity(self):
        # Inject recipients_config parameter
        return self.client.call_tool("get_my_identity", {
            "client_id": self.my_id,
            "recipients_config": self.recipients_config
        })
    
    def send_message(self, recipient_ids, messages):
        return self.client.call_tool("send_message_without_waiting", {
            "sender_id": self.my_id,
            "recipient_ids": recipient_ids if isinstance(recipient_ids, list) else [recipient_ids],
            "messages": messages if isinstance(messages, list) else [messages]
        })
    
    def get_messages(self):
        return self.client.call_tool("get_messages", {
            "client_id": self.my_id
        })

# Usage
recipients_config = {
    "my_id": "my-langchain-app",
    "recipients": {
        "frontend_cursor": {
            "name": "Frontend Team Cursor",
            "description": "Frontend development in Cursor IDE"
        },
        "backend_vscode": {
            "name": "Backend Team VS Code", 
            "description": "Backend API development in VS Code"
        }
    },
    "server_info": {
        "host": "localhost",
        "port": 8111
    }
}

# Initialize wrapper
mcp_client = MCPClientWrapper("http://localhost:8111/mcp/", recipients_config)

# Use exactly like IDE clients
identity = mcp_client.get_my_identity()
print(identity)

response = mcp_client.send_message(["frontend_cursor"], ["Please update the user authentication flow"])
messages = mcp_client.get_messages()

Integración con mcp-use:

import mcp_use

# Same wrapper pattern  
wrapper = MCPClientWrapper("http://localhost:8111/mcp/", recipients_config)
wrapper.send_message(["team_cursor"], ["Task completed!"])

Implementación en el Mundo Real: Patrón Proxy

Para aplicaciones web de producción, el enfoque recomendado es un patrón proxy/interceptor que maneje selectivamente las herramientas de mensajería:

Ejemplo de Ruta API en Next.js (implementación dyson_frontend):

// app/api/mcp-proxy/route.ts
import { NextRequest } from 'next/server'

// Hardcoded configuration (no file dependencies)
const MCP_RECIPIENTS_CONFIG = {
  my_id: 'dyson_frontend',
  recipients: {
    'miles_mcp_server': { name: 'Miles Primary MCP Server', description: 'Main backend API' },
    'mcpresearchserver': { name: 'MCP Research Server', description: 'Research tools' },  
    'mcp-ide-bridge': { name: 'IDE Bridge', description: 'Cross-IDE communication' }
  },
  server_info: { host: 'localhost', port: 8111 }
}

// Only intercept these 4 messaging tools (99% of traffic passes through)
const INTERCEPTED_TOOLS = ['send_message_without_waiting', 'get_messages', 'get_my_identity', 'checkin_client']

export async function POST(request: NextRequest) {
  const { tool_name, arguments: toolArgs, server_id } = await request.json()
  
  // Only intercept messaging tools for ide-bridge
  if (server_id === 'ide-bridge' && INTERCEPTED_TOOLS.includes(tool_name)) {
    return handleMessagingTool(tool_name, toolArgs)
  }
  
  // Forward everything else unchanged
  return forwardToMcp(server_id, tool_name, toolArgs)
}

async function handleMessagingTool(toolName: string, toolArgs: any) {
  switch (toolName) {
    case 'get_my_identity':
      // Override with our config as markdown
      return Response.json(formatConfigAsMarkdown(MCP_RECIPIENTS_CONFIG))
      
    case 'send_message_without_waiting':
      // Inject sender_id and validate recipients
      return forwardToMcp('ide-bridge', toolName, {
        ...toolArgs,
        sender_id: MCP_RECIPIENTS_CONFIG.my_id
      })
      
    case 'get_messages':
      // Inject client_id
      return forwardToMcp('ide-bridge', toolName, {
        ...toolArgs,
        client_id: MCP_RECIPIENTS_CONFIG.my_id
      })
      
    case 'checkin_client':
      // Inject client identity
      return forwardToMcp('ide-bridge', toolName, {
        client_id: MCP_RECIPIENTS_CONFIG.my_id,
        name: 'Dyson Frontend App',
        capabilities: 'Web application for AI agent coordination'
      })
  }
}

function formatConfigAsMarkdown(config: any): string {
  const recipientRows = Object.entries(config.recipients).map(([id, info]: [string, any]) => 
    `| ${id} | ${info.description} | No URL |`
  ).join('\n')
  
  return `# 🆔 MCP Client Identity & Recipients
## Your Client ID: \`${config.my_id}\`
## Available Recipients
| Client ID | Description | URL |
|-----------|-------------|-----|
${recipientRows}
## Usage: Use your client ID in messaging tools...`
}

Pasos de Configuración para Clientes No-IDE:

Crea un endpoint proxy MCP (/api/mcp-proxy o equivalente)
Codifica tu configuración de destinatarios (no se necesitan archivos mcp_recipients.json)
Intercepta solo las herramientas de mensajería: send_message_without_waiting, get_messages, get_my_identity, checkin_client
Inyecta los parámetros requeridos donde falten (sender_id, client_id, etc.)
Anula get_my_identity para devolver tu configuración como markdown
Reenvía todo lo demás sin cambios (enfoque conservador)

Ejemplos de Frameworks:

# Express.js
app.post('/mcp-proxy', (req, res) => {
  const { tool_name, server_id } = req.body
  if (server_id === 'ide-bridge' && MESSAGING_TOOLS.includes(tool_name)) {
    return handleMessaging(tool_name, req.body.arguments)
  }
  return forwardToMcp(server_id, tool_name, req.body.arguments)
})

# Django
def mcp_proxy(request):
    data = json.loads(request.body)
    if data['server_id'] == 'ide-bridge' and data['tool_name'] in MESSAGING_TOOLS:
        return handle_messaging(data['tool_name'], data['arguments'])
    return forward_to_mcp(data['server_id'], data['tool_name'], data['arguments'])

# Flask
@app.route('/mcp-proxy', methods=['POST'])
def mcp_proxy():
    data = request.json
    if data['server_id'] == 'ide-bridge' and data['tool_name'] in MESSAGING_TOOLS:
        return handle_messaging(data['tool_name'], data['arguments'])
    return forward_to_mcp(data['server_id'], data['tool_name'], data['arguments'])

Beneficios

🔗 Integración Simple: Mismo protocolo que los clientes IDE
📡 Sin Configuración Especial: Solo inyección de parámetros
🚀 Control del Lado del Cliente: El proxy gestiona la configuración
🛠️ Agnóstico de Frameworks: Funciona con cualquier biblioteca de cliente MCP
🏗️ Enfoque Conservador: Solo intercepta lo necesario (99% del tráfico sin cambios)
💾 Sin Dependencias de Archivos: Configuración en tiempo de ejecución, sin necesidad de mcp_recipients.json
🔧 Listo para Producción: Patrón del mundo real utilizado por proyectos activos

📋 Herramientas Disponibles

Herramientas de Mensajería Principales

Herramienta	Descripción	Caso de Uso
`checkin_client`	Registra tu presencia	Anuncia disponibilidad
`send_message_without_waiting`	Mensajería de disparar y olvidar	ÚNICO método de mensajería
`get_messages`	📬 ESENCIAL - Verifica respuestas	Requerido después de enviar mensajes
`get_my_identity`	Obtén ayuda de configuración	Asistencia de configuración
`get_active_sessions`	Ver conexiones activas	Monitorea la actividad del equipo

🚀 Flujo de Trabajo de Mensajería

PATRÓN DE MENSAJERÍA: Disparar y olvidar + get_messages para comunicación eficiente:

1. Enviar Mensajes (Disparar y Olvidar):

# Send to one or more recipients - INSTANT return, no blocking!
send_message_without_waiting(
  sender_id="alice_cursor",
  recipient_ids=["bob_vscode", "charlie_windsurf", "diana_jetbrains"],  
  messages=["Meeting in 5 minutes! Please confirm attendance."]
)

2. Verificar Respuestas:

# Get replies from recipients
get_messages("alice_cursor")
# Returns responses from bob_vscode, charlie_windsurf, diana_jetbrains

Patrones de Mensajes:

# Different messages to different recipients
send_message_without_waiting(
  sender_id="alice_cursor", 
  recipient_ids=["bob_vscode", "charlie_windsurf"],
  messages=["Review auth module please", "Check UI components for responsiveness"]
)

# Single recipient
send_message_without_waiting(
  sender_id="alice_cursor",
  recipient_ids=["bob_vscode"],
  messages=["Quick question about the API endpoint"]
)

# Then check for replies
get_messages("alice_cursor")

Beneficios:

✅ Sin Bloqueo: Retorno instantáneo, sin esperas
✅ Escalable: Funciona para uno o más destinatarios de manera eficiente
✅ Rápido: Sin tiempos de espera ni llamadas bloqueantes
✅ Mejor Experiencia de Usuario: Experiencia de mensajería fluida y receptiva

Ejemplos de Flujos de Trabajo

Colaboración en Equipo

# Developer A checks in
checkin_client("alice_cursor", "Alice", "Working on auth module")

# Developer A messages recipients
send_message_without_waiting("alice_cursor", 
  ["bob_vscode", "charlie_windsurf", "diana_jetbrains"],
  ["Need code review on auth module - who's available?"])

# Developer A checks for replies
get_messages("alice_cursor")
# Returns: "I can help! - bob_vscode", "Busy until 3pm - charlie_windsurf"

Coordinación de Agentes de IA

# AI Agent 1 announces completion
send_message_without_waiting("ai_agent_1", 
  ["ai_agent_2", "ai_agent_3", "human_reviewer"],
  ["Code review complete - ready for next phase"])

# Check for coordination responses
get_messages("ai_agent_1")
# Returns responses from recipients

🔒 Consideraciones de Seguridad

Estado Actual (Uso de Escritorio)

✅ Adecuado para:

Equipos de desarrollo locales
Proyectos personales
Flujos de trabajo solo de escritorio
Entornos de red confiables

⚠️ Limitaciones:

Sin autenticación más allá de los IDs de cliente
Sin cifrado de mensajes
Sin control de acceso
Sin registro de auditoría

🔐 Modelo de Seguridad:

Los IDs de cliente actúan como credenciales simples
Los mensajes se almacenan solo en memoria
Expiración automática a los 5 minutos
Sin almacenamiento persistente

Solución Empresarial

Para uso en producción, seguridad y colaboración en equipo, ofrecemos MilesDyson.ai - una Plataforma Agéntica como Servicio (aPaaS) de nivel empresarial que aborda todas las preocupaciones de seguridad:

🔐 Autenticación Empresarial: SSO, RBAC y registros de auditoría
🛡️ Cifrado de Extremo a Extremo: Todos los mensajes cifrados en tránsito y en reposo
🌐 Infraestructura Global: Despliegue multi-región con 99.9% de disponibilidad
👥 Gestión de Equipos: Gestión de usuarios, permisos y herramientas de colaboración
📊 Analítica: Información de uso y monitoreo de rendimiento
🔧 Soporte Empresarial: Soporte dedicado e integraciones personalizadas

Aprende Más → MilesDyson.ai

🧪 Pruebas

Harness de Pruebas MCP (Recomendado)

¡NUEVO! Hemos incluido un harness de pruebas MCP integral (test_mcp_client.py) que hace que probar todas las herramientas MCP sea fácil y confiable:

# Test identity and configuration
python test_mcp_client.py get_my_identity

# Check in as a client
python test_mcp_client.py checkin_client --client_id "test-client" --name "Test Client" --capabilities "Testing tools"

# Send fire-and-forget messages
python test_mcp_client.py send_message_without_waiting \
  --sender_id "test-client" \
  --args '{"recipient_ids": ["target-client"], "messages": ["Hello from test harness!"]}'

# NEW! Broadcast messages (fire & forget)
# Same message to multiple recipients
python test_mcp_client.py send_message_without_waiting \
  --sender_id "test-client" \
  --args '{"recipient_ids": ["alice", "bob", "charlie"], "messages": ["Team meeting in 5 minutes!"]}'

# Different messages to different recipients  
python test_mcp_client.py send_message_without_waiting \
  --sender_id "test-client" \
  --args '{"recipient_ids": ["alice", "bob"], "messages": ["Review the auth code", "Check the UI components"]}'

# Get pending messages
python test_mcp_client.py get_messages --client_id "test-client"

# Check server status
python test_mcp_client.py get_active_sessions

# Use custom JSON arguments
python test_mcp_client.py checkin_client --args '{"client_id": "custom", "name": "Custom Client"}'

Características:

✅ Encabezados MCP Correctos: Maneja text/event-stream y respuestas de streaming correctamente
✅ Salida Hermosa: Visualización limpia en markdown con depuración JSON cruda
✅ Todas las Herramientas Soportadas: Prueba cada herramienta MCP con manejo adecuado de argumentos
✅ Argumentos Flexibles: Usa banderas individuales o JSON para parámetros complejos
✅ Manejo de Errores: Mensajes de error claros e información de solución de problemas

Instalación:

# Install required dependency
pip install requests

# Run any test
python test_mcp_client.py <tool_name> [arguments]

Prueba Rápida de Conexión

# Test server connectivity
curl -X GET http://localhost:8111/api/sessions

# Test MCP client connection
cd examples/client
python test_connection.py --mcp-localhost-port 8111

Cliente de Referencia

El proyecto incluye un cliente MCP de referencia para pruebas:

cd examples/client
pip install -r requirements.txt
python client.py --mcp-localhost-port 8111

🏗️ Desarrollo

Estructura del Proyecto

src/mcp_messaging/
├── server.py          # Main server implementation
├── models.py          # Data models
└── queue_backends.py  # Queue implementations

examples/
├── client/            # Reference MCP client
├── configs/           # Project-specific configurations
├── multi-project-setup/  # Multi-project IDE communication examples
│   ├── README.md      # Comprehensive setup guide
│   ├── frontend-cursor.json
│   ├── backend-vscode.json
│   ├── rag-windsurf.json
│   ├── devops-jetbrains.json
│   └── ...            # More project examples (filenames for reference only)
└── reference/         # Additional examples

test_mcp_client.py     # MCP test harness for command-line testing
mcp_recipients.json    # Example configuration (each project gets ONE file)
requirements.txt       # Python dependencies
Dockerfile            # Container support

Nota: Cada proyecto recibe UN archivo mcp_recipients.json con su propio ID único y lista de destinatarios. Los nombres de archivo de ejemplo en multi-project-setup/ son solo de referencia - tu archivo real debe llamarse mcp_recipients.json en la raíz de cada proyecto.

Desarrollo Local

# Clone and setup
git clone https://github.com/your-username/mcp-ide-bridge.git
cd mcp-ide-bridge

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install package in editable mode (REQUIRED for Python to find mcp_messaging module)
pip install -e .

# Run server
python -m mcp_messaging.server --port 8111

⚠️ Importante: El paso pip install -e . es requerido para que Python encuentre correctamente el módulo mcp_messaging. Sin esto, obtendrás ModuleNotFoundError: No module named 'mcp_messaging'.

🤝 Contribuciones

¡Damos la bienvenida a contribuciones! Consulta CONTRIBUTING.md para:

Configuración de desarrollo
Guías de estilo de código
Procedimientos de prueba
Proceso de pull request

📄 Licencia

Licencia MIT - consulta LICENSE para más detalles.

🚀 Solución Empresarial

¿Listo para uso en producción?

MilesDyson.ai proporciona MCP IDE Bridge de nivel empresarial con:

🔐 Seguridad Empresarial: SSO, cifrado, registros de auditoría
🌐 Infraestructura Global: Multi-región, alta disponibilidad
👥 Gestión de Equipos: Gestión de usuarios y herramientas de colaboración
📊 Analítica y Monitoreo: Información de uso y seguimiento de rendimiento
🔧 Soporte Empresarial: Soporte dedicado e integraciones personalizadas

Perfecto para:

Equipos de desarrollo
Entornos empresariales
Despliegues de producción
Colaboración multi-organización

Construido con transporte MCP HTTP Streamable • Impulsado por FastMCP • Hecho con ❤️ por MVP2o.ai

Contribuir mediante Pull Requests

¡Agradecemos las contribuciones! Para enviar cambios:

Haz un fork de este repositorio y clona tu fork.
Crea una nueva rama de características desde la rama principal de tu fork:
```
git checkout -b feature/your-feature-name
```
Realiza tus cambios y haz commit de ellos en tu rama de características.

Sube tu rama a tu fork:

git push --set-upstream origin feature/your-feature-name

Abre un pull request desde tu fork/rama hacia la rama main del repositorio upstream (Mvp2o-ai/mcp-ide-bridge).
Espera la revisión y los comentarios de los mantenedores.

Consulta CONTRIBUTING.md para más detalles.