@mastra/mcp-docs-server 1.2.6-alpha.1 → 1.2.6-alpha.2

package/.docs/docs/agents/using-tools.md

@@ -411,6 +411,94 @@ Note that for subagents, you'll see two different identifiers in stream response
 - `toolName: "agent-weather"` in tool call events — the generated tool wrapper name
 - `id: "weather-agent"` in `data-tool-agent` chunks — the subagent's actual `id` property
 
+## Built-in tools
+
+Mastra ships agent-agnostic built-in tools in `@mastra/core/tools` that add interactive and organizational capabilities to any agent.
+
+| Tool            | Purpose                                           |
+| --------------- | ------------------------------------------------- |
+| `ask_user`      | Ask the user a question and wait for their answer |
+| `submit_plan`   | Submit a plan file for user 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                 |
+
+### Ask the user a question
+
+Import [`askUserTool`](https://mastra.ai/reference/tools/ask-user-tool) and add it to the agent's toolset. The tool suspends the run, emits a `tool-call-suspended` event with the question, and resumes when you call `resumeStream()` with the user's answer.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { askUserTool } from '@mastra/core/tools'
+
+const agent = new Agent({
+  id: 'assistant',
+  name: 'Assistant',
+  instructions: 'Ask the user for clarification when the request is ambiguous.',
+  model,
+  tools: { askUserTool },
+})
+```
+
+Stream the agent and watch for `tool-call-suspended` chunks. The `suspendPayload` contains the question and optional structured choices:
+
+```typescript
+const stream = await agent.stream('Summarize my project')
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'tool-call-suspended') {
+    const { question, options } = chunk.payload.suspendPayload
+    console.log(question)
+    const answer = await getUserAnswer() // your UI logic
+    const resumed = await agent.resumeStream(answer, { runId: stream.runId })
+    for await (const c of resumed.textStream) process.stdout.write(c)
+  }
+}
+```
+
+`askUserTool` supports free-text, single-select (`options` array), and multi-select (`selectionMode: 'multi_select'`) prompts. Pair it with `autoResumeSuspendedTools` so the agent resumes automatically from the user's next chat message. See [Automatic tool resumption](https://mastra.ai/docs/agents/agent-approval) for details.
+
+### Submit a plan for review
+
+Import [`submitPlanTool`](https://mastra.ai/reference/tools/submit-plan-tool) to let the agent write a plan to a file and submit it for user review. The tool suspends the run until the user approves or rejects:
+
+```typescript
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'tool-call-suspended' && chunk.payload.toolName === 'submit_plan') {
+    const { path } = chunk.payload.suspendPayload
+    // Read and display the plan file, then resume:
+    const resumed = await agent.resumeStream({ action: 'approved' }, { runId: stream.runId })
+    for await (const c of resumed.textStream) process.stdout.write(c)
+  }
+}
+```
+
+### Task tracking
+
+The four task tools manage a structured, durable task list for an agent run. They require [Memory](https://mastra.ai/docs/memory/overview) so the list is persisted in a thread-scoped store.
+
+Add task tracking through [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider), which bundles all four tools and the `TaskStateProcessor` in a single registration:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { TaskSignalProvider } from '@mastra/core/signals'
+
+const agent = new Agent({
+  id: 'coder',
+  name: 'Coder',
+  instructions: 'Track your progress with the task tools.',
+  model,
+  memory: new Memory(),
+  signals: [new TaskSignalProvider()],
+})
+```
+
+Only one task can be `in_progress` at a time. The list is stored in the thread-scoped `threadState` storage domain and projected onto the agent's [state-signal](https://mastra.ai/docs/long-running-agents/signals) lane, so it survives observational-memory truncation. See the [Task tools reference](https://mastra.ai/reference/tools/task-tools) for full schemas.
+
+The [AgentController](https://mastra.ai/docs/agent-controller/overview) automatically includes all built-in tools in every mode — you don't need to add them manually. See [Tool approvals](https://mastra.ai/docs/agent-controller/tool-approvals) for AgentController-specific behavior.
+
 ## Related
 
 - [`createTool` reference](https://mastra.ai/reference/tools/create-tool)
@@ -420,4 +508,8 @@ Note that for subagents, you'll see two different identifiers in stream response
 - [Dynamic tool search](https://mastra.ai/reference/processors/tool-search-processor): Load tools on demand for agents with large tool libraries
 - [Tools with structured output](https://mastra.ai/docs/agents/structured-output): Model compatibility when combining tools and structured output
 - [Agent approval](https://mastra.ai/docs/agents/agent-approval)
+- [`askUserTool` reference](https://mastra.ai/reference/tools/ask-user-tool)
+- [`submitPlanTool` reference](https://mastra.ai/reference/tools/submit-plan-tool)
+- [Task tools reference](https://mastra.ai/reference/tools/task-tools)
+- [TaskSignalProvider reference](https://mastra.ai/reference/signals/task-signal-provider)
 - [Request context](https://mastra.ai/docs/server/request-context)

package/.docs/reference/index.md

@@ -272,6 +272,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.stream()](https://mastra.ai/reference/streaming/workflows/stream)
 - [.timeTravelStream()](https://mastra.ai/reference/streaming/workflows/timeTravelStream)
 - [Overview](https://mastra.ai/reference/templates/overview)
+- [askUserTool](https://mastra.ai/reference/tools/ask-user-tool)
 - [Bright Data Tools](https://mastra.ai/reference/tools/brightdata)
 - [createCodeMode()](https://mastra.ai/reference/tools/create-code-mode)
 - [createDocumentChunkerTool()](https://mastra.ai/reference/tools/document-chunker-tool)
@@ -281,6 +282,8 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [MCPClient](https://mastra.ai/reference/tools/mcp-client)
 - [MCPServer](https://mastra.ai/reference/tools/mcp-server)
 - [Perplexity Tools](https://mastra.ai/reference/tools/perplexity)
+- [submitPlanTool](https://mastra.ai/reference/tools/submit-plan-tool)
+- [Task tools](https://mastra.ai/reference/tools/task-tools)
 - [Tavily Tools](https://mastra.ai/reference/tools/tavily)
 - [Amazon S3 Vector Store](https://mastra.ai/reference/vectors/s3vectors)
 - [Astra Vector Store](https://mastra.ai/reference/vectors/astra)

package/.docs/reference/tools/ask-user-tool.md

@@ -0,0 +1,78 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# askUserTool
+
+A built-in, agent-agnostic tool that asks the user a question and waits for their response. The tool supports free-text questions, single-select prompts, and multi-select prompts.
+
+The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/agent-approval) primitive: it calls `suspend()` with the question payload, which makes the agent emit a `tool-call-suspended` event and persist run state. Resume the run with `agent.resumeStream(answer, { runId })`.
+
+When executed outside an agent run (no `suspend` available), the tool returns a readable fallback string containing the question and choices.
+
+## Usage example
+
+Add `askUserTool` to an agent's toolset:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { askUserTool } from '@mastra/core/tools'
+
+const agent = new Agent({
+  id: 'assistant',
+  name: 'Assistant',
+  instructions: 'Ask the user for clarification when the request is ambiguous.',
+  model,
+  tools: { askUserTool },
+})
+```
+
+Handle the suspension and resume:
+
+```typescript
+const stream = await agent.stream('Summarize my project')
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'tool-call-suspended') {
+    const { question, options, selectionMode } = chunk.payload.suspendPayload
+    // Present the question to the user, collect their answer, then resume:
+    const resumed = await agent.resumeStream('The main repo', { runId: stream.runId })
+    for await (const c of resumed.textStream) process.stdout.write(c)
+  }
+}
+```
+
+For multi-select prompts, resume with a string array:
+
+```typescript
+await agent.resumeStream(['Add tests', 'Update docs'], { runId: stream.runId })
+```
+
+## Input schema
+
+The model calls this tool with the following parameters:
+
+**question** (`string`): The question to ask the user. Must be non-empty.
+
+**options** (`AskUserOption[]`): Structured choices for the user. When omitted, the prompt is free-text.
+
+**options.label** (`string`): Short display text for this option. This value is returned to the model when selected.
+
+**options.description** (`string`): Explanation of what this option means.
+
+**selectionMode** (`'single_select' | 'multi_select'`): Controls how many options the user can select. Defaults to 'single\_select' when options are provided. Requires options.
+
+## Suspend payload
+
+The `tool-call-suspended` event carries a `suspendPayload` with the same shape as the input:
+
+**question** (`string`): The question being asked.
+
+**options** (`AskUserOption[]`): The structured choices, if any.
+
+**selectionMode** (`'single_select' | 'multi_select'`): The resolved selection mode. Omitted for free-text prompts.
+
+## Resume data
+
+Pass the user's answer to `agent.resumeStream()`:
+
+- **Free-text and single-select:** A `string`.
+- **Multi-select:** A `string[]` of selected option labels.

package/.docs/reference/tools/submit-plan-tool.md

@@ -0,0 +1,93 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# submitPlanTool
+
+A built-in, agent-agnostic tool that submits an implementation plan for user review. The agent writes a plan to a markdown file and passes the file path to this tool. The tool suspends the run until the user approves or rejects the plan.
+
+The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/agent-approval) primitive: it calls `suspend({ path })`, which makes the agent emit a `tool-call-suspended` event. The host reads the plan file, presents it to the user, and resumes with an approval or rejection.
+
+When executed outside an agent run (no `suspend` available), the tool returns a readable fallback string containing the file path.
+
+## Usage example
+
+Add `submitPlanTool` to an agent's toolset:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { submitPlanTool } from '@mastra/core/tools'
+
+const agent = new Agent({
+  id: 'planner',
+  name: 'Planner',
+  instructions: 'Write a plan to a file before starting work, then submit it for approval.',
+  model,
+  tools: { submitPlanTool },
+})
+```
+
+Handle the suspension and resume:
+
+```typescript
+import fs from 'node:fs'
+
+const stream = await agent.stream('Refactor the auth module')
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'tool-call-suspended' && chunk.payload.toolName === 'submit_plan') {
+    const { path } = chunk.payload.suspendPayload
+    const plan = fs.readFileSync(path, 'utf-8')
+    console.log(plan)
+
+    // Approve:
+    const resumed = await agent.resumeStream({ action: 'approved' }, { runId: stream.runId })
+    for await (const c of resumed.textStream) process.stdout.write(c)
+  }
+}
+```
+
+To reject with feedback:
+
+```typescript
+await agent.resumeStream(
+  { action: 'rejected', feedback: 'Add error handling steps' },
+  { runId: stream.runId },
+)
+```
+
+## Input schema
+
+The model calls this tool with the following parameters:
+
+**path** (`string`): Path to the plan markdown file on disk (e.g. '.mastracode/plans/add-dark-mode.md').
+
+## Suspend payload
+
+The `tool-call-suspended` event carries a `suspendPayload`:
+
+**path** (`string`): Path to the plan file the agent wrote.
+
+**title** (`string`): Plan title, filled by the host after reading the file.
+
+**plan** (`string`): Plan body, filled by the host after reading the file.
+
+## Resume data
+
+Pass an object to `agent.resumeStream()`:
+
+**action** (`'approved' | 'rejected'`): Whether the user approved or rejected the plan.
+
+**feedback** (`string`): Revision instructions when the plan is rejected. Surfaced to the model so it can revise and resubmit.
+
+**path** (`string`): The plan file path, echoed back for history replay.
+
+**title** (`string`): The plan title, echoed back for history replay.
+
+**plan** (`string`): The plan body, echoed back for history replay.
+
+## Approval behavior
+
+- **Approved:** The tool returns `"Plan approved. Proceed with implementation following the approved plan."` to the model.
+- **Rejected with feedback:** The tool returns the feedback and asks the model to revise the plan and submit again.
+- **Rejected without feedback:** The tool tells the model to wait for the user's next message before revising.
+
+When used inside an [AgentController](https://mastra.ai/docs/agent-controller/overview), plan approval triggers an automatic mode switch from the planning mode to the default execution mode. See [Modes](https://mastra.ai/docs/agent-controller/modes) for details.

package/.docs/reference/tools/task-tools.md

@@ -0,0 +1,132 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Task tools
+
+Four built-in, agent-agnostic tools that manage a structured task list for an agent run. The task list is persisted in the thread-scoped `threadState` storage domain and projected onto the agent [state-signal](https://mastra.ai/docs/long-running-agents/signals) lane so it survives [observational-memory](https://mastra.ai/docs/memory/observational-memory) truncation.
+
+Task tracking requires a memory-backed thread (`threadId` + `resourceId`). Without memory the tools return an error explaining that task tracking requires agent memory.
+
+The recommended setup is [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider), which bundles all four tools and the `TaskStateProcessor` in a single registration. See [Built-in tools](https://mastra.ai/docs/agents/using-tools) for the conceptual guide.
+
+## Usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { TaskSignalProvider } from '@mastra/core/signals'
+
+const agent = new Agent({
+  id: 'coder',
+  name: 'Coder',
+  instructions: 'Track your progress with the task tools.',
+  model,
+  memory: new Memory(),
+  signals: [new TaskSignalProvider()],
+})
+```
+
+Or import the tools directly:
+
+```typescript
+import { taskWriteTool, taskUpdateTool, taskCompleteTool, taskCheckTool } from '@mastra/core/tools'
+
+const agent = new Agent({
+  id: 'coder',
+  name: 'Coder',
+  instructions: 'Track your progress with the task tools.',
+  model,
+  memory: new Memory(),
+  tools: { taskWriteTool, taskUpdateTool, taskCompleteTool, taskCheckTool },
+})
+```
+
+## `task_write`
+
+Create or replace the entire task list. Each call replaces the previous list.
+
+### Input schema
+
+**tasks** (`TaskItemInput[]`): The complete updated task list.
+
+**tasks.id** (`string`): Stable task identifier (e.g. 'task\_investigate\_tests'). Keep this unchanged across updates. Auto-generated when omitted.
+
+**tasks.content** (`string`): Task description in imperative form (e.g. 'Fix authentication bug').
+
+**tasks.status** (`'pending' | 'in_progress' | 'completed'`): Current task status.
+
+**tasks.activeForm** (`string`): Present continuous form shown during execution (e.g. 'Fixing authentication bug').
+
+### Output
+
+Returns a `TaskToolResult` with a human-readable `content` summary, the full `tasks` array with assigned IDs, and an `isError` flag.
+
+### Behavior
+
+- IDs must be unique within a call. Duplicate explicit IDs get a generated fallback.
+- When an ID is omitted while rewriting an existing list, one unambiguous matching task reuses its previous ID for stability.
+- Only one task can have `in_progress` status at a time. Submitting multiple `in_progress` tasks returns an error.
+
+## `task_update`
+
+Update one task by its stable ID. Include only the fields that changed.
+
+### Input schema
+
+**id** (`string`): The stable task identifier to update.
+
+**content** (`string`): New task description in imperative form.
+
+**status** (`'pending' | 'in_progress' | 'completed'`): New task status.
+
+**activeForm** (`string`): New present continuous form.
+
+At least one of `content`, `status`, or `activeForm` is required.
+
+### Behavior
+
+- When the update sets a task to `in_progress`, any other `in_progress` task is automatically demoted to `pending`.
+- Returns an error with available task IDs when the ID is not found.
+
+## `task_complete`
+
+Mark one task completed by its stable ID.
+
+### Input schema
+
+**id** (`string`): The stable task identifier to mark completed.
+
+### Behavior
+
+Returns an error with available task IDs when the ID is not found.
+
+## `task_check`
+
+Check the completion status of the task list. Takes no input parameters.
+
+### Output
+
+Returns a `TaskCheckResult` with:
+
+**content** (`string`): Human-readable summary with task counts and incomplete task IDs.
+
+**tasks** (`TaskItem[]`): Full task list snapshot with stable IDs.
+
+**summary** (`TaskCheckSummary`): Structured counts.
+
+**summary.total** (`number`): Total tracked tasks.
+
+**summary.completed** (`number`): Completed tasks.
+
+**summary.inProgress** (`number`): In-progress tasks.
+
+**summary.pending** (`number`): Pending tasks.
+
+**summary.incomplete** (`number`): Tasks not yet completed (in-progress + pending).
+
+**summary.hasTasks** (`boolean`): True when at least one task exists.
+
+**summary.allCompleted** (`boolean`): True when at least one task exists and every task is completed.
+
+**incompleteTasks** (`TaskItem[]`): Tasks that still need work (in-progress and pending).
+
+**isError** (`boolean`): Whether the check encountered an error.

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.2.6-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`e8eaf3a`](https://github.com/mastra-ai/mastra/commit/e8eaf3aea09d51c131b5d369aee459442f416efc), [`d1c930f`](https://github.com/mastra-ai/mastra/commit/d1c930f713d1de09d5f3cd665cb79a8b7ebd7ec7), [`02634f7`](https://github.com/mastra-ai/mastra/commit/02634f700051e014a125d0d10165e3c9b8414e95)]:
+  - @mastra/core@1.50.1-alpha.1
+
 ## 1.2.6-alpha.0
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.6-alpha.1",
+  "version": "1.2.6-alpha.2",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.50.1-alpha.0",
+    "@mastra/core": "1.50.1-alpha.1",
     "@mastra/mcp": "^1.13.1"
   },
   "devDependencies": {
@@ -46,8 +46,8 @@
     "typescript": "^6.0.3",
     "vitest": "4.1.8",
     "@internal/lint": "0.0.112",
-    "@internal/types-builder": "0.0.87",
-    "@mastra/core": "1.50.1-alpha.0"
+    "@mastra/core": "1.50.1-alpha.1",
+    "@internal/types-builder": "0.0.87"
   },
   "homepage": "https://mastra.ai",
   "repository": {