Repository navigation
hub-mcp Phase 5: MCP-native surfaces (bd-rpra6kpq) - #798
Open
shikokuchuo wants to merge 3 commits into
Open
shikokuchuo wants to merge 3 commits into
shikokuchuo wants to merge 3 commits into
Conversation
Contributor
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
shikokuchuo
added this pull request to stack #792
October 7, 2026 09:01
…9/BP-17; bd-rpra6kpq)
Phase 5 of the elevate-quarto-hub-mcp plan.
BP-5 resources: every file of every connected project is an MCP
resource. Q-2 resolved — hub://project/<indexDocId>/<path>[?server=…]:
doc id in the PATH (RFC 3986 host normalizers lowercase; doc ids are
case-sensitive), the literal segment leaves room for other kinds, and
?server= mirrors the share-URL grammar for foreign-hub projects. The
Phase 4 ephemeral blob URI is aligned to the contract.
- resources/list paginates (nextCursor, PAGE_SIZE 100) across all
connected projects, sorted by URI — hand-rolled on the low-level
Server because the SDK's built-in list handler doesn't paginate.
- resources/read serves text and base64 blob contents; templates/list
advertises hub://project/{indexDocId}/{path}.
- Dual-era subscriptions: modern (2026-07-28) subscriptions/listen is
entry-routed, so the bridge emits every change; legacy (2025-11-25)
resources/subscribe is tracked per connection and gates delivery
(the SDK ships no legacy subscribe handler). createServer gains an
era option fed by serveStdio's factory context.
- ConnectionManager.onProjectEvent seam (file added/changed/removed +
connect/disconnect lifecycle); list_changed debounced 150 ms so a
project connect's per-file adds collapse into one emission.
- resource_link blocks on every write-tool result (write_file,
create_file, patch_file, rename_file → new URI, restore_file_version).
- Best-effort fan-out: sends guarded by isConnected(), the close-race
NotConnected swallowed — caught by verify as 82 unhandled rejections
with all assertions passing; regression test pins it.
BP-6 prompts: review-draft (embeds the draft as an embedded resource
under its hub:// URI), collaborate-with-human, safe-edit-workflow,
fix-render-errors — gated by mode (read-only drops the edit/render
pair; fix-render-errors requires --allow-render). Skills-over-MCP
deferred: prompts are the portable baseline.
BP-9 icons: the Quarto mark (data-URI inlined) on Implementation,
prompts, and the resource template — deliberately not per-tool (~15 KB
of agent context per tools/list for chrome; hosts fall back to the
server icon).
BP-17: long private cache hints on prompts/list and
resources/templates/list (static); resources/list|read keep no-cache
(live data). tools/prompts now honestly declare listChanged: false
(the SDK's registration default claimed true for static lists).
Tests: 17 legacy-era resource/prompt tests, 3 modern-era stdio tests
(2026-07-28-pinned SDK client over the real entry), 2 capability/
wire-schema conformance tests. Suite: 58 files, 527 passed + 3 skips.
Eval suite (15 tasks): 15/15 PASS, median 5 turns — no regression from the Phase 5 surfaces (results/2026-10-07T08-19-49, transcripts committed). Plan file records the Phase 5 completion: the Q-2 URI contract decision, the SDK-v2.3.1 findings that shaped the design (no paginating resources/list, no legacy subscribe handler, entry-owned modern listen routing), the both-eras e2e transcript against the real q2 mcp, and the verify catch (82 unhandled rejections from the debounce close-race, fixed at the root). Braid snapshot refreshed (bd-chtwjljk filed for the pre-existing README staleness).
- docs/tools/q2-mcp.qmd: warn users to treat hub:// resource URIs like
share links — they carry the project's automerge doc id, a bearer
capability on no-auth hubs; don't paste them or transcripts
containing them into public channels.
- docs/tools/q2-mcp.qmd: escape a bare @ ("\@-mention") — pre-existing
parse error that aborted the whole docs site render ("Rendered 0 of
329 files"); site render verified green again. Nothing in verify/CI
renders docs/, so the breakage was invisible — filed bd-drl44ho4.
- plan: record the Q-2 security considerations — doc id as bearer
capability, automatic egress into transcripts/logs vs. deliberate
share-URL distribution, leak asymmetry (standing access, no
rotation), ?server= completing the locator+capability pair,
injection-driven foreign dial-out residual risk.
- braid: file bd-zc3ubxiv (foreign-hub consent gate, with
implementation assessment — left open, not scheduled) and
bd-drl44ho4; export skein snapshot.
shikokuchuo
force-pushed
the
braid/bd-rpra6kpq-hub-mcp-phase-5-mcp-native-surfaces
branch
from
October 7, 2026 13:45
489286e to
cc9cdf0
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase 5 of the hub-mcp elevation plan (bd-rpra6kpq), stacked on #797. The MCP server now speaks two more parts of the MCP protocol: resources and prompts. Design and full record:
claude-notes/plans/2026-10-05-elevate-quarto-hub-mcp.md.Resources (BP-5)
hub://project/<indexDocId>/<path>, with?server=when a share URL routed the project to a different hub (Q-2). The document id lives in the path, because URI normalizers lowercase the host and document ids are case-sensitive.resources/listpaginates withnextCursor(100 entries per page) and lists the files of every connected project in a stable order.resources/readreturns text contents, or base64 blob contents for binaries.subscriptions/listen. On the 2025-11-25 protocol the client sendsresources/subscribe. Both receivenotifications/resources/updatedwhen the file changes, andnotifications/resources/list_changedwhen files are added or removed.resource_linkblock to the file it touched. Hosts can use the link to attach or open the file.Prompts (BP-6)
review-draftreads one file and walks the agent through a careful review. The draft is embedded under itshub://URI.collaborate-with-humanteaches the etiquette for editing a project a human is working in.safe-edit-workflowteaches the read → patch → confirm loop, withexpected_hashdiscipline.fix-render-errorsteaches the render → diagnose → patch loop. It exists only with--allow-render, like therendertool itself. Read-only mode hides the two editing prompts.Other changes
tools/list.prompts/listandresources/templates/listcarry long cache hints, because both lists are fixed at startup (BP-17). The tools and prompts capabilities now declarelistChanged: false, matching that fact.instructionsdescribe the new surfaces, and the docs page gains a Resources and prompts section.Verification
cargo xtask verify: all legs pass. The MCP suite: 527 passed, 3 skipped.