@mastra/mcp-docs-server 1.2.15 → 1.2.16-alpha.3

package/.docs/guides/guide/research-coordinator.md

@@ -1,418 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Build a research coordinator with supervisor agents
-
-In this guide, you'll build a research coordinator that orchestrates multiple specialized agents using supervisor agents. The coordinator will delegate research tasks to a research agent and writing tasks to a writing agent, then synthesize the results into a detailed report.
-
-You'll set up subagents with clear roles and configure a supervisor agent to coordinate them. You'll also use delegation hooks to control execution and scorers to validate task completion.
-
-## Prerequisites
-
-- Node.js `v22.13.0` or later installed
-- An API key from a supported [Model Provider](https://mastra.ai/models)
-- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
-
-## Create the research agent
-
-The research agent specializes in gathering factual information on any topic. It returns concise bullet-point summaries with key facts and sources.
-
-Create a new file `src/mastra/agents/research-agent.ts`:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-
-export const researchAgent = new Agent({
-  id: 'research-agent',
-  name: 'Research Specialist',
-  description:
-    'Specializes in gathering factual information and data on any topic. ' +
-    'Returns concise bullet-point summaries with key facts and sources. ' +
-    'Does not write full articles or narrative content.',
-  instructions:
-    'You are a research specialist. When given a topic, gather key facts, ' +
-    'statistics, and information. Present findings as clear bullet points. ' +
-    'Include sources when possible. Focus on accuracy and completeness.',
-  model: 'openai/gpt-5-mini',
-})
-```
-
-The `description` field is critical - it helps the supervisor understand when to delegate to this agent. Clear descriptions improve delegation accuracy.
-
-## Create the writing agent
-
-The writing agent transforms research into well-structured articles with complete paragraphs and proper flow.
-
-Create a new file `src/mastra/agents/writing-agent.ts`:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-
-export const writingAgent = new Agent({
-  id: 'writing-agent',
-  name: 'Writing Specialist',
-  description:
-    'Transforms research material into well-structured written content. ' +
-    'Produces full paragraphs and complete articles with proper flow. ' +
-    'Best used after research has been gathered.',
-  instructions:
-    'You are a writing specialist. Transform research and information into ' +
-    'well-written articles. Use complete paragraphs, clear structure, and ' +
-    'engaging language. Maintain a professional yet accessible tone. ' +
-    'Ensure the content flows naturally from introduction to conclusion.',
-  model: 'openai/gpt-5-mini',
-})
-```
-
-## Create the supervisor agent
-
-The supervisor coordinates research and writing tasks. Its instructions define the delegation strategy - when to use each subagent and how to synthesize results. Memory is configured directly on the agent.
-
-Create a new file `src/mastra/agents/supervisor-agent.ts`:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { Memory } from '@mastra/memory'
-import { LibSQLStore } from '@mastra/libsql'
-import { researchAgent } from './research-agent'
-import { writingAgent } from './writing-agent'
-
-export const supervisorAgent = new Agent({
-  id: 'supervisor-agent',
-  name: 'Research Coordinator',
-  instructions: `You coordinate research and writing tasks using specialized agents.
-
-Available resources:
-- research-agent: Gathers factual data and sources (returns bullet points)
-- writing-agent: Transforms research into well-structured articles (returns full paragraphs)
-
-Delegation strategy:
-1. For research requests: Delegate to research-agent first to gather facts
-2. For writing requests: Delegate to writing-agent with any available research context
-3. For comprehensive reports: Delegate to research-agent first, then writing-agent
-4. Always ensure you have gathered sufficient information before producing final output
-
-Success criteria:
-- All aspects of the user's request are addressed
-- Information is accurate and well-sourced
-- Final output is well-formatted and complete
-- If anything is missing or uncertain, continue gathering information`,
-  model: 'openai/gpt-5.6-sol',
-  agents: {
-    researchAgent,
-    writingAgent,
-  },
-  memory: new Memory({
-    storage: new LibSQLStore({
-      id: 'mastra-storage',
-      url: 'file:mastra.db',
-    }),
-  }),
-  defaultOptions: {
-    maxSteps: 10,
-
-    // Monitor progress after each iteration
-    onIterationComplete: async context => {
-      console.log(`\n✓ Iteration ${context.iteration} complete`)
-      console.log(`  Finish reason: ${context.finishReason}`)
-      console.log(`  Response length: ${context.text.length} chars\n`)
-
-      // Continue until task is complete
-      return { continue: true }
-    },
-
-    // Control delegations
-    delegation: {
-      onDelegationStart: async context => {
-        console.log(`→ Delegating to: ${context.primitiveId}`)
-
-        // Add context for specific agents
-        if (context.primitiveId === 'research-agent') {
-          return {
-            proceed: true,
-            modifiedPrompt: `${context.prompt}\n\nFocus on recent developments (2024-2025) and include statistics.`,
-          }
-        }
-
-        return { proceed: true }
-      },
-
-      onDelegationComplete: async context => {
-        console.log(`✓ Completed: ${context.primitiveId}\n`)
-
-        // Handle errors: bail to stop execution and provide feedback
-        if (context.error) {
-          console.error('Delegation failed:', context.error)
-          context.bail() // Stop further delegations
-          return {
-            feedback: `Delegation to ${context.primitiveId} failed: ${context.error}. Try a different approach.`,
-          }
-        }
-      },
-
-      // Only pass last 10 messages to subagents
-      messageFilter: ({ messages }) => {
-        return messages.slice(-10)
-      },
-    },
-  },
-})
-```
-
-Register the supervisor with Mastra in `src/mastra/index.ts`:
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { supervisorAgent } from './agents/supervisor-agent'
-
-export const mastra = new Mastra({
-  agents: { supervisorAgent },
-})
-```
-
-The `defaultOptions` on the supervisor agent configure delegation hooks and iteration monitoring:
-
-- `onDelegationStart` modifies the research agent's prompt to request recent data
-- `onDelegationComplete` logs completion and stops on errors, then provides feedback
-- `messageFilter` limits context to the last 10 messages for efficiency
-- `onIterationComplete` monitors progress after each iteration
-
-## Test the basic supervisor
-
-Create a file to interact with the supervisor in `src/index.ts`:
-
-```typescript
-import { supervisorAgent } from './mastra/agents/supervisor-agent'
-
-async function main() {
-  const topic = 'artificial intelligence in education'
-  console.log(`\nTopic: ${topic}\n`)
-
-  const stream = await supervisorAgent.stream(
-    `Research ${topic} and write a comprehensive article about it`,
-  )
-
-  // Stream the response
-  console.log('📝 Final Report:\n')
-  for await (const chunk of stream.textStream) {
-    process.stdout.write(chunk)
-  }
-  console.log('\n')
-}
-
-main()
-```
-
-The supervisor uses the delegation hooks and iteration monitoring configured in `defaultOptions`.
-
-## Add task completion scoring
-
-Task completion scorers automatically validate whether the task is complete. They prevent the supervisor from finishing prematurely.
-
-Create a scorer in `src/mastra/scorers/task-complete-scorer.ts`:
-
-```typescript
-import { createScorer } from '@mastra/core/evals'
-
-export const taskCompleteScorer = createScorer({
-  id: 'task-complete',
-  name: 'Task Completeness',
-  description: 'Checks if the research and writing task has been fully completed',
-}).generateScore(async context => {
-  const text = (context.run.output || '').toString()
-
-  // Check if response contains required elements
-  const hasSubstantialContent = text.length > 500
-  const hasStructure = text.includes('\n\n') // Multiple paragraphs
-  const hasContext = /\d{4}/.test(text) // Contains years/dates
-
-  // Return 1 if complete, 0 if not
-  if (hasSubstantialContent && hasStructure && hasContext) {
-    return 1
-  }
-
-  return 0
-})
-```
-
-Install the evals package:
-
-**npm**:
-
-```bash
-npm install @mastra/evals
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/evals
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/evals
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/evals
-```
-
-Update the supervisor agent to include task completion scoring in `defaultOptions` in `src/mastra/agents/supervisor-agent.ts`:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { Memory } from '@mastra/memory'
-import { LibSQLStore } from '@mastra/libsql'
-import { researchAgent } from './research-agent'
-import { writingAgent } from './writing-agent'
-import { taskCompleteScorer } from '../scorers/task-complete-scorer'
-
-export const supervisorAgent = new Agent({
-  id: 'supervisor-agent',
-  name: 'Research Coordinator',
-  instructions: `You coordinate research and writing tasks using specialized agents.
-
-Available resources:
-- research-agent: Gathers factual data and sources (returns bullet points)
-- writing-agent: Transforms research into well-structured articles (returns full paragraphs)
-
-Delegation strategy:
-1. For research requests: Delegate to research-agent first to gather facts
-2. For writing requests: Delegate to writing-agent with any available research context
-3. For comprehensive reports: Delegate to research-agent first, then writing-agent
-4. Always ensure you have gathered sufficient information before producing final output
-
-Success criteria:
-- All aspects of the user's request are addressed
-- Information is accurate and well-sourced
-- Final output is well-formatted and complete
-- If anything is missing or uncertain, continue gathering information`,
-  model: 'openai/gpt-5.6-sol',
-  agents: {
-    researchAgent,
-    writingAgent,
-  },
-  memory: new Memory({
-    storage: new LibSQLStore({
-      id: 'mastra-storage',
-      url: 'file:mastra.db',
-    }),
-  }),
-  defaultOptions: {
-    maxSteps: 10,
-
-    onIterationComplete: async context => {
-      console.log(`\n✓ Iteration ${context.iteration} complete`)
-      console.log(`  Finish reason: ${context.finishReason}`)
-      console.log(`  Response length: ${context.text.length} chars\n`)
-      return { continue: true }
-    },
-
-    delegation: {
-      onDelegationStart: async context => {
-        console.log(`→ Delegating to: ${context.primitiveId}`)
-
-        if (context.primitiveId === 'research-agent') {
-          return {
-            proceed: true,
-            modifiedPrompt: `${context.prompt}\n\nFocus on recent developments (2024-2025) and include statistics.`,
-          }
-        }
-
-        return { proceed: true }
-      },
-
-      onDelegationComplete: async context => {
-        console.log(`✓ Completed: ${context.primitiveId}\n`)
-
-        if (context.error) {
-          console.error('Delegation failed:', context.error)
-          context.bail() // Stop further delegations
-          return {
-            feedback: `Delegation to ${context.primitiveId} failed: ${context.error}. Try a different approach.`,
-          }
-        }
-      },
-
-      messageFilter: ({ messages }) => {
-        return messages.slice(-10)
-      },
-    },
-
-    // Validate task completion
-    isTaskComplete: {
-      scorers: [taskCompleteScorer],
-      strategy: 'all',
-      onComplete: async result => {
-        console.log('\n🎯 Completion Check:')
-        console.log(`  Complete: ${result.complete}`)
-        console.log(`  Score: ${result.scorers[0]?.score}\n`)
-      },
-    },
-  },
-})
-```
-
-The scorer checks for substantial content, proper structure, and contextual information. If the task isn't complete, the supervisor will continue iterating. Now all hooks and task completion scoring are configured in the agent's `defaultOptions`, making them apply to every call automatically.
-
-## Test the research coordinator
-
-Run the coordinator to see it in action:
-
-```bash
-npx tsx src/index.ts
-```
-
-You'll see the supervisor delegate to the research agent first, then to the writing agent, with logs showing the delegation flow:
-
-```text
-Topic: artificial intelligence in education
-
-→ Delegating to: research-agent
-✓ Iteration 1 complete
-  Finish reason: tool-calls
-  Response length: 0 chars
-
-✓ Completed: research-agent
-
-→ Delegating to: writing-agent
-✓ Iteration 2 complete
-  Finish reason: tool-calls
-  Response length: 0 chars
-
-✓ Completed: writing-agent
-
-🎯 Completion Check:
-  Complete: true
-  Score: 1
-
-✓ Iteration 3 complete
-  Finish reason: stop
-  Response length: 1247 chars
-
-📝 Final Report:
-
-Artificial Intelligence in Education: Transforming Learning in 2024-2025
-
-[The coordinator will produce a comprehensive article combining research findings with well-structured writing...]
-```
-
-Since agent responses are non-deterministic, your output may vary, but the delegation pattern will be the same.
-
-## Next steps
-
-You can extend this research coordinator to:
-
-- Add more specialized agents (fact-checker, editor, citation-formatter)
-- Implement custom scorers for quality metrics (readability, source quality)
-- Add tools for web search or database access
-- Create workflows for complex multi-step research processes
-- Use structured output to generate reports in specific formats
-
-Learn more:
-
-- [Supervisor Agents](https://mastra.ai/docs/capabilities/subagents)
-- [Agent.stream() Reference](https://mastra.ai/reference/streaming/agents/stream)

package/.docs/guides/guide/signal-provider.md

@@ -1,221 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Building a signal provider
-
-In this guide, you'll build a signal provider that polls an external service on an interval and pushes a notification into an agent thread whenever a watched resource changes. You'll learn how to extend the `SignalProvider` base class, track subscriptions, emit notifications from a poll loop, and register the provider on an agent.
-
-The example watches build pipelines in a fake CI service, but the pattern applies to any pull-based source: an issue tracker, a status API, a queue, or your own backend.
-
-> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
-
-## Prerequisites
-
-- Node.js `v22.13.0` or later installed
-- An API key from a supported [Model Provider](https://mastra.ai/models)
-- An existing Mastra project. Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) if needed.
-
-This guide also assumes you understand [signals](https://mastra.ai/docs/long-running-agents/signals) at a high level. For the full API surface, see the [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider).
-
-## Add notification storage
-
-A signal provider pushes [notification signals](https://mastra.ai/docs/long-running-agents/signals) into threads, and notifications require a storage adapter that supports the notifications domain. Configure storage on your Mastra instance.
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { LibSQLStore } from '@mastra/libsql'
-
-export const mastra = new Mastra({
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    url: 'file:./mastra.db',
-  }),
-})
-```
-
-LibSQL, PostgreSQL, and MongoDB all support notification records. Without notification storage, the provider's `notify()` calls throw at runtime.
-
-## Create the external service client
-
-Real providers call an external API. To keep this guide self-contained, create a small fake CI client that returns a build status for a pipeline. Swap this for your real API client later.
-
-```typescript
-export type BuildStatus = {
-  id: string
-  pipeline: string
-  status: 'passed' | 'failed' | 'running'
-}
-
-// Returns a random status so you can see notifications fire while testing.
-export async function fetchBuildStatus(pipeline: string): Promise<BuildStatus> {
-  const states: BuildStatus['status'][] = ['passed', 'failed', 'running']
-  const status = states[Math.floor(Math.random() * states.length)]!
-  return { id: `build_${Date.now()}`, pipeline, status }
-}
-```
-
-This client returns a random status each call. When you wire in a real API, only this file changes.
-
-## Build the signal provider
-
-Extend `SignalProvider`, implement the abstract `id` field, set a `pollInterval`, and override `poll()`. The base class calls `poll()` on the interval with every active subscription. Emit a notification only for the builds you care about.
-
-```typescript
-import { SignalProvider } from '@mastra/core/signals'
-import type { SignalProviderTarget, SignalSubscription } from '@mastra/core/signals'
-import { fetchBuildStatus } from './ci-client'
-
-export class CiSignals extends SignalProvider<'ci-signals'> {
-  readonly id = 'ci-signals' as const
-  readonly pollInterval = 10_000 // poll every 10 seconds
-
-  // Public API so callers can subscribe a thread to a pipeline.
-  watch(target: SignalProviderTarget, pipeline: string): SignalSubscription {
-    return this.subscribe(target, pipeline)
-  }
-
-  unwatch(target: SignalProviderTarget, pipeline: string): boolean {
-    return this.unsubscribe(target, pipeline)
-  }
-
-  async poll(subscriptions: SignalSubscription[]): Promise<void> {
-    for (const sub of subscriptions) {
-      const build = await fetchBuildStatus(sub.externalResourceId)
-      if (build.status !== 'failed') continue
-
-      await this.notify(
-        {
-          source: this.id,
-          kind: 'ci-status',
-          priority: 'high',
-          summary: `Build failed for ${sub.externalResourceId}`,
-          payload: build,
-          dedupeKey: `${this.id}:${sub.externalResourceId}:${build.id}`,
-        },
-        { resourceId: sub.resourceId, threadId: sub.threadId },
-      )
-    }
-  }
-}
-```
-
-A few things to note:
-
-- `subscribe()` and `unsubscribe()` are protected on the base class. Wrap them in your own public methods (`watch` / `unwatch`) so callers can manage subscriptions.
-- `externalResourceId` is any provider-specific string. Here it's the pipeline name; a GitHub provider might use `"github:owner/repo#123"`.
-- `notify()` forwards a notification signal to the connected agent's thread. It throws if the provider was never registered on an agent.
-- `dedupeKey` prevents storing the same failure twice.
-
-## Register the provider on an agent
-
-Pass the provider to the agent through `signals`. The agent connects it and starts the poll loop automatically.
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { CiSignals } from '../signals/ci-signals'
-
-export const ciSignals = new CiSignals()
-
-export const devAgent = new Agent({
-  id: 'dev-agent',
-  name: 'Dev Agent',
-  instructions: 'Help the user triage CI build failures.',
-  model: 'openai/gpt-5.6-sol',
-  signals: [ciSignals],
-})
-```
-
-Register the agent with Mastra and add the storage from the first step.
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { LibSQLStore } from '@mastra/libsql'
-import { devAgent } from './agents/dev-agent'
-
-export const mastra = new Mastra({
-  agents: { devAgent },
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    url: 'file:./mastra.db',
-  }),
-})
-```
-
-## Subscribe a thread
-
-A provider only polls resources that a thread is watching. Subscribe a thread to a pipeline so `poll()` has something to check.
-
-```typescript
-import { ciSignals } from './agents/dev-agent'
-
-ciSignals.watch({ resourceId: 'user_123', threadId: 'thread_456' }, 'acme/app:main')
-```
-
-Run this once after the agent is registered, for example from a setup script or an API route. The subscription lives in the provider's in-memory registry, so re-subscribe after a restart.
-
-## Test the signal provider
-
-Start the dev server:
-
-**npm**:
-
-```bash
-npm run dev
-```
-
-**pnpm**:
-
-```bash
-pnpm run dev
-```
-
-**Yarn**:
-
-```bash
-yarn dev
-```
-
-**Bun**:
-
-```bash
-bun run dev
-```
-
-Make sure a thread is subscribed, then watch the logs. The fake client returns a random status each poll, so within a few cycles you'll see a failed build trigger a notification for the subscribed thread.
-
-To see the agent react to the notification, subscribe to the thread and stream it:
-
-```typescript
-const subscription = await devAgent.subscribeToThread({
-  resourceId: 'user_123',
-  threadId: 'thread_456',
-})
-
-for await (const chunk of subscription.stream) {
-  console.log(chunk)
-}
-```
-
-When a build fails, the model receives the notification as context:
-
-```xml
-<notification source="ci-signals" type="ci-status" priority="high" status="delivered">Build failed for acme/app:main</notification>
-```
-
-Output is non-deterministic because the fake client randomizes status and the model phrases its reply freely, so the exact wording will vary.
-
-## Next steps
-
-You can extend this signal provider to:
-
-- Replace `fetchBuildStatus()` with a real API client.
-- Persist subscriptions so they survive a restart, then rehydrate them in [`start()`](https://mastra.ai/reference/signals/signal-provider).
-- Add a [webhook](https://mastra.ai/docs/long-running-agents/signal-providers) entry point with [`handleWebhook()`](https://mastra.ai/reference/signals/signal-provider) for push-based sources.
-- Expose `subscribe` and `unsubscribe` tools with [`getTools()`](https://mastra.ai/reference/signals/signal-provider) so the agent can manage its own subscriptions.
-- Use [`dedupeKey` and `coalesceKey`](https://mastra.ai/reference/agents/agent) when notifications need deduplication or batching.
-
-Learn more:
-
-- [Building signal providers](https://mastra.ai/docs/long-running-agents/signal-providers)
-- [Signals](https://mastra.ai/docs/long-running-agents/signals)
-- [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider)
-- [`WebhookSignalProvider` reference](https://mastra.ai/reference/signals/webhook-signal-provider)

package/.docs/guides/index.md

@@ -1,24 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Mastra Guides
-
-Mastra offers guides for building agents and workflows, using the Mastra SDK and API, and implementing different UI frameworks. Explore these guides to find the resources you need to get started and build with Mastra.
-
-## New project
-
-The `npm create mastra@latest` command is the fastest way to build your first agent. It creates a ready-to-run agent harness that you can explore and adapt in [Studio](https://mastra.ai/docs/studio/overview) right away. You can always integrate Mastra with your framework or UI when you’re ready.
-
-- [Quickstart](https://mastra.ai/guides/getting-started/quickstart)
-
-## Integrate with your framework
-
-Add Mastra to an existing project, or scaffold a new Mastra-powered app if you’re starting from scratch.
-
-- [Next.js](https://mastra.ai/integrations/frameworks/next-js)
-- [React](https://mastra.ai/integrations/frameworks/vite-react)
-- [SvelteKit](https://mastra.ai/integrations/frameworks/sveltekit)
-- [Astro](https://mastra.ai/integrations/frameworks/astro)
-- [Nuxt](https://mastra.ai/integrations/frameworks/nuxt)
-- [Express](https://mastra.ai/integrations/frameworks/express)
-- [Hono](https://mastra.ai/integrations/frameworks/hono)
-- [Electron](https://mastra.ai/integrations/frameworks/electron)