|
| 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 | +} |
0 commit comments