effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/unstable/ai/McpSchema.js

@@ -1,4 +1,32 @@
 /**
+ * The `McpSchema` module defines Effect Schema and RPC models for the Model
+ * Context Protocol (MCP). It provides the shared protocol vocabulary used by
+ * MCP clients and servers, including JSON-RPC request identifiers, metadata,
+ * capabilities, errors, resources, prompts, tools, logging, sampling,
+ * completions, roots, and elicitation.
+ *
+ * **Common tasks**
+ *
+ * - Describe MCP payloads with schemas such as {@link Resource}, {@link Tool},
+ *   {@link Prompt}, and {@link ContentBlock}
+ * - Build typed protocol handlers with request RPCs such as {@link Initialize},
+ *   {@link ListResources}, {@link ReadResource}, {@link ListTools}, and
+ *   {@link CallTool}
+ * - Work with protocol notifications such as
+ *   {@link ProgressNotification}, {@link ResourceUpdatedNotification}, and
+ *   {@link LoggingMessageNotification}
+ * - Use {@link ClientRpcs} and server RPC groups to derive encoded request,
+ *   notification, success, and failure message types
+ *
+ * **Gotchas**
+ *
+ * - MCP distinguishes absent fields from present fields whose value is
+ *   `undefined`; use {@link optional} and {@link optionalWithDefault} for
+ *   protocol fields so encoding omits undefined values consistently.
+ * - Capability objects are extensible. Known fields are modeled here, but
+ *   `experimental` and `extensions` allow implementations to advertise
+ *   additional protocol features.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.js";
@@ -12,6 +40,12 @@ import * as Rpc from "../rpc/Rpc.js";
 import * as RpcGroup from "../rpc/RpcGroup.js";
 import * as RpcMiddleware from "../rpc/RpcMiddleware.js";
 /**
+ * Marks a struct field as optional and supplies `defaultValue` when the field
+ * is absent.
+ *
+ * The default is used during decoding and as the constructor default for the
+ * schema field.
+ *
  * @since 4.0.0
  */
 export const optionalWithDefault = (schema, defaultValue) => {
@@ -22,6 +56,11 @@ export const optionalWithDefault = (schema, defaultValue) => {
   }), Schema.withConstructorDefault(effect));
 };
 /**
+ * Creates an optional MCP struct-field schema from a required schema.
+ *
+ * The field may be absent, and explicit `undefined` values are omitted when
+ * encoding.
+ *
  * @since 4.0.0
  */
 export const optional = schema => Schema.optionalKey(schema).pipe(Schema.decodeTo(Schema.optional(schema), {
@@ -34,21 +73,26 @@ export const optional = schema => Schema.optionalKey(schema).pipe(Schema.decodeT
 /**
  * A uniquely identifying ID for a request in JSON-RPC.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export const RequestId = /*#__PURE__*/Schema.Union([Schema.String, Schema.Number]);
 /**
  * A progress token, used to associate progress notifications with the original
  * request.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export const ProgressToken = /*#__PURE__*/Schema.Union([Schema.String, Schema.Number]);
 /**
- * @since 4.0.0
+ * Schema for optional MCP request metadata.
+ *
+ * Request metadata may include a progress token that asks the receiver to send
+ * out-of-band progress notifications for the request.
+ *
  * @category common
+ * @since 4.0.0
  */
 export class RequestMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   _meta: /*#__PURE__*/optional(/*#__PURE__*/Schema.Struct({
@@ -63,8 +107,13 @@ export class RequestMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schem
   }))
 })) {}
 /**
- * @since 4.0.0
+ * Schema for optional MCP result metadata.
+ *
+ * The `_meta` field is reserved for protocol, extension, or implementation
+ * metadata attached to a result.
+ *
  * @category common
+ * @since 4.0.0
  */
 export class ResultMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   /**
@@ -74,8 +123,13 @@ export class ResultMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema
   _meta: /*#__PURE__*/optional(/*#__PURE__*/Schema.Record(Schema.String, Schema.Json))
 })) {}
 /**
- * @since 4.0.0
+ * Schema for optional MCP notification metadata.
+ *
+ * The `_meta` field is reserved for protocol, extension, or implementation
+ * metadata attached to a notification.
+ *
  * @category common
+ * @since 4.0.0
  */
 export class NotificationMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   /**
@@ -87,13 +141,18 @@ export class NotificationMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/
 /**
  * An opaque token used to represent a cursor for pagination.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export const Cursor = Schema.String;
 /**
- * @since 4.0.0
+ * Schema for MCP request metadata used by paginated requests.
+ *
+ * It includes the base request metadata fields plus an optional cursor
+ * indicating where the server should continue listing results.
+ *
  * @category common
+ * @since 4.0.0
  */
 export class PaginatedRequestMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   ...RequestMeta.fields,
