@mastra/mcp-docs-server 0.0.3 → 0.0.4-alpha.1

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

@@ -9,11 +9,7 @@ import { Tabs } from "nextra/components";
 
 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
-
-### PostgreSQL with PgVector
-
-Best for teams already using PostgreSQL who want to minimize infrastructure complexity:
+## Supported Databases
 
 <Tabs items={['Pg Vector', 'Pinecone', 'Qdrant', 'Chroma', 'Astra', 'LibSQL', 'Upstash', 'Cloudflare']}>
   <Tabs.Tab>
@@ -22,17 +18,21 @@ Best for teams already using PostgreSQL who want to minimize infrastructure comp
 
   const store = new PgVector(process.env.POSTGRES_CONNECTION_STRING)
   await store.createIndex({
-    indexName: "my-collection",
+    indexName: "myCollection",
     dimension: 1536,
   });
   await store.upsert({
-    indexName: "my-collection",
+    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
@@ -40,11 +40,11 @@ Best for teams already using PostgreSQL who want to minimize infrastructure comp
 
   const store = new PineconeVector(process.env.PINECONE_API_KEY)
   await store.createIndex({
-    indexName: "my-collection",
+    indexName: "myCollection",
     dimension: 1536,
   });
   await store.upsert({
-    indexName: "my-collection",
+    indexName: "myCollection",
     vectors: embeddings,
     metadata: chunks.map(chunk => ({ text: chunk.text })),
   });
@@ -59,11 +59,11 @@ Best for teams already using PostgreSQL who want to minimize infrastructure comp
     apiKey: process.env.QDRANT_API_KEY
   })
   await store.createIndex({
-    indexName: "my-collection",
+    indexName: "myCollection",
     dimension: 1536,
   });
   await store.upsert({
-    indexName: "my-collection",
+    indexName: "myCollection",
     vectors: embeddings,
     metadata: chunks.map(chunk => ({ text: chunk.text })),
   });
@@ -75,11 +75,11 @@ Best for teams already using PostgreSQL who want to minimize infrastructure comp
 
   const store = new ChromaVector()
   await store.createIndex({
-    indexName: "my-collection",
+    indexName: "myCollection",
     dimension: 1536,
   });
   await store.upsert({
-    indexName: "my-collection",
+    indexName: "myCollection",
     vectors: embeddings,
     metadata: chunks.map(chunk => ({ text: chunk.text })),
   });
@@ -95,11 +95,11 @@ Best for teams already using PostgreSQL who want to minimize infrastructure comp
     keyspace: process.env.ASTRA_DB_KEYSPACE
   })
   await store.createIndex({
-    indexName: "my-collection",
+    indexName: "myCollection",
     dimension: 1536,
   });
   await store.upsert({
-    indexName: "my-collection",
+    indexName: "myCollection",
     vectors: embeddings,
     metadata: chunks.map(chunk => ({ text: chunk.text })),
   });
@@ -114,11 +114,11 @@ import { LibSQLVector } from "@mastra/core/vector/libsql";
     authToken: process.env.DATABASE_AUTH_TOKEN // Optional: for Turso cloud databases
   })
   await store.createIndex({
-    indexName: "my-collection",
+    indexName: "myCollection",
     dimension: 1536,
   });
   await store.upsert({
-    indexName: "my-collection",
+    indexName: "myCollection",
     vectors: embeddings,
     metadata: chunks.map(chunk => ({ text: chunk.text })),
   });
@@ -133,11 +133,11 @@ import { LibSQLVector } from "@mastra/core/vector/libsql";
     token: process.env.UPSTASH_TOKEN
   })
   await store.createIndex({
-    indexName: "my-collection",
+    indexName: "myCollection",
     dimension: 1536,
   });
   await store.upsert({
-    indexName: "my-collection",
+    indexName: "myCollection",
     vectors: embeddings,
     metadata: chunks.map(chunk => ({ text: chunk.text })),
   });
@@ -152,11 +152,11 @@ import { LibSQLVector } from "@mastra/core/vector/libsql";
     apiToken: process.env.CF_API_TOKEN
   })
   await store.createIndex({
-    indexName: "my-collection",
+    indexName: "myCollection",
     dimension: 1536,
   });
   await store.upsert({
-    indexName: "my-collection",
+    indexName: "myCollection",
     vectors: embeddings,
     metadata: chunks.map(chunk => ({ text: chunk.text })),
   });
