@mastra/mcp-docs-server 1.2.15-alpha.20 → 1.2.15-alpha.21

package/.docs/docs/observability/integrations/exporters/datadog.md

@@ -1,321 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Datadog exporter
-
-[Datadog](https://datadoghq.com/) is a complete monitoring platform with dedicated LLM Observability features. The Datadog exporter sends your traces to Datadog's LLM Observability product, providing insights into model performance and token usage, plus conversation flows.
-
-> **Also using dd-trace APM?:** If you also use `dd-trace` APM auto-instrumentation, consider the [Datadog Bridge](https://mastra.ai/docs/observability/integrations/bridges/datadog) instead. The bridge creates `dd-trace` spans in real time so HTTP and database calls inside tools and processors are correctly nested under their parent Mastra span. The exporter on its own sends LLM Observability data after execution completes, which means auto-instrumented APM spans fall back to the request handler.
-
-## Installation
-
-**npm**:
-
-```bash
-npm install @mastra/datadog@latest
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/datadog@latest
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/datadog@latest
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/datadog@latest
-```
-
-## Configuration
-
-### Prerequisites
-
-1. **Datadog Account**: Sign up at [datadoghq.com](https://datadoghq.com/) with LLM Observability enabled
-2. **API Key**: Get your API key from Datadog Organization Settings → API Keys
-3. **Environment Variables**: Set your credentials
-
-```bash
-DD_API_KEY=your-datadog-api-key
-DD_LLMOBS_ML_APP=my-llm-app
-DD_SITE=datadoghq.com  # Optional: defaults to datadoghq.com
-DD_ENV=production      # Optional: environment name
-```
-
-### Zero-Config Setup
-
-With environment variables set, use the exporter with no configuration:
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { Observability } from '@mastra/observability'
-import { DatadogExporter } from '@mastra/datadog'
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      datadog: {
-        serviceName: 'my-service',
-        exporters: [new DatadogExporter()],
-      },
-    },
-  }),
-})
-```
-
-### Explicit Configuration
-
-You can also pass credentials directly (takes precedence over environment variables):
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { Observability } from '@mastra/observability'
-import { DatadogExporter } from '@mastra/datadog'
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      datadog: {
-        serviceName: 'my-service',
-        exporters: [
-          new DatadogExporter({
-            mlApp: process.env.DD_LLMOBS_ML_APP!,
-            apiKey: process.env.DD_API_KEY!,
-          }),
-        ],
-      },
-    },
-  }),
-})
-```
-
-## Configuration options
-
-### Complete Configuration
-
-```typescript
-new DatadogExporter({
-  // Required settings
-  mlApp: process.env.DD_LLMOBS_ML_APP!, // Groups traces under this ML app name
-  apiKey: process.env.DD_API_KEY!, // Required for agentless mode (default)
-
-  // Optional settings
-  site: 'datadoghq.com', // Datadog site (datadoghq.eu, us3.datadoghq.com, etc.)
-  service: 'my-service', // Service name (defaults to mlApp)
-  env: 'production', // Environment name
-  agentless: true, // true = direct HTTPS, false = local Datadog Agent
-
-  // Advanced settings
-  integrationsEnabled: false, // Enable dd-trace auto-instrumentation
-
-  // Diagnostic logging
-  logLevel: 'info', // debug | info | warn | error
-})
-```
-
-### With Local Datadog Agent
-
-If you have a Datadog Agent running locally, you can route traces through it instead of direct HTTPS:
-
-```typescript
-new DatadogExporter({
-  mlApp: process.env.DD_LLMOBS_ML_APP!,
-  agentless: false, // Use local Datadog Agent
-  env: 'production',
-})
-```
-
-Note: When using agent mode, the API key is read from the local agent's configuration.
-
-## Span type mapping
-
-Mastra span types are automatically mapped to Datadog LLM Observability span kinds:
-
-| Mastra SpanType      | Datadog Kind |
-| -------------------- | ------------ |
-| `AGENT_RUN`          | `agent`      |
-| `MODEL_GENERATION`   | `workflow`   |
-| `MODEL_STEP`         | `llm`        |
-| `TOOL_CALL`          | `tool`       |
-| `MCP_TOOL_CALL`      | `tool`       |
-| `WORKFLOW_RUN`       | `workflow`   |
-| Other workflow types | `task`       |
-| `GENERIC`            | `task`       |
-
-Other/future Mastra span types will default to 'task' when mapped unless specified.
-
-## Application Performance Monitoring
-
-The sections above cover Mastra's [LLM Observability](https://docs.datadoghq.com/llm_observability/) integration. To trace your Mastra HTTP server routes (request latency, error tracking, service maps), use `dd-trace` directly for Datadog Application Performance Monitoring (APM).
-
-### Prerequisites
-
-1. **Datadog Agent**: Install a [Datadog Agent](https://docs.datadoghq.com/agent/) on the same host or accessible via network. The agent receives traces from `dd-trace` on `localhost:8126` and forwards them to Datadog. Follow the [agent installation guide](https://docs.datadoghq.com/agent/) to set it up.
-
-2. **dd-trace package**: Install the tracing library in your project:
-
-   **npm**:
-
-   ```bash
-   npm install dd-trace
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm add dd-trace
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn add dd-trace
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun add dd-trace
-   ```
-
-> **Note:** APM traces always route through the Datadog Agent. This is different from LLM Observability, which supports agentless mode (direct HTTPS to Datadog).
-
-### APM only
-
-Import and initialize `dd-trace` at the top of your entry file, before any other imports:
-
-```typescript
-import tracer from 'dd-trace'
-
-tracer.init({
-  service: process.env.DD_SERVICE || 'my-mastra-app',
-  env: process.env.DD_ENV || 'production',
-  version: process.env.DD_VERSION,
-})
-
-import { Mastra } from '@mastra/core'
-
-export const mastra = new Mastra({
-  bundler: {
-    externals: [
-      'dd-trace',
-      '@datadog/native-metrics',
-      '@datadog/native-appsec',
-      '@datadog/native-iast-taint-tracking',
-      '@datadog/pprof',
-    ],
-  },
-})
-```
-
-Set the tracer metadata environment variables:
-
-```bash
-DD_SERVICE=my-mastra-app
-DD_ENV=production
-DD_VERSION=1.0.0
-```
-
-`dd-trace` auto-instruments popular HTTP frameworks, including those supported by Mastra's [server adapters](https://mastra.ai/docs/server/server-adapters). Inbound requests, outbound HTTP calls, and database queries appear as APM traces in Datadog.
-
-### APM and LLM Observability
-
-Import and initialize `dd-trace` before creating the Mastra instance. The `DatadogExporter` detects the existing tracer and skips re-initialization, adding LLM Observability on top of your APM setup:
-
-```typescript
-import tracer from 'dd-trace'
-
-tracer.init({
-  service: process.env.DD_SERVICE || 'my-mastra-app',
-  env: process.env.DD_ENV || 'production',
-  version: process.env.DD_VERSION,
-})
-
-import { Mastra } from '@mastra/core'
-import { Observability } from '@mastra/observability'
-import { DatadogExporter } from '@mastra/datadog'
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      datadog: {
-        serviceName: 'my-mastra-app',
-        exporters: [
-          new DatadogExporter({
-            mlApp: process.env.DD_LLMOBS_ML_APP!,
-            apiKey: process.env.DD_API_KEY!,
-          }),
-        ],
-      },
-    },
-  }),
-  bundler: {
-    externals: [
-      'dd-trace',
-      '@datadog/native-metrics',
-      '@datadog/native-appsec',
-      '@datadog/native-iast-taint-tracking',
-      '@datadog/pprof',
-    ],
-  },
-})
-```
-
-```bash
-DD_SERVICE=my-mastra-app
-DD_ENV=production
-DD_VERSION=1.0.0
-DD_API_KEY=your-datadog-api-key
-DD_LLMOBS_ML_APP=my-llm-app
-```
-
-Server routes appear as APM traces and LLM calls appear as LLM Observability spans, all under the same service in Datadog.
-
-> **Note:** Import and initialize `dd-trace` before all other modules. This allows its auto-instrumentation to patch HTTP, database, and framework libraries at load time.
-
-## Troubleshooting
-
-### Native module ABI mismatch
-
-If you see errors like:
-
-```text
-Error: No native build was found for runtime=node abi=137 platform=linuxglibc arch=x64
-```
-
-This indicates a Node.js version compatibility issue with `dd-trace`'s native modules. These native modules are **optional** and provide performance monitoring features.
-
-**Solutions:**
-
-1. **Use Node.js 22.x**: Native modules have the best compatibility with Node.js 22.x.
-
-2. **Ignore native module warnings**: The native modules (`@datadog/native-metrics`, `@datadog/native-appsec`, etc.) are optional. If they fail to load, core tracing functionality still works.
-
-### Bundler externals configuration
-
-When using bundlers like esbuild, webpack, or the Mastra CLI bundler, you may need to mark `dd-trace` and its dependencies as external:
-
-```typescript
-export const mastra = new Mastra({
-  bundler: {
-    externals: [
-      'dd-trace',
-      '@datadog/native-metrics',
-      '@datadog/native-appsec',
-      '@datadog/native-iast-taint-tracking',
-      '@datadog/pprof',
-    ],
-  },
-})
-```
-
-## Related
-
-- [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
-- [Datadog LLM Observability documentation](https://docs.datadoghq.com/llm_observability/)
-- [Datadog APM documentation](https://docs.datadoghq.com/tracing/)

package/.docs/guides/build-your-ui/copilotkit/channels.md

@@ -1,86 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# CopilotKit channels
-
-The same Mastra agent that powers your in-app copilot can also run as a bot in messaging platforms. CopilotKit's Channels SDK connects your agent to Slack and other messaging platforms, with threads, tool calls, rich interactive messages, and human-in-the-loop approvals handled natively in the channel.
-
-> **Note:** Full platform setup lives in the [CopilotKit Channels documentation](https://docs.copilotkit.ai/slack/mastra). This page shows how Channels fit together with a Mastra agent.
-
-## How it fits together
-
-Your Mastra agent stays where it's deployed, exposed over AG-UI through `registerCopilotKit()` (see [CopilotKit overview](https://mastra.ai/guides/build-your-ui/copilotkit/overview)). A channel is a separate long-running process built with `@copilotkit/channels`: you attach one or more platform adapters and point the channel at your agent. `createChannel` takes an array of adapters, so a single process can serve several platforms at once.
-
-Install the SDK (batteries-included, every adapter):
-
-**npm**:
-
-```bash
-npm install @copilotkit/channels
-```
-
-**pnpm**:
-
-```bash
-pnpm add @copilotkit/channels
-```
-
-**Yarn**:
-
-```bash
-yarn add @copilotkit/channels
-```
-
-**Bun**:
-
-```bash
-bun add @copilotkit/channels
-```
-
-```typescript
-import { createChannel, Message, Section } from '@copilotkit/channels'
-import { slack } from '@copilotkit/channels/slack'
-import { mastraAgent } from './agent' // your AG-UI Mastra agent
-
-const channel = createChannel({
-  // Point the channel at your Mastra agent (an AbstractAgent, or a per-thread factory).
-  agent: mastraAgent,
-  adapters: [
-    slack({
-      botToken: process.env.SLACK_BOT_TOKEN!,
-      appToken: process.env.SLACK_APP_TOKEN!,
-    }),
-  ],
-})
-
-channel.onMention(async ({ thread }) => {
-  await thread.runAgent()
-})
-
-await channel.start()
-```
-
-The agent receives ordinary AG-UI input and emits ordinary AG-UI events; the platform mechanics stay behind the adapter, so the same Mastra agent runs unchanged across every channel. Rich messages are written as JSX and rendered to each platform's native format (Block Kit on Slack, for example), so an interactive card degrades gracefully where a platform has no equivalent.
-
-## Slack
-
-The [Slack quickstart](https://docs.copilotkit.ai/slack/mastra) takes you from zero to a bot you can `@`-mention in a channel, then adds an interactive button card. Slack runs over Socket Mode, which opens an outbound WebSocket to Slack, so no public URL or tunnel is required during development.
-
-Set the Slack credentials in your environment:
-
-- `SLACK_BOT_TOKEN`: Bot User OAuth token (`xoxb-...`)
-- `SLACK_APP_TOKEN`: App-level token with the `connections:write` scope (`xapp-...`)
-
-## Other platforms
-
-The Channels SDK isn't limited to Slack. Other platforms like Microsoft Teams run through the same `@copilotkit/channels` API: add the matching adapter to the `adapters` array and the rest of your agent code stays the same. See the [CopilotKit Channels documentation](https://docs.copilotkit.ai/slack/mastra) for the current platform list and per-platform setup.
-
-## Message pipeline and architecture
-
-Managed channels keep a deliberate credential split, which matters when your Mastra agent uses separate model keys and tools:
-
-- **You keep** the agent logic, model credentials, tools, and the channel process.
-- **CopilotKit Intelligence holds** the platform credentials, message delivery, registration, health, and reconnects.
-
-A turn begins when a user messages the app. Intelligence receives the platform event, and the gateway delivers the turn to your running channel process. Your Mastra agent runs and renders a reply. Intelligence then returns the reply as native platform content. Platform credentials never enter the agent process, and enterprise Intelligence can be self-hosted for data residency.
-
-> **Note:** By default, interactive actions live in memory and reset on restart. Back the channel with a durable action and state store (Redis or Postgres) so buttons and per-thread state survive restarts and span multiple instances.

package/.docs/guides/build-your-ui/copilotkit/generative-ui.md

@@ -1,174 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# CopilotKit generative UI
-
-Generative UI describes interfaces that agents help create and that users can interact with. CopilotKit organizes these interfaces along a single axis, the **generative UI spectrum**, which runs from author-controlled (you decide every pixel) to agent-invented (the agent owns the rendered surface). Your position on the axis is a trade-off between predictability and breadth.
-
-The spectrum has three tiers:
-
-| Tier            | Who controls the surface                                                                   | Primitives                                                           |
-| --------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| **Controlled**  | You wrote the component. The agent picks which one to use and what data to pass.           | Tool call rendering, state rendering, reasoning, components as tools |
-| **Declarative** | The agent emits a structured spec. The frontend composes it from a catalog you registered. | A2UI (fixed-schema and flexible variants)                            |
-| **Open-ended**  | The UI is invented elsewhere (an MCP server) and you sandbox it.                           | MCP Apps                                                             |
-
-Each tier is a Mastra agent exposed through `registerCopilotKit()` (see [CopilotKit overview](https://mastra.ai/guides/build-your-ui/copilotkit/overview)) plus the matching CopilotKit hook on the frontend. For the full concept, see CopilotKit's [generative UI spectrum](https://www.copilotkit.ai/generative-ui-spectrum) and [generative UI overview](https://docs.copilotkit.ai/concepts/generative-ui-overview).
-
-> **Tip:** Mastra's [UI Dojo](https://ui-dojo.mastra.ai/) has working CopilotKit examples. Browse the source under `src/pages/copilot-kit`.
-
-## Controlled
-
-You provide a fixed set of components. The agent chooses which component to render and supplies its data. This predictable, brand-safe approach works well for high-traffic surfaces. The Controlled primitives use CopilotKit's v2 API, imported from `@copilotkit/react-core/v2`.
-
-### Tool call rendering
-
-Render an agent's tool call as a React component. Define the agent and tool on the Mastra server as usual:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { weatherTool } from '../tools/weather-tool'
-
-export const weatherAgent = new Agent({
-  id: 'weather-agent',
-  name: 'Weather Agent',
-  instructions: 'Use the weatherTool to fetch current weather data.',
-  model: 'openai/gpt-5.6-sol',
-  tools: { weatherTool },
-})
-```
-
-On the frontend, register a renderer for the tool by name with `useRenderTool`. It's render-only (it doesn't execute the tool); the `render` function receives the tool call's `status` and, once the agent returns, its `result`:
-
-```tsx
-import { z } from 'zod'
-import { CopilotChat } from '@copilotkit/react-ui'
-import { CopilotKit, useRenderTool } from '@copilotkit/react-core/v2'
-import { Weather } from '@/components/weather'
-
-function Chat() {
-  useRenderTool(
-    {
-      name: 'weatherTool',
-      parameters: z.object({ location: z.string() }),
-      render: ({ status, result }) => {
-        if (status !== 'complete') {
-          return <div>Retrieving weather...</div>
-        }
-        return <Weather {...result} />
-      },
-    },
-    [],
-  )
-
-  return <CopilotChat labels={{ title: 'Weather Assistant' }} />
-}
-
-export default function Page() {
-  return (
-    <CopilotKit runtimeUrl="http://localhost:4111/copilotkit" agent="weatherAgent">
-      <Chat />
-    </CopilotKit>
-  )
-}
-```
-
-Because Mastra streams tool-call arguments incrementally, the `render` function is called repeatedly as the arguments arrive, so the UI can paint progressively while the agent works.
-
-### Components as tools
-
-Register a React component and let the agent call it as a tool. CopilotKit renders it inline with typed props (defined with a Zod schema):
-
-```tsx
-import { z } from 'zod'
-import { useComponent } from '@copilotkit/react-core/v2'
-
-const schema = z.object({ text: z.string() })
-
-function Callout({ text }: z.infer<typeof schema>) {
-  return <div className="callout">{text}</div>
-}
-
-function Chat() {
-  useComponent({ name: 'callout', render: Callout, parameters: schema }, [])
-  return <CopilotChat labels={{ title: 'Assistant' }} />
-}
-```
-
-The agent invokes `callout` like any other tool, and CopilotKit renders `Callout` with the props it passed.
-
-### State rendering
-
-Render UI from the agent's state and re-render as it streams. On Mastra, agent state is the agent's working memory, streamed to the client as it changes. Read it with `useAgent`; `agent.state` is reactive, so the component updates automatically:
-
-```tsx
-import { useAgent } from '@copilotkit/react-core/v2'
-
-function TaskBoard() {
-  const { agent } = useAgent()
-  const tasks = (agent.state.tasks as any[]) ?? []
-
-  return (
-    <ul>
-      {tasks.map((task, i) => (
-        <li key={i}>
-          {task.title}: {task.status}
-        </li>
-      ))}
-    </ul>
-  )
-}
-```
-
-### Reasoning
-
-Reasoning is zero-config: when your Mastra agent runs a reasoning-capable model, `CopilotChat` renders the model's thinking inline as a dedicated message type, with no extra code. To restyle it, pass your own component to the `reasoningMessage` slot on `CopilotChat`. See CopilotKit's [generative UI guides](https://docs.copilotkit.ai/) for details.
-
-## Declarative
-
-Instead of a fixed component per tool, you register a catalog of typed building blocks and the agent assembles them into a UI tree per request. CopilotKit calls this **A2UI** (Agent-to-UI), which has fixed-schema and flexible variants. It suits the long tail of secondary interactions where breadth matters more than pixel-perfection.
-
-The path of least resistance is to pass your catalog to the `<CopilotKit>` provider. That single prop enables A2UI rendering and injects the A2UI tool into your agent, so no backend change is needed:
-
-```tsx
-import { CopilotKit } from '@copilotkit/react-core/v2'
-import { myCatalog } from './a2ui-catalog'
-
-export default function Page() {
-  return (
-    <CopilotKit
-      runtimeUrl="http://localhost:4111/copilotkit"
-      agent="weatherAgent"
-      a2ui={{ catalog: myCatalog }}
-    >
-      {/* your app */}
-    </CopilotKit>
-  )
-}
-```
-
-The catalog defines the primitives (their schemas) and the renderers (how each primitive displays). In the fixed-schema variant, the components are pre-authored and the agent's tool only supplies data. The flexible variant lets the agent compose the tree more freely. See CopilotKit's [A2UI documentation](https://docs.copilotkit.ai/a2a/generative-ui/a2ui).
-
-## Open-ended
-
-At the far end of the spectrum, the agent owns the entire surface: the UI is invented elsewhere and sandboxed in your app. CopilotKit supports this through **MCP Apps**, where an MCP server provides UI that renders inside your application. This tier trades determinism for novelty and is the most experimental point on the spectrum.
-
-The path of least resistance keeps the frontend untouched: your existing `<CopilotKit>` provider is enough. On the backend, point `registerCopilotKit()` at one or more MCP servers with the `mcpApps` option (it's forwarded to the CopilotKit runtime):
-
-```typescript
-registerCopilotKit({
-  path: '/copilotkit',
-  resourceId: 'weatherAgent',
-  mcpApps: {
-    servers: [{ type: 'http', url: 'http://localhost:3108/mcp', serverId: 'my-server' }],
-  },
-})
-```
-
-When the agent calls an MCP App tool, CopilotKit fetches and renders that tool's UI in the chat with no additional frontend code. See CopilotKit's [MCP Apps documentation](https://docs.copilotkit.ai/agno/generative-ui/mcp-apps).
-
-## App control and interactivity
-
-Some capabilities sit next to the spectrum rather than on it: they control your app or gate a run instead of rendering agent output. Both are covered in [Get started](https://mastra.ai/guides/build-your-ui/copilotkit/overview):
-
-- **Frontend tools** (`useFrontendTool`): let the agent act on your application. This is part of CopilotKit's separate [App Control](https://docs.copilotkit.ai/) concept, alongside shared state and agent context.
-- **Human-in-the-loop**: pause a run and wait for user approval or edits. Backend side, see Mastra's [Agent approval](https://mastra.ai/docs/agents/agent-approval); frontend side, see CopilotKit's [`useHumanInTheLoop`](https://docs.copilotkit.ai/reference/hooks/useHumanInTheLoop).