@mastra/mcp-docs-server 0.13.8 → 0.13.9-alpha.1

package/.docs/raw/reference/memory/getThreadsByResourceIdPaginated.mdx

@@ -0,0 +1,187 @@
+# getThreadsByResourceIdPaginated Reference
+
+The `getThreadsByResourceIdPaginated` function retrieves threads associated with a specific resource ID with pagination support. This method addresses performance and memory usage concerns when dealing with large numbers of threads by returning results in manageable chunks with metadata for navigation.
+
+## Usage Example
+
+```typescript
+import { Memory } from "@mastra/core/memory";
+
+const memory = new Memory(config);
+
+// Basic usage with default parameters
+const result = await memory.getThreadsByResourceIdPaginated({
+  resourceId: "resource-123",
+  page: 0,
+  perPage: 100,
+});
+
+console.log(result.threads);
+console.log(result.total);
+console.log(result.hasMore);
+
+// Custom pagination with sorting
+const customResult = await memory.getThreadsByResourceIdPaginated({
+  resourceId: "resource-123",
+  page: 2,
+  perPage: 50,
+  orderBy: "updatedAt",
+  sortDirection: "ASC",
+});
+
+// Process paginated results
+let currentPage = 0;
+let hasMorePages = true;
+
+while (hasMorePages) {
+  const pageResult = await memory.getThreadsByResourceIdPaginated({
+    resourceId: "user-456",
+    page: currentPage,
+    perPage: 25,
+    orderBy: "createdAt",
+    sortDirection: "DESC",
+  });
+  
+  // Process threads
+  pageResult.threads.forEach(thread => {
+    console.log(`Thread: ${thread.id}, Created: ${thread.createdAt}`);
+  });
+  
+  hasMorePages = pageResult.hasMore;
+  currentPage++;
+}
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "resourceId",
+      type: "string",
+      description: "The ID of the resource whose threads are to be retrieved.",
+      isOptional: false,
+    },
+    {
+      name: "page",
+      type: "number",
+      description: "Page number to retrieve. Must be a positive integer.",
+      isOptional: false,
+    },
+    {
+      name: "perPage",
+      type: "number",
+      description: "Number of threads to return per page. Must be a positive integer.",
+      isOptional: false,
+    },
+    {
+      name: "orderBy",
+      type: "ThreadOrderBy",
+      description: "Field to sort threads by. Accepts 'createdAt' or 'updatedAt'. Default: 'createdAt'",
+      isOptional: true,
+    },
+    {
+      name: "sortDirection",
+      type: "ThreadSortDirection", 
+      description: "Sort order direction. Accepts 'ASC' or 'DESC'. Default: 'DESC'",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Type Definitions
+
+```typescript
+type ThreadOrderBy = 'createdAt' | 'updatedAt';
+type ThreadSortDirection = 'ASC' | 'DESC';
+
+interface ThreadSortOptions {
+  orderBy?: ThreadOrderBy;
+  sortDirection?: ThreadSortDirection;
+}
+
+interface PaginationInfo {
+  total: number;      // Total number of threads across all pages
+  page: number;       // Current page number
+  perPage: number;    // Number of threads per page
+  hasMore: boolean;   // Whether additional pages exist
+}
+```
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "threads",
+      type: "StorageThreadType[]",
+      description: "Array of threads for the current page, sorted according to the specified criteria.",
+    },
+    {
+      name: "total",
+      type: "number",
+      description: "Total number of threads associated with the resource ID across all pages.",
+    },
+    {
+      name: "page",
+      type: "number",
+      description: "Current page number.",
+    },
+    {
+      name: "perPage",
+      type: "number",
+      description: "Number of threads returned per page as specified in the request.",
+    },
+    {
+      name: "hasMore",
+      type: "boolean",
+      description: "Indicates whether additional pages of results are available.",
+    },
+  ]}
+/>
+
+## Technical Notes
+
+### Performance Considerations
+
+This method executes database-level pagination using LIMIT/OFFSET operations (or equivalent), which provides better performance and memory usage compared to retrieving all threads and paginating in application code.
+
+### Default Values
+
+- `orderBy`: Defaults to `"createdAt"`
+- `sortDirection`: Defaults to `"DESC"` (newest first)
+
+### Relationship to getThreadsByResourceId
+
+The paginated version (`getThreadsByResourceIdPaginated`) complements the existing `getThreadsByResourceId` method:
+
+- Use `getThreadsByResourceId` when you need all threads for a resource
+- Use `getThreadsByResourceIdPaginated` when working with potentially large thread collections or implementing UI pagination
+
+Both methods support the same sorting options for consistency.
+
+### Error Handling
+
+```typescript
+try {
+  const result = await memory.getThreadsByResourceIdPaginated({
+    resourceId: "resource-123",
+    page: 0,
+    perPage: 100,
+  });
+  
+  if (result.threads.length === 0) {
+    console.log("No threads found for this resource");
+  }
+} catch (error) {
+  console.error("Failed to retrieve paginated threads:", error);
+}
+```
+
+### Related
+
+- [Memory Class Reference](/reference/memory/Memory.mdx)
+- [getThreadsByResourceId](/reference/memory/getThreadsByResourceId.mdx) - Non-paginated version
+- [Getting Started with Memory](/docs/memory/overview.mdx) (Covers threads/resources concept)
+- [createThread](/reference/memory/createThread.mdx)
+- [getThreadById](/reference/memory/getThreadById.mdx)

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

@@ -42,21 +42,30 @@ const chunksWithMetadata = await doc.chunk({
 
 ## Parameters
 
+The following parameters are available for all chunking strategies.
+**Important:** Each strategy will only utilize a subset of these parameters relevant to its specific use case.
+
 <PropertiesTable
   content={[
     {
       name: "strategy",
-      type: "'recursive' | 'character' | 'token' | 'markdown' | 'html' | 'json' | 'latex'",
+      type: "'recursive' | 'character' | 'token' | 'markdown' | 'html' | 'json' | 'latex' | 'sentence'",
       isOptional: true,
       description:
         "The chunking strategy to use. If not specified, defaults based on document type. Depending on the chunking strategy, there are additional optionals. Defaults: .md files → 'markdown', .html/.htm → 'html', .json → 'json', .tex → 'latex', others → 'recursive'",
     },
+    {
+      name: "maxSize",
+      type: "number",
+      isOptional: true,
+      defaultValue: "4000",
+      description: "Maximum size of each chunk. **Note:** Some strategy configurations (markdown with headers, HTML with headers) ignore this parameter.",
+    },
     {
       name: "size",
       type: "number",
       isOptional: true,
-      defaultValue: "512",
-      description: "Maximum size of each chunk",
+      description: "**Deprecated:** Use `maxSize` instead. This parameter will be removed in the next major version.",
     },
     {
       name: "overlap",
@@ -66,33 +75,38 @@ const chunksWithMetadata = await doc.chunk({
       description: "Number of characters/tokens that overlap between chunks.",
     },
     {
-      name: "separator",
-      type: "string",
+      name: "lengthFunction",
+      type: "(text: string) => number",
+      isOptional: true,
+      description: "Function to calculate text length. Defaults to character count.",
+    },
+    {
+      name: "keepSeparator",
+      type: "boolean | 'start' | 'end'",
       isOptional: true,
-      defaultValue: "\\n\\n",
       description:
-        "Character(s) to split on. Defaults to double newline for text content.",
+        "Whether to keep the separator at the start or end of chunks",
     },
     {
-      name: "isSeparatorRegex",
+      name: "addStartIndex",
       type: "boolean",
       isOptional: true,
       defaultValue: "false",
-      description: "Whether the separator is a regex pattern",
+      description: "Whether to add start index metadata to chunks.",
     },
     {
-      name: "keepSeparator",
-      type: "'start' | 'end'",
+      name: "stripWhitespace",
+      type: "boolean",
       isOptional: true,
-      description:
-        "Whether to keep the separator at the start or end of chunks",
+      defaultValue: "true",
+      description: "Whether to strip whitespace from chunks.",
     },
     {
       name: "extract",
       type: "ExtractParams",
       isOptional: true,
       description:
-        "Metadata extraction configuration. See [ExtractParams reference](./extract-params) for details.",
+        "Metadata extraction configuration. See [ExtractParams reference](/reference/rag/extract-params) for details.",
     },
   ]}
 />
@@ -102,6 +116,32 @@ const chunksWithMetadata = await doc.chunk({
 Strategy-specific options are passed as top-level parameters alongside the strategy parameter. For example:
 
 ```typescript showLineNumbers copy
+// Character strategy example
+const chunks = await doc.chunk({
+  strategy: "character",
+  separator: ".", // Character-specific option
+  isSeparatorRegex: false, // Character-specific option
+  maxSize: 300, // general option
+});
+
+// Recursive strategy example
+const chunks = await doc.chunk({
+  strategy: "recursive",
+  separators: ["\n\n", "\n", " "], // Recursive-specific option
+  language: "markdown", // Recursive-specific option
+  maxSize: 500, // general option
+});
+
+// Sentence strategy example
+const chunks = await doc.chunk({
+  strategy: "sentence",
+  maxSize: 450, // Required for sentence strategy
+  minSize: 50, // Sentence-specific option
+  sentenceEnders: ["."], // Sentence-specific option
+  fallbackToCharacters: false, // Sentence-specific option
+  keepSeparator: true, // general option
+});
+
 // HTML strategy example
 const chunks = await doc.chunk({
   strategy: "html",
@@ -109,8 +149,6 @@ const chunks = await doc.chunk({
     ["h1", "title"],
     ["h2", "subtitle"],
   ], // HTML-specific option
-  sections: [["div.content", "main"]], // HTML-specific option
-  size: 500, // general option
 });
 
 // Markdown strategy example
@@ -121,7 +159,6 @@ const chunks = await doc.chunk({
     ["##", "section"],
   ], // Markdown-specific option
   stripHeaders: true, // Markdown-specific option
-  overlap: 50, // general option
 });
 
 // Token strategy example
