Slack MCP Server - Complete Implementation

Slack MCP 服务 - 完整实现

📋 项目概述

这是一个使用 FastMCP v2 实现的完整 Slack API 集成 MCP 服务。按照作业指南，已实现4 项必需功能、4 项可选功能以及4 项额外的番茄钟计时器功能。

🎯 主要特点

• ✅ 完整支持 UTF-8 韩文 - 所有消息均完美支持韩文
• ✅ 双令牌系统 - 使用 Bot Token + User Token 支持所有功能
• ✅ 智能文件上传 - 根据文件大小自动选择最佳上传方式
• ✅ 番茄钟计时器 - 时间管理工具，包含自动通知功能
• ✅ 异步处理 - 基于高性能 asyncio 实现
• ✅ 详细的错误处理 - 为所有 API 调用提供适当的异常处理

🚀 功能列表

🔴 必需功能（Required Features - 4 项）

1. send_slack_message - 发送消息

   • 向频道或 DM 发送消息
   • 支持线程回复
   • 完整支持 UTF-8 韩文

2. get_slack_channels - 获取频道列表

   • 区分公开/私有频道
   • 检查成员身份状态
   • 筛选已归档频道

3. get_slack_channel_history - 获取消息历史记录

   • 从最新消息开始获取
   • 可指定时间范围
   • 包含消息元数据

4. send_slack_direct_message - 发送 DM

   • 向指定用户发送一对一消息
   • 自动创建 DM 频道
   • 筛选机器人用户

🟡 可选功能（Optional Features - 4 项）

5. get_slack_users - 获取用户列表

   • 按用户类型分类（管理员、成员、访客、机器人）
   • 筛选可发送 DM 的用户
   • 提供详细的个人资料信息

6. search_slack_messages - 搜索消息（需要 User Token）

   • 基于关键词搜索整个工作区
   • 提供排序和筛选选项
   • 包含搜索结果元数据

7. upload_file_to_slack - 智能文件上传

   • 根据文件大小选择最佳上传方式
   • 支持多种文件格式
   • 自动预览和代码语法高亮

8. add_slack_reaction - 添加消息反应

   • 添加表情符号反应
   • 支持多种表情符号格式

🟢 额外功能（Bonus Features - 4 项）

9. start_pomodoro_timer - 启动番茄钟计时器

   • 5 种计时器类型（study、work、break、meeting、custom）
   • 自动开始/结束通知
   • 自定义时长和消息

10. cancel_pomodoro_timer - 取消计时器

    • 立即停止正在运行的计时器
    • 发送取消通知

11. list_active_timers - 活跃计时器列表

    • 列出当前正在运行的所有计时器
    • 显示进度和剩余时间

12. get_timer_status - 获取计时器状态

    • 查看指定计时器的详细状态
    • 查看实时进度

🛠️ 实用功能

13. test_slack_connection - 测试连接
14. get_workspace_info - 获取工作区信息
15. get_file_preview - 文件预览
16. verify_or_create_file - 验证/创建文件

📦 安装和运行方法

1. 初始化项目

# 프로젝트 클론 또는 다운로드 후
cd slack-mcp

# uv 패키지 매니저 설치 (없는 경우)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 가상환경 생성 및 활성화
uv venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate  # Windows

# 의존성 설치
uv sync
# 또는
uv pip install -r requirements.txt

2. 配置环境变量

创建 .env 文件并按如下方式配置：

# 필수: Slack Bot Token (xoxb-로 시작)
SLACK_BOT_TOKEN=xoxb-your-bot-token-here

# 선택: Slack User Token (xoxp-로 시작) - 검색, 파일업로드용
SLACK_USER_TOKEN=xoxp-your-user-token-here

# 선택: 기본 채널 ID (테스트용)
SLACK_TEST_CHANNEL_ID=C08UZKK9Q4R

# 선택: 로그 레벨
LOG_LEVEL=INFO

3. 配置 Slack App

所需的 Bot Token Scopes：

channels:read        # 채널 목록 조회
channels:history     # 채널 메시지 히스토리 조회
chat:write          # 메시지 전송
im:read             # DM 채널 읽기
im:write            # DM 메시지 전송
im:history          # DM 히스토리 조회
users:read          # 사용자 정보 조회
reactions:write     # 반응 추가

