@mastra/mcp-docs-server 0.0.0-default-storage-virtual-file-20250410035748

package/.docs/raw/rag/vector-databases.mdx

@@ -0,0 +1,340 @@
+---
+title: "Storing Embeddings in A Vector Database | Mastra Docs"
+description: Guide on vector storage options in Mastra, including embedded and dedicated vector databases for similarity search.
+---
+
+import { Tabs } from "nextra/components";
+
+## Storing Embeddings in A Vector Database
+
+After generating embeddings, you need to store them in a database that supports vector similarity search. Mastra provides a consistent interface for storing and querying embeddings across different vector databases.
+
+## Supported Databases
+
+<Tabs items={['Pg Vector', 'Pinecone', 'Qdrant', 'Chroma', 'Astra', 'LibSQL', 'Upstash', 'Cloudflare']}>
+  <Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+  import { PgVector } from '@mastra/pg';
+
+  const store = new PgVector(process.env.POSTGRES_CONNECTION_STRING)
+  await store.createIndex({
+    indexName: "myCollection",
+    dimension: 1536,
+  });
+  await store.upsert({
+    indexName: "myCollection",
+    vectors: embeddings,
+    metadata: chunks.map(chunk => ({ text: chunk.text })),
+  });
+
+  ```
+
+  ### Using PostgreSQL with pgvector
+
+  PostgreSQL with the pgvector extension is a good solution for teams already using PostgreSQL who want to minimize infrastructure complexity. 
+  For detailed setup instructions and best practices, see the [official pgvector repository](https://github.com/pgvector/pgvector).
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+  import { PineconeVector } from '@mastra/pinecone'
+
+  const store = new PineconeVector(process.env.PINECONE_API_KEY)
+  await store.createIndex({
+    indexName: "myCollection",
+    dimension: 1536,
+  });
+  await store.upsert({
+    indexName: "myCollection",
+    vectors: embeddings,
+    metadata: chunks.map(chunk => ({ text: chunk.text })),
+  });
+  ```
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+  import { QdrantVector } from '@mastra/qdrant'
+
+  const store = new QdrantVector({
+    url: process.env.QDRANT_URL,
+    apiKey: process.env.QDRANT_API_KEY
+  })
+  await store.createIndex({
+    indexName: "myCollection",
+    dimension: 1536,
+  });
+  await store.upsert({
+    indexName: "myCollection",
+    vectors: embeddings,
+    metadata: chunks.map(chunk => ({ text: chunk.text })),
+  });
+  ```
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+  import { ChromaVector } from '@mastra/chroma'
+
+  const store = new ChromaVector()
+  await store.createIndex({
+    indexName: "myCollection",
+    dimension: 1536,
+  });
+  await store.upsert({
+    indexName: "myCollection",
+    vectors: embeddings,
+    metadata: chunks.map(chunk => ({ text: chunk.text })),
+  });
+  ```
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+  import { AstraVector } from '@mastra/astra'
+
+  const store = new AstraVector({
+    token: process.env.ASTRA_DB_TOKEN,
+    endpoint: process.env.ASTRA_DB_ENDPOINT,
+    keyspace: process.env.ASTRA_DB_KEYSPACE
+  })
+  await store.createIndex({
+    indexName: "myCollection",
+    dimension: 1536,
+  });
+  await store.upsert({
+    indexName: "myCollection",
+    vectors: embeddings,
+    metadata: chunks.map(chunk => ({ text: chunk.text })),
+  });
+  ```
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+import { LibSQLVector } from "@mastra/core/vector/libsql";
+
+  const store = new LibSQLVector({
+    connectionUrl: process.env.DATABASE_URL,
+    authToken: process.env.DATABASE_AUTH_TOKEN // Optional: for Turso cloud databases
+  })
+  await store.createIndex({
+    indexName: "myCollection",
+    dimension: 1536,
+  });
+  await store.upsert({
+    indexName: "myCollection",
+    vectors: embeddings,
+    metadata: chunks.map(chunk => ({ text: chunk.text })),
+  });
+  ```
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+  import { UpstashVector } from '@mastra/upstash'
+
+  const store = new UpstashVector({
+    url: process.env.UPSTASH_URL,
+    token: process.env.UPSTASH_TOKEN
+  })
+  await store.createIndex({
+    indexName: "myCollection",
+    dimension: 1536,
+  });
+  await store.upsert({
+    indexName: "myCollection",
+    vectors: embeddings,
+    metadata: chunks.map(chunk => ({ text: chunk.text })),
+  });
+  ```
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+  import { CloudflareVector } from '@mastra/vectorize'
+
+  const store = new CloudflareVector({
+    accountId: process.env.CF_ACCOUNT_ID,
+    apiToken: process.env.CF_API_TOKEN
+  })
+  await store.createIndex({
+    indexName: "myCollection",
+    dimension: 1536,
+  });
+  await store.upsert({
+    indexName: "myCollection",
+    vectors: embeddings,
+    metadata: chunks.map(chunk => ({ text: chunk.text })),
+  });
+  ```
+</Tabs.Tab>
+</Tabs>
+
+## Using Vector Storage
+
+Once initialized, all vector stores share the same interface for creating indexes, upserting embeddings, and querying.
+
+### Creating Indexes
+
+Before storing embeddings, you need to create an index with the appropriate dimension size for your embedding model:
+
+```ts filename="store-embeddings.ts" showLineNumbers copy
+// Create an index with dimension 1536 (for text-embedding-3-small)
+await store.createIndex({
+  indexName: 'myCollection',
+  dimension: 1536,
+});
+
+// For other models, use their corresponding dimensions:
+// - text-embedding-3-large: 3072
+// - text-embedding-ada-002: 1536
+// - cohere-embed-multilingual-v3: 1024
+```
+
+The dimension size must match the output dimension of your chosen embedding model. Common dimension sizes are:
+- OpenAI text-embedding-3-small: 1536 dimensions
+- OpenAI text-embedding-3-large: 3072 dimensions
+- Cohere embed-multilingual-v3: 1024 dimensions
+
+> **Important**: Index dimensions cannot be changed after creation. To use a different model, delete and recreate the index with the new dimension size.
+
+### Naming Rules for Databases
+
+Each vector database enforces specific naming conventions for indexes and collections to ensure compatibility and prevent conflicts.
+
+<Tabs items={['Pg Vector', 'Pinecone', 'Qdrant', 'Chroma', 'Astra', 'LibSQL', 'Upstash', 'Cloudflare']}>
+  <Tabs.Tab>
+    Index names must:
+    - Start with a letter or underscore
+    - Contain only letters, numbers, and underscores
+    - Example: `my_index_123` is valid
+    - Example: `my-index` is not valid (contains hyphen)
+  </Tabs.Tab>
+  <Tabs.Tab>
+    Index names must:
+    - Use only lowercase letters, numbers, and dashes
+    - Not contain dots (used for DNS routing)
+    - Not use non-Latin characters or emojis
+    - Have a combined length (with project ID) under 52 characters
+      - Example: `my-index-123` is valid
+      - Example: `my.index` is not valid (contains dot)
+  </Tabs.Tab>
+  <Tabs.Tab>
+    Collection names must:
+    - Be 1-255 characters long
+    - Not contain any of these special characters:
+      - `< > : " / \ | ? *`
+      - Null character (`\0`)
+      - Unit separator (`\u{1F}`)
+    - Example: `my_collection_123` is valid
+    - Example: `my/collection` is not valid (contains slash)
+  </Tabs.Tab>
+  <Tabs.Tab>
+    Collection names must:
+    - Be 3-63 characters long
+    - Start and end with a letter or number
+    - Contain only letters, numbers, underscores, or hyphens
+    - Not contain consecutive periods (..)
+    - Not be a valid IPv4 address
+    - Example: `my-collection-123` is valid
+    - Example: `my..collection` is not valid (consecutive periods)
+  </Tabs.Tab>
+  <Tabs.Tab>
+    Collection names must:
+    - Not be empty
+    - Be 48 characters or less
+    - Contain only letters, numbers, and underscores
+    - Example: `my_collection_123` is valid
+    - Example: `my-collection` is not valid (contains hyphen)
+  </Tabs.Tab>
+  <Tabs.Tab>
+    Index names must:
+    - Start with a letter or underscore
+    - Contain only letters, numbers, and underscores
+    - Example: `my_index_123` is valid
+    - Example: `my-index` is not valid (contains hyphen)
+  </Tabs.Tab>
+  <Tabs.Tab>
+    Namespace names must:
+    - Be 2-100 characters long
+    - Contain only:
+      - Alphanumeric characters (a-z, A-Z, 0-9)
+      - Underscores, hyphens, dots
+    - Not start or end with special characters (_, -, .)
+    - Can be case-sensitive
+    - Example: `MyNamespace123` is valid
+    - Example: `_namespace` is not valid (starts with underscore)
+  </Tabs.Tab>
+  <Tabs.Tab>
+    Index names must:
+    - Start with a letter
+    - Be shorter than 32 characters
+    - Contain only lowercase ASCII letters, numbers, and dashes
+    - Use dashes instead of spaces
+    - Example: `my-index-123` is valid
+    - Example: `My_Index` is not valid (uppercase and underscore)
+  </Tabs.Tab>
+</Tabs>
+
+### Upserting Embeddings
+
+After creating an index, you can store embeddings along with their basic metadata:
+
+```ts filename="store-embeddings.ts" showLineNumbers copy
+// Store embeddings with their corresponding metadata
+await store.upsert({
+  indexName: 'myCollection',  // index name
+  vectors: embeddings,       // array of embedding vectors
+  metadata: chunks.map(chunk => ({
+    text: chunk.text,  // The original text content
+    id: chunk.id       // Optional unique identifier
+  }))
+});
+```
+
+The upsert operation:
+- Takes an array of embedding vectors and their corresponding metadata
+- Updates existing vectors if they share the same ID
+- Creates new vectors if they don't exist
+- Automatically handles batching for large datasets
+
+For complete examples of upserting embeddings in different vector stores, see the [Upsert Embeddings](../../examples/rag/upsert/upsert-embeddings.mdx) guide.
+
+## Adding Metadata
+
+Vector stores support rich metadata (any JSON-serializable fields) for filtering and organization. Since metadata is stored with no fixed schema, use consistent field naming to avoid unexpected query results.
+
+**Important**: Metadata is crucial for vector storage - without it, you'd only have numerical embeddings with no way to return the original text or filter results. Always store at least the source text as metadata.
+
+```ts showLineNumbers copy
+// Store embeddings with rich metadata for better organization and filtering
+await store.upsert({
+  indexName: "myCollection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({
+    // Basic content
+    text: chunk.text,
+    id: chunk.id,
+    
+    // Document organization
+    source: chunk.source,
+    category: chunk.category,
+    
+    // Temporal metadata
+    createdAt: new Date().toISOString(),
+    version: "1.0",
+    
+    // Custom fields
+    language: chunk.language,
+    author: chunk.author,
+    confidenceScore: chunk.score,
+  })),
+});
+```
+
+Key metadata considerations:
+- Be strict with field naming - inconsistencies like 'category' vs 'Category' will affect queries
+- Only include fields you plan to filter or sort by - extra fields add overhead
+- Add timestamps (e.g., 'createdAt', 'lastUpdated') to track content freshness
+
+## Best Practices
+
+- Create indexes before bulk insertions
+- Use batch operations for large insertions (the upsert method handles batching automatically)
+- Only store metadata you'll query against
+- Match embedding dimensions to your model (e.g., 1536 for `text-embedding-3-small`)
+

