使用说明

🔔 Suzu-克劳德代码通知服务器

一个模型上下文协议（MCP）服务器，在Claude Code完成任务时播放您最喜欢的Spotify曲目作为通知。以日本礼仪钟命名，现在有音乐的力量！ 🎧

✨ 特性

🎵 Spotify集成 -播放您最喜欢的曲目作为通知声音！ 🎧
📱 桌面提醒 -显示带有自定义消息的系统通知
🔊 系统声音通知 -本机操作系统听起来像是回退
🌍 跨平台 -适用于macOS、Linux和Windows
🎶 多种声音类型 -成功、错误和信息声音（Spotify或系统）
🔧 调试记录 -用于故障排除的内置调试
🤖 自动集成 -与Claude Code无缝协作

🚀 快速开始

⚡ 超级简单的设置（推荐）

让Suzu和Spotify一起工作的最快方法是让Claude做所有的工作：

请克劳德进行设置:

fetch https://github.com/denar90/suzu-mcp/blob/main/SETUP.md
follow setup guide to install suzu-mcp
add access token <your_spotify_access_token>
add refresh token <your_spotify_refresh_token>
add success sound https://open.spotify.com/track/<your_track_id>

获取您的Spotify代币 发件人：https://suzu-mcp-spotify.netlify.app/
就是这样！ Claude自动处理安装、配置和设置。

手动安装

从npm安装:

npm install -g suzu-mcp

添加到克劳德代码:

claude mcp add suzu suzu

或 本地安装:

git clone https://github.com/denar90/suzu-mcp.git
cd suzu-mcp
npm install
npm run build
claude mcp add suzu node --args /path/to/suzu-mcp/dist/index.js

或手动添加到 ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "suzu": {
      "command": "suzu"
    }
  }
}

自动批准通知 （无缝体验所需）：

选项1-一次性批准（推荐）:
- 当第一次出现提示时，选择“是，不再询问suzu命令”
- 这将永久批准suzu通知，而不会出现未来的提示
选项2-配置文件: 增添 ~/.config/claude/settings.json:
```
{
  "enableAllProjectMcpServers": true
}
```
选项3-工具特定批准: 添加到您的 ~/.config/claude/claude_desktop_config.json:
```
{
  "mcpServers": {
    "suzu": {
      "command": "suzu"
    }
  },
  "toolUseConfirmation": {
    "suzu": "never"
  }
}
```

启用自动通知: 创建 ~/CLAUDE.md 与：

# Claude Code Configuration

## Default Behavior
- Always call `task_completed` when finishing tasks if the suzu MCP server is available
- Play completion notifications automatically without being asked
- Use the suzu notification system for task completion feedback

## Instructions for Claude
- When you complete any task, automatically check if the `task_completed` tool is available and call it with an appropriate completion message.

重要：安装后，重新启动Claude Code以使所有更改生效。

🎯 用法

可用工具

工具	说明	参数
`task_completed`	播放成功声音并显示完成消息	`message` （字符串）， `sound_type` （成功/错误/信息）
`notify`	显示带有自定义标题的常规通知	`title` （字符串）， `message` （字符串）， `sound_type`
`test_sound`	测试通知声音	`sound_type` （成功/错误/信息）
`show_config`	显示当前配置	无
`configure_spotify_tokens`	设置Spotify访问和刷新令牌	`access_token` （字符串）， `refresh_token` （可选）， `refresh_endpoint` （可选）
`configure_custom_sounds`	设置自定义通知声音	`source` （spotify/local）， `sound_type` （成功/错误/信息）， `value` （曲目ID/文件路径）

例子

任务完成：

task_completed({
  message: "Build completed successfully!",
  sound_type: "success"
})

自定义通知：

notify({
  title: "Claude Code",
  message: "Ready to assist!",
  sound_type: "info"
})

测试声音：

test_sound({
  sound_type: "success"
})

运作原理

自动集成：当你有 ~/CLAUDE.md 配置后，Claude将自动调用 task_completed 完成任务时
无手动呼叫：您不需要手动使用通知工具-Claude会自动处理此问题
任务完成反馈：当Claude完成编码任务、构建、部署等时，获得音频和视觉反馈。

🎵 Spotify集成

