@mastra/mcp-docs-server 1.1.17-alpha.1 → 1.1.17-alpha.11

package/.docs/docs/evals/built-in-scorers.md

@@ -18,6 +18,7 @@ These scorers evaluate how correct, truthful, and complete your agent's answers
 - [`content-similarity`](https://mastra.ai/reference/evals/content-similarity): Measures textual similarity using character-level matching (`0-1`, higher is better)
 - [`textual-difference`](https://mastra.ai/reference/evals/textual-difference): Measures textual differences between strings (`0-1`, higher means more similar)
 - [`tool-call-accuracy`](https://mastra.ai/reference/evals/tool-call-accuracy): Evaluates whether the LLM selects the correct tool from available options (`0-1`, higher is better)
+- [`trajectory-accuracy`](https://mastra.ai/reference/evals/trajectory-accuracy): Evaluates whether an agent follows the expected sequence of actions (tool calls, model generations, workflow steps, and other span types) (`0-1`, higher is better)
 - [`prompt-alignment`](https://mastra.ai/reference/evals/prompt-alignment): Measures how well agent responses align with user prompt intent, requirements, completeness, and format (`0-1`, higher is better)
 
 ### Context quality

package/.docs/docs/memory/observational-memory.md

@@ -150,17 +150,19 @@ const memory = new Memory({
       observation: {
         model: new ModelByInputTokens({
           upTo: {
-            10_000: 'google/gemini-2.5-flash', // Fast and cheap for small inputs
-            40_000: 'openai/gpt-4o', // Stronger for medium inputs
-            1_000_000: 'openai/gpt-4.5', // Most capable for very large inputs
+            // Faster, cheaper models for smaller inputs; stronger models for larger contexts
+            5_000: 'openrouter/mistralai/ministral-8b-2512',
+            20_000: 'openrouter/mistralai/mistral-small-2603',
+            40_000: 'openai/gpt-5.4-mini',
+            1_000_000: 'google/gemini-3.1-flash-lite-preview',
           },
         }),
       },
       reflection: {
         model: new ModelByInputTokens({
           upTo: {
-            20_000: 'google/gemini-2.5-flash',
-            80_000: 'openai/gpt-4o',
+            20_000: 'openai/gpt-5.4-mini',
+            100_000: 'google/gemini-2.5-flash',
           },
         }),
       },

package/.docs/docs/observability/tracing/bridges/otel.md

@@ -151,10 +151,10 @@ With the OtelBridge, your traces maintain proper hierarchy across OTEL and Mastr
 ```text
 HTTP POST /api/chat (from Hono middleware)
 └── agent.assistant (from Mastra via OtelBridge)
-    ├── chat gpt-4o (LLM call)
+    ├── chat gpt-5.4 (LLM call)
     ├── tool.execute search (tool execution)
     │   └── HTTP GET api.example.com (from OTEL auto-instrumentation)
-    └── chat gpt-4o (follow-up LLM call)
+    └── chat gpt-5.4 (follow-up LLM call)
 ```
 
 ## Multi-service distributed tracing
@@ -167,7 +167,7 @@ Service A: HTTP POST /api/process
 
 Service B: HTTP POST /api/analyze (incoming call - same trace!)
 └── agent.analyzer (Mastra agent inherits trace context)
-    └── chat gpt-4o
+    └── chat gpt-5.4
 ```
 
 Both services must have:

package/.docs/docs/observability/tracing/exporters/sentry.md

@@ -162,7 +162,7 @@ The exporter uses standard GenAI semantic conventions with Sentry-specific attri
 **For MODEL\_GENERATION spans:**
 
 - `gen_ai.system`: Model provider (e.g., `openai`, `anthropic`)
-- `gen_ai.request.model`: Model identifier (e.g., `gpt-4`)
+- `gen_ai.request.model`: Model identifier (e.g., `gpt-5.4`)
 - `gen_ai.response.model`: Response model
 - `gen_ai.response.text`: Output text response
 - `gen_ai.response.tool_calls`: Tool calls made during generation (JSON array)

package/.docs/docs/server/auth/okta.md

@@ -0,0 +1,225 @@
+# Okta
+
+The `@mastra/auth-okta` package provides authentication and role-based access control for Mastra using Okta. It supports an OAuth 2.0 / OIDC login flow with encrypted session cookies and maps Okta groups to Mastra permissions.
+
+## Prerequisites
+
+This guide uses Okta authentication. Make sure to:
+
+1. Create an Okta account at [okta.com](https://www.okta.com/)
+2. Set up an OAuth application in the Okta Admin Console (Web app, Authorization Code grant)
+3. Add your redirect URI to the application's sign-in redirect URIs
+4. Create an API token (required for RBAC)
+
+Make sure your environment variables are set.
+
+```env
+OKTA_DOMAIN=dev-123456.okta.com
+OKTA_CLIENT_ID=your-client-id
+OKTA_CLIENT_SECRET=your-client-secret
+OKTA_REDIRECT_URI=http://localhost:4111/api/auth/callback
+OKTA_COOKIE_PASSWORD=a-random-string-at-least-32-characters-long
+OKTA_API_TOKEN=your-api-token
+```
+
+> **Note:** `OKTA_COOKIE_PASSWORD` encrypts session cookies. If omitted, an auto-generated value is used that does not survive server restarts. Set it explicitly for production.
+>
+> `OKTA_API_TOKEN` is only required when using `MastraRBACOkta` to map Okta groups to permissions.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/auth-okta
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/auth-okta
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/auth-okta
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/auth-okta
+```
+
+## Usage examples
+
+### Basic usage with environment variables
+
+With the environment variables above set, all constructor parameters are optional:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthOkta } from '@mastra/auth-okta'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthOkta(),
+  },
+})
+```
+
+### Auth with RBAC
+
+Add `MastraRBACOkta` to map Okta groups to Mastra permissions:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthOkta, MastraRBACOkta } from '@mastra/auth-okta'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthOkta(),
+    rbac: new MastraRBACOkta({
+      roleMapping: {
+        Admin: ['*'],
+        Engineering: ['agents:*', 'workflows:*', 'tools:*'],
+        Viewer: ['agents:read', 'workflows:read'],
+        _default: [], // users with unmapped groups get no permissions
+      },
+    }),
+  },
+})
+```
+
+### Cross-provider usage
+
+Use a different auth provider (Auth0, Clerk, etc.) for login and Okta for RBAC. Pass a `getUserId` function to resolve the Okta user ID from the other provider's user object:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthAuth0 } from '@mastra/auth-auth0'
+import { MastraRBACOkta } from '@mastra/auth-okta'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthAuth0(),
+    rbac: new MastraRBACOkta({
+      getUserId: user => user.metadata?.oktaUserId || user.email,
+      roleMapping: {
+        Engineering: ['agents:*', 'workflows:*'],
+        Admin: ['*'],
+        _default: [],
+      },
+    }),
+  },
+})
+```
+
+> **Note:** To link users between providers, store the Okta user ID in the other provider's user metadata. Mastra uses this ID to fetch groups from Okta.
+
+> **Info:** Visit [MastraAuthOkta](https://mastra.ai/reference/auth/okta) for all available configuration options.
+
+## Role mapping
+
+The `roleMapping` option maps Okta group names to arrays of Mastra permission strings. Permissions follow a `resource:action` pattern and support wildcards:
+
+```typescript
+const rbac = new MastraRBACOkta({
+  roleMapping: {
+    // full access to everything
+    Admin: ['*'],
+
+    // full access to agents and workflows
+    Engineering: ['agents:*', 'workflows:*'],
+
+    // read-only access
+    Viewer: ['agents:read', 'workflows:read'],
+
+    // users whose groups don't match any key above
+    _default: [],
+  },
+})
+```
+
+The `_default` key assigns permissions to users whose Okta groups do not match any other key.
+
+## Client-side setup
+
+When auth is enabled, requests to Mastra routes require authentication. `MastraAuthOkta` uses SSO, so users authenticate through Okta's hosted login page. After login, an encrypted session cookie is set automatically.
+
+### Cookie session (recommended)
+
+For cross-origin requests (e.g. a frontend on `:3000` calling Mastra on `:4111`), enable CORS credentials on the Mastra server:
+
+```typescript
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthOkta(),
+    cors: {
+      origin: 'http://localhost:3000',
+      credentials: true,
+    },
+  },
+})
+```
+
+Configure the client to include credentials:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+export const mastraClient = new MastraClient({
+  baseUrl: 'http://localhost:4111',
+  credentials: 'include',
+})
+```
+
+### Bearer token
+
+You can also pass an Okta access token as a Bearer token. The token is verified against Okta's JWKS endpoint:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+export const createMastraClient = (accessToken: string) => {
+  return new MastraClient({
+    baseUrl: 'http://localhost:4111',
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+    },
+  })
+}
+```
+
+> **Info:** Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
+
+### Making authenticated requests
+
+**MastraClient**:
+
+```typescript
+import { mastraClient } from '../lib/mastra-client'
+
+const agent = mastraClient.getAgent('weatherAgent')
+const response = await agent.generate('Weather in London')
+console.log(response)
+```
+
+**cURL**:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-okta-access-token>" \
+  -d '{
+    "messages": "Weather in London"
+  }'
+```
+
+## Troubleshooting
+
+- **401 on every request**: Verify your Okta domain, client ID, and client secret are correct. Check that the redirect URI in your Okta application matches `OKTA_REDIRECT_URI`.
+- **Cookies not sent cross-origin**: Set `credentials: "include"` in `MastraClient` and configure `server.cors` with your frontend origin and `credentials: true`.
+- **Session lost on restart**: Set `OKTA_COOKIE_PASSWORD` to a stable value (at least 32 characters). Without it, an auto-generated key is used that changes on each restart.
+- **RBAC returns empty permissions**: Verify `OKTA_API_TOKEN` is set and the token has permission to list user groups. Check that group names in `roleMapping` match your Okta group names exactly.

