Add gRPC Transport Implementation #8
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Proto definition (proto/mcp/v1/mcp.proto) with native streaming RPCs - Python GrpcClientTransport implementing ClientTransportSession - Streaming support for progress, parallel tools, chunked resources, watches - Bidirectional Session RPC for complex agent interactions
- Implement Session stream for multiplexed requests/responses - Add chunked resource reading via ReadResourceChunked RPC - Add background resource watchers for push notifications - Add proper gRPC error mapping to Python exceptions - Generate proto stubs to src/mcp/v1/ - Add grpc optional dependency to pyproject.toml - Add advanced streaming patterns documentation - Update docs navigation with gRPC transport links
- Replace paginated List RPCs with streaming equivalents - Simplify request/response structures by removing cursor fields - Align with gRPC streaming best practices on branch `streaming-updates`
- Add `Open Questions` section in proto/README.md for stream vs pagination discussion - Detail current implementation limits and considerations for true streaming - Propose potential enhancements like client-requested limits and async generators in Server implementation - Refine gRPC transport documentation on branch `streaming-updates`
- Implement `GrpcServerSession` for handling gRPC request contexts - Add `McpGrpcServicer` for mapping MCP server methods to gRPC services - Support unary and streaming RPCs for tools, resources, and prompts - Provide bidirectional communication with `Session` stream - Include helper methods for protobuf type conversions - Add `start_grpc_server` to initialize gRPC server with optional TLS support - Enhance logging and error handling for incomplete gRPC features
…s, prompts, and templates on branch `streaming-updates` - Replace cursor-based pagination with streaming iterations - Adjust return types to collect results from async streams - Add warnings for unsupported cursor usage - Enhance readability and maintain consistency across list methods
- Implement tests for gRPC server and client interactions - Verify tool calls, resource management, progress tracking, and prompts consistency - Ensure handling of errors and maintaining session health
…ests for gRPC module on branch `streaming-updates`
…tions in `proto/README.md` on branch `streaming-updates` - Introduce a memory-efficient streaming alternative to existing `ClientTransportSession` methods - Ensure backward compatibility with existing implementations - Pose open design questions about streaming abstraction
… on branch `streaming-updates` - Outline architecture for transparent streaming across gRPC and JSON-RPC - Introduce `StreamingAdapter` for backward compatibility and unified interface - Detail cross-protocol bridging for mixed deployments - Highlight benefits of streaming abstraction without breaking existing implementations
…to on branch `streaming-updates` - Define `StreamEnd` and `StreamError` messages for explicit stream completion - Add `RequestMeta` for correlation and tracing across transports - Update list and stream response messages to support new streaming semantics - Document streaming behaviors and transport differences in README
…h `streaming-updates` - Update proto definitions: simplify response messages, refine `StreamEnd` semantics - Revise `SessionResponse` to include top-level control messages - Standardize bidirectional streaming behaviors; remove `oneof payload` pattern - Clarify stream termination and error signaling in `proto/README.md` - Add Google Cloud blog post to document benefits of gRPC as MCP transport
…level API sections on branch `streaming-updates`
…reaming-updates` - Revise phrasing for clarity and consistency - Adjust formatting, headings, and terminology - Highlight differences between gRPC and JSON-RPC transport behaviors - Streamline explanation of backward compatibility and streaming benefits
…posal on branch `streaming-updates` - Update `CancelRequest` documentation to clarify `request_id` matching - Specify `StreamEnd.request_id` alignment for explicit stream termination
…anch `streaming-updates` - Add `StreamingAdapter` to provide a unified streaming interface for `ClientTransportSession` - Implement streaming methods for listing tools, resources, templates, and prompts - Refactor gRPC client to support native streaming with backpressure handling - Register new handlers for `StreamPromptCompletion` and resource watch updates - Expand tests for streaming methods across client and server sessions - Update dependencies to include `grpcio` and `grpcio-tools`
Split Session streaming branches into helper methods and add a shared response emitter for clarity. Keep behavior unchanged while simplifying per-request flow and cancellation handling.
- Compact initialization logic for better readability and reuse in `_handle_session_initialize` - Optimize argument unpacking and inline lambda usage in GrpcServerSession methods - Add parallel execution for `StreamToolCalls`, supporting asynchronous tool calls - Remove unused imports and simplify formatting across multiple methods - Enhance backpressure handling and error reporting for streaming scenarios
…reaming-updates` - Replace hardcoded timeout values with `PROGRESS_POLL_TIMEOUT_SECONDS` and `WATCH_RESOURCES_POLL_TIMEOUT_SECONDS` - Improve maintainability and readability by using named constants
Route unary and streaming RPCs through per-peer GrpcServerSession instances to avoid cross-client state leaks. Add Session initialization guard and extend gRPC session tests for StreamToolCalls and CallToolWithProgress.
Send Initialize before Session list_tools calls to match the new session initialization requirement. Adds the missing InitializeRequest import for the test.
…k` guard - Add `initialize_task` to track async initialization progress. - Await the task or send an error if initialization fails. - Safeguard against uninitialized session errors with improved checks. Branch: `streaming-updates`
- Split session handling into modular helper methods for improved readability and maintainability. - Add `_dispatch_session_request` to centralize request routing for various payload types. - Exclude untyped gRPC modules from Pyright type checking for compatibility. - Refactor `Session` implementation to streamline request handling and initialization flow. Branch: `streaming-updates`
Resolve conflicts: - pyproject.toml: combine dev dependencies and pyright config - src/mcp/client/__init__.py: merge exports - src/mcp/server/lowlevel/server.py: keep stream_prompt_completion handler and updated _make_error_result
Updates camelCase field names to snake_case to match the refactored MCP types: - protocolVersion -> protocol_version - serverInfo -> server_info - listChanged -> list_changed - nextCursor -> next_cursor - isError -> is_error - inputSchema -> input_schema - mimeType -> mime_type - resourceTemplates -> resource_templates Also: - Add missing abstract methods to GrpcServerSession (send_message, elicit_form, elicit_url) - Remove result.root wrapper access since ServerResult is now a Union - Export StreamPromptCompletionChunk from types module - Update uri types from AnyUrl to str where needed - Fix ruff lint issues (imports, docstrings)
9 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I've given a first pass at a gRPC implementation for the python SDK - I'll be glad to do the java one next.
This implementation has a 1:1 implementation with the proper transport layer and I've included the protobuf definition. It follows all best practices for gRPC - including passing all linting and formatting as well as documentation standards in the IDF file.
I'd love to talk more about this definition file to finalize the definition. I'm creating a grpc-centric application and MCP is a major part of it - this will bring major performance improvements to MCP for pipeline processing.
Please observe the streaming capabilities - they use python's standards for async processing and the chunking is true streaming (notice the lack of cursors) - but also provides tunneling capabilties should these two ever need to work together.
I have a number of markdown files that go over the design - the tunneling was especially important and full backward compatibility is maintained. Tests are included as well. All changes are non-breaking and the tests successfully run.
What's Here
The implementation provides real streaming gRPC support for MCP, not just request/response wrapped in gRPC. The transport uses true bidirectional streaming where both client and server can push messages independently.
Key points
What's included
Testing
All existing tests pass. New tests cover the gRPC transport specifically.