@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/docs/mastra-code/customization.md

@@ -0,0 +1,228 @@
+# Customization
+
+Mastra Code is designed as a composable library. The [`createMastraCode()`](https://mastra.ai/reference/mastra-code/createMastraCode) factory function accepts configuration overrides, and the returned [`Harness`](https://mastra.ai/reference/harness/harness-class) can drive any frontend, not just the built-in TUI.
+
+## Programmatic usage
+
+Import `createMastraCode` to bootstrap Mastra Code in your own application:
+
+```typescript
+import { createMastraCode } from 'mastracode'
+
+const { harness, mcpManager, authStorage } = createMastraCode({
+  cwd: '/path/to/project',
+  initialState: {
+    yolo: false,
+  },
+})
+
+await harness.init()
+await harness.selectOrCreateThread()
+
+harness.subscribe(event => {
+  if (event.type === 'message_update') {
+    console.log(event.message.content)
+  }
+})
+
+await harness.sendMessage({ content: 'Explain the auth module' })
+```
+
+The `harness` object is a standard [Harness](https://mastra.ai/reference/harness/harness-class) instance. You can subscribe to events, switch modes, manage threads, and send messages through its API.
+
+## Custom modes
+
+Override the default Build/Plan/Fast modes by passing a `modes` array:
+
+```typescript
+import { createMastraCode } from 'mastracode'
+import { Agent } from '@mastra/core/agent'
+
+const reviewAgent = new Agent({
+  id: 'review-agent',
+  name: 'Review Agent',
+  instructions:
+    'You are a code review specialist. Analyze code for bugs, security issues, and best practices.',
+  model: 'anthropic/claude-sonnet-4',
+})
+
+const { harness } = createMastraCode({
+  modes: [
+    {
+      id: 'review',
+      name: 'Review',
+      default: true,
+      defaultModelId: 'anthropic/claude-sonnet-4',
+      color: '#f59e0b',
+      agent: reviewAgent,
+    },
+    {
+      id: 'build',
+      name: 'Build',
+      defaultModelId: 'anthropic/claude-opus-4-6',
+      color: '#7c3aed',
+      agent: reviewAgent,
+    },
+  ],
+})
+```
+
+Each mode requires an `id` and an `agent`. The `name`, `defaultModelId`, and `color` fields control how the mode appears in the TUI.
+
+## Extra tools
+
+Add custom tools to the agent's tool set without replacing the built-in tools:
+
+```typescript
+import { createMastraCode } from 'mastracode'
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+const deployTool = createTool({
+  id: 'deploy',
+  description: 'Deploy the current branch to staging',
+  inputSchema: z.object({
+    environment: z.enum(['staging', 'production']),
+  }),
+  execute: async ({ environment }) => {
+    return { content: `Deployed to ${environment}` }
+  },
+})
+
+const { harness } = createMastraCode({
+  extraTools: { deploy: deployTool },
+})
+```
+
+Extra tools are merged with the dynamic tool set and are available to the agent in all modes.
+
+## Custom subagents
+
+Override the default Explore/Plan/Execute subagents. Each subagent receives its own set of tools, scoping what it can do:
+
+```typescript
+import { createMastraCode } from 'mastracode'
+import { createTool } from '@mastra/core/tools'
+
+const { harness } = createMastraCode({
+  subagents: [
+    {
+      id: 'explore',
+      name: 'Explore',
+      description: 'Read-only codebase exploration',
+      instructions:
+        'You are an expert code explorer. Use read-only tools to answer questions about the codebase.',
+    },
+    {
+      id: 'test-writer',
+      name: 'Test Writer',
+      description: 'Write tests for the specified module',
+      instructions:
+        'You are a test-writing specialist. Generate comprehensive tests for the given module.',
+    },
+  ],
+})
+```
+
+## Custom storage
+
+Connect to a remote database instead of the default local SQLite:
+
+```typescript
+import { createMastraCode } from 'mastracode'
+
+const { harness } = createMastraCode({
+  storage: {
+    url: 'libsql://my-db.turso.io',
+    authToken: 'my-auth-token',
+  },
+})
+```
+
+This is equivalent to setting `.mastracode/database.json` but allows configuration at the code level.
+
+## Custom heartbeat handlers
+
+Replace or extend the default background tasks:
+
+```typescript
+import { createMastraCode } from 'mastracode'
+
+const { harness } = createMastraCode({
+  heartbeatHandlers: [
+    {
+      id: 'sync-config',
+      intervalMs: 60_000,
+      handler: async () => {
+        await syncConfigFromRemote()
+      },
+    },
+  ],
+})
+```
+
+Heartbeat handlers run on a fixed interval. They start when `harness.init()` is called and stop when `harness.destroy()` is called.
+
+## Building a custom TUI
+
+Mastra Code exports the `MastraTUI` class from `mastracode/tui` for building custom terminal interfaces. The TUI is driven by the Harness event system:
+
+```typescript
+import { createMastraCode } from 'mastracode'
+import { MastraTUI } from 'mastracode/tui'
+
+const { harness, mcpManager, hookManager, authStorage } = createMastraCode()
+
+const tui = new MastraTUI({
+  harness,
+  hookManager,
+  authStorage,
+  mcpManager,
+  appName: 'My Coding Agent',
+  version: '1.0.0',
+})
+
+tui.run()
+```
+
+The TUI subscribes to harness events and renders messages, tool calls, approvals, and status information in real time.
+
+## Initial state overrides
+
+Control default behavior through `initialState`:
+
+```typescript
+import { createMastraCode } from 'mastracode'
+
+const { harness } = createMastraCode({
+  initialState: {
+    yolo: false,
+    thinkingLevel: 'high',
+    smartEditing: true,
+    notifications: 'system',
+    permissionRules: {
+      categories: {
+        read: 'allow',
+        edit: 'ask',
+        execute: 'ask',
+        mcp: 'deny',
+      },
+      tools: {},
+    },
+  },
+})
+```
+
+### Available state fields
+
+| Field                  | Type                                    | Default                     | Description                                  |
+| ---------------------- | --------------------------------------- | --------------------------- | -------------------------------------------- |
+| `yolo`                 | `boolean`                               | `true`                      | Auto-approve all tool calls                  |
+| `thinkingLevel`        | `string`                                | `"off"`                     | Extended thinking depth for Anthropic models |
+| `smartEditing`         | `boolean`                               | `true`                      | Use AST-based analysis for code edits        |
+| `notifications`        | `"bell" \| "system" \| "both" \| "off"` | `"off"`                     | Alert when the TUI needs attention           |
+| `permissionRules`      | `object`                                | Default policies            | Per-category and per-tool approval policies  |
+| `observerModelId`      | `string`                                | `"google/gemini-2.5-flash"` | Model for observational memory observer      |
+| `reflectorModelId`     | `string`                                | `"google/gemini-2.5-flash"` | Model for observational memory reflector     |
+| `observationThreshold` | `number`                                | `30000`                     | Token count triggering observation pass      |
+| `reflectionThreshold`  | `number`                                | `40000`                     | Token count triggering reflection pass       |

package/.docs/docs/mastra-code/modes.md

@@ -0,0 +1,104 @@
+# Modes
+
+Mastra Code operates in one of three modes, each tailored to a different kind of task. Modes control which tools the agent has access to, how it approaches problems, and which default model it uses.
+
+Switch modes with the `/mode` slash command.
+
+## Build mode
+
+Build mode is the default. The agent has full access to all tools — reading, writing, editing files, and running shell commands.
+
+Use Build mode when you want the agent to make changes to your codebase: implementing features, fixing bugs, refactoring code, or running tests.
+
+### Working style
+
+- **Simple tasks** (typo fixes, single-file changes): The agent acts immediately without planning.
+- **Non-trivial tasks** (3+ files, architectural decisions): The agent creates a task list, works through each step, and verifies changes before moving on.
+
+### Implementation loop
+
+For each change, the agent follows this cycle:
+
+1. **Understand**: Read the relevant code and check existing conventions.
+2. **Implement**: Make the change following existing patterns.
+3. **Verify**: Run tests, type-check, or manually confirm the behavior.
+4. **Clean up**: Remove debug statements and ensure no half-done work.
+
+### Approved plans
+
+When a plan is approved in Plan mode, Mastra Code automatically switches to Build mode and injects the plan into the agent's instructions. The agent then implements the plan step by step.
+
+## Plan mode
+
+Plan mode is read-only. The agent can explore the codebase but cannot modify files or run side-effect commands.
+
+Use Plan mode when you want to analyze architecture, design an approach, or create a detailed implementation plan before writing code.
+
+### Available tools
+
+- `view`: Read files and list directories
+- `search_content`: Search file contents
+- `find_files`: Find files by pattern
+- `execute_command`: Only for read-only commands (`git status`, `git log`, `git diff`)
+
+### Plan submission
+
+When the agent finishes analyzing the codebase, it submits a structured plan using the `submit_plan` tool. The plan includes:
+
+- **Overview**: What the change does and why.
+- **Complexity estimate**: Size, risk level, and dependencies.
+- **Steps**: Specific files, changes, and rationale in dependency order.
+- **Verification**: What tests to run and what to check.
+
+After submission, you can:
+
+- **Approve**: Mastra Code switches to Build mode and begins implementation.
+- **Reject**: Stay in Plan mode.
+- **Request changes**: Provide feedback for the agent to revise and resubmit.
+
+## Fast mode
+
+Fast mode prioritizes speed and brevity. The agent uses a faster model and keeps responses short.
+
+Use Fast mode for quick lookups, simple questions, and small edits where latency matters more than depth.
+
+### Rules
+
+- Responses stay under 200 words unless the task requires more.
+- No planning phase; the agent acts directly.
+- For general programming questions, the agent answers from knowledge without searching the codebase.
+- For project-specific questions, the agent reads the relevant code and answers concisely.
+
+## Default models
+
+Each mode has a default model that's selected when you switch to it:
+
+| Mode  | Default model               |
+| ----- | --------------------------- |
+| Build | `anthropic/claude-opus-4-6` |
+| Plan  | `openai/gpt-5.2-codex`      |
+| Fast  | `cerebras/zai-glm-4.7`      |
+
+Override the model for any mode using the `/models` command. Per-mode model selections persist to the thread, so switching back to a mode restores the last model you used in it.
+
+> **Note:** Visit [`createMastraCode()` reference](https://mastra.ai/reference/mastra-code/createMastraCode) for details on configuring custom modes and default models.
+
+## Subagents
+
+In Build mode, the agent can spawn subagents to parallelize work. Subagents run as focused, independent tasks with their own tool access:
+
+| Subagent    | Access       | Use case                                                               |
+| ----------- | ------------ | ---------------------------------------------------------------------- |
+| **Explore** | Read-only    | "Find all usages of X", "How does module Y work"                       |
+| **Plan**    | Read-only    | "Create an implementation plan for X", "Analyze the architecture of Y" |
+| **Execute** | Read + write | "Implement feature X", "Fix bug Y", "Refactor module Z"                |
+
+The parent agent spawns subagents only when multiple tasks can run in parallel. For a single task, the agent handles it directly. Subagent outputs are treated as untrusted — the parent agent verifies results before moving on.
+
+## Thinking level
+
+You can control thinking depth through the `/settings` panel (or `/think`). Stored levels remain `off`, `low`, `medium`, `high`, and `xhigh` across providers. For OpenAI models, the UI shows provider-specific labels (for example, `Very High (xhigh)`), while non-OpenAI models keep generic labels.
+
+## YOLO mode
+
+YOLO mode auto-approves all tool calls without prompting. It's enabled by default and can be toggled through `/settings`. When disabled, Mastra Code prompts for approval before executing write operations or shell commands, based on the [permission system](https://mastra.ai/docs/mastra-code/tools).

package/.docs/docs/mastra-code/overview.md

@@ -0,0 +1,135 @@
+# Mastra Code overview
+
+Mastra Code is a terminal-based AI coding agent built on Mastra's [Harness](https://mastra.ai/reference/harness/harness-class), [Agent](https://mastra.ai/docs/agents/overview), and [Memory](https://mastra.ai/docs/memory/overview) primitives. It runs in your terminal, connects to 70+ AI models, and provides tools for reading, searching, editing, and executing code.
+
+Mastra Code organizes its capabilities around these areas:
+
+- [**Modes**](https://mastra.ai/docs/mastra-code/modes): Switch between Build, Plan, and Fast modes to match your workflow.
+- [**Tools**](https://mastra.ai/docs/mastra-code/tools): Built-in tools for file viewing, editing, searching, shell commands, and web search.
+- [**Configuration**](https://mastra.ai/docs/mastra-code/configuration): Project-scoped threads, MCP servers, hooks, custom commands, skills, and database settings.
+- [**Customization**](https://mastra.ai/docs/mastra-code/customization): Extend Mastra Code programmatically with custom modes, tools, subagents, and storage.
+
+## When to use Mastra Code
+
+- **Day-to-day coding**: Ask questions about your codebase, make edits, run tests, and manage Git.
+- **Code exploration**: Use Plan mode to analyze architecture and create implementation plans before writing code.
+- **Quick lookups**: Switch to Fast mode for brief answers and small edits with minimal latency.
+- **Multi-model workflows**: Compare responses across different AI providers by switching models mid-conversation.
+
+## Prerequisites
+
+Mastra Code requires Node.js 22.13.0 or later.
+
+## Get started
+
+1. Install Mastra Code globally:
+
+   **npm**:
+
+   ```sh
+   npm install -g mastracode
+   ```
+
+   **pnpm**:
+
+   ```sh
+   pnpm add -g mastracode
+   ```
+
+   **Yarn**:
+
+   ```sh
+   yarn global add mastracode
+   ```
+
+   **Bun**:
+
+   ```sh
+   bun add --global mastracode
+   ```
+
+   Or run it with `npx`:
+
+   **npm**:
+
+   ```sh
+   npx mastracode
+   ```
+
+   **pnpm**:
+
+   ```sh
+   pnpm dlx mastracode
+   ```
+
+   **Yarn**:
+
+   ```sh
+   yarn dlx mastracode
+   ```
+
+   **Bun**:
+
+   ```sh
+   bun x mastracode
+   ```
+
+2. Navigate to your project directory and start Mastra Code:
+
+   ```sh
+   cd your-project
+   mastracode
+   ```
+
+3. Set an API key for your preferred provider (e.g. `export ANTHROPIC_API_KEY=sk-ant-...`), or run `/login` to authenticate with an Anthropic or OpenAI subscription. See [Configuration](https://mastra.ai/docs/mastra-code/configuration) for all supported providers.
+
+4. Type a message and press Enter. The agent responds with streaming text and can read, edit, and run code in your project.
+
+## Slash commands
+
+Mastra Code provides built-in slash commands for managing sessions and settings:
+
+| Command     | Description                                       |
+| ----------- | ------------------------------------------------- |
+| `/new`      | Start a new conversation thread                   |
+| `/threads`  | List all threads for this project                 |
+| `/models`   | Select a different AI model                       |
+| `/mode`     | Switch between Build, Plan, and Fast modes        |
+| `/cost`     | Show token usage for the current conversation     |
+| `/login`    | Authenticate with OAuth providers                 |
+| `/logout`   | Log out from a provider                           |
+| `/settings` | Open the settings panel                           |
+| `/theme`    | Switch color theme (auto, dark, or light)         |
+| `/sandbox`  | Add external directories to the allowed path list |
+| `/diff`     | Show files modified in the current session        |
+| `/help`     | Show available commands                           |
+| `/exit`     | Exit the TUI                                      |
+
+You can also define custom slash commands as markdown files. See [Configuration](https://mastra.ai/docs/mastra-code/configuration) for details.
+
+## Keyboard shortcuts
+
+| Shortcut | Action                                              |
+| -------- | --------------------------------------------------- |
+| `Ctrl+C` | Interrupt current operation                         |
+| `Ctrl+D` | Exit (when editor is empty)                         |
+| `Ctrl+T` | Toggle thinking blocks visibility                   |
+| `Ctrl+E` | Expand/collapse all tool outputs                    |
+| `Ctrl+F` | Send a follow-up message while the agent is running |
+
+## Architecture
+
+Mastra Code is built on four layers:
+
+1. **TUI**: Terminal interface (`pi-tui` components)
+2. **Harness**: Mode management, thread persistence, event system, state management
+3. **Mastra Agent**: Dynamic model selection, tool execution, memory integration, subagents
+4. **LibSQL Storage**: Thread persistence, message history, token usage tracking, observational memory
+
+## Next steps
+
+- [Modes](https://mastra.ai/docs/mastra-code/modes)
+- [Tools](https://mastra.ai/docs/mastra-code/tools)
+- [Configuration](https://mastra.ai/docs/mastra-code/configuration)
+- [Customization](https://mastra.ai/docs/mastra-code/customization)
+- [API reference](https://mastra.ai/reference/mastra-code/createMastraCode)