slack-analytics-mcp-server 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# slack-analytics-mcp-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server that lets Analytics Model workflows send Slack messages: dashboard links, alerts, and
+"something new happened" notifications. It delivers messages only. The workflow decides *what* to send.
+
+- **One process = one Slack workspace** (one bot token).
+- Transport: stdio. Node 18+.
+- Messages go to a channel, to people by work email (DM), or both.
+
+---
+
+## 1. Slack app setup (once per workspace)
+
+1. Go to <https://api.slack.com/apps> → **Create New App** → *From scratch*.
+2. **OAuth & Permissions → Bot Token Scopes**, add:
+
+   | Scope | Why |
+   |---|---|
+   | `chat:write` | post messages |
+   | `chat:write.public` | post in public channels without inviting the bot |
+   | `users:read` | find users |
+   | `users:read.email` | find a user by email (needed for DMs) |
+   | `im:write` | open a DM |
+   | `channels:read` | list public channels (channel picker) |
+
+3. **Install to Workspace** and copy the **Bot User OAuth Token** (`xoxb-…`).
+4. For private channels, invite the bot (`/invite @YourApp`).
+
+## 2. Run
+
+```bash
+SLACK_BOT_TOKEN=xoxb-your-token npx slack-analytics-mcp-server
+```
+
+| Env var | Required | Purpose |
+|---|---|---|
+| `SLACK_BOT_TOKEN` | yes | Bot token of the workspace |
+| `SLACK_API_URL` | no | Override the Slack API base URL (tests only) |
+
+MCP client config example:
+
+```json
+{
+  "mcpServers": {
+    "slack": {
+      "command": "npx",
+      "args": ["-y", "slack-analytics-mcp-server"],
+      "env": { "SLACK_BOT_TOKEN": "xoxb-your-token" }
+    }
+  }
+}
+```
+
+## 3. Tools
+
+All tools return JSON as text. Failures return `isError: true` with a readable message.
+
+### `get_workspace`
+Checks the token. Call it right after a user saves a connection.
+Input: none. Output: `{ ok, workspace, workspaceId, url, botUserId, botName }`.
+
+### `lookup_user_by_email`
+Input: `{ email }`. Output: `{ id, name, email, deleted, isBot }`.
+
+### `list_channels`
+Public channels, for a channel picker.
+Input: `{ limit?: 1-200, query?: string }`. Output: `{ channels: [{ id, name, isMember }] }`.
+
+### `send_dm`
+Input: `{ email, text }`. Output: `{ email, userId, channel, ts }`.
+
+### `post_to_channel`
+Input: `{ channel, text }` (name with or without `#`, or id). Output: `{ channel, ts }`.
+
+### `send_dashboard_link`
+A card with a title, optional summary and an **Open dashboard** button.
+
+```json
+{
+  "url": "https://app.example.com/dashboard/42",
+  "title": "Churn analysis",
+  "message": "Churn rose 3% this week.",
+  "emails": ["priya@acme.com"],
+  "channel": "growth"
+}
+```
+
+### `send_notification`
+Generic alert, e.g. "new record in MongoDB". Several items are sent as **one** message (first 10 shown, then "and N more").
+
+```json
+{
+  "title": "New dashboard created",
+  "text": "Created in the last 5 minutes",
+  "items": [
+    { "title": "Churn v2", "url": "https://app.example.com/d/9",
+      "fields": { "Owner": "Priya", "Type": "trend", "Created": "2026-10-29 09:10" } }
+  ],
+  "url": "https://app.example.com/dashboards",
+  "url_label": "Open dashboards",
+  "channel": "growth",
+  "emails": []
+}
+```
+
+Rules for both send tools:
+- Give at least one of `channel` or `emails`.
+- One failed recipient does not stop the others. The result is
+  `{ sent, failed, results: [{ to, sent, error? }] }`, and the call is an error only if **every** recipient failed.
+- Text is escaped, so names containing `<`, `>` or `&` are safe.
+- Slack rate limits (HTTP 429) are retried automatically, up to 3 tries.
+
+## 4. How it fits the platform
+
+```
+Frontend ──(saves connection + node settings)──▶ Backend (FastAPI)
+                                                    │ on schedule
+                                                    ├─ runs Mongo fetch (new records since last run)
+                                                    ├─ skips Slack if nothing is new
+                                                    └─ starts this MCP with the workspace's token
+                                                         └─ calls send_notification / send_dashboard_link
+```
+
+- The frontend never talks to the MCP and never keeps the token. It stores a `connectionId`.
+- The **backend** must remember the last-seen value per workflow (e.g. `createdAt` or `_id`) so nothing is announced twice. This server is stateless.
+
+**Slack connection** (created once): display name + bot token.
+**Slack node settings:** connection, channel and/or emails, title, fields to show, optional button link.
+
+## 5. Troubleshooting
+
+| Error | Meaning / fix |
+|---|---|
+| `invalid_auth`, `not_authed` | Token wrong or revoked. |
+| `missing_scope` | Add the scope in the Slack app and reinstall it. |
+| `users_not_found` | No one in that workspace has that email. |
+| `channel_not_found` | Wrong channel name or id, or a private channel the bot isn't in. |
+| `not_in_channel` | Invite the bot, or add `chat:write.public`. |
+| `is_archived` | The channel is archived. |
+
+## 6. Develop and publish
+
+```bash
+npm install
+npm test        # builds, then runs the server against a fake Slack API (12 checks)
+npm publish     # prepublishOnly runs the build
+```
+
+Source: `src/index.ts` (tools), `src/slack.ts` (Slack client, message blocks).
+
+## Changelog
+- **0.2.0** – added `send_notification`.
+- **0.1.0** – `get_workspace`, `lookup_user_by_email`, `list_channels`, `send_dm`, `post_to_channel`, `send_dashboard_link`.

