@mastra/mcp-docs-server 0.13.18-alpha.1 → 0.13.19-alpha.0

package/.docs/raw/reference/observability/providers/arize-phoenix.mdx

@@ -0,0 +1,120 @@
+---
+title: "Reference: Arize Phoenix Integration | Mastra Observability Docs"
+description: Documentation for integrating Arize Phoenix with Mastra, an open-source AI observability platform for monitoring and evaluating LLM applications.
+---
+
+# Arize Phoenix
+
+Arize Phoenix is an open-source AI observability platform designed for monitoring, evaluating, and improving LLM applications. It can be self-hosted or used via Phoenix Cloud.
+
+## Configuration
+
+### Phoenix Cloud
+
+If you're using Phoenix Cloud, configure these environment variables:
+
+```env
+PHOENIX_API_KEY="your-phoenix-api-key"
+PHOENIX_COLLECTOR_ENDPOINT="your-phoenix-hostname"
+```
+
+#### Getting Your Credentials
+
+1. Sign up for an Arize Phoenix account at [app.phoenix.arize.com](https://app.phoenix.arize.com/login)
+2. Grab your API key from the Keys option on the left bar
+3. Note your Phoenix hostname for the collector endpoint
+
+### Self-Hosted Phoenix
+
+If you're running a self-hosted Phoenix instance, configure:
+
+```env
+PHOENIX_COLLECTOR_ENDPOINT="http://localhost:6006"
+# Optional: If authentication enabled
+PHOENIX_API_KEY="your-api-key"
+```
+
+## Installation
+
+Install the necessary packages:
+
+```bash
+npm install @arizeai/openinference-mastra@^2.2.0
+```
+
+## Implementation
+
+Here's how to configure Mastra to use Phoenix with OpenTelemetry:
+
+### Phoenix Cloud Configuration
+
+```typescript
+import { Mastra } from "@mastra/core";
+import {
+  OpenInferenceOTLPTraceExporter,
+  isOpenInferenceSpan,
+} from "@arizeai/openinference-mastra";
+
+export const mastra = new Mastra({
+  // ... other config
+  telemetry: {
+    serviceName: "my-mastra-app",
+    enabled: true,
+    export: {
+      type: "custom",
+      exporter: new OpenInferenceOTLPTraceExporter({
+        url: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
+        headers: {
+          Authorization: `Bearer ${process.env.PHOENIX_API_KEY}`,
+        },
+        spanFilter: isOpenInferenceSpan,
+      }),
+    },
+  },
+});
+```
+
+### Self-Hosted Phoenix Configuration
+
+```typescript
+import { Mastra } from "@mastra/core";
+import {
+  OpenInferenceOTLPTraceExporter,
+  isOpenInferenceSpan,
+} from "@arizeai/openinference-mastra";
+
+export const mastra = new Mastra({
+  // ... other config
+  telemetry: {
+    serviceName: "my-mastra-app",
+    enabled: true,
+    export: {
+      type: "custom",
+      exporter: new OpenInferenceOTLPTraceExporter({
+        url: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
+        spanFilter: isOpenInferenceSpan,
+      }),
+    },
+  },
+});
+```
+
+## What Gets Automatically Traced
+
+Mastra's comprehensive tracing captures:
+
+- **Agent Operations**: All agent generation, streaming, and interaction calls
+- **LLM Interactions**: Complete model calls with input/output messages and metadata
+- **Tool Executions**: Function calls made by agents with parameters and results
+- **Workflow Runs**: Step-by-step workflow execution with timing and dependencies
+- **Memory Operations**: Agent memory queries, updates, and retrieval operations
+
+All traces follow OpenTelemetry standards and include relevant metadata such as model parameters, token usage, execution timing, and error details.
+
+## Dashboard
+
+Once configured, you can view your traces and analytics in Phoenix:
+- **Phoenix Cloud**: [app.phoenix.arize.com](https://app.phoenix.arize.com)
+- **Self-hosted**: Your Phoenix instance URL (e.g., `http://localhost:6006`)
+
+For self-hosting options, see the [Phoenix self-hosting documentation](https://arize.com/docs/phoenix/self-hosting).

package/.docs/raw/reference/observability/providers/index.mdx

@@ -1,12 +1,14 @@
 ---
 title: "Reference: Provider List | Observability | Mastra Docs"
-description: Overview of observability providers supported by Mastra, including Dash0, SigNoz, Braintrust, Langfuse, and more.
+description: Overview of observability providers supported by Mastra, including Arize AX, Arize Phoenix, Dash0, SigNoz, Braintrust, Langfuse, and more.
 ---
 
 # Observability Providers
 
 Observability providers include:
 
+- [Arize AX](./providers/arize-ax.mdx)
+- [Arize Phoenix](./providers/arize-phoenix.mdx)
 - [Braintrust](./providers/braintrust.mdx)
 - [Dash0](./providers/dash0.mdx)
 - [Laminar](./providers/laminar.mdx)

package/.docs/raw/reference/rag/metadata-filters.mdx

@@ -319,6 +319,20 @@ const results = await store.query({
 ### Couchbase
 - Currently does not have support for metadata filters. Filtering must be done client-side after retrieving results or by using the Couchbase SDK's Search capabilities directly for more complex queries.
 
+### Amazon S3 Vectors
+
+* Equality values must be primitives (string/number/boolean). `null`/`undefined`, arrays, objects, and Date are not allowed for equality. Range operators accept numbers or Date (Dates are normalized to epoch ms).
+* `$in`/`$nin` require **non-empty arrays of primitives**; Date elements are allowed and normalized to epoch ms. **Array equality** is not supported.
+* Implicit AND is canonicalized (`{a:1,b:2}` → `{$and:[{a:1},{b:2}]}`). Logical operators must contain field conditions, use non-empty arrays, and appear only at the root or within other logical operators (not inside field values).
+* Keys listed in `nonFilterableMetadataKeys` at index creation are stored but not filterable; this setting is immutable.
+* $exists requires a boolean value.
+* undefined/null/empty filters are treated as no filter.
+* Each metadata key name limited to 63 characters.
+* Total metadata per vector: Up to 40 KB (filterable + non-filterable)
+* Total metadata keys per vector: Up to 10
+* Filterable metadata per vector: Up to 2 KB
+* Non-filterable metadata keys per vector index: Up to 10
+
 ## Related
 
 - [Astra](./astra)
@@ -330,3 +344,4 @@ const results = await store.query({
 - [Pinecone](./pinecone)
 - [Qdrant](./qdrant)
 - [Upstash](./upstash)
+- [Amazon S3 Vectors](./s3vectors)

package/.docs/raw/reference/rag/s3vectors.mdx

@@ -0,0 +1,386 @@
+---
+title: "Reference: Amazon S3 Vectors Store | Vector Databases | RAG | Mastra Docs"
+description: Documentation for the S3Vectors class in Mastra, which provides vector search using Amazon S3 Vectors (Preview).
+---
+
+# Amazon S3 Vectors Store
+
+> ⚠️ Amazon S3 Vectors is a Preview service.
+> Preview features may change or be removed without notice and are not covered by AWS SLAs.
+> Behavior, limits, and regional availability can change at any time.
+> This library may introduce breaking changes to stay aligned with AWS.
+
+The `S3Vectors` class provides vector search using [Amazon S3 Vectors (Preview)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors.html). It stores vectors in **vector buckets** and performs similarity search in **vector indexes**, with JSON-based metadata filters.
+
+## Installation
+
+```bash copy
+npm install @mastra/s3vectors
+```
+
+## Usage Example
+
+```typescript copy showLineNumbers
+import { S3Vectors } from "@mastra/s3vectors";
+
+const store = new S3Vectors({
+  vectorBucketName: process.env.S3_VECTORS_BUCKET_NAME!, // e.g. "my-vector-bucket"
+  clientConfig: {
+    region: process.env.AWS_REGION!, // credentials use the default AWS provider chain
+  },
+  // Optional: mark large/long-text fields as non-filterable at index creation time
+  nonFilterableMetadataKeys: ["content"],
+});
+
+// Create an index (names are normalized: "_" → "-" and lowercased)
+await store.createIndex({
+  indexName: "my_index",
+  dimension: 1536,
+  metric: "cosine", // "euclidean" also supported; "dotproduct" is NOT supported
+});
+
+// Upsert vectors (ids auto-generated if omitted). Date values in metadata are serialized to epoch ms.
+const ids = await store.upsert({
+  indexName: "my_index",
+  vectors: [
+    [0.1, 0.2 /* … */],
+    [0.3, 0.4 /* … */],
+  ],
+  metadata: [
+    { text: "doc1", genre: "documentary", year: 2023, createdAt: new Date("2024-01-01") },
+    { text: "doc2", genre: "comedy", year: 2021 },
+  ],
+});
+
+// Query with metadata filters (implicit AND is canonicalized)
+const results = await store.query({
+  indexName: "my-index",
+  queryVector: [0.1, 0.2 /* … */],
+  topK: 10, // Service-side limits may apply (commonly 30)
+  filter: { genre: { $in: ["documentary", "comedy"] }, year: { $gte: 2020 } },
+  includeVector: false, // set true to include raw vectors (may trigger a secondary fetch)
+});
+
+// Clean up resources (closes the underlying HTTP handler)
+await store.disconnect();
+```
+
+## Constructor Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "vectorBucketName",
+      type: "string",
+      description: "Target S3 Vectors vector bucket name.",
+    },
+    {
+      name: "clientConfig",
+      type: "S3VectorsClientConfig",
+      isOptional: true,
+      description: "AWS SDK v3 client options (e.g., `region`, `credentials`).",
+    },
+    {
+      name: "nonFilterableMetadataKeys",
+      type: "string[]",
+      isOptional: true,
+      description: "Metadata keys that should NOT be filterable (applied to the index at creation time). Use this for large text fields like `content`.",
+    },
+  ]}
+/>
+
+## Methods
+
+### createIndex()
+
+Creates a new vector index in the configured vector bucket. If the index already exists, the call validates the schema and becomes a no-op (existing metric and dimension are preserved).
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Logical index name. Normalized internally: underscores are replaced with hyphens and the name is lowercased.",
+    },
+    {
+      name: "dimension",
+      type: "number",
+      description: "Vector dimension (must match your embedding model)",
+    },
+    {
+      name: "metric",
+      type: "'cosine' | 'euclidean'",
+      isOptional: true,
+      defaultValue: "cosine",
+      description: "Distance metric for similarity search. `dotproduct` is not supported by S3 Vectors.",
+    },
+  ]}
+/>
+
+### upsert()
+
+Adds or replaces vectors (full-record put). If `ids` are not provided, UUIDs are generated.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to upsert into",
+    },
+    {
+      name: "vectors",
+      type: "number[][]",
+      description: "Array of embedding vectors",
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>[]",
+      isOptional: true,
+      description: "Metadata for each vector",
+    },
+    {
+      name: "ids",
+      type: "string[]",
+      isOptional: true,
+      description: "Optional vector IDs (auto-generated if not provided)",
+    },
+  ]}
+/>
+
+### query()
+
+Searches for nearest neighbors with optional metadata filtering.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to query",
+    },
+    {
+      name: "queryVector",
+      type: "number[]",
+      description: "Query vector to find similar vectors",
+    },
+    {
+      name: "topK",
+      type: "number",
+      isOptional: true,
+      defaultValue: "10",
+      description: "Number of results to return",
+    },
+    {
+      name: "filter",
+      type: "S3VectorsFilter",
+      isOptional: true,
+      description: "JSON-based metadata filter supporting `$and`, `$or`, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`.",
+    },
+    {
+      name: "includeVector",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "Whether to include vectors in the results",
+    },
+  ]}
+/>
+
+
+> **Scoring:** Results include `score = 1/(1 + distance)` so that higher is better while preserving the underlying distance ranking.
+
+### describeIndex()
+
+Returns information about the index.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Index name to describe.",
+    },
+  ]}
+/>
+
+Returns:
+
+```typescript copy
+interface IndexStats {
+  dimension: number;
+  count: number; // computed via ListVectors pagination (O(n))
+  metric: "cosine" | "euclidean";
+}
+```
+
+### deleteIndex()
+
+Deletes an index and its data.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Index to delete.",
+    },
+  ]}
+/>
+
+### listIndexes()
+
+Lists all indexes in the configured vector bucket.
+
+Returns: `Promise<string[]>`
+
+### updateVector()
+
+Updates a vector or metadata for a specific ID within an index.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Index containing the vector.",
+    },
+    {
+      name: "id",
+      type: "string",
+      description: "ID to update.",
+    },
+    {
+      name: "update",
+      type: "object",
+      description: "Update data containing vector and/or metadata",
+    },
+    {
+      name: "update.vector",
+      type: "number[]",
+      isOptional: true,
+      description: "New vector data to update",
+    },
+    {
+      name: "update.metadata",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "New metadata to update",
+    },
+  ]}
+/>
+
+### deleteVector()
+
+Deletes a specific vector by ID.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Index containing the vector.",
+    },
+    {
+      name: "id",
+      type: "string",
+      description: "ID to delete.",
+    },
+  ]}
+/>
+
+### disconnect()
+
+Closes the underlying AWS SDK HTTP handler to free sockets.
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript copy
+interface QueryResult {
+  id: string;
+  score: number; // 1/(1 + distance)
+  metadata: Record<string, any>;
+  vector?: number[]; // Only included if includeVector is true
+}
+```
+
+## Filter Syntax
+
+S3 Vectors supports a strict subset of operators and value types. The Mastra filter translator:
+
+* **Canonicalizes implicit AND**: `{a:1,b:2}` → `{ $and: [{a:1},{b:2}] }`.
+* **Normalizes Date values** to epoch ms for numeric comparisons and array elements.
+* **Disallows Date** in equality positions (`field: value` or `$eq/$ne`); equality values must be **string | number | boolean**.
+* **Rejects** null/undefined for equality; **array equality** is not supported (use `$in`/`$nin`).
+* Only **`$and` / `$or`** are allowed as top-level logical operators.
+* Logical operators must contain **field conditions** (not direct operators).
+
+**Supported operators:**
+
+* **Logical:** `$and`, `$or` (non-empty arrays)
+* **Basic:** `$eq`, `$ne` (string | number | boolean)
+* **Numeric:** `$gt`, `$gte`, `$lt`, `$lte` (number or `Date` → epoch ms)
+* **Array:** `$in`, `$nin` (non-empty arrays of string | number | boolean; `Date` → epoch ms)
+* **Element:** `$exists` (boolean)
+
+**Unsupported / disallowed (rejected):** `$not`, `$nor`, `$regex`, `$all`, `$elemMatch`, `$size`, `$text`, etc.
+
+**Examples:**
+
+```typescript copy
+// Implicit AND
+{ genre: { $in: ["documentary", "comedy"] }, year: { $gte: 2020 } }
+
+// Explicit logicals and ranges
+{
+  $and: [
+    { price: { $gte: 100, $lte: 1000 } },
+    { $or: [{ stock: { $gt: 0 } }, { preorder: true }] }
+  ]
+}
+
+// Dates in range (converted to epoch ms)
+{ timestamp: { $gt: new Date("2024-01-01T00:00:00Z") } }
+```
+
+> **Non-filterable keys:** If you set `nonFilterableMetadataKeys` at index creation, those keys are stored but **cannot** be used in filters.
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript copy
+try {
+  await store.query({
+    indexName: "index-name",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  if (error instanceof VectorStoreError) {
+    console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc
+    console.log(error.details); // Additional error context
+  }
+}
+```
+
+## Environment Variables
+
+Typical environment variables when wiring your app:
+
+* `S3_VECTORS_BUCKET_NAME`: Your S3 **vector bucket** name (used to populate `vectorBucketName`).
+* `AWS_REGION`: AWS region for the S3 Vectors bucket.
+* **AWS credentials**: via the standard AWS SDK provider chain (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_PROFILE`, etc.).
+
+## Best Practices
+
+* Choose the metric (`cosine` or `euclidean`) to match your embedding model; `dotproduct` is not supported.
+* Keep **filterable** metadata small and structured (string/number/boolean). Store large text (e.g., `content`) as **non-filterable**.
+* Use **dotted paths** for nested metadata and explicit `$and`/`$or` for complex logic.
+* Avoid calling `describeIndex()` on hot paths—`count` is computed with paginated `ListVectors` (**O(n)**).
+* Use `includeVector: true` only when you need raw vectors.
+
+## Related
+
+* [Metadata Filters](./metadata-filters)

package/.docs/raw/reference/tools/mcp-server.mdx

@@ -18,7 +18,8 @@ To create a new `MCPServer`, you need to provide some basic information about yo
 ```typescript
 import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
-import { MCPServer, createMCPTool } from "@mastra/mcp";
+import { createTool } from "@mastra/core/tools";
+import { MCPServer } from "@mastra/mcp";
 import { z } from "zod";
 import { dataProcessingWorkflow } from "../workflows/dataProcessingWorkflow";
 
@@ -29,7 +30,7 @@ const myAgent = new Agent({
   model: openai("gpt-4o-mini"),
 });
 
-const weatherTool = createMCPTool({
+const weatherTool = createTool({
   id: "getWeather",
   description: "Gets the current weather for a location.",
   inputSchema: z.object({ location: z.string() }),
@@ -68,10 +69,10 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
     },
     {
       name: "tools",
-      type: "MCPToolsInput",
+      type: "ToolsInput",
       isOptional: false,
       description:
-        "An object where keys are tool names and values are tool definitions. Supports Mastra tools (created with `createMCPTool` or `createTool`) or Vercel AI SDK tools. Tools created with `createMCPTool` have access to MCP-specific features like elicitation for user interaction.",
+        "An object where keys are tool names and values are Mastra tool definitions (created with `createTool` or Vercel AI SDK). These tools will be directly exposed.",
     },
     {
       name: "agents",
@@ -845,18 +846,17 @@ The `MCPServer` class automatically includes elicitation capabilities. Tools rec
 When tools are executed within an MCP server context, they receive an additional `options` parameter:
 
 ```typescript
-execute: async (params, { elicitation, extra }) => {
-  // params contains the validated tool input parameters
-  // elicitation provides user interaction capabilities
-  // extra contains MCP-specific context (auth, session, etc.)
+execute: async ({ context }, options) => {
+  // context contains the tool's input parameters
+  // options contains server capabilities like elicitation and authentication info
   
   // Access authentication information (when available)
-  if (extra?.authInfo) {
-    console.log('Authenticated request from:', extra.authInfo.clientId);
+  if (options.extra?.authInfo) {
+    console.log('Authenticated request from:', options.extra.authInfo.clientId);
   }
   
   // Use elicitation capabilities
-  const result = await elicitation.sendRequest({
+  const result = await options.elicitation.sendRequest({
     message: "Please provide information",
     requestedSchema: { /* schema */ }
   });
@@ -881,28 +881,29 @@ A common use case is during tool execution. When a tool needs user input, it can
 Here's an example of a tool that uses elicitation to collect user contact information:
 
 ```typescript
-import { MCPServer, createMCPTool } from "@mastra/mcp";
+import { MCPServer } from "@mastra/mcp";
+import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 
 const server = new MCPServer({
   name: "Interactive Server",
   version: "1.0.0",
   tools: {
-    collectContactInfo: createMCPTool({
+    collectContactInfo: createTool({
       id: "collectContactInfo",
       description: "Collects user contact information through elicitation",
       inputSchema: z.object({
         reason: z.string().optional().describe("Reason for collecting contact info"),
       }),
-      execute: async (params, { context, elicitation, extra }) => {
-        const { reason } = params;
+      execute: async ({ context }, options) => {
+        const { reason } = context;
         
         // Log session info if available
-        console.log('Request from session:', extra?.sessionId);
+        console.log('Request from session:', options.extra?.sessionId);
 
         try {
           // Request user input via elicitation
-          const result = await elicitation.sendRequest({
+          const result = await options.elicitation.sendRequest({
             message: reason 
               ? `Please provide your contact information. ${reason}`
               : 'Please provide your contact information',
@@ -1009,17 +1010,17 @@ Tools should handle all three response types appropriately.
 The elicitation functionality is available through the `options` parameter in tool execution:
 
 ```typescript
-// Within a tool's execute function (using createMCPTool)
-execute: async (params, { elicitation, extra }) => {
+// Within a tool's execute function
+execute: async ({ context }, options) => {
   // Use elicitation for user input
-  const result = await elicitation.sendRequest({
+  const result = await options.elicitation.sendRequest({
     message: string,           // Message to display to user
     requestedSchema: object    // JSON schema defining expected response structure
   }): Promise<ElicitResult>
   
   // Access authentication info if needed
-  if (extra?.authInfo) {
-    // Use extra.authInfo.token, etc.
+  if (options.extra?.authInfo) {
+    // Use options.extra.authInfo.token, etc.
   }
 }
 ```
@@ -1040,15 +1041,15 @@ type ElicitResult = {
 Tools can access request metadata via `options.extra` when using HTTP-based transports:
 
 ```typescript
-execute: async (params, { elicitation, extra }) => {
-  if (!extra?.authInfo?.token) {
+execute: async ({ context }, options) => {
+  if (!options.extra?.authInfo?.token) {
     return "Authentication required";
   }
   
   // Use the auth token
   const response = await fetch('/api/data', {
-    headers: { Authorization: `Bearer ${extra.authInfo.token}` },
-    signal: extra.signal,
+    headers: { Authorization: `Bearer ${options.extra.authInfo.token}` },
+    signal: options.extra.signal,
   });
   
   return response.json();