@mastra/mcp-docs-server 1.2.8-alpha.0 → 1.2.8-alpha.19

package/.docs/reference/cli/mastra.md

@@ -361,7 +361,7 @@ File to write. Defaults to `.env`.
 
 Manages databases attached to a project on Mastra platform. Databases are provisioned from a managed provider (for example Turso or Neon) and inject their connection env vars into deploys automatically.
 
-A database is either **environment-scoped** (its env vars only go to one environment) or **shared** (project-scoped: its env vars go to all environments). Pass the environment argument to work with environment-scoped databases; omit it for shared databases.
+A database is either **environment-scoped** (its env vars only go to one environment) or **shared** (project-scoped: its env vars go to all environments). Environment-scoped is the default for `mastra env db create` — pass an environment argument, or let the CLI pick or prompt for one. Pass `--shared` on create to attach a shared database instead. For other subcommands (`list`, `delete`, `keys`), pass the environment argument to work with environment-scoped databases and omit it for shared databases.
 
 Creating and deleting databases requires the `admin` role in the organization.
 
@@ -382,11 +382,15 @@ Emit machine-readable JSON.
 
 Provisions a managed database, attaches it, and polls until it's ready. Provisioning errors are printed with the provider's error detail.
 
-With an environment argument, the database is scoped to that environment: only it receives the database's connection env vars, and the provider region is derived from the environment's region. Without one, the database is shared by all environments.
+By default the database is scoped to a single environment: pass an environment argument to pick it, or omit the argument to have the CLI pick for you. When the project has one environment, that environment is used. When it has several, the CLI prompts you to select one interactively; in non-interactive contexts (CI, `--json`) an environment argument is required. Pass `--shared` to attach a project-scoped database that's shared by every environment instead.
+
+Environment-scoped databases inherit their provider region from the environment. Shared databases accept `--region`.
 
 ```bash
-mastra env db create <env> --kind turso
-mastra env db create --kind neon --name my-app-db --region aws-us-east-1
+mastra env db create --kind turso                                    # picks or prompts for an environment
+mastra env db create staging --kind turso                            # scoped to the "staging" environment
+mastra env db create --kind turso --shared                           # shared by all environments
+mastra env db create --kind neon --name my-app-db --region aws-us-east-1 --shared
 ```
 
 #### `--kind`
