Implemented Transport-Translation Bridge (mcpgateway.translate)

[manavgup]

📝 Pull Request Template Selection

Thank you for contributing! To help us review your pull request effectively, please select the appropriate template:

• Feature / Enhancement: Use the Feature Template
  I have implemented the Transport-Translation Bridge (mcpgateway.translate) feature for the MCP Gateway.

Key Components Implemented:

1. Core Bridge Implementation

• mcpgateway/translate/init.py: Complete CLI interface with argparse, validation, and configuration management
• mcpgateway/translate/bridge.py: Core bridge logic with pluggable transport endpoints and bidirectional message pumping
• Support for stdio, SSE, WebSocket, and Streamable-HTTP transports
• Reuses existing SSETransport and WebSocketTransport classes

2. CLI Features

• Console script entry point: mcpgateway-translate
• Mutually exclusive input transports (--stdio, --sse, --streamableHttp)
• Auto-detection of output transport based on input
• Comprehensive flag validation and error handling
• Support for headers, OAuth2 Bearer tokens, CORS, and health endpoints

3. Docker Support

• docker/translate.Dockerfile: Multistage build based on python:3.12-slim
• Multiple variants: base, uvx (Node.js support), deno
• Updated CI/CD pipeline to build and push all variants with proper tagging
• Lightweight images with security best practices

4. Testing & Quality

• tests/unit/mcpgateway/translate/test_cli.py: Comprehensive CLI tests
• tests/unit/mcpgateway/translate/test_bridge.py: Core bridge functionality tests
• Unit tests cover argument parsing, validation, transport endpoints, and message routing
• High test coverage with mocking for external dependencies

5. Documentation

• docs/translate.md: Complete user guide with quick start, command reference, use cases
• Covers Docker usage, environment variables, API endpoints, security considerations
• Includes troubleshooting guide and performance tuning recommendations

User Stories Fulfilled:

✅ User Story 1: mcpgateway-translate --stdio "uvx mcp-server-git" --port 9000 exposes stdio server over SSE
✅ User Story 2: mcpgateway-translate --sse "https://corp.example.com/mcp" bridges remote SSE to local stdio
✅ User Story 3: Health endpoint and CORS support with --healthEndpoint /healthz --cors "https://app.example.com"
✅ User Story 4: Official Docker images with variants published to GHCR

Production-Ready Features:

• Token redaction and security features
• CORS support with origin validation
• Health check endpoints for load balancer integration
• Comprehensive error handling and logging
• Environment variable configuration
• Bidirectional message pumping with JSON-RPC integrity
• Connection pooling and performance optimizations

The implementation is ready for production use and provides a first-class, batteries-included bridge for running any MCP stdio-based server or remote endpoint over every other official transport protocol.

[manavgup]

@madhav165 - any update on this?

[crivetimihai]

Updated #94 with more information - there should not a bridge.py as mcpgateway.translate already provides that interface.

[manavgup]

here is a concise summary of changes:

• Updated module docstring to include bidirectional bridging and additional authorship.
• Added cors_origins parameter and CORS middleware setup in _build_fastapi.
• Added CLI arguments --cors and --oauth2Bearer in _parse_args.
• Updated _run_stdio_to_sse to accept cors parameter and pass it to _build_fastapi.
• Added new async function _run_sse_to_stdio implementing SSE to stdio bridge.
• Updated main function to route execution based on --stdio or --sse CLI arguments.

These changes implement the SSE→stdio bridge, enhance CORS and authentication support, and update CLI handling accordingly.

Testing the SSE→stdio functionality:

Method 1: Using the test server

# Run the test server manually
python tests/integration/test_translate_sse_to_stdio.py

# In another terminal, test the bridge
python -m mcpgateway.translate --sse http://localhost:8001/sse

Method 2: Using two bridges

# Terminal 1: stdio→SSE bridge
python -m mcpgateway.translate --stdio "uvenv run mcp-server-git" --port 9000

# Terminal 2: SSE→stdio bridge
python -m mcpgateway.translate --sse "http://localhost:9000/sse"

# Terminal 3: Send test messages
curl -X POST http://localhost:9000/message \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'