@mastra/mcp-docs-server 1.2.8-alpha.9 → 1.2.8

package/.docs/reference/tools/create-tool.md

@@ -10,25 +10,29 @@ The `createTool()` function is used to define custom tools that your Mastra agen
 import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
-export const tool = createTool({
-  id: 'test-tool',
-  description: 'Reverse the input string',
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   inputSchema: z.object({
-    input: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    output: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async inputData => {
-    const reversed = inputData.input.split('').reverse().join('')
-
+  execute: async ({ location }) => {
     return {
-      output: reversed,
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
 ```
 
+The first `execute` parameter is the validated value from `inputSchema`. Destructure schema fields directly in the function signature, as shown with `{ location }`. The optional second parameter contains the execution context.
+
 ## Parameters
 
 **id** (`string`): A unique identifier for the tool.
@@ -112,10 +116,12 @@ export const weatherTool = createTool({
     location: z.string(),
   }),
   outputSchema: z.object({
-    weather: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -137,11 +143,13 @@ export const weatherTool = createTool({
   ),
   outputSchema: toStandardJsonSchema(
     v.object({
-      weather: v.string(),
+      location: v.string(),
+      temperatureCelsius: v.number(),
+      conditions: v.string(),
     }),
   ),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -159,10 +167,12 @@ export const weatherTool = createTool({
     location: 'string',
   }),
   outputSchema: type({
-    weather: 'string',
+    location: 'string',
+    temperatureCelsius: 'number',
+    conditions: 'string',
   }),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -176,18 +186,22 @@ import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
 export const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get weather for a city',
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   strict: true,
   inputSchema: z.object({
-    city: z.string(),
-    units: z.enum(['metric', 'imperial']),
+    location: z.string(),
+  }),
+  outputSchema: z.object({
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async ({ city, units }) => {
+  execute: async ({ location }) => {
     return {
-      city,
-      units,
-      forecast: 'sunny',
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
@@ -204,28 +218,31 @@ import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
 export const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get weather for a city',
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    city: z.string(),
-    temperature: z.number(),
-    condition: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
     radarImageUrl: z.string().url(),
   }),
-  execute: async ({ city }) => ({
-    city,
-    temperature: 72,
-    condition: 'sunny',
+  execute: async ({ location }) => ({
+    location,
+    temperatureCelsius: 21,
+    conditions: 'sunny',
     radarImageUrl: 'https://example.com/radar/seattle.png',
   }),
   toModelOutput: output => {
     return {
       type: 'content',
       value: [
-        { type: 'text', text: `${output.city}: ${output.temperature}F and ${output.condition}` },
+        {
+          type: 'text',
+          text: `${output.location}: ${output.temperatureCelsius}°C and ${output.conditions}`,
+        },
         { type: 'image-url', url: output.radarImageUrl },
       ],
     }
@@ -294,11 +311,16 @@ import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
 export const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get current weather for a location',
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   inputSchema: z.object({
     location: z.string().describe('City name or coordinates'),
   }),
+  outputSchema: z.object({
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
+  }),
   // MCP-specific properties
   mcp: {
     // Annotations for client behavior hints
@@ -315,9 +337,11 @@ export const weatherTool = createTool({
       category: 'weather',
     },
   },
-  execute: async inputData => {
+  execute: async ({ location }) => {
     return {
-      weather: `Current weather for ${inputData.location}: sunny`,
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
@@ -334,19 +358,21 @@ import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
 export const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get weather for a city',
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    city: z.string(),
-    forecast: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async ({ city }) => {
+  execute: async ({ location }) => {
     return {
-      city,
-      forecast: 'sunny',
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
   onInputStart: ({ toolCallId }) => {
@@ -356,10 +382,10 @@ export const weatherTool = createTool({
     console.log(`Tool call ${toolCallId} received input chunk: ${inputTextDelta}`)
   },
   onInputAvailable: ({ input, toolCallId }) => {
-    console.log(`Tool call ${toolCallId} received city: ${input.city}`)
+    console.log(`Tool call ${toolCallId} received location: ${input.location}`)
   },
   onOutput: ({ output, toolCallId, toolName }) => {
-    console.log(`Tool ${toolName} call ${toolCallId} returned forecast: ${output.forecast}`)
+    console.log(`Tool ${toolName} call ${toolCallId} returned conditions: ${output.conditions}`)
   },
 })
 ```
@@ -403,7 +429,7 @@ export const tool = createTool({
   id: 'example-tool',
   description: 'Example tool with hooks',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   onInputAvailable: ({ input, toolCallId, messages, abortSignal }) => {
     console.log(`Tool received complete input:`, input)

package/.docs/reference/tools/mcp-client.md

@@ -280,9 +280,7 @@ This is useful for connecting external MCP servers that implement the MCP Apps e
 The `MCPClient` instance has a `resources` property that provides access to resource-related operations.
 
 ```typescript
-const mcpClient = new MCPClient({
-  /* ...servers configuration... */
-})
+const mcpClient = new MCPClient({/* ...servers configuration... */})
 
 // Access resource methods via mcpClient.resources
 const allResourcesByServer = await mcpClient.resources.list()
@@ -411,9 +409,7 @@ mcpClient.resources.onListChanged('myWeatherServer', () => {
 The `MCPClient` instance has an `elicitation` property that provides access to elicitation-related operations. Elicitation allows MCP servers to request structured information from users.
 
 ```typescript
-const mcpClient = new MCPClient({
-  /* ...servers configuration... */
-})
+const mcpClient = new MCPClient({/* ...servers configuration... */})
 
 // Set up elicitation handler
 mcpClient.elicitation.onRequest('serverName', async request => {
@@ -552,9 +548,7 @@ await mcpClient.elicitation.onRequest('interactiveServer', async request => {
 The `MCPClient` instance has a `prompts` property that provides access to prompt-related operations.
 
 ```typescript
-const mcpClient = new MCPClient({
-  /* ...servers configuration... */
-})
+const mcpClient = new MCPClient({/* ...servers configuration... */})
 
 // Access prompt methods via mcpClient.prompts
 const allPromptsByServer = await mcpClient.prompts.list()
@@ -980,9 +974,7 @@ class DatabaseOAuthStorage implements OAuthStorage {
 
 const provider = new MCPOAuthClientProvider({
   redirectUrl: 'http://localhost:3000/callback',
-  clientMetadata: {
-    /* ... */
-  },
+  clientMetadata: {/* ... */},
   storage: new DatabaseOAuthStorage(db, 'user-123'),
 })
 ```
@@ -1117,33 +1109,25 @@ For example, if you try to create multiple instances with the same configuration
 ```typescript
 // First instance - OK
 const mcp1 = new MCPClient({
-  servers: {
-    /* ... */
-  },
+  servers: {/* ... */},
 })
 
 // Second instance with same config - Will throw an error
 const mcp2 = new MCPClient({
-  servers: {
-    /* ... */
-  },
+  servers: {/* ... */},
 })
 
 // To fix, either:
 // 1. Add unique IDs
 const mcp3 = new MCPClient({
   id: 'instance-1',
-  servers: {
-    /* ... */
-  },
+  servers: {/* ... */},
 })
 
 // 2. Or disconnect before recreating
 await mcp1.disconnect()
 const mcp4 = new MCPClient({
-  servers: {
-    /* ... */
-  },
+  servers: {/* ... */},
 })
 ```
 

package/.docs/reference/tools/mcp-server.md

@@ -187,9 +187,7 @@ const server = new MCPServer({
   id: 'my-server',
   name: 'My Server',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
 })
 await server.startStdio()
 ```
@@ -353,9 +351,7 @@ const server = new MCPServer({
   id: 'my-serverless-mcp',
   name: 'My Serverless MCP',
   version: '1.0.0',
-  tools: {
-    /* your tools */
-  },
+  tools: {/* your tools */},
 })
 
 serve(async req => {
@@ -637,9 +633,7 @@ const serverWithResources = new MCPServer({
   id: 'resourceful-server',
   name: 'Resourceful Server',
   version: '1.0.0',
-  tools: {
-    /* ... your tools ... */
-  },
+  tools: {/* ... your tools ... */},
   resources: myResourceHandlers,
 })
 ```
@@ -768,9 +762,7 @@ const serverWithPrompts = new MCPServer({
   id: 'promptful-server',
   name: 'Promptful Server',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
   prompts: myPromptHandlers,
 })
 ```
@@ -966,9 +958,7 @@ execute: async (inputData, context) => {
   // Use elicitation capabilities
   const result = await context.mcp.elicitation.sendRequest({
     message: 'Please provide information',
-    requestedSchema: {
-      /* schema */
-    },
+    requestedSchema: {/* schema */},
   })
 
   return result
@@ -1159,9 +1149,7 @@ const mcpServer = new MCPServer({
   id: 'protected-server',
   name: 'Protected MCP Server',
   version: '1.0.0',
-  tools: {
-    /* your tools */
-  },
+  tools: {/* your tools */},
 })
 
 // Create OAuth middleware
@@ -1342,21 +1330,48 @@ To pass data to your tools, populate `req.auth` on the Node.js request object in
 ```typescript
 import express from 'express'
 
+type MCPAuthenticatedRequest = express.Request & {
+  auth?: {
+    token: string
+    clientId: string
+    scopes: string[]
+    expiresAt?: number
+    extra?: Record<string, unknown>
+  }
+}
+
 const app = express()
 
 // Auth middleware - set req.auth before the MCP handler
-app.use('/mcp', (req, res, next) => {
-  const token = req.headers.authorization?.replace('Bearer ', '')
-  const user = verifyToken(token)
-
-  // This entire object becomes context.mcp.extra.authInfo
-  // @ts-ignore - req.auth is read by the MCP SDK
-  req.auth = {
-    token,
-    userId: user.userId,
-    email: user.email,
+app.use('/mcp', async (req, res, next) => {
+  const authorization = req.headers.authorization
+
+  if (!authorization?.startsWith('Bearer ')) {
+    res.status(401).json({ error: 'Missing bearer token' })
+    return
+  }
+
+  const token = authorization.slice('Bearer '.length)
+
+  try {
+    const user = await verifyToken(token)
+
+    // This entire object becomes context.mcp.extra.authInfo
+    const authenticatedRequest = req as MCPAuthenticatedRequest
+    authenticatedRequest.auth = {
+      token,
+      clientId: user.clientId,
+      scopes: user.scopes,
+      expiresAt: user.expiresAt,
+      extra: {
+        userId: user.userId,
+        email: user.email,
+      },
+    }
+    next()
+  } catch {
+    res.status(401).json({ error: 'Invalid or expired token' })
   }
-  next()
 })
 
 app.all('/mcp', async (req, res) => {
@@ -1434,19 +1449,86 @@ The full `context.mcp.extra` object contains:
 
 ### Complete Example
 
-Here's a complete example showing the data flow from middleware to tool:
+Install [`jose`](https://github.com/panva/jose) to verify JSON Web Tokens (JWTs) against your identity provider's JSON Web Key Set (JWKS):
+
+**npm**:
+
+```shell
+npm install jose
+```
+
+**pnpm**:
+
+```shell
+pnpm add jose
+```
+
+**Yarn**:
+
+```shell
+yarn add jose
+```
+
+**Bun**:
+
+```shell
+bun add jose
+```
+
+The following example validates the token's signature, issuer, audience, algorithm, expiration, and required claims before passing its user data to the tool:
 
 ```typescript
 import express from 'express'
+import { createRemoteJWKSet, jwtVerify } from 'jose'
 import { MCPServer } from '@mastra/mcp'
 import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
-const verifyToken = (token: string) => {
-  // TODO: Implement token verification
+type MCPAuthenticatedRequest = express.Request & {
+  auth?: {
+    token: string
+    clientId: string
+    scopes: string[]
+    expiresAt?: number
+    extra?: Record<string, unknown>
+  }
+}
+
+const issuer = process.env.JWT_ISSUER
+const audience = process.env.JWT_AUDIENCE
+const jwksUri = process.env.JWT_JWKS_URI
+
+if (!issuer || !audience || !jwksUri) {
+  throw new Error('JWT_ISSUER, JWT_AUDIENCE, and JWT_JWKS_URI are required')
+}
+
+const jwks = createRemoteJWKSet(new URL(jwksUri))
+
+const verifyToken = async (token: string) => {
+  const { payload } = await jwtVerify(token, jwks, {
+    issuer,
+    audience,
+    algorithms: ['RS256'],
+    requiredClaims: ['exp'],
+  })
+
+  const clientId =
+    typeof payload.client_id === 'string'
+      ? payload.client_id
+      : typeof payload.azp === 'string'
+        ? payload.azp
+        : undefined
+
+  if (!payload.sub || typeof payload.email !== 'string' || !clientId || !payload.exp) {
+    throw new Error('Token must contain sub, email, exp, and client_id or azp claims')
+  }
+
   return {
-    userId: '123',
-    email: 'test@test.com',
+    userId: payload.sub,
+    clientId,
+    email: payload.email,
+    expiresAt: payload.exp,
+    scopes: typeof payload.scope === 'string' ? payload.scope.split(' ') : [],
   }
 }
 
@@ -1481,18 +1563,35 @@ const server = new MCPServer({
 // 3. Set up Express with auth middleware
 const app = express()
 
-app.use('/mcp', (req, res, next) => {
-  const token = req.headers.authorization?.replace('Bearer ', '')
-  const user = verifyToken(token)
+app.use('/mcp', async (req, res, next) => {
+  const authorization = req.headers.authorization
+
+  if (!authorization?.startsWith('Bearer ')) {
+    res.status(401).json({ error: 'Missing bearer token' })
+    return
+  }
 
-  // This entire object becomes context.mcp.extra.authInfo
-  // @ts-ignore - req.auth is read by the MCP SDK
-  req.auth = {
-    token,
-    userId: user.userId,
-    email: user.email,
+  const token = authorization.slice('Bearer '.length)
+
+  try {
+    const user = await verifyToken(token)
+
+    // This entire object becomes context.mcp.extra.authInfo
+    const authenticatedRequest = req as MCPAuthenticatedRequest
+    authenticatedRequest.auth = {
+      token,
+      clientId: user.clientId,
+      scopes: user.scopes,
+      expiresAt: user.expiresAt,
+      extra: {
+        userId: user.userId,
+        email: user.email,
+      },
+    }
+    next()
+  } catch {
+    res.status(401).json({ error: 'Invalid or expired token' })
   }
-  next()
 })
 
 app.all('/mcp', async (req, res) => {

package/.docs/reference/tools/tavily.md

@@ -59,7 +59,7 @@ All factory functions accept `TavilyClientOptions` from `@tavily/core`:
 
 **apiKey** (`string`): Tavily API key. Falls back to the TAVILY\_API\_KEY environment variable.
 
-**clientSource** (`string`): Attribution string sent with each request. (Default: `'mastra'`)
+**clientName** (`string`): Attribution string sent with each request in the X-Client-Name header. (Default: `'mastra'`)
 
 **apiBaseURL** (`string`): Base URL for the Tavily API.
 

package/.docs/reference/tools/vector-query-tool.md

@@ -269,6 +269,28 @@ const chromaQueryTool = createVectorQueryTool({
 - **whereDocument**: Filter by document content
 - **Use Cases**: Advanced filtering, content-based search
 
+**Turbopuffer**:
+
+### Turbopuffer Configuration
+
+```typescript
+const turbopufferQueryTool = createVectorQueryTool({
+  vectorStoreName: 'turbopuffer',
+  indexName: 'docs',
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+  databaseConfig: {
+    turbopuffer: {
+      consistency: 'eventual', // Lower latency, recently written data may not be visible yet
+    },
+  },
+})
+```
+
+**Turbopuffer Features:**
+
+- **consistency**: Choose between `strong` (default, read-your-writes) and `eventual` (lower latency)
+- **Use Cases**: Latency-sensitive queries where slightly stale data is acceptable
+
 **Multiple Configs**:
 
 ### Multiple Database Configurations

package/.docs/reference/vectors/mongodb.md

@@ -89,6 +89,8 @@ Creates a new vector index (collection) in MongoDB.
 
 **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
 
+**filterFields** (`string[]`): Metadata field names to declare as filter fields in the Atlas vectorSearch index (registered as metadata.\<field>). Queries that filter only on declared fields are pushed directly into $vectorSearch instead of pre-filtering candidate \_ids, avoiding the 16 MB BSON limit on large result sets. Filters that reference an undeclared field, or use an operator $vectorSearch does not support, fall back to the pre-filter automatically.
+
 ### `waitForIndexReady()`
 
 Waits for an index to become ready after creation. Useful when you need to ensure an index is ready before performing operations.

package/.docs/reference/vectors/turbopuffer.md

@@ -18,6 +18,8 @@ The TurbopufferVector class provides vector search using [Turbopuffer](https://t
 
 **compression** (`boolean`): Whether to compress requests and accept compressed responses. (Default: `true`)
 
+**consistency** (`'strong' | 'eventual'`): The default consistency level for queries. Can be overridden per query. "strong" guarantees queries see all data written before the query started, at the cost of higher latency. "eventual" offers lower latency, but recently written data may not be visible yet. (Default: `strong`)
+
 **schemaConfigForIndex** (`function`): A callback function that takes an index name and returns a config object for that index. This allows you to define explicit schemas per index.
 
 ## Methods
@@ -50,6 +52,8 @@ The TurbopufferVector class provides vector search using [Turbopuffer](https://t
 
 **includeVector** (`boolean`): Whether to include vectors in the results (Default: `false`)
 
+**consistency** (`'strong' | 'eventual'`): The consistency level for this query. Overrides the consistency level set in the constructor. Defaults to "strong".
+
 ### `listIndexes()`
 
 Returns an array of index names as strings.