@@ -401,13 +405,17 @@ Database name. Defaults to a name derived from the project slug (for example `my
 
 Provider region ID for shared databases. Ignored for environment-scoped databases.
 
+#### `--shared`
+
+Attach as a project-scoped database that's shared by every environment. Cannot be combined with an environment argument.
+
 #### `--no-wait`
 
 Return immediately after the attach is queued instead of polling until the database is ready. Check progress later with `mastra env db show`.
 
 #### `--json`
 
-Emit machine-readable JSON.
+Emit machine-readable JSON. In this mode, an environment argument or `--shared` is required when the project has more than one environment (no interactive prompt).
 
 ### `mastra env db show`
 
@@ -429,7 +437,7 @@ Emit machine-readable JSON. Secret values are masked unless `--show-secrets` is
 
 ### `mastra env db delete`
 
-Permanently deletes a database with the provider, including all of its data. This cannot be undone. The CLI prompts for confirmation unless `--yes` is passed. After deletion, deploys no longer receive the database's env vars.
+Permanently deletes a database with the provider, including all of its data. This can't be undone. The CLI prompts for confirmation unless `--yes` is passed. After deletion, deploys no longer receive the database's env vars.
 
 ```bash
 mastra env db delete <database>

package/.docs/reference/code-sdk/mount-agent-controller.md

@@ -27,9 +27,7 @@ Pass an existing `mastra` to mount the controller onto a Mastra instance that al
 import { Mastra } from '@mastra/core/mastra'
 import { mountAgentControllerOnMastra } from '@mastra/code-sdk'
 
-const mastra = new Mastra({
-  /* ... */
-})
+const mastra = new Mastra({/* ... */})
 
 const { controller } = await mountAgentControllerOnMastra({ mastra })
 ```

package/.docs/reference/core/getMCPServer.md

@@ -12,9 +12,7 @@ const myServer = new MCPServer({
   id: 'my-mcp-server',
   name: 'My Server',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
 })
 
 export const mastra = new Mastra({

package/.docs/reference/core/getMCPServerById.md

@@ -12,9 +12,7 @@ const myServer = new MCPServer({
   id: 'my-mcp-server',
   name: 'My Server',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
 })
 
 export const mastra = new Mastra({

package/.docs/reference/core/getTool.md

@@ -0,0 +1,33 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Mastra.getTool()
+
+The `.getTool()` method retrieves a tool from the Mastra-level registry by its registration key.
+
+## Usage example
+
+Register a tool under the `weather` key, then use that key to retrieve it.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { weatherTool } from './tools/weather-tool'
+
+export const mastra = new Mastra({
+  tools: {
+    weather: weatherTool,
+  },
+})
+
+const tool = mastra.getTool('weather')
+```
+
+## Parameters
+
+**name** (`TToolName extends keyof TTools`): The registration key of the tool in the Mastra tools registry.
+
+## Related
+
+- [Share tools across agents](https://mastra.ai/docs/agents/using-tools)
+- [Mastra class](https://mastra.ai/reference/core/mastra-class)
+- [Mastra.getToolById()](https://mastra.ai/reference/core/getToolById)
+- [Mastra.listTools()](https://mastra.ai/reference/core/listTools)

package/.docs/reference/core/getToolById.md

@@ -0,0 +1,48 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Mastra.getToolById()
+
+The `.getToolById()` method first searches the Mastra-level registry for a tool with a matching intrinsic `id`. If no intrinsic ID matches, it treats the value as a registration key.
+
+## Usage example
+
+This example uses `weather` as the registration key and `weather-tool` as the tool's intrinsic ID.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Fetches weather for a location',
+  inputSchema: z.object({
+    location: z.string(),
+  }),
+  outputSchema: z.object({
+    weather: z.string(),
+  }),
+  execute: async ({ location }) => ({
+    weather: `Weather for ${location}`,
+  }),
+})
+
+export const mastra = new Mastra({
+  tools: {
+    weather: weatherTool,
+  },
+})
+
+const toolById = mastra.getToolById('weather-tool')
+```
+
+## Parameters
+
+**id** (`TTools[TToolName]['id']`): The intrinsic tool ID to find. When no tool has that ID, Mastra uses the value as a registration key.
+
+## Related
+
+- [Share tools across agents](https://mastra.ai/docs/agents/using-tools)
+- [Mastra class](https://mastra.ai/reference/core/mastra-class)
+- [Mastra.getTool()](https://mastra.ai/reference/core/getTool)
+- [Mastra.listTools()](https://mastra.ai/reference/core/listTools)

package/.docs/reference/core/getWorkflow.md

@@ -13,9 +13,7 @@ const run = await workflow.createRun()
 
 // TypeScript will properly infer the input schema type
 await run.startAsync({
-  inputData: {
-    /* properly typed */
-  },
+  inputData: {/* properly typed */},
 })
 ```
 

package/.docs/reference/core/listMCPServers.md

@@ -12,18 +12,14 @@ const server1 = new MCPServer({
   id: 'server-one',
   name: 'Server One',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
 })
 
 const server2 = new MCPServer({
   id: 'server-two',
   name: 'Server Two',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
 })
 
 export const mastra = new Mastra({

package/.docs/reference/core/listTools.md

@@ -0,0 +1,38 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Mastra.listTools()
+
+The `.listTools()` method returns the tools configured on a Mastra instance. The returned record uses Mastra registration keys and tool instances as values.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { weatherTool } from './tools/weather-tool'
+
+export const mastra = new Mastra({
+  tools: {
+    weather: weatherTool,
+  },
+})
+
+const tools = mastra.listTools()
+const weather = tools?.weather
+```
+
+## Parameters
+
+This method doesn't accept any parameters.
+
+## Returns
+
+**tools** (`TTools | undefined`): The Mastra-level tool registry, where each key is a registration key and each value is a tool instance. Returns undefined when no registry is available.
+
+This method lists the Mastra-level registry. It doesn't include tools that exist only in a function-based Agent `tools` callback.
+
+## Related
+
+- [Share tools across agents](https://mastra.ai/docs/agents/using-tools)
+- [Mastra class](https://mastra.ai/reference/core/mastra-class)
+- [Mastra.getTool()](https://mastra.ai/reference/core/getTool)
+- [Mastra.getToolById()](https://mastra.ai/reference/core/getToolById)

package/.docs/reference/core/mastra-class.md

@@ -53,7 +53,7 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **agents** (`Record<string, Agent>`): Agent instances to register, keyed by name (Default: `{}`)
 
-**tools** (`Record<string, ToolApi>`): Custom tools to register. Structured as a key-value pair, with keys being the tool name and values being the tool function. (Default: `{}`)
+**tools** (`Record<string, ToolApi>`): Tool instances to register. Keys are registration keys used by \`getTool()\`, and values are tool instances. Use \`getToolById()\` for intrinsic ID lookup and \`listTools()\` to read the registry. (Default: `{}`)
 
 **storage** (`MastraCompositeStore`): Storage engine instance for persisting data
 

package/.docs/reference/datasets/addItem.md

@@ -11,9 +11,7 @@ Adds a single item to the dataset. Each item has an input, optional ground truth
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/addItems.md

@@ -11,9 +11,7 @@ Adds multiple items to the dataset in a single bulk operation.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/compareExperiments.md

@@ -11,9 +11,7 @@ Compares two or more experiments, producing per-item and per-scorer comparisons.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const comparison = await mastra.datasets.compareExperiments({
   experimentIds: ['exp-baseline', 'exp-new'],

package/.docs/reference/datasets/create.md

@@ -12,9 +12,7 @@ Creates a new dataset. Use Standard JSON Schema (Zod, Valibot, ArkType, etc.) fo
 import { Mastra } from '@mastra/core'
 import { z } from 'zod'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 // Create with metadata
 const dataset = await mastra.datasets.create({

package/.docs/reference/datasets/dataset.md

@@ -13,9 +13,7 @@ The `Dataset` class provides methods for item CRUD, versioning, and experiment m
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.create({
   name: 'QA pairs',
@@ -44,9 +42,7 @@ console.log(`${summary.succeededCount}/${summary.totalItems} succeeded`)
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/datasets-manager.md

@@ -13,9 +13,7 @@ The `DatasetsManager` class provides the public API for managing datasets, inclu
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 // Create a dataset
 const dataset = await mastra.datasets.create({
@@ -32,9 +30,7 @@ const { datasets } = await mastra.datasets.list()
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 // Get by ID
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
@@ -50,9 +46,7 @@ Retrieves a specific experiment (run) by ID. Unlike `dataset.getExperiment()`, t
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 // Get experiment directly without knowing the dataset
 const experiment = await mastra.datasets.getExperiment({
@@ -68,9 +62,7 @@ console.log(`Status: ${experiment.status}`)
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const comparison = await mastra.datasets.compareExperiments({
   experimentIds: ['exp-1', 'exp-2'],
@@ -83,9 +75,7 @@ const comparison = await mastra.datasets.compareExperiments({
 `DatasetsManager` isn't instantiated directly. Access it from a `Mastra` instance:
 
 ```typescript
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 const datasetsManager = mastra.datasets
 ```
 

package/.docs/reference/datasets/delete.md

@@ -11,9 +11,7 @@ Deletes a dataset by ID, including all items, versions, and experiments.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 await mastra.datasets.delete({ id: 'dataset-id' })
 ```

package/.docs/reference/datasets/deleteExperiment.md

@@ -11,9 +11,7 @@ Deletes an experiment (run) by ID, including all associated results.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/deleteItem.md

@@ -11,9 +11,7 @@ Deletes a single item from the dataset by ID.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/deleteItems.md

@@ -11,9 +11,7 @@ Deletes multiple items from the dataset in a single bulk operation.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/get.md

@@ -11,9 +11,7 @@ Retrieves an existing dataset by ID. Throws a `MastraError` if the dataset doesn
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/getDetails.md

@@ -11,9 +11,7 @@ Retrieves the full dataset record from storage, including metadata, schemas, and
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/getExperiment.md

@@ -11,9 +11,7 @@ Retrieves a specific experiment (run) by its ID.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/getItem.md

@@ -11,9 +11,7 @@ Retrieves a single dataset item by ID, optionally at a specific dataset version.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/getItemHistory.md

@@ -11,9 +11,7 @@ Retrieves the full SCD-2 (Slowly Changing Dimension Type 2) history of a specifi
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/list.md

@@ -11,9 +11,7 @@ Lists datasets with pagination and optional filters. Filters are applied at the
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const { datasets, pagination } = await mastra.datasets.list({ page: 0, perPage: 10 })
 

package/.docs/reference/datasets/listExperimentResults.md

@@ -11,9 +11,7 @@ Lists individual item results for a specific experiment with optional filters an
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/listExperiments.md

@@ -11,9 +11,7 @@ Lists experiments (runs) for this dataset with optional filters and pagination.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/listItems.md

@@ -11,9 +11,7 @@ Lists items in the dataset. When only `version` is provided, returns a bare `Dat
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/listVersions.md

@@ -11,9 +11,7 @@ Lists all versions of the dataset with pagination.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/startExperiment.md

@@ -11,9 +11,7 @@ Runs an experiment on the dataset and waits for completion. Executes all items a
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/startExperimentAsync.md

@@ -11,9 +11,7 @@ Starts an experiment asynchronously (fire-and-forget). Returns immediately with
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/update.md

@@ -12,9 +12,7 @@ Updates dataset metadata, name, description, and/or schemas. Use Standard JSON S
 import { Mastra } from '@mastra/core'
 import { z } from 'zod'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/updateItem.md

@@ -11,9 +11,7 @@ Updates an existing item in the dataset. Only the provided fields are updated. U
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/editor/mastra-editor.md

@@ -14,9 +14,7 @@ import { MastraEditor } from '@mastra/editor'
 import { ComposioToolProvider } from '@mastra/editor/providers/composio'
 
 export const mastra = new Mastra({
-  agents: {
-    /* your agents */
-  },
+  agents: {/* your agents */},
   editor: new MastraEditor({
     toolProviders: {
       composio: new ComposioToolProvider({