Skip to content

Commit f862bd8

Browse files
committed
Add stream, putAll and putAllMap to McpTransportContext
- Transports need to list a context's entries and combine contexts, for instance to add the decoded Mcp-Param-* headers to a context built by a user-provided extractor. - This introduces a way to merge McpTransportContext. To do so, it introduces a way to read entries from the contexts, by key-value. - This change is non-breaking but custom implementations of McpTransportContext used in the modern server MUST implement stream(). The implementation is inspired from Reactor's Context. Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>
1 parent 54e8b61 commit f862bd8

4 files changed

Lines changed: 204 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,14 @@ Versioning follows [Semantic Versioning](https://semver.org/); see
1717
| 1.1.x | [1.1.4](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.1.4) (2026-08-19) | 2025-06-18 | Security patches only |
1818
| 0.18.x | [0.18.4](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.18.4) (2026-08-19) | 2025-06-18 | Security patches only |
1919

20+
## Unreleased (2.2.0)
21+
22+
- `McpTransportContext` gains the default methods `stream()`, `putAll` and
23+
`putAllMap` to list and merge contexts. The default `stream()` throws
24+
`UnsupportedOperationException`; custom implementations used with the
25+
modern server must implement it, as the servlet transport merges the
26+
`Mcp-Param-*` headers into the context of `tools/call` requests.
27+
2028
## 2.0.1 — 2026-08-19
2129

2230
- Bound STDIO and HTTP client/server reads to a configurable maximum size

‎mcp-core/src/main/java/io/modelcontextprotocol/common/DefaultMcpTransportContext.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
package io.modelcontextprotocol.common;
66

77
import java.util.Map;
8+
import java.util.stream.Stream;
89

910
import io.modelcontextprotocol.util.Assert;
1011

@@ -28,6 +29,11 @@ public Object get(String key) {
2829
return this.metadata.get(key);
2930
}
3031

32+
@Override
33+
public Stream<Map.Entry<String, Object>> stream() {
34+
return this.metadata.entrySet().stream();
35+
}
36+
3137
@Override
3238
public boolean equals(Object o) {
3339
if (o == null || getClass() != o.getClass())

‎mcp-core/src/main/java/io/modelcontextprotocol/common/McpTransportContext.java‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@
55
package io.modelcontextprotocol.common;
66

77
import java.util.Collections;
8+
import java.util.LinkedHashMap;
89
import java.util.Map;
10+
import java.util.stream.Stream;
911

1012
/**
1113
* Context associated with the transport layer. It allows to add transport-level metadata
@@ -26,6 +28,7 @@
2628
* </ul>
2729
*
2830
* @author Dariusz Jędrzejczyk
31+
* @author Daniel Garnier-Moiroux
2932
*/
3033
public interface McpTransportContext {
3134

@@ -58,4 +61,59 @@ static McpTransportContext create(Map<String, Object> metadata) {
5861
*/
5962
Object get(String key);
6063

64+
/**
65+
* Stream the entries of this context, in no particular order.
66+
* <p>
67+
* Unimplemented and throws by default. Implementations used in the modern version of
68+
* the spec MUST implement this method.
69+
* @return a stream of the key-value pairs held by this context
70+
* @since 2.2.0
71+
*/
72+
default Stream<Map.Entry<String, Object>> stream() {
73+
throw new UnsupportedOperationException("%s must implement stream()".formatted(this.getClass().getName()));
74+
};
75+
76+
/**
77+
* Create a new context holding the entries of this context and those of
78+
* {@code other}. When both contexts hold the same key, the value from {@code other}
79+
* wins. Neither context is modified. When {@code other} is empty, this context is
80+
* returned as is.
81+
* <p>
82+
* The entries are copied eagerly into a new context, as created by
83+
* {@link #create(Map)}, so the result compares equal to a context created directly
84+
* from the same entries.
85+
* @param other the context whose entries are added, taking precedence over the
86+
* entries of this context
87+
* @return a new context holding the merged entries
88+
* @since 2.2.0
89+
*/
90+
default McpTransportContext putAll(McpTransportContext other) {
91+
Map<String, Object> entries = new LinkedHashMap<>();
92+
other.stream().forEach(entry -> entries.put(entry.getKey(), entry.getValue()));
93+
return putAllMap(entries);
94+
}
95+
96+
/**
97+
* Create a new context holding the entries of this context and those of {@code map}.
98+
* When both hold the same key, the value from {@code map} wins. Neither this context
99+
* nor the map is modified. When {@code map} is empty, this context is returned as is.
100+
* <p>
101+
* The entries are copied eagerly into a new context, as created by
102+
* {@link #create(Map)}, so the result compares equal to a context created directly
103+
* from the same entries. As with {@link #create(Map)}, {@code null} values are
104+
* rejected.
105+
* @param map the entries to add, taking precedence over the entries of this context
106+
* @return a new context holding the merged entries
107+
* @since 2.2.0
108+
*/
109+
default McpTransportContext putAllMap(Map<String, ?> map) {
110+
if (map.isEmpty()) {
111+
return this;
112+
}
113+
Map<String, Object> merged = new LinkedHashMap<>();
114+
stream().forEach(entry -> merged.put(entry.getKey(), entry.getValue()));
115+
merged.putAll(map);
116+
return create(merged);
117+
}
118+
61119
}

‎mcp-core/src/test/java/io/modelcontextprotocol/common/McpTransportContextTests.java‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
import org.junit.jupiter.api.Test;
1111

1212
import static org.assertj.core.api.Assertions.assertThat;
13+
import static org.assertj.core.api.Assertions.assertThatThrownBy;
1314

1415
/**
1516
* Tests for {@link McpTransportContext#create(Map)}, which is documented to return an
@@ -86,4 +87,135 @@ void createdContextFromAnImmutableMapIsAlreadyCorrect() {
8687
assertThat(context.get("tenant")).isEqualTo("acme");
8788
}
8889

90+
@Test
91+
void streamShouldListEveryEntryOfTheContext() {
92+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme", "region", "eu"));
93+
94+
assertThat(context.stream()).containsExactlyInAnyOrder(Map.entry("tenant", "acme"), Map.entry("region", "eu"));
95+
}
96+
97+
@Test
98+
void streamOfTheEmptyContextShouldBeEmpty() {
99+
assertThat(McpTransportContext.EMPTY.stream()).isEmpty();
100+
}
101+
102+
@Test
103+
void putAllShouldKeepTheEntriesOfBothContexts() {
104+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
105+
McpTransportContext other = McpTransportContext.create(Map.of("region", "eu"));
106+
107+
McpTransportContext merged = context.putAll(other);
108+
109+
assertThat(merged.get("tenant")).isEqualTo("acme");
110+
assertThat(merged.get("region")).isEqualTo("eu");
111+
}
112+
113+
@Test
114+
void putAllShouldLetTheArgumentWinOnSharedKeys() {
115+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
116+
McpTransportContext other = McpTransportContext.create(Map.of("tenant", "other"));
117+
118+
assertThat(context.putAll(other).get("tenant")).isEqualTo("other");
119+
}
120+
121+
@Test
122+
void putAllShouldLeaveBothOriginalContextsUnchanged() {
123+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
124+
McpTransportContext other = McpTransportContext.create(Map.of("tenant", "other", "region", "eu"));
125+
126+
context.putAll(other);
127+
128+
assertThat(context.stream()).containsExactly(Map.entry("tenant", "acme"));
129+
assertThat(other.stream()).containsExactlyInAnyOrder(Map.entry("tenant", "other"), Map.entry("region", "eu"));
130+
}
131+
132+
@Test
133+
void putAllWithAnEmptyContextShouldReturnTheSameContext() {
134+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
135+
136+
assertThat(context.putAll(McpTransportContext.EMPTY)).isSameAs(context);
137+
assertThat(context.putAll(McpTransportContext.create(Map.of()))).isSameAs(context);
138+
}
139+
140+
@Test
141+
void putAllShouldBeEqualToAContextCreatedFromTheMergedEntries() {
142+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme", "region", "us"));
143+
McpTransportContext other = McpTransportContext.create(Map.of("region", "eu"));
144+
145+
McpTransportContext merged = context.putAll(other);
146+
147+
McpTransportContext expected = McpTransportContext.create(Map.of("tenant", "acme", "region", "eu"));
148+
assertThat(merged).isEqualTo(expected);
149+
assertThat(merged).hasSameHashCodeAs(expected);
150+
}
151+
152+
@Test
153+
void putAllMapShouldKeepTheEntriesOfTheContextAndTheMap() {
154+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
155+
156+
McpTransportContext merged = context.putAllMap(Map.of("region", "eu"));
157+
158+
assertThat(merged.get("tenant")).isEqualTo("acme");
159+
assertThat(merged.get("region")).isEqualTo("eu");
160+
}
161+
162+
@Test
163+
void putAllMapShouldLetTheMapWinOnSharedKeys() {
164+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
165+
166+
assertThat(context.putAllMap(Map.of("tenant", "other")).get("tenant")).isEqualTo("other");
167+
}
168+
169+
@Test
170+
void putAllMapShouldLeaveTheOriginalContextUnchanged() {
171+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
172+
173+
context.putAllMap(Map.of("tenant", "other"));
174+
175+
assertThat(context.get("tenant")).isEqualTo("acme");
176+
}
177+
178+
@Test
179+
void putAllMapWithAnEmptyMapShouldReturnTheSameContext() {
180+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
181+
182+
assertThat(context.putAllMap(Map.of())).isSameAs(context);
183+
}
184+
185+
@Test
186+
void putAllMapShouldBeEqualToAContextCreatedFromTheMergedEntries() {
187+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme", "region", "us"));
188+
189+
McpTransportContext merged = context.putAllMap(Map.of("region", "eu"));
190+
191+
assertThat(merged).isEqualTo(McpTransportContext.create(Map.of("tenant", "acme", "region", "eu")));
192+
}
193+
194+
@Test
195+
void putAllMapShouldRejectNullValues() {
196+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
197+
Map<String, Object> withNullValue = new HashMap<>();
198+
withNullValue.put("region", null);
199+
200+
assertThatThrownBy(() -> context.putAllMap(withNullValue)).isInstanceOf(NullPointerException.class);
201+
}
202+
203+
@Test
204+
void shouldImplementStream() {
205+
var context = new TestTransportContext();
206+
207+
assertThatThrownBy(context::stream).isInstanceOf(UnsupportedOperationException.class)
208+
.hasMessage(
209+
"io.modelcontextprotocol.common.McpTransportContextTests$TestTransportContext must implement stream()");
210+
}
211+
212+
static class TestTransportContext implements McpTransportContext {
213+
214+
@Override
215+
public Object get(String key) {
216+
return null;
217+
}
218+
219+
}
220+
89221
}

0 commit comments

Comments
 (0)