mirror of
https://github.com/mastra-ai/mastra.git
synced 2026-11-17 08:44:46 +00:00
2 commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
4f60903242 |
chore(deps): lock file maintenance (#27013) | ||
|
|
ca29333f8a |
MCP Events: client/server interop tests, example, and guide (#27331)
Fixes #27278 ## Summary This closes out MCP Events support ([SEP-3415](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3415), a draft extension) in `@mastra/mcp`. It adds no runtime code. It proves the client and server work together, gives users a runnable example, and adds a guide. - **Interop tests** (`packages/mcp/src/__tests__/events-interop/`): a real `MCPClient` against a real `MCPServer` over stdio and Streamable HTTP, running the same scenarios on both transports: - discovery; - push routing across two concurrent subscriptions; - poll from the emit buffer; - poll from a `poll()` source; - argument, unknown-event and forced-mode errors (asserting the wrapped `cause.id`); - cursor resume for all three sources (no missed or duplicate occurrences); - `reconnectServer()` during a push subscription; - a server without events, which rejects with `MCP_EVENTS_NOT_SUPPORTED` and receives no `events/*` request. Over stdio this is proven by recording stdin, with a positive control. Over HTTP it is proven by recording request bodies. Neither needs a source change. Occurrences are always caused after the subscription is established (by a tool call or a direct emit), never by a timer. - **Webhook interop tests** (`webhook-interop.test.ts`): a real client against a real server over authenticated Streamable HTTP, with a local receiver that mounts `mcp.events.handleWebhook()`. The URL policy is relaxed in the test fixture only. Covered: - mode selection (webhook preferred when configured, push otherwise); - routing and `match` filtering for two subscriptions sharing one URL; - cursor resume after the unsubscribe lands, and a resubscribe while it's in flight; - refresh before expiry, with `deliveryStatus`; - forced-mode, missing-config and unauthenticated errors; - same-argument subscriptions sharing one server subscription: both receive, cancelling one leaves the other receiving, and only the last cancel unsubscribes; - fallback to `push` with `MCP_EVENTS_WEBHOOK_UNAVAILABLE` over stdio and unauthenticated HTTP when no mode is forced. Forced `webhook` still rejects. - **Example** (`examples/mcp-events/`): a stdio server emits `ticket.created` from a tool. The client subscribes with `{ project: 'web' }`, opens tickets, and runs a triage agent once per matching occurrence. - **Guide** (`/docs/guides/mcp-events`, sidebar entry under Guides): covers concepts, `emit()` vs. `poll` sources, subscribing, cursor resume, error handling, webhook delivery, starting agent and workflow runs per occurrence, and limits. The Events sections of the `MCPClient` and `MCPServer` reference pages link to it. - The guide links to `MCPEventsSignalProvider` at `/reference/tools/mcp-client#events-in-agents-and-workflows-experimental`. That anchor is added by #27330. - Until #27330 merges (it merges before this PR), `pnpm build` warns about it as a broken anchor. The build still passes. No changeset: nothing published changes. ## Stack Merge order: #27320 → #27326, #27324 → #27330 → #27333 → this PR. - #27320: shared events wire contract - #27326: client (`mcp.events.list` / `subscribe`, poll + push) - #27324: server (`defineEvent`, `server.events.emit`, poll + push) - #27333: webhook delivery (server and client) - #27330: agent signals provider This PR targets `daniel/27278-events-webhook` (#27333). ## Run the interop suite `test:client` only globs `./src/client` and `test:server` only `./src/server`, so neither runs this suite. Run it directly: ```bash cd packages/mcp && pnpm vitest run --project unit:packages/mcp src/__tests__/events-interop ``` ## Test plan - `cd packages/mcp && pnpm vitest run --project unit:packages/mcp src/__tests__/events-interop`: 34/34 passed (24 poll/push on both transports, 10 webhook), 3 runs in a row. This suite isn't covered by `test:client`, which only globs `./src/client`. - Mutation checks: - making `match` always true fails the push and buffer-poll tests; - dropping the resume cursor fails all 6 resume cases. - Webhook: making `match` always true fails the routing test. Dropping the resume cursor fails the resume test. Dropping the short TTL/refresh margin times out the refresh test. - `pnpm --filter ./packages/mcp test:client`: 472 passed; `test:server`: 198 passed - `pnpm --filter ./packages/mcp build:lib`, `npx tsc --noEmit -p packages/mcp`, a typecheck of the test files, and oxlint + eslint on the interop directory: all clean. - Example: `pnpm install --ignore-workspace && pnpm typecheck` is clean. A smoke run with a fake key reached the model call after listing, subscribing and receiving. - Docs: `format:check`, `lint:remark` and Vale on the guide are clean. `pnpm build` succeeds; its only broken-anchor warnings are the existing agent-controller ones and the #27330 anchor above. `pnpm validate` fails only on stale `new` sidebar tags that were already there. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ## ELI5 This PR shows that MCP Events work between clients and servers. It adds tests, a runnable ticket example, and documentation for using the feature. ## What changed - Added interop tests for stdio and Streamable HTTP. - Covered discovery, push and poll delivery, filtering, cursors, reconnection, errors, and unsupported servers. - Added authenticated webhook tests for routing, filtering, cursor resume, refresh, shared subscriptions, and fallback behavior. - Added an `mcp-events` example that connects ticket events to an agent. - Added an MCP Events guide covering subscriptions, delivery modes, authorization, cursors, buffering, limits, and agent or workflow runs. - Linked the guide from the MCP client and server references. - Added guidance for cursor persistence, buffer overflow, and `match` versus `authorize`. - Added an empty changeset because the PR does not require a package release. - Added no runtime implementation changes. ## Validation - The author reports that the interop suite passed 34/34 tests in three runs. - The author reports clean package tests, type checks, linting, example checks, and documentation checks. - `pnpm validate` reportedly still fails on pre-existing stale `new` sidebar tags. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> |