Skip to content

feat(desktop): relay MCP server skills to threads - #3707

Merged
Harold Hunt (huntharo) merged 3 commits into
mainfrom
feat/mcp-skills-passthrough
Nov 14, 2026
Merged

Harold Hunt (huntharo) merged 3 commits into
mainfrom
feat/mcp-skills-passthrough

Conversation

@huntharo

@huntharo Harold Hunt (huntharo) commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Summary

PwrAgent-managed MCP connections now pass an upstream server's skills through to thread agents. This is the first step toward adding GitHub's MCP server. github/github-mcp-server#3685 added 18 workflow skills, offered through the io.modelcontextprotocol/skills extension. Turning them on also removes the server's instructions, with no fallback for clients that don't support the extension.

Before this change, the native bridge forwarded only tools, resources and prompts. A thread connected to such a server saw neither the instructions nor the skills.

What changed

  • mcp-skills-relay.ts (new, pure): detects the extension, lists its three methods, and builds a bounded skills index (skillsAwareInstructions).
    • A server's own instructions are always returned unchanged.
    • When a server offers skills and sends no instructions, the bridge's instructions become an index of at most 8,000 characters. Each line gives a skill's name, its description, and the URI of its SKILL.md. Hosts that don't support the extension, which is most of them today, can read that file through their normal MCP resource reader.
    • Entries without a skill:// URI or a name are dropped, and a repeated skill is listed once. Text is reduced to one line and capped. When the index is partial, it ends by saying so.
  • Owner (mcp-connection-gateway-service.ts):
    • describe reports skills. When the server sent no instructions and offers resources, it builds the index from up to four pages of skills/list.
    • The index read has its own budget: at most 5 seconds, and at most half of what the bridge's startup has left. If it fails or stalls, the session still opens with whatever was read, possibly no index. The failure is logged without any upstream text.
    • skills/list, skills/get and resources/directory/read are forwarded only to a server that advertised the extension. Any other server gets MethodNotFound.
  • Bridge (mcp-connection-bridge-entry.ts): declares the extension, copied from the upstream server's declaration, and registers handlers for the three methods. Parameters and results pass through unchanged.
  • PWRAGENT_SKILLS_EXTENSION now re-exports the shared constant.

Catching the next silent drop

The bridge forwards only the capabilities it declares, so one it doesn't relay produces no error anywhere. That's how skills went missing. This PR makes that a recorded decision:

  • mcp-bridge-capabilities.ts lists every MCP server capability as relayed or not, with a reason. Currently not relayed: logging, completions, tasks and experimental. It also names the extensions the bridge relays.
  • mcp-bridge-capabilities.test.ts fails when the MCP SDK knows a capability the table doesn't, so an SDK upgrade has to classify each new one.
  • An oracle test (mcp-connection-bridge-entry.test.ts) gives the bridge a server that advertises everything. It checks that what the bridge declares, plus what the table calls unrelayed, adds up to exactly what the server advertised. Against the bridge before this PR, it fails on extensions:io.modelcontextprotocol/skills.
  • At run time, the owner logs once per connection anything a real server advertises that threads won't see, including extensions nobody has classified yet.

Tests

  • mcp-skills-relay.property.test.ts (fast-check) checks five rules against generated input, including lists that repeat skills:
    • a server's own instructions are never rewritten;
    • the index stays within its size limit;
    • the index names only skills the server actually listed, one per line, with no control characters;
    • each skill appears at most once;
    • the closing "more skills" line appears exactly when the index is partial.
  • mcp-connection-bridge-entry.test.ts:
    • A skills server's extension is offered, and all three methods are forwarded with their parameters. This test fails against the previous bridge: no extension is offered.
    • A server without skills offers no extension, and the owner is never asked for skills.
  • mcp-stdio-connections.test.ts: end to end against a real stdio fixture process.
    • A skills server with no instructions: both pages are indexed, and the skill they share appears once.
    • A server that offers no skills keeps its instructions and refuses skills/list.
    • A server whose skills/list stalls still answers describe within its startup deadline, without an index. Before the review fixes, this test and the next one failed against this branch.
    • A skills server without the resources capability gets no index.

Verification

  • pnpm test: the full suite ran (1,915 files and 27,693 tests passed), as did the three test files above.
  • pnpm lint:oxlint, pnpm lint:oxlint:typed, pnpm typecheck, pnpm lint:boundaries and pnpm lint:codex-storage all pass.
  • pnpm --filter @pwragent/desktop build passes, including the main-bundle boundary check. The built mcp-connection-bridge.js loads and runs.

A server can publish workflow skills through the
io.modelcontextprotocol/skills extension, and may then stop sending
instructions. GitHub's MCP server does that once skills are on
(github/github-mcp-server#3685). PwrAgent's native bridge forwarded only
tools, resources and prompts, so a thread saw neither the instructions
nor the skills.

The bridge now advertises the extension when the upstream server does,
and forwards skills/list, skills/get and resources/directory/read. When
the server offers skills and sends no instructions, its instructions
become a bounded index of its skills, naming each SKILL.md, so hosts
that do not speak the extension can still find and read them. A
server's own instructions are never rewritten.
Review fixes for the skills relay:

- The index's skills/list read spent the bridge's whole startup deadline,
  so a server whose skills/list stalled made the bridge exit and the
  thread lose every tool. It now has its own budget, at most 5 s and at
  most half of what startup has left, and degrades to no index.
- The index read only the first page. It now reads up to four, keeps
  what it read if a later page fails, and lists a repeated skill once.
- No index is built for a server without the resources capability: the
  bridge serves no resources/read, so the agent could not follow it.
- The caller's own cancel now propagates instead of being logged as an
  upstream failure.
- The closing line of a partial index no longer points hosts that lack
  the extension at a skills/list call they cannot make.
- Removed the unused isMcpSkillsMethod helper.
The bridge relays only what it declares, so a capability it does not
relay produces no error anywhere. The skills extension was missing that
way until #3707.

- mcp-bridge-capabilities.ts lists every server capability as relayed
  or not, with the reason, and names the extensions the bridge relays.
- A test fails when the MCP SDK knows a capability the table does not,
  so an SDK upgrade must classify it.
- An oracle test checks that, for a server advertising everything, the
  bridge's declarations and the table's unrelayed list split the
  server's capabilities exactly. Against the bridge before #3707 it fails
  on extensions:io.modelcontextprotocol/skills.
- The owner logs, once per connection, what a real server advertised that
  threads will not see, including unclassified extensions.
@huntharo
Harold Hunt (huntharo) merged commit 653a120 into main Nov 14, 2026
28 checks passed
@huntharo
Harold Hunt (huntharo) deleted the feat/mcp-skills-passthrough branch November 14, 2026 18:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant