@mastra/mcp-docs-server 1.2.7-alpha.1 → 1.2.7-alpha.10

package/.docs/docs/capabilities/channels/overview.md

@@ -0,0 +1,255 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Channels overview
+
+**Added in:** `@mastra/core@1.22.0`
+
+Channels connect agents to messaging and collaboration platforms like Slack, Microsoft Teams, Discord, Telegram, WhatsApp, GitHub, and Linear. When a user sends a message or comment on a platform, the agent receives it, processes it through the normal agent pipeline, and streams the response back to the conversation. Mastra uses [Chat SDK](https://chat-sdk.dev/) for this channel layer.
+
+Start with the page for your platform:
+
+- [Slack](https://mastra.ai/docs/capabilities/channels/slack)
+- [Microsoft Teams](https://mastra.ai/docs/capabilities/channels/teams)
+- [Discord](https://mastra.ai/docs/capabilities/channels/discord)
+- [Telegram](https://mastra.ai/docs/capabilities/channels/telegram)
+- [WhatsApp](https://mastra.ai/docs/capabilities/channels/whatsapp)
+
+[More](https://mastra.ai/docs/capabilities/channels/other-adapters) lists additional platforms. Mastra channels work with compatible [Chat SDK adapters](https://chat-sdk.dev/adapters) beyond the platforms listed here, and the same Mastra configuration pattern applies across adapters.
+
+## When to use channels
+
+Use channels when an agent needs to:
+
+- Meet users where they already talk or work.
+- Respond in chat platforms like Slack, Microsoft Teams, Discord, Telegram, and WhatsApp.
+- Support multiplayer agents where several people interact with the same agent in a shared channel or thread.
+- Integrate with collaboration workflows like GitHub issues, pull request threads, and Linear comments.
+
+## Configure an agent
+
+Channels use Chat SDK adapters and follow the same Mastra-side pattern: create a channel adapter and add it to the agent.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSlackAdapter } from '@chat-adapter/slack'
+
+export const yourAgent = new Agent({
+  id: 'your-agent',
+  name: 'Your Agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5.5',
+  channels: {
+    adapters: {
+      slack: createSlackAdapter(),
+    },
+  },
+})
+```
+
+> **Note:** Channel adapters require provider-specific environment variables for credentials and request verification, such as bot tokens, signing secrets, app IDs, and webhook verification tokens. Check the guide for your platform or the [Chat SDK adapter catalog](https://chat-sdk.dev/adapters) for the exact variable names.
+
+We recommend configuring [storage](https://mastra.ai/docs/storage/overview) for channels. Storage lets Mastra persist channel state, thread subscriptions, tool approvals, and memory across restarts:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+import { yourAgent } from './agents/your-agent'
+
+export const mastra = new Mastra({
+  agents: { yourAgent },
+  storage: new LibSQLStore({
+    url: process.env.DATABASE_URL,
+  }),
+})
+```
+
+## Webhook routes
+
+Platforms send channel activity to Mastra through webhooks. A webhook is an HTTP endpoint that the platform calls when something happens, such as a new message, a mention, or a user selecting "Approve" on an interactive tool approval card. This is how your agent receives a new message, starts processing it, and responds in the same channel.
+
+Mastra registers a webhook route for each configured adapter and handles the request for you:
+
+```text
+/api/agents/<AGENT_ID>/channels/<PLATFORM>/webhook
+```
+
+For example, a Slack adapter on an agent with the `your-agent` ID uses:
+
+```text
+/api/agents/your-agent/channels/slack/webhook
+```
+
+Point the platform's webhook, event, or interactions URL to this path. Follow the guide for your platform or the [Chat SDK docs](https://chat-sdk.dev/adapters).
+
+During local development, platform webhooks need a public URL to reach your local server. Use a tunnel like [cloudflared](https://github.com/cloudflare/cloudflared) or [ngrok](https://ngrok.com/) to expose your server, `localhost:4111` by default:
+
+**npm**:
+
+```bash
+npx cloudflared tunnel --url http://localhost:4111
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx cloudflared tunnel --url http://localhost:4111
+```
+
+**Yarn**:
+
+```bash
+yarn dlx cloudflared tunnel --url http://localhost:4111
+```
+
+**Bun**:
+
+```bash
+bun x cloudflared tunnel --url http://localhost:4111
+```
+
+Use the generated public URL as the base URL for webhook paths, for example `https://abc123.trycloudflare.com/api/agents/your-agent/channels/slack/webhook`.
+
+> **Note:** Tunnel URLs are for local development. After you deploy the Mastra server, update the platform's webhook, event, or interactions URL to your production URL.
+
+## Thread context
+
+When a user mentions the agent mid-conversation in a channel thread, the agent may not have prior context. By default, Mastra fetches the last 10 messages from the platform on the first mention.
+
+1. On the first mention in a thread, the agent fetches recent messages from the platform.
+2. These messages are prepended to the user's message as conversation context.
+3. After responding, the agent subscribes to the thread and has full history through Mastra memory.
+4. Subsequent messages in that thread don't re-fetch from the platform.
+
+Set `threadContext: { maxMessages: 0 }` to disable this behavior. This only applies to non-direct message threads.
+
+Mastra also adds a short system message that tells the agent which channel and platform the request came from, such as whether the message came from a direct message or public channel. Set `threadContext: { addSystemMessage: false }` to skip it.
+
+## Tool approval
+
+Tools with `requireApproval: true` render as interactive cards with Approve and Deny buttons:
+
+```typescript
+import { promises as fs } from 'node:fs'
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const deleteFile = createTool({
+  id: 'delete-file',
+  description: 'Delete a file from the system',
+  inputSchema: z.object({
+    path: z.string().describe('Path to the file to delete'),
+  }),
+  requireApproval: true,
+  execute: async ({ path }) => {
+    await fs.unlink(path)
+    return { deleted: path }
+  },
+})
+```
+
+When the agent calls this tool, users see a card with the tool name, arguments, and Approve and Deny actions. The tool only executes after approval.
+
+Set `toolDisplay: 'text'` on an adapter to render tool calls as plain text instead of interactive cards. In `'hidden'` mode, `autoResumeSuspendedTools` can resume suspended tools when a later user message arrives on the same thread. This requires memory. Hidden mode only suppresses the approval buttons.
+
+## Multi-user awareness
+
+In group conversations, Mastra prefixes each message with the sender's name and platform ID so the agent can distinguish between speakers:
+
+```text
+[Alice (@U123ABC)]: Can you help me with this?
+[Bob (@U456DEF)]: I have a question too.
+```
+
+## Multimodal content
+
+Models like Gemini can process images, video, and audio natively. Combine `inlineMedia` and `inlineLinks` to let users share rich content with your agent across platforms:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createDiscordAdapter } from '@chat-adapter/discord'
+
+export const visionAgent = new Agent({
+  id: 'vision-agent',
+  name: 'Vision Agent',
+  instructions: 'You can see images, watch videos, and listen to audio.',
+  model: 'google/gemini-2.5-flash',
+  channels: {
+    adapters: {
+      discord: createDiscordAdapter(),
+    },
+    inlineMedia: ['image/*', 'video/*', 'audio/*'],
+    inlineLinks: [
+      { match: 'youtube.com', mimeType: 'video/*' },
+      { match: 'youtu.be', mimeType: 'video/*' },
+      'imgur.com',
+    ],
+  },
+})
+```
+
+With this configuration:
+
+- A user uploads a screenshot and the agent describes what it sees.
+- A user uploads an `.mp4` clip and the agent summarizes the video.
+- A user pastes a YouTube link and the agent watches and discusses the video.
+- A user pastes an imgur link and the agent sees the image directly.
+
+By default, only images are sent inline (`inlineMedia: ['image/*']`). Unsupported types are described as text summaries so the agent knows about the file without failing on models that reject them. See [Channels reference](https://mastra.ai/reference/agents/channels) for all `inlineMedia` patterns and [inlineLinks reference](https://mastra.ai/reference/agents/channels) for domain matching, HEAD detection, and forced MIME types.
+
+## Serverless deployment
+
+On serverless platforms like Vercel, each request runs in a separate, short-lived instance. Channels need two things to work reliably in that environment: a way to keep the function alive while the agent responds, and a shared pub/sub so instances can coordinate.
+
+### Keep the function alive with `waitUntil`
+
+A channel webhook returns a `200` response right away, then the agent runs in the background to post its reply. On most serverless platforms the function is frozen as soon as it responds, which stops the run before the agent answers. Pass a `waitUntil` function so the platform keeps the instance alive until the run finishes.
+
+On Vercel, pass `waitUntil` from `@vercel/functions`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSlackAdapter } from '@chat-adapter/slack'
+import { waitUntil } from '@vercel/functions'
+
+export const yourAgent = new Agent({
+  id: 'your-agent',
+  name: 'Your Agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5.5',
+  channels: {
+    adapters: {
+      slack: createSlackAdapter(),
+    },
+    waitUntil,
+  },
+})
+```
+
+Vercel and AWS Lambda require `waitUntil`, since they freeze the function as soon as the response is sent. Cloudflare Workers and Netlify Functions are detected automatically from the request context, so they don't need it. For runtimes where `waitUntil` lives on the request context but isn't detected automatically, use `resolveWaitUntil`. See the [Channels reference](https://mastra.ai/reference/agents/channels) for details.
+
+### Coordinate instances with a shared pub/sub
+
+Channels route messages through the agent's [signal pipeline](https://mastra.ai/docs/long-running-agents/signals), and each run acquires a lease on its thread so one run owns the conversation at a time. The default in-memory pub/sub can't cross instance boundaries, so on serverless a follow-up message can land on a different instance than the one running the agent. Without a shared pub/sub, that instance can't reach the active run and starts its own, leaving the original run untouched and the thread processed twice.
+
+Configure a shared pub/sub backed by Redis Streams on the `Mastra` instance so leases and signals coordinate across instances:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RedisStreamsPubSub } from '@mastra/redis-streams'
+import { yourAgent } from './agents/your-agent'
+
+export const mastra = new Mastra({
+  agents: { yourAgent },
+  pubsub: new RedisStreamsPubSub({
+    url: process.env.REDIS_URL,
+    keyPrefix: 'mastra:my-app',
+  }),
+})
+```
+
+Vercel's managed Redis integration and Upstash Redis both work well. For more on when a distributed pub/sub is needed, see the [PubSub guide](https://mastra.ai/docs/server/pubsub) and the [`RedisStreamsPubSub` reference](https://mastra.ai/reference/pubsub/redis-streams).
+
+## Related
+
+- [Channels reference](https://mastra.ai/reference/agents/channels)
+- 📹 [Mastra channels workshop](https://www.youtube.com/watch?v=E9KFsZEnQO8\&t=5s)

package/.docs/docs/capabilities/channels/slack.md

@@ -0,0 +1,225 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Slack
+
+Add your agent to Slack so people can message it in shared channel threads or direct messages. When someone sends a message, Mastra runs your agent through the normal agent pipeline and streams the response back to Slack. The Slack adapter handles Slack AI indicators and interactive cards for you.
+
+## Installation
+
+Install the Slack adapter from the Chat SDK:
+
+**npm**:
+
+```bash
+npm install @chat-adapter/slack
+```
+
+**pnpm**:
+
+```bash
+pnpm add @chat-adapter/slack
+```
+
+**Yarn**:
+
+```bash
+yarn add @chat-adapter/slack
+```
+
+**Bun**:
+
+```bash
+bun add @chat-adapter/slack
+```
+
+Add `createSlackAdapter()` to the agent's `channels.adapters` object:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSlackAdapter } from '@chat-adapter/slack'
+
+export const yourAgent = new Agent({
+  id: 'your-agent',
+  name: 'Your Agent',
+  instructions: 'Help people plan tasks, answer questions, and coordinate work in Slack.',
+  model: 'anthropic/claude-opus-4-7',
+  channels: {
+    adapters: {
+      slack: createSlackAdapter(),
+    },
+  },
+})
+```
+
+## Create a Slack app
+
+To connect your agent, create a Slack app in the workspace where you want it to run. The Slack app controls how your agent appears in Slack, what it can do, and which events it receives.
+
+This guide uses a [manifest](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/#creating_manifests): a configuration file that creates the Slack app settings for you. This is the fastest path when you are adding your agent to your own workspace. It doesn't cover the platform OAuth flow where other workspaces install your agent.
+
+Create the Slack app from a manifest:
+
+1. Open [api.slack.com/apps](https://api.slack.com/apps).
+2. Select **Create an app**.
+3. Select **From a manifest**.
+4. Choose the workspace where the agent should run.
+5. Paste this manifest, then select **Create**:
+
+```yaml
+display_information:
+  name: mastra-agent
+features:
+  app_home:
+    home_tab_enabled: false
+    messages_tab_enabled: true
+    messages_tab_read_only_enabled: false
+  bot_user:
+    display_name: mastra-agent
+    always_online: true
+oauth_config:
+  scopes:
+    bot:
+      - im:write
+      - app_mentions:read
+      - channels:history
+      - channels:read
+      - chat:write
+      - users:read
+      - im:read
+      - im:history
+  pkce_enabled: false
+settings:
+  event_subscriptions:
+    request_url: https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
+    bot_events:
+      - app_mention
+      - message.channels
+      - message.im
+  interactivity:
+    is_enabled: true
+    request_url: https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
+  org_deploy_enabled: false
+  socket_mode_enabled: false
+  token_rotation_enabled: false
+  is_mcp_enabled: false
+```
+
+This manifest configures:
+
+- `display_information.name` and `features.bot_user.display_name`: Set your agent's name in Slack. You can update it at any time; remember to reinstall the app after changing names or permissions.
+- `app_home.messages_tab_enabled` and `app_home.messages_tab_read_only_enabled`: Enable direct messages from the Slack app's **Messages** tab.
+- `always_online`: Shows the Slack bot user as always available.
+- `oauth_config.scopes.bot`: Grants the bot permission to post messages, read channel messages where it is present, read mentions, read and write direct messages, and look up users.
+- `event_subscriptions`: Tells Slack which message events to send to the webhook.
+- `interactivity`: Enables interactive cards and tells Slack where to send card actions.
+
+After the app is created, open **Install App**, select **Install to Workspace**, and approve the requested scopes.
+
+## Set Slack credentials
+
+Set the Slack credentials in Mastra so it can verify Slack requests and send messages back to Slack.
+
+In the Slack app settings, copy these values:
+
+- **Basic Information** > **App Credentials** > **Signing Secret**
+- **OAuth & Permissions** > **Bot User OAuth Token**
+
+Set them in your Mastra environment:
+
+```bash
+SLACK_SIGNING_SECRET=your-signing-secret
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+```
+
+Mastra reads these environment variables automatically.
+
+## Configure the webhook route
+
+Slack sends channel activity to Mastra through webhooks. A webhook is an HTTP endpoint Slack calls when something happens, such as a new message, a mention, or a user selecting an interactive card.
+
+Mastra automatically registers a Slack webhook route for your agent:
+
+```text
+/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
+```
+
+Build the webhook URL from your public Mastra server URL and the generated route:
+
+```text
+https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
+```
+
+Slack can't send events to `localhost`. For local development, keep the Mastra dev server running and expose `http://localhost:4111` with a tunnel before you save the request URL in Slack.
+
+Use a tunnel such as `cloudflared` or `ngrok` for local development:
+
+**npm**:
+
+```bash
+npx cloudflared tunnel --url http://localhost:4111
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx cloudflared tunnel --url http://localhost:4111
+```
+
+**Yarn**:
+
+```bash
+yarn dlx cloudflared tunnel --url http://localhost:4111
+```
+
+**Bun**:
+
+```bash
+bun x cloudflared tunnel --url http://localhost:4111
+```
+
+Use the generated tunnel host as `<YOUR-PUBLIC-URL>`, for example:
+
+```text
+https://abc123.trycloudflare.com/api/agents/your-agent/channels/slack/webhook
+```
+
+Update the request URLs in Slack:
+
+1. In the Slack app settings, open **Event Subscriptions**.
+2. Replace **Request URL** with the final webhook URL.
+3. Select **Save Changes**.
+4. Open **Interactivity & Shortcuts**.
+5. Replace **Request URL** with the same webhook URL.
+6. Select **Save Changes**.
+7. If Slack asks you to reinstall the app, open **OAuth & Permissions** and select **Reinstall to Workspace**.
+
+## Try it in Slack
+
+Open a direct message with the Slack bot user and send a message. Direct messages work because the manifest includes the `message.im` event and `im:*` scopes.
+
+To use the agent in a channel, invite the Slack bot user first:
+
+```text
+/invite @your-bot-name
+```
+
+Mention the bot in the channel:
+
+```text
+@your-bot-name What can you help me with?
+```
+
+The agent responds in the thread. Response content depends on the model, instructions, memory, and tools configured on the agent.
+
+## Production deployment
+
+When you deploy the Mastra server, update both request URLs in the Slack app settings to the production webhook URL. The tunnel URL used for local development is temporary and changes when the tunnel restarts.
+
+Channels on serverless platforms may need `waitUntil` and shared pub/sub configuration so background responses and thread leases work across short-lived instances. See [serverless deployment](https://mastra.ai/docs/capabilities/channels/overview) in the channels overview.
+
+## Related
+
+- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
+- [More](https://mastra.ai/docs/capabilities/channels/other-adapters)
+- [Channels reference](https://mastra.ai/reference/agents/channels)
+- [Deployment overview](https://mastra.ai/docs/deployment/overview)

package/.docs/docs/capabilities/channels/teams.md

@@ -0,0 +1,100 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Microsoft Teams
+
+Microsoft Teams channels let a Mastra agent receive mentions and conversation events from Teams. Mastra handles the agent wiring and webhook route; the Chat SDK Teams adapter docs cover Teams app setup, authentication, and permissions.
+
+## Install the adapter
+
+Install the Teams adapter from the Chat SDK:
+
+**npm**:
+
+```bash
+npm install @chat-adapter/teams
+```
+
+**pnpm**:
+
+```bash
+pnpm add @chat-adapter/teams
+```
+
+**Yarn**:
+
+```bash
+yarn add @chat-adapter/teams
+```
+
+**Bun**:
+
+```bash
+bun add @chat-adapter/teams
+```
+
+## Agent configuration
+
+Add `createTeamsAdapter()` to the agent's `channels.adapters` object:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createTeamsAdapter } from '@chat-adapter/teams'
+
+export const teamsAgent = new Agent({
+  id: 'teams-agent',
+  name: 'Teams Agent',
+  instructions: 'Answer questions and help with tasks in Microsoft Teams.',
+  model: 'openai/gpt-5.5',
+  channels: {
+    adapters: {
+      teams: createTeamsAdapter({
+        appType: 'SingleTenant',
+      }),
+    },
+  },
+})
+```
+
+Register the agent on the Mastra instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { teamsAgent } from './agents/teams-agent'
+
+export const mastra = new Mastra({
+  agents: { teamsAgent },
+})
+```
+
+## Adapter setup
+
+Follow the [Chat SDK Teams adapter docs](https://chat-sdk.dev/adapters/official/teams) for Teams-specific setup, including Azure bot registration, Teams CLI usage, authentication options, and required permissions.
+
+The adapter reads Teams credentials from environment variables such as:
+
+```bash
+TEAMS_APP_ID=your-azure-bot-app-id
+TEAMS_APP_PASSWORD=your-azure-bot-app-password
+TEAMS_APP_TENANT_ID=your-azure-tenant-id
+```
+
+## Webhook URL
+
+Mastra generates the Teams webhook route from the agent ID and adapter key:
+
+```text
+/api/agents/teams-agent/channels/teams/webhook
+```
+
+Use your public Mastra server URL as the base URL:
+
+```text
+https://your-app.example.com/api/agents/teams-agent/channels/teams/webhook
+```
+
+Use this URL anywhere the Teams adapter docs ask for the bot endpoint or webhook URL. For local development, expose the Mastra dev server with a tunnel and use the tunnel URL as the base URL.
+
+## Related
+
+- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
+- [More](https://mastra.ai/docs/capabilities/channels/other-adapters)

package/.docs/docs/capabilities/channels/telegram.md

@@ -0,0 +1,98 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Telegram
+
+Telegram channels let a Mastra agent receive direct messages, group messages, and bot mentions from Telegram. Mastra handles the agent wiring and webhook route; the Chat SDK Telegram adapter docs cover bot setup, webhook registration, and polling behavior.
+
+## Install the adapter
+
+Install the Telegram adapter from the Chat SDK:
+
+**npm**:
+
+```bash
+npm install @chat-adapter/telegram
+```
+
+**pnpm**:
+
+```bash
+pnpm add @chat-adapter/telegram
+```
+
+**Yarn**:
+
+```bash
+yarn add @chat-adapter/telegram
+```
+
+**Bun**:
+
+```bash
+bun add @chat-adapter/telegram
+```
+
+## Agent configuration
+
+Add `createTelegramAdapter()` to the agent's `channels.adapters` object:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createTelegramAdapter } from '@chat-adapter/telegram'
+
+export const telegramAgent = new Agent({
+  id: 'telegram-agent',
+  name: 'Telegram Agent',
+  instructions: 'Answer questions and help with tasks in Telegram.',
+  model: 'openai/gpt-5.5',
+  channels: {
+    adapters: {
+      telegram: createTelegramAdapter(),
+    },
+  },
+})
+```
+
+Register the agent on the Mastra instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { telegramAgent } from './agents/telegram-agent'
+
+export const mastra = new Mastra({
+  agents: { telegramAgent },
+})
+```
+
+## Adapter setup
+
+Follow the [Chat SDK Telegram adapter docs](https://chat-sdk.dev/adapters/official/telegram) for Telegram-specific setup, including BotFather, webhook registration, secret tokens, and polling mode.
+
+The adapter reads Telegram credentials from environment variables such as:
+
+```bash
+TELEGRAM_BOT_TOKEN=your-telegram-bot-token
+TELEGRAM_WEBHOOK_SECRET_TOKEN=your-webhook-secret-token
+TELEGRAM_BOT_USERNAME=your_bot_username
+```
+
+## Webhook URL
+
+Mastra generates the Telegram webhook route from the agent ID and adapter key:
+
+```text
+/api/agents/telegram-agent/channels/telegram/webhook
+```
+
+Use your public Mastra server URL as the base URL:
+
+```text
+https://your-app.example.com/api/agents/telegram-agent/channels/telegram/webhook
+```
+
+Use this URL anywhere the Telegram adapter docs ask for the webhook URL. Telegram also supports polling mode; follow the Chat SDK adapter docs if you want to use polling for local development.
+
+## Related
+
+- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
+- [More](https://mastra.ai/docs/capabilities/channels/other-adapters)