@mastra/mcp-docs-server 1.2.13 → 1.2.14-alpha.3

package/.docs/docs/agent-controller/threads-and-state.md

@@ -1,148 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Threads and state
-
-Threads and state are how an AgentController conversation survives beyond a single exchange. A **thread** is the persistent record of a conversation, its messages and metadata, saved to storage so a user can close the app and resume the same conversation later, or switch between several conversations. **State** is structured data attached to the conversation, values like model preferences, feature flags, or progress, that agents and your UI read and write as the conversation runs.
-
-The thread and state work together: the thread is the message history, and state is the shared scratchpad alongside it.
-
-Both persist across mode switches, model changes, and restarts, so nothing is lost when a user switches from plan mode to build mode or reopens the app the next day.
-
-Thread _lifecycle_ transitions, create, switch, clone, delete, live on the AgentController because they coordinate the shared thread lock and emit events. The active thread binding and thread/message _reads_ live on the [`Session`](https://mastra.ai/docs/agent-controller/session) as `agentController.session.thread`.
-
-## Threads
-
-A thread holds one conversation's full message history. The AgentController binds the Session to one active thread at a time. Messages you send and the agent's replies are appended to that thread and saved to storage. Threads let users resume a past conversation or keep several conversations side by side, or alternatively branch one into alternatives.
-
-### Creating and selecting threads
-
-On startup, call `selectOrCreateThread()` to resume the most recent thread or create a new one:
-
-```typescript
-await agentController.init()
-const thread = await agentController.selectOrCreateThread()
-```
-
-Create a thread explicitly with a title:
-
-```typescript
-const thread = await agentController.createThread({ title: 'New conversation' })
-```
-
-### Switching threads
-
-Switch to an existing thread.
-
-The agentController aborts any in-progress generation and acquires a lock on the new thread, plus emits a `thread_changed` event:
-
-```typescript
-await agentController.switchThread({ threadId: 'thread-abc123' })
-```
-
-### Listing threads
-
-List threads for the current resource. Forked subagent threads are hidden by default:
-
-```typescript
-const threads = await agentController.session.thread.list()
-
-// Include all resources
-const allThreads = await agentController.session.thread.list({ allResources: true })
-```
-
-### Cloning threads
-
-Clone a thread to create a branch of the conversation. The agentController copies all messages and switches to the clone:
-
-```typescript
-const cloned = await agentController.cloneThread({ title: 'Alternative approach' })
-```
-
-### Thread locking
-
-Pass a `threadLock` to the AgentController constructor to prevent concurrent access from multiple processes. The lock is acquired before any thread operation and released on switch or delete:
-
-```typescript
-const agentController = new AgentController({
-  id: 'my-agent',
-  threadLock: {
-    acquire: async threadId => {
-      /* acquire lock or throw */
-    },
-    release: async threadId => {
-      /* release lock */
-    },
-  },
-})
-```
-
-## State
-
-Where a thread stores the conversation's messages, state stores structured values that describe the conversation but aren't messages, model preferences, feature flags, UI settings, or progress markers. Agents can read and update state during a run, and your UI can react to changes, so state is how the agent and the interface stay in sync on shared facts. You define its shape with a schema, and every update is validated against that schema before it's applied.
-
-### Defining a state schema
-
-Pass a `stateSchema` (Standard JSON Schema) to validate state and extract defaults:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { AgentController } from '@mastra/core/agent-controller'
-import { z } from 'zod'
-
-const agent = new Agent({
-  id: 'assistant',
-  name: 'assistant',
-  instructions: 'Help the user manage a stateful session.',
-  model: 'openai/gpt-5.6-sol',
-})
-
-const agentController = new AgentController({
-  id: 'stateful-agent',
-  agent,
-  modes: [{ id: 'default', name: 'Default', metadata: { default: true } }],
-  stateSchema: z.object({
-    currentModelId: z.string().optional(),
-    theme: z.enum(['light', 'dark']).default('dark'),
-  }),
-})
-```
-
-### Reading and writing state
-
-State is owned by the [`Session`](https://mastra.ai/docs/agent-controller/session) as `agentController.session.state`:
-
-```typescript
-// Read the current state snapshot
-const state = agentController.session.state.get()
-
-// Update state — validates against schema and emits state_changed
-await agentController.session.state.set({ theme: 'light' })
-```
-
-State changes emit a `state_changed` event with the new state and the set of changed keys.
-
-## Resource IDs
-
-Threads are scoped to a resource ID, which groups a conversation's threads by project, user, or workspace. Set it on the AgentController constructor; it defaults to the agentController `id` when omitted:
-
-```typescript
-const agentController = new AgentController({
-  id: 'my-agent',
-  resourceId: 'project-xyz',
-})
-```
-
-The resource ID is part of a conversation's identity, so you read it from the Session:
-
-```typescript
-const resourceId = agentController.session.identity.getResourceId()
-```
-
-The session also has a stable `id` and `ownerId` (read with `session.identity.getId()` and `session.identity.getOwnerId()`). Unlike the resource ID, these don't change when you switch resources, see [Session identity](https://mastra.ai/docs/agent-controller/session) for details.
-
-## Related
-
-- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
-- [Session](https://mastra.ai/docs/agent-controller/session)
-- [Modes](https://mastra.ai/docs/agent-controller/modes)
-- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class)

package/.docs/docs/agent-controller/tool-approvals.md

@@ -1,147 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Tool approvals and permissions
-
-The AgentController provides a permission system that controls which tools require user approval before execution.
-
-You can configure policies at the category level or per-tool, and grant session-wide exceptions for trusted tools.
-
-This gives agents with access to destructive or sensitive tools, file writes, command execution, API calls, a human-in-the-loop checkpoint before those tools run.
-
-## Permission policies
-
-Policies control tool behavior:
-
-- `allow`: The tool runs without prompting
-- `ask`: The tool pauses and emits a `tool_approval_required` event; the user must approve or decline
-- `deny`: The tool is blocked from execution
-
-### Setting policies
-
-Set policies per-category or per-tool. Per-tool policies take precedence over category policies:
-
-```typescript
-// Category-level: all execute tools require approval
-await agentController.session.permissions.setForCategory({ category: 'execute', policy: 'ask' })
-
-// Tool-level: this specific tool is always blocked
-await agentController.session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })
-```
-
-### Tool categories
-
-The `toolCategoryResolver` maps tool names to categories. Pass it to the AgentController constructor:
-
-```typescript
-const agentController = new AgentController({
-  id: 'my-agent',
-  toolCategoryResolver: toolName => {
-    if (toolName.includes('write') || toolName.includes('delete')) return 'edit'
-    if (toolName.includes('execute')) return 'execute'
-    return 'read'
-  },
-})
-```
-
-Built-in categories are `read`, `edit`, `execute`, `mcp`, and `other`.
-
-## Responding to approval requests
-
-When a tool's policy is `ask`, the AgentController emits a `tool_approval_required` event. Your UI should display a prompt and call `session.respondToToolApproval()`:
-
-```typescript
-agentController.subscribe(event => {
-  if (event.type === 'tool_approval_required') {
-    // Show approval UI...
-    agentController.session.respondToToolApproval({ decision: 'approve' })
-  }
-})
-```
-
-The `decision` field accepts `'approve'`, `'decline'`, or `'always_allow_category'`. When `always_allow_category` is used, the tool's category is granted for the rest of the session. Future tools in the same category are auto-approved.
-
-```typescript
-agentController.session.respondToToolApproval({ decision: 'always_allow_category' })
-```
-
-## Session grants
-
-The AgentController owns permission _policy_ (which categories require approval). The [`Session`](https://mastra.ai/docs/agent-controller/session) owns the _grants_ a user makes during a conversation. Grant a category or tool for the rest of the session so it runs without further prompting:
-
-```typescript
-// Grant all edit tools for this session
-agentController.session.grantCategory('edit')
-
-// Grant a specific tool
-agentController.session.grantTool('mastra_workspace_execute_command')
-
-// Check current grants
-const grants = agentController.session.getGrants()
-// { categories: ['edit'], tools: ['mastra_workspace_execute_command'] }
-```
-
-## Tool suspensions
-
-Interactive built-in tools (`ask_user`, `submit_plan`) use the native tool-suspension primitive instead of the approval flow. They emit a `tool_suspended` event with `toolCallId`, `toolName`, and `suspendPayload`. Resume with `respondToToolSuspension()`:
-
-```typescript
-agentController.subscribe(event => {
-  if (event.type === 'tool_suspended' && event.toolName === 'ask_user') {
-    const { question } = event.suspendPayload as { question: string }
-    // Show question to user, then resume:
-    agentController.respondToToolSuspension({
-      toolCallId: event.toolCallId,
-      resumeData: 'User response here',
-    })
-  }
-})
-```
-
-### Plan approval
-
-The `submit_plan` tool suspends via the same mechanism. Resume with an `action` field:
-
-```typescript
-// Approve the plan
-agentController.respondToToolSuspension({
-  toolCallId: event.toolCallId,
-  resumeData: { action: 'approved' },
-})
-
-// Reject with feedback
-agentController.respondToToolSuspension({
-  toolCallId: event.toolCallId,
-  resumeData: { action: 'rejected', feedback: 'Needs more detail' },
-})
-```
-
-## Built-in tools
-
-The AgentController provides these built-in tools to agents in every mode:
-
-| Tool            | Description                                                         |
-| --------------- | ------------------------------------------------------------------- |
-| `ask_user`      | Ask the user a question (free text, single-select, or multi-select) |
-| `submit_plan`   | Submit a plan for user review and approval                          |
-| `task_write`    | Create or replace a structured task list                            |
-| `task_update`   | Update one tracked task by ID                                       |
-| `task_complete` | Mark one tracked task completed                                     |
-| `task_check`    | Check task list completion status                                   |
-| `subagent`      | Spawn a focused subagent (requires `subagents` config)              |
-
-Disable specific built-in tools with `disableBuiltinTools`:
-
-```typescript
-const agentController = new AgentController({
-  id: 'no-plans',
-  disableBuiltinTools: ['submit_plan'],
-})
-```
-
-## Related
-
-- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
-- [Session](https://mastra.ai/docs/agent-controller/session)
-- [Subagents](https://mastra.ai/docs/agent-controller/subagents)
-- [Agent approval](https://mastra.ai/docs/agents/agent-approval)
-- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class)

package/.docs/docs/mcp/mcp-apps.md

@@ -1,306 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# MCP Apps
-
-The [MCP Apps extension](https://github.com/modelcontextprotocol/ext-apps) allows MCP tools to serve interactive HTML UIs via `ui://` resources. When a tool has an associated app resource, Mastra Studio renders it in a sandboxed iframe alongside the tool form or inline in agent chat.
-
-## When to use MCP Apps
-
-Use MCP Apps when a tool result is better presented as an interactive UI rather than plain text. For example:
-
-- A calculator that renders input fields and buttons for computation
-- A color picker that displays swatches and hex values
-- A form builder that captures structured user input
-- A data visualizer that renders charts
-
-## Quickstart
-
-Define app resources on your `MCPServer` by providing a `ui://` URI mapped to inline HTML or an HTML file path.
-
-```typescript
-import { MCPServer } from '@mastra/mcp'
-import { createTool } from '@mastra/core/tools'
-import { z } from 'zod'
-
-const calculatorTool = createTool({
-  id: 'calculatorWithUI',
-  description: 'An interactive calculator',
-  inputSchema: z.object({
-    num1: z.number(),
-    num2: z.number(),
-    operation: z.enum(['add', 'subtract']),
-  }),
-  execute: async ({ num1, num2, operation }) => {
-    const result = operation === 'add' ? num1 + num2 : num1 - num2
-    return {
-      content: [{ type: 'text', text: 'An interactive calculator is displayed.' }],
-      structuredContent: { result },
-    }
-  },
-})
-
-const server = new MCPServer({
-  id: 'my-app-server',
-  name: 'My App Server',
-  version: '1.0.0',
-  tools: { calculatorTool },
-  appResources: {
-    'ui://calculator/main': {
-      name: 'Interactive Calculator',
-      html: `<html>
-        <body>
-          <h2>Calculator</h2>
-          <button id="btn">Compute</button>
-          <script type="module">
-            import { App } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/ext-apps/+esm';
-            const app = new App({ name: 'Calculator', version: '1.0.0' });
-            app.ontoolinput = (params) => {
-              console.log('Tool input:', params.arguments);
-            };
-            document.getElementById('btn').addEventListener('click', async () => {
-              const result = await app.callServerTool({
-                name: 'calculatorWithUI',
-                arguments: { num1: 10, num2: 5, operation: 'add' }
-              });
-              document.body.innerHTML += '<p>Result: ' + JSON.stringify(result) + '</p>';
-            });
-            await app.connect();
-          </script>
-        </body>
-      </html>`,
-    },
-  },
-})
-```
-
-Link the tool to its app resource by adding `_meta.ui.resourceUri` to the tool definition:
-
-```typescript
-calculatorTool._meta = {
-  ui: { resourceUri: 'ui://calculator/main' },
-}
-```
-
-Visit [MCPServer reference](https://mastra.ai/reference/tools/mcp-server) for the full `appResources` configuration.
-
-## Connecting MCP Apps to agents
-
-Agents consume tools, they don't need to know about MCP servers. Pass tools to the agent's `tools` config, and register the MCP server at the Mastra level so Studio can resolve app resources.
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { calculatorTool } from '../mcp/tools'
-
-export const myAgent = new Agent({
-  id: 'my-agent',
-  name: 'My Agent',
-  instructions: 'You have access to interactive UI tools.',
-  model: 'openai/gpt-5-mini',
-  tools: { calculatorTool },
-})
-```
-
-Register the MCP server at the Mastra level. Studio scans registered MCP servers to map tools to their app resources.
-
-```typescript
-import { Mastra } from '@mastra/core/mastra'
-import { myAgent } from './agents'
-import { myAppServer } from './mcp/server'
-
-export const mastra = new Mastra({
-  agents: { myAgent },
-  mcpServers: { myAppServer },
-})
-```
-
-For remote MCP servers, use `MCPClient.listTools()` to get tools and `toMCPServerProxies()` to register the server:
-
-```typescript
-import { MCPClient } from '@mastra/mcp'
-
-const mcpClient = new MCPClient({
-  servers: {
-    remoteApp: { url: new URL('https://remote-mcp-server.example.com/mcp') },
-  },
-})
-
-const myAgent = new Agent({
-  id: 'my-agent',
-  name: 'My Agent',
-  model: 'openai/gpt-5-mini',
-  tools: await mcpClient.listTools(),
-})
-
-export const mastra = new Mastra({
-  agents: { myAgent },
-  mcpServers: { ...mcpClient.toMCPServerProxies() },
-})
-```
-
-When tools come from `MCPClient.listTools()`, each tool's `_meta.ui` is automatically stamped with a `serverId` so Studio can resolve its app resources without scanning all servers.
-
-## How MCP Apps work
-
-MCP Apps follow a specific communication pattern between the host (Mastra Studio) and the iframe:
-
-1. The tool executes and returns a brief summary in `content` (visible to the model) and detailed data in `structuredContent` (visible to the UI only).
-2. The host renders the app HTML in a sandboxed iframe.
-3. The iframe communicates with the host via a JSON-RPC postMessage protocol.
-4. The app can call server tools using `callServerTool()` and inject messages into the chat using `sendMessage()`.
-
-```text
-Agent calls tool → Tool returns brief content + structuredContent
-  → Host renders iframe with app HTML
-  → User interacts with UI
-  → UI calls callServerTool() for computation
-  → UI calls sendMessage() to inject result into chat
-```
-
-## Tool result format
-
-Tools with app resources should return two fields:
-
-- `content`: A brief text summary for the model. Keep this short so the agent doesn't parrot the full result.
-- `structuredContent`: The data payload that hydrates the UI. The model doesn't see this field.
-
-```typescript
-execute: async ({ num1, num2, operation }) => {
-  const result = operation === 'add' ? num1 + num2 : num1 - num2
-  return {
-    content: [{ type: 'text', text: 'An interactive calculator is displayed.' }],
-    structuredContent: { result },
-  }
-}
-```
-
-## App API (guest-side)
-
-MCP App HTML uses the standard [`App` class from `@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps) to communicate with the host. Import it via ESM CDN or bundle it.
-
-```javascript
-import { App } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/ext-apps/+esm'
-const app = new App({ name: 'MyApp', version: '1.0.0' })
-```
-
-### `app.callServerTool(params)`
-
-Calls an MCP server tool from within the iframe. This is useful for interactive computation without leaving the UI.
-
-```javascript
-const result = await app.callServerTool({
-  name: 'calculatorWithUI',
-  arguments: { num1: 42, num2: 8, operation: 'add' },
-})
-```
-
-### `app.sendMessage(params)`
-
-Injects a user message into the agent chat, triggering a new model turn. Use this for sharing results or requesting follow-up actions.
-
-```javascript
-await app.sendMessage({
-  role: 'user',
-  content: [{ type: 'text', text: 'The result of 42 + 8 is 50' }],
-})
-```
-
-### `app.ontoolinput`
-
-A callback that fires when the host delivers tool input data to the iframe, allowing pre-population of form fields. The `params.arguments` object contains the tool call arguments.
-
-```javascript
-app.ontoolinput = params => {
-  document.getElementById('num1').value = params.arguments.num1
-}
-```
-
-> **Preventing UI flicker:** If your app has default form values, the user may briefly see them before `ontoolinput` hydrates the correct values. To prevent this, start the body hidden and reveal it after hydration:
->
-> ```html
-> <style>
->   body {
->     opacity: 0;
->     transition: opacity 0.15s;
->   }
->   body.ready {
->     opacity: 1;
->   }
-> </style>
-> <script type="module">
->   import { App } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/ext-apps/+esm'
->   const app = new App({ name: 'MyApp', version: '1.0.0' })
->
->   app.ontoolinput = params => {
->     // Hydrate form fields from params.arguments
->     document.body.classList.add('ready')
->   }
->
->   await app.connect()
->   // Fallback: reveal after connection if no tool input arrives
->   setTimeout(() => document.body.classList.add('ready'), 150)
-> </script>
-> ```
-
-### `app.connect()`
-
-Establishes the connection to the host. Call this after registering all event handlers.
-
-```javascript
-await app.connect()
-```
-
-See the [`App` class API reference](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html) for the full list of methods, callbacks, and lifecycle hooks.
-
-## Using external MCP servers with apps
-
-External (non-Mastra) MCP servers that implement the MCP Apps extension work with Mastra via `MCPClient`. Use `listTools()` for agent tools and `toMCPServerProxies()` to register them in Studio.
-
-```typescript
-import { Mastra } from '@mastra/core/mastra'
-import { MCPClient } from '@mastra/mcp'
-import { Agent } from '@mastra/core/agent'
-
-const mcpClient = new MCPClient({
-  servers: {
-    'external-server': {
-      command: 'node',
-      args: ['path/to/external-server.js'],
-    },
-  },
-})
-
-const myAgent = new Agent({
-  id: 'my-agent',
-  name: 'My Agent',
-  model: 'openai/gpt-5-mini',
-  tools: await mcpClient.listTools(),
-})
-
-export const mastra = new Mastra({
-  agents: { myAgent },
-  mcpServers: {
-    ...mcpClient.toMCPServerProxies(),
-  },
-})
-```
-
-Visit [MCPClient reference](https://mastra.ai/reference/tools/mcp-client) for more details on proxying external servers.
-
-## Sandbox security
-
-Mastra Studio uses [`@mcp-ui/client`](https://www.npmjs.com/package/@mcp-ui/client) to render MCP App iframes through a sandbox proxy. The proxy loads app HTML via `postMessage` rather than `srcDoc`, providing additional isolation.
-
-App iframes are sandboxed with the following permissions:
-
-- `allow-scripts`: Enables JavaScript execution
-- `allow-forms`: Allows form submission
-- `allow-popups`: Permits `window.open()` and link targets
-
-The iframe doesn't have access to the parent page's DOM, cookies, or storage. All communication happens through the JSON-RPC postMessage protocol managed by `@mcp-ui/client`'s `AppRenderer` on the host side and `@modelcontextprotocol/ext-apps`'s `App` class on the guest side.
-
-## Related
-
-- [MCP overview](https://mastra.ai/docs/mcp/overview)
-- [MCPServer reference](https://mastra.ai/reference/tools/mcp-server)
-- [MCPClient reference](https://mastra.ai/reference/tools/mcp-client)
-- [MCP Apps extension spec](https://github.com/modelcontextprotocol/ext-apps)