@mastra/mcp-docs-server 1.2.15 → 1.2.16-alpha.3

package/.docs/guides/guide/coding-agent.md

@@ -1,392 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Building a coding agent
-
-In this guide, you'll build a small coding-agent application in the same category as Mastra Code, Claude Code, or Codex. You'll create the coding agent with `buildBasePrompt()` and `createCodingAgent()`, wrap it in an `AgentController` for interactive sessions and tool approvals, and run the controller in a terminal UI built with pi-tui.
-
-The video below shows the coding agent you'll build in action.
-
-## Prerequisites
-
-- Node.js `v22.19.0` or later installed
-- An API key from a supported [Model Provider](https://mastra.ai/models)
-- An existing Mastra project. Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) if needed.
-
-## Install the terminal dependencies
-
-Install [pi-tui](https://github.com/earendil-works/pi/tree/main/packages/tui) and `tsx`:
-
-**npm**:
-
-```bash
-npm install @earendil-works/pi-tui
-npm install --save-dev tsx
-```
-
-**pnpm**:
-
-```bash
-pnpm add @earendil-works/pi-tui
-pnpm add --save-dev tsx
-```
-
-**Yarn**:
-
-```bash
-yarn add @earendil-works/pi-tui
-yarn add --dev tsx
-```
-
-**Bun**:
-
-```bash
-bun add @earendil-works/pi-tui
-bun add --dev tsx
-```
-
-pi-tui provides the terminal renderer and input editor. `tsx` runs the TypeScript entry point directly.
-
-## Create the coding agent
-
-Create `src/mastra/agents/coding-agent.ts`. The prompt describes the current project and maps the prompt's generic tool names to the tools supplied by the default workspace.
-
-```typescript
-import { basename } from 'node:path'
-import { buildBasePrompt, createCodingAgent } from '@mastra/core/coding-agent'
-
-export const projectPath = process.cwd()
-const model = 'openai/gpt-5.6-sol'
-
-const instructions = buildBasePrompt({
-  projectPath,
-  projectName: basename(projectPath),
-  platform: process.platform,
-  date: new Date().toISOString().slice(0, 10),
-  mode: 'build',
-  modelId: model,
-  productName: 'My Coding Agent',
-  coAuthorName: 'My Coding Agent',
-  coAuthorEmail: 'coding-agent@example.com',
-  toolGuidance: `# Workspace tools
-- Use mastra_workspace_read_file for view.
-- Use mastra_workspace_list_files for find_files.
-- Use mastra_workspace_grep for search_content.
-- Use mastra_workspace_execute_command for execute_command.
-- Use mastra_workspace_write_file, mastra_workspace_edit_file, and mastra_workspace_file_stat for writing, editing, and inspecting file metadata.
-- Use only the workspace tools provided to you. Do not attempt unavailable capabilities.`,
-})
-
-export const codingAgent = createCodingAgent({
-  id: 'coding-agent',
-  name: 'Coding Agent',
-  model,
-  instructions,
-  basePath: projectPath,
-})
-```
-
-Replace the branding values with the name and co-author details for your agent. `createCodingAgent()` supplies a local filesystem and sandbox workspace, along with defaults for recovering from transient provider errors. The `basePath` scopes the filesystem tools and sets the initial working directory for commands. Any configuration you pass to the factory takes precedence over its defaults.
-
-The default local sandbox runs commands directly on the host without isolation, so `basePath` isn't an operating-system security boundary. This example adds per-tool-call approval in the terminal, but you should still run it only against a trusted local project.
-
-## Register the coding agent
-
-Register the returned agent like any other Mastra agent in `src/mastra/index.ts`. Registration also makes the underlying agent available in Studio and through the Mastra server.
-
-```typescript
-import { Mastra } from '@mastra/core/mastra'
-import { codingAgent } from './agents/coding-agent'
-
-export const mastra = new Mastra({
-  agents: { codingAgent },
-})
-```
-
-## Test the coding agent
-
-Before adding the terminal interface, verify the underlying agent in Studio. When the development server starts, its working directory is `src/mastra/public`, so add a non-sensitive file there for the agent to inspect:
-
-```md
-# Project notes
-
-Name: Acme support portal
-Status: In development
-Owner: Platform team
-```
-
-Start the development server:
-
-**npm**:
-
-```bash
-npm run dev
-```
-
-**pnpm**:
-
-```bash
-pnpm run dev
-```
-
-**Yarn**:
-
-```bash
-yarn dev
-```
-
-**Bun**:
-
-```bash
-bun run dev
-```
-
-Open [Studio](https://mastra.ai/docs/studio/overview), select **Coding Agent**, and enter:
-
-```text
-Inspect project-notes.md and report the project name, status, and owner. Do not modify files.
-```
-
-The response should identify the Acme support portal and describe its development status. It should report that the Platform team owns the project and leave the file unchanged. Model wording may vary.
-
-## Create the agent controller
-
-Create `src/mastra/coding-agent-controller.ts`. The controller owns the interactive session, exposes UI events, and pauses workspace tools for approval.
-
-```typescript
-import { AgentController } from '@mastra/core/agent-controller'
-import { codingAgent, projectPath } from './agents/coding-agent'
-
-export async function createCodingAgentSession() {
-  const workspace = await codingAgent.getWorkspace()
-
-  if (!workspace) {
-    throw new Error('The coding agent requires a workspace.')
-  }
-
-  const controller = new AgentController({
-    id: 'coding-agent-controller',
-    agent: codingAgent,
-    workspace,
-    modes: [{ id: 'build', name: 'Build', metadata: { default: true } }],
-    disableBuiltinTools: [
-      'ask_user',
-      'submit_plan',
-      'task_write',
-      'task_update',
-      'task_complete',
-      'task_check',
-      'subagent',
-    ],
-  })
-
-  await controller.init()
-
-  const session = await controller.createSession({
-    id: 'local-session',
-    ownerId: 'local-user',
-    resourceId: projectPath,
-  })
-
-  return { controller, session }
-}
-```
-
-This example uses one mode and disables the controller's additional built-in tools so the introductory UI can focus on workspace execution. The simplified setup is intended for this tutorial. In a production application, enable the built-in tools your product needs and implement their UI flows: interactive tools such as `ask_user` and `submit_plan` suspend until your interface resumes them, while task and subagent tools have their own lifecycle events. See [tool approvals and suspensions](https://mastra.ai/docs/harness/agent-controller).
-
-The example also omits storage, so the conversation lasts only for the current process. You can add storage later when you want to resume sessions.
-
-## Build the terminal UI
-
-Create `src/coding-agent-tui.ts`. The UI renders assistant message updates and shows tool activity. It also asks the user to approve or decline each workspace tool call.
-
-```typescript
-import { pathToFileURL } from 'node:url'
-import {
-  Editor,
-  matchesKey,
-  ProcessTerminal,
-  Text,
-  TUI,
-  type EditorTheme,
-  type Terminal,
-} from '@earendil-works/pi-tui'
-import { createCodingAgentSession } from './mastra/coding-agent-controller'
-
-const plain = (text: string) => text
-const editorTheme: EditorTheme = {
-  borderColor: plain,
-  selectList: {
-    selectedPrefix: plain,
-    selectedText: plain,
-    description: plain,
-    scrollInfo: plain,
-    noMatch: plain,
-  },
-}
-
-function getText(message: { content: Array<{ type: string; text?: string }> }) {
-  return message.content
-    .filter(part => part.type === 'text')
-    .map(part => part.text ?? '')
-    .join('')
-}
-
-export async function startCodingAgentTui(terminal: Terminal = new ProcessTerminal()) {
-  const { controller, session } = await createCodingAgentSession()
-  const tui = new TUI(terminal)
-  const output = new Text('Ask me to inspect or change this project.', 1, 0)
-  const editor = new Editor(tui, editorTheme)
-
-  let busy = false
-  let pendingApproval: { toolCallId: string; toolName: string } | undefined
-
-  const showError = (error: unknown) => {
-    output.setText(`Error: ${error instanceof Error ? error.message : String(error)}`)
-    busy = false
-    pendingApproval = undefined
-    tui.requestRender()
-  }
-
-  const unsubscribe = session.subscribe(event => {
-    if (event.type === 'message_update' && event.message.role === 'assistant') {
-      output.setText(getText(event.message))
-    } else if (event.type === 'tool_start') {
-      output.setText(`Running ${event.toolName}...`)
-    } else if (event.type === 'tool_approval_required') {
-      pendingApproval = { toolCallId: event.toolCallId, toolName: event.toolName }
-      output.setText(`Allow ${event.toolName}? Enter y or n.`)
-    } else if (event.type === 'agent_end') {
-      busy = false
-    } else if (event.type === 'error') {
-      showError(event.error)
-      return
-    }
-
-    tui.requestRender()
-  })
-
-  editor.onSubmit = value => {
-    if (pendingApproval) {
-      const answer = value.trim().toLowerCase()
-      if (answer !== 'y' && answer !== 'n') {
-        output.setText(`Allow ${pendingApproval.toolName}? Enter y or n.`)
-        tui.requestRender()
-        return
-      }
-
-      const approval = pendingApproval
-      pendingApproval = undefined
-      session.respondToToolApproval({
-        toolCallId: approval.toolCallId,
-        decision: answer === 'y' ? 'approve' : 'decline',
-      })
-      return
-    }
-
-    if (busy || !value.trim()) return
-
-    busy = true
-    output.setText('Thinking...')
-    tui.requestRender()
-    void session.sendMessage({ content: value.trim() }).catch(showError)
-  }
-
-  tui.addChild(new Text('My Coding Agent', 1, 0))
-  tui.addChild(output)
-  tui.addChild(editor)
-  tui.setFocus(editor)
-
-  let stopPromise: Promise<void> | undefined
-  let removeInputListener = () => {}
-
-  const stop = () => {
-    stopPromise ??= (async () => {
-      process.off('SIGINT', handleExit)
-      removeInputListener()
-      session.abort()
-      unsubscribe()
-      tui.stop()
-      await controller.destroy()
-    })()
-    return stopPromise
-  }
-
-  const handleExit = () => {
-    void stop().catch(error => {
-      console.error(error)
-      process.exitCode = 1
-    })
-  }
-
-  removeInputListener = tui.addInputListener(data => {
-    if (!matchesKey(data, 'ctrl+c')) return
-    handleExit()
-    return { consume: true }
-  })
-  process.once('SIGINT', handleExit)
-  tui.start()
-
-  return { stop }
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  await startCodingAgentTui()
-}
-```
-
-The optional `Terminal` parameter supports automated tests while using `ProcessTerminal` during normal execution. The UI intentionally renders only the latest response. The `Session` still maintains the conversation context for follow-up prompts.
-
-## Run the coding agent
-
-Start the terminal application from the project root so `process.cwd()` points to the project you want the agent to use:
-
-**npm**:
-
-```bash
-npx tsx src/coding-agent-tui.ts
-```
-
-**pnpm**:
-
-```bash
-pnpm dlx tsx src/coding-agent-tui.ts
-```
-
-**Yarn**:
-
-```bash
-yarn dlx tsx src/coding-agent-tui.ts
-```
-
-**Bun**:
-
-```bash
-bun x tsx src/coding-agent-tui.ts
-```
-
-Enter this prompt:
-
-```text
-Inspect package.json and report the package name and available scripts. Do not modify files.
-```
-
-When the controller asks whether to allow `mastra_workspace_read_file`, enter `y`. The agent reads `package.json` and reports what it finds. Model wording varies, but the response should include the package name and its scripts without changing the file.
-
-Press **Ctrl+C** to close the application and destroy the controller.
-
-## Next steps
-
-You can extend this foundation to:
-
-- Add storage to persist and resume controller sessions
-- Add more modes with different instructions and workspace-tool allowlists
-- Replace the latest-response component with a transcript that renders tool calls and results
-- Add sandbox isolation before accepting untrusted prompts or distributing the application
-
-Learn more:
-
-- [`createCodingAgent()` reference](https://mastra.ai/reference/coding-agent/create-coding-agent)
-- [`buildBasePrompt()` reference](https://mastra.ai/reference/coding-agent/build-base-prompt)
-- [AgentController overview](https://mastra.ai/docs/harness/agent-controller)
-- [`AgentController` reference](https://mastra.ai/reference/agent-controller/agent-controller-class)
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/guides/guide/dev-assistant.md

@@ -1,309 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Building a dev assistant
-
-In this guide, you'll build a complete development assistant that combines all workspace features:
-
-- [Filesystem](https://mastra.ai/docs/workspace/filesystem) for file management
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox) for code execution
-- [Skills](https://mastra.ai/docs/workspace/skills) for coding standards
-- [Search](https://mastra.ai/docs/workspace/search) for finding examples
-
-You'll set up a workspace with a sample project and add coding standards as a skill. Then you'll create an agent that writes code following TDD practices. By the end, the agent can read existing code and write new implementations, then run tests in a sandbox and iterate based on the results.
-
-## Prerequisites
-
-- Node.js `v22.13.0` or later installed
-- An API key from a supported [Model Provider](https://mastra.ai/models)
-- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
-
-### Install vitest
-
-The dev assistant will use [Vitest](https://vitest.dev/) to run tests inside the workspace sandbox. Install it as a dev dependency in your project:
-
-**npm**:
-
-```bash
-npm install -D vitest
-```
-
-**pnpm**:
-
-```bash
-pnpm add -D vitest
-```
-
-**Yarn**:
-
-```bash
-yarn add --dev vitest
-```
-
-**Bun**:
-
-```bash
-bun add --dev vitest
-```
-
-## Set up the workspace
-
-The workspace uses a local filesystem to manage documentation files. The agent reads and writes files within the workspace directory. In your `src/mastra/index.ts` file, import the [`Workspace`](https://mastra.ai/reference/workspace/workspace-class), [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem), and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) classes.
-
-Additionally, enable BM25 search indexing and load skills from the `skills` directory.
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { resolve } from 'node:path'
-import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
-
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
-  sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
-  skills: ['skills'],
-  bm25: true,
-  autoIndexPaths: ['docs', 'src'],
-})
-
-export const mastra = new Mastra({
-  workspace,
-})
-```
-
-At the root of your project, create a new folder called `workspace`. This is where all files will be stored and managed by the agent.
-
-## Add sample project files
-
-The workspace uses the following folder structure:
-
-- `workspace/src/`: Source code for the sample project
-- `workspace/tests/`: Test files
-- `workspace/docs/`: Project documentation
-- `workspace/skills/`: Coding standards and guidelines as [Agent Skills](https://agentskills.io)
-
-Get started by creating a `workspace/src/utils/string-helpers.ts` file with some utility functions, and a corresponding test file in `workspace/tests/string-helpers.test.ts`.
-
-```typescript
-export function capitalize(str: string): string {
-  if (!str) return str
-  return str.charAt(0).toUpperCase() + str.slice(1)
-}
-
-export function slugify(str: string): string {
-  return str
-    .toLowerCase()
-    .replace(/[^\w\s-]/g, '')
-    .replace(/\s+/g, '-')
-}
-```
-
-```typescript
-import { describe, it, expect } from 'vitest'
-import { capitalize, slugify } from '../src/utils/string-helpers'
-
-describe('String Helpers', () => {
-  describe('capitalize', () => {
-    it('capitalizes first letter', () => {
-      expect(capitalize('hello')).toBe('Hello')
-    })
-  })
-
-  describe('slugify', () => {
-    it('converts to lowercase and replaces spaces', () => {
-      expect(slugify('Hello World')).toBe('hello-world')
-    })
-  })
-})
-```
-
-Create a skill definition at `workspace/skills/coding-standards/SKILL.md`. This tells the agent how to write and test code:
-
-```markdown
----
-name: coding-standards
-description: Project coding standards and testing guidelines
----
-
-# Coding Standards
-
-## Code quality
-
-- Functions under 50 lines
-- Use descriptive variable names
-- Always add TypeScript types
-
-## Testing
-
-- Test all exported functions
-- Use AAA pattern: Arrange, Act, Assert
-- Cover happy paths and edge cases
-
-## Before committing
-
-1. Write implementation
-2. Write comprehensive tests
-3. Run tests: `npm test`
-4. All tests must pass
-```
-
-Create a reference file at `workspace/skills/coding-standards/references/testing-guide.md` with detailed testing patterns:
-
-````markdown
-# Testing Guide
-
-## AAA pattern
-
-```typescript
-it('descriptive test name', () => {
-  // Arrange: Set up test data
-  const input = 'test'
-
-  // Act: Execute the function
-  const result = doSomething(input)
-
-  // Assert: Verify the result
-  expect(result).toBe('expected')
-})
-```
-
-## What to test
-
-- Happy paths (normal inputs)
-- Edge cases (empty, null, boundary values)
-- Error cases (invalid inputs, exceptions)
-````
-
-## Create the dev assistant
-
-With the workspace set up, it's time to create the development assistant agent. This agent will have instructions for adding new features using test-driven development (TDD).
-
-Create a new file `src/mastra/agents/dev-assistant.ts` and define the agent:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-
-export const devAssistant = new Agent({
-  id: 'dev-assistant',
-  name: 'Dev Assistant',
-  instructions: `You are a development assistant.
-
-When adding features:
-1. Activate 'coding-standards' skill
-2. Search workspace for similar code examples
-3. Write the implementation following standards
-4. Write comprehensive tests. Leave existing tests in place, only add your new tests
-5. Execute the command \`npx vitest run\` to validate that all tests pass
-6. Update documentation if needed
-
-For every new feature: Write code → Write tests → Run tests → Update docs
-
-Always explain your reasoning and steps.`,
-  model: 'openai/gpt-5.6-sol',
-})
-```
-
-Define the agent by importing it inside `src/mastra/index.ts` and registering it with the `Mastra` instance:
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { resolve } from 'node:path'
-import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
-import { devAssistant } from './agents/dev-assistant'
-
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
-  sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
-  skills: ['skills'],
-  bm25: true,
-  autoIndexPaths: ['docs', 'src'],
-})
-
-export const mastra = new Mastra({
-  workspace,
-  agents: { devAssistant },
-})
-```
-
-## Test the assistant
-
-Start [Studio](https://mastra.ai/docs/studio/overview) and interact with the agent to see it in action.
-
-**npm**:
-
-```bash
-npm run dev
-```
-
-**pnpm**:
-
-```bash
-pnpm run dev
-```
-
-**Yarn**:
-
-```bash
-yarn dev
-```
-
-**Bun**:
-
-```bash
-bun run dev
-```
-
-Open [localhost:4111](http://localhost:4111) and navigate to the dev assistant.
-
-Try asking the agent to add a new function using TDD:
-
-```text
-Add a 'truncate' function to string-helpers.ts that shortens strings to a max length. Add '...' if truncated.
-
-Follow TDD: write tests first, then implementation.
-```
-
-Since agent responses are non-deterministic, the exact output will vary. However, you should see the agent follow a process similar to this:
-
-1. Activate the coding-standards skill
-
-2. Search the workspace for similar code patterns
-
-3. Write tests first, for example:
-
-   ```typescript
-   describe('truncate', () => {
-     it('truncates long strings', () => {
-       expect(truncate('Hello World', 5)).toBe('He...')
-     })
-
-     it('keeps short strings unchanged', () => {
-       expect(truncate('Hi', 10)).toBe('Hi')
-     })
-
-     it('handles edge cases', () => {
-       expect(truncate('', 5)).toBe('')
-     })
-   })
-   ```
-
-4. Write the implementation, for example:
-
-   ```typescript
-   export function truncate(str: string, maxLength: number): string {
-     if (!str || maxLength < 0) return str
-     if (str.length <= maxLength) return str
-     if (maxLength === 0) return '...'
-     return str.slice(0, maxLength - 3) + '...'
-   }
-   ```
-
-5. Run tests and verify they pass
-
-## Next steps
-
-You can extend this assistant to:
-
-- Add more skills for different languages or frameworks
-- Create specialized agents for backend, frontend, or DevOps
-- Integrate with GitHub for automated PR reviews
-- Build CI/CD automation
-- Add multi-agent workflows