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

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

@@ -1,135 +0,0 @@
-# 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)

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

@@ -1,229 +0,0 @@
-# Tools
-
-Mastra Code provides built-in tools that the agent uses to interact with your codebase. Each tool is designed for a specific task, and the agent selects the right one based on what it needs to do.
-
-## File tools
-
-### `view`
-
-Read file contents with line numbers or list directory contents. The agent uses this tool before editing a file.
-
-- Displays line-numbered output (like `cat -n`) for easy reference.
-- For directories, lists files up to 2 levels deep, excluding hidden items.
-- Supports `view_range` to read specific line ranges in large files.
-- Output is truncated if the file exceeds the token limit. Use `view_range` to read specific sections.
-
-| Parameter    | Type               | Required | Description                                              |
-| ------------ | ------------------ | -------- | -------------------------------------------------------- |
-| `path`       | `string`           | Yes      | Path to the file or directory (relative to project root) |
-| `view_range` | `[number, number]` | No       | Line range `[start, end]` to view a section of the file  |
-
-### `string_replace_lsp`
-
-Edit a file by replacing an exact text match with new content. Returns Language Server Protocol (LSP) diagnostics showing any errors or warnings introduced by the edit.
-
-- The agent reads the file first with `view` before editing.
-- `old_str` must be an exact substring of the current file content.
-- Include enough surrounding context to uniquely identify the replacement location.
-- When `new_str` is omitted or empty, the matched text is deleted.
-- After editing, TypeScript errors, linting warnings, and other diagnostics are returned automatically.
-
-| Parameter    | Type     | Required | Description                                        |
-| ------------ | -------- | -------- | -------------------------------------------------- |
-| `path`       | `string` | Yes      | Path to the file                                   |
-| `old_str`    | `string` | Yes      | Exact text to find and replace                     |
-| `new_str`    | `string` | No       | Replacement text (omit to delete the matched text) |
-| `start_line` | `number` | No       | Line number to narrow the search region            |
-
-### `ast_smart_edit`
-
-Edit code using abstract syntax tree (AST) analysis for intelligent, structure-aware transformations. Powered by [ast-grep](https://ast-grep.github.io/), this tool understands code structure rather than treating files as raw text.
-
-Supported transformations:
-
-- **Pattern-based search and replace**: Find and replace code using AST patterns with `$VARIABLE` placeholders (e.g., replace `console.log($ARG)` with `logger.debug($ARG)`).
-- **Add/remove imports**: Intelligently insert or remove import statements.
-- **Rename functions**: Rename function declarations and all call sites with scope awareness.
-- **Rename variables**: Rename variable declarations and all references.
-- **Selector queries**: Find AST nodes matching a CSS-like selector (e.g., `"FunctionDeclaration"`).
-
-| Parameter     | Type     | Required | Description                                                                                                                     |
-| ------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `path`        | `string` | Yes      | File path relative to project root                                                                                              |
-| `pattern`     | `string` | No       | AST pattern to search for (supports `$VARIABLE` placeholders)                                                                   |
-| `replacement` | `string` | No       | Replacement pattern (can use captured `$VARIABLES`)                                                                             |
-| `selector`    | `string` | No       | CSS-like selector for AST nodes                                                                                                 |
-| `transform`   | `string` | No       | Transformation type: `add-import`, `remove-import`, `rename-function`, `rename-variable`, `extract-function`, `inline-variable` |
-| `targetName`  | `string` | No       | Name of the target element (for rename/remove operations)                                                                       |
-| `newName`     | `string` | No       | New name (for rename operations)                                                                                                |
-| `importSpec`  | `object` | No       | Import specification for `add-import`: `{ module, names, isDefault? }`                                                          |
-
-### `write_file`
-
-Create a new file or overwrite an existing file entirely.
-
-- Use for creating new files. For editing existing files, prefer `string_replace_lsp`.
-- Parent directories are created automatically if they don't exist.
-- If overwriting an existing file, the agent reads it first with `view`.
-
-| Parameter | Type     | Required | Description                                      |
-| --------- | -------- | -------- | ------------------------------------------------ |
-| `path`    | `string` | Yes      | File path to write to (relative to project root) |
-| `content` | `string` | Yes      | Full content to write to the file                |
-
-## Search tools
-
-### `search_content`
-
-Search file contents using regular expressions. Uses ripgrep when available, falling back to grep.
-
-- Supports full regex syntax (e.g., `"function\\s+\\w+"`, `"import.*from"`).
-- Respects `.gitignore` automatically in Git repositories.
-- Always preferred over running `grep` or `rg` via `execute_command`.
-
-| Parameter       | Type      | Required | Description                                                                         |
-| --------------- | --------- | -------- | ----------------------------------------------------------------------------------- |
-| `pattern`       | `string`  | Yes      | Regex pattern to search for in file contents                                        |
-| `path`          | `string`  | No       | Directory or file to search in (relative to project root, defaults to project root) |
-| `glob`          | `string`  | No       | Glob pattern to filter files (e.g., `"*.ts"`, `"*.{js,jsx}"`, `"test/**"`)          |
-| `contextLines`  | `number`  | No       | Number of lines to show before and after each match (default: 0)                    |
-| `maxResults`    | `number`  | No       | Maximum number of matching lines to return (default: 100)                           |
-| `caseSensitive` | `boolean` | No       | Whether the search is case-sensitive (default: true)                                |
-
-### `find_files`
-
-Find files by name pattern using glob matching. Results are sorted by modification time (most recent first).
-
-- Supports standard glob syntax: `*` (any characters), `**` (any path segments), `?` (single character), `{a,b}` (alternatives).
-- Respects `.gitignore` automatically in Git repositories.
-- Always preferred over running `find` or `ls` via `execute_command`.
-
-| Parameter | Type     | Required | Description                                                                 |
-| --------- | -------- | -------- | --------------------------------------------------------------------------- |
-| `pattern` | `string` | Yes      | Glob pattern (e.g., `"**/*.ts"`, `"src/**/*.test.*"`, `"**/package.json"`)  |
-| `path`    | `string` | No       | Directory to search in (relative to project root, defaults to project root) |
-
-## Shell execution
-
-### `execute_command`
-
-Execute a shell command in the project directory.
-
-- Use for Git commands, package managers (`npm`, `pnpm`), build tools, test runners, Docker, and other terminal operations.
-- Commands run with a 30-second default timeout. Use the `timeout` parameter for longer operations.
-- Output is stripped of ANSI codes and streamed to the TUI in real time.
-- Pipe to `| tail -N` for commands with long output — full output streams to the user, but only the last N lines are returned to the agent.
-- The `CI=true` environment variable is set automatically to prevent interactive prompts.
-
-| Parameter | Type     | Required | Description                                  |
-| --------- | -------- | -------- | -------------------------------------------- |
-| `command` | `string` | Yes      | Shell command to execute                     |
-| `cwd`     | `string` | No       | Working directory (defaults to project root) |
-| `timeout` | `number` | No       | Timeout in seconds (default: 30)             |
-
-### `request_sandbox_access`
-
-Request access to directories outside the project root. The user is prompted to approve or deny the request.
-
-| Parameter | Type     | Required | Description                                   |
-| --------- | -------- | -------- | --------------------------------------------- |
-| `path`    | `string` | Yes      | Absolute path to the directory needing access |
-| `reason`  | `string` | Yes      | Explanation of why access is needed           |
-
-## Web tools
-
-### `web_search`
-
-Search the web for documentation, error messages, package APIs, and other information.
-
-This tool is available through two providers:
-
-- **Tavily**: When the `TAVILY_API_KEY` environment variable is set.
-- **Anthropic web search**: Built into Anthropic models, used as a fallback when no Tavily key is configured.
-
-| Parameter       | Type                    | Required | Description                             |
-| --------------- | ----------------------- | -------- | --------------------------------------- |
-| `query`         | `string`                | Yes      | The search query                        |
-| `searchDepth`   | `"basic" \| "advanced"` | No       | Search depth (default: `"basic"`)       |
-| `maxResults`    | `number`                | No       | Maximum number of results (default: 10) |
-| `includeImages` | `boolean`               | No       | Include related images (default: false) |
-
-### `web_extract`
-
-Extract the full content of one or more web pages. Requires a Tavily API key (`TAVILY_API_KEY`).
-
-| Parameter       | Type                    | Required | Description                                   |
-| --------------- | ----------------------- | -------- | --------------------------------------------- |
-| `urls`          | `string[]`              | Yes      | URLs to extract content from (max 20)         |
-| `extractDepth`  | `"basic" \| "advanced"` | No       | Extraction depth (default: `"basic"`)         |
-| `includeImages` | `boolean`               | No       | Include extracted image URLs (default: false) |
-
-## Task management
-
-### `task_write`
-
-Create or update a structured task list for tracking progress on complex, multi-step work.
-
-- Each task has a `content` (imperative form), `status` (`pending`, `in_progress`, `completed`), and `activeForm` (present continuous form shown during execution).
-- Pass the full task list each time — it replaces the previous list.
-- Only one task should be `in_progress` at a time.
-
-### `task_check`
-
-Check the completion status of the current task list. The agent uses this before finishing to verify all tasks are complete.
-
-## Interactive tools
-
-### `ask_user`
-
-Ask the user a structured question. The agent uses this when it needs clarification, wants to validate assumptions, or needs the user to make a decision. Questions render inline in the conversation flow and support optional multiple-choice options.
-
-### `submit_plan`
-
-Submit a structured implementation plan for user review and approval (Plan mode only). The plan renders inline, and the user can approve, reject, or request changes.
-
-## MCP tools
-
-When [MCP servers](https://mastra.ai/docs/mastra-code/configuration) are configured, their tools are automatically available to the agent. MCP tools are namespaced as `serverName_toolName` to avoid collisions with built-in tools.
-
-MCP tools fall under the `mcp` permission category. When YOLO mode is disabled, they require approval before execution.
-
-## Tool availability by mode
-
-Not all tools are available in every mode:
-
-| Tool                     | Build | Plan      | Fast |
-| ------------------------ | ----- | --------- | ---- |
-| `view`                   | Yes   | Yes       | Yes  |
-| `search_content`         | Yes   | Yes       | Yes  |
-| `find_files`             | Yes   | Yes       | Yes  |
-| `execute_command`        | Yes   | Read-only | Yes  |
-| `string_replace_lsp`     | Yes   | No        | Yes  |
-| `ast_smart_edit`         | Yes   | No        | Yes  |
-| `write_file`             | Yes   | No        | Yes  |
-| `web_search`             | Yes   | Yes       | Yes  |
-| `web_extract`            | Yes   | Yes       | Yes  |
-| `task_write`             | Yes   | Yes       | Yes  |
-| `task_check`             | Yes   | Yes       | Yes  |
-| `ask_user`               | Yes   | Yes       | Yes  |
-| `submit_plan`            | No    | Yes       | No   |
-| `request_sandbox_access` | Yes   | Yes       | Yes  |
-
-In Plan mode, `execute_command` is available but restricted to read-only commands (`git status`, `git log`, `git diff`, etc.).
-
-## Permission system
-
-Tools are grouped into four categories, each with a configurable approval policy:
-
-| Category    | Tools                                                               | Default policy |
-| ----------- | ------------------------------------------------------------------- | -------------- |
-| **Read**    | `view`, `search_content`, `find_files`, `web_search`, `web_extract` | `allow`        |
-| **Edit**    | `string_replace_lsp`, `ast_smart_edit`, `write_file`, `subagent`    | `ask`          |
-| **Execute** | `execute_command`                                                   | `ask`          |
-| **MCP**     | All MCP server tools                                                | `ask`          |
-
-When YOLO mode is enabled (the default), all categories are set to `allow`. When disabled, the agent prompts for approval based on the category policy.
-
-You can configure per-category or per-tool overrides through `/settings`, and session-level grants let you approve a category once for the rest of the session.
-
-> **Note:** Visit [Modes](https://mastra.ai/docs/mastra-code/modes) for details on how modes affect tool access and approval behavior.

package/.docs/reference/mastra-code/createMastraCode.md

@@ -1,108 +0,0 @@
-# createMastraCode()
-
-`createMastraCode()` is the main factory function that bootstraps the Mastra Code coding agent. It wires together project detection, storage, authentication, MCP servers, hooks, modes, subagents, and the [Harness](https://mastra.ai/reference/harness/harness-class) that drives the TUI or any other frontend.
-
-## Usage example
-
-```typescript
-import { createMastraCode } from 'mastracode'
-
-const { harness, mcpManager, hookManager, authStorage } = createMastraCode()
-```
-
-Pass a config object to customize behavior:
-
-```typescript
-import { createMastraCode } from 'mastracode'
-
-const { harness } = createMastraCode({
-  cwd: '/path/to/project',
-  disableMcp: true,
-  initialState: { yolo: false },
-})
-
-await harness.init()
-await harness.selectOrCreateThread()
-await harness.sendMessage({ content: 'Explain the auth flow' })
-```
-
-## Parameters
-
-`createMastraCode()` accepts an optional `MastraCodeConfig` object:
-
-**cwd?:** (`string`): Working directory for project detection. Mastra Code uses this path to find the Git root, determine the project name, and scope threads. (Default: `process.cwd()`)
-
-**modes?:** (`HarnessMode[]`): Override the default agent modes. Each mode defines an agent, a default model, and a display color. When omitted, Mastra Code ships with Build, Plan, and Fast modes.
-
-**subagents?:** (`HarnessSubagent[]`): Override the default subagent definitions. When omitted, Mastra Code includes Explore (read-only codebase exploration), Plan (read-only analysis and planning), and Execute (task execution with write access).
-
-**extraTools?:** (`Record<string, any>`): Additional tools merged into the dynamic tool set available to the agent.
-
-**storage?:** (`{ url: string; authToken?: string }`): Custom LibSQL storage configuration. When omitted, Mastra Code auto-detects storage from environment variables, project config, global config, or falls back to a local SQLite database.
-
-**initialState?:** (`Record<string, unknown>`): Initial harness state overrides. Merged with defaults like \`yolo\`, \`thinkingLevel\`, and project info.
-
-**heartbeatHandlers?:** (`HeartbeatHandler[]`): Override the default periodic background tasks. The default handler syncs model gateways every 5 minutes.
-
-**disableMcp?:** (`boolean`): Disable MCP server discovery and connection. (Default: `false`)
-
-**disableHooks?:** (`boolean`): Disable the hooks system (lifecycle shell commands). (Default: `false`)
-
-## Return value
-
-`createMastraCode()` returns an object with four properties:
-
-**harness:** (`Harness`): The Harness instance that orchestrates modes, threads, state, memory, and agent interactions. This is the primary interface for sending messages, switching models, and managing conversations.
-
-**mcpManager:** (`McpManager | undefined`): The MCP manager for connecting to external MCP servers. \`undefined\` when \`disableMcp\` is \`true\`.
-
-**hookManager:** (`HookManager | undefined`): The hook manager for executing lifecycle shell commands. \`undefined\` when \`disableHooks\` is \`true\`.
-
-**authStorage:** (`AuthStorage`): The authentication storage instance. Manages OAuth credentials for AI providers (Anthropic Claude Max, OpenAI Codex).
-
-## Default modes
-
-When no `modes` are specified, Mastra Code creates three modes:
-
-| Mode                | Default model               | Description                                                            |
-| ------------------- | --------------------------- | ---------------------------------------------------------------------- |
-| **Build** (default) | `anthropic/claude-opus-4-6` | Full tool access. Read, write, edit files, and execute commands.       |
-| **Plan**            | `openai/gpt-5.2-codex`      | Read-only mode. Explore the codebase and produce implementation plans. |
-| **Fast**            | `cerebras/zai-glm-4.7`      | Quick answers and small edits with minimal overhead.                   |
-
-## Default subagents
-
-When no `subagents` are specified, Mastra Code creates three subagent types:
-
-| Subagent    | Tools                                                                                              | Description                                                                  |
-| ----------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| **Explore** | `view`, `search_content`, `find_files`                                                             | Read-only codebase exploration for answering questions about code structure. |
-| **Plan**    | `view`, `search_content`, `find_files`                                                             | Read-only analysis and planning with structured plan output.                 |
-| **Execute** | All read tools + `string_replace_lsp`, `write_file`, `execute_command`, `task_write`, `task_check` | Focused task execution with full write capabilities.                         |
-
-## Project detection
-
-Mastra Code automatically detects project identity from the working directory:
-
-1. **Git remote URL** — if available, normalizes SSH and HTTPS URLs to create a stable identifier shared across clones and worktrees.
-2. **Absolute path** — falls back to the filesystem path when Git isn't available.
-
-The resulting `resourceId` scopes threads to the project, so conversations are shared across clones, worktrees, and SSH/HTTPS URLs of the same repository.
-
-## Storage resolution
-
-Storage configuration is resolved in priority order:
-
-1. `storage` parameter passed to `createMastraCode()`
-2. `MASTRA_DB_URL` and `MASTRA_DB_AUTH_TOKEN` environment variables
-3. Project config at `.mastracode/database.json`
-4. Global config at `~/.mastracode/database.json`
-5. Local SQLite database at the platform-specific app data directory
-
-> **Note:** The returned `harness` object is a full [Harness](https://mastra.ai/reference/harness/harness-class) instance with methods for sending messages, switching modes and models, managing threads, and subscribing to events.
-
-## Related
-
-- [Mastra Code overview](https://mastra.ai/docs/mastra-code/overview)
-- [Harness Class reference](https://mastra.ai/reference/harness/harness-class)
-- [Mastra Code configuration](https://mastra.ai/docs/mastra-code/configuration)