package/.docs/docs/server/auth.md

@@ -30,6 +30,7 @@ See [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes) for con
 - [Better Auth](https://mastra.ai/docs/server/auth/better-auth)
 - [Clerk](https://mastra.ai/docs/server/auth/clerk)
 - [Firebase](https://mastra.ai/docs/server/auth/firebase)
+- [Okta](https://mastra.ai/docs/server/auth/okta)
 - [Supabase](https://mastra.ai/docs/server/auth/supabase)
 - [WorkOS](https://mastra.ai/docs/server/auth/workos)
 

package/.docs/docs/workspace/lsp.md

@@ -0,0 +1,116 @@
+# LSP inspection
+
+**Added in:** `@mastra/core@1.1.0`
+
+LSP inspection gives workspace-backed agents semantic code intelligence. When you enable LSP on a workspace, agents can inspect symbols in supported files to retrieve hover information, jump to definitions, and find implementations.
+
+## When to use LSP inspection
+
+Use LSP inspection when your agent needs semantic code understanding instead of plain-text search alone:
+
+- Inspect TypeScript or JavaScript symbols and their inferred types
+- Find where a symbol is declared before editing related code
+- Explore implementations across a codebase without manually tracing every file
+- Combine semantic inspection with `view` and `search_content` for faster navigation
+
+## Basic usage
+
+Enable LSP on a workspace by setting `lsp: true`:
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
+  lsp: true,
+})
+```
+
+With this configuration, the workspace registers the default LSP inspection tool alongside the configured filesystem and sandbox tools.
+
+## Agent tool
+
+When LSP is enabled, the workspace exposes `mastra_workspace_lsp_inspect` by default.
+
+```json
+{
+  "path": "/absolute/path/to/file.ts",
+  "line": 10,
+  "match": "const foo = <<<bar()"
+}
+```
+
+The `match` field must include exactly one `<<<` cursor marker. The marker identifies the symbol position on the specified line.
+
+The tool returns up to three result groups:
+
+| Result           | Description                                                      |
+| ---------------- | ---------------------------------------------------------------- |
+| `hover`          | Type information or documentation for the symbol at the cursor   |
+| `diagnostics`    | Line-scoped LSP diagnostics for the inspected line, when present |
+| `definition`     | Declaration locations with a one-line preview                    |
+| `implementation` | Implementation or usage locations                                |
+
+## Tool name remapping
+
+Rename the tool if your agent expects a shorter name:
+
+```typescript
+import { Workspace, LocalFilesystem, WORKSPACE_TOOLS } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  lsp: true,
+  tools: {
+    [WORKSPACE_TOOLS.LSP.LSP_INSPECT]: {
+      name: 'lsp_inspect',
+    },
+  },
+})
+```
+
+This changes the exposed tool name only. The configuration key stays `WORKSPACE_TOOLS.LSP.LSP_INSPECT`.
+
+## LSP configuration
+
+Set `lsp` to `true` for default behavior, or provide an object to customize server startup and diagnostics:
+
+```typescript
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  lsp: {
+    diagnosticTimeout: 4000,
+    initTimeout: 8000,
+    disableServers: ['pyright'],
+    binaryOverrides: {
+      typescript: '/custom/path/to/typescript-language-server',
+    },
+    searchPaths: ['/opt/homebrew/bin'],
+  },
+})
+```
+
+Use custom configuration when you need to:
+
+- Increase timeouts for large repositories
+- Disable specific language servers
+- Point Mastra at custom language server binaries
+- Add extra binary search paths in constrained environments
+
+## Requirements and limitations
+
+- LSP inspection only works for file types with a matching language server
+- The `path` you inspect must resolve inside the workspace filesystem or allowed paths
+- External package inspection may resolve to declaration files such as `.d.ts` instead of runtime source files
+- `lsp_inspect` complements `view` and `search_content`, but does not replace reading implementation code when you need full context
+
+## Related
+
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Filesystem](https://mastra.ai/docs/workspace/filesystem)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Search and indexing](https://mastra.ai/docs/workspace/search)
+- [Workspace class reference](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/docs/workspace/overview.md

@@ -8,9 +8,14 @@ A workspace supports the following features:
 
 - **[Filesystem](https://mastra.ai/docs/workspace/filesystem)**: File storage (read, write, list, delete, copy, move, grep)
 - **[Sandbox](https://mastra.ai/docs/workspace/sandbox)**: Command execution (shell commands) and background processes
+- **[LSP inspection](https://mastra.ai/docs/workspace/lsp)**: Hover, definition, and implementation queries through language servers
 - **[Search](https://mastra.ai/docs/workspace/search)**: BM25, vector, or hybrid search over indexed content
 - **[Skills](https://mastra.ai/docs/workspace/skills)**: Reusable instructions for agents
 
+## When to use workspaces
+
+Use a workspace when your agent needs access to the local filesystem, shell commands, semantic code inspection, indexed search, or reusable skill instructions.
+
 ## How it works
 
 When you assign a workspace to an agent, Mastra includes the corresponding tools in the agent's toolset. The agent can then use these tools to interact with files and execute commands.
@@ -208,16 +213,24 @@ import { Workspace, LocalFilesystem, LocalSandbox, WORKSPACE_TOOLS } from '@mast
 const workspace = new Workspace({
   filesystem: new LocalFilesystem({ basePath: './workspace' }),
   sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
+  lsp: true,
   tools: {
     [WORKSPACE_TOOLS.FILESYSTEM.READ_FILE]: { name: 'view' },
     [WORKSPACE_TOOLS.FILESYSTEM.GREP]: { name: 'search_content' },
     [WORKSPACE_TOOLS.FILESYSTEM.LIST_FILES]: { name: 'find_files' },
     [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: { name: 'execute_command' },
+    [WORKSPACE_TOOLS.LSP.LSP_INSPECT]: { name: 'lsp_inspect' },
   },
 })
 ```
 