@@ -104,8 +163,13 @@ export class PaginatedRequestMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE
   cursor: /*#__PURE__*/optional(Cursor)
 })) {}
 /**
- * @since 4.0.0
+ * Schema for MCP result metadata returned by paginated operations.
+ *
+ * It includes the base result metadata fields plus an optional `nextCursor`,
+ * which indicates that more results may be available.
+ *
  * @category common
+ * @since 4.0.0
  */
 export class PaginatedResultMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   ...ResultMeta.fields,
@@ -117,16 +181,16 @@ export class PaginatedResultMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE_
 })) {}
 /**
  * The sender or recipient of messages and data in a conversation.
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export const Role = /*#__PURE__*/Schema.Literals(["user", "assistant"]);
 /**
  * Optional annotations for the client. The client can use annotations to
  * inform how objects are used or displayed
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export class Annotations extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   /**
@@ -151,8 +215,8 @@ export class Annotations extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schem
 /**
  * Describes the name and version of an MCP implementation.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export class Implementation extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   name: Schema.String,
@@ -164,8 +228,8 @@ export class Implementation extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sc
  * this schema, but this is not a closed set: any client can define its own,
  * additional capabilities.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export class ClientCapabilities extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/ClientCapabilities")({
   /**
@@ -200,8 +264,8 @@ export class ClientCapabilities extends /*#__PURE__*/Schema.Class("@effect/ai/Mc
  * here, in this schema, but this is not a closed set: any server can define
  * its own, additional capabilities.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export class ServerCapabilities extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   /**
@@ -257,8 +321,13 @@ export class ServerCapabilities extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__
 // Errors
 // =============================================================================
 /**
- * @since 4.0.0
+ * Base schema for MCP and JSON-RPC error objects.
+ *
+ * It contains the numeric error `code`, a concise `message`, and optional
+ * sender-defined `data`.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class McpErrorBase extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/McpErrorBase")({
   /**
@@ -277,33 +346,48 @@ export class McpErrorBase extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchem
   data: /*#__PURE__*/optional(Schema.Any)
 }) {}
 /**
- * @since 4.0.0
+ * JSON-RPC error code for requests that are not valid request objects.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export const INVALID_REQUEST_ERROR_CODE = -32600;
 /**
- * @since 4.0.0
+ * JSON-RPC error code for requests whose method does not exist or is not
+ * available.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export const METHOD_NOT_FOUND_ERROR_CODE = -32601;
 /**
- * @since 4.0.0
+ * JSON-RPC error code for invalid method parameters.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export const INVALID_PARAMS_ERROR_CODE = -32602;
 /**
- * @since 4.0.0
+ * JSON-RPC error code for internal server errors.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export const INTERNAL_ERROR_CODE = -32603;
 /**
- * @since 4.0.0
+ * JSON-RPC error code for invalid JSON that could not be parsed.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export const PARSE_ERROR_CODE = -32700;
 /**
- * @since 4.0.0
+ * MCP/JSON-RPC error for invalid JSON that could not be parsed.
+ *
+ * This error uses the standard parse error code `-32700`.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class ParseError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/McpSchema/ParseError")({
   ...McpErrorBase.fields,
@@ -311,8 +395,12 @@ export class ParseError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/McpSch
   code: /*#__PURE__*/Schema.tag(PARSE_ERROR_CODE)
 }) {}
 /**
- * @since 4.0.0
+ * MCP/JSON-RPC error for a request object that is not valid.
+ *
+ * This error uses the standard invalid request code `-32600`.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class InvalidRequest extends /*#__PURE__*/Schema.ErrorClass("effect/ai/McpSchema/InvalidRequest")({
   ...McpErrorBase.fields,
@@ -320,8 +408,12 @@ export class InvalidRequest extends /*#__PURE__*/Schema.ErrorClass("effect/ai/Mc
   code: /*#__PURE__*/Schema.tag(INVALID_REQUEST_ERROR_CODE)
 }) {}
 /**
- * @since 4.0.0
+ * MCP/JSON-RPC error for a method that does not exist or is not available.
+ *
+ * This error uses the standard method not found code `-32601`.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class MethodNotFound extends /*#__PURE__*/Schema.ErrorClass("effect/ai/McpSchema/MethodNotFound")({
   ...McpErrorBase.fields,
@@ -329,8 +421,12 @@ export class MethodNotFound extends /*#__PURE__*/Schema.ErrorClass("effect/ai/Mc
   code: /*#__PURE__*/Schema.tag(METHOD_NOT_FOUND_ERROR_CODE)
 }) {}
 /**
- * @since 4.0.0
+ * MCP/JSON-RPC error for invalid method parameters.
+ *
+ * This error uses the standard invalid params code `-32602`.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class InvalidParams extends /*#__PURE__*/Schema.ErrorClass("effect/ai/McpSchema/InvalidParams")({
   ...McpErrorBase.fields,
@@ -338,8 +434,13 @@ export class InvalidParams extends /*#__PURE__*/Schema.ErrorClass("effect/ai/Mcp
   code: /*#__PURE__*/Schema.tag(INVALID_PARAMS_ERROR_CODE)
 }) {}
 /**
- * @since 4.0.0
+ * MCP/JSON-RPC error for unexpected internal server failures.
+ *
+ * This error uses the standard internal error code `-32603` and includes
+ * `InternalError.notImplemented` for unimplemented handlers.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class InternalError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/McpSchema/InternalError")({
   ...McpErrorBase.fields,
@@ -351,8 +452,11 @@ export class InternalError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/Mcp
   });
 }
 /**
- * @since 4.0.0
+ * Schema for MCP protocol errors returned in JSON-RPC failure responses,
+ * including standard protocol errors and custom `McpErrorBase` values.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export const McpError = /*#__PURE__*/Schema.Union([ParseError, InvalidRequest, MethodNotFound, InvalidParams, InternalError, McpErrorBase]);
 // =============================================================================
@@ -363,8 +467,8 @@ export const McpError = /*#__PURE__*/Schema.Union([ParseError, InvalidRequest, M
  * party is still alive. The receiver must promptly respond, or else may be
  * disconnected.
  *
- * @since 4.0.0
  * @category ping
+ * @since 4.0.0
  */
 export class Ping extends /*#__PURE__*/Rpc.make("ping", {
   success: /*#__PURE__*/Schema.Struct({}),
@@ -378,8 +482,8 @@ export class Ping extends /*#__PURE__*/Rpc.make("ping", {
  * After receiving an initialize request from the client, the server sends this
  * response.
  *
- * @since 4.0.0
  * @category initialization
+ * @since 4.0.0
  */
 export class InitializeResult extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   ...ResultMeta.fields,
@@ -404,8 +508,8 @@ export class InitializeResult extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/
  * This request is sent from the client to the server when it first connects,
  * asking it to begin initialization.
  *
- * @since 4.0.0
  * @category initialization
+ * @since 4.0.0
  */
 export class Initialize extends /*#__PURE__*/Rpc.make("initialize", {
   success: InitializeResult,
@@ -433,8 +537,8 @@ export class Initialize extends /*#__PURE__*/Rpc.make("initialize", {
  * This notification is sent from the client to the server after initialization
  * has finished.
  *
- * @since 4.0.0
  * @category initialization
+ * @since 4.0.0
  */
 export class InitializedNotification extends /*#__PURE__*/Rpc.make("notifications/initialized", {
   payload: /*#__PURE__*/Schema.UndefinedOr(NotificationMeta)
@@ -443,8 +547,14 @@ export class InitializedNotification extends /*#__PURE__*/Rpc.make("notification
 // Cancellation
 // =============================================================================
 /**
- * @since 4.0.0
+ * Notification sent by either peer to cancel a previously issued request in
+ * the same direction.
+ *
+ * The payload identifies the request to cancel and may include a
+ * human-readable reason.
+ *
  * @category cancellation
+ * @since 4.0.0
  */
 export class CancelledNotification extends /*#__PURE__*/Rpc.make("notifications/cancelled", {
   payload: {
@@ -470,8 +580,8 @@ export class CancelledNotification extends /*#__PURE__*/Rpc.make("notifications/
  * An out-of-band notification used to inform the receiver of a progress update
  * for a long-running request.
  *
- * @since 4.0.0
  * @category progress
+ * @since 4.0.0
  */
 export class ProgressNotification extends /*#__PURE__*/Rpc.make("notifications/progress", {
   payload: {
@@ -502,8 +612,8 @@ export class ProgressNotification extends /*#__PURE__*/Rpc.make("notifications/p
 /**
  * A known resource that the server is capable of reading.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class Resource extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Resource")({
   /**
@@ -551,8 +661,8 @@ export class Resource extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Re
 /**
  * A template description for resources available on the server.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class ResourceTemplate extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/ResourceTemplate")({
   /**
@@ -591,8 +701,8 @@ export class ResourceTemplate extends /*#__PURE__*/Schema.Class("@effect/ai/McpS
 /**
  * The contents of a specific resource or sub-resource.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class ResourceContents extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   /**
@@ -611,8 +721,8 @@ export class ResourceContents extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/
 /**
  * The contents of a text resource, which can be represented as a string.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class TextResourceContents extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   ...ResourceContents.fields,
@@ -625,8 +735,8 @@ export class TextResourceContents extends /*#__PURE__*/Schema.Opaque()(/*#__PURE
 /**
  * The contents of a binary resource, which can be represented as an Uint8Array
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class BlobResourceContents extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   ...ResourceContents.fields,
@@ -638,8 +748,8 @@ export class BlobResourceContents extends /*#__PURE__*/Schema.Opaque()(/*#__PURE
 /**
  * The server's response to a resources/list request from the client.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class ListResourcesResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/ListResourcesResult")({
   ...PaginatedResultMeta.fields,
@@ -648,8 +758,8 @@ export class ListResourcesResult extends /*#__PURE__*/Schema.Class("@effect/ai/M
 /**
  * Sent from the client to request a list of resources the server has.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class ListResources extends /*#__PURE__*/Rpc.make("resources/list", {
   success: ListResourcesResult,
@@ -659,8 +769,8 @@ export class ListResources extends /*#__PURE__*/Rpc.make("resources/list", {
 /**
  * The server's response to a resources/templates/list request from the client.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class ListResourceTemplatesResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/ListResourceTemplatesResult")({
   ...PaginatedResultMeta.fields,
@@ -669,8 +779,8 @@ export class ListResourceTemplatesResult extends /*#__PURE__*/Schema.Class("@eff
 /**
  * Sent from the client to request a list of resource templates the server has.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class ListResourceTemplates extends /*#__PURE__*/Rpc.make("resources/templates/list", {
   success: ListResourceTemplatesResult,
@@ -680,8 +790,8 @@ export class ListResourceTemplates extends /*#__PURE__*/Rpc.make("resources/temp
 /**
  * The server's response to a resources/read request from the client.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class ReadResourceResult extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   ...ResultMeta.fields,
@@ -690,8 +800,8 @@ export class ReadResourceResult extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__
 /**
  * Sent from the client to the server, to read a specific resource URI.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class ReadResource extends /*#__PURE__*/Rpc.make("resources/read", {
   success: ReadResourceResult,
@@ -710,8 +820,8 @@ export class ReadResource extends /*#__PURE__*/Rpc.make("resources/read", {
  * list of resources it can read from has changed. This may be issued by servers
  * without any previous subscription from the client.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class ResourceListChangedNotification extends /*#__PURE__*/Rpc.make("notifications/resources/list_changed", {
   payload: /*#__PURE__*/Schema.UndefinedOr(NotificationMeta)
@@ -720,8 +830,8 @@ export class ResourceListChangedNotification extends /*#__PURE__*/Rpc.make("noti
  * Sent from the client to request resources/updated notifications from the
  * server whenever a particular resource changes.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class Subscribe extends /*#__PURE__*/Rpc.make("resources/subscribe", {
   error: McpError,
@@ -739,8 +849,8 @@ export class Subscribe extends /*#__PURE__*/Rpc.make("resources/subscribe", {
  * notifications from the server. This should follow a previous
  * resources/subscribe request.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export class Unsubscribe extends /*#__PURE__*/Rpc.make("resources/unsubscribe", {
   error: McpError,
@@ -754,8 +864,13 @@ export class Unsubscribe extends /*#__PURE__*/Rpc.make("resources/unsubscribe",
   }
 }) {}
 /**
- * @since 4.0.0
+ * Notification sent by the server when a subscribed resource URI has changed.
+ *
+ * The URI may identify a sub-resource of the resource that the client
+ * originally subscribed to.
+ *
  * @category resources
+ * @since 4.0.0
  */
 export class ResourceUpdatedNotification extends /*#__PURE__*/Rpc.make("notifications/resources/updated", {
   payload: {
@@ -772,8 +887,8 @@ export class ResourceUpdatedNotification extends /*#__PURE__*/Rpc.make("notifica
 /**
  * Describes an argument that a prompt can accept.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class PromptArgument extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   /**
@@ -793,8 +908,8 @@ export class PromptArgument extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sc
 /**
  * A prompt or prompt template that the server offers.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class Prompt extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Prompt")({
   /**
@@ -814,8 +929,8 @@ export class Prompt extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Prom
 /**
  * Text provided to or from an LLM.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class TextContent extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   type: /*#__PURE__*/Schema.tag("text"),
@@ -831,8 +946,8 @@ export class TextContent extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schem
 /**
  * An image provided to or from an LLM.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class ImageContent extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   type: /*#__PURE__*/Schema.tag("image"),
@@ -853,8 +968,8 @@ export class ImageContent extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sche
 /**
  * Audio provided to or from an LLM.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class AudioContent extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   type: /*#__PURE__*/Schema.tag("audio"),
@@ -878,8 +993,8 @@ export class AudioContent extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sche
  * It is up to the client how best to render embedded resources for the benefit
  * of the LLM and/or the user.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class EmbeddedResource extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   type: /*#__PURE__*/Schema.tag("resource"),
@@ -894,16 +1009,19 @@ export class EmbeddedResource extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/
  *
  * Note: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class ResourceLink extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   ...Resource.fields,
   type: /*#__PURE__*/Schema.tag("resource_link")
 })) {}
 /**
- * @since 4.0.0
+ * Union of MCP content blocks that can appear in prompt messages or tool
+ * results, including text, media, embedded resources, and resource links.
+ *
  * @category prompts
+ * @since 4.0.0
  */
 export const ContentBlock = /*#__PURE__*/Schema.Union([TextContent, ImageContent, AudioContent, EmbeddedResource, ResourceLink]);
 /**
@@ -912,8 +1030,8 @@ export const ContentBlock = /*#__PURE__*/Schema.Union([TextContent, ImageContent
  * This is similar to `SamplingMessage`, but also supports the embedding of
  * resources from the MCP server.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class PromptMessage extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   role: Role,
@@ -922,8 +1040,8 @@ export class PromptMessage extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sch
 /**
  * The server's response to a prompts/list request from the client.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class ListPromptsResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/ListPromptsResult")({
   ...PaginatedResultMeta.fields,
@@ -933,8 +1051,8 @@ export class ListPromptsResult extends /*#__PURE__*/Schema.Class("@effect/ai/Mcp
  * Sent from the client to request a list of prompts and prompt templates the
  * server has.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class ListPrompts extends /*#__PURE__*/Rpc.make("prompts/list", {
   success: ListPromptsResult,
@@ -944,8 +1062,8 @@ export class ListPrompts extends /*#__PURE__*/Rpc.make("prompts/list", {
 /**
  * The server's response to a prompts/get request from the client.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class GetPromptResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/GetPromptResult")({
   ...ResultMeta.fields,
@@ -958,8 +1076,8 @@ export class GetPromptResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSc
 /**
  * Used by the client to get a prompt provided by the server.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class GetPrompt extends /*#__PURE__*/Rpc.make("prompts/get", {
   success: GetPromptResult,
@@ -982,8 +1100,8 @@ export class GetPrompt extends /*#__PURE__*/Rpc.make("prompts/get", {
  * the list of prompts it offers has changed. This may be issued by servers
  * without any previous subscription from the client.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export class PromptListChangedNotification extends /*#__PURE__*/Rpc.make("notifications/prompts/list_changed", {
   payload: /*#__PURE__*/Schema.UndefinedOr(NotificationMeta)
@@ -1001,8 +1119,8 @@ export class PromptListChangedNotification extends /*#__PURE__*/Rpc.make("notifi
  * Clients should never make tool use decisions based on ToolAnnotations
  * received from untrusted servers.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export class ToolAnnotations extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   /**
@@ -1046,8 +1164,8 @@ export class ToolAnnotations extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/S
 /**
  * Definition for a tool the client can call.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export class Tool extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Tool")({
   /**
@@ -1080,8 +1198,8 @@ export class Tool extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Tool")
 /**
  * The server's response to a tools/list request from the client.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export class ListToolsResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/ListToolsResult")({
   ...PaginatedResultMeta.fields,
@@ -1090,8 +1208,8 @@ export class ListToolsResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSc
 /**
  * Sent from the client to request a list of tools the server has.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export class ListTools extends /*#__PURE__*/Rpc.make("tools/list", {
   success: ListToolsResult,
@@ -1110,8 +1228,8 @@ export class ListTools extends /*#__PURE__*/Rpc.make("tools/list", {
  * server does not support tool calls, or any other exceptional conditions,
  * should be reported as an MCP error response.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export class CallToolResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/CallToolResult")({
   ...ResultMeta.fields,
@@ -1127,8 +1245,8 @@ export class CallToolResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSch
 /**
  * Used by the client to invoke a tool provided by the server.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export class CallTool extends /*#__PURE__*/Rpc.make("tools/call", {
   success: CallToolResult,
@@ -1144,8 +1262,8 @@ export class CallTool extends /*#__PURE__*/Rpc.make("tools/call", {
  * the list of tools it offers has changed. This may be issued by servers
  * without any previous subscription from the client.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export class ToolListChangedNotification extends /*#__PURE__*/Rpc.make("notifications/tools/list_changed", {
   payload: /*#__PURE__*/Schema.UndefinedOr(NotificationMeta)
@@ -1159,15 +1277,15 @@ export class ToolListChangedNotification extends /*#__PURE__*/Rpc.make("notifica
  * These map to syslog message severities, as specified in RFC-5424:
  * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
  *
- * @since 4.0.0
  * @category logging
+ * @since 4.0.0
  */
 export const LoggingLevel = /*#__PURE__*/Schema.Literals(["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"]);
 /**
  * A request from the client to the server, to enable or adjust logging.
  *
- * @since 4.0.0
  * @category logging
+ * @since 4.0.0
  */
 export class SetLevel extends /*#__PURE__*/Rpc.make("logging/setLevel", {
   payload: {
@@ -1182,8 +1300,13 @@ export class SetLevel extends /*#__PURE__*/Rpc.make("logging/setLevel", {
   error: McpError
 }) {}
 /**
- * @since 4.0.0
+ * Server notification carrying a log message for the client.
+ *
+ * The notification includes the severity level, optional logger name, and
+ * JSON-serializable log data.
+ *
  * @category logging
+ * @since 4.0.0
  */
 export class LoggingMessageNotification extends /*#__PURE__*/Rpc.make("notifications/message", {
   payload: /*#__PURE__*/Schema.Struct({
@@ -1209,8 +1332,8 @@ export class LoggingMessageNotification extends /*#__PURE__*/Rpc.make("notificat
 /**
  * Describes a message issued to or received from an LLM API.
  *
- * @since 4.0.0
  * @category sampling
+ * @since 4.0.0
  */
 export class SamplingMessage extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   role: Role,
@@ -1222,8 +1345,8 @@ export class SamplingMessage extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/S
  * Keys not declared here are currently left unspecified by the spec and are up
  * to the client to interpret.
  *
- * @since 4.0.0
  * @category sampling
+ * @since 4.0.0
  */
 export class ModelHint extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   /**
@@ -1253,8 +1376,8 @@ export class ModelHint extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.
  * up to the client to decide how to interpret these preferences and how to
  * balance them against other considerations.
  *
- * @since 4.0.0
  * @category sampling
+ * @since 4.0.0
  */
 export class ModelPreferences extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/ModelPreferences")({
   /**
@@ -1301,8 +1424,8 @@ export class ModelPreferences extends /*#__PURE__*/Schema.Class("@effect/ai/McpS
  * allow them to inspect the response (human in the loop) and decide whether to
  * allow the server to see it.
  *
- * @since 4.0.0
  * @category sampling
+ * @since 4.0.0
  */
 export class CreateMessageResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/CreateMessageResult")({
   /**
@@ -1320,8 +1443,8 @@ export class CreateMessageResult extends /*#__PURE__*/Schema.Class("@effect/ai/M
  * user before beginning sampling, to allow them to inspect the request (human
  * in the loop) and decide whether to approve it.
  *
- * @since 4.0.0
  * @category sampling
+ * @since 4.0.0
  */
 export class CreateMessage extends /*#__PURE__*/Rpc.make("sampling/createMessage", {
   success: CreateMessageResult,
@@ -1363,8 +1486,8 @@ export class CreateMessage extends /*#__PURE__*/Rpc.make("sampling/createMessage
 /**
  * A reference to a resource or resource template definition.
  *
- * @since 4.0.0
  * @category autocomplete
+ * @since 4.0.0
  */
 export class ResourceReference extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   type: /*#__PURE__*/Schema.tag("ref/resource"),
@@ -1376,8 +1499,8 @@ export class ResourceReference extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*
 /**
  * Identifies a prompt.
  *
- * @since 4.0.0
  * @category autocomplete
+ * @since 4.0.0
  */
 export class PromptReference extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   type: /*#__PURE__*/Schema.tag("ref/prompt"),
@@ -1390,8 +1513,8 @@ export class PromptReference extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/S
 /**
  * The server's response to a completion/complete request
  *
- * @since 4.0.0
  * @category autocomplete
+ * @since 4.0.0
  */
 export class CompleteResult extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
   completion: /*#__PURE__*/Schema.Struct({
@@ -1412,6 +1535,8 @@ export class CompleteResult extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sc
   })
 })) {
   /**
+   * Empty completion result used when a completion request has no values.
+   *
    * @since 4.0.0
    */
   static empty = /*#__PURE__*/CompleteResult.make({
@@ -1425,8 +1550,8 @@ export class CompleteResult extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sc
 /**
  * A request from the client to the server, to ask for completion options.
  *
- * @since 4.0.0
  * @category autocomplete
+ * @since 4.0.0
  */
 export class Complete extends /*#__PURE__*/Rpc.make("completion/complete", {
   success: CompleteResult,
@@ -1465,8 +1590,8 @@ export class Complete extends /*#__PURE__*/Rpc.make("completion/complete", {
 /**
  * Represents a root directory or file that the server can operate on.
  *
- * @since 4.0.0
  * @category roots
+ * @since 4.0.0
  */
 export class Root extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Root")({
   /**
@@ -1487,8 +1612,8 @@ export class Root extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Root")
  * contains an array of Root objects, each representing a root directory or file
  * that the server can operate on.
  *
- * @since 4.0.0
  * @category roots
+ * @since 4.0.0
  */
 export class ListRootsResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/ListRootsResult")({
   roots: /*#__PURE__*/Schema.Array(Root)
@@ -1504,8 +1629,8 @@ export class ListRootsResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSc
  * system structure or access specific locations that the client has permission
  * to read from.
  *
- * @since 4.0.0
  * @category roots
+ * @since 4.0.0
  */
 export class ListRoots extends /*#__PURE__*/Rpc.make("roots/list", {
   success: ListRootsResult,
@@ -1518,8 +1643,8 @@ export class ListRoots extends /*#__PURE__*/Rpc.make("roots/list", {
  * removes, or modifies any root. The server should then request an updated list
  * of roots using the ListRootsRequest.
  *
- * @since 4.0.0
  * @category roots
+ * @since 4.0.0
  */
 export class RootsListChangedNotification extends /*#__PURE__*/Rpc.make("notifications/roots/list_changed", {
   payload: /*#__PURE__*/Schema.UndefinedOr(NotificationMeta)
@@ -1530,8 +1655,8 @@ export class RootsListChangedNotification extends /*#__PURE__*/Rpc.make("notific
 /**
  * The client's response to an elicitation request
  *
- * @since 4.0.0
  * @category elicitation
+ * @since 4.0.0
  */
 export class ElicitAcceptResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/ElicitAcceptResult")({
   ...ResultMeta.fields,
@@ -1551,8 +1676,8 @@ export class ElicitAcceptResult extends /*#__PURE__*/Schema.Class("@effect/ai/Mc
 /**
  * The client's response to an elicitation request
  *
- * @since 4.0.0
  * @category elicitation
+ * @since 4.0.0
  */
 export class ElicitDeclineResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/ElicitDeclineResult")({
   ...ResultMeta.fields,
@@ -1567,13 +1692,19 @@ export class ElicitDeclineResult extends /*#__PURE__*/Schema.Class("@effect/ai/M
 /**
  * The client's response to an elicitation request
  *
- * @since 4.0.0
  * @category elicitation
+ * @since 4.0.0
  */
 export const ElicitResult = /*#__PURE__*/Schema.Union([ElicitAcceptResult, ElicitDeclineResult]);
 /**
- * @since 4.0.0
+ * Request sent by the server asking the client to collect structured input
+ * from the user.
+ *
+ * The client responds with accepted content, an explicit decline, or a
+ * cancellation.
+ *
  * @category elicitation
+ * @since 4.0.0
  */
 export class Elicit extends /*#__PURE__*/Rpc.make("elicitation/create", {
   success: ElicitResult,
@@ -1592,8 +1723,14 @@ export class Elicit extends /*#__PURE__*/Rpc.make("elicitation/create", {
   }
 }) {}
 /**
- * @since 4.0.0
+ * Error raised when an MCP elicitation request is declined or fails before
+ * accepted content is returned.
+ *
+ * The error stores the original elicitation request and, when available, the
+ * underlying cause.
+ *
  * @category elicitation
+ * @since 4.0.0
  */
 export class ElicitationDeclined extends /*#__PURE__*/Schema.ErrorClass("@effect/ai/McpSchema/ElicitationDeclined")({
   _tag: /*#__PURE__*/Schema.tag("ElicitationDeclined"),
@@ -1604,44 +1741,73 @@ export class ElicitationDeclined extends /*#__PURE__*/Schema.ErrorClass("@effect
 // McpServerClient
 // =============================================================================
 /**
- * @since 4.0.0
+ * Service available while handling an MCP client request.
+ *
+ * It exposes the current client id, the client's initialize payload, and a
+ * scoped RPC client for server-initiated requests back to that client.
+ *
  * @category client
+ * @since 4.0.0
  */
 export class McpServerClient extends /*#__PURE__*/Context.Service()("effect/ai/McpSchema/McpServerClient") {}
 /**
- * @since 4.0.0
+ * RPC middleware that provides `McpServerClient` to handlers for initialized
+ * MCP clients.
+ *
  * @category middleware
+ * @since 4.0.0
  */
 export class McpServerClientMiddleware extends /*#__PURE__*/RpcMiddleware.Service()("effect/ai/McpSchema/McpServerClientMiddleware") {}
 /**
- * @since 4.0.0
+ * RPC group for requests that MCP clients send to the server.
+ *
+ * The group includes initialization, resource, prompt, tool, logging,
+ * completion, and ping requests, and installs `McpServerClientMiddleware` for
+ * handlers.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class ClientRequestRpcs extends /*#__PURE__*/RpcGroup.make(Ping, Initialize, Complete, SetLevel, GetPrompt, ListPrompts, ListResources, ListResourceTemplates, ReadResource, Subscribe, Unsubscribe, CallTool, ListTools).middleware(McpServerClientMiddleware) {}
 /**
- * @since 4.0.0
+ * RPC group for notifications that MCP clients send to the server, such as
+ * cancellation, progress, initialization completion, and roots list changes.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class ClientNotificationRpcs extends /*#__PURE__*/RpcGroup.make(CancelledNotification, ProgressNotification, InitializedNotification, RootsListChangedNotification) {}
 /**
- * @since 4.0.0
+ * RPC group combining all client-to-server MCP requests and notifications.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class ClientRpcs extends /*#__PURE__*/ClientRequestRpcs.merge(ClientNotificationRpcs) {}
 /**
- * @since 4.0.0
+ * RPC group for requests that an MCP server can send to a client, including
+ * ping, sampling, roots listing, and elicitation.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class ServerRequestRpcs extends /*#__PURE__*/RpcGroup.make(Ping, CreateMessage, ListRoots, Elicit) {}
 /**
- * @since 4.0.0
+ * RPC group for notifications that an MCP server can send to a client,
+ * including cancellation, progress, logging, and list or resource update
+ * notifications.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class ServerNotificationRpcs extends /*#__PURE__*/RpcGroup.make(CancelledNotification, ProgressNotification, LoggingMessageNotification, ResourceUpdatedNotification, ResourceListChangedNotification, ToolListChangedNotification, PromptListChangedNotification) {}
 const ParamSchemaTypeId = "~effect/ai/McpSchema/ParamSchema";
 /**
- * @since 4.0.0
+ * Returns `true` when a schema was created with `param` and therefore carries
+ * a resource URI template parameter name.
+ *
  * @category parameters
+ * @since 4.0.0
  */
 export function isParam(schema) {
   return Predicate.hasProperty(schema, ParamSchemaTypeId);
@@ -1649,8 +1815,8 @@ export function isParam(schema) {
 /**
  * Helper to create a param for a resource URI template.
  *
- * @since 4.0.0
  * @category parameters
+ * @since 4.0.0
  */
 export function param(name, schema) {
   return Schema.make(schema.ast, {
@@ -1663,8 +1829,8 @@ export function param(name, schema) {
  * Annotation to conditionally enable or disable tools based on client
  * information.
  *
- * @since 4.0.0
  * @category annotations
+ * @since 4.0.0
  */
 export class EnabledWhen extends /*#__PURE__*/Context.Service()("effect/unstable/ai/McpSchema/EnabledWhen") {}
 //# sourceMappingURL=McpSchema.js.map