yt-slack-mcp 0.5.0 → 0.7.0

package/README.md

@@ -7,11 +7,13 @@ A host-agnostic [Model Context Protocol](https://modelcontextprotocol.io) server
 - Read Slack channel history and thread replies.
 - Read message permalinks from channels, DMs, and group DMs.
 - Return image attachments inline, extract text from PDFs, and return `text/*` attachment contents inline.
+- Save any attachment to a local path from a message permalink, file permalink, or file ID, preserving the original bytes and reporting the saved path, filename, and MIME type.
 - Retrieve private attachment contents through the authenticated Slack browser session.
 - Reply to a thread, add or remove a reaction, edit an authored message or thread reply, or upload local files only in explicitly allowed channel IDs.
-- Prefix every message the agent posts with `🤖:` — or `🤖 <model>:` when the call names the model — so agent replies stand apart from the account's own messages; an edit can opt out with `agent_authored: false`.
+- Have no plain top-level text post: a reply needs an existing thread, and a file upload with an `initial_comment` is the only way to start a top-level message.
+- Prefix every message the agent posts with `🤖:` — or `🤖 <backend model ID>:` when the call names the model — so agent replies stand apart from the account's own messages; an edit can opt out with `agent_authored: false`.
 
-Attachment limits: images and text files are limited to 10 MB; text attachments are truncated at 100,000 characters. PDFs are limited to 20 MB, 50 pages, and 100,000 extracted characters.
+Attachment limits: images and text files are limited to 10 MB; text attachments are truncated at 100,000 characters. PDFs are limited to 20 MB, 50 pages, and 100,000 extracted characters. These limits apply to content returned inline; `slack_save_file` streams the attachment unchanged to disk.
 
 ## Tools
 
@@ -19,12 +21,14 @@ Attachment limits: images and text files are limited to 10 MB; text attachments
 |------|-------------|
 | `slack_read_permalink` | Read a message or thread from a channel, DM, or group-DM permalink, including supported attachments. |
 | `slack_get_replies` | Read replies for a thread by channel ID and timestamp. |
-| `slack_get_history` | Read recent channel history. |
-| `slack_reply_to_thread` | Reply to a thread, with optional `model`, in a `🤖:`-prefixed message; restricted to allowed channels. |
+| `slack_get_history` | Read recent channel history by channel ID (up to 200 messages). |
+| `slack_get_history` | Read recent channel history by channel ID (up to 200 messages). |
+| `slack_save_file` | Save a file attached to a message to a local path from a Slack message permalink, file permalink, or file ID, preserving the original bytes; the destination's parent directory must exist, and a destination that is an existing directory keeps the attachment's filename (replacing characters the local filesystem rejects) and refuses to overwrite an existing file — pass an explicit file path to overwrite; returns the saved path, filename, and MIME type. |
+| `slack_reply_to_thread` | Reply to a thread, with `model` set to the backend model ID when known, in a `🤖:`-prefixed message; restricted to allowed channels. |
 | `slack_add_reaction` | Add a reaction; restricted to allowed channels. |
 | `slack_remove_reaction` | Remove a reaction added by this account; restricted to allowed channels. |
-| `slack_upload_files` | Upload up to 10 local files to a channel or thread, with an optional `initial_comment` prefixed with `🤖:` and an optional `model` (only used with a comment); returns file and message permalinks; restricted to allowed channels. |
-| `slack_edit_message` | Edit an authored message or thread reply by channel ID and timestamp; replaces the message text with `🤖:`-prefixed text and an optional `model`, or with the text as given when `agent_authored` is `false` (Slack removes any existing Block Kit blocks) and returns the updated timestamp and permalink; restricted to allowed channels. |
+| `slack_upload_files` | Upload up to 10 local files (10 MB each) to a channel or thread, with an optional `initial_comment` prefixed with `🤖:` and `model` set to the backend model ID when known (only used with a comment); returns file and message permalinks; restricted to allowed channels. |
+| `slack_edit_message` | Edit an authored message or thread reply by channel ID and timestamp; replaces the message text with `🤖:`-prefixed text and `model` set to the backend model ID when known, or with the text as given when `agent_authored` is `false` (Slack removes any existing Block Kit blocks) and returns the updated timestamp and permalink; restricted to allowed channels. |
 
 ## Agent message prefix
 
@@ -36,13 +40,17 @@ text of every posted message is prefixed with `🤖:` by default:
 🤖: deployed revision 4f2c1a9
 ```
 
-The MCP transport does not report which model is calling, so a write tool call
-can pass `model` with the model it is running; the prefix then names it:
+The MCP transport does not report which model is calling, so a write call passes
+`model` with the backend model ID it is running — for example
+`claude-sonnet-4-5`, not a display name — and the prefix then names it:
 
 ```text
 🤖 claude-sonnet-4-5: deployed revision 4f2c1a9
 ```
 
+The parameter stays optional for a client that cannot determine its own model
+ID; without it the prefix is the bare `🤖:`.
+
 The prefix is added once: text that already starts with `🤖` is sent unchanged,
 so editing a prefixed message does not stack prefixes. A file upload without an
 `initial_comment` — or with only whitespace — gets no comment rather than a bare
@@ -71,12 +79,12 @@ Save each token as a single-line file:
 ~/.config/yt-slack-mcp/secrets/slack-xoxd.txt
 ```
 
-The server reads these paths by default. Override them with the config file or environment variables if your MCP host manages secrets elsewhere.
+The server reads these paths by default. Override them in the config file described below if your MCP host manages secrets elsewhere.
 
 ### 3. (Optional) Configure allowed write channels and paths
 
-All configuration can live in a JSON config file at
-`~/.config/yt-slack-mcp/config.json` (override with `SLACK_MCP_CONFIG`):
+All configuration lives in a JSON config file at
+`~/.config/yt-slack-mcp/config.json`:
 
 ```json
 {
@@ -90,22 +98,27 @@ All configuration can live in a JSON config file at
 
 By default the write tools (`slack_reply_to_thread`, `slack_add_reaction`,
 `slack_remove_reaction`, `slack_edit_message`) and `slack_upload_files` are
-locked down — no channel is writable. Each upload is limited to 10 MB. Every
-field is optional; a missing file just means defaults. Env vars always override
-the config file.
+locked down — no channel is writable. Each uploaded file is limited to 10 MB, and
+a call accepts at most 10 files. Every field is optional; a missing file just
+means defaults.
 
 ## Configuration
 
-Config resolution order: built-in defaults → config file → env vars.
+Configuration comes from the JSON config file, with built-in defaults for
+absent keys.
+
+| Config key | Default | Description |
+|------------|---------|-------------|
+| `secretsDir` | `~/.config/yt-slack-mcp/secrets` | Directory holding the token files |
+| `xoxcPath` | `$SECRETS_DIR/slack-xoxc.txt` | Path to the `xoxc` token |
+| `xoxdPath` | `$SECRETS_DIR/slack-xoxd.txt` | Path to the `xoxd` token |
+| `allowedWriteChannels` | *(none)* | Channel IDs allowed for write tools |
+| `userAgent` | `Mozilla/5.0` | HTTP `User-Agent` header |
 
-| Config file key | Env var | Default | Description |
-|-----------------|---------|---------|-------------|
-| `secretsDir` | `SLACK_MCP_SECRETS_DIR` | `~/.config/yt-slack-mcp/secrets` | Directory holding the token files |
-| `xoxcPath` | `SLACK_MCP_XOXC_PATH` | `$SECRETS_DIR/slack-xoxc.txt` | Path to the `xoxc` token |
-| `xoxdPath` | `SLACK_MCP_XOXD_PATH` | `$SECRETS_DIR/slack-xoxd.txt` | Path to the `xoxd` token |
-| `allowedWriteChannels` | `SLACK_MCP_ALLOWED_WRITE_CHANNELS` | *(none)* | Channel IDs allowed for write tools (comma-separated in env) |
-| `userAgent` | `SLACK_MCP_USER_AGENT` | `Mozilla/5.0` | HTTP `User-Agent` header |
-| *(config file path)* | `SLACK_MCP_CONFIG` | `~/.config/yt-slack-mcp/config.json` | Path to the JSON config file |
+Environment-variable configuration has been removed. Move any environment-supplied
+values into `~/.config/yt-slack-mcp/config.json`; the config path is fixed for the
+CLI. `allowedWriteChannels` accepts an array or a comma-separated string, so an
+old comma-separated value can be copied as-is.
 
 ## MCP host configuration
 
@@ -128,6 +141,14 @@ For example, Claude Desktop uses:
 }
 ```
 
+## Install as a skill
+
+[`skills/slack-mcp/SKILL.md`](skills/slack-mcp/SKILL.md) packages this server as
+an Agent Skill so an agent knows when to read Slack, when a write is allowed,
+and which tool fits the request. Copy or symlink the `skills/slack-mcp`
+directory into your agent's skills directory (for example
+`.agents/skills/slack-mcp`); the server still needs the setup above.
+
 ## License
 
 MIT

