@capybara-hq/plugin-slack 0.1.0-rc.3 → 0.1.0-rc.5
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.
- package/.capybara-plugin/plugin.json +24 -2
- package/README.md +112 -36
- package/connectors/slack.json +85 -0
- package/dist/index.mjs +391 -37
- package/guides/slack-app.md +186 -0
- package/guides/slack-app.zh.md +181 -0
- package/guides/slack-connector.md +113 -0
- package/guides/slack-connector.zh.md +107 -0
- package/package.json +1 -1
- package/app-manifest.yaml +0 -64
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"name": "slack",
|
|
4
|
-
"version": "0.1.0-rc.
|
|
4
|
+
"version": "0.1.0-rc.5",
|
|
5
5
|
"publisher": "Capybara",
|
|
6
6
|
"description": "Slack (channel@1 bot over Socket Mode with Block Kit cards, identity-source@1 Sign in with Slack, directory@1)",
|
|
7
7
|
"displayName": {
|
|
@@ -10,11 +10,28 @@
|
|
|
10
10
|
},
|
|
11
11
|
"icon": "./icon.svg",
|
|
12
12
|
"homepage": "https://github.com/capybara-hq/plugins/tree/main/plugins/slack#readme",
|
|
13
|
+
"dependencies": [
|
|
14
|
+
{
|
|
15
|
+
"name": "connector-mcp",
|
|
16
|
+
"version": "^0.1.0-rc.1"
|
|
17
|
+
}
|
|
18
|
+
],
|
|
19
|
+
"setupGuides": [
|
|
20
|
+
{
|
|
21
|
+
"id": "slack-app",
|
|
22
|
+
"place": "channel-connection"
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
"id": "slack-connector",
|
|
26
|
+
"place": "connector-template",
|
|
27
|
+
"template": "slack"
|
|
28
|
+
}
|
|
29
|
+
],
|
|
13
30
|
"extension": {
|
|
14
31
|
"entry": "./dist/index.mjs",
|
|
15
32
|
"manifest": {
|
|
16
33
|
"name": "slack",
|
|
17
|
-
"version": "0.1.0-rc.
|
|
34
|
+
"version": "0.1.0-rc.5",
|
|
18
35
|
"sdk": "^0.1.0-rc.0",
|
|
19
36
|
"provides": [
|
|
20
37
|
"channel@1",
|
|
@@ -27,6 +44,11 @@
|
|
|
27
44
|
"network": [
|
|
28
45
|
"slack.com",
|
|
29
46
|
"wss-primary.slack.com"
|
|
47
|
+
],
|
|
48
|
+
"setupChecks": [
|
|
49
|
+
"bot-token",
|
|
50
|
+
"bot-scopes",
|
|
51
|
+
"app-token"
|
|
30
52
|
]
|
|
31
53
|
},
|
|
32
54
|
"config": {
|
package/README.md
CHANGED
|
@@ -1,12 +1,15 @@
|
|
|
1
1
|
# @capybara-hq/plugin-slack
|
|
2
2
|
|
|
3
|
-
The official Slack plugin. It provides three capabilities:
|
|
3
|
+
The official Slack plugin. It provides three capabilities and a connector template:
|
|
4
4
|
|
|
5
5
|
- `channel@1` (bot): receives events over [Socket Mode](https://docs.slack.dev/apis/events-api/using-socket-mode)
|
|
6
6
|
(no public callback URL needed), sends messages through the Web API, and renders approval / question /
|
|
7
7
|
connection / binding cards as Block Kit.
|
|
8
8
|
- `identity-source@1` (Sign in with Slack, OpenID Connect): sign in to Capybara with a Slack account.
|
|
9
9
|
- `directory@1` (directory sync): syncs Slack workspace members into org members.
|
|
10
|
+
- The connector template `slack` ([Slack connector](#slack-connector-slacks-mcp-server)): agents search,
|
|
11
|
+
read and send in Slack **as the person talking to them**, through Slack's MCP server and each member's own
|
|
12
|
+
OAuth authorization. Switched off by default.
|
|
10
13
|
|
|
11
14
|
All three use the same identity key: `identities.source` = `slack:<team id>`, `external_id` = the Slack user id (`U…`).
|
|
12
15
|
When the same person appears through sign-in, a DM to the bot and directory sync, it maps to one identity row and one account.
|
|
@@ -15,31 +18,39 @@ The Slack docs cited here were consulted on 2026-10-20.
|
|
|
15
18
|
|
|
16
19
|
## Create the Slack app
|
|
17
20
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
21
|
+
The steps live in the product: the plugin ships the setup guide `slack-app`
|
|
22
|
+
([`guides/slack-app.md`](./guides/slack-app.md), Chinese
|
|
23
|
+
[`guides/slack-app.zh.md`](./guides/slack-app.zh.md)). When an org admin creates a Slack channel
|
|
24
|
+
connection (Channels → New channel) or opens one, the web app shows the guide for the connection's
|
|
25
|
+
inbound mode (Socket Mode or webhook) with the app manifest filled in for that connection (its name,
|
|
26
|
+
the Sign in with Slack callback and, in webhook mode, its webhook URL) and a copy button. When a
|
|
27
|
+
plugin upgrade changes the manifest, the channel page says so and asks you to update the Slack app.
|
|
28
|
+
To preview the guide outside Capybara, run
|
|
29
|
+
`capybara-plugin guide slack-app --mode long_connection` (or `--mode webhook`, `--locale zh`) in
|
|
30
|
+
this repository.
|
|
31
|
+
|
|
32
|
+
The guide carries live checks, run when the page is viewed (cached for five minutes) or on
|
|
33
|
+
**Check again**:
|
|
34
|
+
|
|
35
|
+
| Check | What it does |
|
|
36
|
+
|---|---|
|
|
37
|
+
| `bot-token` | `auth.test` with the connection's bot token: refused (`invalid_auth`, `token_revoked`, …), wrong token type or an org-wide install is failing with the fix |
|
|
38
|
+
| `bot-scopes` | Compares the scopes Slack reports for the bot token (`x-oauth-scopes`) with the manifest's bot scopes and names the missing ones |
|
|
39
|
+
| `app-token` | `apps.connections.open` with the app-level token (Socket Mode only; the socket is never opened) |
|
|
40
|
+
|
|
41
|
+
Each check makes one read-only call, passes the kernel's abort signal on and never retries; rate
|
|
42
|
+
limits and Slack outages answer "unknown", never "failing". The guide also uses the kernel checks
|
|
43
|
+
`capybara:public-url`, `capybara:webhook-public` and `capybara:webhook-received`.
|
|
44
|
+
|
|
45
|
+
Notes for operators:
|
|
46
|
+
|
|
47
|
+
- The org must enable the `slack` plugin before it can create a connection (its org-level fields are
|
|
48
|
+
optional and only for [directory sync](#directory-directory1)). The tokens are stored in the
|
|
49
|
+
secret store, and the API only returns "set".
|
|
50
|
+
- The app's name in the manifest is the connection's name; Slack caps it at 35 characters, so shorten it in
|
|
51
|
+
the app settings if Slack refuses it (the bot user's name stays `capybara`).
|
|
52
|
+
- In Slack, DM the bot, or add the bot to a channel and @-mention it. The first conversation gets a
|
|
53
|
+
binding card; click the button to confirm the binding on the web page.
|
|
43
54
|
|
|
44
55
|
Note: apps that use Socket Mode cannot currently be listed in the public Slack Marketplace, and one app can hold at most 10 concurrent
|
|
45
56
|
Socket Mode connections ([Using Socket Mode](https://docs.slack.dev/apis/events-api/using-socket-mode)). At any moment Capybara has only one
|
|
@@ -59,12 +70,14 @@ connection → Overview → Inbound mode); the connection page then shows its we
|
|
|
59
70
|
1. Copy **Basic Information → App Credentials → Signing Secret** into the connection's
|
|
60
71
|
`signingSecret`. Every request is verified with it (HMAC-SHA256 over `v0:<timestamp>:<body>`)
|
|
61
72
|
and must be at most 5 minutes old; without it every webhook request is refused.
|
|
62
|
-
2.
|
|
63
|
-
Subscriptions → Request URL** (Slack verifies it with a `url_verification`
|
|
64
|
-
plugin answers)
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
73
|
+
2. The webhook manifest of the setup guide turns **Socket Mode** off and uses the connection's webhook
|
|
74
|
+
URL as the **Event Subscriptions → Request URL** (Slack verifies it with a `url_verification`
|
|
75
|
+
challenge, which the plugin answers), the **Interactivity & Shortcuts → Request URL** (card
|
|
76
|
+
buttons) and each slash command's **Request URL**. For an existing app, paste it under **App
|
|
77
|
+
Manifest**, or set the four URLs by hand. The plugin tells a slash command from an event by its
|
|
78
|
+
form body and answers it like Socket Mode does.
|
|
79
|
+
3. The webhook URL exists only once the connection is saved, so the guide shows it after saving;
|
|
80
|
+
create the connection first, then let Slack verify the URL.
|
|
68
81
|
4. `appToken` is optional in webhook mode: only Socket Mode uses it.
|
|
69
82
|
|
|
70
83
|
Both modes parse events the same way (same message and card-click ids), so the kernel's dedupe
|
|
@@ -74,7 +87,7 @@ still drops a redelivery that arrives across a mode switch.
|
|
|
74
87
|
|
|
75
88
|
[Sign in with Slack](https://docs.slack.dev/authentication/sign-in-with-slack/) is based on OpenID Connect.
|
|
76
89
|
|
|
77
|
-
1.
|
|
90
|
+
1. The setup guide's manifest already lists the callback; otherwise, in the app settings, add
|
|
78
91
|
`<http.publicUrl>/api/v1/auth/sso/slack/callback` under **OAuth & Permissions → Redirect URLs** (for example `https://capybara.example.com/api/v1/auth/sso/slack/callback`;
|
|
79
92
|
the `redirect_uri` the kernel sends must equal it or be a sub-path of it).
|
|
80
93
|
2. The login flow requests the scopes `openid`, `email` and `profile` in the authorization URL (`openid` is required; `email` gives the email and
|
|
@@ -122,6 +135,62 @@ channel connection uses, but the config is stored separately and goes through th
|
|
|
122
135
|
- When `teamId` / `botToken` are not filled in (the org only uses the bot), the plugin's `configured()` returns false: the kernel does not scan or sync, and records no audit
|
|
123
136
|
or warning; a manual sync returns 409 `directory.not_configured`. It is not treated as an empty directory.
|
|
124
137
|
|
|
138
|
+
## Slack connector (Slack's MCP server)
|
|
139
|
+
|
|
140
|
+
The template [`connectors/slack.json`](./connectors/slack.json) connects Slack's official MCP server
|
|
141
|
+
(`https://mcp.slack.com/mcp`, [Slack MCP server](https://docs.slack.dev/ai/slack-mcp-server/)) through the
|
|
142
|
+
`connector-mcp` plugin (a dependency in `plugin.json`, preinstalled with Capybara). Each member authorizes
|
|
143
|
+
their own Slack account, so an agent sees and does exactly what that person may in Slack, and every call runs
|
|
144
|
+
on the caller's own user token; there is no shared org token. Design and decisions:
|
|
145
|
+
[docs/superpowers/specs/2026-11-08-slack-connector-design.md](https://github.com/capybara-hq/plugins/blob/main/docs/superpowers/specs/2026-11-08-slack-connector-design.md).
|
|
146
|
+
|
|
147
|
+
- **Off by default** (`defaultEnabled: false`): an org that turns on the `slack` plugin for the bot does not
|
|
148
|
+
see the connector until an org admin switches the template on and enters the OAuth client.
|
|
149
|
+
- **Auth**: OAuth authorization code, personal credentials, MCP discovery (Slack's metadata points at
|
|
150
|
+
`https://slack.com/oauth/v2_user/authorize` and `oauth.v2.user.access`), a manually entered client (Slack
|
|
151
|
+
offers no dynamic client registration), `client_secret_post`, and 30 explicit user scopes (the full set
|
|
152
|
+
Slack's server supports; a scope Slack adds later needs a template update).
|
|
153
|
+
- **Tools**: reads are allowed; every write (send, schedule, draft, create, update, react, upload) and
|
|
154
|
+
`slack_search_public_and_private` (reaches DMs and private channels) ask the person first. Org admins and
|
|
155
|
+
agents change the policies on the tools page; tools Slack adds later default by their annotations (`ask`
|
|
156
|
+
without `readOnlyHint`).
|
|
157
|
+
|
|
158
|
+
### Set it up
|
|
159
|
+
|
|
160
|
+
The connector template carries the setup guide `slack-connector`
|
|
161
|
+
([`guides/slack-connector.md`](./guides/slack-connector.md), Chinese
|
|
162
|
+
[`guides/slack-connector.zh.md`](./guides/slack-connector.zh.md)), shown on the template's pages:
|
|
163
|
+
org admins see how to create the internal Slack app (the manifest with this deployment's OAuth
|
|
164
|
+
callback filled in), keep it internal and enter its client id and secret; members see how to connect
|
|
165
|
+
their own Slack account. Preview it with
|
|
166
|
+
`capybara-plugin guide slack-connector --audience admin` (or `--audience member`). Its rows are
|
|
167
|
+
kernel checks: `capybara:public-url`, `capybara:oauth-client`, `capybara:oauth-token-endpoint`
|
|
168
|
+
(the stored client against Slack's token endpoint; the secret stays in the kernel),
|
|
169
|
+
`capybara:connector-tools` and, for members, `capybara:connector-connected`.
|
|
170
|
+
|
|
171
|
+
Notes for operators:
|
|
172
|
+
|
|
173
|
+
- The deployment must set `http.publicUrl`: the OAuth callback is
|
|
174
|
+
`<http.publicUrl>/api/v1/oauth/callback`.
|
|
175
|
+
- Each org enters its own client (the same Slack app may serve several orgs); rotate the secret later
|
|
176
|
+
through the connector's org credentials.
|
|
177
|
+
- Capybara stays a confidential client: it still sends a PKCE challenge (Slack's metadata advertises
|
|
178
|
+
it), but PKCE must not be enabled in the app settings.
|
|
179
|
+
|
|
180
|
+
### Decided risks
|
|
181
|
+
|
|
182
|
+
- **Slack data in conversations**: tool results stay in the conversation event log and archives like any
|
|
183
|
+
other connector's, although Slack's Real-time Search terms say retrieved data must not be stored. The app
|
|
184
|
+
is the customer's own internal app under its own Slack agreement.
|
|
185
|
+
- **Quoting private Slack content into shared threads**: in a Slack channel thread (through the bot), a tool
|
|
186
|
+
call runs on the acting member's token and the reply goes to a channel others read. There is no special
|
|
187
|
+
rule for this; it relies on the tool policies (the `ask` default of `slack_search_public_and_private`
|
|
188
|
+
plus whatever the org or agent sets).
|
|
189
|
+
- **No identity check**: a member may connect a different Slack account than the one bound to their
|
|
190
|
+
Capybara account; the token still reaches only their own calls.
|
|
191
|
+
- **No revoke on disconnect** and **one client per org** (no platform-level client) in this release.
|
|
192
|
+
- **Scopes**: the full set only; there is no reduced variant (for example without DM scopes).
|
|
193
|
+
|
|
125
194
|
## Commands
|
|
126
195
|
|
|
127
196
|
The kernel parses commands from the message text: `/new` (DM: start a new conversation), `/env [name]`
|
|
@@ -163,7 +232,7 @@ one in Slack's menu.
|
|
|
163
232
|
`trigger_id`) reuses the cached echo, so it is posted once.
|
|
164
233
|
- The fixed hints are bilingual (English · 中文): the org's IM language is not known on inbound.
|
|
165
234
|
|
|
166
|
-
Existing apps: re-paste the manifest (**App Manifest** in the app settings) or add the three commands
|
|
235
|
+
Existing apps: re-paste the manifest from the setup guide (**App Manifest** in the app settings) or add the three commands
|
|
167
236
|
by hand under **Slash Commands**, add the bot scopes `commands` and `im:write`, then **reinstall the
|
|
168
237
|
app** to the workspace (Slack asks for it because the scopes changed). The bot token stays the same.
|
|
169
238
|
|
|
@@ -188,8 +257,15 @@ app** to the workspace (Slack asks for it because the scopes changed). The bot t
|
|
|
188
257
|
- **Reconnect**: managed by the plugin (SDK auto-reconnect is turned off). When Slack recycles a connection normally it reconnects immediately; consecutive short-lived (under 10 seconds) connections back off exponentially
|
|
189
258
|
(with jitter), and after 5 in a row, or on receiving `link_disabled`, it reports an error; the kernel records `last_error` and backs off.
|
|
190
259
|
- **Idempotency**: `chat.postMessage` has no idempotency parameter, so `idempotencyKey` is ignored.
|
|
191
|
-
- **Profile
|
|
192
|
-
|
|
260
|
+
- **Profile, time zone and language**: every speaker is looked up with
|
|
261
|
+
[`users.info`](https://docs.slack.dev/reference/methods/users.info) `include_locale=true` (Tier 4, `users:read`):
|
|
262
|
+
`user.tz` becomes `sender.timeZone` and `user.locale` becomes `sender.locale`, passed as is (the kernel
|
|
263
|
+
ignores an unknown zone and normalizes the language; both win over the person's Capybara settings for the
|
|
264
|
+
run's date, zone and language). The display name and avatar come from the event's `user_profile` when it
|
|
265
|
+
has one, else from the same lookup. The result is cached in the plugin kv per team and user for 10 minutes
|
|
266
|
+
(shared by every replica; nothing in process memory; an unknown user is cached as empty). The lookup has a
|
|
267
|
+
1.5 second timeout so the 3 second ack deadline holds; on any failure the fields are left out and nothing
|
|
268
|
+
is cached.
|
|
193
269
|
- **Permission manifest**: `network: ["slack.com", "wss-primary.slack.com"]`, shown only and not enforced; login (OIDC) and the directory also use
|
|
194
270
|
`slack.com`. The WSS host for Socket Mode is
|
|
195
271
|
assigned by Slack and is not fixed (for example `wss-primary.slack.com`, `wss-backup.slack.com`, `wss-111.slack.com`); the manifest's domain
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
{
|
|
2
|
+
"displayName": {
|
|
3
|
+
"zh": "Slack",
|
|
4
|
+
"en": "Slack"
|
|
5
|
+
},
|
|
6
|
+
"description": "Search, read and send Slack messages, canvases, lists and files as the connected person, through Slack's MCP server. Each member connects their own Slack account; an org admin enters the OAuth client of the company's internal Slack app.",
|
|
7
|
+
"icon": "./icon.svg",
|
|
8
|
+
"defaultEnabled": false,
|
|
9
|
+
"template": {
|
|
10
|
+
"plugin": "connector-mcp",
|
|
11
|
+
"pluginVersion": "^0.1.0-rc.1",
|
|
12
|
+
"connector": "mcp",
|
|
13
|
+
"endpoint": {
|
|
14
|
+
"url": "https://mcp.slack.com/mcp"
|
|
15
|
+
},
|
|
16
|
+
"auth": {
|
|
17
|
+
"type": "oauth_code",
|
|
18
|
+
"ownership": "personal",
|
|
19
|
+
"discovery": "mcp",
|
|
20
|
+
"client": "manual",
|
|
21
|
+
"tokenAuthMethod": "client_secret_post",
|
|
22
|
+
"scopes": [
|
|
23
|
+
"search:read.public",
|
|
24
|
+
"search:read.private",
|
|
25
|
+
"search:read.mpim",
|
|
26
|
+
"search:read.im",
|
|
27
|
+
"search:read.files",
|
|
28
|
+
"search:read.users",
|
|
29
|
+
"channels:history",
|
|
30
|
+
"groups:history",
|
|
31
|
+
"mpim:history",
|
|
32
|
+
"im:history",
|
|
33
|
+
"channels:read",
|
|
34
|
+
"groups:read",
|
|
35
|
+
"mpim:read",
|
|
36
|
+
"im:read",
|
|
37
|
+
"channels:write",
|
|
38
|
+
"groups:write",
|
|
39
|
+
"mpim:write",
|
|
40
|
+
"im:write",
|
|
41
|
+
"chat:write",
|
|
42
|
+
"canvases:read",
|
|
43
|
+
"canvases:write",
|
|
44
|
+
"lists:read",
|
|
45
|
+
"lists:write",
|
|
46
|
+
"files:read",
|
|
47
|
+
"files:write",
|
|
48
|
+
"reactions:read",
|
|
49
|
+
"reactions:write",
|
|
50
|
+
"emoji:read",
|
|
51
|
+
"users:read",
|
|
52
|
+
"users:read.email"
|
|
53
|
+
]
|
|
54
|
+
},
|
|
55
|
+
"defaultToolPolicies": {
|
|
56
|
+
"slack_search_public": "allow",
|
|
57
|
+
"slack_search_channels": "allow",
|
|
58
|
+
"slack_search_users": "allow",
|
|
59
|
+
"slack_search_emojis": "allow",
|
|
60
|
+
"slack_read_channel": "allow",
|
|
61
|
+
"slack_read_thread": "allow",
|
|
62
|
+
"slack_read_canvas": "allow",
|
|
63
|
+
"slack_read_file": "allow",
|
|
64
|
+
"slack_read_list": "allow",
|
|
65
|
+
"slack_read_user_profile": "allow",
|
|
66
|
+
"slack_list_user_channels": "allow",
|
|
67
|
+
"slack_list_channel_members": "allow",
|
|
68
|
+
"slack_get_reactions": "allow",
|
|
69
|
+
"slack_search_public_and_private": "ask",
|
|
70
|
+
"slack_send_message": "ask",
|
|
71
|
+
"slack_schedule_message": "ask",
|
|
72
|
+
"slack_send_message_draft": "ask",
|
|
73
|
+
"slack_create_conversation": "ask",
|
|
74
|
+
"slack_add_reaction": "ask",
|
|
75
|
+
"slack_create_canvas": "ask",
|
|
76
|
+
"slack_update_canvas": "ask",
|
|
77
|
+
"slack_create_list": "ask",
|
|
78
|
+
"slack_add_list_record": "ask",
|
|
79
|
+
"slack_update_list": "ask",
|
|
80
|
+
"slack_update_list_record": "ask",
|
|
81
|
+
"slack_get_file_upload_url": "ask",
|
|
82
|
+
"slack_complete_file_upload": "ask"
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|