@@ -129,12 +166,105 @@ const chunks = await doc.chunk({
   strategy: "token",
   encodingName: "gpt2", // Token-specific option
   modelName: "gpt-3.5-turbo", // Token-specific option
-  size: 1000, // general option
+  maxSize: 1000, // general option
 });
 ```
 
 The options documented below are passed directly at the top level of the configuration object, not nested within a separate options object.
 
+### Character
+
+<PropertiesTable
+  content={[
+    {
+      name: "separator",
+      type: "string",
+      isOptional: true,
+      defaultValue: "\\n\\n",
+      description: "Character(s) to split on. Defaults to double newline for text content.",
+    },
+    {
+      name: "isSeparatorRegex",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "Whether the separator is a regex pattern",
+    },
+  ]}
+/>
+
+### Recursive
+
+<PropertiesTable
+  content={[
+    {
+      name: "separators",
+      type: "string[]",
+      isOptional: true,
+      description: "Array of separators to try in order of preference. The strategy will attempt to split on the first separator, then fall back to subsequent ones.",
+    },
+    {
+      name: "isSeparatorRegex",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "Whether the separators are regex patterns",
+    },
+    {
+      name: "language",
+      type: "Language",
+      isOptional: true,
+      description: "Programming or markup language for language-specific splitting behavior. See Language enum for supported values.",
+    },
+  ]}
+/>
+
+### Sentence
+
+<PropertiesTable
+  content={[
+    {
+      name: "maxSize",
+      type: "number",
+      description: "Maximum size of each chunk (required for sentence strategy)",
+    },
+    {
+      name: "minSize",
+      type: "number",
+      isOptional: true,
+      defaultValue: "50",
+      description: "Minimum size of each chunk. Chunks smaller than this will be merged with adjacent chunks when possible.",
+    },
+    {
+      name: "targetSize",
+      type: "number",
+      isOptional: true,
+      description: "Preferred target size for chunks. Defaults to 80% of maxSize. The strategy will try to create chunks close to this size.",
+    },
+    {
+      name: "sentenceEnders",
+      type: "string[]",
+      isOptional: true,
+      defaultValue: "['.', '!', '?']",
+      description: "Array of characters that mark sentence endings for splitting boundaries.",
+    },
+    {
+      name: "fallbackToWords",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "true",
+      description: "Whether to fall back to word-level splitting for sentences that exceed maxSize.",
+    },
+    {
+      name: "fallbackToCharacters",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "true",
+      description: "Whether to fall back to character-level splitting for words that exceed maxSize. Only applies if fallbackToWords is enabled.",
+    },
+  ]}
+/>
+
 ### HTML
 
 <PropertiesTable
@@ -160,6 +290,8 @@ The options documented below are passed directly at the top level of the configu
   ]}
 />
 
+**Important:** When using the HTML strategy, all general options are ignored. Use `headers` for header-based splitting or `sections` for section-based splitting. If used together, `sections` will be ignored.
+
 ### Markdown
 
 <PropertiesTable
@@ -167,6 +299,7 @@ The options documented below are passed directly at the top level of the configu
     {
       name: "headers",
       type: "Array<[string, string]>",
+      isOptional: true,
       description: "Array of [header level, metadata key] pairs",
     },
     {
@@ -184,6 +317,8 @@ The options documented below are passed directly at the top level of the configu
   ]}
 />
 
+**Important:** When using the `headers` option, the markdown strategy ignores all general options and content is split based on the markdown header structure. To use size-based chunking with markdown, omit the `headers` parameter.
+
 ### Token
 
 <PropertiesTable
@@ -200,6 +335,18 @@ The options documented below are passed directly at the top level of the configu
       isOptional: true,
       description: "Name of the model for tokenization",
     },
+    {
+      name: "allowedSpecial",
+      type: "Set<string> | 'all'",
+      isOptional: true,
+      description: "Set of special tokens allowed during tokenization, or 'all' to allow all special tokens",
+    },
+    {
+      name: "disallowedSpecial",
+      type: "Set<string> | 'all'",
+      isOptional: true,
+      description: "Set of special tokens to disallow during tokenization, or 'all' to disallow all special tokens",
+    },
   ]}
 />
 
@@ -233,6 +380,10 @@ The options documented below are passed directly at the top level of the configu
   ]}
 />
 
+### Latex
+
+The Latex strategy uses only the general chunking options listed above. It provides LaTeX-aware splitting optimized for mathematical and academic documents.
+
 ## Return Value
 
 Returns a `MDocument` instance containing the chunked documents. Each chunk includes:

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

@@ -848,8 +848,14 @@ When tools are executed within an MCP server context, they receive an additional
 ```typescript
 execute: async ({ context }, options) => {
   // context contains the tool's input parameters
-  // options contains server capabilities like elicitation
+  // options contains server capabilities like elicitation and authentication info
   
+  // Access authentication information (when available)
+  if (options.extra?.authInfo) {
+    console.log('Authenticated request from:', options.extra.authInfo.clientId);
+  }
+  
+  // Use elicitation capabilities
   const result = await options.elicitation.sendRequest({
     message: "Please provide information",
     requestedSchema: { /* schema */ }
@@ -891,9 +897,12 @@ const server = new MCPServer({
       }),
       execute: async ({ context }, options) => {
         const { reason } = context;
+        
+        // Log session info if available
+        console.log('Request from session:', options.extra?.sessionId);
 
         try {
-          // Request user input via elicitation through the options parameter
+          // Request user input via elicitation
           const result = await options.elicitation.sendRequest({
             message: reason 
               ? `Please provide your contact information. ${reason}`
@@ -1002,10 +1011,18 @@ The elicitation functionality is available through the `options` parameter in to
 
 ```typescript
 // Within a tool's execute function
-options.elicitation.sendRequest({
-  message: string,           // Message to display to user
-  requestedSchema: object    // JSON schema defining expected response structure
-}): Promise<ElicitResult>
+execute: async ({ context }, options) => {
+  // Use elicitation for user input
+  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 (options.extra?.authInfo) {
+    // Use options.extra.authInfo.token, etc.
+  }
+}
 ```
 
 Note that elicitation is **session-aware** when using HTTP-based transports (SSE or HTTP). This means that when multiple clients are connected to the same server, elicitation requests are routed to the correct client session that initiated the tool execution.
@@ -1019,7 +1036,44 @@ type ElicitResult = {
 }
 ```
 
+## Authentication Context
+
+Tools can access request metadata via `options.extra` when using HTTP-based transports:
+
+```typescript
+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 ${options.extra.authInfo.token}` },
+    signal: options.extra.signal,
+  });
+  
+  return response.json();
+}
+```
+
+The `extra` object contains:
+- `authInfo`: Authentication info (when provided by server middleware)
+- `sessionId`: Session identifier  
+- `signal`: AbortSignal for cancellation
+- `sendNotification`/`sendRequest`: MCP protocol functions
+
+> Note: To enable authentication, your HTTP server needs middleware that populates `req.auth` before calling `server.startHTTP()`. For example:
+> ```typescript
+> httpServer.createServer((req, res) => {
+>   // Add auth middleware
+>   req.auth = validateAuthToken(req.headers.authorization);
+>   
+>   // Then pass to MCP server
+>   await server.startHTTP({ url, httpPath, req, res });
+> });
+> ```
+
 ## Related Information
 
 - For connecting to MCP servers in Mastra, see the [MCPClient documentation](./mcp-client).
-- For more about the Model Context Protocol, see the [@modelcontextprotocol/sdk documentation](https://github.com/modelcontextprotocol/typescript-sdk).
+- For more about the Model Context Protocol, see the [@modelcontextprotocol/sdk documentation](https://github.com/modelcontextprotocol/typescript-sdk).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.8",
+  "version": "0.13.9-alpha.1",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -32,7 +32,7 @@
     "uuid": "^11.1.0",
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.5",
-    "@mastra/core": "0.12.1",
+    "@mastra/core": "0.13.0-alpha.1",
     "@mastra/mcp": "^0.10.9"
   },
   "devDependencies": {
@@ -48,8 +48,8 @@
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@mastra/core": "0.12.1",
-    "@internal/lint": "0.0.25"
+    "@internal/lint": "0.0.26",
+    "@mastra/core": "0.13.0-alpha.1"
   },
   "scripts": {
     "prepare-docs": "cross-env PREPARE=true node dist/prepare-docs/prepare.js",