@mastra/mcp-docs-server 1.2.7-alpha.10 → 1.2.7-alpha.3

package/.docs/reference/file-based-agents/subagents.md

@@ -1,123 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Subagents
-
-A file-based agent can declare **subagents**, specialist child agents it delegates to. The parent model sees each subagent as a delegation tool named after the subagent directory, calls that tool to hand off a task, and receives the subagent's result back in the parent conversation.
-
-Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents).
-
-## Quickstart
-
-Declare one directory per subagent under `subagents/`:
-
-```text
-src/mastra/agents/
-└── supervisor/
-    ├── config.ts
-    ├── instructions.md
-    └── subagents/
-        └── researcher/
-            ├── config.ts
-            ├── instructions.md
-            └── tools/
-                └── search.ts
-```
-
-Mastra assembles `researcher` as its own agent and wires it into the supervisor's `agents` map. The parent model can delegate to it by using the generated `researcher` delegation tool.
-
-A subagent's `config.ts` must set a non-empty `description`. The parent model reads this when deciding whether to delegate.
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.5',
-  description: 'Researches a topic and returns cited findings.',
-})
-```
-
-## How the model delegates
-
-A subagent's `description` is routing text for the parent model. Write it like a [tool description](https://mastra.ai/reference/file-based-agents/tools): explain what the subagent does and when to delegate to it.
-
-The build fails when a discovered subagent doesn't provide a non-empty description.
-
-## Isolation
-
-Subagents are isolated. A subagent doesn't inherit its parent's tools, skills, workspace, memory, processors, or subagents. Each child is a self-contained agent with its own directory.
-
-If multiple agents should share the same dependency, define it in code and assign it through each agent's config.
-
-## Nesting
-
-Subagents can declare their own `subagents/` directories, nesting up to three levels below the top-level agent. A `subagents/` directory nested deeper is ignored with a warning.
-
-```text
-src/mastra/agents/
-└── supervisor/            # depth 0
-    └── subagents/
-        └── researcher/    # depth 1
-            └── subagents/
-                └── summarizer/ # depth 2
-```
-
-## Naming rules
-
-- A subagent id that collides with one of the parent's tool keys is a build error.
-- A duplicate subagent id under the same parent is a build error.
-- If a subagent id also exists in the parent's `config.agents`, the `config.agents` entry wins and logs a warning.
-- If `config.agents` is a function, discovered subagents are ignored with a warning because they can't be statically merged.
-
-## Example
-
-This supervisor coordinates a research-and-writing flow. The `researcher` subagent owns search tools, while the `writer` subagent owns a workspace for drafting files.
-
-```text
-src/mastra/agents/
-└── research-supervisor/
-    ├── config.ts
-    ├── instructions.md
-    └── subagents/
-        ├── researcher/
-        │   ├── config.ts
-        │   ├── instructions.md
-        │   └── tools/
-        │       └── search_web.ts
-        └── writer/
-            ├── config.ts
-            ├── instructions.md
-            └── workspace/
-                └── draft-template.md
-```
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.5',
-})
-```
-
-```markdown
-You coordinate research and writing.
-
-Delegate fact gathering to `researcher`. Delegate final drafting to `writer`.
-```
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5-mini',
-  description: 'Use to gather facts, sources, and concise research notes for a topic.',
-})
-```
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.5',
-  description: 'Use to turn research notes into a structured draft.',
-})
-```

package/.docs/reference/file-based-agents/tools.md

