1/**
2 * Defines schemas for Model Context Protocol messages.
3 *
4 * MCP clients and servers use these schemas to describe the JSON-RPC requests,
5 * notifications, results, and errors that can cross the protocol boundary.
6 * This is the stable public compatibility and authoring surface. It is not an
7 * exact dated wire contract: MCP protocol adapters use frozen schemas under
8 * `internal/mcpSchema` for decoding and encoding. This module groups the
9 * current public message model for application authors and provides helpers
10 * for optional fields and parameter metadata. Transport and server behavior
11 * live in other modules.
12 *
13 * @stability unstable
14 * @since 4.0.0
15 */
16import * as Context from "../Context.ts"
17import * as Data from "../Data.ts"
18import * as Effect from "../Effect.ts"
19import { constFalse, constTrue } from "../Function.ts"
20import * as Option from "../Option.ts"
21import * as Predicate from "../Predicate.ts"
22import * as Rpc from "../rpc/Rpc.ts"
23import * as RpcGroup from "../rpc/RpcGroup.ts"
24import * as RpcMiddleware from "../rpc/RpcMiddleware.ts"
25import * as Schema from "../Schema.ts"
26import * as SchemaGetter from "../SchemaGetter.ts"
27import type * as Scope from "../Scope.ts"
28import type { ProtocolVersion, StatefulProtocolVersion } from "./McpProtocol.ts"
29
30/**
31 * Schema type returned by `optionalWithDefault`.
32 *
33 * **Details**
34 *
35 * It represents an optional struct field that supplies a default value when the
36 * field is absent during decoding or construction.
37 *
38 * @stability unstable
39 * @category models
40 * @since 4.0.0
41 */
42export interface optionalWithDefault<S extends Schema.Constraint & Schema.WithoutConstructorDefault>
43 extends Schema.withConstructorDefault<Schema.decodeTo<Schema.toType<Schema.optionalKey<S>>, Schema.optionalKey<S>>>
44{}
45
46/**
47 * Marks a struct field as optional and supplies `defaultValue` when the field
48 * is absent.
49 *
50 * **Details**
51 *
52 * The default is used during decoding and as the constructor default for the
53 * schema field.
54 *
55 * @stability unstable
56 * @category schemas
57 * @since 4.0.0
58 */
59export const optionalWithDefault = <S extends Schema.Constraint & Schema.WithoutConstructorDefault>(
60 schema: S,
61 defaultValue: () => Schema.optionalKey<S>["Type"]
62): optionalWithDefault<S> => {
63 const effect = Effect.sync(defaultValue)
64 return Schema.optionalKey(schema).pipe(
65 Schema.decode<Schema.optionalKey<S>>({
66 decode: SchemaGetter.withDefault(effect),
67 encode: SchemaGetter.passthrough()
68 }),
69 Schema.withConstructorDefault<
70 Schema.decodeTo<Schema.toType<Schema.optionalKey<S>>, Schema.optionalKey<S>>
71 >(effect)
72 )
73}
74
75/**
76 * Creates an optional MCP struct-field schema from a required schema.
77 *
78 * **Details**
79 *
80 * The field may be absent, and explicit `undefined` values are omitted when
81 * encoding.
82 *
83 * @stability unstable
84 * @category schemas
85 * @since 4.0.0
86 */
87export const optional = <S extends Schema.Constraint>(
88 schema: S
89): Schema.decodeTo<Schema.toType<Schema.optional<S>>, Schema.optionalKey<S>> =>
90 Schema.optionalKey(schema).pipe(
91 Schema.decodeTo(Schema.toType(Schema.optional(schema)), {
92 decode: SchemaGetter.passthrough(),
93 encode: SchemaGetter.transformOptional(Option.flatMap(Option.fromUndefinedOr))
94 })
95 )
96
97// =============================================================================
98// Common
99// =============================================================================
100
101/**
102 * Schema for JSON-RPC request identifiers, allowing string or number ids.
103 *
104 * @stability unstable
105 * @category schemas
106 * @since 4.0.0
107 */
108export const RequestId: Schema.Union<[
109 typeof Schema.String,
110 typeof Schema.Finite
111]> = Schema.Union([Schema.String, Schema.Finite])
112
113/**
114 * Type represented by the JSON-RPC request identifier schema.
115 *
116 * @stability unstable
117 * @category models
118 * @since 4.0.0
119 */
120export type RequestId = typeof RequestId.Type
121
122/**
123 * Schema for MCP progress tokens that associate progress notifications with the
124 * original request.
125 *
126 * @stability unstable
127 * @category schemas
128 * @since 4.0.0
129 */
130export const ProgressToken: Schema.Union<[
131 typeof Schema.String,
132 typeof Schema.Finite
133]> = Schema.Union([Schema.String, Schema.Finite])
134
135/**
136 * Type represented by the MCP progress token schema.
137 *
138 * @stability unstable
139 * @category models
140 * @since 4.0.0
141 */
142export type ProgressToken = typeof ProgressToken.Type
143
144/**
145 * Schema for optional MCP request metadata.
146 *
147 * **Details**
148 *
149 * Request metadata may include a progress token that asks the receiver to send
150 * out-of-band progress notifications for the request.
151 *
152 * @stability unstable
153 * @category schemas
154 * @since 4.0.0
155 */
156export class RequestMeta extends Schema.Opaque<RequestMeta>()(Schema.Struct({
157 _meta: optional(Schema.StructWithRest(
158 Schema.Struct({
159 /**
160 * If specified, the caller is requesting out-of-band progress notifications
161 * for this request (as represented by notifications/progress). The value of
162 * this parameter is an opaque token that will be attached to any subsequent
163 * notifications. The receiver is not obligated to provide these
164 * notifications.
165 */
166 progressToken: optional(ProgressToken)
167 }),
168 [Schema.JsonObject]
169 ))
170})) {}
171
172/**
173 * Schema for optional MCP result metadata.
174 *
175 * **Details**
176 *
177 * The `_meta` field is reserved for protocol, extension, or implementation
178 * metadata attached to a result.
179 *
180 * @stability unstable
181 * @category schemas
182 * @since 4.0.0
183 */
184export class ResultMeta extends Schema.Opaque<ResultMeta>()(Schema.Struct({
185 /**
186 * This result property is reserved by the protocol to allow clients and
187 * servers to attach additional metadata to their responses.
188 */
189 _meta: optional(Schema.JsonObject)
190})) {}
191
192/**
193 * Schema for optional MCP notification metadata.
194 *
195 * **Details**
196 *
197 * The `_meta` field is reserved for protocol, extension, or implementation
198 * metadata attached to a notification.
199 *
200 * @stability unstable
201 * @category schemas
202 * @since 4.0.0
203 */
204export class NotificationMeta extends Schema.Opaque<NotificationMeta>()(Schema.Struct({
205 /**
206 * This parameter name is reserved by MCP to allow clients and servers to
207 * attach additional metadata to their notifications.
208 */
209 _meta: optional(Schema.JsonObject)
210})) {}
211
212/**
213 * Schema for opaque cursor tokens used in pagination.
214 *
215 * @stability unstable
216 * @category schemas
217 * @since 4.0.0
218 */
219export const Cursor: typeof Schema.String = Schema.String
220
221/**
222 * Type represented by the MCP cursor schema.
223 *
224 * **Details**
225 *
226 * A cursor is an opaque string token used to continue paginated requests.
227 *
228 * @stability unstable
229 * @category models
230 * @since 4.0.0
231 */
232export type Cursor = typeof Cursor.Type
233
234/**
235 * Schema for MCP request metadata used by paginated requests.
236 *
237 * **Details**
238 *
239 * It includes the base request metadata fields plus an optional cursor
240 * indicating where the server should continue listing results.
241 *
242 * @stability unstable
243 * @category schemas
244 * @since 4.0.0
245 */
246export class PaginatedRequestMeta extends Schema.Opaque<PaginatedRequestMeta>()(Schema.Struct({
247 ...RequestMeta.fields,
248 /**
249 * An opaque token representing the current pagination position.
250 * If provided, the server should return results starting after this cursor.
251 */
252 cursor: optional(Cursor)
253})) {}
254
255/**
256 * Schema for MCP result metadata returned by paginated operations.
257 *
258 * **Details**
259 *
260 * It includes the base result metadata fields plus an optional `nextCursor`,
261 * which indicates that more results may be available.
262 *
263 * @stability unstable
264 * @category schemas
265 * @since 4.0.0
266 */
267export class PaginatedResultMeta extends Schema.Opaque<PaginatedResultMeta>()(Schema.Struct({
268 ...ResultMeta.fields,
269 /**
270 * An opaque token representing the pagination position after the last returned result.
271 * If present, there may be more results available.
272 */
273 nextCursor: optional(Cursor)
274})) {}
275
276/**
277 * Schema for MCP conversation roles, allowing user and assistant.
278 *
279 * @stability unstable
280 * @category schemas
281 * @since 4.0.0
282 */
283export const Role: Schema.Literals<["user", "assistant"]> = Schema.Literals(["user", "assistant"])
284
285/**
286 * Type represented by the MCP role schema.
287 *
288 * **Details**
289 *
290 * Valid roles are `"user"` and `"assistant"`.
291 *
292 * @stability unstable
293 * @category models
294 * @since 4.0.0
295 */
296export type Role = typeof Role.Type
297
298/**
299 * Schema for optional client-facing annotations on MCP objects.
300 *
301 * **When to use**
302 *
303 * Use to describe intended audience and priority metadata for objects shown or
304 * processed by a client.
305 *
306 * @stability unstable
307 * @category schemas
308 * @since 4.0.0
309 */
310export class Annotations extends Schema.Opaque<Annotations>()(Schema.Struct({
311 /**
312 * Describes who the intended customer of this object or data is.
313 *
314 * It can include multiple entries to indicate content useful for multiple
315 * audiences (e.g., `["user", "assistant"]`).
316 */
317 audience: optional(Schema.Array(Role)),
318 /**
319 * Describes how important this data is for operating the server.
320 *
321 * A value of 1 means "most important," and indicates that the data is
322 * effectively required, while 0 means "least important," and indicates that
323 * the data is entirely optional.
324 */
325 priority: optional(Schema.Finite.check(Schema.isBetween({ minimum: 0, maximum: 1 }))),
326 /**
327 * The last time the annotated object was modified, formatted as an ISO 8601
328 * timestamp.
329 */
330 lastModified: optional(Schema.String)
331})) {}
332
333/**
334 * Schema for an icon that an MCP client can display.
335 *
336 * @stability unstable
337 * @category schemas
338 * @since 4.0.0
339 */
340export class Icon extends Schema.Class<Icon>("@effect/ai/McpSchema/Icon")({
341 /**
342 * URI containing the icon image.
343 */
344 src: Schema.String,
345 /**
346 * MIME type of the icon, when known.
347 */
348 mimeType: optional(Schema.String),
349 /**
350 * Sizes supported by the icon, such as `"48x48"` or `"any"`.
351 */
352 sizes: optional(Schema.Array(Schema.String)),
353 /**
354 * Color theme for which the icon was designed.
355 */
356 theme: optional(Schema.Literals(["light", "dark"]))
357}) {}
358
359/**
360 * Describes the name and version of an MCP implementation.
361 *
362 * @stability unstable
363 * @category schemas
364 * @since 4.0.0
365 */
366export class Implementation extends Schema.Opaque<Implementation>()(Schema.Struct({
367 name: Schema.String,
368 title: optional(Schema.String),
369 version: Schema.String,
370 icons: optional(Schema.Array(Icon)),
371 description: optional(Schema.String),
372 websiteUrl: optional(Schema.String)
373})) {}
374
375/**
376 * Describes capabilities advertised by an MCP client.
377 *
378 * **When to use**
379 *
380 * Use to describe which optional MCP features a client supports during
381 * initialization.
382 *
383 * **Details**
384 *
385 * Known capabilities are represented by this schema, but the capability set is
386 * open and clients may define additional capabilities.
387 *
388 * @stability unstable
389 * @category schemas
390 * @since 4.0.0
391 */
392export class ClientCapabilities extends Schema.Class<ClientCapabilities>(
393 "@effect/ai/McpSchema/ClientCapabilities"
394)({
395 /**
396 * Experimental, non-standard capabilities that the client supports.
397 */
398 experimental: optional(Schema.Record(Schema.String, Schema.Struct({}))),
399 /**
400 * Optional extensions capabilities advertised by the client.
401 * Keys are extension identifiers following <vendor-prefix>/<extension-name> (e.g. "io.modelcontextprotocol/ui").
402 */
403 extensions: optional(Schema.Record(Schema.TemplateLiteral([Schema.String, "/", Schema.String]), Schema.Json)),
404 /**
405 * Present if the client supports listing roots.
406 */
407 roots: optional(Schema.Struct({
408 /**
409 * Whether the client supports notifications for changes to the roots list.
410 */
411 listChanged: optional(Schema.Boolean)
412 })),
413 /**
414 * Present if the client supports sampling from an LLM.
415 */
416 sampling: optional(Schema.Struct({
417 /**
418 * Present if the client supports context inclusion during sampling.
419 */
420 context: optional(Schema.Struct({})),
421 /**
422 * Present if the client supports tool use during sampling.
423 */
424 tools: optional(Schema.Struct({}))
425 })),
426 /**
427 * Present if the client supports elicitation from the server.
428 */
429 elicitation: optional(Schema.Struct({
430 /**
431 * Present if the client supports form-mode elicitation.
432 */
433 form: optional(Schema.Struct({})),
434 /**
435 * Present if the client supports URL-mode elicitation.
436 */
437 url: optional(Schema.Struct({}))
438 }))
439}) {}
440
441/**
442 * Describes capabilities advertised by an MCP server.
443 *
444 * **When to use**
445 *
446 * Use to describe which optional MCP features a server supports during
447 * initialization.
448 *
449 * **Details**
450 *
451 * Known capabilities are represented by this schema, but the capability set is
452 * open and servers may define additional capabilities.
453 *
454 * @stability unstable
455 * @category schemas
456 * @since 4.0.0
457 */
458export class ServerCapabilities extends Schema.Opaque<ServerCapabilities>()(Schema.Struct({
459 /**
460 * Experimental, non-standard capabilities that the server supports.
461 */
462 experimental: optional(Schema.Record(Schema.String, Schema.Struct({}))),
463 /**
464 * Optional extensions capabilities advertised by the server.
465 * Keys are extension identifiers following <vendor-prefix>/<extension-name> (e.g. "io.modelcontextprotocol/ui").
466 */
467 extensions: optional(Schema.Record(Schema.TemplateLiteral([Schema.String, "/", Schema.String]), Schema.Json)),
468 /**
469 * Present if the server supports sending log messages to the client.
470 */
471 logging: optional(Schema.Struct({})),
472 /**
473 * Present if the server supports argument autocompletion suggestions.
474 */
475 completions: optional(Schema.Struct({})),
476 /**
477 * Present if the server offers any prompt templates.
478 */
479 prompts: optional(Schema.Struct({
480 /**
481 * Whether this server supports notifications for changes to the prompt list.
482 */
483 listChanged: optional(Schema.Boolean)
484 })),
485 /**
486 * Present if the server offers any resources to read.
487 */
488 resources: optional(Schema.Struct({
489 /**
490 * Whether this server supports subscribing to resource updates.
491 */
492 subscribe: optional(Schema.Boolean),
493 /**
494 * Whether this server supports notifications for changes to the resource list.
495 */
496 listChanged: optional(Schema.Boolean)
497 })),
498 /**
499 * Present if the server offers any tools to call.
500 */
501 tools: optional(Schema.Struct({
502 /**
503 * Whether this server supports notifications for changes to the tool list.
504 */
505 listChanged: optional(Schema.Boolean)
506 }))
507})) {}
508
509// =============================================================================
510// Errors
511// =============================================================================
512
513/**
514 * Schema for MCP and JSON-RPC error objects.
515 *
516 * **Details**
517 *
518 * It contains the numeric error `code`, a concise `message`, and optional
519 * sender-defined `data`.
520 *
521 * @stability unstable
522 * @category schemas
523 * @since 4.0.0
524 */
525export class McpErrorBase extends Schema.Class<McpErrorBase>(
526 "@effect/ai/McpSchema/McpErrorBase"
527)({
528 /**
529 * The error type that occurred.
530 */
531 code: Schema.Int,
532 /**
533 * A short description of the error. The message SHOULD be limited to a
534 * concise single sentence.
535 */
536 message: Schema.String,
537 /**
538 * Additional information about the error. The value of this member is
539 * defined by the sender (e.g. detailed error information, nested errors etc.).
540 */
541 data: optional(Schema.Any)
542}) {}
543
544/**
545 * Represents the JSON-RPC error code for requests that are not valid request objects.
546 *
547 * **When to use**
548 *
549 * Use when building an MCP/JSON-RPC error response for a syntactically parsed
550 * request object that fails request-shape validation.
551 *
552 * @stability unstable
553 * @category constants
554 * @since 4.0.0
555 */
556export const INVALID_REQUEST_ERROR_CODE = -32600 as const
557/**
558 * Represents the JSON-RPC error code for requests whose method does not exist or is not
559 * available.
560 *
561 * **When to use**
562 *
563 * Use when building an MCP/JSON-RPC error response for a request whose
564 * `method` is unknown or unavailable.
565 *
566 * @stability unstable
567 * @category constants
568 * @since 4.0.0
569 */
570export const METHOD_NOT_FOUND_ERROR_CODE = -32601 as const
571/**
572 * Represents the JSON-RPC error code for invalid method parameters.
573 *
574 * **When to use**
575 *
576 * Use when building an MCP/JSON-RPC error response for decoded request
577 * parameters that fail method-specific validation.
578 *
579 * @stability unstable
580 * @category constants
581 * @since 4.0.0
582 */
583export const INVALID_PARAMS_ERROR_CODE = -32602 as const
584/**
585 * Represents the JSON-RPC error code for internal server errors.
586 *
587 * **When to use**
588 *
589 * Use when building an MCP/JSON-RPC error response for an unexpected
590 * server-side failure.
591 *
592 * @stability unstable
593 * @category constants
594 * @since 4.0.0
595 */
596export const INTERNAL_ERROR_CODE = -32603 as const
597/**
598 * Represents the JSON-RPC error code for invalid JSON that could not be parsed.
599 *
600 * **When to use**
601 *
602 * Use when building an MCP/JSON-RPC error response before a request object is
603 * available because the JSON payload could not be parsed.
604 *
605 * @stability unstable
606 * @category constants
607 * @since 4.0.0
608 */
609export const PARSE_ERROR_CODE = -32700 as const
610
611/**
612 * Represents the MCP error code for HTTP headers that do not match the
613 * corresponding request values.
614 *
615 * **When to use**
616 *
617 * Use when building an MCP error response for missing, malformed, or
618 * mismatched request-routing headers.
619 *
620 * @stability unstable
621 * @category constants
622 * @since 4.0.0
623 */
624export const HEADER_MISMATCH_ERROR_CODE = -32020 as const
625
626/**
627 * Represents an MCP/JSON-RPC error for invalid JSON that could not be parsed.
628 *
629 * **When to use**
630 *
631 * Use to report a JSON parse failure before a valid JSON-RPC request object is
632 * available.
633 *
634 * **Details**
635 *
636 * Uses the standard JSON-RPC parse error code `-32700`.
637 *
638 * @stability unstable
639 * @category errors
640 * @since 4.0.0
641 */
642export class ParseError extends Schema.Error<ParseError>("effect/ai/McpSchema/ParseError")({
643 ...McpErrorBase.fields,
644 _tag: Schema.tag("ParseError"),
645 code: Schema.tag(PARSE_ERROR_CODE)
646}) {}
647
648/**
649 * Represents an MCP/JSON-RPC error for a request object that is not valid.
650 *
651 * **When to use**
652 *
653 * Use to report a syntactically parsed JSON-RPC request that is not a valid
654 * request object.
655 *
656 * **Details**
657 *
658 * Uses the standard JSON-RPC invalid request code `-32600`.
659 *
660 * @stability unstable
661 * @category errors
662 * @since 4.0.0
663 */
664export class InvalidRequest extends Schema.Error<InvalidRequest>("effect/ai/McpSchema/InvalidRequest")({
665 ...McpErrorBase.fields,
666 _tag: Schema.tag("InvalidRequest"),
667 code: Schema.tag(INVALID_REQUEST_ERROR_CODE)
668}) {}
669
670/**
671 * Represents an MCP/JSON-RPC error for an unavailable method.
672 *
673 * **When to use**
674 *
675 * Use to report a JSON-RPC method that does not exist or is not available.
676 *
677 * **Details**
678 *
679 * Uses the standard JSON-RPC method-not-found code `-32601`.
680 *
681 * @stability unstable
682 * @category errors
683 * @since 4.0.0
684 */
685export class MethodNotFound extends Schema.Error<MethodNotFound>("effect/ai/McpSchema/MethodNotFound")({
686 ...McpErrorBase.fields,
687 _tag: Schema.tag("MethodNotFound"),
688 code: Schema.tag(METHOD_NOT_FOUND_ERROR_CODE)
689}) {}
690
691/**
692 * Represents an MCP/JSON-RPC error for invalid method parameters.
693 *
694 * **When to use**
695 *
696 * Use to report a request whose method parameters do not match the method
697 * schema.
698 *
699 * **Details**
700 *
701 * Uses the standard JSON-RPC invalid params code `-32602`.
702 *
703 * @stability unstable
704 * @category errors
705 * @since 4.0.0
706 */
707export class InvalidParams extends Schema.Error<InvalidParams>("effect/ai/McpSchema/InvalidParams")({
708 ...McpErrorBase.fields,
709 _tag: Schema.tag("InvalidParams"),
710 code: Schema.tag(INVALID_PARAMS_ERROR_CODE)
711}) {}
712
713/**
714 * Represents an MCP/JSON-RPC error for unexpected internal server failures.
715 *
716 * **When to use**
717 *
718 * Use to report an unexpected server-side failure while handling a valid
719 * request.
720 *
721 * **Details**
722 *
723 * Uses the standard JSON-RPC internal error code `-32603` and includes
724 * `InternalError.notImplemented` for unimplemented handlers.
725 *
726 * @stability unstable
727 * @category errors
728 * @since 4.0.0
729 */
730export class InternalError extends Schema.Error<InternalError>("effect/ai/McpSchema/InternalError")({
731 ...McpErrorBase.fields,
732 _tag: Schema.tag("InternalError"),
733 code: Schema.tag(INTERNAL_ERROR_CODE)
734}) {
735 static readonly notImplemented = new InternalError({ message: "Not implemented" })
736}
737
738/**
739 * Schema for MCP protocol errors returned in JSON-RPC failure responses,
740 * including standard protocol errors and custom `McpErrorBase` values.
741 *
742 * @stability unstable
743 * @category errors
744 * @since 4.0.0
745 */
746export const McpError = Schema.Union([
747 ParseError,
748 InvalidRequest,
749 MethodNotFound,
750 InvalidParams,
751 InternalError,
752 McpErrorBase
753])
754
755/**
756 * Type represented by the MCP protocol error schema.
757 *
758 * @stability unstable
759 * @category models
760 * @since 4.0.0
761 */
762export type McpError = typeof McpError.Type
763
764// =============================================================================
765// Ping
766// =============================================================================
767
768/**
769 * Represents an MCP ping request used to check whether the peer is still alive.
770 *
771 * **When to use**
772 *
773 * Use to implement client or server liveness checks.
774 *
775 * **Details**
776 *
777 * The receiver should respond promptly; otherwise the sender may disconnect.
778 *
779 * @stability unstable
780 * @category protocols
781 * @since 4.0.0
782 */
783export class Ping extends Rpc.make("ping", {
784 success: Schema.Struct({}),
785 error: McpError,
786 payload: Schema.UndefinedOr(RequestMeta)
787}) {}
788
789// =============================================================================
790// Initialization
791// =============================================================================
792
793/**
794 * Schema for the server's response to an initialize request from the client.
795 *
796 * @stability unstable
797 * @category schemas
798 * @since 4.0.0
799 */
800export class InitializeResult extends Schema.Opaque<InitializeResult>()(Schema.Struct({
801 ...ResultMeta.fields,
802 /**
803 * The version of the Model Context Protocol that the server wants to use.
804 * This may not match the version that the client requested. If the client
805 * cannot support this version, it MUST disconnect.
806 */
807 protocolVersion: Schema.String,
808 capabilities: ServerCapabilities,
809 serverInfo: Implementation,
810 /**
811 * Instructions describing how to use the server and its features.
812 *
813 * This can be used by clients to improve the LLM's understanding of available
814 * tools, resources, etc. It can be thought of like a "hint" to the model.
815 * For example, this information MAY be added to the system prompt.
816 */
817 instructions: optional(Schema.String)
818})) {}
819
820/**
821 * Sent from the client to the server when it first connects, asking it to begin
822 * initialization.
823 *
824 * @stability unstable
825 * @category protocols
826 * @since 4.0.0
827 */
828export class Initialize extends Rpc.make("initialize", {
829 success: InitializeResult,
830 error: McpError,
831 payload: {
832 ...RequestMeta.fields,
833 /**
834 * The latest version of the Model Context Protocol that the client
835 * supports. The client MAY decide to support older versions as well.
836 */
837 protocolVersion: Schema.String,
838 /**
839 * Capabilities a client may support. Known capabilities are defined here,
840 * in this schema, but this is not a closed set: any client can define its
841 * own, additional capabilities.
842 */
843 capabilities: ClientCapabilities,
844 /**
845 * Describes the name and version of an MCP implementation.
846 */
847 clientInfo: Implementation
848 }
849}) {}
850
851/**
852 * Sent from the client to the server after initialization has finished.
853 *
854 * @stability unstable
855 * @category protocols
856 * @since 4.0.0
857 */
858export class InitializedNotification extends Rpc.make("notifications/initialized", {
859 payload: Schema.UndefinedOr(NotificationMeta)
860}) {}
861
862// =============================================================================
863// Cancellation
864// =============================================================================
865
866/**
867 * Sent from either peer to cancel a previously issued request in the same
868 * direction.
869 *
870 * **Details**
871 *
872 * The payload identifies the request to cancel and may include a
873 * human-readable reason.
874 *
875 * @stability unstable
876 * @category protocols
877 * @since 4.0.0
878 */
879export class CancelledNotification extends Rpc.make("notifications/cancelled", {
880 payload: {
881 ...NotificationMeta.fields,
882 /**
883 * The ID of the request to cancel.
884 *
885 * This MUST correspond to the ID of a request previously issued in the
886 * same direction.
887 */
888 requestId: RequestId,
889 /**
890 * An optional string describing the reason for the cancellation. This MAY
891 * be logged or presented to the user.
892 */
893 reason: optional(Schema.String)
894 }
895}) {}
896
897// =============================================================================
898// Progress
899// =============================================================================
900
901/**
902 * Sent from either peer to report progress for a long-running request.
903 *
904 * @stability unstable
905 * @category protocols
906 * @since 4.0.0
907 */
908export class ProgressNotification extends Rpc.make("notifications/progress", {
909 payload: {
910 ...NotificationMeta.fields,
911 /**
912 * The progress token which was given in the initial request, used to
913 * associate this notification with the request that is proceeding.
914 */
915 progressToken: ProgressToken,
916 /**
917 * The progress thus far. This should increase every time progress is made,
918 * even if the total is unknown.
919 */
920 progress: Schema.Finite,
921 /**
922 * Total number of items to process (or total progress required), if known.
923 */
924 total: optional(Schema.Finite),
925 /**
926 * An optional message describing the current progress.
927 */
928 message: optional(Schema.String)
929 }
930}) {}
931
932// =============================================================================
933// Resources
934// =============================================================================
935
936/**
937 * Schema for a known resource that the server is capable of reading.
938 *
939 * @stability unstable
940 * @category schemas
941 * @since 4.0.0
942 */
943export class Resource extends Schema.Class<Resource>(
944 "@effect/ai/McpSchema/Resource"
945)({
946 /**
947 * The URI of this resource.
948 */
949 uri: Schema.String,
950 /**
951 * A human-readable name for this resource.
952 *
953 * This can be used by clients to populate UI elements.
954 */
955 name: Schema.String,
956 title: optional(Schema.String),
957 /**
958 * A description of what this resource represents.
959 *
960 * This can be used by clients to improve the LLM's understanding of available
961 * resources. It can be thought of like a "hint" to the model.
962 */
963 description: optional(Schema.String),
964 /**
965 * The MIME type of this resource, if known.
966 */
967 mimeType: optional(Schema.String),
968 /**
969 * Optional annotations for the client.
970 */
971 annotations: optional(Annotations),
972 /**
973 * Icons that clients can display for this resource.
974 */
975 icons: optional(Schema.Array(Icon)),
976 /**
977 * The size of the raw resource content, in bytes (i.e., before base64
978 * encoding or any tokenization), if known.
979 *
980 * This can be used by Hosts to display file sizes and estimate context
981 * window usage.
982 */
983 size: optional(Schema.Int),
984 /**
985 * Optional additional metadata for the client.
986 *
987 * This parameter name is reserved by MCP to allow clients and servers to
988 * attach additional metadata to resources.
989 */
990 _meta: optional(Schema.JsonObject)
991}) {}
992
993/**
994 * Schema for a template description of resources available on the server.
995 *
996 * @stability unstable
997 * @category schemas
998 * @since 4.0.0
999 */
1000export class ResourceTemplate extends Schema.Class<ResourceTemplate>(
1001 "@effect/ai/McpSchema/ResourceTemplate"
1002)({
1003 /**
1004 * A URI template (according to RFC 6570) that can be used to construct
1005 * resource URIs.
1006 */
1007 uriTemplate: Schema.String,
1008 /**
1009 * A human-readable name for the type of resource this template refers to.
1010 *
1011 * This can be used by clients to populate UI elements.
1012 */
1013 name: Schema.String,
1014 title: optional(Schema.String),
1015 /**
1016 * A description of what this template is for.
1017 *
1018 * This can be used by clients to improve the LLM's understanding of available
1019 * resources. It can be thought of like a "hint" to the model.
1020 */
1021 description: optional(Schema.String),
1022
1023 /**
1024 * The MIME type for all resources that match this template. This should only
1025 * be included if all resources matching this template have the same type.
1026 */
1027 mimeType: optional(Schema.String),
1028
1029 /**
1030 * Optional annotations for the client.
1031 */
1032 annotations: optional(Annotations),
1033 /**
1034 * Icons that clients can display for this resource template.
1035 */
1036 icons: optional(Schema.Array(Icon)),
1037
1038 /**
1039 * Optional additional metadata for the client.
1040 */
1041 _meta: optional(Schema.JsonObject)
1042}) {}
1043
1044/**
1045 * Schema for the contents of a specific resource or sub-resource.
1046 *
1047 * @stability unstable
1048 * @category schemas
1049 * @since 4.0.0
1050 */
1051export class ResourceContents extends Schema.Opaque<ResourceContents>()(Schema.Struct({
1052 /**
1053 * The URI of this resource.
1054 */
1055 uri: Schema.String,
1056 /**
1057 * The MIME type of this resource, if known.
1058 */
1059 mimeType: optional(Schema.String),
1060 /**
1061 * Optional additional metadata for the client.
1062 */
1063 _meta: optional(Schema.JsonObject)
1064})) {}
1065
1066/**
1067 * Schema for text resource contents represented as a string.
1068 *
1069 * @stability unstable
1070 * @category schemas
1071 * @since 4.0.0
1072 */
1073export class TextResourceContents extends Schema.Opaque<TextResourceContents>()(Schema.Struct({
1074 ...ResourceContents.fields,
1075 /**
1076 * The text of the item. This must only be set if the item can actually be
1077 * represented as text (not binary data).
1078 */
1079 text: Schema.String
1080})) {}
1081
1082/**
1083 * Schema for binary resource contents represented as a `Uint8Array`.
1084 *
1085 * @stability unstable
1086 * @category schemas
1087 * @since 4.0.0
1088 */
1089export class BlobResourceContents extends Schema.Opaque<BlobResourceContents>()(Schema.Struct({
1090 ...ResourceContents.fields,
1091 /**
1092 * The binary data of the item decoded from a base64-encoded string.
1093 */
1094 blob: Schema.Uint8ArrayFromBase64
1095})) {}
1096
1097/**
1098 * Schema for the server's response to a resources/list request from the client.
1099 *
1100 * @stability unstable
1101 * @category schemas
1102 * @since 4.0.0
1103 */
1104export class ListResourcesResult extends Schema.Class<ListResourcesResult>(
1105 "@effect/ai/McpSchema/ListResourcesResult"
1106)({
1107 ...PaginatedResultMeta.fields,
1108 resources: Schema.Array(Resource)
1109}) {}
1110
1111/**
1112 * Sent from the client to request a list of resources the server has.
1113 *
1114 * @stability unstable
1115 * @category protocols
1116 * @since 4.0.0
1117 */
1118export class ListResources extends Rpc.make("resources/list", {
1119 success: ListResourcesResult,
1120 error: McpError,
1121 payload: Schema.UndefinedOr(PaginatedRequestMeta)
1122}) {}
1123
1124/**
1125 * Schema for the server's response to a resources/templates/list request from
1126 * the client.
1127 *
1128 * @stability unstable
1129 * @category schemas
1130 * @since 4.0.0
1131 */
1132export class ListResourceTemplatesResult extends Schema.Class<ListResourceTemplatesResult>(
1133 "@effect/ai/McpSchema/ListResourceTemplatesResult"
1134)({
1135 ...PaginatedResultMeta.fields,
1136 resourceTemplates: Schema.Array(ResourceTemplate)
1137}) {}
1138
1139/**
1140 * Sent from the client to request a list of resource templates the server has.
1141 *
1142 * @stability unstable
1143 * @category protocols
1144 * @since 4.0.0
1145 */
1146export class ListResourceTemplates extends Rpc.make("resources/templates/list", {
1147 success: ListResourceTemplatesResult,
1148 error: McpError,
1149 payload: Schema.UndefinedOr(PaginatedRequestMeta)
1150}) {}
1151
1152/**
1153 * Schema for the server's response to a resources/read request from the client.
1154 *
1155 * @stability unstable
1156 * @category schemas
1157 * @since 4.0.0
1158 */
1159export class ReadResourceResult extends Schema.Opaque<ReadResourceResult>()(Schema.Struct({
1160 ...ResultMeta.fields,
1161 contents: Schema.Array(Schema.Union([TextResourceContents, BlobResourceContents]))
1162})) {}
1163
1164/**
1165 * Sent from the client to the server, to read a specific resource URI.
1166 *
1167 * @stability unstable
1168 * @category protocols
1169 * @since 4.0.0
1170 */
1171export class ReadResource extends Rpc.make("resources/read", {
1172 success: ReadResourceResult,
1173 error: McpError,
1174 payload: {
1175 ...RequestMeta.fields,
1176 /**
1177 * The URI of the resource to read. The URI can use any protocol; it is up
1178 * to the server how to interpret it.
1179 */
1180 uri: Schema.String
1181 }
1182}) {}
1183
1184/**
1185 * Represents a notification that the server's resource list changed.
1186 *
1187 * **When to use**
1188 *
1189 * Use to notify clients that `resources/list` should be requested again.
1190 *
1191 * **Details**
1192 *
1193 * Servers may send this notification without a previous client subscription.
1194 *
1195 * @stability unstable
1196 * @category protocols
1197 * @since 4.0.0
1198 */
1199export class ResourceListChangedNotification extends Rpc.make("notifications/resources/list_changed", {
1200 payload: Schema.UndefinedOr(NotificationMeta)
1201}) {}
1202
1203/**
1204 * Sent from the client to request resources/updated notifications from the
1205 * server whenever a particular resource changes.
1206 *
1207 * @stability unstable
1208 * @category protocols
1209 * @since 4.0.0
1210 */
1211export class Subscribe extends Rpc.make("resources/subscribe", {
1212 success: Schema.Struct({}),
1213 error: McpError,
1214 payload: {
1215 ...RequestMeta.fields,
1216 /**
1217 * The URI of the resource to subscribe to. The URI can use any protocol;
1218 * it is up to the server how to interpret it.
1219 */
1220 uri: Schema.String
1221 }
1222}) {}
1223
1224/**
1225 * Sent from the client to request cancellation of resources/updated
1226 * notifications from the server. This should follow a previous
1227 * resources/subscribe request.
1228 *
1229 * @stability unstable
1230 * @category protocols
1231 * @since 4.0.0
1232 */
1233export class Unsubscribe extends Rpc.make("resources/unsubscribe", {
1234 success: Schema.Struct({}),
1235 error: McpError,
1236 payload: {
1237 ...RequestMeta.fields,
1238 /**
1239 * The URI of the resource to subscribe to. The URI can use any protocol;
1240 * it is up to the server how to interpret it.
1241 */
1242 uri: Schema.String
1243 }
1244}) {}
1245
1246/**
1247 * Sent from the server when a subscribed resource URI has changed.
1248 *
1249 * **Details**
1250 *
1251 * The URI may identify a sub-resource of the resource that the client
1252 * originally subscribed to.
1253 *
1254 * @stability unstable
1255 * @category protocols
1256 * @since 4.0.0
1257 */
1258export class ResourceUpdatedNotification extends Rpc.make("notifications/resources/updated", {
1259 payload: {
1260 ...NotificationMeta.fields,
1261 /**
1262 * The URI of the resource that has been updated. This might be a sub-resource of the one that the client actually subscribed to.
1263 */
1264 uri: Schema.String
1265 }
1266}) {}
1267
1268// =============================================================================
1269// Prompts
1270// =============================================================================
1271
1272/**
1273 * Describes an argument that a prompt can accept.
1274 *
1275 * @stability unstable
1276 * @category schemas
1277 * @since 4.0.0
1278 */
1279export class PromptArgument extends Schema.Opaque<PromptArgument>()(Schema.Struct({
1280 /**
1281 * The name of the argument.
1282 */
1283 name: Schema.String,
1284 title: optional(Schema.String),
1285 /**
1286 * A human-readable description of the argument.
1287 */
1288 description: optional(Schema.String),
1289 /**
1290 * Whether this argument must be provided.
1291 */
1292 required: optional(Schema.Boolean)
1293})) {}
1294
1295/**
1296 * Represents a prompt or prompt template that the server offers.
1297 *
1298 * @stability unstable
1299 * @category schemas
1300 * @since 4.0.0
1301 */
1302export class Prompt extends Schema.Class<Prompt>(
1303 "@effect/ai/McpSchema/Prompt"
1304)({
1305 /**
1306 * The name of the prompt or prompt template.
1307 */
1308 name: Schema.String,
1309 title: optional(Schema.String),
1310 /**
1311 * An optional description of what this prompt provides
1312 */
1313 description: optional(Schema.String),
1314 /**
1315 * A list of arguments to use for templating the prompt.
1316 */
1317 arguments: optional(Schema.Array(PromptArgument)),
1318 /**
1319 * Icons that clients can display for this prompt.
1320 */
1321 icons: optional(Schema.Array(Icon)),
1322 _meta: optional(Schema.JsonObject)
1323}) {}
1324
1325/**
1326 * Represents text content provided to or from an LLM.
1327 *
1328 * @stability unstable
1329 * @category schemas
1330 * @since 4.0.0
1331 */
1332export class TextContent extends Schema.Opaque<TextContent>()(Schema.Struct({
1333 type: Schema.tag("text"),
1334 /**
1335 * The text content of the message.
1336 */
1337 text: Schema.String,
1338 /**
1339 * Optional annotations for the client.
1340 */
1341 annotations: optional(Annotations),
1342 _meta: optional(Schema.JsonObject)
1343})) {}
1344
1345/**
1346 * Represents image content provided to or from an LLM.
1347 *
1348 * @stability unstable
1349 * @category schemas
1350 * @since 4.0.0
1351 */
1352export class ImageContent extends Schema.Opaque<ImageContent>()(Schema.Struct({
1353 type: Schema.tag("image"),
1354 /**
1355 * The image data.
1356 */
1357 data: Schema.Uint8ArrayFromBase64,
1358 /**
1359 * The MIME type of the image. Different providers may support different
1360 * image types.
1361 */
1362 mimeType: Schema.String,
1363 /**
1364 * Optional annotations for the client.
1365 */
1366 annotations: optional(Annotations),
1367 _meta: optional(Schema.JsonObject)
1368})) {}
1369
1370/**
1371 * Represents audio content provided to or from an LLM.
1372 *
1373 * @stability unstable
1374 * @category schemas
1375 * @since 4.0.0
1376 */
1377export class AudioContent extends Schema.Opaque<AudioContent>()(Schema.Struct({
1378 type: Schema.tag("audio"),
1379 /**
1380 * The audio data.
1381 */
1382 data: Schema.Uint8ArrayFromBase64,
1383 /**
1384 * The MIME type of the audio. Different providers may support different
1385 * audio types.
1386 */
1387 mimeType: Schema.String,
1388 /**
1389 * Optional annotations for the client.
1390 */
1391 annotations: optional(Annotations),
1392 _meta: optional(Schema.JsonObject)
1393})) {}
1394
1395/**
1396 * Represents resource contents embedded into a prompt or tool call result.
1397 *
1398 * **Details**
1399 *
1400 * It is up to the client how best to render embedded resources for the benefit
1401 * of the LLM and/or the user.
1402 *
1403 * @stability unstable
1404 * @category schemas
1405 * @since 4.0.0
1406 */
1407export class EmbeddedResource extends Schema.Opaque<EmbeddedResource>()(Schema.Struct({
1408 type: Schema.tag("resource"),
1409 resource: Schema.Union([TextResourceContents, BlobResourceContents]),
1410 /**
1411 * Optional annotations for the client.
1412 */
1413 annotations: optional(Annotations),
1414 _meta: optional(Schema.JsonObject)
1415})) {}
1416
1417/**
1418 * Represents a readable resource included in a prompt or tool call result.
1419 *
1420 * **Gotchas**
1421 *
1422 * Resource links returned by tools are not guaranteed to appear in the results
1423 * of `resources/list` requests.
1424 *
1425 * @stability unstable
1426 * @category schemas
1427 * @since 4.0.0
1428 */
1429export class ResourceLink extends Schema.Opaque<ResourceLink>()(Schema.Struct({
1430 ...Resource.fields,
1431 type: Schema.tag("resource_link")
1432})) {}
1433
1434/**
1435 * Schema for MCP content blocks that can appear in prompt messages or tool
1436 * results.
1437 *
1438 * @stability unstable
1439 * @category schemas
1440 * @since 4.0.0
1441 */
1442export const ContentBlock = Schema.Union([
1443 TextContent,
1444 ImageContent,
1445 AudioContent,
1446 EmbeddedResource,
1447 ResourceLink
1448])
1449
1450/**
1451 * Type represented by the MCP content block schema.
1452 *
1453 * @stability unstable
1454 * @category models
1455 * @since 4.0.0
1456 */
1457export type ContentBlock = typeof ContentBlock.Type
1458
1459/**
1460 * Describes a message returned as part of a prompt.
1461 *
1462 * **Details**
1463 *
1464 * This is similar to `SamplingMessage`, but also supports the embedding of
1465 * resources from the MCP server.
1466 *
1467 * @stability unstable
1468 * @category schemas
1469 * @since 4.0.0
1470 */
1471export class PromptMessage extends Schema.Opaque<PromptMessage>()(Schema.Struct({
1472 role: Role,
1473 content: ContentBlock
1474})) {}
1475
1476/**
1477 * Represents the server response to a prompts/list request from the client.
1478 *
1479 * @stability unstable
1480 * @category schemas
1481 * @since 4.0.0
1482 */
1483export class ListPromptsResult extends Schema.Class<ListPromptsResult>(
1484 "@effect/ai/McpSchema/ListPromptsResult"
1485)({
1486 ...PaginatedResultMeta.fields,
1487 prompts: Schema.Array(Prompt)
1488}) {}
1489
1490/**
1491 * Sent from the client to request a list of prompts and prompt templates the
1492 * server has.
1493 *
1494 * @stability unstable
1495 * @category protocols
1496 * @since 4.0.0
1497 */
1498export class ListPrompts extends Rpc.make("prompts/list", {
1499 success: ListPromptsResult,
1500 error: McpError,
1501 payload: Schema.UndefinedOr(PaginatedRequestMeta)
1502}) {}
1503
1504/**
1505 * Represents the server response to a prompts/get request from the client.
1506 *
1507 * @stability unstable
1508 * @category schemas
1509 * @since 4.0.0
1510 */
1511export class GetPromptResult extends Schema.Class<GetPromptResult>(
1512 "@effect/ai/McpSchema/GetPromptResult"
1513)({
1514 ...ResultMeta.fields,
1515 messages: Schema.Array(PromptMessage),
1516 /**
1517 * An optional description for the prompt.
1518 */
1519 description: optional(Schema.String)
1520}) {}
1521
1522/**
1523 * Sent from the client to get a prompt provided by the server.
1524 *
1525 * @stability unstable
1526 * @category protocols
1527 * @since 4.0.0
1528 */
1529export class GetPrompt extends Rpc.make("prompts/get", {
1530 success: GetPromptResult,
1531 error: McpError,
1532 payload: {
1533 ...RequestMeta.fields,
1534 /**
1535 * The name of the prompt or prompt template.
1536 */
1537 name: Schema.String,
1538 title: optional(Schema.String),
1539 /**
1540 * Arguments to use for templating the prompt.
1541 */
1542 arguments: optional(Schema.Record(Schema.String, Schema.String))
1543 }
1544}) {}
1545
1546/**
1547 * Represents a notification that the server's prompt list changed.
1548 *
1549 * **When to use**
1550 *
1551 * Use to notify clients that `prompts/list` should be requested again.
1552 *
1553 * **Details**
1554 *
1555 * Servers may send this notification without a previous client subscription.
1556 *
1557 * @stability unstable
1558 * @category protocols
1559 * @since 4.0.0
1560 */
1561export class PromptListChangedNotification extends Rpc.make("notifications/prompts/list_changed", {
1562 payload: Schema.UndefinedOr(NotificationMeta)
1563}) {}
1564
1565// =============================================================================
1566// Tools
1567// =============================================================================
1568
1569/**
1570 * Schema for additional properties describing a tool to clients.
1571 *
1572 * **Details**
1573 *
1574 * NOTE: all properties in ToolAnnotations are **hints**. They are not
1575 * guaranteed to provide a faithful description of tool behavior (including
1576 * descriptive properties like `title`).
1577 *
1578 * **Gotchas**
1579 *
1580 * Clients should never make tool use decisions based on ToolAnnotations
1581 * received from untrusted servers.
1582 *
1583 * @stability unstable
1584 * @category schemas
1585 * @since 4.0.0
1586 */
1587export class ToolAnnotations extends Schema.Opaque<ToolAnnotations>()(Schema.Struct({
1588 /**
1589 * A human-readable title for the tool.
1590 */
1591 title: optional(Schema.String),
1592 /**
1593 * If true, the tool does not modify its environment.
1594 *
1595 * Default: `false`
1596 */
1597 readOnlyHint: optionalWithDefault(Schema.Boolean, constFalse),
1598 /**
1599 * If true, the tool may perform destructive updates to its environment.
1600 * If false, the tool performs only additive updates.
1601 *
1602 * (This property is meaningful only when `readOnlyHint == false`)
1603 *
1604 * Default: `true`
1605 */
1606 destructiveHint: optionalWithDefault(Schema.Boolean, constTrue),
1607 /**
1608 * If true, calling the tool repeatedly with the same arguments
1609 * will have no additional effect on the its environment.
1610 *
1611 * (This property is meaningful only when `readOnlyHint == false`)
1612 *
1613 * Default: `false`
1614 */
1615 idempotentHint: optionalWithDefault(Schema.Boolean, constFalse),
1616 /**
1617 * If true, this tool may interact with an "open world" of external
1618 * entities. If false, the tool's domain of interaction is closed.
1619 * For example, the world of a web search tool is open, whereas that
1620 * of a memory tool is not.
1621 *
1622 * Default: `true`
1623 */
1624 openWorldHint: optionalWithDefault(Schema.Boolean, constTrue)
1625})) {}
1626
1627/**
1628 * Object-root JSON Schema used by MCP tool inputs.
1629 *
1630 * **Details**
1631 *
1632 * Property definitions and additional root keywords are constrained to JSON
1633 * values. The open root supports generated keywords such as `$defs`.
1634 *
1635 * @stability unstable
1636 * @category tools
1637 * @since 4.0.0
1638 */
1639export type ToolJson = Schema.JsonObject & {
1640 readonly type: "object"
1641 readonly properties?: Readonly<Record<string, Schema.JsonObject>> | undefined
1642 readonly required?: ReadonlyArray<string> | undefined
1643}
1644
1645/**
1646 * Schema for {@link ToolJson}.
1647 *
1648 * @stability unstable
1649 * @category tools
1650 * @since 4.0.0
1651 */
1652export const ToolJson: Schema.Codec<ToolJson> = Schema.StructWithRest(
1653 Schema.Struct({
1654 type: Schema.Literal("object"),
1655 properties: optional(Schema.Record(Schema.String, Schema.JsonObject)),
1656 required: optional(Schema.Array(Schema.String))
1657 }),
1658 [Schema.JsonObject]
1659)
1660
1661/**
1662 * JSON Schema used by MCP tool outputs.
1663 *
1664 * **Details**
1665 *
1666 * Unlike tool inputs, tool outputs may use any JSON Schema root type.
1667 *
1668 * @stability unstable
1669 * @category tools
1670 * @since 4.0.0
1671 */
1672export type ToolOutputJson = Schema.JsonObject
1673
1674/**
1675 * Schema for {@link ToolOutputJson}.
1676 *
1677 * @stability unstable
1678 * @category tools
1679 * @since 4.0.0
1680 */
1681export const ToolOutputJson: Schema.Codec<ToolOutputJson> = Schema.JsonObject
1682
1683/**
1684 * Schema for the definition of a tool the client can call.
1685 *
1686 * @stability unstable
1687 * @category schemas
1688 * @since 4.0.0
1689 */
1690export class Tool extends Schema.Class<Tool>(
1691 "@effect/ai/McpSchema/Tool"
1692)({
1693 /**
1694 * The name of the tool.
1695 */
1696 name: Schema.String,
1697 title: optional(Schema.String),
1698 /**
1699 * A human-readable description of the tool.
1700 *
1701 * This can be used by clients to improve the LLM's understanding of available tools. It can be thought of like a "hint" to the model.
1702 */
1703 description: optional(Schema.String),
1704 /**
1705 * A JSON Schema object defining the expected parameters for the tool.
1706 */
1707 inputSchema: ToolJson,
1708 /**
1709 * An optional JSON Schema object defining the structure of the tool output.
1710 */
1711 outputSchema: optional(ToolOutputJson),
1712 /**
1713 * Optional additional tool information.
1714 */
1715 annotations: optional(ToolAnnotations),
1716 /**
1717 * Icons that clients can display for this tool.
1718 */
1719 icons: optional(Schema.Array(Icon)),
1720 /**
1721 * Optional additional metadata for the client.
1722 *
1723 * This parameter name is reserved by MCP to allow clients and servers to
1724 * attach additional metadata to resources.
1725 */
1726 _meta: optional(Schema.JsonObject)
1727}) {}
1728
1729/**
1730 * Schema for the server's response to a tools/list request from the client.
1731 *
1732 * @stability unstable
1733 * @category schemas
1734 * @since 4.0.0
1735 */
1736export class ListToolsResult extends Schema.Class<ListToolsResult>(
1737 "@effect/ai/McpSchema/ListToolsResult"
1738)({
1739 ...PaginatedResultMeta.fields,
1740 tools: Schema.Array(Tool)
1741}) {}
1742
1743/**
1744 * Sent from the client to request a list of tools the server has.
1745 *
1746 * @stability unstable
1747 * @category protocols
1748 * @since 4.0.0
1749 */
1750export class ListTools extends Rpc.make("tools/list", {
1751 success: ListToolsResult,
1752 error: McpError,
1753 payload: Schema.UndefinedOr(PaginatedRequestMeta)
1754}) {}
1755
1756/**
1757 * Schema for the server's response to a tool call.
1758 *
1759 * **Details**
1760 *
1761 * Any errors that originate from the tool SHOULD be reported inside the result
1762 * object, with `isError` set to true, _not_ as an MCP protocol-level error
1763 * response. Otherwise, the LLM would not be able to see that an error occurred
1764 * and self-correct. However, any errors in _finding_ the tool, an error
1765 * indicating that the server does not support tool calls, or any other
1766 * exceptional conditions, should be reported as an MCP error response.
1767 *
1768 * @stability unstable
1769 * @category schemas
1770 * @since 4.0.0
1771 */
1772export class CallToolResult extends Schema.Class<CallToolResult>("@effect/ai/McpSchema/CallToolResult")({
1773 ...ResultMeta.fields,
1774 content: Schema.Array(ContentBlock),
1775 /**
1776 * An optional JSON value containing the structured result of the tool call.
1777 */
1778 structuredContent: optional(Schema.Json),
1779 /**
1780 * Whether the tool call ended in an error.
1781 *
1782 * If not set, this is assumed to be false (the call was successful).
1783 */
1784 isError: optional(Schema.Boolean)
1785}) {}
1786
1787/**
1788 * Represents a client request to invoke a tool provided by the server.
1789 *
1790 * **When to use**
1791 *
1792 * Use when you need to represent a client request that already knows the tool
1793 * name and asks the server to execute it with argument values.
1794 *
1795 * @see {@link ListTools} for discovering available tools before calling one
1796 * @see {@link CallToolResult} for the successful tool-call result shape
1797 *
1798 * @stability unstable
1799 * @category protocols
1800 * @since 4.0.0
1801 */
1802export class CallTool extends Rpc.make("tools/call", {
1803 success: CallToolResult,
1804 error: McpError,
1805 payload: {
1806 ...RequestMeta.fields,
1807 name: Schema.String,
1808 arguments: optionalWithDefault(
1809 Schema.Record(
1810 Schema.String,
1811 Schema.Any
1812 ),
1813 () => ({})
1814 )
1815 }
1816}) {}
1817
1818/**
1819 * Represents a notification that the server's tool list changed.
1820 *
1821 * **When to use**
1822 *
1823 * Use to notify clients that `tools/list` should be requested again.
1824 *
1825 * **Details**
1826 *
1827 * Servers may send this notification without a previous client subscription.
1828 *
1829 * @stability unstable
1830 * @category protocols
1831 * @since 4.0.0
1832 */
1833export class ToolListChangedNotification extends Rpc.make("notifications/tools/list_changed", {
1834 payload: Schema.UndefinedOr(NotificationMeta)
1835}) {}
1836
1837// =============================================================================
1838// Logging
1839// =============================================================================
1840
1841/**
1842 * Schema for log message severity levels, mapped to syslog message severities
1843 * as specified in RFC 5424 section 6.2.1:
1844 * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1.
1845 *
1846 * @stability unstable
1847 * @category logging
1848 * @since 4.0.0
1849 */
1850export const LoggingLevel: Schema.Literals<[
1851 "debug",
1852 "info",
1853 "notice",
1854 "warning",
1855 "error",
1856 "critical",
1857 "alert",
1858 "emergency"
1859]> = Schema.Literals([
1860 "debug",
1861 "info",
1862 "notice",
1863 "warning",
1864 "error",
1865 "critical",
1866 "alert",
1867 "emergency"
1868])
1869
1870/**
1871 * Type represented by the MCP logging level schema, mapped to syslog message
1872 * severities as specified in RFC 5424 section 6.2.1:
1873 * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1.
1874 *
1875 * @stability unstable
1876 * @category logging
1877 * @since 4.0.0
1878 */
1879export type LoggingLevel = typeof LoggingLevel.Type
1880
1881/**
1882 * Sent from the client to the server to enable or adjust logging.
1883 *
1884 * @stability unstable
1885 * @category logging
1886 * @since 4.0.0
1887 */
1888export class SetLevel extends Rpc.make("logging/setLevel", {
1889 payload: {
1890 ...RequestMeta.fields,
1891 /**
1892 * The level of logging that the client wants to receive from the server.
1893 * The server should send all logs at this level and higher (i.e., more
1894 * severe) to the client as notifications/message.
1895 */
1896 level: LoggingLevel
1897 },
1898 success: Schema.Struct({}),
1899 error: McpError
1900}) {}
1901
1902/**
1903 * Sent from the server to the client carrying a log message.
1904 *
1905 * **Details**
1906 *
1907 * The notification includes the severity level, optional logger name, and
1908 * JSON-serializable log data.
1909 *
1910 * @stability unstable
1911 * @category logging
1912 * @since 4.0.0
1913 */
1914export class LoggingMessageNotification extends Rpc.make("notifications/message", {
1915 payload: Schema.Struct({
1916 ...NotificationMeta.fields,
1917 /**
1918 * The severity of this log message.
1919 */
1920 level: LoggingLevel,
1921 /**
1922 * An optional name of the logger issuing this message.
1923 */
1924 logger: optional(Schema.String),
1925 /**
1926 * The data to be logged, such as a string message or an object. Any JSON
1927 * serializable type is allowed here.
1928 */
1929 data: Schema.Any
1930 })
1931}) {}
1932
1933// =============================================================================
1934// Sampling
1935// =============================================================================
1936
1937/**
1938 * Schema for a tool-use request produced during MCP sampling.
1939 *
1940 * @stability unstable
1941 * @category sampling
1942 * @since 4.0.0
1943 */
1944export class ToolUseContent extends Schema.Class<ToolUseContent>("@effect/ai/McpSchema/ToolUseContent")({
1945 type: Schema.tag("tool_use"),
1946 /**
1947 * Identifier used to associate a later tool result with this request.
1948 */
1949 id: Schema.String,
1950 /**
1951 * Name of the tool to invoke.
1952 */
1953 name: Schema.String,
1954 /**
1955 * Arguments supplied to the tool.
1956 */
1957 input: Schema.Record(Schema.String, Schema.Unknown),
1958 _meta: optional(Schema.JsonObject)
1959}) {}
1960
1961/**
1962 * Schema for the result of a tool use supplied in a sampling message.
1963 *
1964 * @stability unstable
1965 * @category sampling
1966 * @since 4.0.0
1967 */
1968export class ToolResultContent extends Schema.Class<ToolResultContent>("@effect/ai/McpSchema/ToolResultContent")({
1969 type: Schema.tag("tool_result"),
1970 /**
1971 * Identifier of the tool-use request that produced this result.
1972 */
1973 toolUseId: Schema.String,
1974 /**
1975 * Content returned by the tool.
1976 */
1977 content: Schema.Array(ContentBlock),
1978 /**
1979 * Optional structured result returned by the tool.
1980 */
1981 structuredContent: optional(Schema.Json),
1982 /**
1983 * Whether tool execution ended in an error.
1984 */
1985 isError: optional(Schema.Boolean),
1986 _meta: optional(Schema.JsonObject)
1987}) {}
1988
1989/**
1990 * Schema for content blocks accepted in MCP sampling messages.
1991 *
1992 * @stability unstable
1993 * @category sampling
1994 * @since 4.0.0
1995 */
1996export const SamplingMessageContentBlock = Schema.Union([
1997 TextContent,
1998 ImageContent,
1999 AudioContent,
2000 ToolUseContent,
2001 ToolResultContent
2002])
2003
2004/**
2005 * Type represented by the MCP sampling message content block schema.
2006 *
2007 * @stability unstable
2008 * @category models
2009 * @since 4.0.0
2010 */
2011export type SamplingMessageContentBlock = typeof SamplingMessageContentBlock.Type
2012
2013/**
2014 * Describes a message issued to or received from an LLM API.
2015 *
2016 * @stability unstable
2017 * @category schemas
2018 * @since 4.0.0
2019 */
2020export class SamplingMessage extends Schema.Opaque<SamplingMessage>()(Schema.Struct({
2021 role: Role,
2022 content: Schema.Union([SamplingMessageContentBlock, Schema.Array(SamplingMessageContentBlock)]),
2023 _meta: optional(Schema.JsonObject)
2024})) {}
2025
2026/**
2027 * Schema for controlling tool selection during MCP sampling.
2028 *
2029 * @stability unstable
2030 * @category sampling
2031 * @since 4.0.0
2032 */
2033export class ToolChoice extends Schema.Class<ToolChoice>("@effect/ai/McpSchema/ToolChoice")({
2034 /**
2035 * Tool-selection mode requested from the client.
2036 */
2037 mode: optional(Schema.Literals(["auto", "required", "none"]))
2038}) {}
2039
2040/**
2041 * Schema for model selection hints.
2042 *
2043 * **Details**
2044 *
2045 * Keys not declared here are currently left unspecified by the spec and are up
2046 * to the client to interpret.
2047 *
2048 * @stability unstable
2049 * @category schemas
2050 * @since 4.0.0
2051 */
2052export class ModelHint extends Schema.Opaque<ModelHint>()(Schema.Struct({
2053 /**
2054 * A hint for a model name.
2055 *
2056 * The client SHOULD treat this as a substring of a model name; for example:
2057 * - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022`
2058 * - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc.
2059 * - `claude` should match any Claude model
2060 *
2061 * The client MAY also map the string to a different provider's model name or
2062 * a different model family, as long as it fills a similar niche; for example:
2063 * - `gemini-1.5-flash` could match `claude-3-haiku-20240307`
2064 */
2065 name: optional(Schema.String)
2066})) {}
2067
2068/**
2069 * Schema for the server's model selection preferences requested of the client
2070 * during sampling.
2071 *
2072 * **Details**
2073 *
2074 * Because LLMs can vary along multiple dimensions, choosing the "best" model is
2075 * rarely straightforward. Different models excel in different areas, some are
2076 * faster but less capable, others are more capable but more expensive, and so
2077 * on. This interface allows servers to express their priorities across multiple
2078 * dimensions to help clients make an appropriate selection for their use case.
2079 *
2080 * **Gotchas**
2081 *
2082 * These preferences are always advisory. The client MAY ignore them. It is also
2083 * up to the client to decide how to interpret these preferences and how to
2084 * balance them against other considerations.
2085 *
2086 * @stability unstable
2087 * @category schemas
2088 * @since 4.0.0
2089 */
2090export class ModelPreferences extends Schema.Class<ModelPreferences>(
2091 "@effect/ai/McpSchema/ModelPreferences"
2092)({
2093 /**
2094 * Optional hints to use for model selection.
2095 *
2096 * If multiple hints are specified, the client MUST evaluate them in order
2097 * (such that the first match is taken).
2098 *
2099 * The client SHOULD prioritize these hints over the numeric priorities, but
2100 * MAY still use the priorities to select from ambiguous matches.
2101 */
2102 hints: optional(Schema.Array(ModelHint)),
2103 /**
2104 * How much to prioritize cost when selecting a model. A value of 0 means cost
2105 * is not important, while a value of 1 means cost is the most important
2106 * factor.
2107 */
2108 costPriority: optional(Schema.Finite.check(Schema.isBetween({ minimum: 0, maximum: 1 }))),
2109 /**
2110 * How much to prioritize sampling speed (latency) when selecting a model. A
2111 * value of 0 means speed is not important, while a value of 1 means speed is
2112 * the most important factor.
2113 */
2114 speedPriority: optional(Schema.Finite.check(Schema.isBetween({ minimum: 0, maximum: 1 }))),
2115 /**
2116 * How much to prioritize intelligence and capabilities when selecting a
2117 * model. A value of 0 means intelligence is not important, while a value of 1
2118 * means intelligence is the most important factor.
2119 */
2120 intelligencePriority: optional(Schema.Finite.check(Schema.isBetween({ minimum: 0, maximum: 1 })))
2121}) {}
2122
2123/**
2124 * Represents a client response to an MCP sampling request.
2125 *
2126 * **When to use**
2127 *
2128 * Use to return the message produced by client-side model sampling.
2129 *
2130 * **Details**
2131 *
2132 * The client should let the user inspect the sampled message before returning
2133 * it to the server.
2134 *
2135 * @stability unstable
2136 * @category schemas
2137 * @since 4.0.0
2138 */
2139export class CreateMessageResult extends Schema.Class<CreateMessageResult>(
2140 "@effect/ai/McpSchema/CreateMessageResult"
2141)({
2142 role: Role,
2143 content: Schema.Union([SamplingMessageContentBlock, Schema.Array(SamplingMessageContentBlock)]),
2144 _meta: optional(Schema.JsonObject),
2145 /**
2146 * The name of the model that generated the message.
2147 */
2148 model: Schema.String,
2149 /**
2150 * The reason why sampling stopped, if known.
2151 */
2152 stopReason: optional(Schema.String)
2153}) {}
2154
2155/**
2156 * Represents a server request for the client to sample an LLM.
2157 *
2158 * **When to use**
2159 *
2160 * Use when you need to request model sampling from an MCP client on behalf of a
2161 * server.
2162 *
2163 * **Details**
2164 *
2165 * The client chooses the model and should ask the user to approve the sampling
2166 * request before it begins.
2167 *
2168 * @stability unstable
2169 * @category protocols
2170 * @since 4.0.0
2171 */
2172export class CreateMessage extends Rpc.make("sampling/createMessage", {
2173 success: CreateMessageResult,
2174 error: McpError,
2175 payload: {
2176 messages: Schema.Array(SamplingMessage),
2177 /**
2178 * The server's preferences for which model to select. The client MAY ignore
2179 * these preferences.
2180 */
2181 modelPreferences: optional(Schema.Struct(ModelPreferences.fields)),
2182 /**
2183 * An optional system prompt the server wants to use for sampling. The
2184 * client MAY modify or omit this prompt.
2185 */
2186 systemPrompt: optional(Schema.String),
2187 /**
2188 * A request to include context from one or more MCP servers (including the
2189 * caller), to be attached to the prompt. The client MAY ignore this request.
2190 */
2191 includeContext: optional(Schema.Literals(["none", "thisServer", "allServers"])),
2192 temperature: optional(Schema.Finite),
2193 /**
2194 * The maximum number of tokens to sample, as requested by the server. The
2195 * client MAY choose to sample fewer tokens than requested.
2196 */
2197 maxTokens: Schema.Int,
2198 stopSequences: optional(Schema.Array(Schema.String)),
2199 /**
2200 * Optional metadata to pass through to the LLM provider. The format of
2201 * this metadata is provider-specific.
2202 */
2203 metadata: optional(Schema.Record(Schema.String, Schema.Unknown)),
2204 /**
2205 * Tools that the model may call while producing the response.
2206 */
2207 tools: optional(Schema.Array(Schema.Struct(Tool.fields))),
2208 /**
2209 * Controls whether the model may or must call a tool.
2210 */
2211 toolChoice: optional(Schema.Struct(ToolChoice.fields))
2212 }
2213}) {}
2214
2215// =============================================================================
2216// Autocomplete
2217// =============================================================================
2218
2219/**
2220 * Schema for a reference to a resource or resource template definition.
2221 *
2222 * @stability unstable
2223 * @category schemas
2224 * @since 4.0.0
2225 */
2226export class ResourceReference extends Schema.Opaque<ResourceReference>()(Schema.Struct({
2227 type: Schema.tag("ref/resource"),
2228 /**
2229 * The URI or URI template of the resource.
2230 */
2231 uri: Schema.String
2232})) {}
2233
2234/**
2235 * Schema for a prompt reference used in autocomplete requests.
2236 *
2237 * @stability unstable
2238 * @category schemas
2239 * @since 4.0.0
2240 */
2241export class PromptReference extends Schema.Opaque<PromptReference>()(Schema.Struct({
2242 type: Schema.tag("ref/prompt"),
2243 /**
2244 * The name of the prompt or prompt template
2245 */
2246 name: Schema.String,
2247 title: optional(Schema.String)
2248})) {}
2249
2250/**
2251 * Schema for the server's response to a completion/complete request.
2252 *
2253 * @stability unstable
2254 * @category schemas
2255 * @since 4.0.0
2256 */
2257export class CompleteResult extends Schema.Opaque<CompleteResult>()(Schema.Struct({
2258 ...ResultMeta.fields,
2259 completion: Schema.Struct({
2260 /**
2261 * An array of completion values. Must not exceed 100 items.
2262 */
2263 values: Schema.Array(Schema.String),
2264 /**
2265 * The total number of completion options available. This can exceed the
2266 * number of values actually sent in the response.
2267 */
2268 total: optional(Schema.Int),
2269 /**
2270 * Indicates whether there are additional completion options beyond those
2271 * provided in the current response, even if the exact total is unknown.
2272 */
2273 hasMore: optional(Schema.Boolean)
2274 })
2275})) {
2276 /**
2277 * Empty completion result used when a completion request has no values.
2278 *
2279 * @stability unstable
2280 * @since 4.0.0
2281 */
2282 static readonly empty = CompleteResult.make({
2283 completion: {
2284 values: [],
2285 total: 0,
2286 hasMore: false
2287 }
2288 })
2289}
2290
2291/**
2292 * Sent from the client to the server to ask for completion options.
2293 *
2294 * @stability unstable
2295 * @category protocols
2296 * @since 4.0.0
2297 */
2298export class Complete extends Rpc.make("completion/complete", {
2299 success: CompleteResult,
2300 error: McpError,
2301 payload: Schema.Struct({
2302 ref: Schema.Union([PromptReference, ResourceReference]),
2303 /**
2304 * The argument's information
2305 */
2306 argument: Schema.Struct({
2307 /**
2308 * The name of the argument
2309 */
2310 name: Schema.String,
2311 /**
2312 * The value of the argument to use for completion matching.
2313 */
2314 value: Schema.String
2315 }),
2316 /**
2317 * Additional, optional context for completions
2318 */
2319 context: optionalWithDefault(
2320 Schema.Struct({
2321 /**
2322 * Previously-resolved variables in a URI template or prompt.
2323 */
2324 arguments: optionalWithDefault(
2325 Schema.Record(Schema.String, Schema.String),
2326 () => ({})
2327 )
2328 }),
2329 () => ({ arguments: {} })
2330 )
2331 })
2332}) {}
2333
2334// =============================================================================
2335// Roots
2336// =============================================================================
2337
2338/**
2339 * Represents a root directory or file that the server can operate on.
2340 *
2341 * @stability unstable
2342 * @category schemas
2343 * @since 4.0.0
2344 */
2345export class Root extends Schema.Class<Root>(
2346 "@effect/ai/McpSchema/Root"
2347)({
2348 /**
2349 * The URI identifying the root. This *must* start with file:// for now.
2350 * This restriction may be relaxed in future versions of the protocol to allow
2351 * other URI schemes.
2352 */
2353 uri: Schema.String,
2354 /**
2355 * An optional name for the root. This can be used to provide a human-readable
2356 * identifier for the root, which may be useful for display purposes or for
2357 * referencing the root in other parts of the application.
2358 */
2359 name: optional(Schema.String),
2360 /**
2361 * Optional additional metadata associated with the root.
2362 */
2363 _meta: optional(Schema.JsonObject)
2364}) {}
2365
2366/**
2367 * Represents a client response containing the roots available to the server.
2368 *
2369 * **When to use**
2370 *
2371 * Use to return the directories or files that an MCP server may operate on.
2372 *
2373 * @stability unstable
2374 * @category schemas
2375 * @since 4.0.0
2376 */
2377export class ListRootsResult extends Schema.Class<ListRootsResult>(
2378 "@effect/ai/McpSchema/ListRootsResult"
2379)({
2380 roots: Schema.Array(Root)
2381}) {}
2382
2383/**
2384 * Sent from the server to request a list of root URIs from the client. Roots
2385 * allow servers to ask for specific directories or files to operate on. A
2386 * common example for roots is providing a set of repositories or directories a
2387 * server should operate on.
2388 *
2389 * **Details**
2390 *
2391 * This request is typically used when the server needs to understand the file
2392 * system structure or access specific locations that the client has permission
2393 * to read from.
2394 *
2395 * @stability unstable
2396 * @category protocols
2397 * @since 4.0.0
2398 */
2399export class ListRoots extends Rpc.make("roots/list", {
2400 success: ListRootsResult,
2401 error: McpError,
2402 payload: Schema.UndefinedOr(RequestMeta)
2403}) {}
2404
2405/**
2406 * Represents a notification that the client's root list changed.
2407 *
2408 * **When to use**
2409 *
2410 * Use to tell the server that it should request an updated roots list.
2411 *
2412 * **Details**
2413 *
2414 * Send this when the client adds, removes, or modifies a root.
2415 *
2416 * @stability unstable
2417 * @category protocols
2418 * @since 4.0.0
2419 */
2420export class RootsListChangedNotification extends Rpc.make("notifications/roots/list_changed", {
2421 payload: Schema.UndefinedOr(NotificationMeta)
2422}) {}
2423
2424// =============================================================================
2425// Elicitation
2426// =============================================================================
2427
2428/**
2429 * Schema for a string field in an MCP elicitation form.
2430 *
2431 * @stability unstable
2432 * @category elicitation
2433 * @since 4.0.0
2434 */
2435export class ElicitationString extends Schema.Class<ElicitationString>("@effect/ai/McpSchema/ElicitationString")({
2436 type: Schema.tag("string"),
2437 title: optional(Schema.String),
2438 description: optional(Schema.String),
2439 minLength: optional(Schema.Int),
2440 maxLength: optional(Schema.Int),
2441 format: optional(Schema.Literals(["email", "uri", "date", "date-time"])),
2442 default: optional(Schema.String)
2443}) {}
2444
2445/**
2446 * Schema for a numeric field in an MCP elicitation form.
2447 *
2448 * @stability unstable
2449 * @category elicitation
2450 * @since 4.0.0
2451 */
2452export class ElicitationNumber extends Schema.Class<ElicitationNumber>("@effect/ai/McpSchema/ElicitationNumber")({
2453 type: Schema.Literals(["number", "integer"]),
2454 title: optional(Schema.String),
2455 description: optional(Schema.String),
2456 minimum: optional(Schema.Finite),
2457 maximum: optional(Schema.Finite),
2458 default: optional(Schema.Finite)
2459}) {}
2460
2461/**
2462 * Schema for a boolean field in an MCP elicitation form.
2463 *
2464 * @stability unstable
2465 * @category elicitation
2466 * @since 4.0.0
2467 */
2468export class ElicitationBoolean extends Schema.Class<ElicitationBoolean>("@effect/ai/McpSchema/ElicitationBoolean")({
2469 type: Schema.tag("boolean"),
2470 title: optional(Schema.String),
2471 description: optional(Schema.String),
2472 default: optional(Schema.Boolean)
2473}) {}
2474
2475/**
2476 * Schema for an untitled single-select field in an MCP elicitation form.
2477 *
2478 * @stability unstable
2479 * @category elicitation
2480 * @since 4.0.0
2481 */
2482export class UntitledSingleSelectEnum extends Schema.Class<UntitledSingleSelectEnum>(
2483 "@effect/ai/McpSchema/UntitledSingleSelectEnum"
2484)({
2485 type: Schema.tag("string"),
2486 title: optional(Schema.String),
2487 description: optional(Schema.String),
2488 enum: Schema.Array(Schema.String),
2489 default: optional(Schema.String)
2490}) {}
2491
2492/**
2493 * Schema for a titled single-select field in an MCP elicitation form.
2494 *
2495 * @stability unstable
2496 * @category elicitation
2497 * @since 4.0.0
2498 */
2499export class TitledSingleSelectEnum extends Schema.Class<TitledSingleSelectEnum>(
2500 "@effect/ai/McpSchema/TitledSingleSelectEnum"
2501)({
2502 type: Schema.tag("string"),
2503 title: optional(Schema.String),
2504 description: optional(Schema.String),
2505 oneOf: Schema.Array(Schema.Struct({
2506 const: Schema.String,
2507 title: Schema.String
2508 })),
2509 default: optional(Schema.String)
2510}) {}
2511
2512/**
2513 * Schema for every single-select field in an MCP elicitation form.
2514 *
2515 * @stability unstable
2516 * @category elicitation
2517 * @since 4.0.0
2518 */
2519export const SingleSelectEnum = Schema.Union([
2520 UntitledSingleSelectEnum,
2521 TitledSingleSelectEnum
2522])
2523
2524/**
2525 * Type represented by the single-select elicitation field schema.
2526 *
2527 * @stability unstable
2528 * @category models
2529 * @since 4.0.0
2530 */
2531export type SingleSelectEnum = typeof SingleSelectEnum.Type
2532
2533/**
2534 * Schema for an untitled multi-select field in an MCP elicitation form.
2535 *
2536 * @stability unstable
2537 * @category elicitation
2538 * @since 4.0.0
2539 */
2540export class UntitledMultiSelectEnum extends Schema.Class<UntitledMultiSelectEnum>(
2541 "@effect/ai/McpSchema/UntitledMultiSelectEnum"
2542)({
2543 type: Schema.tag("array"),
2544 title: optional(Schema.String),
2545 description: optional(Schema.String),
2546 minItems: optional(Schema.Int),
2547 maxItems: optional(Schema.Int),
2548 items: Schema.Struct({
2549 type: Schema.tag("string"),
2550 enum: Schema.Array(Schema.String)
2551 }),
2552 default: optional(Schema.Array(Schema.String))
2553}) {}
2554
2555/**
2556 * Schema for a titled multi-select field in an MCP elicitation form.
2557 *
2558 * @stability unstable
2559 * @category elicitation
2560 * @since 4.0.0
2561 */
2562export class TitledMultiSelectEnum extends Schema.Class<TitledMultiSelectEnum>(
2563 "@effect/ai/McpSchema/TitledMultiSelectEnum"
2564)({
2565 type: Schema.tag("array"),
2566 title: optional(Schema.String),
2567 description: optional(Schema.String),
2568 minItems: optional(Schema.Int),
2569 maxItems: optional(Schema.Int),
2570 items: Schema.Struct({
2571 anyOf: Schema.Array(Schema.Struct({
2572 const: Schema.String,
2573 title: Schema.String
2574 }))
2575 }),
2576 default: optional(Schema.Array(Schema.String))
2577}) {}
2578
2579/**
2580 * Schema for every multi-select field in an MCP elicitation form.
2581 *
2582 * @stability unstable
2583 * @category elicitation
2584 * @since 4.0.0
2585 */
2586export const MultiSelectEnum = Schema.Union([
2587 UntitledMultiSelectEnum,
2588 TitledMultiSelectEnum
2589])
2590
2591/**
2592 * Type represented by the multi-select elicitation field schema.
2593 *
2594 * @stability unstable
2595 * @category models
2596 * @since 4.0.0
2597 */
2598export type MultiSelectEnum = typeof MultiSelectEnum.Type
2599
2600/**
2601 * Schema for the legacy titled single-select elicitation field.
2602 *
2603 * @deprecated Use {@link TitledSingleSelectEnum} instead.
2604 * @stability unstable
2605 * @category elicitation
2606 * @since 4.0.0
2607 */
2608export class LegacyTitledEnum extends Schema.Class<LegacyTitledEnum>(
2609 "@effect/ai/McpSchema/LegacyTitledEnum"
2610)({
2611 type: Schema.tag("string"),
2612 title: optional(Schema.String),
2613 description: optional(Schema.String),
2614 enum: Schema.Array(Schema.String),
2615 enumNames: optional(Schema.Array(Schema.String)),
2616 default: optional(Schema.String)
2617}) {}
2618
2619/**
2620 * Schema for every enumeration field in an MCP elicitation form.
2621 *
2622 * @stability unstable
2623 * @category elicitation
2624 * @since 4.0.0
2625 */
2626export const ElicitationEnum = Schema.Union([
2627 LegacyTitledEnum,
2628 SingleSelectEnum,
2629 MultiSelectEnum
2630])
2631
2632/**
2633 * Type represented by the elicitation enumeration field schema.
2634 *
2635 * @stability unstable
2636 * @category models
2637 * @since 4.0.0
2638 */
2639export type ElicitationEnum = typeof ElicitationEnum.Type
2640
2641/**
2642 * Schema for primitive field definitions accepted by MCP elicitation forms.
2643 *
2644 * @stability unstable
2645 * @category elicitation
2646 * @since 4.0.0
2647 */
2648export const PrimitiveSchemaDefinition = Schema.Union([
2649 ElicitationEnum,
2650 ElicitationString,
2651 ElicitationNumber,
2652 ElicitationBoolean
2653])
2654
2655/**
2656 * Type represented by the primitive elicitation field schema.
2657 *
2658 * @stability unstable
2659 * @category models
2660 * @since 4.0.0
2661 */
2662export type PrimitiveSchemaDefinition = typeof PrimitiveSchemaDefinition.Type
2663
2664const ElicitationForm = Schema.Struct({
2665 $schema: optional(Schema.String),
2666 type: Schema.tag("object"),
2667 properties: Schema.Record(Schema.String, PrimitiveSchemaDefinition),
2668 required: optional(Schema.Array(Schema.String))
2669})
2670
2671/**
2672 * Schema for form-mode MCP elicitation requests.
2673 *
2674 * @stability unstable
2675 * @category elicitation
2676 * @since 4.0.0
2677 */
2678export class ElicitRequestFormParams extends Schema.Class<ElicitRequestFormParams>(
2679 "@effect/ai/McpSchema/ElicitRequestFormParams"
2680)({
2681 ...RequestMeta.fields,
2682 mode: optional(Schema.Literal("form")),
2683 message: Schema.String,
2684 requestedSchema: ElicitationForm
2685}) {}
2686
2687/**
2688 * Schema for URL-mode MCP elicitation requests.
2689 *
2690 * @stability unstable
2691 * @category elicitation
2692 * @since 4.0.0
2693 */
2694export class ElicitRequestURLParams extends Schema.Class<ElicitRequestURLParams>(
2695 "@effect/ai/McpSchema/ElicitRequestURLParams"
2696)({
2697 ...RequestMeta.fields,
2698 mode: Schema.Literal("url"),
2699 message: Schema.String,
2700 elicitationId: Schema.String,
2701 url: Schema.String
2702}) {}
2703
2704/**
2705 * Schema for every MCP elicitation request mode.
2706 *
2707 * @stability unstable
2708 * @category elicitation
2709 * @since 4.0.0
2710 */
2711export const ElicitRequestParams = Schema.Union([
2712 ElicitRequestFormParams,
2713 ElicitRequestURLParams
2714])
2715
2716/**
2717 * Type represented by the MCP elicitation request parameters schema.
2718 *
2719 * @stability unstable
2720 * @category models
2721 * @since 4.0.0
2722 */
2723export type ElicitRequestParams = typeof ElicitRequestParams.Type
2724
2725/**
2726 * Schema for an accepted client response to an elicitation request.
2727 *
2728 * @stability unstable
2729 * @category schemas
2730 * @since 4.0.0
2731 */
2732export class ElicitAcceptResult extends Schema.Class<ElicitAcceptResult>(
2733 "@effect/ai/McpSchema/ElicitAcceptResult"
2734)({
2735 ...ResultMeta.fields,
2736 /**
2737 * The user action in response to the elicitation.
2738 * - "accept": User submitted the form/confirmed the action
2739 * - "decline": User explicitly declined the action
2740 * - "cancel": User dismissed without making an explicit choice
2741 */
2742 action: Schema.Literal("accept"),
2743 /**
2744 * The submitted form data, only present when action is "accept".
2745 * Contains values matching the requested schema.
2746 */
2747 content: optional(Schema.Record(
2748 Schema.String,
2749 Schema.Union([Schema.String, Schema.Finite, Schema.Boolean, Schema.Array(Schema.String)])
2750 ))
2751}) {}
2752
2753/**
2754 * Schema for a declined or canceled client response to an elicitation request.
2755 *
2756 * @stability unstable
2757 * @category schemas
2758 * @since 4.0.0
2759 */
2760export class ElicitDeclineResult extends Schema.Class<ElicitDeclineResult>(
2761 "@effect/ai/McpSchema/ElicitDeclineResult"
2762)({
2763 ...ResultMeta.fields,
2764 /**
2765 * The user action in response to the elicitation.
2766 * - "accept": User submitted the form/confirmed the action
2767 * - "decline": User explicitly declined the action
2768 * - "cancel": User dismissed without making an explicit choice
2769 */
2770 action: Schema.Literals(["cancel", "decline"])
2771}) {}
2772
2773/**
2774 * Schema for every client response to an elicitation request.
2775 *
2776 * @stability unstable
2777 * @category schemas
2778 * @since 4.0.0
2779 */
2780export const ElicitResult = Schema.Union([
2781 ElicitAcceptResult,
2782 ElicitDeclineResult
2783])
2784
2785/**
2786 * Type represented by the MCP elicitation result schema.
2787 *
2788 * @stability unstable
2789 * @category models
2790 * @since 4.0.0
2791 */
2792export type ElicitResult = typeof ElicitResult.Type
2793
2794/**
2795 * Version-neutral request for additional MCP client input.
2796 *
2797 * @stability unstable
2798 * @category models
2799 * @since 4.0.0
2800 */
2801export type McpInputRequest =
2802 | { readonly method: "roots/list"; readonly params?: Schema.JsonObject | undefined }
2803 | { readonly method: "sampling/createMessage"; readonly params: Schema.JsonObject }
2804 | { readonly method: "elicitation/create"; readonly params: Schema.JsonObject }
2805
2806/**
2807 * Version-neutral response supplied by an MCP client for a prior input request.
2808 *
2809 * @stability unstable
2810 * @category models
2811 * @since 4.0.0
2812 */
2813export type McpInputResponse = Schema.JsonObject
2814
2815/**
2816 * Indicates that an MCP operation requires additional keyed input from the client.
2817 *
2818 * **When to use**
2819 *
2820 * Use when a handler cannot complete until the client supplies roots, sampling,
2821 * or elicitation input in a later request.
2822 *
2823 * **Details**
2824 *
2825 * `requestState` is opaque to the client and is returned unchanged with the
2826 * keyed input responses.
2827 *
2828 * @stability unstable
2829 * @category models
2830 * @since 4.0.0
2831 */
2832export class InputRequired extends Data.TaggedClass("InputRequired")<{
2833 readonly inputRequests?: Readonly<Record<string, McpInputRequest>> | undefined
2834 readonly requestState?: string | undefined
2835}> {
2836 // The overload preserves the requirement that at least one of inputRequests or requestState is present.
2837 // oxlint-disable-next-line no-useless-constructor
2838 constructor(
2839 fields:
2840 | {
2841 readonly inputRequests: Readonly<Record<string, McpInputRequest>>
2842 readonly requestState?: string | undefined
2843 }
2844 | {
2845 readonly inputRequests?: Readonly<Record<string, McpInputRequest>> | undefined
2846 readonly requestState: string
2847 }
2848 ) {
2849 super(fields)
2850 }
2851}
2852
2853/**
2854 * Sent from the server asking the client to collect structured input from the
2855 * user.
2856 *
2857 * **Details**
2858 *
2859 * The client responds with accepted content, an explicit decline, or a
2860 * cancellation.
2861 *
2862 * @stability unstable
2863 * @category protocols
2864 * @since 4.0.0
2865 */
2866export class Elicit extends Rpc.make("elicitation/create", {
2867 success: ElicitResult,
2868 error: McpError,
2869 payload: ElicitRequestParams
2870}) {}
2871
2872/**
2873 * Notifies a client that a URL-mode elicitation completed.
2874 *
2875 * @stability unstable
2876 * @category elicitation
2877 * @since 4.0.0
2878 */
2879export class ElicitationCompleteNotification extends Rpc.make("notifications/elicitation/complete", {
2880 payload: {
2881 elicitationId: Schema.String
2882 }
2883}) {}
2884
2885/**
2886 * Error raised when an MCP elicitation request is declined or fails before
2887 * accepted content is returned.
2888 *
2889 * **Details**
2890 *
2891 * The error stores the original elicitation request and, when available, the
2892 * underlying cause.
2893 *
2894 * @stability unstable
2895 * @category schemas
2896 * @since 4.0.0
2897 */
2898export class ElicitationDeclined extends Schema.Error<ElicitationDeclined>("@effect/ai/McpSchema/ElicitationDeclined")({
2899 _tag: Schema.tag("ElicitationDeclined"),
2900 request: Elicit.payloadSchema,
2901 cause: optional(Schema.Defect())
2902}) {}
2903
2904// =============================================================================
2905// McpServerClient
2906// =============================================================================
2907
2908/**
2909 * Raised when the negotiated MCP revision or client capabilities do not
2910 * support a server-initiated operation.
2911 *
2912 * @stability unstable
2913 * @category errors
2914 * @since 4.0.0
2915 */
2916export class McpReverseOperationUnsupported extends Data.TaggedError("McpReverseOperationUnsupported")<{
2917 readonly operation: "roots/list" | "sampling/createMessage" | "elicitation/create"
2918 readonly protocolVersion: ProtocolVersion
2919 readonly reason: string
2920}> {}
2921
2922/**
2923 * A reverse MCP operation failed while being sent or projected through a
2924 * version adapter.
2925 *
2926 * @stability unstable
2927 * @category errors
2928 * @since 4.0.0
2929 */
2930export class McpReverseOperationError extends Data.TaggedError("McpReverseOperationError")<{
2931 readonly operation: "roots/list" | "sampling/createMessage" | "elicitation/create"
2932 readonly cause: unknown
2933}> {}
2934
2935/**
2936 * Version-neutral operations that an MCP server may request from its client.
2937 *
2938 * @stability unstable
2939 * @category client
2940 * @since 4.0.0
2941 */
2942export interface McpReverseClient {
2943 readonly listRoots: (
2944 request?: typeof ListRoots.payloadSchema.Type
2945 ) => Effect.Effect<ListRootsResult, McpReverseOperationError | McpReverseOperationUnsupported>
2946 readonly createMessage: (
2947 request: typeof CreateMessage.payloadSchema.Type
2948 ) => Effect.Effect<CreateMessageResult, McpReverseOperationError | McpReverseOperationUnsupported>
2949 readonly elicit: (
2950 request: typeof Elicit.payloadSchema.Type
2951 ) => Effect.Effect<ElicitResult, McpReverseOperationError | McpReverseOperationUnsupported>
2952}
2953
2954/**
2955 * Protocol-neutral context available while handling an MCP request.
2956 *
2957 * **Details**
2958 *
2959 * Unlike `McpServerClient`, this service does not imply an initialized session
2960 * or support for server-initiated requests.
2961 *
2962 * @stability unstable
2963 * @category services
2964 * @since 4.0.0
2965 */
2966export class McpRequestContext extends Context.Service<McpRequestContext, {
2967 readonly clientId: number
2968 readonly protocolVersion: string
2969 readonly clientCapabilities: ClientCapabilities
2970 readonly clientInfo?: Implementation | undefined
2971 readonly requestMetadata?:
2972 | NonNullable<typeof Initialize.payloadSchema.Type["_meta"]>
2973 | Schema.JsonObject
2974 | undefined
2975 readonly inputResponses?: Readonly<Record<string, McpInputResponse>> | undefined
2976 readonly requestState?: string | undefined
2977}>()("effect/ai/McpSchema/McpRequestContext") {}
2978
2979/**
2980 * Service available while handling an MCP client request.
2981 *
2982 * **Details**
2983 *
2984 * It exposes the current client id, normalized initialization data, and a
2985 * scoped version-neutral facade for server-initiated requests.
2986 *
2987 * @stability unstable
2988 * @category services
2989 * @since 4.0.0
2990 */
2991export class McpServerClient extends Context.Service<McpServerClient, {
2992 readonly clientId: number
2993 readonly protocolVersion: StatefulProtocolVersion
2994 readonly clientCapabilities: ClientCapabilities
2995 readonly clientInfo: Implementation
2996 readonly initializePayload: typeof Initialize.payloadSchema["Type"]
2997 readonly requestMetadata?: Schema.JsonObject | undefined
2998 readonly getClient: Effect.Effect<
2999 McpReverseClient,
3000 never,
3001 Scope.Scope
3002 >
3003}>()("effect/ai/McpSchema/McpServerClient") {}
3004
3005/**
3006 * RPC middleware that provides `McpServerClient` to handlers for initialized
3007 * MCP clients.
3008 *
3009 * @stability unstable
3010 * @category middleware
3011 * @since 4.0.0
3012 */
3013export class McpServerClientMiddleware extends RpcMiddleware.Service<McpServerClientMiddleware, {
3014 provides: McpServerClient
3015}>()("effect/ai/McpSchema/McpServerClientMiddleware") {}
3016
3017// =============================================================================
3018// Protocol
3019// =============================================================================
3020
3021/**
3022 * Encoded JSON-RPC request message for an RPC in `Group`, including the request
3023 * id, method, and encoded payload.
3024 *
3025 * @stability unstable
3026 * @category protocols
3027 * @since 4.0.0
3028 */
3029export type RequestEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
3030 Group
3031> extends infer Rpc ? Rpc extends Rpc.Rpc<
3032 infer _Tag,
3033 infer _Payload,
3034 infer _Success,
3035 infer _Error,
3036 infer _Middleware
3037 > ? {
3038 readonly _tag: "Request"
3039 readonly id: string | number
3040 readonly method: _Tag
3041 readonly payload: _Payload["Encoded"]
3042 }
3043 : never
3044 : never
3045
3046/**
3047 * Encoded notification message for an RPC in `Group`, including the method and
3048 * encoded payload without a request id.
3049 *
3050 * @stability unstable
3051 * @category protocols
3052 * @since 4.0.0
3053 */
3054export type NotificationEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
3055 Group
3056> extends infer Rpc ? Rpc extends Rpc.Rpc<
3057 infer _Tag,
3058 infer _Payload,
3059 infer _Success,
3060 infer _Error,
3061 infer _Middleware
3062 > ? {
3063 readonly _tag: "Notification"
3064 readonly method: _Tag
3065 readonly payload: _Payload["Encoded"]
3066 }
3067 : never
3068 : never
3069
3070/**
3071 * Encoded success response for an RPC in `Group`, containing the original
3072 * request id and encoded result.
3073 *
3074 * @stability unstable
3075 * @category protocols
3076 * @since 4.0.0
3077 */
3078export type SuccessEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
3079 Group
3080> extends infer Rpc ? Rpc extends Rpc.Rpc<
3081 infer _Tag,
3082 infer _Payload,
3083 infer _Success,
3084 infer _Error,
3085 infer _Middleware
3086 > ? {
3087 readonly _tag: "Success"
3088 readonly id: string | number
3089 readonly result: _Success["Encoded"]
3090 }
3091 : never
3092 : never
3093
3094/**
3095 * Encoded failure response for an RPC in `Group`, containing the original
3096 * request id and encoded error.
3097 *
3098 * @stability unstable
3099 * @category protocols
3100 * @since 4.0.0
3101 */
3102export type FailureEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
3103 Group
3104> extends infer Rpc ? Rpc extends Rpc.Rpc<
3105 infer _Tag,
3106 infer _Payload,
3107 infer _Success,
3108 infer _Error,
3109 infer _Middleware
3110 > ? {
3111 readonly _tag: "Failure"
3112 readonly id: string | number
3113 readonly error: _Error["Encoded"]
3114 }
3115 : never
3116 : never
3117
3118/**
3119 * RPC group for requests that MCP clients send to the server.
3120 *
3121 * **Details**
3122 *
3123 * The group includes initialization, resource, prompt, tool, logging,
3124 * completion, and ping requests, and installs `McpServerClientMiddleware` for
3125 * handlers.
3126 *
3127 * @stability unstable
3128 * @category protocols
3129 * @since 4.0.0
3130 */
3131export class ClientRequestRpcs extends RpcGroup.make(
3132 Ping,
3133 Initialize,
3134 Complete,
3135 SetLevel,
3136 GetPrompt,
3137 ListPrompts,
3138 ListResources,
3139 ListResourceTemplates,
3140 ReadResource,
3141 Subscribe,
3142 Unsubscribe,
3143 CallTool,
3144 ListTools
3145).middleware(McpServerClientMiddleware) {}
3146
3147/**
3148 * Encoded union of all client-to-server MCP request messages.
3149 *
3150 * @stability unstable
3151 * @category protocols
3152 * @since 4.0.0
3153 */
3154export type ClientRequestEncoded = RequestEncoded<typeof ClientRequestRpcs>
3155
3156/**
3157 * RPC group for notifications that MCP clients send to the server, such as
3158 * cancellation, progress, initialization completion, and roots list changes.
3159 *
3160 * @stability unstable
3161 * @category protocols
3162 * @since 4.0.0
3163 */
3164export class ClientNotificationRpcs extends RpcGroup.make(
3165 CancelledNotification,
3166 ProgressNotification,
3167 InitializedNotification,
3168 RootsListChangedNotification
3169) {}
3170
3171/**
3172 * Encoded union of all client-to-server MCP notification messages.
3173 *
3174 * @stability unstable
3175 * @category protocols
3176 * @since 4.0.0
3177 */
3178export type ClientNotificationEncoded = NotificationEncoded<typeof ClientNotificationRpcs>
3179
3180/**
3181 * RPC group combining all client-to-server MCP requests and notifications.
3182 *
3183 * @stability unstable
3184 * @category protocols
3185 * @since 4.0.0
3186 */
3187export class ClientRpcs extends ClientRequestRpcs.merge(ClientNotificationRpcs) {}
3188
3189/**
3190 * Encoded success response sent by a client for a server-initiated request.
3191 *
3192 * @stability unstable
3193 * @category protocols
3194 * @since 4.0.0
3195 */
3196export type ClientSuccessEncoded = SuccessEncoded<typeof ServerRequestRpcs>
3197
3198/**
3199 * Encoded failure response sent by a client for a server-initiated request.
3200 *
3201 * @stability unstable
3202 * @category protocols
3203 * @since 4.0.0
3204 */
3205export type ClientFailureEncoded = FailureEncoded<typeof ServerRequestRpcs>
3206
3207/**
3208 * RPC group for requests that an MCP server can send to a client, including
3209 * ping, sampling, roots listing, and elicitation.
3210 *
3211 * @stability unstable
3212 * @category protocols
3213 * @since 4.0.0
3214 */
3215export class ServerRequestRpcs extends RpcGroup.make(
3216 Ping,
3217 CreateMessage,
3218 ListRoots,
3219 Elicit
3220) {}
3221
3222/**
3223 * Encoded union of all server-to-client MCP request messages.
3224 *
3225 * @stability unstable
3226 * @category protocols
3227 * @since 4.0.0
3228 */
3229export type ServerRequestEncoded = RequestEncoded<typeof ServerRequestRpcs>
3230
3231/**
3232 * RPC group for notifications that an MCP server can send to a client,
3233 * including cancellation, progress, logging, and list or resource update
3234 * notifications.
3235 *
3236 * @stability unstable
3237 * @category protocols
3238 * @since 4.0.0
3239 */
3240export class ServerNotificationRpcs extends RpcGroup.make(
3241 CancelledNotification,
3242 ProgressNotification,
3243 LoggingMessageNotification,
3244 ResourceUpdatedNotification,
3245 ResourceListChangedNotification,
3246 ToolListChangedNotification,
3247 PromptListChangedNotification,
3248 ElicitationCompleteNotification
3249) {}
3250
3251/**
3252 * Encoded union of all server-to-client MCP notification messages.
3253 *
3254 * @stability unstable
3255 * @category protocols
3256 * @since 4.0.0
3257 */
3258export type ServerNotificationEncoded = NotificationEncoded<typeof ServerNotificationRpcs>
3259
3260/**
3261 * Encoded success response sent by the server for a client-initiated request.
3262 *
3263 * @stability unstable
3264 * @category protocols
3265 * @since 4.0.0
3266 */
3267export type ServerSuccessEncoded = SuccessEncoded<typeof ClientRequestRpcs>
3268
3269/**
3270 * Encoded failure response sent by the server for a client-initiated request.
3271 *
3272 * @stability unstable
3273 * @category protocols
3274 * @since 4.0.0
3275 */
3276export type ServerFailureEncoded = FailureEncoded<typeof ClientRequestRpcs>
3277
3278/**
3279 * Encoded server response to a client request, either success or failure.
3280 *
3281 * @stability unstable
3282 * @category protocols
3283 * @since 4.0.0
3284 */
3285export type ServerResultEncoded = ServerSuccessEncoded | ServerFailureEncoded
3286
3287/**
3288 * Encoded MCP messages accepted from a client by the server protocol: client
3289 * requests and client notifications.
3290 *
3291 * @stability unstable
3292 * @category protocols
3293 * @since 4.0.0
3294 */
3295export type FromClientEncoded = ClientRequestEncoded | ClientNotificationEncoded
3296
3297/**
3298 * Encoded MCP messages emitted by the server protocol to a client: server
3299 * responses and server notifications.
3300 *
3301 * @stability unstable
3302 * @category protocols
3303 * @since 4.0.0
3304 */
3305export type FromServerEncoded = ServerResultEncoded | ServerNotificationEncoded
3306
3307const ParamSchemaTypeId = "~effect/ai/McpSchema/ParamSchema"
3308
3309/**
3310 * Returns `true` when a schema was created with `param` and therefore carries
3311 * a resource URI template parameter name.
3312 *
3313 * @stability unstable
3314 * @category guards
3315 * @since 4.0.0
3316 */
3317export function isParam(schema: Schema.Constraint): schema is Param<string, Schema.Top> {
3318 return Predicate.hasProperty(schema, ParamSchemaTypeId)
3319}
3320
3321/**
3322 * Schema wrapper used for resource URI template parameters.
3323 *
3324 * **Details**
3325 *
3326 * A `Param` behaves like the wrapped schema while carrying the parameter name
3327 * used for template compilation and completion lookup.
3328 *
3329 * @stability unstable
3330 * @category parameters
3331 * @since 4.0.0
3332 */
3333export interface Param<Name extends string, S extends Schema.Constraint> extends
3334 Schema.BottomLazy<
3335 S["ast"],
3336 Param<Name, S>,
3337 S["~type.parameters"],
3338 S["~type.mutability"],
3339 S["~type.optionality"],
3340 S["~type.constructor.default"],
3341 S["~encoded.mutability"],
3342 S["~encoded.optionality"]
3343 >
3344{
3345 readonly "Type": S["Type"]
3346 readonly "Encoded": S["Encoded"]
3347 readonly "DecodingServices": S["DecodingServices"]
3348 readonly "EncodingServices": S["EncodingServices"]
3349 readonly "Rebuild": Param<Name, S>
3350 readonly "~type.make.in": S["~type.make.in"]
3351 readonly "~type.make": S["~type.make"]
3352 readonly "Iso": S["Iso"]
3353 readonly [ParamSchemaTypeId]: typeof ParamSchemaTypeId
3354 readonly name: Name
3355 readonly schema: S
3356}
3357
3358/**
3359 * Creates a parameter for a resource URI template.
3360 *
3361 * @stability unstable
3362 * @category parameters
3363 * @since 4.0.0
3364 */
3365export function param<const Name extends string, S extends Schema.Constraint>(
3366 name: Name,
3367 schema: S
3368): Param<Name, S> {
3369 return Schema.make(schema.ast, { [ParamSchemaTypeId]: ParamSchemaTypeId, name, schema })
3370}
3371
3372/**
3373 * Annotation to conditionally enable or disable tools based on client
3374 * information.
3375 *
3376 * @stability unstable
3377 * @category services
3378 * @since 4.0.0
3379 */
3380export class EnabledWhen extends Context.Service<
3381 EnabledWhen,
3382 Predicate.Predicate<{
3383 readonly protocolVersion: string
3384 readonly capabilities: ClientCapabilities
3385 readonly clientInfo?: Implementation | undefined
3386 }>
3387>()(
3388 "effect/ai/McpSchema/EnabledWhen"
3389) {}