effect 4.0.7 → 4.1.1

package/src/ai/internal/mcpProtocol/v2025_11_25.ts

@@ -8,9 +8,10 @@ import * as McpCore from "../mcpCore.ts"
 import * as McpProtocol from "../mcpProtocol.ts"
 import * as McpRuntime from "../mcpRuntime.ts"
 import * as McpSchema from "../mcpSchema/v2025_11_25.ts"
+import * as McpSkills from "../mcpSkills.ts"
 
 // Pings can arrive before initialize and do not require a client session.
-const ClientRequestRpcs = McpSchema.ClientRequestRpcs.omit("ping").middleware(
+const ClientRequestRpcs = McpSchema.ClientRequestRpcs.omit("ping").merge(McpSkills.LegacyRpcs).middleware(
   PublicMcpSchema.McpServerClientMiddleware
 ).add(McpSchema.Ping)
 
@@ -133,6 +134,7 @@ export const protocol = McpProtocol.make({
   handlerRpcs: AdapterRpcs,
   makeHandlers: (core, lifecycle) =>
     AdapterRpcs.of({
+      ...McpSkills.legacyHandlers(core),
       initialize: (request, { client }) =>
         lifecycle.initialize(McpSchema.protocolVersion, {
           protocolVersion: McpSchema.protocolVersion,
@@ -177,7 +179,7 @@ export const protocol = McpProtocol.make({
       "notifications/roots/list_changed": (_, { client, headers }) =>
         lifecycle.clientNotification(McpCore.ClientNotification.RootsChanged(), client.id, headers),
       "resources/list": () =>
-        PublicMcpSchema.McpServerClient.use((request) => core.resources.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.resources.list)
           .pipe(
             Effect.map((resources) =>
               McpSchema.ListResourcesResult.make({
@@ -186,9 +188,7 @@ export const protocol = McpProtocol.make({
             )
           ),
       "resources/templates/list": () =>
-        PublicMcpSchema.McpServerClient.use((request) =>
-          core.resources.listTemplates(McpProtocol.profileFromClient(request))
-        ).pipe(
+        McpProtocol.listForClient(core.resources.listTemplates).pipe(
           Effect.map((resourceTemplates) =>
             McpSchema.ListResourceTemplatesResult.make({
               resourceTemplates: resourceTemplates.map((resourceTemplate) =>
@@ -226,7 +226,7 @@ export const protocol = McpProtocol.make({
       "resources/unsubscribe": ({ uri }, { client, headers }) =>
         lifecycle.unsubscribe(uri, client.id, headers).pipe(Effect.as({})),
       "prompts/list": () =>
-        PublicMcpSchema.McpServerClient.use((request) => core.prompts.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.prompts.list)
           .pipe(
             Effect.map((prompts) =>
               McpSchema.ListPromptsResult.make({
@@ -285,8 +285,7 @@ export const protocol = McpProtocol.make({
         })
       }),
       "tools/list": Effect.fnUntraced(function*() {
-        const request = yield* PublicMcpSchema.McpServerClient
-        const tools = yield* core.tools.list(McpProtocol.profileFromClient(request))
+        const tools = yield* McpProtocol.listForClient(core.tools.list)
         return McpSchema.ListToolsResult.make({
           tools: tools.map((tool) =>
             McpSchema.Tool.make({

package/src/ai/internal/mcpProtocol/v2026_07_28.ts

@@ -25,6 +25,7 @@ import * as PublicMcpSchema from "../../McpSchema.ts"
 import * as McpCore from "../mcpCore.ts"
 import * as McpProtocol from "../mcpProtocol.ts"
 import * as McpSchema from "../mcpSchema/v2026_07_28.ts"
+import * as McpSkills from "../mcpSkills.ts"
 
 const InputResponses = Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.Unknown))
 const decodeRequestMetadata = Schema.decodeUnknownEffect(McpSchema.RequestMetaObject)
@@ -202,9 +203,10 @@ const projectContent = Match.type<PublicMcpSchema.ContentBlock>().pipe(
   Match.exhaustive
 )
 
-const projectResource = (resource: PublicMcpSchema.Resource) => McpSchema.Resource.make(resource)
+const projectResource = (resource: PublicMcpSchema.Resource) =>
+  McpProtocol.transcode(PublicMcpSchema.Resource, McpSchema.Resource, resource)
 const projectResourceTemplate = (resourceTemplate: PublicMcpSchema.ResourceTemplate) =>
-  McpSchema.ResourceTemplate.make(resourceTemplate)
+  McpProtocol.transcode(PublicMcpSchema.ResourceTemplate, McpSchema.ResourceTemplate, resourceTemplate)
 
 const projectPrompt = (prompt: PublicMcpSchema.Prompt) =>
   McpProtocol.transcode(PublicMcpSchema.Prompt, McpSchema.Prompt, prompt)
@@ -231,6 +233,8 @@ const projectCompleteResult = Effect.fnUntraced(function*(
 type ProtocolError =
   | McpCore.ResourceNotFound
   | McpCore.PromptNotFound
+  | McpCore.SkillNotFound
+  | McpCore.DirectoryNotFound
   | McpCore.ToolError
   | McpCore.UnsupportedByProtocol
   | McpProtocol.ProtocolError
@@ -297,7 +301,7 @@ const unsupported = (
 /**
  * @internal
  */
-export const handlerRpcs = McpSchema.ClientRequestRpcs.merge(McpSchema.ClientNotificationRpcs)
+export const handlerRpcs = McpSchema.ClientRequestRpcs.merge(McpSchema.ClientNotificationRpcs, McpSkills.StatelessRpcs)
 
 /**
  * @internal
@@ -320,6 +324,9 @@ export const makeHandlers = (
   ]))
   const decodeCompleteResult = Schema.decodeUnknownEffect(McpSchema.CompleteResult)
   const decodeListToolsResult = Schema.decodeUnknownEffect(McpSchema.ListToolsResult)
+  const decodeListSkillsResult = Schema.decodeUnknownEffect(McpSkills.ListSkillsResult)
+  const decodeGetSkillResult = Schema.decodeUnknownEffect(McpSkills.GetSkillResult)
+  const decodeReadResourceDirectoryResult = Schema.decodeUnknownEffect(McpSkills.ReadResourceDirectoryResult)
   const sendNotification = context.sendNotification
   const supportsSubscriptions = sendNotification !== undefined
   // Older adapters accept arbitrary JSON; this binding requires extension settings objects.
@@ -327,9 +334,15 @@ export const makeHandlers = (
     context.serverInfo.extensions,
     (value): value is Readonly<Record<string, unknown>> => Predicate.isReadonlyObject(value)
   )
+  // Project only the wire fields; structurally compatible hints can carry extra properties.
+  const cacheHint = (family: keyof McpProtocol.CacheHints) => {
+    const hint = context.serverInfo.cacheHints?.[family]
+    return hint === undefined ? privateStaleCache : { ttlMs: hint.ttlMs, cacheScope: hint.cacheScope }
+  }
   const getDiscovery = Effect.map(context.registrationPresence, (presence) => {
     const capabilities: Types.Mutable<typeof McpSchema.ServerCapabilities.Type> = { completions: {}, logging: {} }
-    if (extensions !== undefined) capabilities.extensions = extensions
+    const declared = McpSkills.declareExtension(extensions, presence.skills)
+    if (declared !== undefined) capabilities.extensions = declared
     if (presence.tools) capabilities.tools = { listChanged: supportsSubscriptions }
     if (presence.resources) {
       capabilities.resources = { listChanged: supportsSubscriptions, subscribe: supportsSubscriptions }
@@ -337,6 +350,10 @@ export const makeHandlers = (
     if (presence.prompts) capabilities.prompts = { listChanged: supportsSubscriptions }
     return { supportedVersions: context.supportedVersions, capabilities, serverInfo: context.serverInfo }
   })
+  const requireSkills = (method: string) =>
+    McpSkills.requireSkills(core, method).pipe(
+      Effect.catch((error) => failWithHttpStatus(404, error))
+    )
   const getInvocation = PublicMcpSchema.McpRequestContext.useSync(
     McpProtocol.invocationFromRequestContext
   )
@@ -483,7 +500,7 @@ export const makeHandlers = (
     ) {
       const discovery = yield* getDiscovery
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("discover"),
         supportedVersions: Array.from(discovery.supportedVersions),
         capabilities: discovery.capabilities,
         instructions: context.serverInfo.instructions
@@ -494,10 +511,10 @@ export const makeHandlers = (
       _request: typeof McpSchema.ListResources.payloadSchema.Type
     ) {
       const invocation = yield* getInvocation
-      const resources = yield* core.resources.list(invocation.protocol)
+      const resources = yield* core.resources.list(invocation)
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
-        resources: resources.map(projectResource)
+        ...cacheHint("resources"),
+        resources: yield* Effect.forEach(resources, projectResource)
       }, context.serverInfo)
       return yield* decodeListResourcesResult(result)
     }, Effect.mapError(projectError)),
@@ -505,10 +522,10 @@ export const makeHandlers = (
       _request: typeof McpSchema.ListResourceTemplates.payloadSchema.Type
     ) {
       const invocation = yield* getInvocation
-      const resourceTemplates = yield* core.resources.listTemplates(invocation.protocol)
+      const resourceTemplates = yield* core.resources.listTemplates(invocation)
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
-        resourceTemplates: resourceTemplates.map(projectResourceTemplate)
+        ...cacheHint("resourceTemplates"),
+        resourceTemplates: yield* Effect.forEach(resourceTemplates, projectResourceTemplate)
       }, context.serverInfo)
       return yield* decodeListResourceTemplatesResult(result)
     }, Effect.mapError(projectError)),
@@ -537,10 +554,10 @@ export const makeHandlers = (
         )
       }
       const invocation = yield* getInvocation
-      const prompts = yield* core.prompts.list(invocation.protocol)
+      const prompts = yield* core.prompts.list(invocation)
       const projectedPrompts = yield* Effect.forEach(prompts, projectPrompt)
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("prompts"),
         prompts: projectedPrompts
       }, context.serverInfo)
       return yield* decodeListPromptsResult(result)
@@ -593,17 +610,17 @@ export const makeHandlers = (
       _request: typeof McpSchema.ListTools.payloadSchema.Type
     ) {
       const invocation = yield* getInvocation
-      const tools = yield* core.tools.list(invocation.protocol)
+      const tools = yield* core.tools.list(invocation)
       const projectedTools = yield* Effect.forEach(tools, projectTool)
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("tools"),
         tools: projectedTools
       }, context.serverInfo)
       return yield* decodeListToolsResult(result)
     }, Effect.mapError(projectError)),
     "tools/call": Effect.fnUntraced(function*(request: typeof McpSchema.CallTool.payloadSchema.Type) {
       const invocation = yield* getInputInvocation(request)
-      const tool = (yield* core.tools.list(invocation.protocol)).find((tool) => tool.name === request.name)
+      const tool = core.tools.find(request.name, invocation.protocol)
       const httpRequest = yield* Effect.serviceOption(HttpServerRequest.HttpServerRequest)
 
       if (tool !== undefined && Option.isSome(httpRequest)) {
@@ -668,6 +685,28 @@ export const makeHandlers = (
         context.serverInfo
       )
     }, Effect.mapError(projectError)),
+    "skills/list": Effect.fnUntraced(function*(request: typeof McpSkills.ListSkills.payloadSchema.Type) {
+      yield* requireSkills("skills/list")
+      yield* McpSkills.rejectCursor(request.cursor)
+      const skills = yield* core.skills.list(yield* getInvocation)
+      const result = yield* projectCompleteResult({ ...cacheHint("skills"), skills }, context.serverInfo)
+      return yield* decodeListSkillsResult(result)
+    }, Effect.mapError(projectError)),
+    "skills/get": Effect.fnUntraced(function*(request: typeof McpSkills.GetSkill.payloadSchema.Type) {
+      yield* requireSkills("skills/get")
+      const skill = yield* core.skills.get(request.uri, yield* getInvocation)
+      const result = yield* projectCompleteResult({ ...cacheHint("skills"), skill }, context.serverInfo)
+      return yield* decodeGetSkillResult(result)
+    }, Effect.mapError(projectError)),
+    "resources/directory/read": Effect.fnUntraced(function*(
+      request: typeof McpSkills.ReadResourceDirectory.payloadSchema.Type
+    ) {
+      yield* requireSkills("resources/directory/read")
+      yield* McpSkills.rejectCursor(request.cursor)
+      const resources = yield* core.skills.readDirectory(request.uri, yield* getInvocation)
+      const result = yield* projectCompleteResult({ ...cacheHint("skills"), resources }, context.serverInfo)
+      return yield* decodeReadResourceDirectoryResult(result)
+    }, Effect.mapError(projectError)),
     "notifications/cancelled": Effect.fnUntraced(function*(
       _request: typeof McpSchema.CancelledNotification.payloadSchema.Type
     ) {
@@ -691,7 +730,7 @@ const runtime = {
 export const protocol = McpProtocol.make({
   protocolVersion: McpSchema.protocolVersion,
   runtime,
-  clientRpcs: McpSchema.ClientRpcs,
+  clientRpcs: McpSchema.ClientRpcs.merge(McpSkills.StatelessRpcs),
   clientNotificationRpcs: McpSchema.ClientNotificationRpcs,
   serverRequestRpcs: McpSchema.ServerRequestRpcs,
   serverNotificationRpcs: McpSchema.ServerNotificationRpcs,

package/src/ai/internal/mcpProtocol.ts

@@ -16,6 +16,7 @@ import * as Schema from "../../Schema.ts"
 import type * as Scope from "../../Scope.ts"
 import type * as PublicMcpProtocol from "../McpProtocol.ts"
 import * as PublicMcpSchema from "../McpSchema.ts"
+import type * as PublicMcpServer from "../McpServer.ts"
 import * as McpCore from "./mcpCore.ts"
 
 const LEGACY_RESOURCE_NOT_FOUND_ERROR_CODE = -32002
@@ -95,6 +96,18 @@ export const invocationFromClient = (
   serverClient: request
 })
 
+/**
+ * Runs a core list operation for the legacy client of the current request.
+ *
+ * @internal
+ */
+export const listForClient = <A>(
+  list: (invocation: McpCore.McpInvocation) => Effect.Effect<A, McpCore.RequestRejected>
+): Effect.Effect<A, ProtocolError, PublicMcpSchema.McpServerClient> =>
+  PublicMcpSchema.McpServerClient.use((request) =>
+    list(invocationFromClient(request)).pipe(Effect.mapError(ProtocolError.fromFeature))
+  )
+
 /**
  * @internal
  */
@@ -212,6 +225,9 @@ export class ProtocolError extends Data.TaggedError("ProtocolError")<{
   static fromTool(
     error: McpCore.ToolError | McpCore.UnsupportedByProtocol
   ): ProtocolError {
+    if (error._tag === "RequestRejected") {
+      return new ProtocolError({ code: error.code, message: error.message, data: error.data })
+    }
     const message = Match.value(error).pipe(
       Match.tag("ToolNotFound", (error) => `Tool '${error.name}' not found`),
       Match.tag(
@@ -241,6 +257,20 @@ export class ProtocolError extends Data.TaggedError("ProtocolError")<{
           message: `Prompt '${error.name}' not found`
         })
       }
+      if (error._tag === "SkillNotFound" && Predicate.hasProperty(error, "uri") && Predicate.isString(error.uri)) {
+        return new ProtocolError({
+          code: PublicMcpSchema.INVALID_PARAMS_ERROR_CODE,
+          message: `Skill '${error.uri}' not found`
+        })
+      }
+      if (
+        error._tag === "DirectoryNotFound" && Predicate.hasProperty(error, "uri") && Predicate.isString(error.uri)
+      ) {
+        return new ProtocolError({
+          code: PublicMcpSchema.INVALID_PARAMS_ERROR_CODE,
+          message: `Directory '${error.uri}' not found`
+        })
+      }
       if (error._tag === "ResourceNotFound" && Predicate.hasProperty(error, "uri") && Predicate.isString(error.uri)) {
         return new ProtocolError({
           code: LEGACY_RESOURCE_NOT_FOUND_ERROR_CODE,
@@ -428,14 +458,28 @@ export interface HandlerInstallationContext {
     readonly websiteUrl?: string | undefined
     readonly icons?: ReadonlyArray<PublicMcpSchema.Icon> | undefined
     readonly extensions?: PublicMcpSchema.ServerCapabilities["extensions"] | undefined
+    readonly cacheHints?: CacheHints | undefined
   }
   readonly registrationPresence: Effect.Effect<{
     readonly tools: boolean
     readonly resources: boolean
     readonly prompts: boolean
+    readonly skills: boolean
   }>
 }
 
+/**
+ * Cache hints normalized to wire values when the server is constructed.
+ *
+ * @internal
+ */
+export type CacheHints = {
+  readonly [Family in keyof PublicMcpServer.CacheHints]?: {
+    readonly ttlMs: number
+    readonly cacheScope: "private"
+  }
+}
+
 /**
  * @internal
  */

package/src/ai/internal/mcpRuntime.ts

@@ -6,6 +6,7 @@
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
 import * as Cause from "../../Cause.ts"
 import * as Context from "../../Context.ts"
+import * as SecureRandom from "../../crypto/SecureRandom.ts"
 import * as Effect from "../../Effect.ts"
 import type * as Headers from "../../http/Headers.ts"
 import { appendPreResponseHandlerUnsafe } from "../../http/HttpEffect.ts"
@@ -18,11 +19,13 @@ import * as Result from "../../Result.ts"
 import * as RpcGroup from "../../rpc/RpcGroup.ts"
 import type * as RpcMessage from "../../rpc/RpcMessage.ts"
 import type * as Scope from "../../Scope.ts"
+import type * as Types from "../../Types.ts"
 import type * as PublicMcpProtocol from "../McpProtocol.ts"
 import * as PublicMcpSchema from "../McpSchema.ts"
 import type * as McpCore from "./mcpCore.ts"
 import * as McpProtocol from "./mcpProtocol.ts"
 import * as McpProtocolRegistry from "./mcpProtocolRegistry.ts"
+import * as McpSkills from "./mcpSkills.ts"
 import * as McpStatefulRuntime from "./mcpStatefulRuntime.ts"
 
 const MCP_SESSION_ID_HEADER = "mcp-session-id"
@@ -138,6 +141,7 @@ export interface HandlerInstallationOptions {
     readonly websiteUrl?: string | undefined
     readonly icons?: ReadonlyArray<PublicMcpSchema.Icon> | undefined
     readonly extensions?: NonNullable<PublicMcpSchema.ServerCapabilities["extensions"]> | undefined
+    readonly cacheHints?: McpProtocol.CacheHints | undefined
   }
 }
 
@@ -185,7 +189,8 @@ export interface ServerRuntimeShape {
     clientId: number,
     headers: Headers.Headers,
     notification: McpCore.ServerNotification,
-    fallbackLogLevel: LogLevel.LogLevel
+    fallbackLogLevel: LogLevel.LogLevel,
+    listChangeRevision: number | undefined
   ) => boolean
   readonly installHandlers: (
     options: HandlerInstallationOptions
@@ -506,8 +511,8 @@ export const make = Effect.fnUntraced(function*(
           })
       ),
     deliveryClientIds: () => stateful?.initializedClientIds() ?? [],
-    canDeliver: (clientId, headers, notification, fallback) =>
-      stateful?.canDeliver(clientId, headers, notification, fallback) ?? true,
+    canDeliver: (clientId, headers, notification, fallback, listChangeRevision) =>
+      stateful?.canDeliver(clientId, headers, notification, fallback, listChangeRevision) ?? true,
     installHandlers: Effect.fnUntraced(function*(options) {
       const contextMap = new Map<string, unknown>()
       const installationContext: McpProtocol.HandlerInstallationContext = {
@@ -539,16 +544,17 @@ export const make = Effect.fnUntraced(function*(
             const presence = yield* options.core.registrationPresence
             return yield* Effect.withFiber((fiber) => {
               const httpRequest = Context.getOrUndefined(fiber.context, HttpServerRequest.HttpServerRequest)
-              const capabilities: McpCore.CanonicalServerCapabilities = {
+              const capabilities: Types.Mutable<McpCore.CanonicalServerCapabilities> = {
                 completions: true,
                 logging: true,
                 ...(presence.tools ? { tools: { listChanged: true } } : {}),
                 ...(presence.resources
                   ? { resources: { listChanged: true, subscribe: httpRequest === undefined } }
                   : {}),
-                ...(presence.prompts ? { prompts: { listChanged: true } } : {}),
-                ...(options.serverInfo.extensions ? { extensions: options.serverInfo.extensions } : {})
+                ...(presence.prompts ? { prompts: { listChanged: true } } : {})
               }
+              const extensions = McpSkills.declareExtension(options.serverInfo.extensions, presence.skills)
+              if (extensions !== undefined) capabilities.extensions = extensions
               const initializePayload = PublicMcpSchema.Initialize.payloadSchema.make({
                 protocolVersion,
                 capabilities: profile.clientCapabilities,
@@ -561,10 +567,11 @@ export const make = Effect.fnUntraced(function*(
                 protocol: protocol as PublicMcpProtocol.ProtocolAdapter,
                 supportsResourceSubscriptions: httpRequest === undefined &&
                   capabilities.resources?.subscribe === true,
-                logLevel: options.defaultLogLevel
+                logLevel: options.defaultLogLevel,
+                listChangeRevision: options.getListChangeRevision?.() ?? 0
               }
               if (httpRequest !== undefined) {
-                const sessionId = crypto.randomUUID()
+                const sessionId = SecureRandom.uuidV4Unsafe()
                 stateful.registerHttp(sessionId, registration)
                 appendPreResponseHandlerUnsafe(
                   fiber.context,