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

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

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()

import mcp_use

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

// 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}

## 📋 Available Tools

### Core Messaging Tools

| Tool | Description | Use Case |
|------|-------------|----------|
| `checkin_client` | Register your presence | Announce availability |
| `send_message_without_waiting` | Fire & forget messaging | **ONLY** messaging method |
| `get_messages` | **📬 ESSENTIAL** - Check for replies | **Required** after messaging |
| `get_my_identity` | Get configuration help | Setup assistance |
| `get_active_sessions` | View active connections | Monitor team activity |

### 🚀 Messaging Workflow

**MESSAGING PATTERN**: Fire-and-forget + get_messages for efficient communication:

**1. Send Messages (Fire & Forget):**
```bash
# 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."]
)

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

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

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

# 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

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

# Install required dependency
pip install requests

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

# 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

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

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

# 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

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

# 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

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

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

**Setup Steps for Non-IDE Clients:**

1. **Create MCP proxy endpoint** (`/api/mcp-proxy` or equivalent)
2. **Hardcode your recipient configuration** (no `mcp_recipients.json` files needed)
3. **Intercept only messaging tools:** `send_message_without_waiting`, `get_messages`, `get_my_identity`, `checkin_client`
4. **Inject required parameters** where missing (sender_id, client_id, etc.)
5. **Override `get_my_identity`** to return your config as markdown
6. **Forward everything else unchanged** (conservative approach)

**Framework Examples:**

```python
# 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'])