Skip to content

Commit 3a65e9e

Browse files
authored
Restore MCP Skills support on legacy protocol revisions (#10540)
1 parent 2b23262 commit 3a65e9e

11 files changed

Lines changed: 172 additions & 79 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"effect": patch
3+
---
4+
5+
Restore Skills discovery, retrieval, and directory browsing in `McpClient` and `McpServer` on supported MCP protocol revisions before 2026-07-28.

‎packages/effect/src/ai/McpClient.ts‎

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -259,11 +259,6 @@ export const isMcpClient = (value: unknown): value is McpClient => Predicate.has
259259
* `crypto.subtle`.
260260
* Schema decoding requires the schema's services from the caller.
261261
*
262-
* **Gotchas**
263-
*
264-
* The Skills extension requires protocol 2026-07-28. With `skills: true` on an
265-
* earlier protocol, construction fails with an `UnsupportedError`.
266-
*
267262
* @stability experimental
268263
* @category constructors
269264
* @since 4.0.6
@@ -296,12 +291,6 @@ export const make: (options: {
296291
const protocol = transport.protocol
297292
const version = protocol.protocolVersion
298293
const modern = version === "2026-07-28"
299-
const skillsEnabled = options.extensions?.skills === true
300-
if (skillsEnabled && !modern) {
301-
return yield* fail(
302-
new UnsupportedError({ description: "The MCP Skills extension requires at least protocol 2026-07-28" })
303-
)
304-
}
305294
const timeout = options.timeout ?? DEFAULT_TIMEOUT
306295
const discoveryLimits = yield* resolveDiscoveryLimits(options.discoveryLimits, DEFAULT_DISCOVERY_LIMITS)
307296
const closed = yield* Deferred.make<never, McpClientError>()
@@ -321,6 +310,7 @@ export const make: (options: {
321310

322311
// Modern requests carry the client identity in every request.
323312
// https://modelcontextprotocol.io/specification/2026-07-28/basic/index
313+
const skillsEnabled = options.extensions?.skills === true
324314
const clientCapabilities = skillsEnabled ? { extensions: { [McpSkills.EXTENSION_ID]: {} } } : {}
325315
const meta = {
326316
"io.modelcontextprotocol/protocolVersion": version,

‎packages/effect/src/ai/McpServer.ts‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3855,9 +3855,7 @@ const toSkillSourceFile = (path: string, file: SkillFile): McpSkills.SourceFile
38553855
* `skills/list` and `skills/get` with a manifest of every file's SHA-256
38563856
* digest and size, computed from the bytes served. Every directory of the
38573857
* skill namespace is readable with `resources/directory/read`. The server
3858-
* declares the extension on protocol 2026-07-28 once any skill is registered.
3859-
* Earlier revisions neither declare it nor answer its methods, but still serve
3860-
* the skill's files through `resources/read`.
3858+
* declares the extension once any skill is registered.
38613859
*
38623860
* Fails when the skill breaks the extension's rules: a name that does not
38633861
* match the URI, a `SKILL.md` without YAML frontmatter, frontmatter that is

‎packages/effect/src/ai/internal/mcpProtocol/v2024_11_05.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@ import * as McpCore from "../mcpCore.ts"
77
import * as McpProtocol from "../mcpProtocol.ts"
88
import * as McpRuntime from "../mcpRuntime.ts"
99
import * as McpSchema from "../mcpSchema/v2024_11_05.ts"
10+
import * as McpSkills from "../mcpSkills.ts"
1011

1112
// Pings can arrive before initialize and do not require a client session.
12-
const ClientRequestRpcs = McpSchema.ClientRequestRpcs.omit("ping").middleware(
13+
const ClientRequestRpcs = McpSchema.ClientRequestRpcs.omit("ping").merge(McpSkills.LegacyRpcs).middleware(
1314
PublicMcpSchema.McpServerClientMiddleware
1415
).add(McpSchema.Ping)
1516

@@ -121,6 +122,7 @@ export const protocol = McpProtocol.make({
121122
handlerRpcs: AdapterRpcs,
122123
makeHandlers: (core, lifecycle) =>
123124
AdapterRpcs.of({
125+
...McpSkills.legacyHandlers(core),
124126
initialize: (request, { client }) =>
125127
lifecycle.initialize(McpSchema.protocolVersion, profileFromInitialize(request), client.id).pipe(
126128
Effect.map((result) =>

‎packages/effect/src/ai/internal/mcpProtocol/v2025_03_26.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@ import * as McpCore from "../mcpCore.ts"
77
import * as McpProtocol from "../mcpProtocol.ts"
88
import * as McpRuntime from "../mcpRuntime.ts"
99
import * as McpSchema from "../mcpSchema/v2025_03_26.ts"
10+
import * as McpSkills from "../mcpSkills.ts"
1011

1112
// Pings can arrive before initialize and do not require a client session.
12-
const ClientRequestRpcs = McpSchema.ClientRequestRpcs.omit("ping").middleware(
13+
const ClientRequestRpcs = McpSchema.ClientRequestRpcs.omit("ping").merge(McpSkills.LegacyRpcs).middleware(
1314
PublicMcpSchema.McpServerClientMiddleware
1415
).add(McpSchema.Ping)
1516

@@ -124,6 +125,7 @@ export const protocol = McpProtocol.make({
124125
handlerRpcs: AdapterRpcs,
125126
makeHandlers: (core, lifecycle) =>
126127
AdapterRpcs.of({
128+
...McpSkills.legacyHandlers(core),
127129
initialize: (request, { client }) =>
128130
lifecycle.initialize(McpSchema.protocolVersion, profileFromInitialize(request), client.id).pipe(
129131
Effect.map((result) =>

‎packages/effect/src/ai/internal/mcpProtocol/v2025_06_18.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,10 @@ import * as McpCore from "../mcpCore.ts"
99
import * as McpProtocol from "../mcpProtocol.ts"
1010
import * as McpRuntime from "../mcpRuntime.ts"
1111
import * as McpSchema from "../mcpSchema/v2025_06_18.ts"
12+
import * as McpSkills from "../mcpSkills.ts"
1213

1314
// Pings can arrive before initialize and do not require a client session.
14-
const ClientRequestRpcs = McpSchema.ClientRequestRpcs.omit("ping").middleware(
15+
const ClientRequestRpcs = McpSchema.ClientRequestRpcs.omit("ping").merge(McpSkills.LegacyRpcs).middleware(
1516
PublicMcpSchema.McpServerClientMiddleware
1617
).add(McpSchema.Ping)
1718

@@ -143,6 +144,7 @@ export const protocol = McpProtocol.make({
143144
handlerRpcs: AdapterRpcs,
144145
makeHandlers: (core, lifecycle) =>
145146
AdapterRpcs.of({
147+
...McpSkills.legacyHandlers(core),
146148
initialize: (request, { client }) =>
147149
lifecycle.initialize(McpSchema.protocolVersion, profileFromInitialize(request), client.id).pipe(
148150
Effect.map((result) =>

‎packages/effect/src/ai/internal/mcpProtocol/v2025_11_25.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,10 @@ import * as McpCore from "../mcpCore.ts"
88
import * as McpProtocol from "../mcpProtocol.ts"
99
import * as McpRuntime from "../mcpRuntime.ts"
1010
import * as McpSchema from "../mcpSchema/v2025_11_25.ts"
11+
import * as McpSkills from "../mcpSkills.ts"
1112

1213
// Pings can arrive before initialize and do not require a client session.
13-
const ClientRequestRpcs = McpSchema.ClientRequestRpcs.omit("ping").middleware(
14+
const ClientRequestRpcs = McpSchema.ClientRequestRpcs.omit("ping").merge(McpSkills.LegacyRpcs).middleware(
1415
PublicMcpSchema.McpServerClientMiddleware
1516
).add(McpSchema.Ping)
1617

@@ -133,6 +134,7 @@ export const protocol = McpProtocol.make({
133134
handlerRpcs: AdapterRpcs,
134135
makeHandlers: (core, lifecycle) =>
135136
AdapterRpcs.of({
137+
...McpSkills.legacyHandlers(core),
136138
initialize: (request, { client }) =>
137139
lifecycle.initialize(McpSchema.protocolVersion, {
138140
protocolVersion: McpSchema.protocolVersion,

‎packages/effect/src/ai/internal/mcpRuntime.ts‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@ import * as HttpServerResponse from "../../http/HttpServerResponse.ts"
1313
import * as Layer from "../../Layer.ts"
1414
import type * as LogLevel from "../../LogLevel.ts"
1515
import * as Predicate from "../../Predicate.ts"
16-
import * as Rec from "../../Record.ts"
1716
import * as Result from "../../Result.ts"
1817
import * as RpcGroup from "../../rpc/RpcGroup.ts"
1918
import type * as RpcMessage from "../../rpc/RpcMessage.ts"
@@ -533,10 +532,6 @@ export const make = Effect.fnUntraced(function*(
533532
registrationPresence: options.core.registrationPresence
534533
}
535534
const handlerTarget = registry.handlerTarget(contextMap, installationContext)
536-
// Skills requires 2026-07-28, so sessionful revisions never declare it.
537-
const sessionfulExtensions = options.serverInfo.extensions === undefined
538-
? undefined
539-
: Rec.remove(options.serverInfo.extensions, McpSkills.EXTENSION_ID)
540535
for (const protocol of registry.protocols) {
541536
if (protocol.runtime._tag === "Stateless") {
542537
yield* protocol.installHandlers(options.core, undefined, handlerTarget)
@@ -560,7 +555,8 @@ export const make = Effect.fnUntraced(function*(
560555
: {}),
561556
...(presence.prompts ? { prompts: { listChanged: true } } : {})
562557
}
563-
if (sessionfulExtensions !== undefined) capabilities.extensions = sessionfulExtensions
558+
const extensions = McpSkills.declareExtension(options.serverInfo.extensions, presence.skills)
559+
if (extensions !== undefined) capabilities.extensions = extensions
564560
const initializePayload = PublicMcpSchema.Initialize.payloadSchema.make({
565561
protocolVersion,
566562
capabilities: profile.clientCapabilities,

‎packages/effect/src/ai/internal/mcpSkills.ts‎

Lines changed: 70 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
/**
2-
* The Skills extension (SEP-2640): wire schemas and the catalog behind a
3-
* static skill.
2+
* The Skills extension (SEP-2640): wire schemas, the catalog behind a static
3+
* skill, and the handlers shared by the sessionful adapters.
44
*/
55
import * as Cause from "../../Cause.ts"
66
import * as Digest from "../../crypto/Digest.ts"
@@ -15,6 +15,7 @@ import * as Schema from "../../Schema.ts"
1515
import * as PublicMcpSchema from "../McpSchema.ts"
1616
import type * as McpCore from "./mcpCore.ts"
1717
import * as McpProtocol from "./mcpProtocol.ts"
18+
import * as Legacy from "./mcpSchema/v2024_11_05.ts"
1819
import * as Stateless from "./mcpSchema/v2026_07_28.ts"
1920

2021
/**
@@ -58,6 +59,41 @@ const Skill = Schema.Struct({
5859
// invalid entry instead of rejecting the whole page.
5960
const ListedSkills = Schema.Array(Schema.Unknown)
6061

62+
/**
63+
* @internal
64+
*/
65+
export class LegacyListSkills extends Rpc.make("skills/list", {
66+
success: Schema.Struct({ ...Legacy.PaginatedResult.fields, skills: ListedSkills }),
67+
error: Legacy.McpError,
68+
payload: Schema.UndefinedOr(Legacy.PaginatedRequest)
69+
}) {}
70+
71+
/**
72+
* @internal
73+
*/
74+
export class LegacyGetSkill extends Rpc.make("skills/get", {
75+
success: Schema.Struct({ ...Legacy.ResultMeta.fields, skill: Skill }),
76+
error: Legacy.McpError,
77+
payload: { ...Legacy.RequestMeta.fields, uri: Schema.String }
78+
}) {}
79+
80+
/**
81+
* @internal
82+
*/
83+
export class LegacyReadResourceDirectory extends Rpc.make("resources/directory/read", {
84+
success: Schema.Struct({ ...Legacy.PaginatedResult.fields, resources: Schema.Array(Legacy.Resource) }),
85+
error: Legacy.McpError,
86+
payload: { ...Legacy.PaginatedRequest.fields, uri: Schema.String }
87+
}) {}
88+
89+
/**
90+
* The extension's methods on revisions before 2026-07-28, which have no
91+
* result caching attributes.
92+
*
93+
* @internal
94+
*/
95+
export class LegacyRpcs extends RpcGroup.make(LegacyListSkills, LegacyGetSkill, LegacyReadResourceDirectory) {}
96+
6197
/**
6298
* @internal
6399
*/
@@ -142,6 +178,38 @@ export const requireSkills = (core: McpCore.McpCore, method: string) =>
142178
(presence) => presence.skills ? Effect.void : Effect.fail(methodNotFound(method))
143179
)
144180

181+
/**
182+
* Handlers for {@link LegacyRpcs}, for the sessionful adapters.
183+
*
184+
* @internal
185+
*/
186+
export const legacyHandlers = (core: McpCore.McpCore) => ({
187+
"skills/list": Effect.fnUntraced(function*(request: typeof LegacyListSkills.payloadSchema.Type) {
188+
yield* requireSkills(core, "skills/list")
189+
const skills = yield* McpProtocol.listForClient(core.skills.list, request?.cursor)
190+
return { skills }
191+
}),
192+
"skills/get": Effect.fnUntraced(function*(request: typeof LegacyGetSkill.payloadSchema.Type) {
193+
yield* requireSkills(core, "skills/get")
194+
const client = yield* PublicMcpSchema.McpServerClient
195+
const skill = yield* core.skills.get(request.uri, McpProtocol.invocationFromClient(client)).pipe(
196+
Effect.mapError(McpProtocol.ProtocolError.fromFeature)
197+
)
198+
return { skill }
199+
}),
200+
"resources/directory/read": Effect.fnUntraced(function*(
201+
request: typeof LegacyReadResourceDirectory.payloadSchema.Type
202+
) {
203+
yield* requireSkills(core, "resources/directory/read")
204+
yield* McpProtocol.rejectCursor(request.cursor)
205+
const client = yield* PublicMcpSchema.McpServerClient
206+
const resources = yield* core.skills.readDirectory(request.uri, McpProtocol.invocationFromClient(client)).pipe(
207+
Effect.mapError(McpProtocol.ProtocolError.fromFeature)
208+
)
209+
return { resources }
210+
})
211+
})
212+
145213
// =============================================================================
146214
// Static skills
147215
// =============================================================================

‎packages/effect/test/ai/McpClient.test.ts‎

Lines changed: 51 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -901,55 +901,62 @@ describe("McpClient skills", () => {
901901
}))
902902
)
903903

904-
it.effect("should list, get and browse skills and read their files verified", () =>
905-
Effect.gen(function*() {
906-
const client = yield* connect(McpProtocol.v2026_07_28, skillsServerLayer, { skills: true })
907-
const skills = yield* client.listSkills()
908-
assert.deepStrictEqual(skills.map((skill) => skill.uri).sort(), [
909-
"skill://acme/invoices/SKILL.md",
910-
"skill://acme/refunds/SKILL.md"
911-
])
912-
const refunds = yield* client.getSkill({ uri: "skill://acme/refunds/SKILL.md" })
913-
assert.deepStrictEqual(refunds, skills.find((skill) => skill.uri === refunds.uri))
914-
assert.deepStrictEqual(refunds.frontmatter, { name: "refunds", description: "Process refunds" })
915-
916-
const children = yield* client.readResourceDirectory({ uri: "skill://acme/refunds" })
917-
assert.deepStrictEqual(children.map((child) => child.name), ["refunds", "assets", "references"])
904+
for (const protocol of protocols) {
905+
describe(protocol.protocolVersion, () => {
906+
it.effect("should list, get and browse skills and read their files verified", () =>
907+
Effect.gen(function*() {
908+
const client = yield* connect(protocol, skillsServerLayer, { skills: true })
909+
const skills = yield* client.listSkills()
910+
assert.deepStrictEqual(skills.map((skill) => skill.uri).sort(), [
911+
"skill://acme/invoices/SKILL.md",
912+
"skill://acme/refunds/SKILL.md"
913+
])
914+
const refunds = yield* client.getSkill({ uri: "skill://acme/refunds/SKILL.md" })
915+
assert.deepStrictEqual(refunds, skills.find((skill) => skill.uri === refunds.uri))
916+
assert.deepStrictEqual(refunds.frontmatter, { name: "refunds", description: "Process refunds" })
917+
918+
const children = yield* client.readResourceDirectory({ uri: "skill://acme/refunds" })
919+
assert.deepStrictEqual(children.map((child) => child.name), ["refunds", "assets", "references"])
920+
921+
assert(refunds.resources !== "dynamic")
922+
for (const { uri } of refunds.resources) {
923+
const result = yield* client.readSkillResource({ skill: refunds, uri })
924+
assert.strictEqual(result.contents[0].uri, uri)
925+
}
926+
const logo = yield* client.readSkillResource({ skill: refunds, uri: "skill://acme/refunds/assets/logo.png" })
927+
assert.deepStrictEqual("blob" in logo.contents[0] ? logo.contents[0].blob : undefined, PNG)
928+
}))
918929

919-
assert(refunds.resources !== "dynamic")
920-
for (const { uri } of refunds.resources) {
921-
const result = yield* client.readSkillResource({ skill: refunds, uri })
922-
assert.strictEqual(result.contents[0].uri, uri)
923-
}
924-
const logo = yield* client.readSkillResource({ skill: refunds, uri: "skill://acme/refunds/assets/logo.png" })
925-
assert.deepStrictEqual("blob" in logo.contents[0] ? logo.contents[0].blob : undefined, PNG)
926-
}))
930+
it.effect("should not call the extension's methods on a server that does not declare it", () =>
931+
Effect.gen(function*() {
932+
const client = yield* connect(protocol, serverLayer, { skills: true })
933+
assert.deepStrictEqual(yield* client.listSkills(), [])
934+
for (
935+
const effect of <ReadonlyArray<Effect.Effect<unknown, McpClientError.McpClientError>>> [
936+
client.getSkill({ uri: "skill://acme/refunds/SKILL.md" }),
937+
client.readResourceDirectory({ uri: "skill://acme" })
938+
]
939+
) {
940+
assert.strictEqual((yield* Effect.flip(effect)).reason._tag, "UnsupportedError")
941+
}
942+
}))
943+
})
944+
}
927945

928-
it.effect("should not call the extension's methods on a server that does not declare it", () =>
946+
it.effect("should declare the extension only when enabled", () =>
929947
Effect.gen(function*() {
930-
const client = yield* connect(McpProtocol.v2026_07_28, serverLayer, { skills: true })
931-
assert.deepStrictEqual(yield* client.listSkills(), [])
932-
for (
933-
const effect of <ReadonlyArray<Effect.Effect<unknown, McpClientError.McpClientError>>> [
934-
client.getSkill({ uri: "skill://acme/refunds/SKILL.md" }),
935-
client.readResourceDirectory({ uri: "skill://acme" })
936-
]
937-
) {
938-
assert.strictEqual((yield* Effect.flip(effect)).reason._tag, "UnsupportedError")
948+
for (const skills of [true, false]) {
949+
const { sent } = yield* scriptedHttp(
950+
(message) => scriptedReply(McpProtocol.v2025_11_25, message),
951+
{ protocol: McpProtocol.v2025_11_25, extensions: { skills } }
952+
)
953+
const initialize = sent.map(({ message }) => message).find((message) => methodOf(message) === "initialize")
954+
assert.deepStrictEqual(
955+
(initialize as McpSchema.JsonRpcRequest).params?.capabilities,
956+
skills ? { extensions: { "io.modelcontextprotocol/skills": {} } } : {}
957+
)
939958
}
940-
}))
941959

942-
it.effect("should reject the extension on legacy protocols", () =>
943-
Effect.gen(function*() {
944-
const error = yield* scriptedHttp(
945-
(message) => scriptedReply(McpProtocol.v2025_11_25, message),
946-
{ protocol: McpProtocol.v2025_11_25, extensions: { skills: true } }
947-
).pipe(Effect.flip)
948-
assert.strictEqual(error.reason._tag, "UnsupportedError")
949-
}))
950-
951-
it.effect("should declare the extension only when enabled", () =>
952-
Effect.gen(function*() {
953960
const discoveredCapabilities = (
954961
sent: ReadonlyArray<{ readonly message?: McpSchema.JsonRpcMessage | undefined }>
955962
) => {

0 commit comments

Comments
 (0)