package/.docs/raw/reference/agents/createTool.mdx

@@ -0,0 +1,229 @@
+---
+title: "Reference: createTool() | Tools | Agents | Mastra Docs"
+description: Documentation for the createTool function in Mastra, which creates custom tools for agents and workflows.
+---
+
+# `createTool()`
+
+The `createTool()` function creates typed tools that can be executed by agents or workflows. Tools have built-in schema validation, execution context, and integration with the Mastra ecosystem.
+
+## Overview
+
+Tools are a fundamental building block in Mastra that allow agents to interact with external systems, perform computations, and access data. Each tool has:
+
+- A unique identifier
+- A description that helps the AI understand when and how to use the tool
+- Optional input and output schemas for validation
+- An execution function that implements the tool's logic
+
+## Example Usage
+
+```ts filename="src/tools/stock-tools.ts" showLineNumbers copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+// Helper function to fetch stock data
+const getStockPrice = async (symbol: string) => {
+  const response = await fetch(
+    `https://mastra-stock-data.vercel.app/api/stock-data?symbol=${symbol}`
+  );
+  const data = await response.json();
+  return data.prices["4. close"];
+};
+
+// Create a tool to get stock prices
+export const stockPriceTool = createTool({
+  id: "getStockPrice",
+  description: "Fetches the current stock price for a given ticker symbol",
+  inputSchema: z.object({
+    symbol: z.string().describe("The stock ticker symbol (e.g., AAPL, MSFT)")
+  }),
+  outputSchema: z.object({
+    symbol: z.string(),
+    price: z.number(),
+    currency: z.string(),
+    timestamp: z.string()
+  }),
+  execute: async ({ context }) => {
+    const price = await getStockPrice(context.symbol);
+    
+    return {
+      symbol: context.symbol,
+      price: parseFloat(price),
+      currency: "USD",
+      timestamp: new Date().toISOString()
+    };
+  }
+});
+
+// Create a tool that uses the thread context
+export const threadInfoTool = createTool({
+  id: "getThreadInfo",
+  description: "Returns information about the current conversation thread",
+  inputSchema: z.object({
+    includeResource: z.boolean().optional().default(false)
+  }),
+  execute: async ({ context, threadId, resourceId }) => {
+    return {
+      threadId,
+      resourceId: context.includeResource ? resourceId : undefined,
+      timestamp: new Date().toISOString()
+    };
+  }
+});
+```
+
+## API Reference
+
+### Parameters
+
+`createTool()` accepts a single object with the following properties:
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      required: true,
+      description: "Unique identifier for the tool. This should be descriptive of the tool's function."
+    },
+    {
+      name: "description",
+      type: "string",
+      required: true,
+      description: "Detailed description of what the tool does, when it should be used, and what inputs it requires. This helps the AI understand how to use the tool effectively."
+    },
+    {
+      name: "execute",
+      type: "(context: ToolExecutionContext, options?: any) => Promise<any>",
+      required: false,
+      description: "Async function that implements the tool's logic. Receives the execution context and optional configuration.",
+      properties: [
+        {
+          type: "ToolExecutionContext",
+          parameters: [
+            {
+              name: "context",
+              type: "object",
+              description: "The validated input data that matches the inputSchema"
+            },
+            {
+              name: "threadId",
+              type: "string",
+              isOptional: true,
+              description: "Identifier for the conversation thread, if available"
+            },
+            {
+              name: "resourceId",
+              type: "string",
+              isOptional: true,
+              description: "Identifier for the user or resource interacting with the tool"
+            },
+            {
+              name: "mastra",
+              type: "Mastra",
+              isOptional: true,
+              description: "Reference to the Mastra instance, if available"
+            },
+          ]
+        },
+        {
+          type: "ToolOptions",
+          parameters: [
+            {
+              name: "toolCallId",
+              type: "string",
+              description: "The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data."
+            },
+            {
+              name: "messages",
+              type: "CoreMessage[]",
+              description: "Messages that were sent to the language model to initiate the response that contained the tool call. The messages do not include the system prompt nor the assistant response that contained the tool call."
+            },
+            {
+              name: "abortSignal",
+              type: "AbortSignal",
+              isOptional: true,
+              description: "An optional abort signal that indicates that the overall operation should be aborted."
+            },
+          ]
+        }
+      ]
+    },
+    {
+      name: "inputSchema",
+      type: "ZodSchema",
+      required: false,
+      description: "Zod schema that defines and validates the tool's input parameters. If not provided, the tool will accept any input."
+    },
+    {
+      name: "outputSchema",
+      type: "ZodSchema",
+      required: false,
+      description: "Zod schema that defines and validates the tool's output. Helps ensure the tool returns data in the expected format."
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "Tool",
+      type: "Tool<TSchemaIn, TSchemaOut>",
+      description: "A Tool instance that can be used with agents, workflows, or directly executed.",
+      properties: [
+        {
+          type: "Tool",
+          parameters: [
+            {
+              name: "id",
+              type: "string",
+              description: "The tool's unique identifier"
+            },
+            {
+              name: "description",
+              type: "string",
+              description: "Description of the tool's functionality"
+            },
+            {
+              name: "inputSchema",
+              type: "ZodSchema | undefined",
+              description: "Schema for validating inputs"
+            },
+            {
+              name: "outputSchema",
+              type: "ZodSchema | undefined",
+              description: "Schema for validating outputs"
+            },
+            {
+              name: "execute",
+              type: "Function",
+              description: "The tool's execution function"
+            }
+          ]
+        }
+      ]
+    }
+  ]}
+/>
+
+## Type Safety
+
+The `createTool()` function provides full type safety through TypeScript generics:
+
+- Input types are inferred from the `inputSchema`
+- Output types are inferred from the `outputSchema`
+- The execution context is properly typed based on the input schema
+
+This ensures that your tools are type-safe throughout your application.
+
+## Best Practices
+
+1. **Descriptive IDs**: Use clear, action-oriented IDs like `getWeatherForecast` or `searchDatabase`
+2. **Detailed Descriptions**: Provide comprehensive descriptions that explain when and how to use the tool
+3. **Input Validation**: Use Zod schemas to validate inputs and provide helpful error messages
+4. **Error Handling**: Implement proper error handling in your execute function
+5. **Idempotency**: When possible, make your tools idempotent (same input always produces same output)
+6. **Performance**: Keep tools lightweight and fast to execute