@mastra/mcp-docs-server 1.1.6 → 1.1.7

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

@@ -1,299 +0,0 @@
-# Configuration
-
-Mastra Code is configured through project-level files, global settings, and environment variables. Configuration files live in `.mastracode/` directories at the project and user levels.
-
-## Authentication
-
-Mastra Code supports two authentication methods: **API keys** (environment variables) and **OAuth** (provider subscriptions). You can use either or both.
-
-### API keys
-
-The simplest way to get started is to set API key environment variables for the providers you want to use. Mastra Code auto-detects these on startup:
-
-```sh
-export ANTHROPIC_API_KEY=sk-ant-...
-export OPENAI_API_KEY=sk-...
-export GOOGLE_GENERATIVE_AI_API_KEY=...
-export DEEPSEEK_API_KEY=...
-export CEREBRAS_API_KEY=...
-```
-
-Mastra Code uses Mastra's [model router](https://mastra.ai/models), which routes requests to the correct provider based on the model ID and available API keys. No OAuth login is required when using API keys.
-
-### OAuth login (optional)
-
-If you have an Anthropic Claude Max or OpenAI ChatGPT Plus subscription, you can authenticate via OAuth to use your subscription instead of API keys. Run `/login` in the TUI to start the flow.
-
-| Provider      | OAuth flow              | What you get                                  |
-| ------------- | ----------------------- | --------------------------------------------- |
-| **Anthropic** | Claude Max subscription | Access to Claude models via your subscription |
-| **OpenAI**    | ChatGPT Plus / Codex    | Access to OpenAI models via your subscription |
-
-OAuth credentials are stored in `auth.json` alongside the database in the [app data directory](#database-location). During onboarding, you can skip the OAuth step if you already have API keys configured.
-
-### Anthropic OAuth warning
-
-Authenticating with a Claude Max subscription through OAuth is a grey area. Anthropic has reportedly banned users for using Claude max credentials outside of Claude Code, so it may violate Anthropic Terms of Service.
-
-## MCP servers
-
-Mastra Code can connect to external [MCP](https://mastra.ai/docs/mcp/overview) servers and make their tools available to the agent. Configure servers in JSON files:
-
-| Priority | Path                          | Scope                            |
-| -------- | ----------------------------- | -------------------------------- |
-| Highest  | `.mastracode/mcp.json`        | Project                          |
-|          | `~/.mastracode/mcp.json`      | Global                           |
-| Lowest   | `.claude/settings.local.json` | Project (Claude Code compatible) |
-
-Project config overrides global config by server name. Claude Code settings are the lowest priority fallback.
-
-### MCP config format
-
-```json
-{
-  "mcpServers": {
-    "my-server": {
-      "command": "npx",
-      "args": ["-y", "@my-org/mcp-server"],
-      "env": {
-        "API_KEY": "your-key"
-      }
-    }
-  }
-}
-```
-
-Each server entry requires a `command` field. The `args` and `env` fields are optional.
-
-On startup, Mastra Code connects to all configured servers and reports the status:
-
-```text
-MCP: 2 server(s) connected, 15 tool(s)
-```
-
-Tools from MCP servers are namespaced as `serverName_toolName` and appear in the agent's tool list alongside built-in tools.
-
-## Hooks
-
-Hooks are user-configured shell commands that run at specific lifecycle events. Use hooks for custom validation, logging, notifications, or integration with external systems.
-
-### Hook config format
-
-```json
-{
-  "PreToolUse": [
-    {
-      "type": "command",
-      "command": "node scripts/validate-tool.js",
-      "matcher": {
-        "tool_name": "execute_command"
-      },
-      "timeout": 5000,
-      "description": "Validate shell commands before execution"
-    }
-  ],
-  "PostToolUse": [
-    {
-      "type": "command",
-      "command": "node scripts/log-tool.js",
-      "description": "Log tool usage"
-    }
-  ]
-}
-```
-
-### Hook events
-
-| Event              | When it fires                                                   | Can block? |
-| ------------------ | --------------------------------------------------------------- | ---------- |
-| `PreToolUse`       | Before a tool call executes                                     | Yes        |
-| `PostToolUse`      | After a tool call completes                                     | No         |
-| `Stop`             | When an agent response ends (`complete`, `aborted`, or `error`) | Yes        |
-| `UserPromptSubmit` | When the user sends a message                                   | Yes        |
-| `SessionStart`     | When a session begins                                           | No         |
-| `SessionEnd`       | When a session ends                                             | No         |
-| `Notification`     | When the TUI fires a notification                               | No         |
-
-`UserPromptSubmit` runs before a non-command prompt is sent to the agent. If a hook blocks, the prompt is not sent.
-
-### Hook I/O protocol
-
-Hook processes receive a JSON payload on stdin with context about the event:
-
-```json
-{
-  "session_id": "thread-abc123",
-  "cwd": "/path/to/project",
-  "hook_event_name": "PreToolUse",
-  "tool_name": "execute_command",
-  "tool_input": { "command": "npm test" }
-}
-```
-
-For blocking events (`PreToolUse`, `Stop`, `UserPromptSubmit`), the hook can respond on stdout with a JSON object:
-
-```json
-{
-  "decision": "block",
-  "reason": "This command is not allowed"
-}
-```
-
-### Hook config locations
-
-| Priority | Path                       | Scope                           |
-| -------- | -------------------------- | ------------------------------- |
-| Higher   | `.mastracode/hooks.json`   | Project (appended after global) |
-| Lower    | `~/.mastracode/hooks.json` | Global (runs first)             |
-
-Global hooks run before project hooks. For the same event, all hooks execute in order.
-
-## Custom slash commands
-
-Define reusable prompt templates as markdown files. Mastra Code scans these directories for `.md` files:
-
-| Priority | Path                      | Scope                            |
-| -------- | ------------------------- | -------------------------------- |
-| Highest  | `.mastracode/commands/`   | Project                          |
-|          | `.claude/commands/`       | Project (Claude Code compatible) |
-|          | `~/.mastracode/commands/` | Global                           |
-| Lowest   | `~/.claude/commands/`     | Global (Claude Code compatible)  |
-
-Each command file can include YAML frontmatter with `name` and `description` fields:
-
-```yaml
----
-name: review
-description: Review the current diff for issues
----
-Review my current git diff. Look for bugs, security issues,
-and violations of the project's coding standards.
-```
-
-The filename (or directory structure) determines the command name. For example, `git/commit.md` becomes `/git:commit`.
-
-Commands support variables like `$ARGUMENTS` for positional args, `@filename` for file content injection, and `!command` for shell command output.
-
-## Skills
-
-Skills are structured instruction files that the agent loads automatically based on trigger conditions. They provide domain-specific guidance without manually pasting instructions.
-
-Mastra Code scans these directories for skills:
-
-| Priority | Path                    | Scope                            |
-| -------- | ----------------------- | -------------------------------- |
-| Highest  | `.mastracode/skills/`   | Project                          |
-|          | `.claude/skills/`       | Project (Claude Code compatible) |
-|          | `~/.mastracode/skills/` | Global                           |
-| Lowest   | `~/.claude/skills/`     | Global (Claude Code compatible)  |
-
-Each skill is a directory containing a `SKILL.md` file with instructions and trigger descriptions. Skills installed via symlinks (e.g., from `npx skills add`) are automatically resolved.
-
-## Agent instructions
-
-Mastra Code loads project-specific instructions from `AGENTS.md` or `CLAUDE.md` files and injects them into the agent's system prompt. This is how you can customize the agent's behavior for your project.
-
-### Lookup order
-
-For project instructions (first match wins):
-
-1. `AGENTS.md` or `CLAUDE.md` in the project root
-2. `.claude/AGENTS.md` or `.claude/CLAUDE.md`
-3. `.mastracode/AGENTS.md` or `.mastracode/CLAUDE.md`
-
-For global instructions (first match wins):
-
-1. `~/.claude/AGENTS.md` or `~/.claude/CLAUDE.md`
-2. `~/.mastracode/AGENTS.md` or `~/.mastracode/CLAUDE.md`
-3. `~/.config/claude/AGENTS.md` or `~/.config/claude/CLAUDE.md`
-4. `~/.config/mastracode/AGENTS.md` or `~/.config/mastracode/CLAUDE.md`
-
-`AGENTS.md` takes priority over `CLAUDE.md` when both exist at the same location.
-
-## Storage
-
-Mastra Code stores threads, messages, state, and observational memory in a database. It uses LibSQL by default with a local file — no setup needed.
-
-To switch to a remote LibSQL (Turso) or PostgreSQL backend, run `/settings` and select a storage backend. You'll be prompted for a connection URL.
-
-If a PostgreSQL connection fails on startup, Mastra Code falls back to LibSQL and shows a warning so you can fix the connection via `/settings`.
-
-## Observational memory
-
-[Observational memory](https://mastra.ai/docs/memory/observational-memory) (OM) uses background agents to maintain a dense log of observations and reflections about the conversation, providing long-term context that persists across sessions.
-
-### OM scope
-
-Control whether observations are scoped to individual threads or shared across all threads for a project:
-
-| Scope              | Behavior                                                        |
-| ------------------ | --------------------------------------------------------------- |
-| `thread` (default) | Observations are private to each conversation thread            |
-| `resource`         | Observations are shared across all threads for the same project |
-
-Configure the scope through:
-
-1. `MASTRA_OM_SCOPE` environment variable (`"thread"` or `"resource"`)
-2. `.mastracode/database.json` → `omScope` field
-3. `~/.mastracode/database.json` → `omScope` field
-
-### OM model settings
-
-The observer and reflector models default to `google/gemini-2.5-flash`. Override them per-thread through the `/settings` panel or in the harness state.
-
-### OM thresholds
-
-| Threshold             | Default       | Description                                   |
-| --------------------- | ------------- | --------------------------------------------- |
-| Observation threshold | 30,000 tokens | Token count that triggers an observation pass |
-| Reflection threshold  | 40,000 tokens | Token count that triggers a reflection pass   |
-
-## Color theme
-
-Mastra Code detects your terminal's color scheme and applies a matching dark or light theme. You can override the detected theme with the `/theme` slash command or the `MASTRA_THEME` environment variable.
-
-### Detection order
-
-1. `MASTRA_THEME` environment variable — explicit `dark` or `light`
-2. Persisted setting from `/theme` command (stored in `settings.json`)
-3. OSC 11 query — asks your terminal for its actual background color
-4. `COLORFGBG` environment variable (set by some terminals like iTerm2 and Konsole)
-5. Falls back to dark theme
-
-### Switching themes
-
-Use the `/theme` command to change the theme at runtime:
-
-```text
-/theme light
-/theme dark
-/theme auto
-```
-
-Running `/theme` with no arguments shows the current theme. The choice is persisted across sessions.
-
-## Environment variables
-
-| Variable               | Description                                                    |
-| ---------------------- | -------------------------------------------------------------- |
-| `MASTRA_DB_URL`        | LibSQL database URL (e.g., `libsql://...` or `file:./data.db`) |
-| `MASTRA_DB_AUTH_TOKEN` | Auth token for remote LibSQL database                          |
-| `MASTRA_DB_PATH`       | Override the local database file path                          |
-| `MASTRA_USER_ID`       | Override the auto-detected user identity                       |
-| `MASTRA_RESOURCE_ID`   | Override the auto-detected project resource ID                 |
-| `MASTRA_OM_SCOPE`      | Observational memory scope (`thread` or `resource`)            |
-| `DEFAULT_OM_MODEL_ID`  | Default model for OM observer and reflector                    |
-| `MASTRA_THEME`         | Color theme override (`dark` or `light`)                       |
-| `TAVILY_API_KEY`       | Enable Tavily-powered web search and extract tools             |
-
-## Resource ID override
-
-Resource IDs determine how threads are grouped. By default, Mastra Code generates one from the Git remote URL or filesystem path. Override it to share threads across repositories or isolate threads within a monorepo:
-
-```json
-{
-  "resourceId": "my-custom-project-id"
-}
-```
-
-You can also set `MASTRA_RESOURCE_ID` as an environment variable. Two users who set the same resource ID share threads and observations for that resource.

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

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

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