# Slack MCP Server

自前実装の Slack MCP サーバー。User OAuth Token (xoxp-) を使い、自分名義でメッセージ送信・閲覧が可能。

依存: `@modelcontextprotocol/sdk` のみ（サードパーティ Slack ライブラリなし）。

## 機能

| ツール | 説明 |
|--------|------|
| `slack_list_channels` | チャンネル一覧（public/private/DM/グループDM） |
| `slack_get_channel_history` | チャンネル履歴取得（チャンネル名指定可、スレッド自動展開） |
| `slack_get_channel_members` | チャンネルメンバー一覧（ユーザー名・メール・組織付き） |
| `slack_get_thread` | スレッド返信取得 |
| `slack_get_pins` | ピン留めメッセージ一覧（スレッド展開付き） |
| `slack_post_message` | メッセージ投稿（自分名義、チャンネル名指定可、スレッド返信対応） |
| `slack_schedule_message` | 予約投稿（指定時刻に自動投稿） |
| `slack_update_message` | 投稿済みメッセージの編集 |
| `slack_delete_message` | 投稿済みメッセージの削除 |
| `slack_add_reaction` | リアクション追加 |
| `slack_search_messages` | メッセージ検索（Slack検索構文対応） |
| `slack_send_dm` | DM送信（ユーザー名指定可） |
| `slack_add_reminder` | リマインダー設定 |
| `slack_list_reminders` | リマインダー一覧 |
| `slack_get_presence` | ユーザーのオンライン状態確認 |
| `slack_set_topic` | チャンネルトピック更新 |
| `slack_get_bookmarks` | チャンネルのブックマーク一覧 |
| `slack_list_emoji` | カスタム絵文字一覧 |
| `slack_set_status` | 自分のSlackステータス変更 |
| `slack_list_users` | ワークスペース全ユーザー一覧 |
| `slack_get_user_info` | ユーザープロフィール詳細 |

### 特徴

- **チャンネル名で指定可能**: IDを調べる必要なし（`#general`、`dev_channel` 等）
- **ユーザー名自動解決**: メッセージ中の `<@U123>` や投稿者IDを表示名に変換
- **スレッド自動展開**: 返信を全件取得してインライン表示
- **メッセージリンク付き**: 各メッセージに Slack URL を付与

## セットアップ

### 1. Slack App 作成（一度だけ）

1. https://api.slack.com/apps にアクセスし「Create New App」をクリック
2. 「From an app manifest」を選択
3. ワークスペースを選択（例: gochipon）
4. 以下の JSON マニフェストを貼り付けて作成:

```json
{
  "display_information": {
    "name": "kiro-mcp"
  },
  "oauth_config": {
    "redirect_urls": [
      "http://localhost:3000/callback"
    ],
    "scopes": {
      "user": [
        "bookmarks:read",
        "channels:history",
        "channels:read",
        "channels:write",
        "chat:write",
        "dnd:read",
        "emoji:read",
        "files:read",
        "groups:history",
        "groups:read",
        "groups:write",
        "identify",
        "im:history",
        "im:read",
        "im:write",
        "links:read",
        "mpim:history",
        "mpim:read",
        "mpim:write",
        "pins:read",
        "reactions:read",
        "reactions:write",
        "reminders:read",
        "reminders:write",
        "search:read",
        "team:read",
        "usergroups:read",
        "users:read",
        "users:read.email",
        "users.profile:read",
        "users.profile:write"
      ]
    }
  },
  "settings": {
    "org_deploy_enabled": false,
    "socket_mode_enabled": false,
    "token_rotation_enabled": false
  }
}
```

5. 作成後、**Basic Information** ページで **Client ID** と **Client Secret** を確認

> **注意**: マニフェスト方式で作成すれば、スコープと Redirect URL が一発で設定されるため、手動で個別追加する必要はありません。

### 2. インストール

```bash
git clone <this-repo>
cd slack-mcp
npm install
```

`.env.example` を編集（Client ID と Client Secret を記入）:
```
SLACK_CLIENT_ID=（Basic Information の Client ID）
SLACK_CLIENT_SECRET=（Basic Information の Client Secret）
```

> **注意**: `.env` ファイルは初回起動時に `.env.example` から自動生成されます。`cp` コマンドは不要です。

### 3. MCP クライアント設定

#### Kiro

`~/.kiro/settings/mcp.json` の `mcpServers` に追加:

```json
"slack": {
  "command": "/opt/homebrew/bin/node",
  "args": ["/path/to/slack-mcp/server.js"],
  "disabled": false
}
```

#### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "slack": {
      "command": "node",
      "args": ["/path/to/slack-mcp/server.js"]
    }
  }
}
```

### 4. 初回接続時の認証

MCP クライアントから接続すると:
- `.env` にトークンがあれば → そのまま使える
- `.env` にトークンがなければ → **自動でブラウザが開き OAuth 認証画面が表示される**
- ブラウザで「許可」を押せばトークンが `.env` に保存され、以降は自動接続

> `npm run auth` を別途実行する必要はありません（初回接続時に自動実行されます）。
> 手動で再認証したい場合のみ `npm run auth` を使ってください。

### 5. Kiro ステアリング（推奨）

`.kiro/steering/slack-mcp-usage.md` をプロジェクトまたはグローバルに配置すると、AI が Slack データをどう要約・表示するかのルールが適用されます。

## トラブルシューティング

| 症状 | 対処 |
|------|------|
| `token_revoked` | トークン失効。`npm run auth` を再実行 |
| `missing_scope` | api.slack.com で User Token Scopes を追加 → `npm run auth` で再取得 |
| `channel_not_found` | チャンネルIDが正しいか確認。プライベートchは `groups:read` scope が必要 |
| `not_in_channel` | User Token ならアクセス可能なはず。チャンネルに参加しているか確認 |
| `spawn node ENOENT` | node のフルパスを指定する（例: `/opt/homebrew/bin/node`） |

## セキュリティ

- `.env` は `.gitignore` 済み（リポジトリにコミットされない）
- User Token は自分のアカウント権限で動作する
- Token の有効期間: 明示的に revoke するまで有効（期限なし）
- Slack App のワークスペースインストールには管理者承認が不要（User Token の OAuth フロー）

## ファイル構成

```
slack-mcp/
├── .env.example      ← コピーして Client ID/Secret を記入
├── .env              ← Token 保存先（gitignore済み）
├── .gitignore
├── .kiro/
│   └── steering/
│       └── slack-mcp-usage.md  ← AI表示ルール（ステアリング）
├── oauth.js          ← トークン取得（一度だけ実行）
├── server.js         ← MCP サーバー本体
├── package.json
└── README.md
```