package/index.js

@@ -12,14 +12,19 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
+import { randomUUID } from "crypto";
 import fs from "fs";
 import os from "os";
 import path from "path";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
 import { fileURLToPath } from "url";
 
 
 const DEFAULT_SECRETS_DIR = path.join(os.homedir(), ".config", "yt-slack-mcp", "secrets");
 const DEFAULT_CONFIG_PATH = path.join(os.homedir(), ".config", "yt-slack-mcp", "config.json");
+const PACKAGE_INFO = JSON.parse(fs.readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+const SERVER_INFO = { name: "yt-slack-mcp", version: PACKAGE_INFO.version };
 
 const maxImageBytes = 10 * 1024 * 1024;
 const maxPdfBytes = 20 * 1024 * 1024;
@@ -28,6 +33,8 @@ const maxPdfTextCharacters = 100_000;
 const maxTextFileBytes = 10 * 1024 * 1024;
 const maxTextFileCharacters = 100_000;
 const maxUploadBytes = 10 * 1024 * 1024;
+const threadPageSize = 200;
+const maxThreadPages = 10;
 
 function expandHome(filePath) {
     if (!filePath) {
@@ -46,14 +53,29 @@ function parseChannelList(value) {
     if (value === undefined || value === null || value === "") {
         return null;
     }
-    return value
-        .split(",")
-        .map((c) => c.trim())
+    const list = Array.isArray(value)
+        ? value
+        : typeof value === "string"
+          ? value.split(",")
+          : null;
+    if (list === null) {
+        throw new Error("channel IDs must be an array or a comma-separated string");
+    }
+    return list
+        .map((channel) => {
+            if (typeof channel !== "string") {
+                throw new Error("channel IDs must be strings");
+            }
+            return channel.trim();
+        })
         .filter(Boolean);
 }
 
-function loadConfig(env = process.env) {
-    const configPath = env.SLACK_MCP_CONFIG || DEFAULT_CONFIG_PATH;
+function loadConfig(input = DEFAULT_CONFIG_PATH) {
+    const configPath =
+        typeof input === "string"
+            ? input
+            : input?.SLACK_MCP_CONFIG || DEFAULT_CONFIG_PATH;
     let fileConfig = {};
     if (fs.existsSync(configPath)) {
         try {
@@ -63,19 +85,44 @@ function loadConfig(env = process.env) {
         }
     }
 
-    const secretsDir =
-        env.SLACK_MCP_SECRETS_DIR || expandHome(fileConfig.secretsDir) || DEFAULT_SECRETS_DIR;
-    const xoxcPath =
-        env.SLACK_MCP_XOXC_PATH || expandHome(fileConfig.xoxcPath) || path.join(secretsDir, "slack-xoxc.txt");
-    const xoxdPath =
-        env.SLACK_MCP_XOXD_PATH || expandHome(fileConfig.xoxdPath) || path.join(secretsDir, "slack-xoxd.txt");
-    const allowedWriteChannels =
-        parseChannelList(env.SLACK_MCP_ALLOWED_WRITE_CHANNELS) ?? fileConfig.allowedWriteChannels ?? [];
-    const userAgent = env.SLACK_MCP_USER_AGENT || fileConfig.userAgent || "Mozilla/5.0";
+    const secretsDir = expandHome(fileConfig.secretsDir) || DEFAULT_SECRETS_DIR;
+    const xoxcPath = expandHome(fileConfig.xoxcPath) || path.join(secretsDir, "slack-xoxc.txt");
+    const xoxdPath = expandHome(fileConfig.xoxdPath) || path.join(secretsDir, "slack-xoxd.txt");
+    let allowedWriteChannels;
+    try {
+        allowedWriteChannels = parseChannelList(fileConfig.allowedWriteChannels) ?? [];
+    } catch (e) {
+        throw new Error(`invalid Slack MCP config ${configPath}: ${e.message}`);
+    }
+    const userAgent = fileConfig.userAgent || "Mozilla/5.0";
 
     return { configPath, secretsDir, xoxcPath, xoxdPath, allowedWriteChannels, userAgent };
 }
 
+function legacyEnvDiagnostic(env = process.env) {
+    const mappings = [
+        ["SLACK_MCP_SECRETS_DIR", "secretsDir"],
+        ["SLACK_MCP_XOXC_PATH", "xoxcPath"],
+        ["SLACK_MCP_XOXD_PATH", "xoxdPath"],
+        ["SLACK_MCP_ALLOWED_WRITE_CHANNELS", "allowedWriteChannels"],
+        ["SLACK_MCP_USER_AGENT", "userAgent"],
+    ]
+        .filter(([key]) => typeof env[key] === "string" && env[key].trim() !== "")
+        .map(([key, configKey]) => `  ${key} -> "${configKey}"`);
+    if (typeof env.SLACK_MCP_CONFIG === "string" && env.SLACK_MCP_CONFIG.trim() !== "") {
+        mappings.push(`  SLACK_MCP_CONFIG -> ignored; the config path is fixed at ${DEFAULT_CONFIG_PATH}`);
+    }
+    if (mappings.length === 0) {
+        return null;
+    }
+    return [
+        "Warning: obsolete Slack MCP environment configuration detected. Environment-variable configuration has been removed and is ignored.",
+        `Move these settings into ${DEFAULT_CONFIG_PATH} and remove the variables from your MCP host environment:`,
+        ...mappings,
+        "Write tools stay deny-by-default until allowedWriteChannels is configured in the config file.",
+    ].join("\n");
+}
+
 function readSecret(filePath, label) {
     if (!fs.existsSync(filePath)) {
         throw new Error(`missing ${label} (looked at ${filePath})`);
@@ -230,6 +277,86 @@ function createSlackClient({ xoxcToken, xoxdToken, userAgent = "Mozilla/5.0" })
         return text;
     };
 
+    const resolveMessageFile = async ({ channelId, timestamp, threadTs }) => {
+        const rootTs = threadTs || timestamp;
+        let cursor;
+        let pages = 0;
+        const seenCursors = new Set();
+        for (;;) {
+            pages += 1;
+            let response;
+            try {
+                response = await slackApi("conversations.replies", {
+                    channel: channelId,
+                    ts: rootTs,
+                    limit: String(threadPageSize),
+                    cursor,
+                });
+            } catch (error) {
+                const reason = String(error?.message ?? error);
+                if (/ratelimit|rate_limited/i.test(reason)) {
+                    throw new Error(
+                        `${reason}. Retry later, or pass a Slack file ID or file permalink to skip the thread lookup.`
+                    );
+                }
+                throw error;
+            }
+            const message = (response.messages || []).find((item) => item.ts === timestamp);
+            if (message) {
+                const files = message.files || [];
+                if (!files.length) {
+                    throw new Error(`no files attached to message ${timestamp} in ${channelId}`);
+                }
+                if (files.length > 1) {
+                    const candidates = files
+                        .map((file) => `${file.id || "unknown id"} (${file.name || file.title || "untitled"})`)
+                        .join(", ");
+                    throw new Error(
+                        `message ${timestamp} has ${files.length} files; pass a file ID or file permalink to choose one: ${candidates}`
+                    );
+                }
+                return files[0];
+            }
+            const nextCursor = response.response_metadata?.next_cursor;
+            if (!nextCursor || seenCursors.has(nextCursor)) {
+                break;
+            }
+            if (pages >= maxThreadPages) {
+                throw new Error(
+                    `message ${timestamp} is beyond the first ${maxThreadPages * threadPageSize} messages of thread ${rootTs} in ${channelId}; pass a Slack file ID or file permalink to choose the attachment directly`
+                );
+            }
+            seenCursors.add(nextCursor);
+            cursor = nextCursor;
+        }
+        throw new Error(`message ${timestamp} not found in thread ${rootTs} in ${channelId}`);
+    };
+
+    // Writes the attachment exactly as Slack stores it: the response body is
+    // streamed to a temporary file beside the destination and renamed into
+    // place, so binary formats such as SVG are never decoded, large attachments
+    // are not buffered in memory, and a failed download leaves no partial file.
+    const saveSlackFile = async ({ reference, destinationPath }) => {
+        const target = parseFileReference(reference);
+        const file = target.message ? await resolveMessageFile(target.message) : { id: target.fileId };
+        const fileData = await getSlackFileData(file);
+        const downloadUrl = fileData.url_private_download || fileData.url_private;
+        if (!downloadUrl) {
+            throw new Error("Slack did not provide a private download URL for this file");
+        }
+        const filename = safeFilename(fileData.name || fileData.title || fileData.id);
+        const destination = resolveDestinationPath(destinationPath, filename);
+        const response = await fetch(downloadUrl, { headers: slackHeaders() });
+        if (!response.ok) {
+            throw new Error(`Slack file download failed: ${response.status}`);
+        }
+        const mimeType = (response.headers.get("content-type") || fileData.mimetype || "application/octet-stream")
+            .split(";", 1)[0]
+            .trim();
+        await writeResponseToFile(response, destination.path, { replaceExisting: destination.replaceExisting });
+        return { path: destination.path, filename: path.basename(destination.path), mimeType };
+    };
+
     const uploadSlackFiles = async ({ filePaths, channelId, threadTs, initialComment }) => {
         const localFiles = filePaths.map((filePath) => {
             const fileStats = fs.statSync(filePath);
@@ -346,7 +473,7 @@ function createSlackClient({ xoxcToken, xoxdToken, userAgent = "Mozilla/5.0" })
         return content;
     };
 
-    return { slackApi, formatMessages, uploadSlackFiles };
+    return { slackApi, formatMessages, uploadSlackFiles, saveSlackFile };
 }
 
 function parsePermalink(url) {
@@ -354,7 +481,13 @@ function parsePermalink(url) {
     if (!match) {
         throw new Error("invalid Slack permalink");
     }
-    return { channelId: match[1], timestamp: `${match[2]}.${match[3]}` };
+    const parsed = { channelId: match[1], timestamp: `${match[2]}.${match[3]}` };
+    // Reply permalinks carry the thread's parent timestamp in the query string.
+    const threadTs = url.match(/[?&]thread_ts=(\d+\.\d+)/)?.[1];
+    if (threadTs) {
+        parsed.threadTs = threadTs;
+    }
+    return parsed;
 }
 
 function requireString(value, name) {
@@ -364,6 +497,189 @@ function requireString(value, name) {
     return value.trim();
 }
 
+// Streams a Slack download into a temporary file beside the destination and
+// moves it into place, so a failed transfer never leaves a partial attachment
+// and a large file never has to fit in memory.
+async function writeResponseToFile(response, destinationPath, { replaceExisting = false } = {}) {
+    if (!response.body) {
+        throw new Error("Slack returned an empty file response");
+    }
+    const target = replaceExisting ? resolveSymlinkTarget(destinationPath) : destinationPath;
+    const tempPath = path.join(path.dirname(target), `.slack-save-${randomUUID()}.part`);
+    try {
+        await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(tempPath, { flags: "wx" }));
+    } catch (error) {
+        fs.rmSync(tempPath, { force: true });
+        throw new Error(`could not save Slack file: ${error.message}`);
+    }
+    try {
+        if (replaceExisting) {
+            // Replacing is allowed only for a path the caller named, and a
+            // symlink there means write the target rather than remove the link.
+            // Renaming creates a new inode, so carry the replaced file's mode
+            // over; ownership, ACLs, and xattrs are not preserved.
+            const mode = existingFileMode(target);
+            if (mode !== undefined) {
+                fs.chmodSync(tempPath, mode);
+            }
+            fs.renameSync(tempPath, target);
+        } else {
+            placeWithoutReplacing(tempPath, destinationPath);
+        }
+    } catch (error) {
+        fs.rmSync(tempPath, { force: true });
+        throw error;
+    }
+}
+
+// Links the finished temp file into place instead of renaming it, because link
+// fails with EEXIST when the destination appeared while the download ran.
+// Filesystems without hard-link support fall back to a checked rename.
+function placeWithoutReplacing(tempPath, destinationPath) {
+    try {
+        fs.linkSync(tempPath, destinationPath);
+    } catch (error) {
+        if (error.code === "EEXIST" || fs.existsSync(destinationPath)) {
+            throw new Error(`destination file already exists: ${destinationPath}; pass an explicit file path to overwrite it`);
+        }
+        fs.renameSync(tempPath, destinationPath);
+        return;
+    }
+    try {
+        fs.rmSync(tempPath, { force: true });
+    } catch {
+        // The destination link is in place; a leftover temp file is harmless.
+    }
+}
+
+// Follows a chain of symlinks so a save through a link writes the link's
+// target, including a target that does not exist yet. The returned path shares
+// a directory with the temp file, so cross-volume links are not renamed across
+// filesystems.
+function resolveSymlinkTarget(destinationPath) {
+    let current = destinationPath;
+    const seen = new Set();
+    for (;;) {
+        let stats;
+        try {
+            stats = fs.lstatSync(current);
+        } catch (error) {
+            if (error.code === "ENOENT" || error.code === "ENOTDIR") {
+                return current;
+            }
+            throw new Error(`could not access ${current}: ${error.code || error.message}`);
+        }
+        if (!stats.isSymbolicLink()) {
+            return current;
+        }
+        if (seen.has(current)) {
+            throw new Error(`could not resolve symlink ${destinationPath}: link loop`);
+        }
+        seen.add(current);
+        let linkTarget;
+        try {
+            linkTarget = fs.readlinkSync(current);
+        } catch (error) {
+            throw new Error(`could not access ${current}: ${error.code || error.message}`);
+        }
+        current = path.resolve(path.dirname(current), linkTarget);
+    }
+}
+
+// Returns the mode of an existing regular file so a replacement keeps it, or
+// undefined for a path that does not exist (or is not a file).
+function existingFileMode(filePath) {
+    try {
+        const stats = fs.statSync(filePath);
+        return stats.isFile() ? stats.mode & 0o777 : undefined;
+    } catch (error) {
+        if (error.code === "ENOENT" || error.code === "ENOTDIR") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+
+const WINDOWS_RESERVED_NAME = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\..*)?$/i;
+
+// A saved attachment keeps the name Slack reports, but a path separator must
+// not let the name escape the destination directory, and Windows interprets
+// names such as "Q3: plan.pdf" as an alternate data stream on "Q3" while
+// reserved device names are unusable as files. Such characters are replaced on
+// Windows; other platforms keep the original name.
+function safeFilename(name, platform = process.platform) {
+    let value = String(name ?? "").trim().replace(/[\\/]+/g, "_");
+    if (platform === "win32") {
+        value = value.replace(/[<>:"|?*\u0000-\u001f]/g, "_").replace(/[. ]+$/, "");
+        if (WINDOWS_RESERVED_NAME.test(value)) {
+            value = `_${value}`;
+        }
+    }
+    return value && value !== "." && value !== ".." ? value : "slack-file";
+}
+
+function statDestinationPath(candidate) {
+    try {
+        return fs.statSync(candidate);
+    } catch (error) {
+        if (error.code === "ENOENT" || error.code === "ENOTDIR") {
+            return undefined;
+        }
+        throw new Error(`could not access ${candidate}: ${error.code || error.message}`);
+    }
+}
+
+// Resolves a destination that is either an existing directory (keep Slack's
+// filename, refusing to replace a file already there) or the full path of the
+// file to write. The parent directory must already exist, so a typo fails
+// before the attachment is downloaded.
+function resolveDestinationPath(destinationPath, filename) {
+    const value = requireString(destinationPath, "destination_path");
+    const resolved = path.resolve(expandHome(value));
+    const stats = statDestinationPath(resolved);
+    if (stats?.isDirectory()) {
+        const target = path.join(resolved, filename);
+        if (fs.existsSync(target)) {
+            throw new Error(`destination file already exists: ${target}; pass an explicit file path to overwrite it`);
+        }
+        return { path: target, replaceExisting: false };
+    }
+    if (stats && !stats.isFile()) {
+        throw new Error(`destination is not a regular file or directory: ${resolved}`);
+    }
+    if (!stats && /[\\/]$/.test(value)) {
+        throw new Error(`destination directory does not exist: ${resolved}`);
+    }
+    const directory = path.dirname(resolved);
+    const directoryStats = statDestinationPath(directory);
+    if (!directoryStats) {
+        throw new Error(`destination directory does not exist: ${directory}`);
+    }
+    if (!directoryStats.isDirectory()) {
+        throw new Error(`destination parent is not a directory: ${directory}`);
+    }
+    return { path: resolved, replaceExisting: true };
+}
+
+// Accepts a Slack file ID (F…), a file permalink (/files/F…), or a message
+// permalink (/archives/C…/p…). Anything else is rejected rather than guessed.
+function parseFileReference(reference) {
+    const value = requireString(reference, "file");
+    const filePermalink = value.match(/\/files\/(?:[A-Z0-9]+\/)?(F[A-Z0-9]+)/i);
+    if (filePermalink) {
+        return { fileId: filePermalink[1].toUpperCase() };
+    }
+    if (/^F[A-Z0-9]+$/i.test(value)) {
+        return { fileId: value.toUpperCase() };
+    }
+    if (value.includes("/archives/")) {
+        return { message: parsePermalink(value) };
+    }
+    throw new Error(
+        `invalid Slack file reference: ${value} (expected a Slack permalink or a file ID such as F0123ABCD)`
+    );
+}
+
 function assertAllowedWriteChannel(channelId, allowed) {
     if (!allowed.has(channelId)) {
         throw new Error(`writes are not allowed for channel ${channelId}`);
@@ -395,7 +711,9 @@ function withAgentPrefix(text, model) {
 const AgentModelField = z
     .string()
     .optional()
-    .describe("Model you are running, e.g. gpt-5.1, shown in the 🤖 prefix. Omit when unknown.");
+    .describe(
+        "Backend model ID you are running, for example claude-sonnet-4-5, not a display name; shown in the 🤖 prefix. Always pass it on an agent-authored post, and omit it only when your client cannot determine its model ID."
+    );
 
 const ReadPermalinkSchema = z.object({
     url: z.string().describe("Slack permalink, e.g. https://<workspace>.slack.com/archives/C.../p..."),
@@ -433,6 +751,19 @@ const UploadFilesSchema = z.object({
     model: AgentModelField,
 });
 
+const SaveFileSchema = z.object({
+    file: z
+        .string()
+        .min(1)
+        .describe("Slack permalink for the message or file, or a Slack file ID such as F0123ABCD."),
+    destination_path: z
+        .string()
+        .min(1)
+        .describe(
+            "Local file path to write, or an existing directory that keeps the attachment's filename. An existing directory refuses to replace a file already there; pass an explicit file path to overwrite."
+        ),
+});
+
 const EditMessageSchema = z.object({
     channel_id: z.string(),
     timestamp: z.string().describe("Timestamp of the message or thread reply to edit."),
@@ -465,7 +796,7 @@ const TOOLS = [
     },
     {
         name: "slack_reply_to_thread",
-        description: "Reply to a Slack thread. The posted text is prefixed with `🤖:` — or `🤖 <model>:` when model is given — so readers can tell it came from an agent; pass model to name the model writing it. Restricted to allowed channels.",
+        description: "Reply to a Slack thread. The posted text is prefixed with `🤖:` — or `🤖 <model>:` when model is given — so readers can tell it came from an agent; always pass model with the backend model ID you are running when you know it, and omit it only when you cannot determine it. Restricted to allowed channels.",
         inputSchema: zodToJsonSchema(ReplyToThreadSchema),
     },
     {
@@ -480,19 +811,25 @@ const TOOLS = [
     },
     {
         name: "slack_upload_files",
-        description: "Upload one or more local files to a channel or thread. A given initial_comment is prefixed with `🤖:` — or `🤖 <model>:` when model is given — so readers can tell it came from an agent; pass model to name the model writing it, and note that model has no effect without initial_comment. Restricted to allowed channels.",
+        description: "Upload one or more local files to a channel or thread. A given initial_comment is prefixed with `🤖:` — or `🤖 <model>:` when model is given — so readers can tell it came from an agent; always pass model with the backend model ID you are running when you know it (it has no effect without initial_comment), and omit it only when you cannot determine it. Restricted to allowed channels.",
         inputSchema: zodToJsonSchema(UploadFilesSchema),
     },
+    {
+        name: "slack_save_file",
+        description:
+            "Save a file attached to a Slack message to a local path, keeping the original bytes. Accepts a message or file permalink, or a file ID. Returns the saved path, filename, and MIME type. The destination's parent directory must exist; an existing directory keeps the attachment's filename, with characters the local filesystem rejects replaced, and refuses to overwrite an existing file.",
+        inputSchema: zodToJsonSchema(SaveFileSchema),
+    },
     {
         name: "slack_edit_message",
-        description: "Edit an authored Slack message or thread reply by channel id and timestamp. Replaces the message text, prefixed with `🤖:` — or `🤖 <model>:` when model is given — unless it already carries the prefix; pass model to name the model writing it, and set agent_authored to false when the new text is not agent-written. Any existing Block Kit blocks are removed by Slack. Restricted to allowed channels.",
+        description: "Edit an authored Slack message or thread reply by channel id and timestamp. Replaces the message text, prefixed with `🤖:` — or `🤖 <model>:` when model is given — unless it already carries the prefix; always pass model with the backend model ID you are running when you know it, and omit it only when you cannot determine it. Set agent_authored to false when the new text is not agent-written. Any existing Block Kit blocks are removed by Slack. Restricted to allowed channels.",
         inputSchema: zodToJsonSchema(EditMessageSchema),
     },
 ];
 
 // ── Execute factory (exported for tests) ─────────────────────────────────────
 
-function createExecuteToolCall({ slackApi, formatMessages, uploadSlackFiles, allowedWriteChannels }) {
+function createExecuteToolCall({ slackApi, formatMessages, uploadSlackFiles, saveSlackFile, allowedWriteChannels }) {
     const allowed = new Set(allowedWriteChannels);
     return async function executeToolCall(name, args) {
         switch (name) {
@@ -580,6 +917,22 @@ function createExecuteToolCall({ slackApi, formatMessages, uploadSlackFiles, all
                 };
             }
 
+            case "slack_save_file": {
+                const a = SaveFileSchema.parse(args);
+                const saved = await saveSlackFile({
+                    reference: requireString(a.file, "file"),
+                    destinationPath: requireString(a.destination_path, "destination_path"),
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `saved file: ${saved.path}\nfilename: ${saved.filename}\nmime type: ${saved.mimeType}`,
+                        },
+                    ],
+                };
+            }
+
             case "slack_edit_message": {
                 const a = EditMessageSchema.parse(args);
                 const channelId = requireString(a.channel_id, "channel_id");
@@ -625,6 +978,11 @@ function createExecuteToolCall({ slackApi, formatMessages, uploadSlackFiles, all
 // ── Main ─────────────────────────────────────────────────────────────────────
 
 async function main() {
+    const legacyDiagnostic = legacyEnvDiagnostic();
+    if (legacyDiagnostic) {
+        console.error(legacyDiagnostic);
+    }
+
     let config;
     try {
         config = loadConfig();
@@ -642,14 +1000,14 @@ async function main() {
         process.exit(1);
     }
 
-    const { slackApi, formatMessages, uploadSlackFiles } = createSlackClient({ xoxcToken, xoxdToken, userAgent: config.userAgent });
+    const { slackApi, formatMessages, uploadSlackFiles, saveSlackFile } = createSlackClient({ xoxcToken, xoxdToken, userAgent: config.userAgent });
 
     const server = new Server(
-        { name: "yt-slack-mcp", version: "0.1.0" },
+        SERVER_INFO,
         {
             capabilities: { tools: {} },
             instructions:
-                "MCP server for Slack. Read with slack_read_permalink, slack_get_replies, slack_get_history; write with slack_reply_to_thread, slack_add_reaction, slack_remove_reaction, slack_upload_files, slack_edit_message (restricted to allowed channels). Messages sent by the write tools are prefixed with `🤖:` by default, and slack_edit_message can opt out with agent_authored false; pass model with the model you are running to include it in the prefix.",
+                "MCP server for Slack. Read with slack_read_permalink, slack_get_replies, slack_get_history; save an attachment with slack_save_file; write with slack_reply_to_thread, slack_add_reaction, slack_remove_reaction, slack_upload_files, slack_edit_message (restricted to allowed channels). Messages sent by the write tools are prefixed with `🤖:` by default, and slack_edit_message can opt out with agent_authored false; always pass model with the backend model ID you are running when you know it, for example claude-sonnet-4-5, so the prefix names the model — omit it only when you cannot determine it.",
         }
     );
 
@@ -659,6 +1017,7 @@ async function main() {
         slackApi,
         formatMessages,
         uploadSlackFiles,
+        saveSlackFile,
         allowedWriteChannels: config.allowedWriteChannels,
     });
 
@@ -691,6 +1050,8 @@ if (isMain) {
 
 export {
     TOOLS,
+    SERVER_INFO,
+    parseChannelList,
     parsePermalink,
     requireString,
     assertAllowedWriteChannel,
@@ -698,13 +1059,17 @@ export {
     createExecuteToolCall,
     createSlackClient,
     loadConfig,
+    legacyEnvDiagnostic,
     expandHome,
-    parseChannelList,
+    parseFileReference,
+    safeFilename,
+    resolveDestinationPath,
     ReadPermalinkSchema,
     GetRepliesSchema,
     GetHistorySchema,
     ReplyToThreadSchema,
     AddReactionSchema,
     UploadFilesSchema,
+    SaveFileSchema,
     EditMessageSchema,
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yt-slack-mcp",
-  "version": "0.5.0",
-  "description": "MCP server for Slack — read permalinks, threads, and channel history; reply to threads; add or remove reactions; edit messages.",
+  "version": "0.7.0",
+  "description": "MCP server for Slack — read permalinks, threads, and channel history; save attachments to local paths; reply to threads; add or remove reactions; edit messages.",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -11,7 +11,8 @@
     "test": "node --test --experimental-test-coverage"
   },
   "files": [
-    "index.js"
+    "index.js",
+    "skills/*/SKILL.md"
   ],
   "keywords": [
     "mcp",

package/skills/slack-mcp/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: slack-mcp
+description: Read and write Slack through yt-slack-mcp — read permalinks, threads, channel history, and attachments; save an attachment to a local file; reply in threads, react, upload files, and edit messages in allowed channels. Use when asked to inspect a Slack link, summarize a channel or thread, find recent channel messages, save an attachment, or reply, react, upload, or edit in Slack.
+---
+
+# Slack MCP
+
+Use the `yt-slack-mcp` MCP server through this skill. Read before writing, and
+write only where the channel allow-list permits.
+
+Server: `yt-slack-mcp` 0.7.0, launched as `npx yt-slack-mcp` over stdio.
+
+## Setup and auth
+
+The server talks to Slack through your logged-in browser session, not a bot
+token.
+
+1. Save the `xoxc` token (Slack web localStorage) as a single line in
+   `~/.config/yt-slack-mcp/secrets/slack-xoxc.txt`.
+2. Save the `xoxd` token (the cookie named `d`) as a single line in
+   `~/.config/yt-slack-mcp/secrets/slack-xoxd.txt`.
+3. Allow writes by listing channel IDs in `allowedWriteChannels` in
+   `~/.config/yt-slack-mcp/config.json`. With an empty or missing list, every
+   write is refused.
+
+Configuration is file-based: `config.json` also accepts `secretsDir`, `xoxcPath`,
+`xoxdPath`, and `userAgent`, and the defaults apply when a key is absent. Never
+echo a token or a file's contents back to the user.
+
+### What each failure means
+
+| Message | Cause | Fix |
+|---------|-------|-----|
+| `Error: missing slack-xoxc.txt (looked at <path>)` | The `xoxc` file is absent at startup; the server exits before listing tools. | Write the token file at the reported path, or set `xoxcPath` in `config.json` to point at it. |
+| `Error: missing slack-xoxd.txt (looked at <path>)` | Same, for the `xoxd` file. | Write the token file at the reported path, or set `xoxdPath` in `config.json` to point at it. |
+| `Error: invalid Slack MCP config <path>: <detail>` | `config.json` is not valid JSON, or a value has the wrong type; the detail names the problem. | Fix the JSON, correct the value, or remove the file. |
+| `Error: writes are not allowed for channel <id>` | The channel is not in the allow-list. | Add the channel ID to the allow-list if the user wants writes there; never work around the refusal. |
+| `slack <method> failed: invalid_auth` (or `not_authed`) | The browser session expired or the token was copied incorrectly. | Refresh the `xoxc`/`xoxd` pair, then retry once. |
+| `Error: missing <name>` | A required write-tool argument (`channel_id`, `thread_ts`, `timestamp`, `text`, `reaction`) was blank. | Supply the actual value; do not invent IDs. |
+
+Tool errors arrive as text starting with `Error:`. Report the text instead of
+retrying the same call unchanged.
+
+## Troubleshooting
+
+- **Writes refused or tokens missing after an upgrade.** Configuration is
+  file-based only: values supplied through environment variables are ignored.
+  Move `secretsDir`, `xoxcPath`, `xoxdPath`, `allowedWriteChannels`, and
+  `userAgent` into `~/.config/yt-slack-mcp/config.json`.
+- **Only some expected channels are writable.** `allowedWriteChannels` is the
+  complete list with no additive default; compare it with the channel IDs the
+  user expects.
+- **The server exits at startup.** A reported token path is missing; create the
+  file at that path. An empty or stale token does not stop startup; the first
+  Slack call fails later as `invalid_auth`.
+- **A write still fails inside an allowed channel.** The browser session may have
+  lost write access or the message may be outside the edit window; report the
+  exact `Error:` text instead of retrying.
+
+## Tool map
+
+Choose the read tool from what the user gave you, and the write tool from the
+action they asked for.
+
+| Tool | Use it when |
+|------|-------------|
+| `slack_read_permalink` | A Slack link is the input. Reads the linked message's thread, including inline images, PDF text, and text attachments. |
+| `slack_save_file` | The user needs an attachment on disk. Accepts a message or file permalink, or a file ID, plus `destination_path`; keeps the original bytes, replaces characters the OS rejects in the filename, and refuses to overwrite an existing file in a directory destination. Reports the saved path, filename, and MIME type. It is not channel-restricted. |
+| `slack_get_replies` | You have a channel ID and thread timestamp and need that thread again or its latest replies. |
+| `slack_get_history` | There is no link or thread: read recent messages when you have a channel ID. The tool does not resolve channel names. |
+| `slack_reply_to_thread` | Post a reply into an existing thread. Requires `channel_id`, `thread_ts`, `text`, and `model` set to your backend model ID whenever you can determine it. |
+| `slack_add_reaction` | Mark or acknowledge a message without posting text. |
+| `slack_remove_reaction` | Remove a reaction this account added. |
+| `slack_upload_files` | Post up to 10 local files (10 MB each) to a channel or thread, with an optional `initial_comment`. |
+| `slack_edit_message` | Correct a message this account already posted, by channel ID and timestamp. |
+
+The server has no plain top-level text post; a reply needs an existing thread.
+A file upload with an `initial_comment` is the only way to start a new top-level
+message. Say so instead of promising a text post.
+
+## Recipes
+
+### Read a permalink and reply in its thread
+
+1. Call `slack_read_permalink` with the `url`.
+2. Take the channel ID from the permalink and the root `[ts]` from the first
+   returned message.
+3. Read the whole thread before answering; do not repost what is already there.
+4. Call `slack_reply_to_thread` with `channel_id`, `thread_ts`, `text`, and
+   `model` set to the backend model ID you are running, for example
+   `claude-sonnet-4-5` — not a display name.
+
+### Summarize a channel
+
+1. Resolve the channel ID first. The tool does not accept names like `#ops`; take
+   the ID from a permalink or ask the user.
+2. Call `slack_get_history` with `channel_id` and `limit` up to 200.
+3. Summarize in the conversation, quoting `[ts]` values when the user needs to
+   locate a message.
+4. Post the summary only when asked, and only as a reply in a relevant thread or
+   as a file upload's `initial_comment`; there is no plain top-level text post.
+
+### Upload a file with a comment
+
+1. Resolve absolute local paths; at most 10 files, 10 MB each.
+2. Call `slack_upload_files` with `file_paths`, `channel_id`, an optional
+   `thread_ts`, and `initial_comment` when a message should accompany the files.
+3. Pass `model` with the backend model ID you are running; it is used only when
+   `initial_comment` is present, and without a comment the upload stays
+   comment-free.
+4. Report the returned file and message permalinks.
+
+### Save an attachment to disk
+
+1. Take the message or file permalink, or the file ID, from the user.
+2. Resolve the destination: an existing directory keeps Slack's filename, with
+   characters the OS rejects replaced, and refuses to overwrite a file already
+   there; pass an explicit file path to overwrite. Its parent directory must
+   exist.
+3. Call `slack_save_file` with `file` and `destination_path`.
+4. Report the returned saved path, filename, and MIME type. If the message has
+   several attachments, the error lists their IDs; retry with the one the user
+   meant.
+
+### Correct a posted message
+
+1. Call `slack_edit_message` with `channel_id`, the message `timestamp`, and the
+   replacement `text`.
+2. Leave `agent_authored` at its default for agent-written text; pass `model`
+   with your backend model ID so the prefix names the model.
+3. Pass `agent_authored: false` only when replacing agent text with the user's own
+   words, such as correcting their message; `model` is then ignored.
+4. Slack removes existing Block Kit blocks on edit and only allows edits to this
+   account's messages within its edit window.
+
+## Guardrails
+
+- Read before writing. Fetch the thread or channel context first, even when the
+  requested text seems obvious.
+- Stay inside the allow-list. Never attempt a write to a channel that is not
+  listed, and never suggest disabling the check to "make it work".
+- Always pass `model` on every text-writing call — reply, upload with a comment,
+  edit — with the backend model ID you are running, for example
+  `claude-sonnet-4-5`, not a display name, so posts read `🤖 <model ID>:`. Omit it
+  only when you cannot determine your model ID. Never add the prefix yourself;
+  the server adds it once.
+- `agent_authored: false` is an explicit correction of non-agent text, not a
+  default and not a way to hide that an agent posted.
+- Channel names are not resolved. Never pass `#name` as `channel_id`; use a
+  `C...`, `G...`, or `D...` ID from a permalink or ask the user.
+- Prefer edits over reposting. Do not "fix" a message by posting it again.