Skip to content

fix(devframe): use WebMCP draft tool hints and honor abort signal - #496

Merged
antfu merged 2 commits into
mainfrom
fix/webmcp-spec-hints
Nov 18, 2026
Merged

antfu merged 2 commits into
mainfrom
fix/webmcp-spec-hints

Conversation

@antfubot

Copy link
Copy Markdown
Collaborator

Summary

The WebMCP projection in devframe/client used MCP's annotation names. The current WebMCP draft defines its own ToolAnnotations (readOnlyHint, consequentialHint, untrustedContentHint, debugging) and has no destructiveHint. WebIDL drops unknown dictionary members, so browsers that follow the draft never saw that a tool was destructive.

Changes in registerWebMcpTools:

  • read sets readOnlyHint, destructive sets consequentialHint, and every tool sets debugging: true (devframe tools are developer tooling, the case the draft names).
  • title is set at the top level of the tool, as in the draft's ModelContextTool.
  • destructiveHint and annotations.title stay, for earlier drafts and polyfills that follow the MCP shape.
  • execute(input, { signal }) now honors the signal. An aborted call rejects with signal.reason. A call whose signal is already aborted does not run the handler. A running handler cannot be stopped, so its late result is dropped.

A separate fix in node/client-agent.ts: when a tab re-syncs its tools, the check compared only tool ids. A changed description or input schema under the same id did not notify MCP clients that the tool list changed. It now compares the whole manifest.

Spec reference: WebMCP draft index.bs (ToolAnnotations, ModelContextTool, execute(input, { signal })).

User prompts

Model: Claude Opus 5.5 in Claude Code (Paseo).

  • Asked what devframe can learn from https://ui-sdk.dev/ and whether to adopt it.
  • Chose deeper research on its agent bridge and WebMCP.
  • Chose the quick fixes from that research: WebMCP hints, abort signal, and the re-sync check.
  • Asked for a PR without the research notes.

Verification

  • pnpm vitest run packages/devframe/src/client/webmcp.test.ts packages/devframe/src/node/__tests__/client-agent.test.ts: 21 passed. New tests cover the draft hints, consequentialHint on destructive tools, rejection on abort (during a call and before it), and a notify on a changed manifest under the same id.
  • pnpm lint, pnpm knip, pnpm typecheck, pnpm build: pass.
  • pnpm test: 1871 passed, 2 failed. The failures are adapters/__tests__/dev.test.ts ("does not share a port held on 127.0.0.1") and adapters/__tests__/initiate.test.ts ("ws.sidecar on localhost"), with Proxy response (502) from the sandbox HTTP proxy. Both fail the same way on main (06d41e39) with this diff removed.
  • The devframe/client type snapshot is updated for the new optional fields and the execute options argument.
  • Not verified: behavior in a real browser with WebMCP (Chrome origin trial).

This PR was written with an AI agent. The human gave the task and chose the scope. The human has not reviewed the diff yet.

@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated
devframe Ignored Ignored Nov 18, 2026 12:14am UTC

@github-actions

Copy link
Copy Markdown

👁️‍🗨️ Review this pull request with grouped, summarized diffs at:
👉 https://pulls.review/gh/devframes/devframe/496?from=github-actions[bot]

raw result

💭 analyzed by vercel-ai-gateway/anthropic/claude-sonnet-5
🕰️ 2026-11-18 00:15 UTC
🔗 head daf0a0c
🤖 automated by pulls.review

{
  "headSha": "daf0a0c94b669cacec979e9d9f9e638f9b7ddf87",
  "result": {
    "overallSummary": "Aligns devframe's WebMCP tool projection with the current WebMCP draft spec: using the draft's own ToolAnnotations names (so browsers that drop unknown dictionary members still see safety hints) and honoring the execute abort signal, plus a related fix so tool manifest changes under the same id correctly notify MCP clients.",
    "groups": [
      {
        "key": "webmcp-hints",
        "label": "WebMCP draft hints and abort",
        "summary": "Switches the WebMCP tool projection from MCP-only annotation names to the current WebMCP draft's ToolAnnotations (readOnlyHint, consequentialHint, debugging), while keeping the older MCP-shaped fields for compatibility, and makes execute honor an abort signal so a cancelled call rejects with the signal's reason instead of being left dangling.",
        "category": "api",
        "filePaths": [
          "packages/devframe/src/client/webmcp.ts"
        ],
        "fileNotes": [
          {
            "path": "packages/devframe/src/client/webmcp.ts",
            "text": "raceAbort rejects on abort but cannot stop the underlying handler; its late result or error is simply discarded.",
            "critical": true
          }
        ]
      },
      {
        "key": "client-agent-sync",
        "label": "Full manifest comparison on sync",
        "summary": "Fixes a missed-notification bug: re-sync previously compared only tool ids, so a changed description or input schema under the same id did not notify MCP clients. Now the whole manifest is compared via JSON equality.",
        "category": "api",
        "filePaths": [
          "packages/devframe/src/node/client-agent.ts"
        ],
        "critical": true
      },
      {
        "key": "tests",
        "label": "Tests and type snapshot",
        "summary": "Covers the new draft hints, consequential/destructive mapping, abort-before-call and abort-during-call behavior, and the manifest-change re-sync notification; updates the generated type snapshot for the new optional fields and execute signature.",
        "category": "tests",
        "filePaths": [
          "packages/devframe/src/client/webmcp.test.ts",
          "packages/devframe/src/node/__tests__/client-agent.test.ts",
          "tests/__snapshots__/tsnapi/devframe/client.snapshot.d.ts"
        ]
      },
      {
        "key": "docs",
        "label": "Docs update",
        "summary": "Documents the new WebMCP hint names, the debugging flag, and the abort/cancellation behavior for browser-side tools.",
        "category": "docs",
        "filePaths": [
          "docs/content/1.guide/15.agent-native.md"
        ]
      }
    ],
    "schemaVersion": 1,
    "source": "llm",
    "generatedAt": "2026-11-18T00:15:31.723Z",
    "model": "vercel-ai-gateway/anthropic/claude-sonnet-5",
    "locale": "en"
  }
}

@antfu
antfu merged commit 50a0147 into main Nov 18, 2026
15 of 16 checks passed
@antfu
antfu deleted the fix/webmcp-spec-hints branch November 18, 2026 00:25
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.

2 participants