Skip to content

Commit 2c9f71e

Browse files
committed
Rework McpParamHeaders into McpHeaders
- This will open the possibility to store Mcp-Name headers in this class. Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>
1 parent ebd13cf commit 2c9f71e

16 files changed

Lines changed: 425 additions & 345 deletions

File tree

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
/*
2+
* Copyright 2026-2026 the original author or authors.
3+
*/
4+
5+
package io.modelcontextprotocol.modern.server;
6+
7+
import java.util.Objects;
8+
9+
import io.modelcontextprotocol.util.Assert;
10+
import org.jspecify.annotations.Nullable;
11+
12+
/**
13+
* A request header that a client mirrors from the JSON-RPC body, as decoded by the
14+
* transport. A header that was sent but couldn't be decoded, or was sent more than once,
15+
* is malformed and has no value.
16+
*
17+
* @author Daniel Garnier-Moiroux
18+
* @see McpHeaders
19+
*/
20+
public final class McpHeader {
21+
22+
private final String name;
23+
24+
private final @Nullable String value;
25+
26+
private McpHeader(String name, @Nullable String value) {
27+
Assert.notNull(name, "name must not be null");
28+
this.name = name;
29+
this.value = value;
30+
}
31+
32+
/**
33+
* Creates a header with a decoded value.
34+
* @param name the header name, for instance {@code Mcp-Param-Region}
35+
* @param value the decoded value
36+
* @return the header
37+
*/
38+
public static McpHeader of(String name, String value) {
39+
Assert.notNull(value, "value must not be null");
40+
return new McpHeader(name, value);
41+
}
42+
43+
/**
44+
* Creates a header that was sent but couldn't be decoded, or was sent more than once.
45+
* @param name the header name, for instance {@code Mcp-Param-Region}
46+
* @return the malformed header
47+
*/
48+
public static McpHeader malformed(String name) {
49+
return new McpHeader(name, null);
50+
}
51+
52+
/**
53+
* The header name, in the case it was received.
54+
* @return the header name
55+
*/
56+
public String name() {
57+
return this.name;
58+
}
59+
60+
/**
61+
* The decoded value.
62+
* @return the decoded value, or {@code null} if the header is malformed
63+
*/
64+
public @Nullable String value() {
65+
return this.value;
66+
}
67+
68+
/**
69+
* Whether the header was sent but has no usable value, because it couldn't be decoded
70+
* or was sent more than once.
71+
* @return {@code true} if the header is malformed
72+
*/
73+
public boolean isMalformed() {
74+
return this.value == null;
75+
}
76+
77+
@Override
78+
public boolean equals(Object other) {
79+
return (this == other) || (other instanceof McpHeader that && this.name.equals(that.name)
80+
&& Objects.equals(this.value, that.value));
81+
}
82+
83+
@Override
84+
public int hashCode() {
85+
return Objects.hash(this.name, this.value);
86+
}
87+
88+
@Override
89+
public String toString() {
90+
// The value stays out: it may end up in logs.
91+
return "McpHeader[name=" + this.name + (isMalformed() ? ", malformed" : "") + "]";
92+
}
93+
94+
}
Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
/*
2+
* Copyright 2026-2026 the original author or authors.
3+
*/
4+
5+
package io.modelcontextprotocol.modern.server;
6+
7+
import java.util.Collections;
8+
import java.util.LinkedHashMap;
9+
import java.util.Locale;
10+
import java.util.Map;
11+
12+
import io.modelcontextprotocol.util.Assert;
13+
import org.jspecify.annotations.Nullable;
14+
15+
/**
16+
* The request headers a client mirrors from the JSON-RPC body: the
17+
* {@code Mcp-Param-{Name}} headers of a {@code tools/call} request, which mirror the
18+
* arguments a tool annotates with {@code x-mcp-header}.
19+
* <p>
20+
* An HTTP transport decodes the headers, for instance with
21+
* {@code McpHeaderDecoder.paramHeaders}, and adds them to the transport context under
22+
* {@link #TRANSPORT_CONTEXT_KEY}. A transport that has no headers, such as stdio, maps
23+
* the key to {@link #NOT_MIRRORED} instead. The tools feature validates the headers
24+
* against the arguments, and fails the call as an internal error when the key is missing.
25+
* <p>
26+
* Headers are looked up ignoring case.
27+
*
28+
* @author Daniel Garnier-Moiroux
29+
* @see <a href="https://modelcontextprotocol.io/seps/2243-http-standardization">SEP-2243:
30+
* HTTP Standardization</a>
31+
*/
32+
public final class McpHeaders {
33+
34+
/**
35+
* The transport context key under which a transport provides the {@code McpHeaders}
36+
* of a request.
37+
*/
38+
public static final String TRANSPORT_CONTEXT_KEY = McpHeaders.class.getName();
39+
40+
/**
41+
* The prefix of every {@code Mcp-Param-{Name}} header name.
42+
*/
43+
public static final String PARAM_PREFIX = "Mcp-Param-";
44+
45+
/**
46+
* Marks a transport that never mirrors the body into headers, such as stdio, so
47+
* header validation is skipped. Compared by identity: headers built with
48+
* {@link #builder()} are never {@code NOT_MIRRORED}, even when empty.
49+
*/
50+
public static final McpHeaders NOT_MIRRORED = new McpHeaders(Map.of());
51+
52+
// Keyed by the lower-cased full header name, such as mcp-param-region, so headers
53+
// other than Mcp-Param-{Name} can share the map.
54+
private final Map<String, McpHeader> headers;
55+
56+
private McpHeaders(Map<String, McpHeader> headers) {
57+
this.headers = headers;
58+
}
59+
60+
public static Builder builder() {
61+
return new Builder();
62+
}
63+
64+
/**
65+
* The header with the given full name, for instance {@code Mcp-Param-Region}.
66+
* @param headerName the header name, in any case
67+
* @return the header, possibly malformed, or {@code null} if it was not sent
68+
*/
69+
public @Nullable McpHeader get(String headerName) {
70+
Assert.notNull(headerName, "headerName must not be null");
71+
return this.headers.get(normalize(headerName));
72+
}
73+
74+
/**
75+
* The {@code Mcp-Param-{Name}} header with the given {@code {Name}}.
76+
* @param name the {@code {Name}} part of {@code Mcp-Param-{Name}}, in any case
77+
* @return the header, possibly malformed, or {@code null} if it was not sent
78+
*/
79+
public @Nullable McpHeader param(String name) {
80+
return get(paramHeaderName(name));
81+
}
82+
83+
private static String paramHeaderName(String name) {
84+
Assert.notNull(name, "name must not be null");
85+
return PARAM_PREFIX + name;
86+
}
87+
88+
private static String normalize(String headerName) {
89+
return headerName.toLowerCase(Locale.ROOT);
90+
}
91+
92+
@Override
93+
public String toString() {
94+
return (this == NOT_MIRRORED) ? "McpHeaders[NOT_MIRRORED]" : "McpHeaders" + this.headers.values();
95+
}
96+
97+
public static final class Builder {
98+
99+
private final Map<String, McpHeader> headers = new LinkedHashMap<>();
100+
101+
private Builder() {
102+
}
103+
104+
/**
105+
* Adds an {@code Mcp-Param-{Name}} header. A name added more than once, ignoring
106+
* case, is malformed, because a header sent more than once has no single value to
107+
* compare.
108+
* @param name the {@code {Name}} part of {@code Mcp-Param-{Name}}, in any case
109+
* @param value the decoded value, or {@code null} if the header was sent but
110+
* couldn't be decoded
111+
* @return this builder
112+
*/
113+
public Builder param(String name, @Nullable String value) {
114+
String headerName = paramHeaderName(name);
115+
return add((value != null) ? McpHeader.of(headerName, value) : McpHeader.malformed(headerName));
116+
}
117+
118+
// A header added again, ignoring case, becomes malformed and keeps the name it
119+
// was first added with.
120+
private Builder add(McpHeader header) {
121+
this.headers.merge(normalize(header.name()), header,
122+
(previous, added) -> McpHeader.malformed(previous.name()));
123+
return this;
124+
}
125+
126+
public McpHeaders build() {
127+
return new McpHeaders(Collections.unmodifiableMap(new LinkedHashMap<>(this.headers)));
128+
}
129+
130+
}
131+
132+
}

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/server/McpParamHeaders.java‎

Lines changed: 0 additions & 154 deletions
This file was deleted.

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/server/McpRequestManager.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@
1515
* block, {@link #handle} when it must not. Neither completes with an error.
1616
* <p>
1717
* For {@code tools/call}, the transport context must map
18-
* {@link McpParamHeaders#TRANSPORT_CONTEXT_KEY} to the request's {@code Mcp-Param-{Name}}
19-
* headers, or to {@link McpParamHeaders#NOT_MIRRORED} for a transport without headers.
18+
* {@link McpHeaders#TRANSPORT_CONTEXT_KEY} to the request's {@code Mcp-Param-{Name}}
19+
* headers, or to {@link McpHeaders#NOT_MIRRORED} for a transport without headers.
2020
*
2121
* @author Dariusz Jędrzejczyk
2222
*/

0 commit comments

Comments
 (0)