@capybara-hq/plugin-slack 0.1.0-rc.1 → 0.1.0-rc.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,243 @@
1
+ # Create the Slack app
2
+
3
+ This connects one Slack workspace to Capybara as a bot. People message the bot directly, mention
4
+ it in channels and use the slash commands `/new`, `/env` and `/capybara`. You need permission to
5
+ create apps in the workspace (with "Only allow pre-approved apps", a workspace admin approves the
6
+ app after step 2).
7
+
8
+ ## 1. Create the app from the manifest
9
+
10
+ Open <https://api.slack.com/apps>, choose **Create New App → From a manifest**, pick your
11
+ workspace and paste the manifest below.
12
+
13
+ ::: mode long_connection
14
+ Socket Mode needs no public address: Slack keeps a connection open to Capybara. The manifest
15
+ registers the bot scopes, the events and the slash commands the plugin needs.
16
+
17
+ ```yaml title="App manifest (Socket Mode)"
18
+ # Slack app manifest for the Capybara Slack plugin, Socket Mode (long connection).
19
+ # Reference: https://docs.slack.dev/reference/app-manifest (checked 2026-11-09).
20
+ display_information:
21
+ # Slack caps app names at 35 characters; shorten it in the app settings if it is longer.
22
+ name: "{{connectionName}}"
23
+ description: Chat with your organization's Capybara agents.
24
+ background_color: "#3d2f24"
25
+ features:
26
+ app_home:
27
+ home_tab_enabled: false
28
+ messages_tab_enabled: true
29
+ messages_tab_read_only_enabled: false
30
+ bot_user:
31
+ display_name: Capybara
32
+ always_online: true
33
+ slash_commands:
34
+ - command: /new
35
+ description: Start a new conversation (direct message)
36
+ should_escape: false
37
+ - command: /env
38
+ description: List or set your default environment (direct message)
39
+ usage_hint: "[name]"
40
+ should_escape: false
41
+ - command: /capybara
42
+ description: Run a skill
43
+ usage_hint: "<skill> [args]"
44
+ should_escape: false
45
+ oauth_config:
46
+ # Sign in with Slack (identity-source@1).
47
+ redirect_urls:
48
+ - "{{signInCallbackUrl}}"
49
+ scopes:
50
+ bot:
51
+ - chat:write # post and update replies and cards
52
+ - commands # slash commands /new, /env, /capybara
53
+ - im:write # conversations.open: tell the bot's own DM from other DMs
54
+ - im:history # message.im: direct messages to the bot
55
+ - app_mentions:read # app_mention: @capybara in channels
56
+ - channels:history # message.channels: thread replies in public channels
57
+ - groups:history # message.groups: thread replies in private channels
58
+ - users:read # users.info; team_join / user_change; users.list
59
+ - users:read.email # directory@1: email addresses in users.list
60
+ settings:
61
+ event_subscriptions:
62
+ bot_events:
63
+ - message.im
64
+ - app_mention
65
+ - message.channels
66
+ - message.groups
67
+ - team_join
68
+ - user_change
69
+ interactivity:
70
+ is_enabled: true
71
+ socket_mode_enabled: true
72
+ org_deploy_enabled: false
73
+ token_rotation_enabled: false
74
+ ```
75
+ :::
76
+
77
+ ::: mode webhook
78
+ In webhook mode Slack posts events, card clicks and slash commands to this connection's address,
79
+ which exists only once the connection is saved. Start with this basic manifest: it registers the
80
+ bot and its scopes, without any address. Step 5 adds the addresses after saving.
81
+
82
+ ```yaml title="Basic app manifest (webhook)"
83
+ # Slack app manifest for the Capybara Slack plugin, webhook inbound mode, first step: no
84
+ # addresses yet. Step 5 replaces it with the full manifest once the connection is saved.
85
+ # Reference: https://docs.slack.dev/reference/app-manifest (checked 2026-11-09).
86
+ display_information:
87
+ # Slack caps app names at 35 characters; shorten it in the app settings if it is longer.
88
+ name: "{{connectionName}}"
89
+ description: Chat with your organization's Capybara agents.
90
+ background_color: "#3d2f24"
91
+ features:
92
+ app_home:
93
+ home_tab_enabled: false
94
+ messages_tab_enabled: true
95
+ messages_tab_read_only_enabled: false
96
+ bot_user:
97
+ display_name: Capybara
98
+ always_online: true
99
+ oauth_config:
100
+ # Sign in with Slack (identity-source@1).
101
+ redirect_urls:
102
+ - "{{signInCallbackUrl}}"
103
+ scopes:
104
+ bot:
105
+ - chat:write # post and update replies and cards
106
+ - commands # slash commands /new, /env, /capybara
107
+ - im:write # conversations.open: tell the bot's own DM from other DMs
108
+ - im:history # message.im: direct messages to the bot
109
+ - app_mentions:read # app_mention: @capybara in channels
110
+ - channels:history # message.channels: thread replies in public channels
111
+ - groups:history # message.groups: thread replies in private channels
112
+ - users:read # users.info; team_join / user_change; users.list
113
+ - users:read.email # directory@1: email addresses in users.list
114
+ settings:
115
+ socket_mode_enabled: false
116
+ org_deploy_enabled: false
117
+ token_rotation_enabled: false
118
+ ```
119
+ :::
120
+
121
+ ::: mode long_connection
122
+ ## 2. Create the app-level token
123
+
124
+ Under **Basic Information → App-Level Tokens** choose **Generate Token and Scopes**, add the scope
125
+ `connections:write` and copy the `xapp-…` token into the **App-level token** field below.
126
+
127
+ ::check app-token App-level token opens a Socket Mode connection
128
+ :::
129
+
130
+ ::: mode webhook
131
+ ## 2. Copy the signing secret
132
+
133
+ Copy **Basic Information → App Credentials → Signing Secret** into the **Signing secret** field
134
+ below. Every webhook request is verified with it; without it every request is refused.
135
+ :::
136
+
137
+ ## 3. Install the app and copy the bot token
138
+
139
+ Choose **Install App → Install to Workspace** and copy the **Bot User OAuth Token** (`xoxb-…`)
140
+ into the **Bot token** field below.
141
+
142
+ ::check bot-token Bot token works
143
+ ::check bot-scopes The app has every scope in the manifest
144
+
145
+ ## 4. Save the channel
146
+
147
+ Fill in the remaining fields on this page and save. Capybara verifies the bot token when you save.
148
+ With Socket Mode that is all: the bot connects and is ready for messages.
149
+
150
+ ::: mode webhook
151
+ ## 5. Point Slack at this connection
152
+
153
+ After saving, the manifest below carries this connection's address `{{webhookUrl}}` (before saving
154
+ it is shown as written). In the app open **App Manifest**, replace the manifest with this one and
155
+ save. It adds the slash commands, the event subscriptions and interactivity, all sent to this
156
+ address.
157
+
158
+ ```yaml title="App manifest (webhook)"
159
+ # Slack app manifest for the Capybara Slack plugin, webhook inbound mode.
160
+ # Reference: https://docs.slack.dev/reference/app-manifest (checked 2026-11-09).
161
+ display_information:
162
+ # Slack caps app names at 35 characters; shorten it in the app settings if it is longer.
163
+ name: "{{connectionName}}"
164
+ description: Chat with your organization's Capybara agents.
165
+ background_color: "#3d2f24"
166
+ features:
167
+ app_home:
168
+ home_tab_enabled: false
169
+ messages_tab_enabled: true
170
+ messages_tab_read_only_enabled: false
171
+ bot_user:
172
+ display_name: Capybara
173
+ always_online: true
174
+ slash_commands:
175
+ - command: /new
176
+ url: "{{webhookUrl}}"
177
+ description: Start a new conversation (direct message)
178
+ should_escape: false
179
+ - command: /env
180
+ url: "{{webhookUrl}}"
181
+ description: List or set your default environment (direct message)
182
+ usage_hint: "[name]"
183
+ should_escape: false
184
+ - command: /capybara
185
+ url: "{{webhookUrl}}"
186
+ description: Run a skill
187
+ usage_hint: "<skill> [args]"
188
+ should_escape: false
189
+ oauth_config:
190
+ # Sign in with Slack (identity-source@1).
191
+ redirect_urls:
192
+ - "{{signInCallbackUrl}}"
193
+ scopes:
194
+ bot:
195
+ - chat:write # post and update replies and cards
196
+ - commands # slash commands /new, /env, /capybara
197
+ - im:write # conversations.open: tell the bot's own DM from other DMs
198
+ - im:history # message.im: direct messages to the bot
199
+ - app_mentions:read # app_mention: @capybara in channels
200
+ - channels:history # message.channels: thread replies in public channels
201
+ - groups:history # message.groups: thread replies in private channels
202
+ - users:read # users.info; team_join / user_change; users.list
203
+ - users:read.email # directory@1: email addresses in users.list
204
+ settings:
205
+ event_subscriptions:
206
+ request_url: "{{webhookUrl}}"
207
+ bot_events:
208
+ - message.im
209
+ - app_mention
210
+ - message.channels
211
+ - message.groups
212
+ - team_join
213
+ - user_change
214
+ interactivity:
215
+ is_enabled: true
216
+ request_url: "{{webhookUrl}}"
217
+ socket_mode_enabled: false
218
+ org_deploy_enabled: false
219
+ token_rotation_enabled: false
220
+ ```
221
+
222
+ Slack verifies the Request URL when you save, and Capybara answers because the connection now
223
+ exists. Reinstall the app if Slack asks.
224
+
225
+ ::check capybara:webhook-public Webhook address is reachable from the internet
226
+ ::check capybara:webhook-received Slack has delivered a signed request
227
+ :::
228
+
229
+ ---
230
+
231
+ ## Sign in with Slack
232
+
233
+ The manifest's redirect URL `{{signInCallbackUrl}}` is for **Sign in with Slack**. It needs the
234
+ deployment's public URL; without it, delete the redirect URL from the manifest or ask your super
235
+ admin to set `http.publicUrl`.
236
+
237
+ ::check capybara:public-url The platform has a public URL
238
+
239
+ ## When the plugin changes this manifest
240
+
241
+ After a Slack plugin update that changes the manifest, Capybara shows a notice on this connection.
242
+ Open the app at <https://api.slack.com/apps>, go to **App Manifest**, paste the new manifest,
243
+ save, reinstall the app if Slack asks, then confirm here with **I have updated the Slack app**.
@@ -0,0 +1,237 @@
1
+ # 创建 Slack 应用
2
+
3
+ 这会把一个 Slack 工作区以机器人的形式接入 Capybara。成员可以直接私信机器人、在频道里 @ 它,
4
+ 并使用斜杠命令 `/new`、`/env` 和 `/capybara`。你需要有在该工作区创建应用的权限(工作区开启了
5
+ 「Only allow pre-approved apps」时,第 2 步之后需要工作区管理员批准该应用)。
6
+
7
+ ## 1. 用 manifest 创建应用
8
+
9
+ 打开 <https://api.slack.com/apps>,选择 **Create New App → From a manifest**,选中你的工作区,
10
+ 粘贴下面的 manifest。
11
+
12
+ ::: mode long_connection
13
+ Socket Mode 不需要公网地址:由 Slack 与 Capybara 之间保持一条长连接。这份 manifest 会登记插件需要的
14
+ 机器人权限、事件和斜杠命令。
15
+
16
+ ```yaml title="应用 manifest(Socket Mode)"
17
+ # Slack app manifest for the Capybara Slack plugin, Socket Mode (long connection).
18
+ # Reference: https://docs.slack.dev/reference/app-manifest (checked 2026-11-09).
19
+ display_information:
20
+ # Slack caps app names at 35 characters; shorten it in the app settings if it is longer.
21
+ name: "{{connectionName}}"
22
+ description: Chat with your organization's Capybara agents.
23
+ background_color: "#3d2f24"
24
+ features:
25
+ app_home:
26
+ home_tab_enabled: false
27
+ messages_tab_enabled: true
28
+ messages_tab_read_only_enabled: false
29
+ bot_user:
30
+ display_name: Capybara
31
+ always_online: true
32
+ slash_commands:
33
+ - command: /new
34
+ description: Start a new conversation (direct message)
35
+ should_escape: false
36
+ - command: /env
37
+ description: List or set your default environment (direct message)
38
+ usage_hint: "[name]"
39
+ should_escape: false
40
+ - command: /capybara
41
+ description: Run a skill
42
+ usage_hint: "<skill> [args]"
43
+ should_escape: false
44
+ oauth_config:
45
+ # Sign in with Slack (identity-source@1).
46
+ redirect_urls:
47
+ - "{{signInCallbackUrl}}"
48
+ scopes:
49
+ bot:
50
+ - chat:write # post and update replies and cards
51
+ - commands # slash commands /new, /env, /capybara
52
+ - im:write # conversations.open: tell the bot's own DM from other DMs
53
+ - im:history # message.im: direct messages to the bot
54
+ - app_mentions:read # app_mention: @capybara in channels
55
+ - channels:history # message.channels: thread replies in public channels
56
+ - groups:history # message.groups: thread replies in private channels
57
+ - users:read # users.info; team_join / user_change; users.list
58
+ - users:read.email # directory@1: email addresses in users.list
59
+ settings:
60
+ event_subscriptions:
61
+ bot_events:
62
+ - message.im
63
+ - app_mention
64
+ - message.channels
65
+ - message.groups
66
+ - team_join
67
+ - user_change
68
+ interactivity:
69
+ is_enabled: true
70
+ socket_mode_enabled: true
71
+ org_deploy_enabled: false
72
+ token_rotation_enabled: false
73
+ ```
74
+ :::
75
+
76
+ ::: mode webhook
77
+ Webhook 模式下,Slack 把事件、卡片点击和斜杠命令发到这个渠道连接的地址,而这个地址要等连接保存后
78
+ 才存在。先用这份基础 manifest:它只登记机器人和权限,不含任何地址。保存之后,第 5 步再补上地址。
79
+
80
+ ```yaml title="基础应用 manifest(Webhook)"
81
+ # Slack app manifest for the Capybara Slack plugin, webhook inbound mode, first step: no
82
+ # addresses yet. Step 5 replaces it with the full manifest once the connection is saved.
83
+ # Reference: https://docs.slack.dev/reference/app-manifest (checked 2026-11-09).
84
+ display_information:
85
+ # Slack caps app names at 35 characters; shorten it in the app settings if it is longer.
86
+ name: "{{connectionName}}"
87
+ description: Chat with your organization's Capybara agents.
88
+ background_color: "#3d2f24"
89
+ features:
90
+ app_home:
91
+ home_tab_enabled: false
92
+ messages_tab_enabled: true
93
+ messages_tab_read_only_enabled: false
94
+ bot_user:
95
+ display_name: Capybara
96
+ always_online: true
97
+ oauth_config:
98
+ # Sign in with Slack (identity-source@1).
99
+ redirect_urls:
100
+ - "{{signInCallbackUrl}}"
101
+ scopes:
102
+ bot:
103
+ - chat:write # post and update replies and cards
104
+ - commands # slash commands /new, /env, /capybara
105
+ - im:write # conversations.open: tell the bot's own DM from other DMs
106
+ - im:history # message.im: direct messages to the bot
107
+ - app_mentions:read # app_mention: @capybara in channels
108
+ - channels:history # message.channels: thread replies in public channels
109
+ - groups:history # message.groups: thread replies in private channels
110
+ - users:read # users.info; team_join / user_change; users.list
111
+ - users:read.email # directory@1: email addresses in users.list
112
+ settings:
113
+ socket_mode_enabled: false
114
+ org_deploy_enabled: false
115
+ token_rotation_enabled: false
116
+ ```
117
+ :::
118
+
119
+ ::: mode long_connection
120
+ ## 2. 创建应用级令牌
121
+
122
+ 在 **Basic Information → App-Level Tokens** 选择 **Generate Token and Scopes**,添加权限
123
+ `connections:write`,把 `xapp-…` 令牌填进下方的 **应用令牌**。
124
+
125
+ ::check app-token 应用令牌能建立 Socket Mode 连接
126
+ :::
127
+
128
+ ::: mode webhook
129
+ ## 2. 复制签名密钥
130
+
131
+ 把 **Basic Information → App Credentials → Signing Secret** 填进下方的 **签名密钥**。每个 webhook
132
+ 请求都用它校验;不填则所有请求都会被拒绝。
133
+ :::
134
+
135
+ ## 3. 安装应用并复制机器人令牌
136
+
137
+ 选择 **Install App → Install to Workspace**,把 **Bot User OAuth Token**(`xoxb-…`)填进下方的
138
+ **机器人令牌**。
139
+
140
+ ::check bot-token 机器人令牌可用
141
+ ::check bot-scopes 应用具备 manifest 中的全部权限
142
+
143
+ ## 4. 保存渠道
144
+
145
+ 填好本页其余字段并保存,保存时 Capybara 会校验机器人令牌。使用 Socket Mode 时到这里就完成了:机器人
146
+ 会自动连上,可以开始收消息。
147
+
148
+ ::: mode webhook
149
+ ## 5. 让 Slack 指向这个连接
150
+
151
+ 保存之后,下面的 manifest 会带上这个连接的地址 `{{webhookUrl}}`(保存前按原样显示)。在应用里打开
152
+ **App Manifest**,用这份 manifest 整体替换并保存。它会加上斜杠命令、事件订阅和交互,全部发往这个地址。
153
+
154
+ ```yaml title="应用 manifest(Webhook)"
155
+ # Slack app manifest for the Capybara Slack plugin, webhook inbound mode.
156
+ # Reference: https://docs.slack.dev/reference/app-manifest (checked 2026-11-09).
157
+ display_information:
158
+ # Slack caps app names at 35 characters; shorten it in the app settings if it is longer.
159
+ name: "{{connectionName}}"
160
+ description: Chat with your organization's Capybara agents.
161
+ background_color: "#3d2f24"
162
+ features:
163
+ app_home:
164
+ home_tab_enabled: false
165
+ messages_tab_enabled: true
166
+ messages_tab_read_only_enabled: false
167
+ bot_user:
168
+ display_name: Capybara
169
+ always_online: true
170
+ slash_commands:
171
+ - command: /new
172
+ url: "{{webhookUrl}}"
173
+ description: Start a new conversation (direct message)
174
+ should_escape: false
175
+ - command: /env
176
+ url: "{{webhookUrl}}"
177
+ description: List or set your default environment (direct message)
178
+ usage_hint: "[name]"
179
+ should_escape: false
180
+ - command: /capybara
181
+ url: "{{webhookUrl}}"
182
+ description: Run a skill
183
+ usage_hint: "<skill> [args]"
184
+ should_escape: false
185
+ oauth_config:
186
+ # Sign in with Slack (identity-source@1).
187
+ redirect_urls:
188
+ - "{{signInCallbackUrl}}"
189
+ scopes:
190
+ bot:
191
+ - chat:write # post and update replies and cards
192
+ - commands # slash commands /new, /env, /capybara
193
+ - im:write # conversations.open: tell the bot's own DM from other DMs
194
+ - im:history # message.im: direct messages to the bot
195
+ - app_mentions:read # app_mention: @capybara in channels
196
+ - channels:history # message.channels: thread replies in public channels
197
+ - groups:history # message.groups: thread replies in private channels
198
+ - users:read # users.info; team_join / user_change; users.list
199
+ - users:read.email # directory@1: email addresses in users.list
200
+ settings:
201
+ event_subscriptions:
202
+ request_url: "{{webhookUrl}}"
203
+ bot_events:
204
+ - message.im
205
+ - app_mention
206
+ - message.channels
207
+ - message.groups
208
+ - team_join
209
+ - user_change
210
+ interactivity:
211
+ is_enabled: true
212
+ request_url: "{{webhookUrl}}"
213
+ socket_mode_enabled: false
214
+ org_deploy_enabled: false
215
+ token_rotation_enabled: false
216
+ ```
217
+
218
+ 保存时 Slack 会校验 Request URL;连接已经存在,Capybara 会应答校验。Slack 要求时重新安装应用。
219
+
220
+ ::check capybara:webhook-public Webhook 地址可从公网访问
221
+ ::check capybara:webhook-received Slack 已送达一个签名有效的请求
222
+ :::
223
+
224
+ ---
225
+
226
+ ## Slack 登录
227
+
228
+ manifest 里的重定向地址 `{{signInCallbackUrl}}` 用于 **Sign in with Slack**(Slack 登录),需要部署
229
+ 设置公网地址;未设置时,请从 manifest 中删掉该重定向地址,或请超级管理员设置 `http.publicUrl`。
230
+
231
+ ::check capybara:public-url 平台已设置公网地址
232
+
233
+ ## 插件更新了 manifest 时
234
+
235
+ Slack 插件更新并改动了 manifest 后,Capybara 会在这个渠道连接上显示提示。在
236
+ <https://api.slack.com/apps> 打开该应用,进入 **App Manifest**,粘贴新的 manifest 并保存,Slack
237
+ 要求时重新安装应用,然后在这里点 **我已更新 Slack 应用** 确认。
@@ -0,0 +1,113 @@
1
+ # Set up the Slack connector
2
+
3
+ The Slack connector lets agents search, read and send Slack messages, canvases, lists and files
4
+ **as the person using them**, through Slack's MCP server. Each member connects their own Slack
5
+ account; there is no shared org token.
6
+
7
+ ::: audience admin
8
+ An org admin sets it up once: create an internal Slack app (a separate app from the bot), then
9
+ enter its client id and secret here. Members connect afterwards.
10
+
11
+ ## 1. Create the OAuth app
12
+
13
+ Open <https://api.slack.com/apps>, choose **Create New App → From a manifest** in the company
14
+ workspace and paste the manifest below. It turns on MCP and requests the user scopes the
15
+ {{templateName}} template asks for.
16
+
17
+ ```yaml title="App manifest (Slack connector)"
18
+ # Slack app manifest for the "{{templateName}}" connector template ({{pluginName}} {{pluginVersion}}).
19
+ # A separate internal app: user scopes only, MCP on, no bot, no Socket Mode.
20
+ # Reference: https://docs.slack.dev/reference/app-manifest and
21
+ # https://docs.slack.dev/ai/slack-mcp-server/ (checked 2026-11-08).
22
+ display_information:
23
+ name: "Capybara connector"
24
+ description: Lets Capybara agents use Slack as you, with your permission.
25
+ background_color: "#3d2f24"
26
+ oauth_config:
27
+ redirect_urls:
28
+ - "{{oauthCallbackUrl}}"
29
+ scopes:
30
+ user:
31
+ - search:read.public
32
+ - search:read.private
33
+ - search:read.mpim
34
+ - search:read.im
35
+ - search:read.files
36
+ - search:read.users
37
+ - channels:history
38
+ - groups:history
39
+ - mpim:history
40
+ - im:history
41
+ - channels:read
42
+ - groups:read
43
+ - mpim:read
44
+ - im:read
45
+ - channels:write
46
+ - groups:write
47
+ - mpim:write
48
+ - im:write
49
+ - chat:write
50
+ - canvases:read
51
+ - canvases:write
52
+ - lists:read
53
+ - lists:write
54
+ - files:read
55
+ - files:write
56
+ - reactions:read
57
+ - reactions:write
58
+ - emoji:read
59
+ - users:read
60
+ - users:read.email
61
+ settings:
62
+ is_mcp_enabled: true
63
+ org_deploy_enabled: false # true for an Enterprise Grid org-wide install
64
+ socket_mode_enabled: false
65
+ token_rotation_enabled: false
66
+ ```
67
+
68
+ ::check capybara:public-url The platform has a public URL
69
+
70
+ ## 2. Keep the app internal
71
+
72
+ - Leave **Manage Distribution** off. Slack's MCP server serves only internal apps and Marketplace
73
+ apps.
74
+ - Do **not** enable PKCE in the app settings: it turns the app into a public client for good.
75
+ Capybara stays a confidential client.
76
+ - Keep token rotation off (the manifest does); without it user tokens do not expire.
77
+ - Approve or install the app as your workspace requires (with "Only allow pre-approved apps", a
78
+ workspace admin approves it; on Enterprise Grid, an org admin).
79
+
80
+ ## 3. Enter the client
81
+
82
+ Copy **Basic Information → App Credentials → Client ID** and **Client Secret** into the fields
83
+ below. The secret is stored encrypted and reads back only as "set".
84
+
85
+ ::check capybara:oauth-client The client id and secret are entered
86
+ ::check capybara:oauth-token-endpoint Slack accepts the client id and secret
87
+ ::check capybara:connector-tools A member connected and the tool list was read
88
+
89
+ ### Reusing the bot app instead
90
+
91
+ You can add the user scopes, turn on MCP and add the redirect URL `{{oauthCallbackUrl}}` to the
92
+ bot's app instead, as long as token rotation stays off (rotation is app-wide and would expire the
93
+ bot's `xoxb` token). Slack prefix-matches redirect URLs, so one entry `{{publicUrl}}/api/v1/`
94
+ covers this callback and the Sign in with Slack callback `{{signInCallbackUrl}}`.
95
+
96
+ ## When the plugin changes this manifest
97
+
98
+ After an update that changes the scopes, Capybara shows a notice on the connector. Paste the new
99
+ manifest under **App Manifest**, save, and confirm here with **I have updated the Slack app**.
100
+ Members reconnect when Slack asks them to.
101
+ :::
102
+
103
+ ::: audience member
104
+ ## Connect your Slack account
105
+
106
+ Choose **Connect** and approve on Slack's consent screen. Agents then act in Slack as you, and
107
+ writes (sending, creating, reacting, uploading) ask you first unless your admin changed that.
108
+
109
+ **Disconnect** deletes the token in Capybara but does not revoke it at Slack: also remove the app
110
+ under your Slack profile's **Apps**, or ask a workspace admin.
111
+
112
+ ::check capybara:connector-connected Your Slack account is connected
113
+ :::
@@ -0,0 +1,107 @@
1
+ # 设置 Slack 连接器
2
+
3
+ Slack 连接器让智能体通过 Slack 的 MCP 服务器,**以使用者本人的身份**搜索、读取和发送 Slack 消息、
4
+ 画布、列表和文件。每个成员连接自己的 Slack 账号,组织没有共用的令牌。
5
+
6
+ ::: audience admin
7
+ 由组织管理员设置一次:创建一个内部 Slack 应用(与机器人应用分开),再把它的 Client ID 和
8
+ Client Secret 填到这里。之后成员各自连接。
9
+
10
+ ## 1. 创建 OAuth 应用
11
+
12
+ 打开 <https://api.slack.com/apps>,在公司工作区选择 **Create New App → From a manifest**,粘贴
13
+ 下面的 manifest。它会开启 MCP,并申请 {{templateName}} 模板需要的用户权限。
14
+
15
+ ```yaml title="应用 manifest(Slack 连接器)"
16
+ # Slack app manifest for the "{{templateName}}" connector template ({{pluginName}} {{pluginVersion}}).
17
+ # A separate internal app: user scopes only, MCP on, no bot, no Socket Mode.
18
+ # Reference: https://docs.slack.dev/reference/app-manifest and
19
+ # https://docs.slack.dev/ai/slack-mcp-server/ (checked 2026-11-08).
20
+ display_information:
21
+ name: "Capybara connector"
22
+ description: Lets Capybara agents use Slack as you, with your permission.
23
+ background_color: "#3d2f24"
24
+ oauth_config:
25
+ redirect_urls:
26
+ - "{{oauthCallbackUrl}}"
27
+ scopes:
28
+ user:
29
+ - search:read.public
30
+ - search:read.private
31
+ - search:read.mpim
32
+ - search:read.im
33
+ - search:read.files
34
+ - search:read.users
35
+ - channels:history
36
+ - groups:history
37
+ - mpim:history
38
+ - im:history
39
+ - channels:read
40
+ - groups:read
41
+ - mpim:read
42
+ - im:read
43
+ - channels:write
44
+ - groups:write
45
+ - mpim:write
46
+ - im:write
47
+ - chat:write
48
+ - canvases:read
49
+ - canvases:write
50
+ - lists:read
51
+ - lists:write
52
+ - files:read
53
+ - files:write
54
+ - reactions:read
55
+ - reactions:write
56
+ - emoji:read
57
+ - users:read
58
+ - users:read.email
59
+ settings:
60
+ is_mcp_enabled: true
61
+ org_deploy_enabled: false # true for an Enterprise Grid org-wide install
62
+ socket_mode_enabled: false
63
+ token_rotation_enabled: false
64
+ ```
65
+
66
+ ::check capybara:public-url 平台已设置公网地址
67
+
68
+ ## 2. 保持应用为内部应用
69
+
70
+ - 不要开启 **Manage Distribution**。Slack 的 MCP 服务器只服务内部应用和 Marketplace 应用。
71
+ - **不要**在应用设置里开启 PKCE:开启后应用会永久变成公开客户端。Capybara 始终是机密客户端。
72
+ - 保持令牌轮换关闭(manifest 已关闭);不轮换时用户令牌不会过期。
73
+ - 按工作区的要求批准或安装应用(开启了「Only allow pre-approved apps」时由工作区管理员批准;
74
+ Enterprise Grid 上由组织管理员批准)。
75
+
76
+ ## 3. 填写客户端
77
+
78
+ 把 **Basic Information → App Credentials → Client ID** 和 **Client Secret** 填进下方的字段。
79
+ 密钥加密存储,读回时只显示「已设置」。
80
+
81
+ ::check capybara:oauth-client 已填写 Client ID 和 Client Secret
82
+ ::check capybara:oauth-token-endpoint Slack 接受该 Client ID 和 Client Secret
83
+ ::check capybara:connector-tools 已有成员连接并读取到工具列表
84
+
85
+ ### 改用机器人应用
86
+
87
+ 也可以把这些用户权限、MCP 开关和重定向地址 `{{oauthCallbackUrl}}` 加到机器人应用上,前提是令牌
88
+ 轮换保持关闭(轮换对整个应用生效,会让机器人的 `xoxb` 令牌过期)。Slack 按前缀匹配重定向地址,
89
+ 所以一条 `{{publicUrl}}/api/v1/` 就能同时覆盖这个回调和 Slack 登录的回调 `{{signInCallbackUrl}}`。
90
+
91
+ ## 插件更新了 manifest 时
92
+
93
+ 插件更新并改动了权限后,Capybara 会在连接器上显示提示。在 **App Manifest** 粘贴新的 manifest
94
+ 并保存,然后在这里点 **我已更新 Slack 应用** 确认。Slack 要求时,成员重新连接。
95
+ :::
96
+
97
+ ::: audience member
98
+ ## 连接你的 Slack 账号
99
+
100
+ 点 **连接**,在 Slack 的授权页面上同意。之后智能体会以你的身份在 Slack 中操作;写操作(发送、
101
+ 创建、回应、上传)会先征求你的同意,除非管理员改了设置。
102
+
103
+ **断开连接** 会删除 Capybara 中的令牌,但不会在 Slack 端撤销它:请同时在 Slack 个人资料的
104
+ **Apps** 中移除该应用,或请工作区管理员处理。
105
+
106
+ ::check capybara:connector-connected 你的 Slack 账号已连接
107
+ :::