-The agent sees `view`, `search_content`, `find_files`, and `execute_command` instead of the default `mastra_workspace_*` names. Tool names must be unique — duplicate names or conflicts with other default names throw an error.
+The agent sees `view`, `search_content`, `find_files`, `execute_command`, and `lsp_inspect` instead of the default `mastra_workspace_*` names. Tool names must be unique — duplicate names or conflicts with other default names throw an error.
+
+## LSP inspection
+
+Enable `lsp` on a workspace to add semantic code inspection through language servers. This adds the `mastra_workspace_lsp_inspect` tool by default, which can return hover information, definition locations, and implementations for a symbol at a specific cursor position.
+
+See [LSP inspection](https://mastra.ai/docs/workspace/lsp) for configuration, examples, and tool name remapping.
 
 ### Output truncation
 
@@ -294,6 +307,7 @@ External providers may perform additional setup like establishing connections or
 
 - [Filesystem](https://mastra.ai/docs/workspace/filesystem)
 - [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [LSP inspection](https://mastra.ai/docs/workspace/lsp)
 - [Skills](https://mastra.ai/docs/workspace/skills)
 - [Search and indexing](https://mastra.ai/docs/workspace/search)
 - [Workspace class reference](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/guides/agent-frameworks/ai-sdk.md

@@ -56,7 +56,7 @@ const loggingProcessor: Processor<'logger'> = {
   },
 }
 
-const model = withMastra(openai('gpt-4o'), {
+const model = withMastra(openai('gpt-5.4'), {
   inputProcessors: [loggingProcessor],
   outputProcessors: [loggingProcessor],
 })
@@ -85,7 +85,7 @@ await storage.init()
 
 const memoryStorage = await storage.getStore('memory')
 
-const model = withMastra(openai('gpt-4o'), {
+const model = withMastra(openai('gpt-5.4'), {
   memory: {
     storage: memoryStorage!,
     threadId: 'user-thread-123',
@@ -115,7 +115,7 @@ await storage.init()
 
 const memoryStorage = await storage.getStore('memory')
 
-const model = withMastra(openai('gpt-4o'), {
+const model = withMastra(openai('gpt-5.4'), {
   inputProcessors: [myGuardProcessor],
   outputProcessors: [myLoggingProcessor],
   memory: {

package/.docs/models/gateways/openrouter.md

@@ -1,6 +1,6 @@
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 164 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 165 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -103,6 +103,7 @@ ANTHROPIC_API_KEY=ant-...
 | `mistralai/devstral-small-2507`                                 |
 | `mistralai/mistral-medium-3`                                    |
 | `mistralai/mistral-medium-3.1`                                  |
+| `mistralai/mistral-small-2603`                                  |
 | `mistralai/mistral-small-3.1-24b-instruct`                      |
 | `mistralai/mistral-small-3.2-24b-instruct`                      |
 | `moonshotai/kimi-k2`                                            |

package/.docs/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3391 models from 94 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3595 models from 95 providers through a single API.
 
 ## Features