@mastra/mcp-docs-server 1.2.7-alpha.1 → 1.2.7-alpha.12

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

@@ -1,297 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# File-based agents
-
-**Added in:** `@mastra/core@1.48.0`
-
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
-
-You can define an agent by file convention instead of constructing it in code. Mastra discovers a directory under `src/mastra/agents/<name>/`, assembles an [`Agent`](https://mastra.ai/reference/agents/agent), and registers it on your [`Mastra`](https://mastra.ai/reference/core/mastra-class) instance.
-
-## When to use file-based agents
-
-Use file-based agents when you want one directory per agent, with configuration, instructions, tools, skills, workspace files, and subagents grouped together.
-
-Keep using [`new Agent()`](https://mastra.ai/reference/agents/agent) in code when you need dynamic configuration, programmatic registration, or a shared agent instance across modules. Both approaches can coexist: code-registered agents are always present, and the bundler adds file-based agents when you run through the Mastra CLI.
-
-## Quickstart
-
-Create a directory for the agent and add a `config.ts`. Use `agentConfig` so the partial config is typed while sibling files supply the rest.
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.5',
-  // instructions omitted -> taken from instructions.md
-  // tools omitted -> taken from tools/*.ts
-})
-```
-
-Add the agent instructions:
-
-```markdown
-You are a helpful weather assistant. Answer questions about current conditions and forecasts.
-```
-
-Add a tool. The filename becomes the tool key, so this file is exposed 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() }),
-  execute: async ({ context }) => ({ city: context.city, tempC: 21 }),
-})
-```
-
-Your `src/mastra/index.ts` stays the same. The discovered agent is registered automatically when you run the app through `mastra dev` or `mastra build`.
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { Agent } from '@mastra/core/agent'
-
-const supportAgent = new Agent({
-  id: 'support',
-  name: 'support',
-  instructions: 'You are a support agent.',
-  model: 'openai/gpt-5.5',
-})
-
-// `support` is registered in code; `weather` is discovered from the filesystem.
-export const mastra = new Mastra({
-  agents: { support: supportAgent },
-})
-```
-
-Start the app through the Mastra CLI:
-
-**npm**:
-
-```bash
-npx mastra dev
-```
-
-**pnpm**:
-
-```bash
-pnpm dlx mastra dev
-```
-
-**Yarn**:
-
-```bash
-yarn dlx mastra dev
-```
-
-**Bun**:
-
-```bash
-bun x mastra dev
-```
-
-## Folder structure
-
-The following table shows the supported file-based agent surface:
-
-| File / directory                        | Maps to                                                                                                                                   |
-| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `agents/<name>/config.ts`               | Default export merged into the agent config. `id` and `name` default to `<name>`.                                                         |
-| `agents/<name>/instructions.md`         | The agent `instructions`. The file contents are inlined into generated code.                                                              |
-| `agents/<name>/tools/*.ts`              | Each default-exported [`createTool()`](https://mastra.ai/reference/tools/create-tool). The tool key defaults to the filename.             |
-| `agents/<name>/skills/*.ts`             | Each default-exported [`createSkill()`](https://mastra.ai/reference/agents/createSkill), added to the agent `skills`.                     |
-| `agents/<name>/skills/<skill>/SKILL.md` | A packaged skill. Frontmatter supplies `name` and `description`, the body is the instructions, and files under `references/` are inlined. |
-| `agents/<name>/skills/<skill>.md`       | A flat skill. The filename is the skill name and the body is the instructions.                                                            |
-| `agents/<name>/memory.ts`               | Default export: a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance used as the agent `memory`.                        |
-| `agents/<name>/workspace.ts`            | Default export: a [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) for the agent.                                     |
-| `agents/<name>/workspace/`              | Seed files mirrored into the agent's default workspace at build time.                                                                     |
-| `agents/<name>/subagents/<childId>/`    | A declared subagent with the same layout as an agent directory. Wired into the parent as a delegation tool named `<childId>`.             |
-
-Test files named `*.test.ts`, `*.spec.ts`, `*.test.js`, and `*.spec.js` are ignored during tool and skill discovery.
-
-## Add skills
-
-Add skills to a file-based agent by placing them under `agents/<name>/skills/`. Three layouts are supported, and they're inlined into the bundle at build time so the deployed agent doesn't read them from disk at runtime.
-
-- A `.ts` file can default-export `createSkill()`:
-
-  ```typescript
-  import { createSkill } from '@mastra/core/skills'
-
-  export default createSkill({
-    name: 'forecasting',
-    description: 'Use when the user asks about multi-day forecasts.',
-    instructions: 'Summarize the forecast day by day and call out precipitation.',
-  })
-  ```
-
-  > **Note:** Visit [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill) for the full API.
-
-- A packaged `SKILL.md` directory uses frontmatter for the name and description. Files under `references/` are inlined with the skill.
-
-  ```markdown
-  ---
-  name: severe-weather
-  description: Use when conditions include storms, flooding, or other hazards.
-  ---
-
-  Lead with the active alert, then give safety guidance.
-  ```
-
-- A flat `<skill>.md` file uses the filename as the skill name:
-
-  ```markdown
-  Always report temperatures in both Celsius and Fahrenheit.
-  ```
-
-Discovered skills merge with any `skills` in `config.ts`. On a name collision, `config.skills` wins and a warning is logged. If `config.skills` is a function, discovered skills are ignored with a warning because they can't be statically merged.
-
-## Add memory
-
-Give a file-based agent [memory](https://mastra.ai/docs/memory/overview) by adding a `memory.ts` that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance:
-
-```typescript
-import { Memory } from '@mastra/memory'
-
-export default new Memory()
-```
-
-The exported instance becomes the agent's `memory`. You can also set `memory` directly in `config.ts`. `config.memory` wins over `memory.ts`, and a warning is logged when both are present. If neither is present, the agent has no memory, which is the default.
-
-## Add a workspace
-
-When a file-based agent is discovered through `mastra dev` or `mastra build`, it gets a default workspace unless `config.workspace` or `workspace.ts` supplies one. The default workspace uses a contained filesystem and shell sandbox rooted at a per-agent `workspace/` directory in the bundle.
-
-To customize it, add a `workspace.ts` that default-exports a [`Workspace`](https://mastra.ai/reference/workspace/workspace-class):
-
-```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' }),
-})
-```
-
-You can also set `workspace` directly in `config.ts`. `config.workspace` wins over `workspace.ts`, and `workspace.ts` wins over the default workspace.
-
-### Seed files
-
-Add a `workspace/` directory to ship files with the agent. Mastra mirrors every file under it into the agent's default 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
-```
-
-Seed files are copied into the bundle next to the running server. Commit the starting files alongside the agent that uses them.
-
-## Add subagents
-
-A file-based agent can declare **subagents**, specialist child agents it can delegate to. Add a `subagents/` directory under the agent, with one directory per subagent. Each subagent directory has the same layout as a top-level agent: `config.ts`, `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `workspace/`.
-
-```text
-src/mastra/agents/
-  supervisor/
-    config.ts
-    instructions.md
-    subagents/
-      researcher/
-        config.ts
-        instructions.md
-        tools/
-          search.ts
-```
-
-Each subagent is assembled as its own agent and wired into the parent's `agents` map. The agent loop lowers it into a model-visible delegation tool. The tool name is the bare directory name, so the example above exposes `researcher` to the supervisor.
-
-A subagent's `config.ts` must set a non-empty `description`. The description is what the model sees when deciding whether to delegate, so the build fails if it's missing.
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.5',
-  description: 'Researches a topic and returns cited findings.',
-})
-```
-
-Subagents are isolated. A subagent inherits nothing from its parent. Its tools, skills, and workspace come only from its own directory, and any absent slot falls back to the same framework defaults as a top-level agent.
-
-Subagents can declare their own `subagents/` directories, nesting up to three levels below the top-level agent. A `subagents/` directory deeper than that 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.
-
-## Precedence rules
-
-File-based and code-based agents coexist with deterministic rules:
-
-- **Code wins on name collisions:** If an agent name exists in both code and the filesystem, the code-registered agent is kept and a warning is logged.
-- **A folder can hold a code agent:** If `config.ts` exports a configured `new Agent({ id: 'file-based-agent', ... })`, that instance is used as-is. Sibling `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `subagents/` entries are ignored with warnings.
-- **Instructions:** Dynamic function instructions in `config.ts` win over `instructions.md`. Otherwise, `instructions.md` wins over a static `instructions` string. If neither is present, the build fails for that agent.
-- **Model:** A missing `model` fails the build and names the agent directory.
-- **Tools:** Tools from `tools/*.ts` merge with `config.tools`. 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.
-- **Skills:** Skills from `skills/` merge with `config.skills`. On a name collision, `config.skills` wins and a warning is logged. If `config.skills` is a function, discovered skills are ignored with a warning.
-- **Memory:** `config.memory` wins over `memory.ts`, and a warning is logged when both are present. If neither is set, the agent has no memory.
-- **Workspace:** `config.workspace` wins over `workspace.ts`, which wins over the default workspace.
-- **Subagents:** Subagents from `subagents/` merge with `config.agents`. On an id collision, `config.agents` wins and a warning is logged. A subagent id that collides with a tool key, or a duplicate subagent id, is a build error.
-
-## What happens at build time
-
-File-based agents are discovered by the Mastra **bundler**, the step that runs under `mastra dev` and `mastra build`.
-
-File-based agents are registered only when your app runs through the Mastra CLI. If you import your `mastra` instance directly, `agents/<name>/` directories aren't discovered.
-
-When you consume Mastra as a library, register those agents in code instead of relying on file discovery:
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { Agent } from '@mastra/core/agent'
-
-const weather = new Agent({
-  id: 'weather',
-  name: 'weather',
-  instructions: 'You are a helpful weather assistant.',
-  model: 'openai/gpt-5.5',
-})
-
-export const mastra = new Mastra({
-  agents: { weather },
-})
-```
-
-## Related
-
-- [Agents overview](https://mastra.ai/docs/agents/overview)
-- [Tools](https://mastra.ai/docs/agents/using-tools)
-- [Skills](https://mastra.ai/docs/agents/skills)
-- [Memory](https://mastra.ai/docs/memory/overview)
-- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
-- [Workspace](https://mastra.ai/docs/workspace/overview)
-- [Studio overview](https://mastra.ai/docs/studio/overview)
-- [`Agent` reference](https://mastra.ai/reference/agents/agent)
-- [`createTool()` reference](https://mastra.ai/reference/tools/create-tool)
-- [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)
-- [`Memory` reference](https://mastra.ai/reference/memory/memory-class)
-- [`Workspace` reference](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/docs/memory/storage.md

@@ -1,267 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Storage
-
-For agents to remember previous interactions, Mastra needs a storage adapter. Use one of the [supported providers](#supported-providers) and pass it to 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',
-  }),
-})
-```
-
-> **Sharing the database with Studio:** When running `mastra dev` alongside your application (e.g., Next.js), use an absolute path to ensure both processes access the same database:
->
-> ```typescript
-> url: 'file:/absolute/path/to/your/project/mastra.db'
-> ```
->
-> Relative paths like `file:./mastra.db` resolve based on each process's working directory, which may differ.
-
-This configures instance-level storage, which all agents share by default. You can also configure [agent-level storage](#agent-level-storage) for isolated data boundaries.
-
-Mastra automatically initializes the necessary storage structures on first interaction. See [Storage Overview](https://mastra.ai/reference/storage/overview) for domain coverage and the schema used by the built-in database-backed domains.
-
-## Supported providers
-
-Each provider page includes installation instructions, configuration parameters, and usage examples:
-
-- [libSQL](https://mastra.ai/reference/storage/libsql)
-- [PostgreSQL](https://mastra.ai/reference/storage/postgresql)
-- [MongoDB](https://mastra.ai/reference/storage/mongodb)
-- [Upstash](https://mastra.ai/reference/storage/upstash)
-- [Redis](https://mastra.ai/reference/storage/redis)
-- [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
-- [Cloudflare KV & Durable Objects](https://mastra.ai/reference/storage/cloudflare)
-- [Convex](https://mastra.ai/reference/storage/convex)
-- [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
-- [LanceDB](https://mastra.ai/reference/storage/lance)
-- [Microsoft SQL Server](https://mastra.ai/reference/storage/mssql)
-- [Google Cloud Spanner](https://mastra.ai/reference/storage/spanner)
-
-> **Tip:** libSQL is the easiest way to get started because it doesn’t require running a separate database server.
-
-## Configuration scope
-
-Storage can be configured at the instance level (shared by all agents) or at the agent level (isolated to a specific agent).
-
-### Instance-level storage
-
-Add storage to your Mastra instance so all agents, workflows, observability traces, and scores share the same storage backend:
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { PostgresStore } from '@mastra/pg'
-
-export const mastra = new Mastra({
-  storage: new PostgresStore({
-    id: 'mastra-storage',
-    connectionString: process.env.DATABASE_URL,
-  }),
-})
-
-// Both agents inherit storage from the Mastra instance above
-const agent1 = new Agent({ id: 'agent-1', memory: new Memory() })
-const agent2 = new Agent({ id: 'agent-2', memory: new Memory() })
-```
-
-This is useful when all primitives share the same storage backend and have similar performance, scaling, and operational requirements.
-
-#### Composite storage
-
-[Composite storage](https://mastra.ai/reference/storage/composite) is an alternative way to configure instance-level storage. Use `MastraCompositeStore` to route `memory` and any other [supported domains](https://mastra.ai/reference/storage/composite) to different storage providers.
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { MastraCompositeStore } from '@mastra/core/storage'
-import { MemoryLibSQL } from '@mastra/libsql'
-import { WorkflowsPG } from '@mastra/pg'
-import { ObservabilityStorageClickhouse } from '@mastra/clickhouse'
-
-export const mastra = new Mastra({
-  storage: new MastraCompositeStore({
-    id: 'composite',
-    domains: {
-      memory: new MemoryLibSQL({ url: 'file:./memory.db' }),
-      workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
-      observability: new ObservabilityStorageClickhouse({
-        url: process.env.CLICKHOUSE_URL,
-        username: process.env.CLICKHOUSE_USERNAME,
-        password: process.env.CLICKHOUSE_PASSWORD,
-      }),
-    },
-  }),
-})
-```
-
-This is useful when different types of data have different performance or operational requirements, such as low-latency storage for memory, durable storage for workflows, and high-throughput storage for observability.
-
-#### Retention
-
-Storage grows without bound by default. To cap growth, declare per-table `maxAge` policies in the `retention` config and call `storage.prune()` from your own scheduler to delete old rows. Anything you don't configure is kept forever. See [Storage retention](https://mastra.ai/reference/storage/retention) for `prune()` and the full config shape.
-
-### Agent-level storage
-
-Agent-level storage overrides storage configured at the instance level. Add storage to a specific agent when you need to keep data separate or use different providers per agent.
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { Memory } from '@mastra/memory'
-import { PostgresStore } from '@mastra/pg'
-
-export const agent = new Agent({
-  id: 'agent',
-  memory: new Memory({
-    storage: new PostgresStore({
-      id: 'agent-storage',
-      connectionString: process.env.AGENT_DATABASE_URL,
-    }),
-  }),
-})
-```
-
-## Threads and resources
-
-Mastra organizes conversations using two identifiers:
-
-- **Thread**: A conversation session containing a sequence of messages.
-- **Resource**: The entity that owns the thread, such as a user, organization, project, or any other domain entity in your application.
-
-Both identifiers are required for agents to store information:
-
-**.generate()**:
-
-```typescript
-const response = await agent.generate('hello', {
-  memory: {
-    thread: 'conversation-abc-123',
-    resource: 'user_123',
-  },
-})
-```
-
-**.stream()**:
-
-```typescript
-const stream = await agent.stream('hello', {
-  memory: {
-    thread: 'conversation-abc-123',
-    resource: 'user_123',
-  },
-})
-```
-
-> **Note:** [Studio](https://mastra.ai/docs/studio/overview) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
-
-### Thread title generation
-
-Mastra can automatically generate descriptive thread titles based on the user's first message when `generateTitle` is enabled.
-
-Use this option when implementing a ChatGPT-style chat interface to render a title alongside each thread in the conversation list (for example, in a sidebar) derived from the thread’s initial user message.
-
-```typescript
-export const agent = new Agent({
-  id: 'agent',
-  memory: new Memory({
-    options: {
-      generateTitle: true,
-    },
-  }),
-})
-```
-
-Title generation runs asynchronously after the agent responds and doesn't affect response time.
-
-To optimize cost or behavior, provide a smaller [`model`](https://mastra.ai/models) and custom `instructions`:
-
-```typescript
-export const agent = new Agent({
-  id: 'agent',
-  memory: new Memory({
-    options: {
-      generateTitle: {
-        model: 'openai/gpt-5-mini',
-        instructions: 'Generate a 1 word title',
-      },
-    },
-  }),
-})
-```
-
-## Semantic recall
-
-Semantic recall has different storage requirements - it needs a vector database in addition to the standard storage adapter. See [Semantic recall](https://mastra.ai/docs/memory/semantic-recall) for setup and supported vector providers.
-
-## Handling large attachments
-
-Some storage providers enforce record size limits that base64-encoded file attachments (such as images) can exceed:
-
-| Provider                                                           | Record size limit |
-| ------------------------------------------------------------------ | ----------------- |
-| [DynamoDB](https://mastra.ai/reference/storage/dynamodb)           | 400 KB            |
-| [Convex](https://mastra.ai/reference/storage/convex)               | 1 MiB             |
-| [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1) | 1 MiB             |
-
-PostgreSQL, MongoDB, and libSQL have higher limits and are generally unaffected.
-
-To avoid this, use an input processor to upload attachments to external storage (S3, R2, GCS, [Convex file storage](https://docs.convex.dev/file-storage), etc.) and replace them with URL references before persistence.
-
-```typescript
-import type { Processor } from '@mastra/core/processors'
-import type { MastraDBMessage } from '@mastra/core/memory'
-
-export class AttachmentUploader implements Processor {
-  id = 'attachment-uploader'
-
-  async processInput({ messages }: { messages: MastraDBMessage[] }) {
-    return Promise.all(messages.map(msg => this.processMessage(msg)))
-  }
-
-  async processMessage(msg: MastraDBMessage) {
-    const attachments = msg.content.experimental_attachments
-    if (!attachments?.length) return msg
-
-    const uploaded = await Promise.all(
-      attachments.map(async att => {
-        // Skip if already a URL
-        if (!att.url?.startsWith('data:')) return att
-
-        // Upload base64 data and replace with URL
-        const url = await this.upload(att.url, att.contentType)
-        return { ...att, url }
-      }),
-    )
-
-    return { ...msg, content: { ...msg.content, experimental_attachments: uploaded } }
-  }
-
-  async upload(dataUri: string, contentType?: string): Promise<string> {
-    const base64 = dataUri.split(',')[1]
-    const buffer = Buffer.from(base64, 'base64')
-
-    // Replace with your storage provider (S3, R2, GCS, Convex, etc.)
-    // return await s3.upload(buffer, contentType);
-    throw new Error('Implement upload() with your storage provider')
-  }
-}
-```
-
-Use the processor with your agent:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { Memory } from '@mastra/memory'
-import { AttachmentUploader } from './processors/attachment-uploader'
-
-const agent = new Agent({
-  id: 'my-agent',
-  memory: new Memory({ storage: yourStorage }),
-  inputProcessors: [new AttachmentUploader()],
-})
-```