Skip to content

feat(server): serve the Skills extension through extensions: [skills] - #3066

Open
mattzcarey wants to merge 6 commits into
mainfrom
feat/skills-as-extension
Open

mattzcarey wants to merge 6 commits into
mainfrom
feat/skills-as-extension

Conversation

@mattzcarey

@mattzcarey mattzcarey commented Oct 22, 2026 •

Copy link
Copy Markdown
Member

SkillsExtension is now a { id, setup(ctx) } server extension, so new McpServer(info, { extensions: [skills] }) serves it. SkillsExtension.attach(server) still works and is deprecated; it will be removed in a later minor release.

const skills = await loadSkills('./skills');
const server = new McpServer(info, { extensions: [skills] });

#2820 added extensions, which takes only { id, setup(ctx) }, and Skills (#3047) shipped with attach(mcp), so it couldn't go in that option:

  • setup declares the capability with ctx.capability and registers the skills methods with ctx.setRequestHandler, so a second skills extension fails the duplicate-id check and a method another extension serves is refused.
  • attach runs the same setup on a constructed server and keeps its rules: before connecting, one skills extension per server, and a repeat for the same server does nothing.
  • With extensions, the skills resource template is registered at construction, so an application ResourceTemplate for skill:// URIs comes after it. A fixed-URI resource still wins at its URI.
  • setup is @experimental: the wiring may change in a minor release while the extensions SEPs settle. The rest of the Skills API is unchanged.
  • Docs, guides, examples, the agent skill, the conformance server and the test fixtures use extensions.

pnpm check:all, the build, the unit, integration and e2e suites and the client and extensions conformance suites ran on Node 24.

@mattzcarey
mattzcarey requested a review from a team as a code owner October 22, 2026 11:22
@changeset-bot

changeset-bot Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: ddff359

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages
Name Type
@modelcontextprotocol/server Minor
@modelcontextprotocol/client Minor
@modelcontextprotocol/codemod Minor
@modelcontextprotocol/core Minor
@modelcontextprotocol/server-legacy Minor
@modelcontextprotocol/core-internal Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@mattzcarey
mattzcarey added this pull request to stack #3067 October 22, 2026 11:22
@pkg-pr-new

pkg-pr-new Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@3066

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@3066

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@3066

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@3066

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@3066

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@3066

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@3066

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@3066

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@3066

commit: ddff359

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Beyond the inline nits, I also checked two things in the setup rewrite and ruled them out: declaring directoryRead before the handlers are registered cannot leave a server advertising skills it does not serve, because installServerExtensions runs inside the McpServer constructor and any throw from setup (duplicate id, handler collision, taken template name) fails construction; and resources/directory/read is not in the modern codec's core method list, so ctx.setRequestHandler accepts it rather than refusing it as a core method.

Extended reasoning...

The change migrates the unreleased Skills extension from attach(mcp) to the ServerExtension setup(ctx) shape and updates every call site (docs, changeset, examples, conformance server, integration fixtures, unit tests); the only behavioural code is in packages/server/src/ext/skills/extension.ts and it delegates the former guards to the installer. It touches no auth, crypto or input-handling surface. The three inline findings are test and comment nits, and the repository's CODEOWNERS assigns every path to the SDK team, so a human look is still warranted.

