[chemicL]

Transports need to add their own keys to the context a user-provided extractor built, for instance the decoded Mcp-Param-* headers:

• the provided keys take precedence over the user-extracted ones
• neither the user's context nor the map is modified
• custom McpTransportContext implementations keep working unchanged

Contexts created via McpTransportContext.create are merged into a single map. Other implementations are wrapped once, and further merges combine into a single wrapper rather than adding layers.

This is an alternative implementation to #1285

[Kehrlann]

I like the simpler shape of this. However, this raises the question of context equality.

If the keys and values are the same, the contexts should probably be the same, shouldn't they?

The DefaultMcpTransportContext equality we have is dubious too, but it was the only implementation we provided, and now we're compounding problems.

[Kehrlann]

we should not create an overlay when the context is empty

Suggested change

	if (map.isEmpty()) {
	return this;
	}
	return new OverlayMcpTransportContext(this, map);
	if (map.isEmpty()) {
	return this;
	}
	if (this == McpTransportContext.EMPTY) {
	return McpTransportContext.create(map);
	}
	return new OverlayMcpTransportContext(this, map);

[chemicL]

Actually, this wouldn't have any effect. McpTransportContext.EMPTY is a DefaultMcpTransportContext so it means that the overridden method would be called. I'll add a check there for this.metadata.isEmpty().

[Kehrlann]

This is probably incorrect.

With this:

var one = McpTransportContext.EMPTY.putAll(Map.of("foo", "one", "bar", "two"));
var two = McpTransportContext.create(Map.of("foo", "one")).putAll(Map.of("bar", "two"));

one.equals(two); // -> false

but both context have the same values.

[chemicL]

We never claimed anything about context equality. As discussed, the equality implementations are now gone. The McpTransportContext contract is to extract values for known keys and that is how users can interact with the context. So the tests are also modified now.