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

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