@@ -1,63 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Tools
-
-A file-based agent discovers tools from `.ts` and `.js` files directly under its `tools/` directory. Each discovered file is imported at build time, the file must default-export a [`createTool()`](https://mastra.ai/reference/tools/create-tool) result, and the filename without its extension becomes the tool key the model can call.
-
-Use this page for the file-based convention. For tool schemas, execution options, output shaping, and approval options, see the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool).
-
-## Quickstart
-
-Place one tool per file under `tools/`. This file is exposed to the agent as `get_weather`.
-
-```typescript
-import { createTool } from '@mastra/core/tools'
-import { z } from 'zod'
-
-export default createTool({
-  id: 'get_weather',
-  description: 'Get the current weather for a city.',
-  inputSchema: z.object({
-    city: z.string(),
-  }),
-  outputSchema: z.object({
-    city: z.string(),
-    tempC: z.number(),
-  }),
-  execute: async ({ context }) => {
-    return { city: context.city, tempC: 21 }
-  },
-})
-```
-
-## Organizing tools
-
-Use one file per tool. Name the file after the action the model should take:
-
-- Use `get_weather.ts`, `search_docs.ts`, or `create_ticket.ts`.
-- Avoid vague names like `helper.ts`, `api.ts`, or `utils.ts`.
-- Co-locate tests next to the tool as `*.test.ts` or `*.spec.ts`; discovery ignores those files.
-- Keep shared helper code outside `tools/` or in files that don't match the discovered extensions under `tools/`.
-
-Because nested directories aren't discovered as tools, group related tools with clear filename prefixes instead of subfolders, such as `calendar_create_event.ts` and `calendar_list_events.ts`.
-
-## Tool options
-
-The file-based convention only controls where the tool lives and how it's registered. The tool API still comes from `createTool()`:
-
-- Use `description` to tell the model when to call the tool.
-- Use `inputSchema` and `outputSchema` for structured inputs and outputs.
-- Use `toModelOutput` when the model should see a different shape than the raw value returned from `execute`.
-- Use `requireApproval` when a tool needs human confirmation before execution.
-
-See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for all options and [tool approval](https://mastra.ai/docs/agent-controller/tool-approvals) for the approval flow.
-
-## Runtime boundary
-
-Tool code runs in your app/server runtime when the agent calls the tool. If a tool needs filesystem or shell isolation, call [workspace](https://mastra.ai/reference/file-based-agents/workspace) or sandbox APIs explicitly.
-
-## Precedence with config
-
-Discovered tools merge with any `tools` in [`config.ts`](https://mastra.ai/reference/file-based-agents/config). On a key collision, `config.tools` wins and a warning is logged.
-
-If `config.tools` is a function, discovered tools are ignored with a warning because function-valued tools can't be statically merged.

package/.docs/reference/file-based-agents/workflows.md

@@ -1,52 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Workflows
-
-Mastra discovers project-level workflows from `.ts` and `.js` files under `src/mastra/workflows/`. This convention isn't scoped to one agent: every file with a default export becomes a registered workflow, and the filename becomes the workflow key.
-
-Use this page for the file-based convention. For steps, schemas, control flow, streaming, state, and workflow execution, see [Workflows overview](https://mastra.ai/docs/workflows/overview).
-
-## Quickstart
-
-Create a file under `src/mastra/workflows/`, build the workflow with [`createWorkflow()`](https://mastra.ai/reference/workflows/workflow), and default-export it.
-
-```typescript
-import { createStep, createWorkflow } from '@mastra/core/workflows'
-import { z } from 'zod'
-
-const collectInputs = createStep({
-  id: 'collect-inputs',
-  inputSchema: z.object({ topic: z.string() }),
-  outputSchema: z.object({ topic: z.string(), audience: z.string() }),
-  execute: async ({ inputData }) => ({
-    topic: inputData.topic,
-    audience: 'engineering',
-  }),
-})
-
-const writeSummary = createStep({
-  id: 'write-summary',
-  inputSchema: z.object({ topic: z.string(), audience: z.string() }),
-  outputSchema: z.object({ report: z.string() }),
-  execute: async ({ inputData }) => ({
-    report: `Daily report about ${inputData.topic} for ${inputData.audience}.`,
-  }),
-})
-
-const dailyReport = createWorkflow({
-  id: 'daily-report',
-  inputSchema: z.object({ topic: z.string() }),
-  outputSchema: z.object({ report: z.string() }),
-})
-  .then(collectInputs)
-  .then(writeSummary)
-  .commit()
-
-export default dailyReport
-```
-
-Mastra registers this workflow under the `daily-report` key.
-
-## Precedence with code
-
-File-based workflows merge with workflows registered in [`new Mastra()`](https://mastra.ai/reference/core/mastra-class). On a key collision, the code-registered workflow wins.

package/.docs/reference/file-based-agents/workspace.md

@@ -1,74 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Workspace
-
-A [workspace](https://mastra.ai/docs/workspace/overview) gives an agent filesystem access and command execution. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`, so they can read and write files and run shell commands without extra configuration.
-
-Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Workspaces](https://mastra.ai/docs/workspace/overview).
-
-## Default workspace
-
-Without `workspace.ts`, a file-based agent gets a default [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) when the build provides a per-agent workspace path. The default workspace uses:
-
-- [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) rooted at the agent's bundled workspace directory.
-- [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) with the same working directory.
-
-This gives the agent file tools and shell tools automatically. The default workspace is per agent; subagents get nested workspace directories under their parent agent's workspace path.
-
-## Quickstart
-
-For the default workspace, don't add a file. Start with an agent directory like this:
-
-```text
-src/mastra/agents/weather/
-├── config.ts
-└── instructions.md
-```
-
-Add `workspace.ts` only when you need to customize the workspace:
-
-```typescript
-import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
-
-export default new Workspace({
-  name: 'weather-workspace',
-  filesystem: new LocalFilesystem({ basePath: './data/weather' }),
-  sandbox: new LocalSandbox({ workingDirectory: './data/weather' }),
-})
-```
-
-Visit the [`Workspace` reference](https://mastra.ai/reference/workspace/workspace-class) for the full config.
-
-## When to customize the workspace
-
-Customize the workspace when the default local directory isn't enough. Common reasons include:
-
-- Point file tools at a different filesystem root.
-- Run shell commands in a different sandbox provider.
-- Add workspace search with BM25 or vector search.
-- Share one workspace across multiple agents.
-
-For provider patterns and runtime behavior, see the [workspace overview](https://mastra.ai/docs/workspace/overview), [sandbox guide](https://mastra.ai/docs/workspace/sandbox), and [workspace search](https://mastra.ai/docs/workspace/search).
-
-## Runtime boundary
-
-The workspace filesystem controls what file tools can read and write. The sandbox controls where shell commands run. Application runtime code, including code in [`tools/`](https://mastra.ai/reference/file-based-agents/tools), still runs in your app/server process unless it explicitly calls workspace or sandbox APIs.
-
-## Seed files
-
-Add a `workspace/` directory to ship starting files with the agent. Mastra mirrors files under `workspace/` into the agent's default runtime workspace at build time, so the agent starts with those files on disk.
-
-```text
-src/mastra/agents/weather/
-├── config.ts
-└── workspace/
-    ├── README.md
-    └── data/
-        └── cities.json
-```
-
-The files are copied into the bundled workspace path, where workspace file tools and sandbox commands can read them. Symlinked seed files are skipped during mirroring.
-
-## Precedence with config
-
-`config.workspace` wins over `workspace.ts`; otherwise the default file-based workspace is used. See [`config.ts` precedence](https://mastra.ai/reference/file-based-agents/config) for the full merge table.

package/.docs/reference/memory/summarizeConversation.md

@@ -1,99 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# summarizeConversation()
-
-The standalone `summarizeConversation()` function summarizes a conversation in one shot. It distills the messages you pass in with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory) — without Observational Memory attached to an agent, and without reading from or writing to storage.
-
-Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go — for example your own database.
-
-Use this when you already have the messages in hand and want explicit control over what gets summarized. To summarize a stored thread by ID instead, use [`Memory.summarizeThread()`](https://mastra.ai/reference/memory/summarizeThread), which loads the messages for you.
-
-## Usage example
-
-```typescript
-import { summarizeConversation } from '@mastra/memory'
-
-const result = await summarizeConversation({
-  model: 'openai/gpt-5-mini',
-  messages,
-  instructions: 'Summarize this voicemail call for the business owner.',
-})
-```
-
-## Parameters
-
-**model** (`string | LanguageModel | DynamicModel`): Model that runs the summarization, such as a router string like '\_\_GATEWAY\_OPENAI\_MODEL\_MINI\_\_'.
-
-**messages** (`MastraDBMessage[]`): The conversation to summarize. When empty, the function returns an empty result without calling the model.
-
-**instructions** (`string`): Extra guidance appended to the summarizer's system prompt, such as what to focus on or who the summary is for.
-
-**extract** (`Extractor[]`): Extractors to run over the conversation. Extractors with a Zod schema run as a follow-up structured output call; schema-less extractors are extracted inline. Each extractor's onExtracted hook fires with the extracted value.
-
-**threadId** (`string`): Thread the conversation belongs to. Defaults to the first threadId found on messages. Passed to extractor contexts.
-
-**resourceId** (`string`): Resource (user) the conversation belongs to. Defaults to the first resourceId found on messages. Passed to extractor contexts.
-
-**memory** (`Memory`): Memory instance forwarded to extractor contexts. Set automatically when called through Memory.summarizeThread().
-
-**mastra** (`Mastra`): Mastra instance used to resolve custom gateway models. Set automatically when called through Memory.summarizeThread().
-
-**requestContext** (`RequestContext`): Request context forwarded to the summarizer model and extractor hooks.
-
-**abortSignal** (`AbortSignal`): Signal to cancel the summarization call.
-
-## Returns
-
-**summary** (`string`): The distilled observations produced from the conversation, in dense bullet form.
-
-**extracted** (`Record<string, unknown>`): Values produced by extract extractors, keyed by extractor slug.
-
-**extractionFailures** (`{ slug: string; error: string }[]`): Extractors that failed to produce a valid value, with the reason. Only present when at least one extractor failed.
-
-**usage** (`{ inputTokens?: number; outputTokens?: number; totalTokens?: number }`): Token usage of the summarization call.
-
-## Extended usage example
-
-The following example summarizes an in-flight voice session from messages the application already holds, and extracts a structured record:
-
-```typescript
-import { summarizeConversation, Extractor } from '@mastra/memory'
-import type { MastraDBMessage } from '@mastra/core/agent'
-import { z } from 'zod'
-import { sessionRecords } from './db'
-
-const sessionSummary = new Extractor({
-  name: 'session-summary',
-  instructions: 'Return a concise summary of the session.',
-  schema: z.object({
-    summary: z.string(),
-    sentiment: z.enum(['positive', 'neutral', 'negative']),
-    followUps: z.array(z.string()),
-  }),
-  metadataKeyPath: false, // don't persist into memory metadata — the hook owns storage
-  onExtracted: async ({ current, threadId }) => {
-    await sessionRecords.upsert({ sessionId: threadId, record: current })
-  },
-})
-
-export async function onSessionEnd(messages: MastraDBMessage[]) {
-  const { summary, extracted, extractionFailures } = await summarizeConversation({
-    model: 'openai/gpt-5-mini',
-    messages,
-    instructions: 'Summarize this support session for the account manager.',
-    extract: [sessionSummary],
-  })
-
-  if (extractionFailures?.length) {
-    console.warn('Some extractors failed', extractionFailures)
-  }
-
-  return { summary, extracted }
-}
-```
-
-### Related
-
-- [.summarizeThread()](https://mastra.ai/reference/memory/summarizeThread)
-- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
-- [Observational Memory](https://mastra.ai/reference/memory/observational-memory)

package/.docs/reference/memory/summarizeThread.md

@@ -1,93 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Memory.summarizeThread()
-
-The `.summarizeThread()` method summarizes a thread's conversation in one shot. It loads the thread's messages from storage and distills them with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory) — as a standalone call, without Observational Memory attached to an agent.
-
-Messages load page-by-page starting from the newest, bounded by `lastMessages` and `maxInputTokens`, so summarizing a long thread doesn't read its entire history from storage.
-
-Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go — for example your own database.
-
-Use this when a session ends and you want a summary or structured extraction of the whole conversation, such as a voice call at hang-up. To summarize messages you already have in hand (without loading them from a thread), use the standalone [`summarizeConversation()`](https://mastra.ai/reference/memory/summarizeConversation) function instead — it takes the same options with `messages` in place of `threadId`.
-
-## Usage example
-
-```typescript
-const result = await memory.summarizeThread({
-  model: 'openai/gpt-5-mini',
-  threadId: 'thread-123',
-  instructions: 'Summarize this voicemail call for the business owner.',
-})
-```
-
-## Parameters
-
-**threadId** (`string`): The unique identifier of the thread to summarize.
-
-**model** (`string | LanguageModel | DynamicModel`): Model that runs the summarization, such as a router string like '\_\_GATEWAY\_OPENAI\_MODEL\_MINI\_\_'.
-
-**resourceId** (`string`): ID of the resource that owns the thread. If provided, validates thread ownership. Also passed to extractor contexts.
-
-**lastMessages** (`number`): Only summarize the last N messages of the thread. By default the whole thread is loaded, bounded by maxInputTokens.
-
-**maxInputTokens** (`number`): Stop loading older messages once the collected messages exceed this estimated token count. The newest message is always included. (Default: `1000000`)
-
-**instructions** (`string`): Extra guidance appended to the summarizer's system prompt, such as what to focus on or who the summary is for.
-
-**extract** (`Extractor[]`): Extractors to run over the conversation. Extractors with a Zod schema run as a follow-up structured output call; schema-less extractors are extracted inline. Each extractor's onExtracted hook fires with the extracted value.
-
-**requestContext** (`RequestContext`): Request context forwarded to the summarizer model and extractor hooks.
-
-**abortSignal** (`AbortSignal`): Signal to cancel the summarization call.
-
-## Returns
-
-**summary** (`string`): The distilled observations produced from the conversation, in dense bullet form.
-
-**extracted** (`Record<string, unknown>`): Values produced by extract extractors, keyed by extractor slug.
-
-**extractionFailures** (`{ slug: string; error: string }[]`): Extractors that failed to produce a valid value, with the reason. Only present when at least one extractor failed.
-
-**usage** (`{ inputTokens?: number; outputTokens?: number; totalTokens?: number }`): Token usage of the summarization call.
-
-## Extended usage example
-
-The following example summarizes a finished voice call and stores a structured record in the application's own database:
-
-```typescript
-import { Extractor } from '@mastra/memory'
-import { z } from 'zod'
-import { memory } from './mastra/memory'
-import { callRecords } from './db'
-
-const callSummary = new Extractor({
-  name: 'call-summary',
-  instructions: 'Return a concise summary of the call.',
-  schema: z.object({
-    summary: z.string(),
-    sentiment: z.enum(['positive', 'neutral', 'negative']),
-    requestedServices: z.array(z.string()),
-  }),
-  metadataKeyPath: false, // don't persist into memory metadata — the hook owns storage
-  onExtracted: async ({ current, threadId, resourceId }) => {
-    await callRecords.upsert({ callId: threadId, callerId: resourceId, record: current })
-  },
-})
-
-export async function onCallEnd(threadId: string, resourceId: string) {
-  await memory.summarizeThread({
-    model: 'openai/gpt-5-mini',
-    threadId,
-    resourceId,
-    instructions: 'Summarize this voicemail call for the business owner.',
-    extract: [callSummary],
-  })
-}
-```
-
-### Related
-
-- [summarizeConversation()](https://mastra.ai/reference/memory/summarizeConversation)
-- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
-- [Observational Memory](https://mastra.ai/reference/memory/observational-memory)
-- [.recall()](https://mastra.ai/reference/memory/recall)