MCP IDE Bridge

Um servidor de mensagens de código aberto para comunicação entre clientes usando MCP HTTP

Documentação

MCP IDE Bridge

🎬 Vídeo de Demonstração

FRONT END WEB APP CURSOR IDE	BACK END API CURSOR IDE

Clique na imagem acima para assistir à demonstração ao vivo do MCP IDE Bridge em ação!
Isso mostra dois Cursor IDEs (front end e back end) colaborando em tempo real por meio do IDE Bridge.

Um servidor MCP (Model Context Protocol) HTTP Streamable, open source e sem estado, que permite comunicação cliente-a-cliente entre IDEs e ferramentas de desenvolvimento. Isso abre uma nova dimensão de colaboração além das interações tradicionais cliente-servidor do MCP.

🚀 Perfeito para: Colaboração entre IDEs, fluxos de trabalho de desenvolvimento em equipe, coordenação de agentes de IA e integração perfeita de ferramentas.

🌟 O Que Torna Isso Especial?

MCP Tradicional vs MCP IDE Bridge

MCP Tradicional	MCP IDE Bridge
Cliente ↔ Servidor	Cliente ↔ Servidor ↔ Cliente
Comunicação unidirecional	Mensageria bidirecional
Apenas execução de ferramentas	Colaboração em tempo real
Foco em um único IDE	Coordenação multi-IDE

Casos de Uso no Mundo Real

🎯 Colaboração entre IDEs

Cursor ↔ Cursor: Compartilhe trechos de código, sessões de depuração ou programação em par
Cursor ↔ VS Code: Comunicação entre editores e compartilhamento de arquivos
Windsurf ↔ Qualquer IDE: Coordenação de agentes de IA em diferentes ambientes de desenvolvimento
Fluxos de Trabalho em Equipe: Coordene vários desenvolvedores trabalhando no mesmo projeto

🤖 Coordenação de Agentes de IA

Comunicação agente-a-agente para fluxos de trabalho complexos
Processamento distribuído de IA em múltiplas ferramentas
Colaboração humano-no-circuito com assistentes de IA

🏗️ Arquitetura

Comunicação Cliente-a-Cliente

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

Componentes Principais

Retransmissão de Mensagens: Servidor sem estado que roteia mensagens entre clientes
Registro de Clientes: Descoberta e registro dinâmico de clientes
Filas de Mensagens: Filas por destinatário com expiração automática
HTTP Streamable: Transporte MCP mais recente para comunicação em tempo real

🚀 Início Rápido

1. Inicie o Servidor

Docker (Recomendado):

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

Configuração Padrão:

Porta: 8111 (externa e interna)
Host: 0.0.0.0 (aceita conexões de qualquer interface)
Transporte: HTTP Streamable (MCP mais recente)
Verificação de Saúde: Monitoramento integrado de endpoint

Python (Configuração de Desenvolvimento):

# 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. Configure Seu IDE

Crie o arquivo mcp_recipients.json na raiz do seu projeto. Cada projeto recebe UM arquivo com seu próprio ID exclusivo e lista de destinatários com quem pode se comunicar:

{
  "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"
  }
}

🤖 Geração por Agente de IA: O agente de IA do seu IDE pode gerar este arquivo! Basta perguntar:

Cursor: "Gere um mcp_recipients.json para o meu projeto"
VS Code: "Crie a configuração mcp_recipients.json para minha equipe"
Windsurf: "Ajude-me a configurar mcp_recipients.json para colaboração"

📁 Exemplos Multi-Projeto: Consulte examples/multi-project-setup/ para exemplos de como diferentes projetos se comunicam. Cada arquivo de projeto deve ser nomeado mcp_recipients.json - os nomes de arquivo de exemplo nessa pasta são apenas para referência.

3. Conecte Seu IDE

Cursor IDE:

Crie o arquivo .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"
    }
  }
}

Abra a Paleta de Comandos (Cmd/Ctrl + Shift + P)
Pesquise por "MCP: Connect to Server"
Digite: http://localhost:8111/mcp/

VS Code:

Instale a extensão MCP do marketplace
Crie o arquivo mcp_recipients.json na raiz do projeto
Configure as configurações do MCP nas preferências do VS Code
Use os comandos MCP para conectar e colaborar

Windsurf:

Crie o arquivo mcp_recipients.json na raiz do projeto
Abra as configurações do Windsurf → configuração MCP
Adicione a URL do servidor: http://localhost:8111/mcp/
Comece a enviar mensagens com outros IDEs

Claude Desktop:

