effect 4.0.4 → 4.0.6

package/src/ai/McpServer.ts

@@ -424,214 +424,210 @@ export class McpServer extends Context.Service<McpServer, {
       get tools() {
         return tools
       },
-      addTool: (options) =>
-        Effect.gen(function*() {
-          const existingIndex = tools.findIndex(({ tool }) => tool.name === options.tool.name)
-          if (existingIndex === -1) {
-            tools.push(options)
-          } else {
-            tools[existingIndex] = options
-          }
-          const enabledWhen = Context.getOrUndefined(options.annotations, EnabledWhen)
-          yield* internalCore.tools.register({
-            descriptor: new McpTool({
-              ...options.tool,
-              title: options.tool.title ?? options.tool.annotations?.title
-            }),
-            isVisible: (profile) =>
-              enabledWhen === undefined || enabledWhen(
-                {
-                  protocolVersion: profile.protocolVersion,
-                  capabilities: profile.clientCapabilities,
-                  clientInfo: profile.clientInfo
-                }
-              ),
-            handle: (call, invocation) =>
-              provideInvocationContext(options.handle(call.arguments), invocation).pipe(
-                Effect.catchTags({
-                  InternalError: (error) =>
-                    Effect.fail(
-                      new McpCore.ToolExecutionError({
-                        name: options.tool.name,
-                        message: error.message
-                      })
-                    ),
-                  InvalidParams: (error) =>
-                    Effect.fail(
-                      new (invocation.requestContext.requestState === undefined &&
-                          invocation.requestContext.inputResponses === undefined
-                        ? McpCore.InvalidToolInput
-                        : McpCore.InvalidToolContinuation)({
-                        name: options.tool.name,
-                        message: error.message
-                      })
-                    )
-                }),
-                Effect.map((result) =>
-                  Predicate.isTagged(result, "InputRequired")
-                    ? McpCore.OperationOutcome.InputRequired(result)
-                    : McpCore.OperationOutcome.Complete(result)
-                )
+      addTool: Effect.fnUntraced(function*(options) {
+        const existingIndex = tools.findIndex(({ tool }) => tool.name === options.tool.name)
+        if (existingIndex === -1) {
+          tools.push(options)
+        } else {
+          tools[existingIndex] = options
+        }
+        const enabledWhen = Context.getOrUndefined(options.annotations, EnabledWhen)
+        yield* internalCore.tools.register({
+          descriptor: new McpTool({
+            ...options.tool,
+            title: options.tool.title ?? options.tool.annotations?.title
+          }),
+          isVisible: (profile) =>
+            enabledWhen === undefined || enabledWhen(
+              {
+                protocolVersion: profile.protocolVersion,
+                capabilities: profile.clientCapabilities,
+                clientInfo: profile.clientInfo
+              }
+            ),
+          handle: (call, invocation) =>
+            provideInvocationContext(options.handle(call.arguments), invocation).pipe(
+              Effect.catchTags({
+                InternalError: (error) =>
+                  Effect.fail(
+                    new McpCore.ToolExecutionError({
+                      name: options.tool.name,
+                      message: error.message
+                    })
+                  ),
+                InvalidParams: (error) =>
+                  Effect.fail(
+                    new (invocation.requestContext.requestState === undefined &&
+                        invocation.requestContext.inputResponses === undefined
+                      ? McpCore.InvalidToolInput
+                      : McpCore.InvalidToolContinuation)({
+                      name: options.tool.name,
+                      message: error.message
+                    })
+                  )
+              }),
+              Effect.map((result) =>
+                Predicate.isTagged(result, "InputRequired")
+                  ? McpCore.OperationOutcome.InputRequired(result)
+                  : McpCore.OperationOutcome.Complete(result)
               )
-          })
-          yield* notifications.client["notifications/tools/list_changed"]({})
-        }),
-      callTool: (request) =>
-        Effect.gen(function*() {
-          const client = yield* McpServerClient
-          const result = yield* internalCore.tools.call(
-            request,
-            McpProtocolInternal.invocationFromClient(client)
-          ).pipe(
-            Effect.mapError((error) =>
-              new InvalidParams({
-                message: error._tag === "ToolNotFound"
-                  ? `Tool '${error.name}' not found`
-                  : error.message
-              })
             )
+        })
+        yield* notifications.client["notifications/tools/list_changed"]({})
+      }),
+      callTool: Effect.fnUntraced(function*(request) {
+        const client = yield* McpServerClient
+        const result = yield* internalCore.tools.call(
+          request,
+          McpProtocolInternal.invocationFromClient(client)
+        ).pipe(
+          Effect.mapError((error) =>
+            new InvalidParams({
+              message: error._tag === "ToolNotFound"
+                ? `Tool '${error.name}' not found`
+                : error.message
+            })
           )
-          if (result._tag === "InputRequired") {
-            return yield* new InvalidParams({ message: "Client input is not supported by this MCP protocol" })
-          }
-          return result.value
-        }),
+        )
+        if (result._tag === "InputRequired") {
+          return yield* new InvalidParams({ message: "Client input is not supported by this MCP protocol" })
+        }
+        return result.value
+      }),
       get resources() {
         return resources
       },
       get resourceTemplates() {
         return resourceTemplates
       },
-      addResource: (options) =>
-        Effect.gen(function*() {
-          const existingIndex = resources.findIndex(({ resource }) => resource.uri === options.resource.uri)
-          if (existingIndex === -1) {
-            resources.push(options)
-          } else {
-            resources[existingIndex] = options
-          }
-          yield* internalCore.resources.register({
-            descriptor: options.resource,
-            isVisible: (profile) => {
-              const enabledWhen = Context.getOrUndefined(options.annotations, EnabledWhen)
-              return enabledWhen === undefined || enabledWhen({
-                protocolVersion: profile.protocolVersion,
-                capabilities: profile.clientCapabilities,
-                clientInfo: profile.clientInfo
-              })
-            },
-            read: (invocation) => provideInvocationContext(options.handle, invocation)
-          })
-          yield* notifications.client["notifications/resources/list_changed"]({})
-        }),
-      addResourceTemplate: ({ annotations, completions, handle, routerPath, template }) =>
-        Effect.gen(function*() {
-          const existingIndex = resourceTemplates.findIndex(({ template: current }) =>
-            current.uriTemplate === template.uriTemplate
+      addResource: Effect.fnUntraced(function*(options) {
+        const existingIndex = resources.findIndex(({ resource }) => resource.uri === options.resource.uri)
+        if (existingIndex === -1) {
+          resources.push(options)
+        } else {
+          resources[existingIndex] = options
+        }
+        yield* internalCore.resources.register({
+          descriptor: options.resource,
+          isVisible: (profile) => {
+            const enabledWhen = Context.getOrUndefined(options.annotations, EnabledWhen)
+            return enabledWhen === undefined || enabledWhen({
+              protocolVersion: profile.protocolVersion,
+              capabilities: profile.clientCapabilities,
+              clientInfo: profile.clientInfo
+            })
+          },
+          read: (invocation) => provideInvocationContext(options.handle, invocation)
+        })
+        yield* notifications.client["notifications/resources/list_changed"]({})
+      }),
+      addResourceTemplate: Effect.fnUntraced(function*({ annotations, completions, handle, routerPath, template }) {
+        const existingIndex = resourceTemplates.findIndex(({ template: current }) =>
+          current.uriTemplate === template.uriTemplate
+        )
+        if (existingIndex === -1) {
+          resourceTemplates.push({ template, annotations })
+        } else {
+          resourceTemplates[existingIndex] = { template, annotations }
+        }
+        const templateMatcher = makeUriMatcher<true>()
+        templateMatcher.add(routerPath, true)
+        yield* internalCore.resources.registerTemplate({
+          descriptor: template,
+          isVisible: (profile) => {
+            const enabledWhen = Context.getOrUndefined(annotations, EnabledWhen)
+            return enabledWhen === undefined || enabledWhen({
+              protocolVersion: profile.protocolVersion,
+              capabilities: profile.clientCapabilities,
+              clientInfo: profile.clientInfo
+            })
+          },
+          match: (uri) => {
+            const match = templateMatcher.find(uri)
+            if (match === undefined) {
+              return undefined
+            }
+            const params: Array<string> = []
+            for (const key of Object.keys(match.params)) {
+              params[Number(key)] = match.params[key]!
+            }
+            return params
+          },
+          read: (uri, params, invocation) => provideInvocationContext(handle(uri, Array.from(params)), invocation)
+        })
+        for (const [param, handle] of Object.entries(completions)) {
+          yield* internalCore.completions.register(
+            `resource/${template.uriTemplate}/${param}`,
+            (request, invocation) =>
+              provideInvocationContext(handle(request.argument.value, request.context), invocation).pipe(
+                Effect.map((result) => ({
+                  values: result.completion.values,
+                  total: result.completion.total,
+                  hasMore: result.completion.hasMore,
+                  metadata: result._meta
+                }))
+              )
           )
-          if (existingIndex === -1) {
-            resourceTemplates.push({ template, annotations })
-          } else {
-            resourceTemplates[existingIndex] = { template, annotations }
-          }
-          const templateMatcher = makeUriMatcher<true>()
-          templateMatcher.add(routerPath, true)
-          yield* internalCore.resources.registerTemplate({
-            descriptor: template,
-            isVisible: (profile) => {
-              const enabledWhen = Context.getOrUndefined(annotations, EnabledWhen)
-              return enabledWhen === undefined || enabledWhen({
-                protocolVersion: profile.protocolVersion,
-                capabilities: profile.clientCapabilities,
-                clientInfo: profile.clientInfo
-              })
-            },
-            match: (uri) => {
-              const match = templateMatcher.find(uri)
-              if (match === undefined) {
-                return undefined
-              }
-              const params: Array<string> = []
-              for (const key of Object.keys(match.params)) {
-                params[Number(key)] = match.params[key]!
-              }
-              return params
-            },
-            read: (uri, params, invocation) => provideInvocationContext(handle(uri, Array.from(params)), invocation)
-          })
-          for (const [param, handle] of Object.entries(completions)) {
-            yield* internalCore.completions.register(
-              `resource/${template.uriTemplate}/${param}`,
-              (request, invocation) =>
-                provideInvocationContext(handle(request.argument.value, request.context), invocation).pipe(
-                  Effect.map((result) => ({
-                    values: result.completion.values,
-                    total: result.completion.total,
-                    hasMore: result.completion.hasMore,
-                    metadata: result._meta
-                  }))
-                )
-            )
-          }
-          yield* notifications.client["notifications/resources/list_changed"]({})
-        }),
-      findResource: (uri) =>
-        Effect.gen(function*() {
-          const client = yield* McpServerClient
-          return yield* internalCore.resources.read(
-            uri,
-            McpProtocolInternal.invocationFromClient(client)
-          ).pipe(
-            Effect.catchTag("ResourceNotFound", (error) =>
-              Effect.fail(new InvalidParams({ message: `Resource '${error.uri}' not found` })))
+        }
+        yield* notifications.client["notifications/resources/list_changed"]({})
+      }),
+      findResource: Effect.fnUntraced(function*(uri) {
+        const client = yield* McpServerClient
+        return yield* internalCore.resources.read(
+          uri,
+          McpProtocolInternal.invocationFromClient(client)
+        ).pipe(
+          Effect.catchTag(
+            "ResourceNotFound",
+            (error) => Effect.fail(new InvalidParams({ message: `Resource '${error.uri}' not found` }))
           )
-        }),
+        )
+      }),
       get prompts() {
         return prompts
       },
-      addPrompt: (options) =>
-        Effect.gen(function*() {
-          const existingIndex = prompts.findIndex(({ prompt }) => prompt.name === options.prompt.name)
-          if (existingIndex === -1) {
-            prompts.push(options)
-          } else {
-            prompts[existingIndex] = options
-          }
-          yield* internalCore.prompts.register({
-            descriptor: options.prompt,
-            isVisible: (profile) => {
-              const enabledWhen = Context.getOrUndefined(options.annotations, EnabledWhen)
-              return enabledWhen === undefined || enabledWhen({
-                protocolVersion: profile.protocolVersion,
-                capabilities: profile.clientCapabilities,
-                clientInfo: profile.clientInfo
-              })
-            },
-            get: (params, invocation) =>
-              provideInvocationContext(options.handle(params), invocation).pipe(
-                Effect.map((result) =>
-                  Predicate.isTagged(result, "InputRequired")
-                    ? McpCore.OperationOutcome.InputRequired(result)
-                    : McpCore.OperationOutcome.Complete(result)
-                )
+      addPrompt: Effect.fnUntraced(function*(options) {
+        const existingIndex = prompts.findIndex(({ prompt }) => prompt.name === options.prompt.name)
+        if (existingIndex === -1) {
+          prompts.push(options)
+        } else {
+          prompts[existingIndex] = options
+        }
+        yield* internalCore.prompts.register({
+          descriptor: options.prompt,
+          isVisible: (profile) => {
+            const enabledWhen = Context.getOrUndefined(options.annotations, EnabledWhen)
+            return enabledWhen === undefined || enabledWhen({
+              protocolVersion: profile.protocolVersion,
+              capabilities: profile.clientCapabilities,
+              clientInfo: profile.clientInfo
+            })
+          },
+          get: (params, invocation) =>
+            provideInvocationContext(options.handle(params), invocation).pipe(
+              Effect.map((result) =>
+                Predicate.isTagged(result, "InputRequired")
+                  ? McpCore.OperationOutcome.InputRequired(result)
+                  : McpCore.OperationOutcome.Complete(result)
               )
-          })
-          for (const [param, handle] of Object.entries(options.completions)) {
-            yield* internalCore.completions.register(
-              `prompt/${options.prompt.name}/${param}`,
-              (request, invocation) =>
-                provideInvocationContext(handle(request.argument.value, request.context), invocation).pipe(
-                  Effect.map((result) => ({
-                    values: result.completion.values,
-                    total: result.completion.total,
-                    hasMore: result.completion.hasMore,
-                    metadata: result._meta
-                  }))
-                )
             )
-          }
-          yield* notifications.client["notifications/prompts/list_changed"]({})
-        }),
+        })
+        for (const [param, handle] of Object.entries(options.completions)) {
+          yield* internalCore.completions.register(
+            `prompt/${options.prompt.name}/${param}`,
+            (request, invocation) =>
+              provideInvocationContext(handle(request.argument.value, request.context), invocation).pipe(
+                Effect.map((result) => ({
+                  values: result.completion.values,
+                  total: result.completion.total,
+                  hasMore: result.completion.hasMore,
+                  metadata: result._meta
+                }))
+              )
+          )
+        }
+        yield* notifications.client["notifications/prompts/list_changed"]({})
+      }),
       getPromptResult: Effect.fnUntraced(function*({ arguments: params, name }) {
         const client = yield* McpServerClient
         const outcome = yield* internalCore.prompts.get(
@@ -916,18 +912,15 @@ const runWithRuntime = Effect.fnUntraced(function*(
     const isInitialize = rpc._tag.endsWith("/initialize")
     if (!isInitialize && !session) {
       const fiber = Fiber.getCurrent()!
-      const httpRequest = Context.getOrUndefined(fiber.context, HttpServerRequest.HttpServerRequest)
-      if (httpRequest) {
-        appendPreResponseHandlerUnsafe(
-          httpRequest,
-          () =>
-            Effect.succeed(
-              HttpServerResponse.empty({
-                status: headers[MCP_SESSION_ID_HEADER] === undefined ? 400 : 404
-              })
-            )
-        )
-      }
+      appendPreResponseHandlerUnsafe(
+        fiber.context,
+        () =>
+          Effect.succeed(
+            HttpServerResponse.empty({
+              status: headers[MCP_SESSION_ID_HEADER] === undefined ? 400 : 404
+            })
+          )
+      )
       return Effect.die(new Error(`Mcp-Session-Id does not exist`))
     }
     // RPC middleware erases the correlation between the initialize tag
@@ -966,7 +959,7 @@ const runWithRuntime = Effect.fnUntraced(function*(
             clientInfo: profile.clientInfo,
             initializePayload,
             requestMetadata: Predicate.isReadonlyObject(payload) && Predicate.isReadonlyObject(payload._meta)
-              ? payload._meta as Schema.JsonObject
+              ? payload._meta as Readonly<Record<string, unknown>>
               : undefined,
             getClient: RcMap.get(
               clients,
@@ -1033,7 +1026,7 @@ const runWithRuntime = Effect.fnUntraced(function*(
           ? Context.getOrUndefined(fiber.context, HttpServerRequest.HttpServerRequest)
           : undefined
         if (httpRequest !== undefined && request._tag !== "Eof") {
-          appendPreResponseHandlerUnsafe(httpRequest, (_, response) =>
+          appendPreResponseHandlerUnsafe(fiber.context, (_, response) =>
             Effect.succeed(
               response.status === 200 &&
                 response.body._tag === "Uint8Array" &&
@@ -1095,7 +1088,7 @@ const runWithRuntime = Effect.fnUntraced(function*(
                 )
               }
               if (httpRequest !== undefined && session !== undefined) {
-                appendPreResponseHandlerUnsafe(httpRequest, (_, res) =>
+                appendPreResponseHandlerUnsafe(fiber.context, (_, res) =>
                   Effect.succeed(
                     runtime.resolveRequest(clientId, headers) === undefined
                       ? HttpServerResponse.empty({ status: 404 })
@@ -1111,17 +1104,15 @@ const runWithRuntime = Effect.fnUntraced(function*(
               const isClientNotification = selectedProtocol.clientNotificationRpcs.requests.has(request.tag)
               if (rpc && isClientNotification && request.isNotification) {
                 if (!session && selectedProtocol.runtime._tag === "Stateful") {
-                  if (httpRequest) {
-                    appendPreResponseHandlerUnsafe(
-                      httpRequest,
-                      () =>
-                        Effect.succeed(
-                          HttpServerResponse.empty({
-                            status: headers[MCP_SESSION_ID_HEADER] === undefined ? 400 : 404
-                          })
-                        )
-                    )
-                  }
+                  appendPreResponseHandlerUnsafe(
+                    fiber.context,
+                    () =>
+                      Effect.succeed(
+                        HttpServerResponse.empty({
+                          status: headers[MCP_SESSION_ID_HEADER] === undefined ? 400 : 404
+                        })
+                      )
+                  )
                   return
                 }
                 const decode = selectedProtocol.payloadCodecs(rpc).decode(request.payload)
@@ -2192,10 +2183,16 @@ const isParameterValidationError = (
 ): error is AiError.AiError & { readonly reason: AiError.ToolParameterValidationError } =>
   AiError.isAiError(error) && error.reason._tag === "ToolParameterValidationError"
 
-// MCP requires an object root, so a top-level `$ref` is inlined.
+// MCP requires an object root. A non-recursive root is compiled inline rather
+// than as a definition; a recursive root keeps its definition and the top-level
+// `$ref` is inlined.
 const toolJsonSchema = (schema: Schema.Constraint, strict: boolean): JsonSchema.JsonSchema => {
+  const root = SchemaAST.getContextOwner(SchemaAST.getLastEncoding(Schema.toCodecJson(schema).ast))
   const document = InternalStructuredOutput.resolveTopLevelReference(
-    Schema.toJsonSchemaDocument(schema, { onExcessProperty: strict ? "error" : "ignore" })
+    Schema.toJsonSchemaDocument(schema, {
+      onExcessProperty: strict ? "error" : "ignore",
+      referencePolicy: ({ ast, identifier, occurrences }) => ast === root && occurrences === 1 ? undefined : identifier
+    })
   )
   return Object.keys(document.definitions).length === 0
     ? document.schema
@@ -2277,12 +2274,6 @@ export type ResourceCompletions<Schemas extends ReadonlyArray<Schema.Constraint>
 /**
  * Registers an MCP resource or resource template from an Effect program.
  *
- * **When to use**
- *
- * Use when you are already inside an Effect program with an `McpServer`
- * service and need to add a concrete resource or URI-template resource
- * directly.
- *
  * @see {@link resource} for the layer-based resource registration wrapper
  *
  * @stability unstable
@@ -2293,12 +2284,6 @@ export const registerResource: {
   /**
    * Registers an MCP resource or resource template from an Effect program.
    *
-   * **When to use**
-   *
-   * Use when you are already inside an Effect program with an `McpServer`
-   * service and need to add a concrete resource or URI-template resource
-   * directly.
-   *
    * @see {@link resource} for the layer-based resource registration wrapper
    *
    * @stability unstable
@@ -2324,12 +2309,6 @@ export const registerResource: {
   /**
    * Registers an MCP resource or resource template from an Effect program.
    *
-   * **When to use**
-   *
-   * Use when you are already inside an Effect program with an `McpServer`
-   * service and need to add a concrete resource or URI-template resource
-   * directly.
-   *
    * @see {@link resource} for the layer-based resource registration wrapper
    *
    * @stability unstable
@@ -2360,9 +2339,7 @@ export const registerResource: {
       | Schemas[number]["DecodingServices"]
       | Schemas[number]["EncodingServices"]
       | R
-      | (Completions[keyof Completions] extends (input: string) => infer Ret ?
-        Ret extends Effect.Effect<infer _A, infer _E, infer _R> ? _R : never
-        : never),
+      | CompletionServices<Completions>,
       McpRequestContext
     >
     | McpServer
@@ -2491,10 +2468,6 @@ export const registerResource: {
 /**
  * Creates a layer that registers an MCP resource or resource template.
  *
- * **When to use**
- *
- * Use to compose resource registration into an MCP server layer.
- *
  * @see {@link registerResource} for the Effect-level resource registration API
  *
  * @stability unstable
@@ -2505,10 +2478,6 @@ export const resource: {
   /**
    * Creates a layer that registers an MCP resource or resource template.
    *
-   * **When to use**
-   *
-   * Use to compose resource registration into an MCP server layer.
-   *
    * @see {@link registerResource} for the Effect-level resource registration API
    *
    * @stability unstable
@@ -2533,10 +2502,6 @@ export const resource: {
   /**
    * Creates a layer that registers an MCP resource or resource template.
    *
-   * **When to use**
-   *
-   * Use to compose resource registration into an MCP server layer.
-   *
    * @see {@link registerResource} for the Effect-level resource registration API
    *
    * @stability unstable
@@ -2563,10 +2528,10 @@ export const resource: {
     never,
     never,
     Exclude<
+      | Schemas[number]["DecodingServices"]
+      | Schemas[number]["EncodingServices"]
       | R
-      | (Completions[keyof Completions] extends (input: string) => infer Ret ?
-        Ret extends Effect.Effect<infer _A, infer _E, infer _R> ? _R : never
-        : never),
+      | CompletionServices<Completions>,
       McpRequestContext
     >
   >
@@ -2586,16 +2551,10 @@ export const resource: {
 /**
  * Registers an MCP prompt from an Effect program.
  *
- * **When to use**
- *
- * Use when you are already inside an Effect program with an `McpServer`
- * service and need to add a prompt handler directly.
- *
  * **Details**
  *
- * Parameters are decoded with the supplied schema, completion handlers encode
- * per-parameter suggestions, and string prompt content is converted into a user
- * text message.
+ * Decodes parameters and encodes completion suggestions using their schemas.
+ * String content becomes a user text message.
  *
  * @see {@link prompt} for the layer-based prompt registration wrapper
  *
@@ -2630,6 +2589,7 @@ export const registerPrompt = <
   never,
   | Exclude<
     | Schema.Struct.DecodingServices<Params>
+    | Params[Extract<keyof Completions, keyof Params>]["EncodingServices"]
     | R
     | CompletionServices<Completions>,
     McpRequestContext
@@ -2665,7 +2625,13 @@ export const registerPrompt = <
     const registry = yield* McpServer
     const services = omitRequestServices(
       yield* Effect.context<
-        Exclude<R | Schema.Struct.DecodingServices<Params>, McpRequestContext>
+        Exclude<
+          | R
+          | Schema.Struct.DecodingServices<Params>
+          | Params[Extract<keyof Completions, keyof Params>]["EncodingServices"]
+          | CompletionServices<Completions>,
+          McpRequestContext
+        >
       >()
     )
     const completions: Record<
@@ -2731,16 +2697,6 @@ export const registerPrompt = <
 /**
  * Creates a layer that registers an MCP prompt.
  *
- * **When to use**
- *
- * Use to compose prompt registration into an MCP server layer.
- *
- * **Details**
- *
- * Parameters are decoded with the supplied schema, completion handlers encode
- * per-parameter suggestions, and string prompt content is converted into a user
- * text message.
- *
  * @see {@link registerPrompt} for the Effect-level prompt registration API
  *
  * @stability unstable
@@ -2774,6 +2730,7 @@ export const prompt = <
   never,
   Exclude<
     | Schema.Struct.DecodingServices<Params>
+    | Params[Extract<keyof Completions, keyof Params>]["EncodingServices"]
     | R
     | CompletionServices<Completions>,
     McpRequestContext