Merge branch 'main' into dependabot/github_actions/actions/setup-python-6

Author: mwbrooks

.gitignore

@@ -6,3 +6,7 @@
 
 # Git
 .worktrees/
+
+# Slack App Templates
+*/.slack/apps.json
+*/.slack/apps.dev.json

README.md

@@ -28,6 +28,10 @@ Behind the scenes, Casey has access to five simulated tools: knowledge base sear
 
 > **Note:** All tools return simulated data for demonstration purposes. In a production app, these would connect to your actual IT systems.
 
+### Slack MCP Server
+
+Casey also works with the [Slack MCP Server](https://docs.slack.dev/agents-ai/model-context-protocol), giving it the ability to search messages and files, read channel history and threads, send messages, schedule messages, and create or update Slack canvases. When deployed with OAuth (HTTP mode), Casey automatically connects to the Slack MCP Server using the user's token, unlocking these capabilities on top of the built-in IT tools.
+
 ## Local Development
 
 This repo uses a vendored (pre-release) build of `slack-bolt` from the [bolt-python](https://github.com/slackapi/bolt-python) `main` branch. The `.whl` file lives in `vendor/` and is referenced by each app's `requirements.txt`.

claude-agent-sdk/.env.sample

@@ -1,9 +1,15 @@
+# Required, set your Anthropic API key.
+ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
+
 # Optional, uncomment and set when running without the Slack CLI (python3 app.py).
 # SLACK_APP_TOKEN=YOUR_SLACK_APP_TOKEN
 # SLACK_BOT_TOKEN=YOUR_SLACK_BOT_TOKEN
 
+# Required for OAuth (app_oauth.py). Set your app's OAuth credentials.
+# SLACK_CLIENT_ID=YOUR_SLACK_CLIENT_ID
+# SLACK_CLIENT_SECRET=YOUR_SLACK_CLIENT_SECRET
+# SLACK_REDIRECT_URI=https://YOUR_NGROK_SUBDOMAIN.ngrok-free.app/slack/oauth_redirect
+# SLACK_SIGNING_SECRET=YOUR_SLACK_SIGNING_SECRET
+
 # Optional, uncomment and set when using a custom Slack instance.
 # SLACK_API_URL=YOUR_SLACK_API_URL
-
-# Required, set your Anthropic API key.
-ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY

claude-agent-sdk/.gitignore

@@ -39,5 +39,8 @@ logs/
 .pytype/
 .idea/
 
+# oauth data
+data/
+
 # claude
 .claude/*.local.json

claude-agent-sdk/README.md

@@ -22,6 +22,10 @@ Casey uses five simulated tools to assist users:
 
 > **Note:** All tools return simulated data for demonstration purposes. In a production app, these would connect to your actual IT systems.
 
+### Slack MCP Server
+
+Casey also works with the [Slack MCP Server](https://docs.slack.dev/agents-ai/model-context-protocol), giving it the ability to search messages and files, read channel history and threads, send messages, schedule messages, and create or update Slack canvases. When deployed with OAuth (HTTP mode), Casey automatically connects to the Slack MCP Server using the user's token, unlocking these capabilities on top of the built-in IT tools.
+
 ## Setup
 
 Before getting started, make sure you have a development workspace where you have permissions to install apps.
@@ -140,6 +144,101 @@ python3 app.py
 
 </details>
 
+<details><summary><strong>Using OAuth HTTP Server (with ngrok)</strong></summary>
+
+#### OAuth HTTP Server
+
+This mode uses an HTTP server instead of Socket Mode, which is required for OAuth-based distribution.
+
+1. Install [ngrok](https://ngrok.com/download) and start a tunnel:
+
+```sh
+ngrok http 3000
+```
+
+2. Copy the `https://*.ngrok-free.app` URL from the ngrok output.
+
+<details><summary><strong>Using Slack CLI</strong></summary>
+
+#### Slack CLI
+
+3. Update `manifest.json` for HTTP mode:
+   - Set `socket_mode_enabled` to `false`
+   - Replace `ngrok-free.app` with your ngrok domain (e.g. `YOUR_NGROK_SUBDOMAIN.ngrok-free.app`)
+
+4. Create a new local dev app:
+
+```sh
+slack install -E local
+```
+
+5. Enable MCP for your app:
+   - Run `slack app settings` to open your app's settings
+   - Navigate to **Agents & AI Apps** in the left-side navigation
+   - Toggle **Model Context Protocol** on
+
+6. Update your `.env` OAuth environment variables:
+   - Run `slack app settings` to open App Settings
+   - Copy **Client ID**, **Client Secret**, and **Signing Secret**
+   - Update `SLACK_REDIRECT_URI` in `.env` with your ngrok domain
+
+```sh
+SLACK_CLIENT_ID=YOUR_CLIENT_ID
+SLACK_CLIENT_SECRET=YOUR_CLIENT_SECRET
+SLACK_REDIRECT_URI=https://YOUR_NGROK_SUBDOMAIN.ngrok-free.app/slack/oauth_redirect
+SLACK_SIGNING_SECRET=YOUR_SIGNING_SECRET
+```
+
+7. Start the app:
+
+```sh
+slack run app_oauth.py
+```
+
+8. Click the install URL printed in the terminal to install the app to your workspace via OAuth.
+
+</details>
+
+<details><summary><strong>Using the Terminal</strong></summary>
+
+#### Terminal
+
+3. Create your Slack app at [api.slack.com/apps/new](https://api.slack.com/apps/new) using [`manifest.json`](./manifest.json). Before pasting the manifest, set `socket_mode_enabled` to `false` and replace `ngrok-free.app` with your ngrok domain.
+
+4. Install the app to your workspace and copy the following values into your `.env`:
+   - **Signing Secret** — from _Basic Information_
+   - **Bot User OAuth Token** — from _OAuth & Permissions_
+   - **Client ID** and **Client Secret** — from _Basic Information_
+
+```sh
+SLACK_SIGNING_SECRET=YOUR_SIGNING_SECRET
+SLACK_BOT_TOKEN=xoxb-YOUR_BOT_TOKEN
+SLACK_CLIENT_ID=YOUR_CLIENT_ID
+SLACK_CLIENT_SECRET=YOUR_CLIENT_SECRET
+SLACK_REDIRECT_URI=https://YOUR_NGROK_SUBDOMAIN.ngrok-free.app/slack/oauth_redirect
+```
+
+Replace `your-subdomain` in `SLACK_REDIRECT_URI` with your ngrok subdomain.
+
+5. Enable MCP for your app:
+   - Open your app at [api.slack.com/apps](https://api.slack.com/apps)
+   - Navigate to **Agents & AI Apps** in the left-side navigation
+   - Toggle **Model Context Protocol** on
+
+6. Start the app:
+
+```sh
+python3 app_oauth.py
+```
+
+7. Click the install URL printed in the terminal to install the app to your workspace via OAuth.
+
+</details>
+
+> **Note:** Each time ngrok restarts, it generates a new URL. You'll need to update the ngrok domain in `manifest.json`, `SLACK_REDIRECT_URI` in your `.env`, and re-install the app.
+
+</details>
+
 ### Using the App
 
 Once Casey is running, there are three ways to interact:
@@ -172,6 +271,14 @@ ruff format
 
 `app.py` is the entry point for the application and is the file you'll run to start the server. This project uses `AsyncApp` from Bolt for Python, with all handlers running asynchronously.
 
+### `app_oauth.py`
+
+`app_oauth.py` is an alternative entry point that runs the app in HTTP mode instead of Socket Mode. This is intended for deployments that use OAuth for app distribution. See the HTTP Mode section under Development for setup instructions.
+
+### `manifest_oauth.json`
+
+`manifest_oauth.json` is the app manifest configured for HTTP mode (Socket Mode disabled, with request URLs for event subscriptions and interactivity). Use this when setting up the app for HTTP mode instead of `manifest.json`.
+
 ### `/listeners`
 
 Every incoming request is routed to a "listener". This directory groups each listener based on the Slack Platform feature used.
@@ -205,3 +312,19 @@ The `tools` directory contains five IT helpdesk tools defined using the `@tool`
 ### `/thread_context`
 
 The `store.py` file implements a thread-safe in-memory session ID store, keyed by channel and thread. The Claude Agent SDK manages conversation history server-side via sessions, so only session IDs need to be tracked locally for resuming conversations.
+
+## Troubleshooting
+
+### MCP Server connection error: `HTTP error 400 (Bad Request)`
+
+If you see an error like:
+
+```
+Failed to connect to MCP server 'streamable_http: https://mcp.slack.com/mcp': HTTP error 400 (Bad Request)
+```
+
+This means the Slack MCP feature has not been enabled for your app. There is no manifest property for this yet, so it must be toggled on manually:
+
+1. Run `slack app settings` to open your app's settings page (or visit [api.slack.com/apps](https://api.slack.com/apps) and select your app)
+2. Navigate to **Agents & AI Apps** in the left-side navigation
+3. Toggle **Slack Model Context Protocol** on

claude-agent-sdk/agent/casey.py

@@ -6,6 +6,7 @@
     TextBlock,
     create_sdk_mcp_server,
 )
+from claude_agent_sdk.types import McpHttpServerConfig
 
 from agent.context import casey_deps_var
 from agent.deps import CaseyDeps
@@ -56,6 +57,7 @@
 2. Search the knowledge base for relevant articles
 3. If the KB has a solution, walk the user through it step by step
 4. If the issue requires action (password reset, ticket creation), use the appropriate tool
+   - For password resets: follow the instructions in the `trigger_password_reset` tool description to obtain the user's email before calling it
 5. After taking action, confirm what was done and what the user should expect next
 6. If you cannot resolve the issue, create a support ticket and let the user know
 
@@ -74,6 +76,21 @@
 Call this once when the issue is fully resolved (password reset done, ticket created, problem fixed).
 - Do not use `eyes` — it is added automatically
 
+## SLACK MCP SERVER
+You may have access to the Slack MCP Server, which gives you powerful Slack tools beyond \
+your built-in IT helpdesk tools. Use them whenever they would help the user.
+
+Available capabilities:
+- **Search**: Search messages and files across public channels, search for channels by name
+- **Read**: Read channel message history, read thread replies, read canvas documents
+- **Write**: Send messages, create draft messages, schedule messages for later
+- **Canvases**: Create, read, and update Slack canvas documents
+
+Use these tools proactively when they can help resolve an IT issue — for example, \
+searching for related reports from other users, checking a channel for outage updates, \
+or creating a canvas to document a solution. Also use them when the user explicitly \
+asks you to perform a Slack action like sending a message or creating a canvas.
+
 ## BOUNDARIES
 - You are an IT helpdesk agent only — politely redirect non-IT questions
 - Do not make up system statuses or ticket numbers — always use the provided tools
@@ -95,7 +112,9 @@
     ],
 )
 
-ALLOWED_TOOLS = [
+SLACK_MCP_URL = "https://mcp.slack.com/mcp"
+
+CASEY_TOOLS = [
     "add_emoji_reaction",
     "check_system_status",
     "create_support_ticket",
@@ -124,10 +143,21 @@ async def run_casey_agent(
     if deps:
         casey_deps_var.set(deps)
 
+    mcp_servers: dict = {"casey-tools": casey_tools_server}
+    allowed_tools = list(CASEY_TOOLS)
+
+    if deps and deps.user_token:
+        mcp_servers["slack-mcp"] = McpHttpServerConfig(
+            type="http",
+            url=SLACK_MCP_URL,
+            headers={"Authorization": f"Bearer {deps.user_token}"},
+        )
+        allowed_tools.append("mcp__slack-mcp__*")
+
     options = ClaudeAgentOptions(
         system_prompt=CASEY_SYSTEM_PROMPT,
-        mcp_servers={"casey-tools": casey_tools_server},
-        allowed_tools=ALLOWED_TOOLS,
+        mcp_servers=mcp_servers,
+        allowed_tools=allowed_tools,
         permission_mode="bypassPermissions",
     )
 

claude-agent-sdk/agent/deps.py

@@ -10,3 +10,4 @@ class CaseyDeps:
     channel_id: str
     thread_ts: str
     message_ts: str
+    user_token: str | None = None

claude-agent-sdk/agent/tools/password_reset.py

@@ -7,7 +7,11 @@
         "Trigger a password reset for a specified user account. "
         "Use this tool when a user requests a password reset for their own account "
         "or reports being locked out. The reset link will be sent to their registered "
-        "email address."
+        "email address. "
+        "IMPORTANT: You need the user's email address for target_user. "
+        "First, try to look up the user's Slack profile to get their email address. "
+        "If the lookup fails or does not return an email, ask the user for their email address. "
+        "Never guess or assume — you must either look it up or ask for it."
     ),
     input_schema={"target_user": str},
 )
@@ -17,7 +21,7 @@ async def trigger_password_reset_tool(args):
 
     text = (
         f"Password reset initiated for **{target_user}**.\n\n"
-        f"A reset link has been sent to the email address on file. "
+        f"A reset link has been emailed to **{target_user}**. "
         f"The link will expire in 30 minutes.\n\n"
         f"_If the user doesn't receive the email within 5 minutes, "
         f"ask them to check their spam folder or verify their registered email address._"

claude-agent-sdk/app_oauth.py

@@ -0,0 +1,32 @@
+import logging
+import os
+
+from dotenv import load_dotenv
+from slack_bolt.async_app import AsyncApp
+from slack_sdk.web.async_client import AsyncWebClient
+
+from listeners import register_listeners
+from oauth import oauth_settings
+
+load_dotenv(dotenv_path=".env", override=False)
+
+logging.basicConfig(level=logging.DEBUG)
+
+app = AsyncApp(
+    signing_secret=os.environ.get("SLACK_SIGNING_SECRET"),
+    token=os.environ.get("SLACK_BOT_TOKEN"),
+    client=AsyncWebClient(
+        base_url=os.environ.get("SLACK_API_URL", "https://slack.com/api"),
+        token=os.environ.get("SLACK_BOT_TOKEN"),
+    ),
+    # Allow bot-posted messages (e.g. issue modal submissions with metadata)
+    # to reach the message handler instead of being silently dropped
+    ignoring_self_events_enabled=False,
+    oauth_settings=oauth_settings,
+)
+
+register_listeners(app)
+
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", 3000))
+    app.start(port=port)

claude-agent-sdk/listeners/events/app_home_opened.py

@@ -1,4 +1,6 @@
+import os
 from logging import Logger
+from urllib.parse import urljoin
 
 from slack_bolt.context.async_context import AsyncBoltContext
 from slack_sdk.web.async_client import AsyncWebClient
@@ -12,7 +14,17 @@ async def handle_app_home_opened(
     """Publish the App Home view when a user opens the app's Home tab."""
     try:
         user_id = context.user_id
-        view = build_app_home_view()
+        install_url = None
+        is_connected = False
+
+        if os.environ.get("SLACK_CLIENT_ID"):
+            if context.user_token:
+                is_connected = True
+            else:
+                redirect_uri = os.environ.get("SLACK_REDIRECT_URI", "")
+                install_url = urljoin(redirect_uri, "/slack/install")
+
+        view = build_app_home_view(install_url=install_url, is_connected=is_connected)
         await client.views_publish(user_id=user_id, view=view)
     except Exception as e:
         logger.exception(f"Failed to publish App Home: {e}")