npm - @mastra/mcp-docs-server - Versions diffs - 1.0.0-beta.9 → 1.0.0 - Mend

@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (541) hide show

package/.docs/raw/observability/tracing/processors/sensitive-data-filter.mdx CHANGED Viewed

@@ -1,20 +1,40 @@
 ---
 title: "Sensitive Data Filter | Processors | Observability"
 description: "Protect sensitive information in your traces with automatic data redaction"
+packages:
+  - "@mastra/observability"
 ---
 # Sensitive Data Filter
-The Sensitive Data Filter is a span processor that automatically redacts sensitive information from your traces before they're exported. This ensures that passwords, API keys, tokens, and other confidential data never leave your application or get stored in observability platforms.
+The Sensitive Data Filter is a span processor that redacts sensitive information from your traces during the processing pipeline before export. This ensures that passwords, API keys, tokens, and other confidential data never leave your application or get stored in observability platforms.
 ## Default Configuration
-By default, the Sensitive Data Filter is automatically enabled when you use the standard Mastra configuration:
+The Sensitive Data Filter is included in the recommended observability configuration:
+```ts title="src/mastra/index.ts"
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from "@mastra/observability";
-```ts title="src/mastra/index.ts" showLineNumbers copy
 export const mastra = new Mastra({
   observability: new Observability({
-    default: { enabled: true }, // Automatically includes SensitiveDataFilter
+    configs: {
+      default: {
+        serviceName: "mastra",
+        exporters: [
+          new DefaultExporter(),
+          new CloudExporter(),
+        ],
+        spanOutputProcessors: [
+          new SensitiveDataFilter(), // Redacts sensitive fields before export
+        ],
+      },
+    },
   }),
   storage: new LibSQLStore({
     id: 'mastra-storage',
@@ -23,7 +43,7 @@ export const mastra = new Mastra({
 });
 ```
-With the default configuration, the filter automatically redacts these common sensitive field names:
+With the default configuration, the filter redacts these common sensitive field names:
 - `password`
 - `token`
@@ -63,7 +83,7 @@ When a sensitive field is detected, its value is replaced with `[REDACTED]` by d
 You can customize which fields are redacted and how redaction appears:
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 import { SensitiveDataFilter, DefaultExporter, Observability } from "@mastra/observability";
 export const mastra = new Mastra({
@@ -210,7 +230,7 @@ The Sensitive Data Filter is designed to be lightweight and efficient:
 If you need to disable sensitive data filtering (not recommended for production):
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 export const mastra = new Mastra({
   observability: new Observability({
     configs: {

package/.docs/raw/rag/chunking-and-embedding.mdx CHANGED Viewed

@@ -1,13 +1,16 @@
 ---
-title: Chunking and Embedding Documents | RAG | Mastra Docs
+title: Chunking and Embedding Documents | RAG
 description: Guide on chunking and embedding documents in Mastra for efficient processing and retrieval.
+packages:
+  - "@mastra/core"
+  - "@mastra/rag"
 ---
 # Chunking and Embedding Documents
 Before processing, create a MDocument instance from your content. You can initialize it from various formats:
-```ts showLineNumbers copy
+```ts
 const docFromText = MDocument.fromText("Your plain text content...");
 const docFromHTML = MDocument.fromHTML("<html>Your HTML content...</html>");
 const docFromMarkdown = MDocument.fromMarkdown("# Your Markdown content...");
@@ -28,11 +31,13 @@ Use `chunk` to split documents into manageable pieces. Mastra supports multiple
 - `latex`: LaTeX structure-aware splitting
 - `sentence`: Sentence-aware splitting
-**Note:** Each strategy accepts different parameters optimized for its chunking approach.
+:::note
+Each strategy accepts different parameters optimized for its chunking approach.
+:::
 Here's an example of how to use the `recursive` strategy:
-```ts showLineNumbers copy
+```ts
 const chunks = await doc.chunk({
   strategy: "recursive",
   maxSize: 512,
@@ -46,20 +51,19 @@ const chunks = await doc.chunk({
 For text where preserving sentence structure is important, here's an example of how to use the `sentence` strategy:
-```ts showLineNumbers copy
+```ts
 const chunks = await doc.chunk({
   strategy: "sentence",
   maxSize: 450,
   minSize: 50,
   overlap: 0,
   sentenceEnders: ["."],
-  keepSeparator: true,
 });
 ```
 For markdown documents where preserving the semantic relationships between sections is important, here's an example of how to use the `semantic-markdown` strategy:
-```ts showLineNumbers copy
+```ts
 const chunks = await doc.chunk({
   strategy: "semantic-markdown",
   joinThreshold: 500,
@@ -67,19 +71,21 @@ const chunks = await doc.chunk({
 });
 ```
-**Note:** Metadata extraction may use LLM calls, so ensure your API key is set.
+:::note
+Metadata extraction may use LLM calls, so ensure your API key is set.
+:::
-We go deeper into chunking strategies in our [chunk documentation](/reference/v1/rag/chunk).
+We go deeper into chunking strategies in our [`chunk()` reference documentation](/reference/v1/rag/chunk).
 ## Step 2: Embedding Generation
-Transform chunks into embeddings using your preferred provider. Mastra supports embedding models through the model router or AI SDK packages.
+Transform chunks into embeddings using your preferred provider. Mastra supports embedding models through the model router.
-### Using the Model Router (Recommended)
+### Using the Model Router
 The simplest way is to use Mastra's model router with `provider/model` strings:
-```ts showLineNumbers copy
+```ts
 import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 import { embedMany } from "ai";
@@ -89,27 +95,10 @@ const { embeddings } = await embedMany({
 });
 ```
-Supported embedding models:
-- **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
-- **Google**: `gemini-embedding-001`, `text-embedding-004`
+Mastra supports OpenAI and Google embedding models. For a complete list of supported embedding models, see the [embeddings reference](/reference/v1/rag/embeddings).
 The model router automatically handles API key detection from environment variables.
-### Using AI SDK Packages
-You can also use AI SDK embedding models directly:
-```ts showLineNumbers copy
-import { embedMany } from "ai";
-import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
-const { embeddings } = await embedMany({
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-  values: chunks.map((chunk) => chunk.text),
-});
-```
 The embedding functions return vectors, arrays of numbers representing the semantic meaning of your text, ready for similarity searches in your vector database.
 ### Configuring Embedding Dimensions
@@ -147,15 +136,15 @@ const { embeddings } = await embedMany({
 });
 ```
-### Vector Database Compatibility
+:::important[Vector Database Compatibility]
 When storing embeddings, the vector database index must be configured to match the output size of your embedding model. If the dimensions do not match, you may get errors or data corruption.
+:::
 ## Example: Complete Pipeline
 Here's an example showing document processing and embedding generation with both providers:
-```ts showLineNumbers copy
+```ts
 import { embedMany } from "ai";
 import { MDocument } from "@mastra/rag";

package/.docs/raw/rag/graph-rag.mdx ADDED Viewed

@@ -0,0 +1,223 @@
+---
+title: "GraphRAG | RAG"
+description: Guide on graph-based retrieval in Mastra's RAG systems for documents with complex relationships.
+packages:
+  - "@mastra/core"
+  - "@mastra/rag"
+---
+# GraphRAG
+Graph-based retrieval enhances traditional vector search by following relationships between chunks of information. This approach is useful when information is spread across multiple documents or when documents reference each other.
+## When to use GraphRAG
+GraphRAG is particularly effective when:
+- Information is spread across multiple documents
+- Documents reference each other
+- You need to traverse relationships to find complete answers
+- Understanding connections between concepts is important
+- Simple vector similarity misses important contextual relationships
+For straightforward semantic search without relationship traversal, use [standard retrieval methods](/docs/v1/rag/retrieval).
+## How GraphRAG works
+GraphRAG combines vector similarity with knowledge graph traversal:
+1. Initial vector search retrieves relevant chunks based on semantic similarity
+2. A knowledge graph is constructed from the retrieved chunks
+3. The graph is traversed to find connected information
+4. Results include both directly relevant chunks and related content
+This process helps surface information that might not be semantically similar to the query but is contextually relevant through connections.
+## Creating a graph query tool
+The Graph Query Tool provides agents with the ability to perform graph-based retrieval:
+```ts
+import { createGraphRAGTool } from "@mastra/rag";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+const graphQueryTool = createGraphRAGTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  graphOptions: {
+    threshold: 0.7,
+  },
+});
+```
+### Configuration options
+The `graphOptions` parameter controls how the knowledge graph is built and traversed:
+- `threshold`: Similarity threshold (0-1) for determining which chunks are related. Higher values create sparser graphs with stronger connections; lower values create denser graphs with more potential relationships.
+- `dimension`: Vector embedding dimension. Must match the embedding model's output dimension (e.g., 1536 for OpenAI's text-embedding-3-small).
+```ts
+const graphQueryTool = createGraphRAGTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  graphOptions: {
+    dimension: 1536,
+    threshold: 0.7,
+  },
+});
+```
+## Using GraphRAG with agents
+Integrate the graph query tool with an agent to enable graph-based retrieval:
+```ts
+import { Agent } from "@mastra/core/agent";
+const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "GraphRAG Agent",
+  instructions: `You are a helpful assistant that answers questions based on the provided context.
+When answering questions, use the graph query tool to find relevant information and relationships.
+Base your answers on the context provided by the tool, and clearly state if the context doesn't contain enough information.`,
+  model: "openai/gpt-5.1",
+  tools: {
+    graphQueryTool,
+  },
+});
+```
+## Document processing and storage
+Before using graph-based retrieval, process documents into chunks and store their embeddings:
+```ts
+import { MDocument } from "@mastra/rag";
+import { embedMany } from "ai";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+// Create and chunk document
+const doc = MDocument.fromText("Your document content here...");
+const chunks = await doc.chunk({
+  strategy: "recursive",
+  size: 512,
+  overlap: 50,
+  separator: "\n",
+});
+// Generate embeddings
+const { embeddings } = await embedMany({
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  values: chunks.map((chunk) => chunk.text),
+});
+// Store in vector database
+const vectorStore = mastra.getVector("pgVector");
+await vectorStore.createIndex({
+  indexName: "embeddings",
+  dimension: 1536,
+});
+await vectorStore.upsert({
+  indexName: "embeddings",
+  vectors: embeddings,
+  metadata: chunks?.map((chunk) => ({ text: chunk.text })),
+});
+```
+## Querying with GraphRAG
+Once configured, the agent can perform graph-based queries:
+```ts
+const query = "What are the effects of infrastructure changes on local businesses?";
+const response = await ragAgent.generate(query);
+console.log(response.text);
+```
+The agent uses the graph query tool to:
+1. Convert the query to an embedding
+2. Find semantically similar chunks in the vector store
+3. Build a knowledge graph from related chunks
+4. Traverse the graph to find connected information
+5. Return comprehensive context for generating the response
+## Choosing the right threshold
+The threshold parameter significantly impacts retrieval quality:
+- **High threshold (0.8-0.9)**: Strict connections, fewer relationships, more precise but potentially incomplete results
+- **Medium threshold (0.6-0.8)**: Balanced approach, good for most use cases
+- **Low threshold (0.4-0.6)**: More connections, broader context, risk of including less relevant information
+Start with 0.7 and adjust based on your specific use case:
+```ts
+// Strict connections for precise answers
+const strictGraphTool = createGraphRAGTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  graphOptions: {
+    threshold: 0.85,
+  },
+});
+// Broader connections for exploratory queries
+const broadGraphTool = createGraphRAGTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  graphOptions: {
+    threshold: 0.5,
+  },
+});
+```
+## Combining with other retrieval methods
+GraphRAG can be used alongside other retrieval approaches:
+```ts
+import { createVectorQueryTool } from "@mastra/rag";
+const vectorQueryTool = createVectorQueryTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+});
+const graphQueryTool = createGraphRAGTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  graphOptions: {
+    threshold: 0.7,
+  },
+});
+const agent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  instructions: `Use vector search for simple fact-finding queries.
+Use graph search when you need to understand relationships or find connected information.`,
+  model: "openai/gpt-5.1",
+  tools: {
+    vectorQueryTool,
+    graphQueryTool,
+  },
+});
+```
+This gives the agent flexibility to choose the appropriate retrieval method based on the query.
+## Reference
+For detailed API documentation, see:
+- [GraphRAG Class](/reference/v1/rag/graph-rag)
+- [createGraphRAGTool()](/reference/v1/tools/graph-rag-tool)

package/.docs/raw/rag/overview.mdx CHANGED Viewed

@@ -1,6 +1,10 @@
 ---
 title: "RAG (Retrieval-Augmented Generation) in Mastra | RAG"
 description: Overview of Retrieval-Augmented Generation (RAG) in Mastra, detailing its capabilities for enhancing LLM outputs with relevant context.
+packages:
+  - "@mastra/core"
+  - "@mastra/pg"
+  - "@mastra/rag"
 ---
 # RAG (Retrieval-Augmented Generation) in Mastra
@@ -18,7 +22,7 @@ Mastra's RAG system provides:
 To implement RAG, you process your documents into chunks, create embeddings, store them in a vector database, and then retrieve relevant context at query time.
-```ts showLineNumbers copy
+```ts
 import { embedMany } from "ai";
 import { PgVector } from "@mastra/pg";
 import { MDocument } from "@mastra/rag";
@@ -74,5 +78,4 @@ Mastra supports multiple vector stores for embedding persistence and similarity
 ## More resources
-- [Chain of Thought RAG Example](/examples/v1/rag/usage/cot-rag)
-- [All RAG Examples](/examples/v1/) (including different chunking strategies, embedding models, and vector stores)
+- [Chain of Thought RAG Example](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/cot-rag)