Skip to content

Commit 6ce6a28

Browse files
authored
Add putAll(Map) to McpTransportContext (#1288)
- Add a `.putAll(Map)` API to McpTransportContext. Transports need to add their own keys to the context a user-provided extractor built, for instance the decoded Mcp-Param-* headers. Keys from `putAll` take precedence over existing keys. Context remains immutable. - Remove content-based equals and hashCode from McpTransportContext. Comparing transport contexts was never a goal, and with putAll a context can be layered over the one a user's extractor returns. Tests now check the entries a context holds rather than context equality. This is a non-breaking change for existing transports. Signed-off-by: Dariusz Jedrzejczyk <2554306+chemicL@users.noreply.github.com>
1 parent 50e788d commit 6ce6a28

6 files changed

Lines changed: 210 additions & 37 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,15 @@ 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+
- Add `McpTransportContext.putAll(Map)`, returning a context that combines an
23+
existing context with additional entries, which take precedence.
24+
- `McpTransportContext` no longer compares contexts by their contents in
25+
`equals` and `hashCode`. With `putAll`, transports can layer their own entries
26+
over the context a user's extractor returns, and comparing contexts was never
27+
a goal; read entries via `get(String)` instead.
28+
2029
## 2.0.1 — 2026-08-19
2130

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

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

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
package io.modelcontextprotocol.common;
66

7+
import java.util.HashMap;
78
import java.util.Map;
89

910
import io.modelcontextprotocol.util.Assert;
@@ -18,7 +19,7 @@ class DefaultMcpTransportContext implements McpTransportContext {
1819

1920
private final Map<String, Object> metadata;
2021

21-
DefaultMcpTransportContext(Map<String, Object> metadata) {
22+
DefaultMcpTransportContext(Map<String, ?> metadata) {
2223
Assert.notNull(metadata, "The metadata cannot be null");
2324
this.metadata = Map.copyOf(metadata);
2425
}
@@ -29,17 +30,17 @@ public Object get(String key) {
2930
}
3031

3132
@Override
32-
public boolean equals(Object o) {
33-
if (o == null || getClass() != o.getClass())
34-
return false;
35-
36-
DefaultMcpTransportContext that = (DefaultMcpTransportContext) o;
37-
return this.metadata.equals(that.metadata);
38-
}
39-
40-
@Override
41-
public int hashCode() {
42-
return this.metadata.hashCode();
33+
public McpTransportContext putAll(Map<String, ?> map) {
34+
Assert.notNull(map, "The map cannot be null");
35+
if (map.isEmpty()) {
36+
return this;
37+
}
38+
if (this.metadata.isEmpty()) {
39+
return new DefaultMcpTransportContext(map);
40+
}
41+
Map<String, Object> merged = new HashMap<>(this.metadata);
42+
merged.putAll(map);
43+
return new DefaultMcpTransportContext(merged);
4344
}
4445

4546
}

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
import java.util.Collections;
88
import java.util.Map;
99

10+
import io.modelcontextprotocol.util.Assert;
11+
1012
/**
1113
* Context associated with the transport layer. It allows to add transport-level metadata
1214
* for use further down the line. Specifically, it can be beneficial to extract HTTP
@@ -58,4 +60,24 @@ static McpTransportContext create(Map<String, Object> metadata) {
5860
*/
5961
Object get(String key);
6062

63+
/**
64+
* Create a new context holding the values of this context and of the specified map.
65+
* When both hold the same key, the value from the provided map wins. Neither this
66+
* context nor the provided map is modified. When the provided map is empty, this
67+
* context is returned as is.
68+
* <p>
69+
* Keys absent from the provided map are looked up in this context. As with
70+
* {@link #create(Map)}, {@code null} keys and values are rejected.
71+
* @param map the values to add, taking precedence over the values of this context
72+
* @return a new context holding the merged values
73+
* @since 2.2.0
74+
*/
75+
default McpTransportContext putAll(Map<String, ?> map) {
76+
Assert.notNull(map, "The map cannot be null");
77+
if (map.isEmpty()) {
78+
return this;
79+
}
80+
return new OverlayMcpTransportContext(this, map);
81+
}
82+
6183
}
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
/*
2+
* Copyright 2026-2026 the original author or authors.
3+
*/
4+
5+
package io.modelcontextprotocol.common;
6+
7+
import java.util.HashMap;
8+
import java.util.Map;
9+
10+
import io.modelcontextprotocol.util.Assert;
11+
12+
/**
13+
* {@link McpTransportContext} that looks up keys in a map first and falls back to a base
14+
* context. {@link #putAll(Map)} returns a new instance over the same base.
15+
*
16+
* @author Dariusz Jędrzejczyk
17+
*/
18+
final class OverlayMcpTransportContext implements McpTransportContext {
19+
20+
private final McpTransportContext base;
21+
22+
private final Map<String, Object> overlay;
23+
24+
OverlayMcpTransportContext(McpTransportContext base, Map<String, ?> overlay) {
25+
Assert.notNull(base, "The base context cannot be null");
26+
Assert.notNull(overlay, "The overlay cannot be null");
27+
this.base = base;
28+
this.overlay = Map.copyOf(overlay);
29+
}
30+
31+
@Override
32+
public Object get(String key) {
33+
Object value = this.overlay.get(key);
34+
return (value != null) ? value : this.base.get(key);
35+
}
36+
37+
@Override
38+
public McpTransportContext putAll(Map<String, ?> map) {
39+
Assert.notNull(map, "The map cannot be null");
40+
if (map.isEmpty()) {
41+
return this;
42+
}
43+
Map<String, Object> merged = new HashMap<>(this.overlay);
44+
merged.putAll(map);
45+
return new OverlayMcpTransportContext(this.base, merged);
46+
}
47+
48+
}

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

Lines changed: 115 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,12 @@
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
/**
15-
* Tests for {@link McpTransportContext#create(Map)}, which is documented to return an
16-
* unmodifiable context.
16+
* Tests for {@link McpTransportContext}: {@link McpTransportContext#create(Map)}, which
17+
* is documented to return an unmodifiable context, and
18+
* {@link McpTransportContext#putAll(Map)}.
1719
*/
1820
class McpTransportContextTests {
1921

@@ -51,39 +53,130 @@ void createdContextShouldNotBeEmptiedByClearingTheSourceMap() {
5153
}
5254

5355
@Test
54-
void createdContextShouldRemainUsableAsAMapKey() {
55-
Map<String, Object> metadata = new HashMap<>();
56-
metadata.put("tenant", "acme");
57-
McpTransportContext context = McpTransportContext.create(metadata);
58-
59-
Map<McpTransportContext, String> byContext = new HashMap<>();
60-
byContext.put(context, "value");
61-
metadata.put("tenant", "other");
56+
void createdContextFromAnImmutableMapIsAlreadyCorrect() {
57+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
6258

63-
assertThat(byContext.get(context)).isEqualTo("value");
59+
assertThat(context.get("tenant")).isEqualTo("acme");
6460
}
6561

6662
@Test
67-
void twoContextsCreatedFromEqualMapsShouldStayEqual() {
68-
Map<String, Object> first = new HashMap<>();
69-
first.put("tenant", "acme");
70-
Map<String, Object> second = new HashMap<>();
71-
second.put("tenant", "acme");
63+
void putAllShouldKeepTheEntriesOfTheContextAndTheMap() {
64+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
7265

73-
McpTransportContext firstContext = McpTransportContext.create(first);
74-
McpTransportContext secondContext = McpTransportContext.create(second);
75-
assertThat(firstContext).isEqualTo(secondContext);
66+
McpTransportContext merged = context.putAll(Map.of("region", "eu"));
7667

77-
first.put("tenant", "other");
68+
assertThat(merged.get("tenant")).isEqualTo("acme");
69+
assertThat(merged.get("region")).isEqualTo("eu");
70+
}
7871

79-
assertThat(firstContext).isEqualTo(secondContext);
72+
@Test
73+
void putAllShouldLetTheMapWinOnSharedKeys() {
74+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
75+
76+
assertThat(context.putAll(Map.of("tenant", "other")).get("tenant")).isEqualTo("other");
8077
}
8178

8279
@Test
83-
void createdContextFromAnImmutableMapIsAlreadyCorrect() {
80+
void putAllShouldLeaveTheOriginalContextUnchanged() {
8481
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
8582

83+
context.putAll(Map.of("tenant", "other", "region", "eu"));
84+
8685
assertThat(context.get("tenant")).isEqualTo("acme");
86+
assertThat(context.get("region")).isNull();
87+
}
88+
89+
@Test
90+
void putAllShouldNotSeeLaterWritesToTheSourceMap() {
91+
Map<String, Object> entries = new HashMap<>();
92+
entries.put("region", "eu");
93+
94+
McpTransportContext merged = new LookupTransportContext(Map.of()).putAll(entries);
95+
entries.put("region", "us");
96+
97+
assertThat(merged.get("region")).isEqualTo("eu");
98+
}
99+
100+
@Test
101+
void putAllWithAnEmptyMapShouldReturnTheSameContext() {
102+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme"));
103+
McpTransportContext custom = new LookupTransportContext(Map.of("tenant", "acme"));
104+
105+
assertThat(context.putAll(Map.of())).isSameAs(context);
106+
assertThat(custom.putAll(Map.of())).isSameAs(custom);
107+
}
108+
109+
@Test
110+
void putAllOnTheDefaultContextShouldHoldTheMergedEntries() {
111+
McpTransportContext context = McpTransportContext.create(Map.of("tenant", "acme", "region", "us"));
112+
113+
McpTransportContext merged = context.putAll(Map.of("region", "eu"));
114+
115+
assertThat(merged.get("tenant")).isEqualTo("acme");
116+
assertThat(merged.get("region")).isEqualTo("eu");
117+
assertThat(merged.get("missing")).isNull();
118+
}
119+
120+
@Test
121+
void putAllShouldRejectNullValues() {
122+
Map<String, Object> withNullValue = new HashMap<>();
123+
withNullValue.put("region", null);
124+
125+
assertThatThrownBy(() -> McpTransportContext.create(Map.of()).putAll(withNullValue))
126+
.isInstanceOf(NullPointerException.class);
127+
assertThatThrownBy(() -> new LookupTransportContext(Map.of()).putAll(withNullValue))
128+
.isInstanceOf(NullPointerException.class);
129+
}
130+
131+
@Test
132+
void putAllOnACustomContextShouldDelegateLookupsForKeysNotInTheMap() {
133+
McpTransportContext custom = new LookupTransportContext(Map.of("tenant", "acme", "region", "us"));
134+
135+
McpTransportContext merged = custom.putAll(Map.of("region", "eu"));
136+
137+
assertThat(merged.get("tenant")).isEqualTo("acme");
138+
assertThat(merged.get("region")).isEqualTo("eu");
139+
assertThat(merged.get("missing")).isNull();
140+
}
141+
142+
@Test
143+
void putAllOnACustomContextShouldSeeLaterChangesToIt() {
144+
Map<String, Object> source = new HashMap<>();
145+
McpTransportContext custom = new LookupTransportContext(source);
146+
147+
McpTransportContext merged = custom.putAll(Map.of("region", "eu"));
148+
source.put("tenant", "acme");
149+
150+
assertThat(merged.get("tenant")).isEqualTo("acme");
151+
}
152+
153+
@Test
154+
void repeatedPutAllShouldHoldTheCombinedEntries() {
155+
McpTransportContext custom = new LookupTransportContext(Map.of("tenant", "acme"));
156+
157+
McpTransportContext merged = custom.putAll(Map.of("region", "us")).putAll(Map.of("region", "eu", "zone", "a"));
158+
159+
assertThat(merged.get("tenant")).isEqualTo("acme");
160+
assertThat(merged.get("region")).isEqualTo("eu");
161+
assertThat(merged.get("zone")).isEqualTo("a");
162+
}
163+
164+
/**
165+
* A context reading its backing map on each lookup.
166+
*/
167+
static class LookupTransportContext implements McpTransportContext {
168+
169+
private final Map<String, Object> source;
170+
171+
LookupTransportContext(Map<String, Object> source) {
172+
this.source = source;
173+
}
174+
175+
@Override
176+
public Object get(String key) {
177+
return this.source.get(key);
178+
}
179+
87180
}
88181

89182
}

‎mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1416,7 +1416,7 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
14161416
var clientBuilder = clientBuilders.get(clientType);
14171417

14181418
var transportContextIsNull = new AtomicBoolean(false);
1419-
var transportContextIsEmpty = new AtomicBoolean(false);
1419+
var importantValue = new AtomicReference<Object>();
14201420
var responseBodyIsNullOrBlank = new AtomicBoolean(false);
14211421

14221422
var expectedCallResponse = McpSchema.CallToolResult.builder()
@@ -1428,7 +1428,7 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
14281428

14291429
McpTransportContext transportContext = exchange.transportContext();
14301430
transportContextIsNull.set(transportContext == null);
1431-
transportContextIsEmpty.set(transportContext.equals(McpTransportContext.EMPTY));
1431+
importantValue.set(transportContext.get("important"));
14321432
String ctxValue = (String) transportContext.get("important");
14331433

14341434
try {
@@ -1460,7 +1460,7 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
14601460
.callTool(McpSchema.CallToolRequest.builder("tool1").arguments(Map.of()).build());
14611461

14621462
assertThat(transportContextIsNull.get()).isFalse();
1463-
assertThat(transportContextIsEmpty.get()).isFalse();
1463+
assertThat(importantValue.get()).isEqualTo("value");
14641464
assertThat(responseBodyIsNullOrBlank.get()).isFalse();
14651465
assertThat(response).isNotNull().isEqualTo(expectedCallResponse);
14661466
}

0 commit comments

Comments
 (0)