额外的 User Token Scopes（用于可选功能）：

search:read         # 메시지 검색
files:write         # 파일 업로드

4. 运行服务

# MCP 서버 실행
python slack_mcp_server.py

# 또는 직접 실행
uv run slack_mcp_server.py

💡 用法和示例

发送基本消息

# Claude/LLM이 도구 호출 시
send_slack_message(
    channel="C08UZKK9Q4R", 
    text="안녕하세요! MCP에서 보내는 메시지입니다! 🚀"
)

上传文件（智能处理）

# 다양한 크기의 파일을 자동으로 최적 방식으로 업로드
upload_file_to_slack(
    file_path="./report.pdf",
    channels="C08UZKK9Q4R",
    title="분석 보고서",
    comment="월간 데이터 분석 결과입니다."
)

使用番茄钟计时器

# 수업 타이머 시작 (50분)
start_pomodoro_timer(
    timer_type="study",
    channel_id="C08UZKK9Q4R",
    duration_minutes=50,
    custom_name="파이썬 고급 문법 학습"
)

# 활성 타이머 확인
list_active_timers()

# 타이머 취소
cancel_pomodoro_timer("study_20250602_143022_123456")

搜索消息（需要 User Token）

# 워크스페이스 전체에서 메시지 검색
search_slack_messages(
    query="MCP 서버",
    count=10,
    sort="timestamp"
)

🏗️ 项目结构

slack-mcp/
├── .env                     # 환경 변수 (Git 제외)
├── .env.example            # 환경 변수 템플릿
├── .gitignore              # Git 무시 파일
├── README.md               # 이 파일
├── requirements.txt        # 의존성 목록
├── pyproject.toml         # 프로젝트 설정
├── slack_api_client.py    # Slack API 클라이언트 (핵심 모듈)
├── pomodoro_timer.py      # 뽀모도로 타이머 모듈
└── slack_mcp_server.py    # FastMCP 서버 메인

🔧 技术实现细节

双令牌系统

• Bot Token (xoxb-)：常规机器人功能（发送消息、获取频道等）
• User Token (xoxp-)：需要用户权限的功能（搜索、大文件上传）

智能文件上传策略

1. 小型文本文件（< 50KB）：直接作为消息内容发送
2. 中型文件（50KB - 1MB）：作为代码片段上传
3. 普通文件（1MB - 100MB）：使用标准文件上传
4. 大型文件（100MB - 1GB）：使用 User Token 上传
5. 超大型文件（> 1GB）：仅分享文件信息

异步处理和并发

• 基于 asyncio 完全异步实现
• 支持番茄钟计时器并行运行
• 通过锁（Lock）确保客户端初始化安全

UTF-8 韩文支持

headers = {
    'Content-Type': 'application/json; charset=utf-8'
}

🐛 开发过程中遇到的困难及解决方法

1. 难以统一各函数的 Input 变量名

问题：API 函数的参数名称各不相同，缺乏一致性

• channel vs channel_id vs channels
• text vs message vs content

解决方案：

• 以 Slack API 官方文档为准统一变量名（计划后续更新）
• 在内部函数中采用一致的命名规范
• 在 docstring 中明确说明参数

async def send_message(
    self, 
    channel: str,      # 가능한 부분들은 channel 로 통일 예정
    text: str,         # 통일: text
    thread_ts: Optional[str] = None
) -> Dict[str, Any]:

2. 难以找到 Input-Output 变量名

问题：Slack API 响应具有复杂的嵌套结构，难以提取所需数据

解决方案：

• 输出 API 响应日志以了解其结构
• 编写通用的数据提取函数
• 规范化并格式化响应数据

# 응답 데이터 정규화 예시
formatted_messages.append({
    'text': msg.get('text', ''),
    'user': msg.get('user', 'Unknown'),
    'timestamp': readable_time,
    'ts': msg.get('ts', ''),
    # ... 필요한 필드만 추출
})

3. 为使用最新版本的 Outdated file_upload 函数经历了许多尝试

问题：Slack 的文件上传 API 多次变更，原有方式已弃用

