@mastra/mcp-docs-server 1.1.45 → 1.1.46-alpha.0

package/.docs/reference/signals/webhook-signal-provider.md

@@ -0,0 +1,137 @@
+# WebhookSignalProvider
+
+**Added in:** `@mastra/core@1.39.0`
+
+Concrete signal provider for push-based event delivery. Routes incoming webhook payloads to subscribed agent threads by matching the payload against a configurable resource ID extractor.
+
+Extends [`SignalProvider`](https://mastra.ai/reference/signals/signal-provider) with public subscription management and a built-in `handleWebhook()` implementation.
+
+## Usage example
+
+Route GitHub webhook events to subscribed threads:
+
+```typescript
+import { WebhookSignalProvider } from '@mastra/core/signals'
+
+const webhookProvider = new WebhookSignalProvider({
+  extractResourceId: payload => `${payload.repository?.full_name}`,
+  buildNotification: (payload, subscription) => ({
+    source: 'github-webhook',
+    kind: payload.action ?? 'event',
+    summary: `${payload.action} on ${subscription.externalResourceId}`,
+    payload,
+  }),
+})
+```
+
+Register with an agent and subscribe a thread:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+const agent = new Agent({
+  signals: [webhookProvider],
+})
+
+// subscribe a thread to a specific repo
+webhookProvider.subscribeThread({ threadId: 'thread-1', resourceId: 'user-1' }, 'mastra-ai/mastra')
+
+// handle an incoming webhook
+const result = await webhookProvider.handleWebhook({
+  body: { repository: { full_name: 'mastra-ai/mastra' }, action: 'push' },
+  headers: {},
+})
+// result.matched === 1
+```
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for the provider instance. (Default: `'webhook-signals'`)
+
+**name** (`string`): Human-readable name. (Default: `'Webhook Signals'`)
+
+**extractResourceId** (`(payload: unknown) => string | string[] | undefined`): Extract the external resource ID from a webhook payload. Return \`undefined\` to skip the event. Can return an array to match multiple resources. (Default: ``Returns `payload.resource` or `payload.externalResourceId` if present``)
+
+**buildNotification** (`(payload: unknown, subscription: SignalSubscription) => SendNotificationSignalInput`): Build the notification object from a webhook payload and the matched subscription. (Default: `` Returns `{ source: id, kind: 'webhook-event', summary, payload }` ``)
+
+## Methods
+
+### Subscription management
+
+#### `subscribeThread(target, externalResourceId, metadata?)`
+
+Subscribe a thread to receive webhook events for a specific external resource.
+
+```typescript
+webhookProvider.subscribeThread(
+  { threadId: 'thread-1', resourceId: 'user-1' },
+  'mastra-ai/mastra',
+  { watchType: 'push' },
+)
+```
+
+Returns: `SignalSubscription`
+
+**target** (`SignalProviderTarget`): The thread to subscribe. Must include \`threadId\` and \`resourceId\`.
+
+**externalResourceId** (`string`): The external resource to monitor (for example, a repository full name).
+
+**metadata** (`Record<string, unknown>`): Additional data to store with the subscription.
+
+#### `unsubscribeThread(target, externalResourceId)`
+
+Unsubscribe a thread from a specific external resource.
+
+```typescript
+const removed = webhookProvider.unsubscribeThread(
+  { threadId: 'thread-1', resourceId: 'user-1' },
+  'mastra-ai/mastra',
+)
+```
+
+Returns: `boolean`
+
+### Webhook handling
+
+#### `handleWebhook(request)`
+
+Process an incoming webhook request. Extracts the resource ID from the payload, finds matching subscriptions, builds a notification for each, and calls `notify()`.
+
+```typescript
+const result = await webhookProvider.handleWebhook({
+  body: { repository: { full_name: 'mastra-ai/mastra' }, action: 'push' },
+  headers: { 'x-github-event': 'push' },
+})
+```
+
+Returns: `Promise<{ status: number; body: { matched: number } }>`
+
+Returns `{ status: 200, body: { matched: N } }` where `N` is the number of subscriptions that received notifications. Returns `matched: 0` when no resource ID could be extracted or no subscriptions match.
+
+**request** (`object`): The incoming webhook request.
+
+**request.body** (`unknown`): The parsed webhook payload.
+
+**request.headers** (`Record<string, string>`): HTTP headers from the webhook request.
+
+### Static signal factories
+
+#### `WebhookSignalProvider.signals.subscribe(externalResourceId)`
+
+Create a reactive signal input that subscribes the current thread to an external resource.
+
+```typescript
+const signal = WebhookSignalProvider.signals.subscribe('mastra-ai/mastra')
+```
+
+Returns: `{ type: 'reactive'; tagName: string; contents: string; attributes: { resource: string } }`
+
+#### `WebhookSignalProvider.signals.unsubscribe(externalResourceId)`
+
+Create a reactive signal input that unsubscribes the current thread from an external resource.
+
+```typescript
+const signal = WebhookSignalProvider.signals.unsubscribe('mastra-ai/mastra')
+```
+
+Returns: `{ type: 'reactive'; tagName: string; contents: string; attributes: { resource: string } }`

package/.docs/reference/storage/clickhouse.md

@@ -81,7 +81,7 @@ export const mastra = new Mastra({
 })
 ```
 
-`MastraStorageExporter` automatically selects the `insert-only` strategy when ClickHouse is the observability backend, which gives the highest write throughput. See [tracing strategies](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) for details.
+`MastraStorageExporter` automatically selects the `insert-only` strategy when ClickHouse is the observability backend, which gives the highest write throughput. See [tracing strategies](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) for details.
 
 ### Observability with the legacy domain
 
@@ -290,11 +290,11 @@ ClickHouse is the recommended backend for production observability:
 - **Insert-only strategy**: `MastraStorageExporter` writes completed spans in batches without per-span updates, which is the highest-throughput strategy available.
 - **Columnar compression**: Span attributes and log payloads compress well compared to the same data in row-oriented databases.
 
-For the full strategy matrix and production guidance, see the [`MastraStorageExporter` reference](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage).
+For the full strategy matrix and production guidance, see the [`MastraStorageExporter` reference](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage).
 
 ## Related
 
 - [Storage overview](https://mastra.ai/reference/storage/overview)
 - [Composite storage](https://mastra.ai/reference/storage/composite)
-- [`MastraStorageExporter`](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage)
+- [`MastraStorageExporter`](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage)
 - [Observability overview](https://mastra.ai/docs/observability/overview)

package/.docs/reference/storage/composite.md

@@ -242,4 +242,4 @@ const storage = new MastraCompositeStore({
 
 > **Note:** `ObservabilityStorageClickhouseVNext` is the current observability domain implementation. The legacy `ObservabilityStorageClickhouse` class is also exported and remains supported for projects that have not migrated. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
 
-> **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [MastraStorageExporter documentation](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) for the full list of supported providers.
+> **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [MastraStorageExporter documentation](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) for the full list of supported providers.

package/.docs/reference/storage/duckdb.md

@@ -139,7 +139,7 @@ await duckdb.observability.init()
 
 ## Observability strategy
 
-DuckDB supports the `event-sourced` strategy used by `MastraStorageExporter`, which buffers spans in memory and writes completed events in batches. This is appropriate for development-scale traffic. For high-volume production workloads, see [`MastraStorageExporter` storage provider support](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage).
+DuckDB supports the `event-sourced` strategy used by `MastraStorageExporter`, which buffers spans in memory and writes completed events in batches. This is appropriate for development-scale traffic. For high-volume production workloads, see [`MastraStorageExporter` storage provider support](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage).
 
 ## Related
 

package/.docs/reference/storage/libsql.md

@@ -136,6 +136,6 @@ const thread = await memoryStore?.getThreadById({ threadId: '...' })
 
 ## Observability
 
-libSQL supports observability and is ideal for local development. Use the `realtime` [tracing strategy](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) for immediate visibility while debugging.
+libSQL supports observability and is ideal for local development. Use the `realtime` [tracing strategy](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) for immediate visibility while debugging.
 
 For production environments with higher trace volumes, consider using [PostgreSQL](https://mastra.ai/reference/storage/postgresql) or [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite).

package/.docs/reference/storage/postgresql.md

@@ -140,7 +140,7 @@ The storage implementation handles schema creation and updates automatically. It
 
 PostgreSQL supports observability and can handle low trace volumes. Throughput capacity depends on deployment factors such as hardware, schema design, indexing, and retention policies, and should be validated for your specific environment. For high-volume production environments, consider:
 
-- Using the `insert-only` [tracing strategy](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) to reduce database write operations
+- Using the `insert-only` [tracing strategy](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) to reduce database write operations
 - Setting up table partitioning for efficient data retention
 - Migrating observability to [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite) if you need to scale further
 

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @mastra/mcp-docs-server
 
+## 1.1.46-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`d468acb`](https://github.com/mastra-ai/mastra/commit/d468acb07aec1bb19a2cb0ada8042b05b46746b2), [`e9be4e7`](https://github.com/mastra-ai/mastra/commit/e9be4e747ec3d8b65548bff92f9377db06105376), [`d53cfc2`](https://github.com/mastra-ai/mastra/commit/d53cfc2c7f8d78343a4aa84ec4e129ba25f3325e), [`65799d4`](https://github.com/mastra-ai/mastra/commit/65799d4d549e5ebb9c848fbe3f51ac090f64becf), [`c268c89`](https://github.com/mastra-ai/mastra/commit/c268c89f4c63a93ee474d3cffdf3ea60bf00d4f2), [`d468acb`](https://github.com/mastra-ai/mastra/commit/d468acb07aec1bb19a2cb0ada8042b05b46746b2), [`7ef9ebf`](https://github.com/mastra-ai/mastra/commit/7ef9ebf79ec3c90536643ef169c7a306f105fb9d), [`0c72f03`](https://github.com/mastra-ai/mastra/commit/0c72f032abb13254df5a7856d64be2f207b8006d), [`75adfb8`](https://github.com/mastra-ai/mastra/commit/75adfb81e3fca1fe8dc9ab382bed7b714854ba4f), [`3b45ea9`](https://github.com/mastra-ai/mastra/commit/3b45ea95015557a6cb9d70dc5252af54ab1b78ac), [`f084be1`](https://github.com/mastra-ai/mastra/commit/f084be1fcbe33ad7480913e44d6130c421c0976f)]:
+  - @mastra/core@1.42.0-alpha.0
+  - @mastra/mcp@1.9.2-alpha.0
+
 ## 1.1.45
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.45",
+  "version": "1.1.46-alpha.0",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.41.0",
-    "@mastra/mcp": "^1.9.1"
+    "@mastra/core": "1.42.0-alpha.0",
+    "@mastra/mcp": "^1.9.2-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -39,15 +39,15 @@
     "@vitest/ui": "4.1.5",
     "@wong2/mcp-cli": "^1.13.0",
     "cross-env": "^10.1.0",
-    "eslint": "^10.2.1",
+    "eslint": "^10.4.1",
     "hono": "^4.12.8",
     "tsup": "^8.5.1",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
-    "@internal/types-builder": "0.0.78",
     "@internal/lint": "0.0.103",
-    "@mastra/core": "1.41.0"
+    "@internal/types-builder": "0.0.78",
+    "@mastra/core": "1.42.0-alpha.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {