yt-slack-mcp 0.5.0 → 0.6.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Maksim Korinets
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Maksim Korinets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -9,6 +9,7 @@ A host-agnostic [Model Context Protocol](https://modelcontextprotocol.io) server
 - Return image attachments inline, extract text from PDFs, and return `text/*` attachment contents inline.
 - 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.
+- 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 `🤖 <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`.
 
 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.
@@ -19,11 +20,11 @@ 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_get_history` | Read recent channel history by channel ID (up to 200 messages). |
 | `slack_reply_to_thread` | Reply to a thread, with optional `model`, 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_upload_files` | Upload up to 10 local files (10 MB each) 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. |
 
 ## Agent message prefix
@@ -71,12 +72,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 +91,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 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 |
+| 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 |
+
+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 +134,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

@@ -20,6 +20,8 @@ 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;
@@ -46,14 +48,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,15 +80,16 @@ 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 };
 }
@@ -645,7 +663,7 @@ async function main() {
     const { slackApi, formatMessages, uploadSlackFiles } = createSlackClient({ xoxcToken, xoxdToken, userAgent: config.userAgent });
 
     const server = new Server(
-        { name: "yt-slack-mcp", version: "0.1.0" },
+        SERVER_INFO,
         {
             capabilities: { tools: {} },
             instructions:
@@ -691,6 +709,8 @@ if (isMain) {
 
 export {
     TOOLS,
+    SERVER_INFO,
+    parseChannelList,
     parsePermalink,
     requireString,
     assertAllowedWriteChannel,
@@ -699,7 +719,6 @@ export {
     createSlackClient,
     loadConfig,
     expandHome,
-    parseChannelList,
     ReadPermalinkSchema,
     GetRepliesSchema,
     GetHistorySchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yt-slack-mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP server for Slack — read permalinks, threads, and channel history; reply to threads; add or remove reactions; edit messages.",
   "type": "module",
   "main": "index.js",
@@ -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,134 @@
+---
+name: slack-mcp
+description: Read and write Slack through yt-slack-mcp — read permalinks, threads, channel history, and attachments; 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, 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.6.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_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 preferably `model`. |
+| `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 model you are running.
+
+### 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`, which is used only when `initial_comment` is present; without a
+   comment the upload stays comment-free.
+4. Report the returned file and message permalinks.
+
+### 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` 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".
+- Pass `model` on every text-writing call — reply, upload with a comment, edit —
+  so posts read `🤖 <model>:`. 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.