解决方案：

• files.upload（已弃用）→ files.getUploadURLExternal + files.completeUploadExternal
• 采用 Slack SDK 与现有 REST API 的混合方案
• 针对不同文件大小实现不同的上传策略

# 새로운 파일 업로드 플로우
# 1. 업로드 URL 요청
upload_response = await self._make_request('files.getUploadURLExternal', 'POST', upload_data)

# 2. 외부 URL로 파일 업로드
async with self._session.put(upload_url, data=file_content) as response:
    # 파일 업로드

# 3. 업로드 완료 처리
complete_response = await self._make_request('files.completeUploadExternal', 'POST', complete_data)

4. 需要 User Token 的情况与仅用 Bot Token 即可处理的情况

问题：难以确定各项功能需要使用哪种令牌

解决方案：

• 明确分类各项功能的令牌要求
• 通过双令牌系统自动选择
• 令牌不足时显示清晰的提示信息

# Bot Token으로 가능한 기능
- 메시지 전송 (chat.postMessage)
- 채널 목록 (conversations.list)
- 사용자 목록 (users.list)
- 파일 업로드 (< 100MB)

# User Token이 필요한 기능  
- 메시지 검색 (search.messages)
- 대용량 파일 업로드 (> 100MB)

5. GET 与 POST 的区别

问题：不清楚什么时候应该使用 GET，什么时候应该使用 POST

解决方案：

• 准确核对 Slack API 文档中的 HTTP 方法
• 数据查询使用 GET，数据创建/修改使用 POST
• 统一通过 _make_request 函数处理

# GET: 데이터 조회
await self._make_request('conversations.list', 'GET', params)
await self._make_request('users.list', 'GET', params)

# POST: 데이터 생성/수정
await self._make_request('chat.postMessage', 'POST', data)
await self._make_request('files.getUploadURLExternal', 'POST', data)

6. 기타 해결한 이슈들

• Rate Limiting: 지수 백오프와 재시도 로직
• Error Handling: 각 에러 코드별 맞춤형 해결 제안
• UTF-8 Encoding: 한글 메시지 완벽 지원
• Async Safety: 뽀모도로 타이머의 동시 실행 처리

📊 성능 및 제한사항

파일 업로드 제한

• 무료 플랜: 최대 5GB 워크스페이스 스토리지
• 개별 파일: 최대 1GB (유료 플랜에서)
• Bot Token: 최대 100MB 파일 업로드
• User Token: 최대 1GB 파일 업로드

API Rate Limits

• Tier 1 메소드: 1+ per minute
• Tier 2 메소드: 20+ per minute
• Tier 3 메소드: 50+ per minute
• Tier 4 메소드: 100+ per minute

🔍 테스트 방법

1. 연결 테스트

# 서버 실행 후 Claude에서 테스트
test_slack_connection()

2. 기본 기능 테스트

# 채널 목록 조회
get_slack_channels()

# 메시지 전송 테스트  
send_slack_message("C08UZKK9Q4R", "테스트 메시지입니다! 🎉")

3. 고급 기능 테스트

# 파일 업로드 테스트
upload_file_to_slack("./test.txt", title="테스트 파일")

# 뽀모도로 타이머 테스트
start_pomodoro_timer("work", duration_minutes=25, custom_name="테스트 작업")

🤝 기여 방법

1. 이슈 제보: GitHub Issues 사용
2. 기능 제안: Feature Request 템플릿 사용
3. 코드 기여: Pull Request 환영
4. 문서 개선: README 및 docstring 개선

📄 라이선스

이 프로젝트는 MIT 라이선스를 따릅니다.

🙋‍♂️ 문의 및 지원

• 개발자: JunHyuck Kwon
• 버전: 8.5.2 (Complete Implementation)
• 최종 업데이트: 2025-06-04

---

과제 완성도: ✅ 필수 4개 + ✅ 선택 4개 + ✅ 보너스 4개 + ✅ 유틸리티 4개 = 총 16개 기능 완전 구현

이 프로젝트를 통해 실제 업무에서 활용할 수 있는 고품질 Slack 연동 도구를 구축할 수 있습니다! 🚀