1/**
2 * Defines the MCP protocol implementations that an `McpServer` can support.
3 *
4 * @stability unstable
5 * @since 4.0.0
6 */
7import type * as Effect from "../Effect.ts"
8import type * as Rpc from "../rpc/Rpc.ts"
9import type * as RpcClient from "../rpc/RpcClient.ts"
10import type * as RpcGroup from "../rpc/RpcGroup.ts"
11import type * as Schema from "../Schema.ts"
12import type * as Scope from "../Scope.ts"
13import { protocol as protocol2024_11_05 } from "./internal/mcpProtocol/v2024_11_05.ts"
14import { protocol as protocol2025_03_26 } from "./internal/mcpProtocol/v2025_03_26.ts"
15import { protocol as protocol2025_06_18 } from "./internal/mcpProtocol/v2025_06_18.ts"
16import { protocol as protocol2025_11_25 } from "./internal/mcpProtocol/v2025_11_25.ts"
17import { protocol as protocol2026_07_28 } from "./internal/mcpProtocol/v2026_07_28.ts"
18import type * as McpSchema from "./McpSchema.ts"
19
20/**
21 * The MCP protocol versions implemented by this release.
22 *
23 * @stability unstable
24 * @category models
25 * @since 4.0.0
26 */
27export type ProtocolVersion = "2024-11-05" | "2025-03-26" | "2025-06-18" | "2025-11-25" | "2026-07-28"
28
29/**
30 * MCP protocol versions that use initialization and server-managed sessions.
31 *
32 * @stability unstable
33 * @category models
34 * @since 4.0.0
35 */
36export type StatefulProtocolVersion = Exclude<ProtocolVersion, "2026-07-28">
37
38/**
39 * Payload codecs used by a protocol adapter.
40 *
41 * @stability unstable
42 * @category models
43 * @since 4.0.0
44 */
45export interface PayloadCodecs {
46 readonly decode: (input: unknown) => Effect.Effect<unknown, Schema.SchemaError>
47 readonly encode: (input: unknown) => Effect.Effect<unknown, Schema.SchemaError>
48}
49
50/**
51 * A notification projected into a protocol-specific payload.
52 *
53 * @stability unstable
54 * @category models
55 * @since 4.0.0
56 */
57export interface ProjectedNotification {
58 readonly tag: string
59 readonly payload: unknown
60}
61
62/**
63 * The operations required from an RPC group after its RPC union is erased.
64 *
65 * @stability unstable
66 * @category models
67 * @since 4.0.0
68 */
69export interface ErasedRpcGroup<RpcType extends Rpc.Any = Rpc.Any> {
70 readonly requests: ReadonlyMap<string, RpcType>
71}
72
73/**
74 * The additional operation required from the complete client RPC group.
75 *
76 * @stability unstable
77 * @category models
78 * @since 4.0.0
79 */
80export interface ErasedClientRpcGroup extends ErasedRpcGroup {
81 readonly prefix: (prefix: string) => RpcGroup.RpcGroup<any>
82}
83
84/**
85 * Transport behavior declared by an MCP runtime descriptor.
86 *
87 * @stability unstable
88 * @category models
89 * @since 4.0.0
90 */
91export interface TransportPolicy {
92 readonly jsonRpc: {
93 readonly acceptsBatches: boolean
94 }
95 readonly http: {
96 readonly requiresVersionHeader?: boolean | undefined
97 }
98}
99
100/**
101 * Request information decoded by a stateless MCP runtime.
102 *
103 * @stability unstable
104 * @category models
105 * @since 4.0.0
106 */
107export interface StatelessRuntimeProfile {
108 readonly protocolVersion: string
109 readonly clientCapabilities: Schema.JsonObject
110 readonly clientInfo?: McpSchema.Implementation | undefined
111 readonly requestMetadata: Schema.JsonObject
112}
113
114/**
115 * Stateful lifecycle runtime declaration carried by a protocol adapter.
116 *
117 * @stability unstable
118 * @category models
119 * @since 4.0.0
120 */
121export interface StatefulRuntimeDescriptor {
122 readonly _tag: "Stateful"
123 readonly transport: TransportPolicy
124}
125
126/**
127 * Stateless lifecycle runtime declaration carried by a protocol adapter.
128 *
129 * @stability unstable
130 * @category models
131 * @since 4.0.0
132 */
133export interface StatelessRuntimeDescriptor {
134 readonly _tag: "Stateless"
135 readonly transport: TransportPolicy
136 readonly profileFromRequestMetadata: (
137 metadata: unknown
138 ) => Effect.Effect<StatelessRuntimeProfile, unknown>
139}
140
141/**
142 * Lifecycle runtime declaration carried by a protocol adapter.
143 *
144 * @stability unstable
145 * @category models
146 * @since 4.0.0
147 */
148export type RuntimeDescriptor = StatefulRuntimeDescriptor | StatelessRuntimeDescriptor
149
150/**
151 * The operational shape shared by protocol adapters.
152 *
153 * @stability unstable
154 * @category models
155 * @since 4.0.0
156 */
157export interface AnyProtocolAdapter<
158 out Version extends string = string,
159 HandlerRequirements = unknown,
160 out Runtime extends RuntimeDescriptor = RuntimeDescriptor
161> {
162 readonly protocolVersion: Version
163 readonly runtime: Runtime
164 readonly clientRpcs: ErasedClientRpcGroup
165 readonly clientNotificationRpcs: ErasedRpcGroup
166 readonly serverRequestRpcs: RpcGroup.Any
167 readonly serverNotificationRpcs: ErasedRpcGroup<Rpc.AnyWithProps>
168 readonly payloadCodecs: (rpc: Rpc.AnyWithProps) => PayloadCodecs
169 readonly installHandlers: (
170 core: any,
171 lifecycle: any,
172 target: any
173 ) => Effect.Effect<void, never, HandlerRequirements>
174 readonly makeReverseClient: (
175 profile: any
176 ) => Effect.Effect<McpSchema.McpReverseClient, never, RpcClient.Protocol | Scope.Scope>
177 readonly projectNotification: (
178 notification: any
179 ) => Effect.Effect<ProjectedNotification | undefined, any>
180 readonly normalizeCancellation: (payload: unknown) => Effect.Effect<any, unknown>
181}
182
183/**
184 * An MCP protocol adapter that can be supplied to `McpServer`.
185 *
186 * @stability unstable
187 * @category models
188 * @since 4.0.0
189 */
190export interface ProtocolAdapter<
191 out Version extends ProtocolVersion = ProtocolVersion,
192 out Runtime extends RuntimeDescriptor = RuntimeDescriptor
193> extends AnyProtocolAdapter<Version, unknown, Runtime> {}
194
195/**
196 * The MCP 2026-07-28 protocol implementation.
197 *
198 * **Details**
199 *
200 * This revision uses request-scoped metadata instead of initialization and
201 * protocol-level sessions.
202 *
203 * When the selected transport supports server notifications, discovery
204 * advertises change-notification capabilities and `subscriptions/listen`
205 * delivers the requested notifications over the long-lived response.
206 *
207 * @stability unstable
208 * @category protocols
209 * @since 4.0.0
210 */
211export const v2026_07_28: ProtocolAdapter<"2026-07-28", StatelessRuntimeDescriptor> = protocol2026_07_28
212
213/**
214 * The MCP 2025-11-25 protocol implementation.
215 *
216 * @stability unstable
217 * @category protocols
218 * @since 4.0.0
219 */
220export const v2025_11_25: ProtocolAdapter<"2025-11-25", StatefulRuntimeDescriptor> = protocol2025_11_25
221
222/**
223 * The MCP 2025-06-18 protocol implementation.
224 *
225 * @stability unstable
226 * @category protocols
227 * @since 4.0.0
228 */
229export const v2025_06_18: ProtocolAdapter<"2025-06-18", StatefulRuntimeDescriptor> = protocol2025_06_18
230
231/**
232 * The MCP 2025-03-26 protocol implementation.
233 *
234 * @stability unstable
235 * @category protocols
236 * @since 4.0.0
237 */
238export const v2025_03_26: ProtocolAdapter<"2025-03-26", StatefulRuntimeDescriptor> = protocol2025_03_26
239
240/**
241 * The MCP 2024-11-05 protocol implementation.
242 *
243 * **Details**
244 *
245 * It provides the dated schema and stdio behavior. When supplied to
246 * `McpServer.layerHttp`, the server uses its single-endpoint Streamable HTTP
247 * compatibility transport; it does not implement the historical two-endpoint
248 * HTTP+SSE transport.
249 *
250 * @stability unstable
251 * @category protocols
252 * @since 4.0.0
253 */
254export const v2024_11_05: ProtocolAdapter<"2024-11-05", StatefulRuntimeDescriptor> = protocol2024_11_05