0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
Commit graph

2 commits

Author SHA1 Message Date
Dane - AI (Mastra)
4f60903242
chore(deps): lock file maintenance (#27013) 2026-10-21 09:25:38 +02:00
Daniel Lew
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>
2026-10-20 20:47:42 -04:00