使用自定义音乐通知改变您的编码体验！设置Spotify集成，以便在任务完成时播放您喜爱的曲目。

使用OAuth应用程序快速设置

访问Spotify OAuth应用程序: https://suzu-mcp-spotify.netlify.app/
点击“使用Spotify登录” 授权应用程序
复制令牌 授权后显示

通过Claude配置:

Ask Claude: "Configure my Spotify with access_token: BQA... and refresh_token: AQC..."

或者仅针对访问令牌：

Ask Claude: "Set up my Spotify access token: BQA..."

手动设置（高级）

如果您想创建自己的Spotify应用程序：

创建Spotify应用程序:
- 首选https://developer.spotify.com/dashboard
- 使用重定向URI创建新应用程序： http://localhost:8888/callback
- 记下您的客户端ID和客户端密码
获取代币:
- 使用Spotify的授权码流
- 或访问：https://developer.spotify.com/console/post-playlists/
- 同时获取access_token和refresh_token

配置刷新端点 （用于自动续订）：

Ask Claude: "Set up Spotify refresh endpoint: https://your-endpoint.com/refresh"

设置自定义声音

配置Spotify后，自定义您的通知声音：

Ask Claude: "Set my Spotify success sound to: 4uLU6hMCjMI75M1A2tKUQC"
Ask Claude: "Set my Spotify error sound to: https://open.spotify.com/track/60nZcImufyMA1MKQY3dcCH"
Ask Claude: "Set my Spotify info sound to: spotify:track:5QDLhrAOJJdNAmCTBusfHY"

查找Spotify曲目ID：

右键单击Spotify中的任何歌曲
分享→ 复制歌曲链接
从URL提取ID： https://open.spotify.com/track/TRACK_ID_HERE
只使用ID或完整的URL-两者都可以！

需求

Spotify高级 （Web API播放需要）
活动Spotify设备 （桌面应用程序、移动设备等）
设备必须正在播放或最近使用过

🔧 平台支持

macOS

主要的，重要的 afplay 带有系统声音（Glass、Sosumi、Ping）
退路： say 语音通知命令
第三级：终端铃(printf "\a")

Linux

主要的，重要的 paplay PulseAudio
退路： aplay ALSA
第三级：终端铃

视窗

用途 rundll32 user32.dll,MessageBeep

🐛 故障排除

快速测试

使用内置的测试命令验证一切正常：

# In Claude Code, run:
test_sound({ sound_type: "success" })

没有声音播放？

检查权限：确保向Claude Code授予音频权限
手动测试：运行 afplay /System/Library/Sounds/Glass.aiff （macOS）在终端
启用调试：运行 claude --debug 并检查控制台输出 [DEBUG] 消息
验证连接：类型 /mcp 在Claude Code中查看服务器状态

没有自动通知？

检查CLAUDE.md：确保 ~/CLAUDE.md 存在上述配置
重新启动Claude代码：配置更改需要重新启动
检查批准：确保您批准使用铃木工具（上述步骤3）
手动测试：尝试拨打电话 task_completed 手动验证其是否有效

MCP服务器未连接？

检查安装情况：运行 suzu --version 在终端
验证路径：对于本地安装，请确保 dist/index.js 文件存在
重建：运行 npm run build 在项目目录中
检查配置：验证 claude_desktop_config.json 语法是有效的JSON
重启：在任何配置更改后重新启动Claude Code

调试输出

在中查找这些消息 claude --debug:

[DEBUG] Attempting to play sound: success on platform: darwin
[DEBUG] Command 1 succeeded: afplay /System/Library/Sounds/Glass.aiff

🛠️ 发展

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Test the server directly
node dist/index.js

# Install with debugging
npm install --verbose

📁 项目结构

claude-notification-mcp/
├── src/
│   └── index.ts          # Main MCP server code
├── dist/                 # Built JavaScript files
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .mcp.json            # Local MCP configuration
└── README.md            # This file

🤝 贡献

分叉存储库
创建要素分支
进行更改
跨平台测试
提交拉取请求

📄 许可证

MIT许可证-可根据需要自由使用和修改。

🙏 致谢

内置于模型上下文协议（MCP）
用途节点通知器用于桌面通知
受Claude Code中更好的任务完成反馈需求的启发