Crie o arquivo mcp_recipients.json na raiz do projeto
Abra as configurações do Claude Desktop → configuração MCP
Adicione a URL do servidor: http://localhost:8111/mcp/
Use a integração MCP do Claude para se comunicar

IDEs JetBrains (IntelliJ, PyCharm, etc.):

Instale o plugin MCP do marketplace de plugins
Crie o arquivo mcp_recipients.json na raiz do projeto
Configure o servidor MCP nas configurações do plugin
Use as ferramentas MCP a partir do IDE

Nota: Cada IDE requer tanto o mcp_recipients.json (para mensageria) quanto a configuração MCP específica do IDE (para conexão). Cada projeto recebe UM arquivo mcp_recipients.json com seu próprio ID exclusivo e lista de destinatários. O arquivo deve ser nomeado exatamente mcp_recipients.json e colocado na raiz do projeto para fácil descoberta pelos agentes do IDE. Consulte examples/multi-project-setup/README.md para instruções detalhadas de configuração.

🔗 Clientes Não-IDE (LangChain, mcp-use, Aplicativos Personalizados)

Visão Geral

Clientes não-IDE usam o mesmo protocolo MCP que os clientes IDE. A única diferença é como eles fornecem sua configuração:

Clientes IDE: Leem o mcp_recipients.json do sistema de arquivos local
Clientes não-IDE: Fornecem o recipients_config como parâmetro para as ferramentas MCP

Sem registro, sem endpoints REST, sem configuração especial - apenas injeção de parâmetros!

Isso permite integração perfeita com frameworks como LangChain, mcp-use, scripts Python personalizados e aplicações web.

Arquitetura

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

Configuração - Abordagem com Wrapper de Cliente

Crie um wrapper que injeta automaticamente sua configuração:

Integração 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()

Integração mcp-use:

import mcp_use

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

Implementação no Mundo Real: Padrão de Proxy

Para aplicações web em produção, a abordagem recomendada é um padrão de proxy/interceptador que lida seletivamente com ferramentas de mensageria:

