feat(mcp): introduce unified request context API and enhance documentation #4633
Conversation
…ation - Add StreamableMcpAnnotations2IT integration test covering: - Tool execution with progress notifications - Sampling and elicitation capabilities - Structured output support with CallToolResult - Resource and prompt handling - Completion functionality - Logging notifications - Client-server bidirectional communication - Refactor documentation to use McpSyncRequestContext/McpAsyncRequestContext: - Replace McpSyncServerExchange/McpAsyncServerExchange examples - Add convenient helper methods (info(), progress(), ping(), elicit(), sample()) - Update examples to show unified context API usage - Document capability checking (elicitEnabled(), sampleEnabled(), rootsEnabled()) - Add method filtering policies documentation: - Explain sync vs async method filtering behavior - Document stateful vs stateless filtering rules - Provide best practices for method filtering - Improve special parameters documentation: - Update to show unified request context usage patterns - Add examples of accessing progress token via context - Document limitations of stateless servers - Show capability-aware implementation patterns - Note that McpSyncRequestContext/McpAsyncRequestContext work with both stateful and stateless modes The unified context API provides a cleaner, more intuitive interface for MCP operations and works seamlessly with both stateful and stateless server configurations. Signed-off-by: Christian Tzolov <[email protected]>
| // Progress notifications | ||
| if (progressToken != null) { | ||
| context.progress(50); // Simple percentage |
There was a problem hiding this comment.
This example should be changed to clarify that progress is not necessarily a percentage (eg add total=100)
| **Stateless servers do not support bidirectional operations:** | ||
|
|
||
| * `roots()` - Not available | ||
| * `elicit()` - Not available |
There was a problem hiding this comment.
I think those should be named elicitation() and sampling() (same for the Enabled variations below)
| // Check if elicitation is supported before using it | ||
| if (context.elicitEnabled()) { | ||
| // Safe to use elicitation | ||
| var result = context.elicit(UserInfo.class); |
There was a problem hiding this comment.
What happens if the client doesn't support elicitation? Could we make it a NOOP (with warning)?
There was a problem hiding this comment.
It will throw runtime exception and propagate it back to the client that called the tool, resource, prompt, complete handler that uses elicit internally.
Also It doesn't make much sense to ignore the elicit call with NOOP. For example a tool call handler may use elicit to get additional info, like user consent to apply some action. The NOOP can provide a default declined response. Is this desired.
Anyway we can make this configurable strategy and have NOOP as an option. But in a follow up issue
Signed-off-by: Christian Tzolov <[email protected]>
|
thanks @ericbottard , pushed an update |
|
LGTM, rebased, squashed and merged as 3e6084c |
3 participants
Add StreamableMcpAnnotations2IT integration test covering:
Refactor documentation to use McpSyncRequestContext/McpAsyncRequestContext:
Add method filtering policies documentation:
Improve special parameters documentation:
The unified context API provides a cleaner, more intuitive interface for MCP operations and works seamlessly with both stateful and stateless server configurations.