package/dist/index.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { dashboardBlocks, isEmail, notificationBlocks, slack } from './slack.js';
+// One process = one Slack workspace. The platform starts it with that workspace's bot token.
+const TOKEN = process.env.SLACK_BOT_TOKEN || '';
+const server = new McpServer({ name: 'slack-analytics-mcp-server', version: '0.2.0' });
+const text = (v) => ({ content: [{ type: 'text', text: typeof v === 'string' ? v : JSON.stringify(v) }] });
+const fail = (e) => ({ isError: true, content: [{ type: 'text', text: e instanceof Error ? e.message : String(e) }] });
+const need = () => { if (!TOKEN)
+    throw new Error('SLACK_BOT_TOKEN is not set'); return TOKEN; };
+async function dmByEmail(email, msg) {
+    const t = need();
+    const { user } = await slack(t, 'users.lookupByEmail', { email });
+    const { channel } = await slack(t, 'conversations.open', { users: user.id });
+    const sent = await slack(t, 'chat.postMessage', { channel: channel.id, ...msg, unfurl_links: false });
+    return { email, userId: user.id, channel: channel.id, ts: sent.ts };
+}
+server.registerTool('get_workspace', {
+    description: 'Check the connection. Returns the Slack workspace name, id and the bot user. Use it to validate a token when a user adds a workspace.',
+    inputSchema: {},
+}, async () => {
+    try {
+        const r = await slack(need(), 'auth.test');
+        return text({ ok: true, workspace: r.team, workspaceId: r.team_id, url: r.url, botUserId: r.user_id, botName: r.user });
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.registerTool('lookup_user_by_email', {
+    description: 'Find a person in the workspace by their email address. Needs the users:read.email scope.',
+    inputSchema: { email: z.string().describe('Work email of the person') },
+}, async ({ email }) => {
+    try {
+        if (!isEmail(email))
+            throw new Error(`"${email}" is not a valid email`);
+        const { user } = await slack(need(), 'users.lookupByEmail', { email });
+        return text({ id: user.id, name: user.real_name || user.name, email, deleted: Boolean(user.deleted), isBot: Boolean(user.is_bot) });
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.registerTool('list_channels', {
+    description: 'List public channels the bot can post to, so the user can pick one in the UI.',
+    inputSchema: { limit: z.number().int().min(1).max(200).optional(), query: z.string().optional().describe('Filter by name') },
+}, async ({ limit, query }) => {
+    try {
+        const r = await slack(need(), 'conversations.list', { types: 'public_channel', exclude_archived: true, limit: limit ?? 200 });
+        const q = query?.toLowerCase();
+        const channels = r.channels.filter((c) => !q || c.name.includes(q)).map((c) => ({ id: c.id, name: c.name, isMember: Boolean(c.is_member) }));
+        return text({ channels });
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.registerTool('send_dm', {
+    description: 'Send a direct message to one person, found by email.',
+    inputSchema: { email: z.string(), text: z.string().describe('Message text (Slack mrkdwn)') },
+}, async ({ email, text: body }) => {
+    try {
+        if (!isEmail(email))
+            throw new Error(`"${email}" is not a valid email`);
+        return text(await dmByEmail(email, { text: body }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.registerTool('post_to_channel', {
+    description: 'Post a message to a channel, by name (e.g. "growth") or id. The bot must be in the channel unless it has chat:write.public.',
+    inputSchema: { channel: z.string(), text: z.string() },
+}, async ({ channel, text: body }) => {
+    try {
+        const r = await slack(need(), 'chat.postMessage', { channel: channel.replace(/^#/, ''), text: body, unfurl_links: false });
+        return text({ channel: r.channel, ts: r.ts });
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.registerTool('send_dashboard_link', {
+    description: 'Send a dashboard link to Slack. Give emails to DM each person and/or a channel to post in. One failure does not stop the others; the result lists every recipient with sent true/false.',
+    inputSchema: {
+        url: z.string().url().describe('Link to the dashboard'),
+        title: z.string().optional().describe('Dashboard or workflow name'),
+        message: z.string().optional().describe('Short summary shown above the button'),
+        emails: z.array(z.string()).optional().describe('People to DM, by work email'),
+        channel: z.string().optional().describe('Channel name or id to post in'),
+    },
+}, async ({ url, title, message, emails = [], channel }) => {
+    try {
+        const t = need();
+        if (!emails.length && !channel)
+            throw new Error('Give at least one email or a channel');
+        const fallback = `${title || 'Your dashboard is ready'}: ${url}`;
+        const payload = { text: fallback, blocks: dashboardBlocks({ title, url, message }) };
+        const results = [];
+        for (const email of [...new Set(emails.map((e) => e.trim()).filter(Boolean))]) {
+            try {
+                if (!isEmail(email))
+                    throw new Error('not a valid email');
+                await dmByEmail(email, payload);
+                results.push({ to: email, sent: true });
+            }
+            catch (e) {
+                results.push({ to: email, sent: false, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        if (channel) {
+            try {
+                await slack(t, 'chat.postMessage', { channel: channel.replace(/^#/, ''), ...payload, unfurl_links: false });
+                results.push({ to: `#${channel.replace(/^#/, '')}`, sent: true });
+            }
+            catch (e) {
+                results.push({ to: `#${channel.replace(/^#/, '')}`, sent: false, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        const failed = results.filter((r) => !r.sent).length;
+        return { ...text({ sent: results.length - failed, failed, results }), ...(failed === results.length ? { isError: true } : {}) };
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.registerTool('send_notification', {
+    description: 'Send a notification about anything (a new record, an alert, a summary) to a channel and/or people by email. Pass the data as fields or items; several items are sent as ONE message. The caller decides WHAT is new; this tool only delivers it.',
+    inputSchema: {
+        title: z.string().describe('Headline, e.g. "New dashboard created"'),
+        text: z.string().optional().describe('Short sentence under the headline'),
+        items: z.array(z.object({
+            title: z.string().optional(),
+            url: z.string().url().optional(),
+            fields: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])).optional(),
+        })).optional().describe('One entry per new record. Shown as name + key/value lines'),
+        url: z.string().url().optional().describe('Button link'),
+        url_label: z.string().optional(),
+        channel: z.string().optional().describe('Channel name or id'),
+        emails: z.array(z.string()).optional().describe('People to DM, by work email'),
+    },
+}, async ({ title, text: body, items, url, url_label, channel, emails = [] }) => {
+    try {
+        const t = need();
+        if (!emails.length && !channel)
+            throw new Error('Give at least one email or a channel');
+        const count = items?.length ? ` (${items.length})` : '';
+        const payload = { text: `${title}${count}${body ? `: ${body}` : ''}`, blocks: notificationBlocks({ title: `${title}${count}`, text: body, items, url, urlLabel: url_label }) };
+        const results = [];
+        for (const email of [...new Set(emails.map((e) => e.trim()).filter(Boolean))]) {
+            try {
+                if (!isEmail(email))
+                    throw new Error('not a valid email');
+                await dmByEmail(email, payload);
+                results.push({ to: email, sent: true });
+            }
+            catch (e) {
+                results.push({ to: email, sent: false, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        if (channel) {
+            const name = channel.replace(/^#/, '');
+            try {
+                await slack(t, 'chat.postMessage', { channel: name, ...payload, unfurl_links: false });
+                results.push({ to: `#${name}`, sent: true });
+            }
+            catch (e) {
+                results.push({ to: `#${name}`, sent: false, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        const failed = results.filter((r) => !r.sent).length;
+        return { ...text({ sent: results.length - failed, failed, results }), ...(failed === results.length ? { isError: true } : {}) };
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+await server.connect(new StdioServerTransport());

package/dist/slack.js

@@ -0,0 +1,68 @@
+// Thin Slack Web API client. One bot token = one workspace.
+const BASE = (process.env.SLACK_API_URL || 'https://slack.com/api').replace(/\/$/, '');
+export class SlackError extends Error {
+    code;
+    method;
+    constructor(code, method) {
+        super(`Slack ${method} failed: ${code}${HINTS[code] ? ` (${HINTS[code]})` : ''}`);
+        this.code = code;
+        this.method = method;
+    }
+}
+const HINTS = {
+    invalid_auth: 'the bot token is wrong or revoked',
+    not_authed: 'no bot token was provided',
+    users_not_found: 'no one in this workspace has that email',
+    missing_scope: 'add the missing scope to the Slack app and reinstall it',
+    channel_not_found: 'check the channel name or id',
+    not_in_channel: 'invite the bot to the channel, or add the chat:write.public scope',
+    is_archived: 'the channel is archived',
+};
+export async function slack(token, method, params = {}, tries = 3) {
+    const res = await fetch(`${BASE}/${method}`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json; charset=utf-8' },
+        body: JSON.stringify(params),
+    });
+    if (res.status === 429 && tries > 1) {
+        const wait = Math.min(Number(res.headers.get('retry-after')) || 1, 30);
+        await new Promise((r) => setTimeout(r, wait * 1000));
+        return slack(token, method, params, tries - 1);
+    }
+    if (!res.ok)
+        throw new SlackError(`http_${res.status}`, method);
+    const data = (await res.json());
+    if (!data.ok)
+        throw new SlackError(data.error || 'unknown_error', method);
+    return data;
+}
+export const isEmail = (s) => /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/.test(s);
+export function dashboardBlocks(opts) {
+    const title = opts.title || 'Your dashboard is ready';
+    return [
+        { type: 'header', text: { type: 'plain_text', text: title.slice(0, 150) } },
+        ...(opts.message ? [{ type: 'section', text: { type: 'mrkdwn', text: opts.message.slice(0, 2900) } }] : []),
+        { type: 'actions', elements: [{ type: 'button', text: { type: 'plain_text', text: 'Open dashboard' }, url: opts.url, style: 'primary' }] },
+    ];
+}
+const esc = (v) => String(v ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+// Generic notification card: title, optional text, one block of fields per item, optional button.
+// Many items become ONE message so a burst of new records does not spam the channel.
+export function notificationBlocks(o) {
+    const blocks = [{ type: 'header', text: { type: 'plain_text', text: o.title.slice(0, 150) } }];
+    if (o.text)
+        blocks.push({ type: 'section', text: { type: 'mrkdwn', text: o.text.slice(0, 2900) } });
+    const items = o.items || [];
+    for (const it of items.slice(0, 10)) {
+        const head = it.title ? (it.url ? `*<${it.url}|${esc(it.title)}>*` : `*${esc(it.title)}*`) : '';
+        const rows = Object.entries(it.fields || {}).slice(0, 10).map(([k, v]) => `*${esc(k)}:* ${esc(v)}`).join('\n');
+        const body = [head, rows].filter(Boolean).join('\n');
+        if (body)
+            blocks.push({ type: 'section', text: { type: 'mrkdwn', text: body.slice(0, 2900) } });
+    }
+    if (items.length > 10)
+        blocks.push({ type: 'context', elements: [{ type: 'mrkdwn', text: `and ${items.length - 10} more` }] });
+    if (o.url)
+        blocks.push({ type: 'actions', elements: [{ type: 'button', text: { type: 'plain_text', text: (o.urlLabel || 'Open').slice(0, 75) }, url: o.url }] });
+    return blocks;
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "slack-analytics-mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "MCP server that lets Analytics Model workflows send dashboard links and messages to Slack (DM by email, or post to a channel).",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "slack-analytics-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node test/smoke.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Analytics-model-LTD/slack-analytics-mcp-server.git"
+  },
+  "homepage": "https://github.com/Analytics-model-LTD/slack-analytics-mcp-server#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
 }