@mastra/mcp-docs-server 1.1.29-alpha.8 → 1.1.29-alpha.9

package/.docs/docs/agents/channels.md

@@ -72,7 +72,7 @@ Platform webhooks need a public URL to reach your local server. Use a tunnel to
 ngrok http 4111
 
 # cloudflared
-cloudflared tunnel --url http://localhost:4111
+npx cloudflared tunnel --url http://localhost:4111
 ```
 
 Copy the generated URL and use it as the base for your webhook paths (e.g. `https://abc123.ngrok.io/api/agents/support-agent/channels/slack/webhook`).
@@ -164,6 +164,7 @@ By default, only images are sent inline (`inlineMedia: ['image/*']`). Unsupporte
 
 ## Related
 
+- [Guide: Building a Slack assistant](https://mastra.ai/guides/guide/slack-assistant)
 - [Agent overview](https://mastra.ai/docs/agents/overview)
 - [Tool approval](https://mastra.ai/docs/agents/agent-approval)
 - [Channels reference](https://mastra.ai/reference/agents/channels)

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

@@ -0,0 +1,191 @@
+# Building a Slack assistant
+
+In this guide, you'll build a Mastra agent that responds to messages and mentions on Slack. You'll learn how to configure a channel adapter, set up a Slack app with the right permissions, connect it to your agent via a webhook, and test the interaction.
+
+## 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) if needed.
+- A [Slack workspace](https://slack.com/) where you can create apps
+
+## Create the agent
+
+Install the Slack adapter:
+
+**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
+```
+
+Create a new file `src/mastra/agents/slack-agent.ts` and define your agent:
+
+```ts
+import { Agent } from '@mastra/core/agent'
+import { createSlackAdapter } from '@chat-adapter/slack'
+
+export const slackAgent = new Agent({
+  id: 'slack-agent',
+  name: 'Slack Agent',
+  instructions:
+    'You are a helpful assistant. Answer questions, help with tasks, and have natural conversations.',
+  model: 'anthropic/claude-opus-4-6',
+  channels: {
+    adapters: {
+      slack: createSlackAdapter(),
+    },
+  },
+})
+```
+
+The `channels` property tells Mastra to generate a webhook endpoint for each adapter. In this case, the Slack adapter handles event verification, signature validation, and message formatting automatically.
+
+Register the agent in your `src/mastra/index.ts` file:
+
+```ts
+import { Mastra } from '@mastra/core'
+import { slackAgent } from './agents/slack-agent'
+
+export const mastra = new Mastra({
+  agents: { slackAgent },
+})
+```
+
+## Create a Slack app
+
+You need a Slack app to connect your agent to a workspace.
+
+Go to <https://api.slack.com/apps> and select **Create New App** > **From scratch**. Give it a name and select your workspace.
+
+Navigate to **OAuth & Permissions** and scroll to **Bot Token Scopes**. Add the following scopes:
+
+- `app_mentions:read`
+- `channels:history`
+- `channels:read`
+- `chat:write`
+- `users:read`
+
+At the top of **OAuth & Permissions**, select **Install to Workspace**. Copy the **Bot User OAuth Token** (`xoxb-...`).
+
+Go to **Basic Information** > **App Credentials** and copy the **Signing Secret** (e.g. `c3a4...`).
+
+Ensure **Socket Mode** is turned **off** under **Settings** > **Socket Mode**.
+
+Add the credentials to your `.env` file:
+
+```bash
+SLACK_SIGNING_SECRET=your-signing-secret
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+```
+
+The adapter reads these environment variables by default. See the [Chat SDK Slack adapter docs](https://chat-sdk.dev/adapters/slack) for more details.
+
+## Connect the webhook
+
+Slack delivers events to your agent via a webhook. Mastra generates this endpoint automatically for each channel adapter.
+
+Start the dev server:
+
+**npm**:
+
+```bash
+npm run dev
+```
+
+**pnpm**:
+
+```bash
+pnpm run dev
+```
+
+**Yarn**:
+
+```bash
+yarn dev
+```
+
+**Bun**:
+
+```bash
+bun run dev
+```
+
+During local development, Slack needs a public URL to reach your local server. Open a new terminal and start a tunnel:
+
+```bash
+npx cloudflared tunnel --url http://localhost:4111
+```
+
+This outputs a temporary public URL like `https://triple-arms-solutions-kit.trycloudflare.com`. The URL changes each time you restart the tunnel.
+
+In your Slack app settings, go to **Event Subscriptions** and toggle **Enable Events** to **On**.
+
+Set the **Request URL** to your tunnel URL with the agent webhook path:
+
+```text
+https://<your-tunnel-url>/api/agents/slack-agent/channels/slack/webhook
+```
+
+Slack sends a verification request. If your dev server is running, it responds with a green checkmark.
+
+Under **Subscribe to bot events**, add:
+
+- `app_mention`
+- `message.channels`
+
+Select **Save Changes**. Slack requires you to reinstall the app after changing event subscriptions. Go to **OAuth & Permissions** and select **Reinstall to Workspace** to apply the updated permissions.
+
+> **Note:** The tunnel URL is for local development only. When you [deploy your application](https://mastra.ai/docs/deployment/overview), update the **Request URL** in your Slack app's **Event Subscriptions** to your production URL (e.g. `https://your-app.example.com/api/agents/slack-agent/channels/slack/webhook`).
+
+## Test the agent
+
+Before testing with Slack, you can refine your agent's behavior in [Studio](https://mastra.ai/docs/studio/overview). Open <http://localhost:4111/> to chat with your agent directly, adjust its instructions, and inspect traces to see how responses are generated.
+
+Once you're happy with the agent's responses, test the Slack integration. Invite the bot to a channel in Slack:
+
+```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. Output may vary depending on the model and instructions.
+
+## Next steps
+
+You can extend this agent to:
+
+- [Deploy your application](https://mastra.ai/docs/deployment/overview) and update the Slack **Request URL** to your production endpoint
+- Add more adapters (Discord, Telegram) to the same agent so it responds on multiple platforms
+- Configure [multimodal content](https://mastra.ai/docs/agents/channels) to let your agent process images, video, and audio shared in chat
+- Add [tools](https://mastra.ai/docs/agents/using-tools) to give the agent access to external APIs and data
+
+Learn more:
+
+- [Channels overview](https://mastra.ai/docs/agents/channels)
+- [Studio](https://mastra.ai/docs/studio/overview)
+- [Deployment overview](https://mastra.ai/docs/deployment/overview)
+- [Chat SDK adapter docs](https://chat-sdk.dev)

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.1.29-alpha.9
+
+### Patch Changes
+
+- Updated dependencies [[`8a71261`](https://github.com/mastra-ai/mastra/commit/8a71261e3954ae617c6f8e25767b951f99438ab2), [`021a60f`](https://github.com/mastra-ai/mastra/commit/021a60f1f3e0135a70ef23c58be7a9b3aaffe6b4)]:
+  - @mastra/core@1.29.0-alpha.4
+
 ## 1.1.29-alpha.7
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.29-alpha.8",
+  "version": "1.1.29-alpha.9",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.29.0-alpha.3",
+    "@mastra/core": "1.29.0-alpha.4",
     "@mastra/mcp": "^1.5.2"
   },
   "devDependencies": {
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "4.1.5",
+    "@internal/lint": "0.0.86",
     "@internal/types-builder": "0.0.61",
-    "@mastra/core": "1.29.0-alpha.3",
-    "@internal/lint": "0.0.86"
+    "@mastra/core": "1.29.0-alpha.4"
   },
   "homepage": "https://mastra.ai",
   "repository": {