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

package/.docs/raw/reference/processors/token-limiter-processor.mdx

@@ -1,15 +1,21 @@
 ---
 title: "Reference: Token Limiter Processor | Processors"
-description: "Documentation for the TokenLimiterProcessor in Mastra, which limits the number of tokens in AI responses."
+description: "Documentation for the TokenLimiterProcessor in Mastra, which limits the number of tokens in messages."
+packages:
+  - "@mastra/core"
+  - "@mastra/memory"
 ---
 
 # TokenLimiterProcessor
 
-The `TokenLimiterProcessor` is an **output processor** that limits the number of tokens in AI responses. This processor helps control response length by implementing token counting with configurable strategies for handling exceeded limits, including truncation and abortion options for both streaming and non-streaming scenarios.
+The `TokenLimiterProcessor` limits the number of tokens in messages. It can be used as both an input and output processor:
+
+- **Input processor**: Filters historical messages to fit within the context window, prioritizing recent messages
+- **Output processor**: Limits generated response tokens via streaming or non-streaming with configurable strategies for handling exceeded limits
 
 ## Usage example
 
-```typescript copy
+```typescript
 import { TokenLimiterProcessor } from "@mastra/core/processors";
 
 const processor = new TokenLimiterProcessor({
@@ -82,6 +88,12 @@ const processor = new TokenLimiterProcessor({
       description: "Optional processor display name",
       isOptional: true,
     },
+    {
+      name: "processInput",
+      type: "(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>",
+      description: "Filters input messages to fit within token limit, prioritizing recent messages while preserving system messages",
+      isOptional: false,
+    },
     {
       name: "processOutputStream",
       type: "(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never }) => Promise<ChunkType | null>",
@@ -90,22 +102,10 @@ const processor = new TokenLimiterProcessor({
     },
     {
       name: "processOutputResult",
-      type: "(args: { messages: MastraMessageV2[]; abort: (reason?: string) => never }) => Promise<MastraMessageV2[]>",
+      type: "(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>",
       description: "Processes final output results to limit token count in non-streaming scenarios",
       isOptional: false,
     },
-    {
-      name: "reset",
-      type: "() => void",
-      description: "Reset the token counter (useful for testing or reusing the processor)",
-      isOptional: false,
-    },
-    {
-      name: "getCurrentTokens",
-      type: "() => number",
-      description: "Get the current token count",
-      isOptional: false,
-    },
     {
       name: "getMaxTokens",
       type: "() => number",
@@ -115,16 +115,59 @@ const processor = new TokenLimiterProcessor({
   ]}
 />
 
+## Error behavior
+
+When used as an input processor, `TokenLimiterProcessor` throws a `TripWire` error in the following cases:
+
+- **Empty messages**: If there are no messages to process, a TripWire is thrown because you cannot send an LLM request with no messages.
+- **System messages exceed limit**: If system messages alone exceed the token limit, a TripWire is thrown because you cannot send an LLM request with only system messages and no user/assistant messages.
+
+```typescript
+import { TripWire } from "@mastra/core/agent";
+
+try {
+  await agent.generate("Hello");
+} catch (error) {
+  if (error instanceof TripWire) {
+    console.log("Token limit error:", error.message);
+  }
+}
+```
+
 ## Extended usage example
 
-```typescript title="src/mastra/agents/limited-agent.ts" showLineNumbers copy
+### As an input processor (limit context window)
+
+Use `inputProcessors` to limit historical messages sent to the model, which helps stay within context window limits:
+
+```typescript title="src/mastra/agents/context-limited-agent.ts"
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { TokenLimiterProcessor } from "@mastra/core/processors";
+
+export const agent = new Agent({
+  name: "context-limited-agent",
+  instructions: "You are a helpful assistant",
+  model: "openai/gpt-4o",
+  memory: new Memory({ /* ... */ }),
+  inputProcessors: [
+    new TokenLimiterProcessor({ limit: 4000 }) // Limits historical messages to ~4000 tokens
+  ]
+});
+```
+
+### As an output processor (limit response length)
+
+Use `outputProcessors` to limit the length of generated responses:
+
+```typescript title="src/mastra/agents/response-limited-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { TokenLimiterProcessor } from "@mastra/core/processors";
 
 export const agent = new Agent({
-  name: "limited-agent",
+  name: "response-limited-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-5.1",
+  model: "openai/gpt-4o",
   outputProcessors: [
     new TokenLimiterProcessor({
       limit: 1000,

package/.docs/raw/reference/processors/tool-call-filter.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Tool Call Filter | Processors"
 description: "Documentation for the ToolCallFilter processor in Mastra, which filters out tool calls and results from messages."
+packages:
+  - "@mastra/core"
 ---
 
 # ToolCallFilter
@@ -9,7 +11,7 @@ The `ToolCallFilter` is an **input processor** that filters out tool calls and t
 
 ## Usage example
 
-```typescript copy
+```typescript
 import { ToolCallFilter } from "@mastra/core/processors";
 
 // Exclude all tool calls
@@ -74,7 +76,7 @@ const filterSpecific = new ToolCallFilter({
 
 ## Extended usage example
 
-```typescript title="src/mastra/agents/filtered-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/filtered-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { ToolCallFilter } from "@mastra/core/processors";
 
@@ -99,7 +101,7 @@ export const agent = new Agent({
 
 ## Filtering all tool calls
 
-```typescript copy
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { ToolCallFilter } from "@mastra/core/processors";
 

package/.docs/raw/reference/processors/unicode-normalizer.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Unicode Normalizer | Processors"
 description: "Documentation for the UnicodeNormalizer in Mastra, which normalizes Unicode text to ensure consistent formatting and remove potentially problematic characters."
+packages:
+  - "@mastra/core"
 ---
 
 # UnicodeNormalizer
@@ -9,7 +11,7 @@ The `UnicodeNormalizer` is an **input processor** that normalizes Unicode text t
 
 ## Usage example
 
-```typescript copy
+```typescript
 import { UnicodeNormalizer } from "@mastra/core/processors";
 
 const processor = new UnicodeNormalizer({
@@ -84,7 +86,7 @@ const processor = new UnicodeNormalizer({
     },
     {
       name: "processInput",
-      type: "(args: { messages: MastraMessageV2[]; abort: (reason?: string) => never }) => MastraMessageV2[]",
+      type: "(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => MastraDBMessage[]",
       description: "Processes input messages to normalize Unicode text",
       isOptional: false,
     },
@@ -94,11 +96,12 @@ const processor = new UnicodeNormalizer({
 
 ## Extended usage example
 
-```typescript title="src/mastra/agents/normalized-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/normalized-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { UnicodeNormalizer } from "@mastra/core/processors";
 
 export const agent = new Agent({
+  id: "normalized-agent",
   name: "normalized-agent",
   instructions: "You are a helpful assistant",
   model: "openai/gpt-5.1",

package/.docs/raw/reference/processors/working-memory-processor.mdx

@@ -1,6 +1,9 @@
 ---
 title: "Reference: Working Memory Processor | Processors"
 description: "Documentation for the WorkingMemory processor in Mastra, which injects persistent user/context data as system instructions."
+packages:
+  - "@mastra/core"
+  - "@mastra/pg"
 ---
 
 # WorkingMemory
@@ -9,7 +12,7 @@ The `WorkingMemory` is an **input processor** that injects working memory data a
 
 ## Usage example
 
-```typescript copy
+```typescript
 import { WorkingMemory } from "@mastra/core/processors";
 
 const processor = new WorkingMemory({
@@ -135,7 +138,7 @@ const processor = new WorkingMemory({
 
 ## Extended usage example
 
-```typescript title="src/mastra/agents/personalized-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/personalized-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { WorkingMemory, MessageHistory } from "@mastra/core/processors";
 import { PostgresStorage } from "@mastra/pg";
@@ -173,7 +176,7 @@ export const agent = new Agent({
 
 ## JSON format example
 
-```typescript copy
+```typescript
 import { WorkingMemory } from "@mastra/core/processors";
 
 const processor = new WorkingMemory({

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

@@ -1,6 +1,8 @@
 ---
-title: "Reference: Reference: .chunk() | RAG"
+title: "Reference: .chunk() | RAG"
 description: Documentation for the chunk function in Mastra, which splits documents into smaller segments using various strategies.
+packages:
+  - "@mastra/rag"
 ---
 
 # Reference: .chunk()
@@ -77,11 +79,11 @@ The following parameters are available for all chunking strategies.
         "Function to calculate text length. Defaults to character count.",
     },
     {
-      name: "keepSeparator",
-      type: "boolean | 'start' | 'end'",
+      name: "separatorPosition",
+      type: "'start' | 'end'",
       isOptional: true,
       description:
-        "Whether to keep the separator at the start or end of chunks",
+        "Where to position the separator in chunks. 'start' attaches to beginning of next chunk, 'end' attaches to end of current chunk. If not specified, separators are discarded.",
     },
     {
       name: "addStartIndex",
@@ -112,7 +114,7 @@ See [ExtractParams reference](/reference/v1/rag/extract-params) for details on t
 
 Strategy-specific options are passed as top-level parameters alongside the strategy parameter. For example:
 
-```typescript showLineNumbers copy
+```typescript
 // Character strategy example
 const chunks = await doc.chunk({
   strategy: "character",
@@ -136,7 +138,6 @@ const chunks = await doc.chunk({
   minSize: 50, // Sentence-specific option
   sentenceEnders: ["."], // Sentence-specific option
   fallbackToCharacters: false, // Sentence-specific option
-  keepSeparator: true, // general option
 });
 
 // HTML strategy example

package/.docs/raw/reference/rag/database-config.mdx

@@ -1,6 +1,9 @@
 ---
 title: "Reference: DatabaseConfig | RAG"
 description: API reference for database-specific configuration types used with vector query tools in Mastra RAG systems.
+packages:
+  - "@mastra/core"
+  - "@mastra/rag"
 ---
 
 import Tabs from "@theme/Tabs";
@@ -210,11 +213,10 @@ whereDocument: { "$contains": "API documentation" }
       }
     });
 
-    await vectorTool.execute({
-      context: { queryText: 'search query' },
-      mastra,
-      requestContext
-    });
+    await vectorTool.execute(
+      { queryText: 'search query' },
+      { mastra, requestContext }
+    );
     ```
 
   </TabItem>
@@ -348,5 +350,5 @@ const vectorTool = createVectorQueryTool({
 ## Related
 
 - [createVectorQueryTool()](/reference/v1/tools/vector-query-tool)
-- [Hybrid Vector Search](/examples/v1/rag/query/hybrid-vector-search)
+- [Hybrid Vector Search](/docs/v1/rag/retrieval#metadata-filtering)
 - [Metadata Filters](/reference/v1/rag/metadata-filters)

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: MDocument | Document Processing | RAG"
 description: Documentation for the MDocument class in Mastra, which handles document processing and chunking.
+packages:
+  - "@mastra/rag"
 ---
 
 # MDocument

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Embed | RAG"
 description: Documentation for embedding functionality in Mastra using the AI SDK.
+packages:
+  - "@mastra/core"
 ---
 
 # Embed

package/.docs/raw/reference/rag/extract-params.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: ExtractParams | RAG"
 description: Documentation for metadata extraction configuration in Mastra.
+packages:
+  - "@mastra/rag"
 ---
 
 # ExtractParams
@@ -9,7 +11,7 @@ ExtractParams configures metadata extraction from document chunks using LLM anal
 
 ## Example
 
-```typescript showLineNumbers copy
+```typescript
 import { MDocument } from "@mastra/rag";
 
 const doc = MDocument.fromText(text);
@@ -63,6 +65,13 @@ The `extract` parameter accepts the following fields:
       description:
         "Enable keyword extraction. Set to true for default settings, or provide custom configuration.",
     },
+    {
+      name: "schema",
+      type: "SchemaExtractArgs",
+      isOptional: true,
+      description:
+        "Enable structured metadata extraction using a Zod schema.",
+    },
   ]}
 />
 
@@ -186,9 +195,40 @@ The `extract` parameter accepts the following fields:
   ]}
 />
 
+### SchemaExtractArgs
+
+<PropertiesTable
+  content={[
+    {
+      name: "schema",
+      type: "ZodType",
+      isOptional: false,
+      description: "Zod schema defining the structure of the data to extract.",
+    },
+    {
+      name: "llm",
+      type: "MastraLanguageModel",
+      isOptional: true,
+      description: "AI SDK language model to use for extraction.",
+    },
+    {
+      name: "instructions",
+      type: "string",
+      isOptional: true,
+      description: "Instructions for the LLM on what to extract.",
+    },
+    {
+      name: "metadataKey",
+      type: "string",
+      isOptional: true,
+      description: "Key to nest extraction results under. If omitted, results are spread into the metadata object.",
+    },
+  ]}
+/>
+
 ## Advanced Example
 
-```typescript showLineNumbers copy
+```typescript
 import { MDocument } from "@mastra/rag";
 
 const doc = MDocument.fromText(text);
@@ -219,6 +259,16 @@ const chunks = await doc.chunk({
       keywords: 5, // Extract 5 keywords
       promptTemplate: "Extract {maxKeywords} key terms from: {context}",
     },
+
+    // Schema extraction with Zod
+    schema: {
+        schema: z.object({
+            productName: z.string(),
+            category: z.enum(["electronics", "clothing"]),
+        }),
+        instructions: "Extract product information.",
+        metadataKey: "product",
+    },
   },
 });
 
@@ -227,7 +277,11 @@ const chunks = await doc.chunk({
 //   documentTitle: "AI in Modern Computing",
 //   sectionSummary: "Overview of AI concepts and their applications in computing",
 //   questionsThisExcerptCanAnswer: "1. What is machine learning?\n2. How do neural networks work?",
-//   excerptKeywords: "1. Machine learning\n2. Neural networks\n3. Training data"
+//   excerptKeywords: "1. Machine learning\n2. Neural networks\n3. Training data",
+//   product: {
+//     productName: "Neural Net 2000",
+//     category: "electronics"
+//   }
 // }
 ```
 

package/.docs/raw/reference/rag/graph-rag.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: GraphRAG | RAG"
 description: Documentation for the GraphRAG class in Mastra, which implements a graph-based approach to retrieval augmented generation.
+packages:
+  - "@mastra/rag"
 ---
 
 # GraphRAG

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Metadata Filters | RAG"
 description: Documentation for metadata filtering capabilities in Mastra, which allow for precise querying of vector search results across different vector stores.
+packages:
+  - "@mastra/pg"
 ---
 
 # Metadata Filters
@@ -98,7 +100,7 @@ const results = await store.query({
       name: "$elemMatch",
       description: "Matches array elements meeting criteria",
       example: "{ scores: { $elemMatch: { $gt: 80 } } }",
-      supportedBy: ["LibSQL", "PgVector", "MongoDB"],
+      supportedBy: ["libSQL", "PgVector", "MongoDB"],
     },
   ]}
 />
@@ -127,7 +129,7 @@ const results = await store.query({
         "Qdrant",
         "Upstash",
         "PgVector",
-        "LibSQL",
+        "libSQL",
         "MongoDB",
       ],
     },
@@ -135,7 +137,7 @@ const results = await store.query({
       name: "$nor",
       description: "Logical NOR",
       example: '{ $nor: [{ status: "deleted" }, { archived: true }] }',
-      supportedBy: ["Qdrant", "Upstash", "PgVector", "LibSQL", "MongoDB"],
+      supportedBy: ["Qdrant", "Upstash", "PgVector", "libSQL", "MongoDB"],
     },
   ]}
 />
@@ -159,7 +161,7 @@ const results = await store.query({
       name: "$contains",
       description: "Text contains substring",
       example: '{ description: { $contains: "sale" } }',
-      supportedBy: ["Upstash", "LibSQL", "PgVector"],
+      supportedBy: ["Upstash", "libSQL", "PgVector"],
     },
     {
       name: "$regex",
@@ -171,7 +173,7 @@ const results = await store.query({
       name: "$size",
       description: "Array length check",
       example: "{ tags: { $size: { $gt: 2 } } }",
-      supportedBy: ["Astra", "LibSQL", "PgVector", "MongoDB"],
+      supportedBy: ["Astra", "libSQL", "PgVector", "MongoDB"],
     },
     {
       name: "$geo",
@@ -263,7 +265,7 @@ const results = await store.query({
 - Vectors must be re-upserted after creating new metadata indexes to be included in filtered results
 - Range queries may have reduced accuracy with very large datasets (~10M+ vectors)
 
-### LibSQL
+### libSQL
 
 - Supports nested object queries with dot notation
 - Array fields are validated to ensure they contain valid JSON arrays
@@ -291,6 +293,24 @@ const results = await store.query({
 
 - Supports advanced filtering with nested conditions
 - Payload (metadata) fields must be explicitly indexed for filtering
+- Use `createPayloadIndex()` to index fields you want to filter on:
+
+```typescript
+// Index a field before filtering on it
+await store.createPayloadIndex({
+  indexName: "my_index",
+  fieldName: "source",
+  fieldSchema: "keyword", // 'keyword' | 'integer' | 'float' | 'geo' | 'text' | 'bool' | 'datetime' | 'uuid'
+});
+
+// Now filtering works
+const results = await store.query({
+  indexName: "my_index",
+  queryVector: queryVector,
+  filter: { source: "document-a" },
+});
+```
+
 - Efficient handling of geo-spatial queries
 - Special handling for null and empty values
 - Vector-specific filtering capabilities
@@ -338,7 +358,7 @@ const results = await store.query({
 - [Astra](/reference/v1/vectors/astra)
 - [Chroma](/reference/v1/vectors/chroma)
 - [Cloudflare Vectorize](/reference/v1/vectors/vectorize)
-- [LibSQL](/reference/v1/vectors/libsql)
+- [libSQL](/reference/v1/vectors/libsql)
 - [MongoDB](/reference/v1/vectors/mongodb)
 - [PgStore](/reference/v1/vectors/pg)
 - [Pinecone](/reference/v1/vectors/pinecone)

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: rerank() | RAG"
 description: Documentation for the rerank function in Mastra, which provides advanced reranking capabilities for vector search results.
+packages:
+  - "@mastra/rag"
 ---
 
 # rerank()

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: rerankWithScorer() | RAG"
 description: Documentation for the rerank function in Mastra, which provides advanced reranking capabilities for vector search results.
+packages:
+  - "@mastra/rag"
 ---
 
 # rerankWithScorer()