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

package/src/unstable/ai/McpServer.ts

@@ -1,4 +1,27 @@
 /**
+ * The `McpServer` module provides Effect services and layers for building
+ * Model Context Protocol servers. It keeps track of registered tools,
+ * resources, resource templates, prompts, completions, and server
+ * notifications, then exposes them through the MCP request handlers.
+ *
+ * **Common tasks**
+ *
+ * - Start a server over stdio with {@link layerStdio}
+ * - Register HTTP routes for an existing `HttpRouter` with {@link layerHttp}
+ * - Expose Effect AI toolkits as MCP tools with {@link registerToolkit}
+ * - Register resources, resource templates, and prompts with {@link resource}
+ *   and {@link prompt}
+ * - Ask the connected MCP client for structured input with {@link elicit}
+ *
+ * **Gotchas**
+ *
+ * - Registration helpers require an `McpServer` service, usually provided by
+ *   one of this module's layers.
+ * - HTTP clients must complete MCP initialization before other requests; the
+ *   server tracks initialized sessions with the `Mcp-Session-Id` header.
+ * - Resource template parameters are decoded with the schemas embedded in the
+ *   template literal.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -72,8 +95,14 @@ import * as Tool from "./Tool.ts"
 import type * as Toolkit from "./Toolkit.ts"
 
 /**
- * @since 4.0.0
+ * Service that stores and serves an MCP server's registered tools, resources,
+ * prompts, completions, and outgoing notifications.
+ *
+ * Handlers use this service to register capabilities and resolve incoming MCP
+ * requests.
+ *
  * @category server
+ * @since 4.0.0
  */
 export class McpServer extends Context.Service<McpServer, {
   readonly notifications: RpcClient.RpcClient<RpcGroup.Rpcs<typeof ServerNotificationRpcs>>
@@ -148,6 +177,8 @@ export class McpServer extends Context.Service<McpServer, {
   ) => Effect.Effect<CompleteResult, InternalError, McpServerClient>
 }>()("effect/ai/McpServer") {
   /**
+   * Builds an MCP server service from registered tools, prompts, resources, and completions.
+   *
    * @since 4.0.0
    */
   static readonly make = Effect.gen(function*() {
@@ -307,6 +338,8 @@ export class McpServer extends Context.Service<McpServer, {
   })
 
   /**
+   * Layer that provides the MCP server and client services.
+   *
    * @since 4.0.0
    */
   static readonly layer: Layer.Layer<McpServer | McpServerClient> = Layer.effect(McpServer)(McpServer.make) as any
@@ -323,8 +356,14 @@ const mcpSessionIdHeader = "mcp-session-id"
 const mcpProtocolVersionHeader = "mcp-protocol-version"
 
 /**
- * @since 4.0.0
+ * Runs an MCP server over the current `RpcServer.Protocol`.
+ *
+ * The server performs initialization and session handling, serves registered
+ * tools, resources, and prompts, and forwards queued server notifications to
+ * initialized clients.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const run: (options: {
   readonly name: string
@@ -500,8 +539,12 @@ export const run: (options: {
 }, Effect.scoped)
 
 /**
- * @since 4.0.0
+ * Creates a layer that starts an MCP server over an existing
+ * `RpcServer.Protocol` and provides the `McpServer` and `McpServerClient`
+ * services.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly name: string
@@ -515,7 +558,8 @@ export const layer = (options: {
 /**
  * Run the McpServer, using stdio for input and output.
  *
- * @example
+ * **Example** (Running an MCP server over stdio)
+ *
  * ```ts
  * import { NodeRuntime, NodeStdio } from "@effect/platform-node"
  * import { Effect, Layer, Logger, Schema } from "effect"
@@ -566,8 +610,8 @@ export const layer = (options: {
  * Layer.launch(ServerLayer).pipe(NodeRuntime.runMain)
  * ```
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layerStdio = (options: {
   readonly name: string
@@ -582,8 +626,8 @@ export const layerStdio = (options: {
 /**
  * Run the `McpServer`, registering a router with a `HttpRouter`
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layerHttp = (options: {
   readonly name: string
@@ -599,8 +643,8 @@ export const layerHttp = (options: {
 /**
  * Register a `Toolkit` with the `McpServer`.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
   toolkit: Toolkit.Toolkit<Tools>
@@ -675,8 +719,8 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
 /**
  * Register an AiToolkit with the McpServer.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const toolkit = <Tools extends Record<string, Tool.Any>>(
   toolkit: Toolkit.Toolkit<Tools>
@@ -690,6 +734,9 @@ export const toolkit = <Tools extends Record<string, Tool.Any>>(
   )
 
 /**
+ * Utility type that validates a completion-handler record against the allowed
+ * parameter keys.
+ *
  * @since 4.0.0
  */
 export type ValidateCompletions<Completions, Keys extends string> =
@@ -699,6 +746,12 @@ export type ValidateCompletions<Completions, Keys extends string> =
   }
 
 /**
+ * Completion-handler map for a resource URI template.
+ *
+ * Each schema interpolation contributes a parameter key, using an explicit
+ * `Param` name when present or `paramN` otherwise, and each handler returns
+ * candidate values for that parameter.
+ *
  * @since 4.0.0
  */
 export type ResourceCompletions<Schemas extends ReadonlyArray<Schema.Top>> = {
@@ -711,15 +764,15 @@ export type ResourceCompletions<Schemas extends ReadonlyArray<Schema.Top>> = {
 /**
  * Register a resource with the McpServer.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export const registerResource: {
   /**
    * Register a resource with the McpServer.
    *
-   * @since 4.0.0
    * @category resources
+   * @since 4.0.0
    */
   <E, R>(
     options: {
@@ -740,8 +793,8 @@ export const registerResource: {
   /**
    * Register a resource with the McpServer.
    *
-   * @since 4.0.0
    * @category resources
+   * @since 4.0.0
    */
   <const Schemas extends ReadonlyArray<Schema.Top>>(segments: TemplateStringsArray, ...schemas: Schemas): <
     E,
@@ -881,15 +934,15 @@ export const registerResource: {
 /**
  * Register a resource with the McpServer.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export const resource: {
   /**
    * Register a resource with the McpServer.
    *
-   * @since 4.0.0
    * @category resources
+   * @since 4.0.0
    */
   <E, R>(
     options: {
@@ -909,8 +962,8 @@ export const resource: {
   /**
    * Register a resource with the McpServer.
    *
-   * @since 4.0.0
    * @category resources
+   * @since 4.0.0
    */
   <const Schemas extends ReadonlyArray<Schema.Top>>(segments: TemplateStringsArray, ...schemas: Schemas): <
     E,
@@ -955,8 +1008,8 @@ export const resource: {
 /**
  * Register a prompt with the McpServer.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export const registerPrompt = <
   E,
@@ -1050,8 +1103,8 @@ export const registerPrompt = <
 /**
  * Register a prompt with the McpServer.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export const prompt = <
   E,
@@ -1077,10 +1130,14 @@ export const prompt = <
   )
 
 /**
- * Create an elicitation request
+ * Requests structured input from the current MCP client and decodes the
+ * accepted response with `schema`.
+ *
+ * Accepted content is decoded with the supplied schema, declined requests fail
+ * with `ElicitationDeclined`, and canceled requests interrupt the effect.
  *
- * @since 4.0.0
  * @category elicitation
+ * @since 4.0.0
  */
 export const elicit: <S extends Schema.Encoder<Record<string, unknown>, unknown>>(options: {
   readonly message: string
@@ -1116,8 +1173,8 @@ export const elicit: <S extends Schema.Encoder<Record<string, unknown>, unknown>
 /**
  * Access the current client's capabilities.
  *
- * @since 4.0.0
  * @category capabilities
+ * @since 4.0.0
  */
 export const clientCapabilities: Effect.Effect<
   ClientCapabilities,

package/src/unstable/ai/Model.ts

@@ -6,7 +6,8 @@
  * functionality with provider identification, allowing for seamless switching
  * between different AI service providers while maintaining type safety.
  *
- * @example
+ * **Example** (Creating a provider-specific model)
+ *
  * ```ts
  * import type { Layer } from "effect"
  * import { Effect } from "effect"
@@ -50,8 +51,8 @@ const TypeId = "~effect/ai/Model" as const
  * @template Provides - Services that this model provides.
  * @template Requires - Services that this model requires.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Model<in out Provider, in out Provides, in out Requires>
   extends Layer.Layer<Provides | ProviderName | ModelName, never, Requires>
@@ -80,8 +81,8 @@ export interface Model<in out Provider, in out Provides, in out Requires>
  * access the name of the provider that is currently in use within a given
  * Effect program.
  *
- * @since 4.0.0
  * @category services
+ * @since 4.0.0
  */
 export class ProviderName extends Context.Service<ProviderName, string>()(
   "effect/unstable/ai/Model/ProviderName"
@@ -94,8 +95,8 @@ export class ProviderName extends Context.Service<ProviderName, string>()(
  * access the name of the model that is currently in use within a given Effect
  * program.
  *
- * @since 4.0.0
  * @category services
+ * @since 4.0.0
  */
 export class ModelName extends Context.Service<ModelName, string>()(
   "effect/unstable/ai/Model/ModelName"
@@ -126,7 +127,8 @@ const Proto = {
 /**
  * Creates a Model from a provider name and a Layer that constructs AI services.
  *
- * @example
+ * **Example** (Providing model metadata)
+ *
  * ```ts
  * import type { Layer } from "effect"
  * import { Effect } from "effect"
@@ -152,8 +154,8 @@ const Proto = {
  * // Will log: "Generating with: amazon-bedrock/claude-3-5-haiku"
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <const Provider extends string, const Name extends string, Provides, Requires>(
   /**

package/src/unstable/ai/OpenAiStructuredOutput.ts

@@ -1,7 +1,7 @@
 /**
  * Provides codec transformations for OpenAI structured output.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
 import * as JsonSchema from "../../JsonSchema.ts"
@@ -37,8 +37,8 @@ import * as Tool from "./Tool.ts"
  * If the schema is already compatible, the original codec is returned
  * unchanged.
  *
- * @since 1.0.0
  * @category Codec Transformation
+ * @since 4.0.0
  */
 export function toCodecOpenAI<T, E, RD, RE>(
   schema: Schema.Codec<T, E, RD, RE>