Exemplo de Rota de API Next.js (implementação 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...`
}

Etapas de Configuração para Clientes Não-IDE:

Crie um endpoint de proxy MCP (/api/mcp-proxy ou equivalente)
Codifique sua configuração de destinatários (sem necessidade de arquivos mcp_recipients.json)
Intercepte apenas ferramentas de mensageria: send_message_without_waiting, get_messages, get_my_identity, checkin_client
Injete parâmetros obrigatórios quando ausentes (sender_id, client_id, etc.)
Substitua get_my_identity para retornar sua configuração como markdown
Encaminhe todo o resto sem alterações (abordagem conservadora)

Exemplos 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'])

Benefícios

🔗 Integração Simples: Mesmo protocolo que os clientes IDE
📡 Sem Configuração Especial: Apenas injeção de parâmetros
🚀 Controle no Lado do Cliente: O proxy gerencia a configuração
🛠️ Agnóstico de Framework: Funciona com qualquer biblioteca de cliente MCP
🏗️ Abordagem Conservadora: Intercepta apenas o necessário (99% do tráfego inalterado)
💾 Sem Dependências de Arquivo: Configuração em tempo de execução, sem necessidade de mcp_recipients.json
🔧 Pronto para Produção: Padrão usado no mundo real por projetos ativos

📋 Ferramentas Disponíveis

Ferramentas Principais de Mensageria

Ferramenta	Descrição	Caso de Uso
`checkin_client`	Registre sua presença	Anuncie disponibilidade
`send_message_without_waiting`	Mensageria fire & forget	ÚNICO método de mensageria
`get_messages`	📬 ESSENCIAL - Verifique respostas	Obrigatório após enviar mensagens
`get_my_identity`	Obtenha ajuda de configuração	Assistência de configuração
`get_active_sessions`	Veja conexões ativas	Monitore a atividade da equipe

🚀 Fluxo de Trabalho de Mensageria

PADRÃO DE MENSAGERIA: Fire-and-forget + get_messages para comunicação eficiente:

1. Envie Mensagens (Fire & Forget):

# 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. Verifique Respostas:

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

Padrões de Mensagem:

# 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")

Benefícios:

✅ Sem Bloqueio: Retorno instantâneo, sem esperas
✅ Escalável: Funciona para um ou mais destinatários com eficiência
✅ Rápido: Sem timeouts ou chamadas bloqueantes
✅ Melhor UX: Experiência de mensageria suave e responsiva

Exemplos de Fluxos de Trabalho

Colaboração em Equipe

# 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"

Coordenação 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

🔒 Considerações de Segurança

Estado Atual (Uso em Desktop)

✅ Adequado para:

Equipes de desenvolvimento locais
Projetos pessoais
Fluxos de trabalho apenas em desktop
Ambientes de rede confiáveis

⚠️ Limitações:

Sem autenticação além dos IDs de cliente
Sem criptografia de mensagens
Sem controle de acesso
Sem registro de auditoria

🔐 Modelo de Segurança:

IDs de cliente atuam como credenciais simples
Mensagens armazenadas apenas em memória
Expiração automática em 5 minutos
Sem armazenamento persistente

Solução Empresarial

Para uso em produção, segurança e colaboração em equipe, oferecemos MilesDyson.ai - uma Plataforma como Serviço Agêntica (aPaaS) de nível empresarial que aborda todas as preocupações de segurança:

🔐 Autenticação Empresarial: SSO, RBAC e trilhas de auditoria
🛡️ Criptografia de Ponta a Ponta: Todas as mensagens criptografadas em trânsito e em repouso
🌐 Infraestrutura Global: Implantação multi-região com disponibilidade de 99,9%
👥 Gerenciamento de Equipes: Gerenciamento de usuários, permissões e ferramentas de colaboração
📊 Análises: Insights de uso e monitoramento de desempenho
🔧 Suporte Empresarial: Suporte dedicado e integrações personalizadas

Saiba Mais → MilesDyson.ai

🧪 Testes

Harness de Teste MCP (Recomendado)

NOVO! Incluímos um harness de teste MCP abrangente (test_mcp_client.py) que torna o teste de todas as ferramentas MCP fácil e confiável:

# 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"}'

Recursos:

✅ Cabeçalhos MCP Adequados: Lida com text/event-stream e respostas de streaming corretamente
✅ Saída Bonita: Exibição limpa em markdown com depuração JSON bruta
✅ Todas as Ferramentas Suportadas: Teste cada ferramenta MCP com tratamento adequado de argumentos
✅ Argumentos Flexíveis: Use flags individuais ou JSON para parâmetros complexos
✅ Tratamento de Erros: Mensagens de erro claras e informações de solução de problemas

Instalação:

# Install required dependency
pip install requests

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

Teste Rápido de Conexão

# 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 Referência

O projeto inclui um cliente MCP de referência para testes:

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

🏗️ Desenvolvimento

Estrutura do Projeto

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 projeto recebe UM arquivo mcp_recipients.json com seu próprio ID exclusivo e lista de destinatários. Os nomes de arquivo de exemplo em multi-project-setup/ são apenas para referência - seu arquivo real deve ser nomeado mcp_recipients.json na raiz de cada projeto.

Desenvolvimento 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: A etapa pip install -e . é obrigatória para que o Python encontre corretamente o módulo mcp_messaging. Sem isso, você receberá ModuleNotFoundError: No module named 'mcp_messaging'.

🤝 Contribuindo

Aceitamos contribuições! Consulte CONTRIBUTING.md para:

Configuração de desenvolvimento
Diretrizes de estilo de código
Procedimentos de teste
Processo de pull request

📄 Licença

Licença MIT - consulte LICENSE para detalhes.

🚀 Solução Empresarial

Pronto para uso em produção?

MilesDyson.ai fornece MCP IDE Bridge de nível empresarial com:

🔐 Segurança Empresarial: SSO, criptografia, trilhas de auditoria
🌐 Infraestrutura Global: Multi-região, alta disponibilidade
👥 Gerenciamento de Equipes: Gerenciamento de usuários e ferramentas de colaboração
📊 Análises e Monitoramento: Insights de uso e rastreamento de desempenho
🔧 Suporte Empresarial: Suporte dedicado e integrações personalizadas

Perfeito para:

Equipes de desenvolvimento
Ambientes empresariais
Implantações em produção
Colaboração multi-organização

Construído com transporte MCP HTTP Streamable • Desenvolvido com FastMCP • Feito com ❤️ pela MVP2o.ai

Contribuindo via Pull Requests

Aceitamos contribuições! Para enviar alterações:

Faça um fork deste repositório e clone o seu fork.
Crie um novo branch de funcionalidade a partir do branch principal do seu fork:
```
git checkout -b feature/your-feature-name
```
Faça suas alterações e faça commit delas no seu branch de funcionalidade.

Envie seu branch para o seu fork:

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

Abra um pull request do seu fork/branch para o branch main do repositório upstream (Mvp2o-ai/mcp-ide-bridge).
Aguarde a revisão e o feedback dos mantenedores.

Consulte CONTRIBUTING.md para mais detalhes.