feat: add MCP proxy pattern convenience function (#12)

[dgenio]

Description

Implements the mcp_proxy() convenience function that enables bidirectional message forwarding between two MCP transports, porting the TypeScript proxy pattern to the Python SDK.

Changes

• Added mcp_proxy() context manager in src/mcp/shared/proxy.py
• Implements bidirectional message forwarding using anyio task groups
• Supports optional error handling with sync/async callbacks
• Automatically closes both transports when one closes
• Comprehensive test coverage in tests/shared/test_proxy.py

Features

• Bidirectional forwarding: Messages flow in both directions simultaneously
• Error handling: Optional onerror callback (supports both sync and async)
• Automatic cleanup: When one transport closes, the other is also closed
• Exception handling: Properly handles SessionMessage and Exception objects from read streams
• Resource management: Uses context manager pattern for proper cleanup

Usage Example

from mcp.shared.proxy import mcp_proxy

async with mcp_proxy(
transport_to_client=(client_read, client_write),
transport_to_server=(server_read, server_write),
onerror=lambda e: logger.error(f"Proxy error:{e}"),
):
# Proxy is active, forwarding messages bidirectionally
await some_operation()

Both transports are closed when exiting the context## Testing

• Unit tests cover bidirectional forwarding, error handling, stream cleanup, and edge cases
• All tests pass with proper async/await patterns
• Follows existing test patterns in the repository

Related

Closes#12

Type of Change

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

Checklist

• Code follows the repository's style guidelines
• Tests added/updated for new functionality
• All tests pass locally
• Linting and type checking pass
• Documentation updated (if applicable)

[Kludex]

Any reason why you closed this?

[dgenio]

Any reason why you closed this?

Thanks for asking — and sorry for the noise.
I closed it because the CI kept failing and I realised I wouldn’t be able to invest the time to properly debug and fix it in the short term. I also wasn’t sure what the preferred etiquette is here (leaving a PR with red CI open for a while vs. closing and reopening later), so I chose to close it for now.

If you’d prefer a different workflow, I’m happy to reopen this (possibly as a draft) and keep iterating when I have time, or for someone from the team to pick it up from where it is. In any case, I’m still keen on getting this proxy helper merged eventually.

[Kludex]

I'll leave it open. I'm interested in this feature.

[jlowin]

I'm interested in this feature.

Same. I tried to build something very similar to this a few months ago and ran into some async context manager issues (IIRC); hoping this solves it!

[jlowin]

@Kludex@dgenio I opened #1763 which includes all the commits from this PR plus some changes to help the coverage tests pass; as far as I can tell it's a race condition between parallel works and cleanup blocks (resulting in some workers never running the cleanup block and reporting <100% coverage), in addition to some small annotations on the core code.