mcp_music_tools

# 音乐代理 这是一个 Swift 6 项目，包含用于通过直接 API 访问和模型上下文协议（MCP）服务器控制音乐生态系统的库和工具。该项目包括一个由 AgentKit 提供支持的 AI 驱动命令行代理，可以创建用于家庭的智能音乐助手。 ## 架构 ### 核心库 1. **AppleMusicKit**：与 Apple Music API 交互的库 2. **SonosKit**：通过 node-sonos-http-api 控制 Sonos 扬声器的库 3. **AmplifierKit**：控制 Denon/Marantz 放大器的库 4. **OpenURLKit**：在默认浏览器中打开 URL 的库 5. **MusicPlayerControlTool**：用于控制简单基于 Web 的音乐播放器的工具 ### MCP 服务器集成 每个工具都将其功能作为 MCP（模型上下文协议）工具公开，允许 AI 代理与您的音乐生态系统交互。**MusicMCPServer** 可执行文件将所有工具组合成一个单一的 MCP 服务器，可由 AI 助手使用。 ### AI 代理 **MusicAgentCLI** 是一个由 AWS Bedrock 和 AgentKit 提供支持的智能命令行助手，可以： - 使用自然语言搜索音乐 - 控制家庭音频系统 - 在各种设备上播放音乐 - 回答有关歌曲和艺术家的问题 ## 功能 ### AppleMusicKit - 按艺术家姓名、歌曲标题或两者搜索 Apple Music 目录 - 获取有关特定歌曲的详细信息 - 使用 ES256 算法生成 Apple Music API 开发人员令牌 - 用于 AI 代理集成的 MCP 工具 - 用于测试的命令行界面 ### SonosKit - 控制播放（播放、暂停、停止、下一曲、上一曲） - 管理队列（添加曲目、清除队列） - 设置音量和随机播放模式 - 获取播放器状态和房间信息 - 列出可用的房间/区域 - 播放 Apple Music 歌曲、专辑和播放列表 - 加入/离开房间组 - 用于 AI 代理集成的 MCP 工具 - 用于测试的命令行界面 ### AmplifierKit - 打开/关闭放大器 - 在输入源之间切换（Sonos、Apple TV 或按索引） - 获取可用的源名称及其索引 - 获取放大器状态 - 用于本地网络设备的 SSL 证书绕过 - 用于 AI 代理集成的 MCP 工具 - 用于测试的命令行界面 ### OpenURLKit - 在默认浏览器中打开 URL - 支持 macOS 和 iOS 平台 - 无效 URL 的错误处理 - 用于 AI 代理集成的 MCP 工具 - 用于测试的命令行界面 ### MusicPlayerControlTool - 控制简单的基于 Web 的音乐播放器 - 从播放队列中添加/删除歌曲 - 基于 JSON 的命令接口 - 用于 AI 代理集成的 MCP 工具 ## 要求 - Swift 6.0+ - macOS 15.0+ - 对于 AppleMusicKit：Apple Music API 开发人员令牌 - 对于 SonosKit：本地或网络上运行的 [node-sonos-http-api](https://github.com/jishi/node-sonos-http-api) - 对于 AmplifierKit：本地网络上的 Denon/Marantz 放大器 - 对于 MusicAgentCLI：AWS 凭证和 [AgentKit](https://github.com/sebsto/AgentKit) 依赖项 ## 安装 ### Swift 包管理器 将以下内容添加到您的 `Package.swift` 文件中： ```swift dependencies: [ .package(url: "https://github.com/sebsto/MusicAgentKit.git", from: "1.0.0"), .package(url: "https://github.com/sebsto/AgentKit.git", from: "1.0.0") // AI 代理功能所需 ] ``` ### 构建项目 ```bash # 克隆仓库 git clone https://github.com/sebsto/MusicAgentKit.git cd MusicAgentKit # 构建所有目标 swift build # 构建特定可执行文件 swift build --product MusicAgentCLI swift build --product MusicMCPServer ``` ## 用法 ### MusicAgentCLI - AI 音乐助手 AI 驱动的音乐助手使用 AWS Bedrock 和 AgentKit 提供对音乐生态系统的自然语言控制： ```bash # 启动交互式 AI 助手 swift run MusicAgentCLI # 使用特定的 AWS 配置文件 swift run MusicAgentCLI --profile-name myprofile # 使用 SSO 身份验证 swift run MusicAgentCLI --sso # 使用自定义区域 swift run MusicAgentCLI --region us-west-2 ``` 示例交互： - “放大器的状态是什么？” - “播放 Queen 的 Bohemian Rhapsody” - “Hotel California 的发行日期是什么？” - “切换到 Sonos 输入并播放一些爵士乐” ### MusicMCPServer - MCP 服务器（HTTP） 运行 MCP 服务器，通过 HTTP 将所有音乐控制工具暴露给 AI 助手： ```bash # 启动 MCP 服务器 swift run MusicMCPServer ``` 服务器暴露的工具： - 放大器控制（电源、源切换、状态） - Sonos 控制（播放、音量、队列管理） - Apple Music 搜索和播放 - URL 打开 - 音乐播放器控制 ### 库用法 #### AppleMusicKit ```swift import AppleMusicKit // 使用现有的开发人员令牌初始化 let client = AppleMusicClient(developerToken: "your_developer_token", storefront: "us") // 或使用密钥（私钥、团队 ID、密钥 ID）初始化 let secret = Secret(privateKey: privateKeyString, teamId: "YOUR_TEAM_ID", keyId: "YOUR_KEY_ID") let client = try await AppleMusicClient(secret: secret, storefront: "us") // 按艺术家搜索 let artistResults = try await client.searchByArtist("Queen") // 按歌曲标题搜索 let songResults = try await client.searchByTitle("Bohemian Rhapsody") // 按艺术家和标题搜索 let combinedResults = try await client.searchByArtistAndTitle(artist: "Queen", title: "Bohemian Rhapsody") // 获取特定歌曲的详细信息 let songDetails = try await client.getSongDetails(id: "1234567890") // 直接生成令牌 let tokenFactory = AppleMusicTokenFactory(secret: secret) let token = try await tokenFactory.generateToken() ``` #### SonosKit ```swift import SonosKit // 使用默认主机和端口初始化 let client = SonosClient() // 或使用自定义主机、端口和默认房间初始化 let client = SonosClient(host: "192.168.1.100", port: 5005, defaultRoom: "Living Room") // 控制播放 try await client.play() try await client.pause() try await client.stop() try await client.next() try await client.previous() // 设置音量 try await client.setVolume(50) // 管理队列 try await client.addToQueue(uri: "spotify:track:5hTpBe8h35rJ67eAWHQsJx") try await client.clearQueue() // 播放 Apple Music 内容 try await client.playAppleMusic(contentType: .song, contentId: "355364259", mode: .queue) try await client.playAppleMusic(contentType: .album, contentId: "355363490", mode: .now) try await client.playAppleMusic(contentType: .playlist, contentId: "pl.ed52c9eeaa0740079c21fa8e455b225e", mode: .next) // 获取状态 let state = try await client.getState() print("当前播放：\(state.currentTrack.title) by \(state.currentTrack.artist)") // 列出房间 let rooms = try await client.getRooms() for room in rooms { print(room) } ``` #### AmplifierKit ```swift import AmplifierKit // 使用默认主机和端口初始化 let config = AmplifierConfig(host: "192.168.1.37", port: 10443) let controller = HTTPAmplifierController(config: config) // 电源控制 try await controller.powerOn() try await controller.powerOff() // 源控制 try await controller.switchToSource(index: 4) // 切换到索引为 4 的源 try await controller.switchToSonos() // 快捷方式切换到 Sonos try await controller.switchToAppleTV() // 快捷方式切换到 Apple TV // 获取信息 let sources = try await controller.getSourceNames() let status = try await controller.getMainZoneStatus() print("区域：\(status.name)，电源：\(status.isPowered ? "开启" : "关闭")") ``` #### OpenURLKit ```swift import OpenURLKit // 直接打开 URL try URLOpener.open("https://aws.amazon.com") // 或使用 URL 对象 let url = URL(string: "https://aws.amazon.com")! try URLOpener.open(url) // 错误处理 do { try URLOpener.open("invalid-url") } catch URLOpenerError.invalidURL { print("URL 无效") } catch URLOpenerError.failedToOpenURL { print("无法打开 URL") } catch { print("发生错误：\(error)") } ``` ## 命令行界面 ### AppleMusicCLI 用法 ```bash # 按艺术家搜索（使用内置令牌生成） swift run AppleMusicCLI artist "Queen" # 按标题搜索（使用内置令牌生成） swift run AppleMusicCLI title "Bohemian Rhapsody" # 按艺术家和标题搜索（使用内置令牌生成） swift run AppleMusicCLI search "Queen" "Bohemian Rhapsody" # 获取歌曲详情（使用内置令牌生成） swift run AppleMusicCLI song "1234567890" # 使用内置 ES256 实现生成令牌（默认） swift run AppleMusicCLI token # 使用自定义凭证生成令牌 swift run AppleMusicCLI token --team-id "YOUR_TEAM_ID" --key-id "YOUR_KEY_ID" --key-path "/path/to/private_key.p8" ``` ### SonosCLI 用法 首先，启动 node-sonos-http-api 服务器： ```bash # 启动 Sonos HTTP API 服务器 ./setup_sonos_api.sh ``` 然后，在新的终端窗口中： ```bash # 获取当前状态（默认命令） swift run SonosCLI # 播放音乐 swift run SonosCLI play --room "Living Room" # 暂停音乐 swift run SonosCLI pause --room "Living Room" # 设置音量 swift run SonosCLI volume 50 --room "Living Room" # 现在播放 Apple Music 歌曲 swift run SonosCLI applemusic song "355364259" --mode now --room "Living Room" # 列出可用房间 swift run SonosCLI rooms ``` ### AmplifierCLI 用法 ```bash # 打开放大器 swift run AmplifierCLI power-on # 关闭放大器 swift run AmplifierCLI power-off # 切换到 Sonos 输入 swift run AmplifierCLI sonos # 切换到 Apple TV 输入 swift run AmplifierCLI appletv # 切换到特定源索引 swift run AmplifierCLI source 3 # 列出所有可用源及其索引 swift run AmplifierCLI sources # 获取放大器状态 swift run AmplifierCLI status ``` ### OpenURLCLI 用法 ```bash # 在默认浏览器中打开 URL swift run OpenURLCLI open "https://aws.amazon.com" # 或使用默认子命令 swift run OpenURLCLI "https://aws.amazon.com" ``` ## 设置和配置 ### Apple Music API 设置 要使用 Apple Music API，您需要获取开发人员凭证： 1. **注册 Apple 开发者计划**：如果您尚未注册，请在 [developer.apple.com](https://developer.apple.com/) 注册。 2. **创建 MusicKit 标识符**： - 进入 [Apple 开发者账户](https://developer.apple.com/account/) - 导航到“证书、标识符和配置文件” - 选择“标识符”并点击“+”按钮 - 选择“媒体 ID”并按照说明注册 MusicKit 标识符 3. **生成私钥**： - 在您的 Apple 开发者账户中，进入“密钥” - 点击“+”按钮添加新密钥 - 给它一个名称并选择“MusicKit”复选框 - 点击“继续”然后“注册” - **重要**：在提示时下载私钥文件（.p8）。Apple 只提供此文件**一次**。 4. **记录您的凭证**： - **团队 ID**：在 Apple 开发者账户页面右上角找到 - **密钥 ID**：您创建的密钥的标识符 - **私钥**：您下载的 .p8 文件的内容 5. **更新 Secret.swift 文件**： - 打开 `Sources/AppleMusicKit/DefaultSecret.swift` - 取消注释 `defaultSecret` 部分 - 用您的实际凭证替换占位符值： ```swift public let defaultSecret = Secret( privateKey: """ -----BEGIN PRIVATE KEY----- YOUR_PRIVATE_KEY_CONTENT_HERE -----END PRIVATE KEY----- """, teamId: "YOUR_TEAM_ID", keyId: "YOUR_KEY_ID" ) ``` 有关生成开发人员令牌的更多信息，请参阅 [Apple 的文档](https://developer.apple.com/documentation/applemusicapi/generating-developer-tokens)。 ### AWS 凭证设置 对于 AI 代理功能，您需要 AWS 凭证： 1. **安装 AWS CLI** 并配置您的凭证： ```bash aws configure ``` 2. **或使用 AWS SSO**： ```bash aws sso login --profile myprofile ``` 3. **或使用临时凭证**，通过提供到凭证文件的路径。 ### MCP 配置 MCP 服务器配置存储在 `mcp-stdio.json` 中。更新路径以匹配您的构建位置： ```json { "mcpServers": { "MusicMCPServer": { "command": "/path/to/your/.build/debug/MusicMCPServer", "args": [] } } } ``` ### Sonos 控制设置 1. 安装并运行 [node-sonos-http-api](https://github.com/jishi/node-sonos-http-api)： ```bash git clone https://github.com/jishi/node-sonos-http-api.git cd node-sonos-http-api npm install npm start ``` 2. API 将自动在网络上发现您的 Sonos 扬声器。 3. 使用 SonosClient 配置更新主机和端口： ```swift let client = SonosClient(host: "192.168.1.100", port: 5005) ``` ### 放大器控制设置 1. 确保您的 Denon/Marantz 放大器连接到您的本地网络。 2. 查找放大器的 IP 地址（检查路由器的 DHCP 客户端列表或放大器的网络设置）。 3. 使用正确的 IP 地址更新 AmplifierConfig： ```swift let config = AmplifierConfig(host: "192.168.1.37", port: 10443) ``` 4. AmplifierKit 包括用于处理这些设备常用的自签名证书的 SSL 证书绕过功能。 ## 项目结构 ``` MusicAgent/ ├── Sources/ │ ├── AmplifierKit/ # 放大器控制库 + MCP 工具 │ ├── AmplifierCLI/ # 放大器命令行界面 │ ├── AppleMusicKit/ # Apple Music API 库 + MCP 工具 │ ├── AppleMusicCLI/ # Apple Music 命令行界面 │ ├── SonosKit/ # Sonos 控制库 + MCP 工具 │ ├── SonosCLI/ # Sonos 命令行界面 │ ├── OpenURLKit/ # URL 打开库 + MCP 工具 │ ├── OpenURLCLI/ # URL 打开命令行界面 │ ├── MusicPlayerControlTool/ # 基于 Web 的音乐播放器控制工具 │ ├── MusicMCPServer/ # 所有工具的综合 MCP 服务器 │ └── MusicAgentCLI/ # AI 驱动的音乐助手 ├── Tests/ # 所有库的单元测试 ├── web_player/ # 简单的基于 Web 的音乐播放器 ├── sonos-api/ # Node.js Sonos HTTP API └── data/ # MCP 调用样本数据 ``` ## 许可证 该项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。