Additional findings (outside the current diff — GitHub can't attach inline comments there):

  • 🟡 packages/server/test/server/barrelClean.test.ts — nit: maintainers lose the declaration guard against a public setup hook, because this test still searches for the old name afterAttach and now passes vacuously. The hook was renamed to afterSetup in packages/server/src/ext/skills/extension.ts:63, but packages/server/test/server/barrelClean.test.ts:173 still matches /\bafterAttach\b/, which no file contains. Fix: match the current hook name (/\bafterSetup\b/) in the dist declaration sweep, and update the comment at line 168 that still says registration "will not go through attach()". [also at: packages/server/src/ext/skills/extension.ts:63 - nit: renaming the hook afterAttach to afterSetup leaves the declaration-file guard in packages/server/test/server/barrelClean.test.ts:173 checking a name that no longer exists, so it no longer guards anything.] (Finding ID: f-8ebf9264)

    Why this was flagged

    The diff renames the module-level WeakMap afterAttach to afterSetup at packages/server/src/ext/skills/extension.ts:63. packages/server/test/server/barrelClean.test.ts:167-176 is the test that walks the built ext/skills/index.d.mts declaration graph and asserts no file mentions the hook name, so subclasses get no public hook to override. It still matches /\bafterAttach\b/ at line 173. On the base branch that name was the real hook, so the test would fail if the hook leaked into declarations; after merging, nothing is named afterAttach, so the assertion can never fail and a future afterSetup leaking into the public .d.mts goes unnoticed. The unit test in extension.test.ts checks only 'afterSetup' in SkillsExtension.prototype at runtime, not the shipped declarations. The comment at line 168 also still says registration "will not go through attach()", which no longer describes the code.

    Verification: Any future change that leaks the renamed hook into the ext/skills .d.mts graph would now go undetected. The diff renames the WeakMap in packages/server/src/ext/skills/extension.ts:63, but packages/server/test/server/barrelClean.test.ts:173 is unchanged from the base and still asserts expect.stringMatching(/\bafterAttach\b/). The loop at lines 171-175 can never match and passes vacuously.

@claude claude Bot added the v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes label Oct 23, 2026
@mattzcarey
mattzcarey removed this pull request from stack #3067 October 23, 2026 13:59
@mattzcarey
mattzcarey added this pull request to stack #3112 October 27, 2026 09:29
@mattzcarey
mattzcarey force-pushed the feat/skills-as-extension branch from a270679 to 16c4354 Compare October 27, 2026 12:18

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Beyond the inline findings, I also checked two things that turned out fine:

  • Dropping the explicit registerCapabilities call does not lose the {} skills capability for sources without readDirectory: installServerExtensions (packages/server/src/server/extension.ts:104) declares { [id]: {} } before each setup runs.
  • The e2e id rename to typescript:skills:extension:one-per-server is consistent: its one verifies() citation (test/e2e/scenarios/skills.test.ts:893) was updated, no reference to the old id remains, and the only .attach( text left in the repo is the changeset's migration note.
Extended reasoning...

Findings are posted inline, so this is only a note on what else was examined: the capability declaration when directoryRead is absent is covered by the extension framework, and the renamed e2e requirement id has no stale citations. The change touches the public SkillsExtension surface (removing attach) and no auth or other security-sensitive code; the inline finding about removing a released API in a minor release is the reason this is not an approval.

Findings marked 🟡 are optional suggestions and need no follow-up push.

Still open from earlier reviews (2):

  • Unresolved: 2 minor or pre-existing.

Comment thread test/e2e/requirements.ts Resolved
@mattzcarey
mattzcarey force-pushed the feat/skills-as-extension branch from 16c4354 to cf69deb Compare October 27, 2026 12:53

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 other optional suggestions (nits or notes on pre-existing code) were found and not posted.

Findings marked 🟡 are optional suggestions and need no follow-up push.

Still open from earlier reviews (4):

  • 🔴 skills/mcp-typescript-sdk-skills/SKILL.md:49 — Agents following this skill on the released 2.4.0 SDK now write { extensions: [skills] }, which that version does not s…
  • Also unresolved: 3 minor or pre-existing.

If you have decided not to act on one of these findings, resolve its thread (a reply alone leaves it open) and the next review stops counting it. To review this commit again now, use Re-run on its "Claude Code Review" check.

@mattzcarey
mattzcarey force-pushed the feat/skills-as-extension branch from cf69deb to 95e3688 Compare October 27, 2026 13:55

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new blocking issues. 1 optional suggestion (a nit or a note on pre-existing code) was found and not posted.

Still open from earlier reviews (4):

  • Unresolved: 4 minor or pre-existing.

@mattzcarey
mattzcarey force-pushed the feat/skills-as-extension branch from 95e3688 to 1116ccd Compare October 27, 2026 14:09

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new blocking issues. 1 optional suggestion (a nit or a note on pre-existing code) was found and not posted. Nothing in this review needs a push before merging.

@mattzcarey
mattzcarey force-pushed the feat/skills-as-extension branch from 1116ccd to 7ff034c Compare October 27, 2026 14:41
@mattzcarey
mattzcarey force-pushed the feat/skills-as-extension branch from 7ff034c to 575e634 Compare November 5, 2026 14:31

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new blocking issues. 1 optional suggestion (a nit or a note on pre-existing code) was found and not posted. Nothing in this review needs a push before merging.

@mattzcarey
mattzcarey force-pushed the feat/skills-as-extension branch from 575e634 to cec5642 Compare November 18, 2026 15:24

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new blocking issues. 1 optional suggestion (a nit or a note on pre-existing code) was found and not posted. Nothing in this review needs a push before merging.

Base automatically changed from feat/server-extensions to main November 18, 2026 16:47
@mattzcarey
mattzcarey force-pushed the feat/skills-as-extension branch from cec5642 to e674dca Compare November 18, 2026 16:56

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new blocking issues. 1 optional suggestion (a nit or a note on pre-existing code) was found and not posted. Nothing in this review needs a push before merging.

SkillsExtension is now a ServerExtension: setup(ctx) declares the
capability and registers the skill resource template and the skills
methods through the extension context, so the SDK checks the id and the
method names. attach(mcp) and its guards (one per server, before
connecting, idempotent) are gone; the extensions option covers them.
SkillCatalog tracks every server it is set up on for reload().
The move from attach to setup dropped the only test of the constructor's
cacheHint validation, which is unchanged.
…e minor

attach shipped in 2.4.0. It now sets the extension up through the same
setup as the extensions option and keeps its rules: before connecting,
idempotent per server, one skills extension per server, and a refused or
failed attach leaves no capability behind. Restores its e2e requirement,
and the agent skill falls back to attach on releases without the
extensions option.
…e order in the changeset

- The agent skill tells 2.4.0 projects to use attach, and says it keeps
  working after an upgrade; the factory note no longer says attach.
- The app-resource-first requirement holds for fixed-URI resources only:
  the skills template is registered at construction, before any template
  the application adds. The changeset now says so.
- Drop the JSDoc on a test helper.
The wiring may change in a minor release while the extensions SEPs settle;
the Skills API that shipped before it is unchanged.
…extension in extensions

It threw 'another skills extension is already attached', though attaching the
same extension again is documented to do nothing.
@mattzcarey
mattzcarey force-pushed the feat/skills-as-extension branch from e674dca to ddff359 Compare November 19, 2026 00:18

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new blocking issues. 2 optional suggestions (nits or notes on pre-existing code) were found and not posted. Nothing in this review needs a push before merging.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant