# Slack検索MCPサーバー仕様書
## 概要
このシステムは、LLMからのSlack検索クエリを受け取り、Slack検索APIを呼び出して結果を返すMCPサーバーです。
LLMが自然言語の問い合わせをSlack検索クエリに変換し、このMCPサーバーが実際のAPI呼び出しを担当します。
## システム構成
```mermaid
sequenceDiagram
participant User
participant LLM
participant MCPサーバ
participant SlackAPI
User->>LLM: 曖昧な問い合わせ
LLM->>LLM: クエリ生成・変換
LLM->>MCPサーバ: Slack検索クエリ
MCPサーバ->>SlackAPI: search.messages呼び出し
SlackAPI->>MCPサーバ: 検索結果
MCPサーバ->>LLM: 生の検索結果
LLM->>LLM: 結果解析・要約
LLM->>User: 要約済みレスポンス
Note over LLM,MCPサーバ: 必要に応じて再検索・ページング
LLM->>MCPサーバ: 別クエリまたはcursor指定
MCPサーバ->>SlackAPI: 追加検索
SlackAPI->>MCPサーバ: 追加結果
MCPサーバ->>LLM: 追加検索結果
```
## Slack検索API仕様
### エンドポイント
- **URL**: `https://slack.com/api/search.messages`
- **メソッド**: `GET`
- **認証**: `search:read`スコープが必要
### 主要パラメータ
| パラメータ名 | 必須 | 型 | 説明 | デフォルト値 |
|---|---|---|---|---|
| `token` | 必須 | string | 認証トークン | - |
| `query` | 必須 | string | 検索クエリ | - |
| `count` | 任意 | integer | 1ページあたりの取得件数 | 20 |
| `cursor` | 任意 | string | ページネーション用カーソル | - |
| `highlight` | 任意 | boolean | ヒット部分のマークアップ | false |
| `page` | 任意 | integer | ページ番号 | 1 |
| `sort` | 任意 | string | 並び順（score/timestamp） | score |
| `sort_dir` | 任意 | string | 並び順方向（asc/desc） | desc |
| `team_id` | 任意 | string | 検索対象のチームID | - |
### 検索クエリの修飾子
- `in:channel_name` - 特定チャンネル内で検索
- `from:@user` - 特定ユーザーのメッセージを検索
- `before:YYYY-MM-DD` - 指定日以前のメッセージ
- `after:YYYY-MM-DD` - 指定日以降のメッセージ
## MCPサーバー設計
### 責務分担
#### LLM（呼び出し元）の担当
1. **クエリ生成**: ユーザーの曖昧な問い合わせをSlack検索用クエリに変換
2. **結果解析・要約**: MCPサーバーからの生の検索結果を解析し、自然言語で要約
3. **リトライ戦略**: 検索結果が不十分な場合の別クエリ生成やページング判断
4. **追加検索**: 必要に応じてMCPサーバーへの複数回のツール呼び出し
#### MCPサーバーの担当
1. **API呼び出し**: Slack search.messages APIへのHTTPリクエスト実行
2. **パラメータ処理**: クエリ、件数、カーソルなどのパラメータをSlack APIに渡す
3. **エラーハンドリング**: APIエラーやレート制限のエラーレスポンス返却
4. **結果返却**: Slack APIのレスポンスをそのままLLMに返却
### ツール設計
#### Slack検索ツール
```python
@mcp.tool()
async def get_slack_search_results(
query: str,
ctx: Context,
count: int = 20,
cursor: Optional[str] = None,
highlight: bool = True
) -> dict:
"""
Slack検索APIを呼び出して検索結果を取得します。
Args:
query: 検索クエリ
ctx: MCPコンテキスト
count: 取得件数
cursor: ページネーション用カーソル
highlight: ヒット部分のマークアップ有効化
Returns:
Slack APIのレスポンス辞書
"""
```
このツール1つのみを提供し、LLMが必要に応じて複数回呼び出してページングや再検索を行います。
### LLM利用時の参考プロンプト
#### クエリ生成の指針
LLMがユーザーの問い合わせをSlack検索用のクエリに変換する際の参考：
```text
ユーザーの問い合わせをSlack検索用のクエリに変換してください。
検索クエリのルール:
- 自然言語をSlack検索用のキーワードに変換
- 必要に応じて修飾子（in:, from:, before:, after:）を追加
- 曖昧な表現は具体的なキーワードに変換
- 日付表現は「昨日」「先週」などを具体的な日付に変換
例:
- 入力: 「昨日の会議のメモ」
- 出力: 「会議 メモ after:2024-01-14」
- 入力: 「田中さんからの資料」
- 出力: 「資料 from:@tanaka」
```
#### 結果解析・要約の指針
LLMがMCP検索結果を解析・要約する際の参考：
```text
Slack検索MCPから取得した結果を自然言語で要約・整形してください。
要約のルール:
- 検索結果が0件の場合: 「該当するメッセージが見つかりませんでした」
- 検索結果がある場合: 重要な情報を抽出して自然な文章で要約
- メッセージの送信者、日時、チャンネル名も含める
- 複数のメッセージがある場合は時系列順に整理
検索結果が不十分な場合:
- 関連性が低い、または件数が少ない場合は別のクエリで再検索
- より具体的なキーワードや関連語を使用
- cursorパラメータを使用してページングする
```
## エラーハンドリング
### APIエラー
- `invalid_auth`: 認証エラー
- `missing_scope`: スコープ不足
- `ratelimited`: レート制限
- `service_unavailable`: サービス停止
### 検索結果エラー
MCPサーバーはSlack APIのレスポンスをそのまま返却します。LLMが以下の判断を行います：
- 0件の場合: 別のクエリで再検索
- 関連性が低い場合: キーワード変更による再検索
- 大量の結果: cursorパラメータによるページング
## 設定項目
### 環境変数
- `SLACK_BOT_TOKEN`: Slack Bot Token
- `SLACK_USER_TOKEN`: Slack User Token（必要に応じて）
- `DEFAULT_SEARCH_COUNT`: デフォルト取得件数（デフォルト: 20）
### 設定ファイル
```json
{
"slack": {
"default_channels": ["general", "random"],
"excluded_channels": ["private-channel"],
"max_results_per_search": 100
}
}
```
## 使用例
### 基本的な使用フロー
```text
1. ユーザー: 「昨日の会議のメモを探して」
2. LLM: 「会議 メモ after:2024-01-14」に変換
3. LLM: get_slack_search_results(query="会議 メモ after:2024-01-14") を呼び出し
4. MCPサーバー: Slack APIを呼び出し、生の検索結果を返却
5. LLM: 検索結果を解析・要約
6. LLM: 「昨日の会議では、プロジェクトの進捗について議論されました...」
```
### 複数回検索の例
```text
1回目: LLM → get_slack_search_results(query="田中さんの資料") → 0件
2回目: LLM → get_slack_search_results(query="資料 from:@tanaka") → 0件
3回目: LLM → get_slack_search_results(query="資料 in:general from:@tanaka") → 2件ヒット
→ LLM: 「田中さんがgeneralチャンネルで資料を共有していました...」
```
### ページングの例
```text
1回目: LLM → get_slack_search_results(query="プロジェクト", count=20) → 20件 + cursor
2回目: LLM → get_slack_search_results(query="プロジェクト", count=20, cursor="xxx") → 追加20件
→ LLM: 全40件の結果を統合して要約
```
## 参考リンク
- [Slack Search API Documentation](https://api.slack.com/methods/search.messages)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Slack API Rate Limits](https://api.slack.com/docs/rate-limits)