@@ -175,7 +175,7 @@ Before storing embeddings, you need to create an index with the appropriate dime
 ```ts filename="store-embeddings.ts" showLineNumbers copy
 // Create an index with dimension 1536 (for text-embedding-3-small)
 await store.createIndex({
-  indexName: 'my-collection',
+  indexName: 'myCollection',
   dimension: 1536,
 });
 
@@ -190,6 +190,84 @@ The dimension size must match the output dimension of your chosen embedding mode
 - OpenAI text-embedding-3-large: 3072 dimensions
 - Cohere embed-multilingual-v3: 1024 dimensions
 
+### 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:
@@ -197,7 +275,7 @@ After creating an index, you can store embeddings along with their basic metadat
 ```ts filename="store-embeddings.ts" showLineNumbers copy
 // Store embeddings with their corresponding metadata
 await store.upsert({
-  indexName: 'my-collection',  // index name
+  indexName: 'myCollection',  // index name
   vectors: embeddings,       // array of embedding vectors
   metadata: chunks.map(chunk => ({
     text: chunk.text,  // The original text content
@@ -212,16 +290,18 @@ The upsert operation:
 - 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 for advanced filtering and organization. You can add any JSON-serializable fields that will help with retrieval.
+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.
 
-**Reminder:** Metadata is stored as a JSON field with no fixed schema, so you'll want to name your fields consistently and apply a consistent schema, or your queries will return unexpected 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 vectorStore.upsert({
-  indexName: "embeddings",
+await store.upsert({
+  indexName: "myCollection",
   vectors: embeddings,
   metadata: chunks.map((chunk) => ({
     // Basic content
@@ -256,16 +336,3 @@ Key metadata considerations:
 - Only store metadata you'll query against
 - Match embedding dimensions to your model (e.g., 1536 for `text-embedding-3-small`)
 
-## Examples
-
-For complete examples of different vector store implementations, see:
-
-- [Insert Embedding in PgVector](../../examples/rag/insert-embedding-in-pgvector.mdx)
-- [Insert Embedding in Pinecone](../../examples/rag/insert-embedding-in-pinecone.mdx)
-- [Insert Embedding in Qdrant](../../examples/rag/insert-embedding-in-qdrant.mdx)
-- [Insert Embedding in Chroma](../../examples/rag/insert-embedding-in-chroma.mdx)
-- [Insert Embedding in Astra DB](../../examples/rag/insert-embedding-in-astra.mdx)
-- [Insert Embedding in LibSQL](../../examples/rag/insert-embedding-in-libsql.mdx)
-- [Insert Embedding in Upstash](../../examples/rag/insert-embedding-in-upstash.mdx)
-- [Insert Embedding in Cloudflare Vectorize](../../examples/rag/insert-embedding-in-vectorize.mdx)
-- [Basic RAG with Vector Storage](../../examples/rag/basic-rag.mdx)

package/.docs/raw/reference/client-js/memory.mdx

@@ -10,7 +10,8 @@ Retrieve all memory threads for a specific resource:
 
 ```typescript
 const threads = await client.getMemoryThreads({
-  resourceid: "resource-1",
+  resourceId: "resource-1",
+  agentId: "agent-1"
 });
 ```
 
@@ -23,6 +24,7 @@ const thread = await client.createMemoryThread({
   title: "New Conversation",
   metadata: { category: "support" },
   resourceid: "resource-1",
+  agentId: "agent-1"
 });
 ```
 
@@ -31,7 +33,7 @@ const thread = await client.createMemoryThread({
 Get an instance of a specific memory thread:
 
 ```typescript
-const thread = client.getMemoryThread("thread-id");
+const thread = client.getMemoryThread("thread-id", "agent-id");
 ```
 
 ## Thread Methods
@@ -82,6 +84,7 @@ const savedMessages = await client.saveMessageToMemory({
       type: "text",
     },
   ],
+  agentId: "agent-1"
 });
 ```
 
@@ -90,5 +93,5 @@ const savedMessages = await client.saveMessageToMemory({
 Check the status of the memory system:
 
 ```typescript
-const status = await client.getMemoryStatus();
+const status = await client.getMemoryStatus("agent-id");
 ```

package/.docs/raw/reference/client-js/workflows.mdx

@@ -93,6 +93,7 @@ try{
   console.error(e);
 }
 ```
+### Resume Workflow
 
 Resume workflow run and watch workflow step transitions
 

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

@@ -44,3 +44,5 @@ export const mastra = new Mastra({
 ## Dashboard
 
 Access your traces and analytics in the LangSmith dashboard at [smith.langchain.com](https://smith.langchain.com)
+
+> **Note**: Even if you run your workflows, you may not see data appearing in a new project. You will need to sort by Name column to see all projects, select your project, then filter by LLM Calls instead of Root Runs.

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

@@ -30,7 +30,7 @@ const store = new LibSQLVector({
 
 // Create an index
 await store.createIndex({
-  indexName: "my-collection",
+  indexName: "myCollection",
   dimension: 1536,
 });
 
@@ -41,7 +41,7 @@ const metadata = [
   { text: "second document", category: "B" }
 ];
 await store.upsert({
-  indexName: "my-collection",
+  indexName: "myCollection",
   vectors,
   metadata,
 });
@@ -49,7 +49,7 @@ await store.upsert({
 // Query similar vectors
 const queryVector = [0.1, 0.2, ...];
 const results = await store.query({
-  indexName: "my-collection",
+  indexName: "myCollection",
   queryVector,
   topK: 10, // top K results
   filter: { category: "A" } // optional metadata filter

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

@@ -156,6 +156,54 @@ interface IndexStats {
   ]}
 />
 
+### updateIndexById()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to update",
+    },
+    {
+      name: "id",
+      type: "string",
+      description: "ID of the item to update",
+    },
+    {
+      name: "update",
+      type: "object",
+      description: "Update object containing vector and/or metadata",
+    },
+  ]}
+/>
+
+The `update` object can have the following properties:
+
+- `vector` (optional): An array of numbers representing the new vector.
+- `metadata` (optional): A record of key-value pairs for metadata.
+
+Throws an error if neither `vector` nor `metadata` is provided, or if only `metadata` is provided.
+
+### deleteIndexById()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index from which to delete the item",
+    },
+    {
+      name: "id",
+      type: "string",
+      description: "ID of the item to delete",
+    },
+  ]}
+/>
+
+Attempts to delete an item by its ID from the specified index. Logs an error message if the deletion fails.
+
 ## Response Types
 
 Query results are returned in this format:
@@ -195,4 +243,5 @@ Required environment variables:
 - `UPSTASH_VECTOR_TOKEN`: Your Upstash Vector API token
 
 ### Related
-- [Metadata Filters](./metadata-filters) 
+
+- [Metadata Filters](./metadata-filters)

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

@@ -45,7 +45,8 @@ The CloudflareVector class provides vector search using [Cloudflare Vectorize](h
       type: "'cosine' | 'euclidean' | 'dotproduct'",
       isOptional: true,
       defaultValue: "cosine",
-      description: "Distance metric for similarity search (dotproduct maps to dot-product)",
+      description:
+        "Distance metric for similarity search (dotproduct maps to dot-product)",
     },
   ]}
 />
@@ -162,7 +163,7 @@ Creates an index on a metadata field to enable filtering.
   content={[
     {
       name: "indexName",
-      type: "string", 
+      type: "string",
       description: "Name of the index containing the metadata field",
     },
     {
@@ -211,6 +212,49 @@ Lists all metadata field indexes for an index.
   ]}
 />
 
+### updateIndexById()
+
+Updates a vector or metadata for a specific ID within an index.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the ID to update",
+    },
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier of the vector or metadata to update",
+    },
+    {
+      name: "update",
+      type: "{ vector?: number[]; metadata?: Record<string, any>; }",
+      description: "Object containing the vector and/or metadata to update",
+    },
+  ]}
+/>
+
+### deleteIndexById()
+
+Deletes a vector and its associated metadata for a specific ID within an index.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the ID to delete",
+    },
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier of the vector and metadata to delete",
+    },
+  ]}
+/>
+
 ## Response Types
 
 Query results are returned in this format:
@@ -250,4 +294,5 @@ Required environment variables:
 - `CLOUDFLARE_API_TOKEN`: Your Cloudflare API token with Vectorize permissions
 
 ### Related
-- [Metadata Filters](./metadata-filters) 
+
+- [Metadata Filters](./metadata-filters)

package/.docs/raw/reference/tools/client.mdx

@@ -17,11 +17,13 @@ constructor({
     version = '1.0.0',
     server,
     capabilities = {},
+    timeout = 60000,
 }: {
     name: string;
     server: StdioServerParameters | SSEClientParameters;
     capabilities?: ClientCapabilities;
     version?: string;
+    timeout?: number;
 })
 ```
 
@@ -54,6 +56,13 @@ constructor({
       defaultValue: "{}",
       description: "Optional capabilities configuration for the client.",
     },
+    {
+      name: "timeout",
+      type: "number",
+      isOptional: true,
+      defaultValue: 60000,
+      description: "The timeout duration, in milliseconds, for client tool calls.",
+    },
   ]}
 />
 
@@ -175,6 +184,5 @@ const sseClient = new MastraMCPClient({
 
 ## Related Information
 
-- For managing multiple MCP servers in your application, see the [MCPConfiguration documentation](./configuration)
+- For managing multiple MCP servers in your application, see the [MCPConfiguration documentation](./mcp-configuration)
 - For more details about the Model Context Protocol, see the [@modelcontextprotocol/sdk documentation](https://github.com/modelcontextprotocol/typescript-sdk).
-

package/.docs/raw/reference/tools/vector-query-tool.mdx

@@ -155,7 +155,7 @@ This agent-driven approach:
 
 For detailed filter syntax and store-specific capabilities, see the [Metadata Filters](../rag/metadata-filters) documentation.
 
-For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](../../../examples/rag/filter-rag) example.
+For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](../../../examples/rag/usage/filter-rag) example.
 
 ## Example with Reranking