mirror of https://github.com/CopilotKit/CopilotKit.git synced 2026-09-14 16:26:20 +08:00

Files

T

Alem Tuzlak 8a5a976f1a feat(core): expose webmcp-enabled frontend tools to browser agents (#6847 )

## What does this PR do?

Hooks can now expose a frontend tool to browser agents through the
WebMCP browser API, next to the normal agent registration. Set `webmcp:
true`, or pass `{ annotations }` for WebMCP hints:

```ts
useFrontendTool({
  name: "searchOrders",
  description: "Search the signed-in user's orders by status",
  parameters: z.object({ status: z.enum(["open", "shipped", "delivered"]) }),
  handler: async ({ status }) => searchOrders(status),
  webmcp: { annotations: { readOnlyHint: true } },
});
```

How it works:

1. `FrontendTool` in `@copilotkit/core` gains the `webmcp` option. A new
`WebMCPRegistry` registers the tool on `document.modelContext` with its
name, description, input schema, and annotations. `execute` runs the
tool's own handler. The handler context has no `agent` there.
2. Every tool registry change in `RunHandler` reconciles the WebMCP
registrations. The same availability rules apply as for the agent tool
list. Removing a tool aborts its registration signal, and the browser
then unregisters it.
3. Each adapter picks the option up from core: v2 `useFrontendTool`
(React, Vue, React Native), the v1 `useCopilotAction` and
`useFrontendTool` wrappers (React, Vue), and Angular's
`registerFrontendTool`. Where WebMCP is not available (SSR, React
Native, browsers without the API), registration is a no-op.

The `webmcp` prop is documented on the React, Vue, and Angular reference
pages in shell-docs.

## Related PRs and Issues

- None.

## Checklist

- [x] I have read the [Contribution
Guide](https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md)
- [x] If the PR changes or adds functionality, I have updated the
relevant documentation
- [ ] "Allow edits by maintainers" is checked (lets us help iterate on
your PR directly — faster turnaround for everyone)

## Testing

**Commands run**

- `pnpm nx run-many -t check-types
--projects=@copilotkit/core,@copilotkit/react-core,@copilotkit/vue,@copilotkit/angular`
— all pass.
- Full test suites: core (829 tests), vue (103), and angular pass.
react-core passes standalone (1589 tests). Under the lefthook pre-commit
hook, react-core flakes on pre-existing e2e tests (A2UI, MCP Apps) that
do not touch this code. Those tests pass when run alone.

**Manual test**

Requires Chrome 149+ with the WebMCP origin trial, or the testing flag.

1. Enable `chrome://flags/#enable-webmcp-testing`, then relaunch Chrome.
2. In an app that uses CopilotKit, register a tool with `webmcp: true`.
3. Run `await document.modelContext.getTools()` in DevTools. The tool is
listed with its schema and annotations.
4. Unmount the hook. Run the command again. The tool is gone.

**How this PR makes testing easy**

The behavior has automated tests on this branch:

- `packages/core/src/core/__tests__/run-handler-webmcp.test.ts` — 15
tests with a `document.modelContext` stub: registration, annotations,
unregistration, availability rules, name collisions, stale-rejection
races, and handler execution.
-
`packages/react-core/src/v2/hooks/__tests__/use-frontend-tool-webmcp.test.tsx`
and the mirrored
`packages/vue/src/v2/hooks/__tests__/use-frontend-tool-webmcp.test.ts` —
pass-through, re-registration, and agent-scoped cases at the hook level.
- `packages/vue/src/hooks/__tests__/use-frontend-tool-webmcp.test.ts` —
reactive `webmcp` getters through the v1 Vue API.

## Risk / rollback

Low. The feature is opt-in per tool. Without `webmcp`, no code path
changes. Where WebMCP is unsupported, registration is a no-op. Revert
this PR to roll back.

## Public API change

New optional `webmcp` prop on frontend tool registrations. Existing call
sites do not change.

**Before**

```ts
useFrontendTool({
  name: "searchOrders",
  description: "Search orders by status",
  parameters: z.object({ status: z.string() }),
  handler: async ({ status }) => searchOrders(status),
});
```

**After**

```ts
useFrontendTool({
  name: "searchOrders",
  description: "Search orders by status",
  parameters: z.object({ status: z.string() }),
  handler: async ({ status }) => searchOrders(status),
  webmcp: { annotations: { readOnlyHint: true } },
});
```


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
  * Tools can now be exposed to browser agents through WebMCP.
* Added support for custom annotations and automatic parameter schema
generation.
* WebMCP registrations stay synchronized as tools are added, removed,
enabled, or updated.
  * Available across Angular, React, and Vue tool APIs.
* WebMCP reuses existing handlers and safely does nothing when
unavailable.

* **Documentation**
* Added usage guidance and examples for configuring WebMCP-enabled
tools.
  * Documented that WebMCP invocations do not include an agent context.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

2026-09-03 14:15:29 +02:00

public

chore: rename Enterprise Intelligence product copy

2026-08-24 09:38:15 -07:00

src

feat(core): expose webmcp-enabled frontend tools to browser agents (#6847 )

2026-09-03 14:15:29 +02:00

.env.example

chore: rename Enterprise Intelligence product copy

2026-08-24 09:38:15 -07:00

.gitignore

…

Dockerfile

…

model-allowlist.json

docs: update Anthropic model references to Opus 4.8

2026-08-20 16:40:09 -07:00

next.config.ts

fix(showcase): 301 the legacy premium URLs onto the renamed Intelligence tree

2026-09-01 14:00:37 +02:00

package-lock.json

…

package.json

…

postcss.config.mjs

…

README.md

…

tsconfig.json

…

vercel.json

…

vitest.config.ts

…

README.md

Shell Docs

showcase/shell-docs is the Next.js app that builds and serves docs.copilotkit.ai. Author CopilotKit product documentation here, not in the retired top-level docs/ app.

Run Locally

Shell-docs is a standalone npm-based app. You do not need a root install just to run the docs app locally.

cd showcase/scripts
npm install

cd ../shell-docs
npm install
npm run dev

The local dev server runs on port 3003.

http://localhost:3003

The shell-docs npm lifecycle generates registry, demo-content, setup-content, and search data before dev, build, and typecheck.

Validate Changes

Run these from showcase/shell-docs:

npm run build
npm run typecheck
npm run test

For repo-level CI parity, prefer Nx when a shell-docs target is available in the current checkout and root dependencies are installed. For normal shell-docs local development, the npm commands above are the canonical path.

Authoring Recipes

Showcase-Driven Framework Docs

Showcase-driven frameworks use docs_mode: generated. The docs are assembled from showcase registry/generated data, demos, source regions, shared/root MDX, snippets, and sparse framework overrides.

To update showcase-driven docs:

Edit the showcase source of truth: manifests, demos, feature coverage, source regions, or registry inputs.
Edit shared/root MDX only when the change applies across generated frameworks.
Add sparse framework overrides only for real framework-specific differences.
Do not hand-edit generated files under src/data/frameworks/.
Validate routes, sidebar state, search results, snippets, and framework switching.

Authored Framework Docs

Authored frameworks use docs_mode: authored. The framework owns an MDX tree under src/content/docs/integrations/<docsFolder>/ with a meta.json sidebar.

To update authored docs:

Check getDocsFolder() in src/lib/registry.ts; the URL slug and folder name may differ.
Edit the MDX page under src/content/docs/integrations/<docsFolder>/.
Update that folder's meta.json when adding, removing, or moving pages.
Reuse shared snippets from src/content/snippets/ when content should stay consistent across frameworks.
Validate the framework route, sidebar, search result, and any shared snippet render.

Reference Docs

Edit API reference pages under src/content/reference/.

The v2 reference does not use meta.json; navigation is generated by walking the tree and reading each page's title and description frontmatter. Only the legacy reference/v1/ tree uses meta.json.

Snippets

Reusable snippets live under src/content/snippets/. Snippets may be rendered by root docs, authored framework pages, and showcase-driven framework pages, so keep them general unless the path is intentionally framework-specific.

Frontend Applicability

Frontend routes use page-level applicability metadata, independent from where the content is authored. A page can be authored MDX, showcase-generated content, mirrored protocol docs, or reference content and still be universal across frontends.

Use the frontend field in page frontmatter or meta.json when a root doc should appear in non-React frontend docs:

universal — render the same page under /<frontend>/....
frontend-variant — render only when a matching page exists under src/content/docs/frontends/<frontend>/....
hide — omit the page from frontend-scoped docs.

Do not use "showcase-driven" as a proxy for frontend availability. Showcase derivation is an authoring/source detail; frontend applicability controls routing and sidebar inclusion.

AG-UI Mirrored Docs

AG-UI protocol docs are authored upstream in ag-ui-protocol/ag-ui. The src/content/ag-ui/ tree is a downstream mirror rendered on the CopilotKit docs host. Change AG-UI docs upstream first, then sync the mirror back into shell-docs.

Top-Level Docs Symlink

The repository's top-level docs/ path is a symlink to showcase/shell-docs/ for contributor muscle memory. It is not a separate docs app. Do not recreate the old docs/content/docs/ tree; author CopilotKit docs in showcase/shell-docs/src/content/.