开始前你需要開始前你需要Before you start
- 已经接上其中一套 MCP（两套的区别看这篇）。还没接的话，这篇当参考读也可以。已經接上其中一套 MCP（兩套的分別看這篇）。還沒接的話，這篇當參考讀也可以。Either MCP already connected (see how the two differ). Reading it as reference works too.
- 想跟着验证的话，准备一个能问「列出我的房间」的 AI 助手。想跟著驗證的話，準備一個能問「列出我的房間」的 AI 助理。To follow along, an assistant you can ask to list your rooms.
先说清楚：官方那 34 个列不出名字先說清楚：官方那 34 個列不出名字First, the honest part: Sonos's 34 have no published names
Sonos 的技术博客只写了「34 carefully designed tools」（34 个精心设计的工具），没有给出任何一个工具名。官方帮助页列的是一段功能范围，不是工具清单。而且官方明说：工具名、说明和参数会随时变化，不应当成稳定 API，工具表才是最终依据。Sonos 的技術部落格只寫了「34 carefully designed tools」（34 個精心設計的工具），沒有給出任何一個工具名。官方說明頁列的是一段功能範圍，不是工具清單。而且官方明說：工具名、說明和參數會隨時變化，不應當成穩定 API，工具表才是最終依據。Sonos's tech blog says only "34 carefully designed tools" and names none of them. The support page describes a capability range, not a tool list. And Sonos states plainly that tool names, descriptions and schemas will evolve without notice — the tool list itself is the authority.
我们试着从公开渠道拿真名，结果如下，你可以自己复核：我們試著從公開渠道拿真名，結果如下，你可以自己覆核：We tried to obtain the real names from public sources. Here is what we found, so you can check it yourself:
- 直接对
https://mcp.ws.sonos.com/mcp发tools/list，未鉴权时返回401，错误串是access_denied / Invalid Token。直接對https://mcp.ws.sonos.com/mcp發tools/list，未驗證時回傳401，錯誤字串是access_denied / Invalid Token。Postingtools/liststraight tohttps://mcp.ws.sonos.com/mcpwithout auth returns401withaccess_denied / Invalid Token. - 它的资源元数据只暴露两个 scope：
playback-control-all和partner-content:read，没有工具表。它的資源中繼資料只暴露兩個 scope：playback-control-all和partner-content:read，沒有工具表。Its resource metadata exposes just two scopes,playback-control-allandpartner-content:read— no tool catalogue. - Sonos 的开发者文档站（
docs.sonos.com）里没有 MCP 一节。Sonos 的開發者文件站（docs.sonos.com）裡沒有 MCP 一節。Sonos's developer docs site (docs.sonos.com) has no MCP section.
所以：那 34 个的真名，唯一可靠来源是登录 Sonos 账号后从运行时读出来。谁在文章里「列出」了它们，要么是猜的，要么是抄别人猜的。我们这边不发这种表。所以：那 34 個的真名，唯一可靠來源是登入 Sonos 帳號後從執行時讀出來。誰在文章裡「列出」了它們，要麼是猜的，要麼是抄別人猜的。我們這邊不發這種表。So the only reliable source for those 34 names is reading them at runtime after signing in to a Sonos account. Anyone publishing a "list" of them is guessing, or copying someone who guessed. We won't publish one.
官方文档写明的八类能力官方文件寫明的八類能力The eight capability areas Sonos does document
这是官方帮助页明确列出的范围，可以逐条核对：這是官方說明頁明確列出的範圍，可以逐條核對：These are the areas Sonos's support page does state explicitly — each is checkable:
- 发现设备与分组發現裝置與分組Discovery of players and groups
- 从已连接的音乐服务播放從已連接的音樂服務播放Playback from connected services
- 按设备或分组调音量、静音按裝置或分組調音量、靜音Volume and mute by product or group
- 播放 / 暂停 / 跳过 / 定位播放 / 暫停 / 跳過 / 定位Play, pause, skip, seek
- 分组与搬移音频分組與搬移音訊Grouping and moving audio
- Sonos 收藏夹与播放列表Sonos 收藏夾與播放清單Sonos Favorites and playlists
- 随机与循环隨機與循環Shuffle and repeat
- 线路输入，以及家庭影院的夜间模式与语音增强線路輸入，以及家庭影院的夜間模式與語音增強Line-in, plus home-theater Night Sound and Speech Enhancement
这八类分别对应我们哪个工具這八類分別對應我們哪個工具Which of our tools covers each
| 官方写明的能力官方寫明的能力Documented by Sonos | 我们的工具我們的工具Our tools |
|---|---|
| 发现设备与分组發現裝置與分組Discovery of players and groups | list_rooms |
| 从已连接的服务播放從已連接的服務播放Playback from connected services | play_music · search_music |
| 按设备或分组调音量、静音按裝置或分組調音量、靜音Volume and mute by product or group | set_volume · adjust_volume · set_mute |
| 播放 / 暂停 / 跳过 / 定位播放 / 暫停 / 跳過 / 定位Play, pause, skip, seek | toggle_play_pause · next_track · previous_track · seek |
| 分组与搬移音频分組與搬移音訊Grouping and moving audio | group_rooms · ungroup_room · move_music |
| 收藏夹与播放列表收藏夾與播放清單Favorites and playlists | list_favorites · list_playlists |
| 随机与循环隨機與循環Shuffle and repeat | set_play_mode |
| 线路输入 / 夜间模式 / 语音增强線路輸入 / 夜間模式 / 語音增強Line-in / Night Sound / Speech Enhancement | switch_source · set_home_theater |
也就是说：按官方自己写出来的范围，八类我们都有对应工具。我们不宣称「能力一样多」——官方那 34 个里可能还有更细的动作，但我们没法核实，所以不做判断。也就是說：按官方自己寫出來的範圍，八類我們都有對應工具。我們不宣稱「能力一樣多」——官方那 34 個裡可能還有更細的動作，但我們沒法核實，所以不做判斷。In other words, every capability Sonos actually documents has a matching tool on our side. We do not claim parity: the other tools among their 34 may cover finer actions we can't verify, so we don't judge.
我们的 27 个工具，逐条我們的 27 個工具，逐條All 27 of our tools, one by one
英文端点 https://relay.zonefoundry.dev/mcp 提供的完整名单：英文端點 https://relay.zonefoundry.dev/mcp 提供的完整名單：The full list served by the English endpoint, https://relay.zonefoundry.dev/mcp:
| 用途用途Group | 工具工具Tool | 做什么做什麼What it does |
|---|---|---|
| 看状态看狀態Read state | list_rooms |
列出家里所有 Sonos 房间与当前分组列出家裡所有 Sonos 房間與目前分組Lists every room and the current grouping |
now_playing |
某房间正在放什么、播放状态与音量某房間正在播什麼、播放狀態與音量What a room is playing, its state and volume | |
list_favorites |
列出 Sonos 收藏夹列出 Sonos 收藏夾Lists Sonos Favorites | |
list_playlists |
列出 Sonos 播放列表列出 Sonos 播放清單Lists Sonos playlists | |
play_history |
最近向 ZoneFoundry 发出的请求（原话、时间、渠道、成功与否）；在 App 或 Sonos App 里手动播的不在其中最近向 ZoneFoundry 發出的請求（原話、時間、渠道、成功與否）；在 App 或 Sonos App 裡手動播的不在其中Recent requests made to ZoneFoundry (wording, time, channel, success); manual plays in the app or Sonos app aren't included | |
taste_profile |
这个家的收听画像：常听艺人、类型、房间、时段、语言习惯，加上请求统计這個家的收聽畫像：常聽藝人、類型、房間、時段、語言習慣，加上請求統計This home's listening profile — usual artists, genres, rooms, times, language habits — plus request stats | |
list_reminders |
列出还没播的定时提醒列出還沒播的定時提醒Lists pending spoken reminders | |
| 播放播放Playback | play_music |
搜歌或艺人并开始播放。单词查询默认播 10 首，「歌名 艺人」默认 1 首，最多 25 首搜歌或藝人並開始播放。單詞查詢預設播 10 首，「歌名 藝人」預設 1 首，最多 25 首Searches and plays. A single word plays 10 tracks by default, "title artist" plays one, 25 max |
search_music |
只搜不播，返回候选曲目（名称、艺人、专辑、时长）只搜不播，回傳候選曲目（名稱、藝人、專輯、時長）Searches without playing; returns candidates with artist, album and duration | |
toggle_play_pause |
在播就暂停，暂停就继续在播就暫停，暫停就繼續Pauses if playing, resumes if paused | |
next_track · previous_track |
下一首 / 上一首下一首 / 上一首Next / previous track | |
seek |
跳到当前曲目的第几秒跳到目前曲目的第幾秒Jumps to a position in the current track, in seconds | |
set_play_mode |
随机开或关；循环关、循环整个队列、循环当前曲隨機開或關；循環關、循環整個佇列、循環目前曲Shuffle on/off; repeat off, whole queue, or current track | |
| 音量音量Volume | set_volume |
把某个房间的音量设成 0–70把某個房間的音量設成 0–70Sets a room's volume to 0–70 |
adjust_volume |
在当前音量上加减（−30 到 +30），不用先知道现在多大在目前音量上加減（−30 到 +30），不用先知道現在多大Raises or lowers by a relative amount (−30 to +30) without knowing the current level | |
set_mute |
静音或取消静音一个房间，播放继续靜音或取消靜音一個房間，播放繼續Mutes or unmutes one room; playback keeps running | |
| 房间与分组房間與分組Rooms and groups | group_rooms |
把一个或多个房间并到主房间上，一起播同一个源把一個或多個房間並到主房間上，一起播同一個來源Joins one or more rooms onto a host so they play the same source |
ungroup_room |
把一个房间从它所在的分组里拿出来把一個房間從它所在的分組裡拿出來Takes a room out of whatever group it's in | |
move_music |
把正在播的音乐从一个房间搬到另一个：原房间停，新房间接着播把正在播的音樂從一個房間搬到另一個：原房間停，新房間接著播Moves what's playing from one room to another; the source room stops | |
| 设备与播报裝置與播報Devices and announcements | switch_source |
在音乐、电视音频、线路输入之间切换在音樂、電視音訊、線路輸入之間切換Switches between music, TV audio and line-in |
set_home_theater |
家庭影院回音壁的夜间模式与语音增强，只改你传的那几项家庭影院 soundbar 的夜間模式與語音增強，只改你傳的那幾項Night Sound and Speech Enhancement for a soundbar; only the settings you pass change | |
announce |
在某个房间用 TTS 播一段话，音乐暂停、播完自动恢复。最长 300 字，两次之间至少 8 秒在某個房間用 TTS 播一段話，音樂暫停、播完自動恢復。最長 300 字，兩次之間至少 8 秒Speaks a short message via TTS; music pauses and resumes. Up to 300 characters, at least 8 seconds apart | |
| 提醒提醒Reminders | set_reminder |
定一个一次性语音提醒：按本地时间 HH:MM，或 N 分钟后訂一個一次性語音提醒：按本地時間 HH:MM，或 N 分鐘後Schedules a one-off spoken reminder by local HH:MM or N minutes |
cancel_reminder |
取消一个还没播的提醒取消一個還沒播的提醒Cancels a pending reminder | |
| 随口说隨口說Free-form | ask_zonefoundry |
把用户的一句话原样交给 ZoneFoundry 助手去解析和执行把使用者的一句話原樣交給 ZoneFoundry 助理去解析和執行Hands the user's sentence to the ZoneFoundry assistant to parse and run |
undo_last |
撤销最近一次音量或分组改动（10 分钟内，每次改动只能撤一次）復原最近一次音量或分組改動（10 分鐘內，每次改動只能撤一次）Reverts the last volume or grouping change (within 10 minutes, once per change) |
中文版多出来的 3 个中文版多出來的 3 個The 3 extras in the Chinese catalogue
中文端点 …/mcp/zh 一共 30 个工具 = 上面 27 个 + 这 3 个。它们都是幂等的，比反复用 toggle_play_pause 稳：中文端點 …/mcp/zh 一共 30 個工具 = 上面 27 個 + 這 3 個。它們都是冪等的，比反覆用 toggle_play_pause 穩：The Chinese endpoint …/mcp/zh has 30 tools: the 27 above plus these 3. All idempotent, steadier than toggling twice:
pause—— 只暂停。已经暂停的房间保持暂停，不会被翻成播放。pause—— 只暫停。已經暫停的房間保持暫停，不會被翻成播放。pause— pauses only. An already-paused room stays paused rather than flipping to play.resume—— 只继续。已经在播的保持不变。resume—— 只繼續。已經在播的保持不變。resume— resumes only. A room already playing is left alone.pause_all—— 一次暂停全屋所有房间，不用逐个房间调。pause_all—— 一次暫停全屋所有房間，不用逐個房間調。pause_all— pauses every room at once instead of one by one.
英文端点保持 27 个不动，是为了不影响已经在用的客户端和目录收录——多出来的动作，中文那边的模型更需要。英文端點保持 27 個不動，是為了不影響已經在用的用戶端和目錄收錄——多出來的動作，中文那邊的模型更需要。The English endpoint stays at 27 so existing clients and directory listings aren't disturbed — the extra actions matter more to Chinese-language models.
我们有、官方文档没提到的我們有、官方文件沒提到的What we have that Sonos's docs don't mention
先讲清楚这条的边界：官方没公布工具表，所以「官方文档没提到」不等于「官方一定没有」。下面这些在我们的工具表里是确定存在的；在官方那边，只能说官方帮助页列举功能范围时没有提到。先講清楚這條的邊界：官方沒公布工具表，所以「官方文件沒提到」不等於「官方一定沒有」。下面這些在我們的工具表裡是確定存在的；在官方那邊，只能說官方說明頁列舉功能範圍時沒有提到。Here's the boundary: Sonos hasn't published its tool list, so "not mentioned in their docs" does not mean "they don't have it". These definitely exist on our side; on theirs, all we can say is that the support page doesn't mention them.
now_playing—— 查某个房间正在放什么。官方列的是控制类动作，没有明确写「读当前曲目」。now_playing—— 查某個房間正在播什麼。官方列的是控制類動作，沒有明確寫「讀目前曲目」。now_playing— reads what a room is playing. Sonos lists control actions; reading the current track isn't stated explicitly.announce—— TTS 播报并在播完恢复音乐。官方列的是播放与设备控制，没提语音播报。announce—— TTS 播報並在播完恢復音樂。官方列的是播放與裝置控制，沒提語音播報。announce— TTS that restores music afterwards. Sonos lists playback and device control; speech isn't mentioned.set_reminder/list_reminders/cancel_reminder—— 定时语音提醒。官方功能范围里没有这一类。set_reminder/list_reminders/cancel_reminder—— 定時語音提醒。官方功能範圍裡沒有這一類。set_reminder/list_reminders/cancel_reminder— scheduled spoken reminders; no such category appears in Sonos's stated range.play_history与taste_profile—— 请求记录与收听画像。官方列的是控制类动作，没有讲述数据。play_history與taste_profile—— 請求記錄與收聽畫像。官方列的是控制類動作，沒有講述資料。play_historyandtaste_profile— request history and a listening profile. Sonos lists control actions, not descriptions of listening.ask_zonefoundry—— 把整句话交给我们自己的助手解析，适合处理工具表覆盖不到的说法。ask_zonefoundry—— 把整句話交給我們自己的助理解析，適合處理工具表覆蓋不到的說法。ask_zonefoundry— hands a whole sentence to our assistant for phrasing the tool list doesn't cover.undo_last—— 撤销刚才那次音量或分组改动。官方功能范围里没有撤销。undo_last—— 復原剛才那次音量或分組改動。官方功能範圍裡沒有復原。undo_last— reverts the last volume or grouping change; undo isn't in Sonos's stated range.- 中文工具名与中文说明本身 —— 对中文模型来说，工具描述读得懂才选得准。中文工具名與中文說明本身 —— 對中文模型來說，工具描述讀得懂才選得準。The Chinese tool names and descriptions themselves — a model picks better from text it actually reads.
反过来，官方有一件事在文档里写了、我们的工具表里没有对应项：一个账号通过同一界面管理它的所有 Sonos 系统。我们的 27 个工具全部以房间名为入口，没有单独的家庭切换工具。如果你家里有两套独立的 Sonos 系统要分别控，这一点值得先确认。反過來，官方有一件事在文件裡寫了、我們的工具表裡沒有對應項：一個帳號透過同一介面管理它的所有 Sonos 系統。我們的 27 個工具全部以房間名為入口，沒有單獨的家庭切換工具。如果你家裡有兩套獨立的 Sonos 系統要分別控，這一點值得先確認。Going the other way, there is one thing Sonos documents that has no counterpart in our tool list: managing all of an account's Sonos systems through one interface. All 27 of our tools take a room name and none switches households. If you run two separate Sonos systems, check that before choosing.
自己验一遍自己驗一遍Verify it yourself
不用信这张表，直接问：跟接上的 AI 说「列出我的房间」。回你真实的 Sonos 房间名，就说明工具调用通了。想看得更细，可以让它「把你能用的工具列出来」——大多数客户端能读到运行时工具表，那才是你实际拿到的那一份。不用信這張表，直接問：跟接上的 AI 說「列出我的房間」。回你真實的 Sonos 房間名，就說明工具呼叫通了。想看得更細，可以讓它「把你能用的工具列出來」——大多數用戶端能讀到執行時工具表，那才是你實際拿到的那一份。Don't take the table on faith — ask the connected assistant to list your rooms. Real Sonos room names mean tool calls work. For detail, ask it to list the tools it can use: most clients can read the runtime tool list, and that is the set you actually have.
如果你接的是官方 27mcp，这一步同样有用——你能亲眼看到那 34 个到底叫什么，比读任何二手文章都准。如果你接的是官方 27mcp，這一步同樣有用——你能親眼看到那 34 個到底叫什麼，比讀任何二手文章都準。If you connected Sonos's 27mcp instead, the same step is worth doing — you'll see what those 34 are actually called, which beats any second-hand list.
常见问题常見問題FAQ
官方那 34 个工具叫什么名字？官方那 34 個工具叫什麼名字？What are Sonos's 34 tools called?
Sonos 没有公布。官方技术博客只写了「34 carefully designed tools」，帮助页只列功能范围，并明说工具名、说明和参数会随时变化、不应当成稳定 API。名字只能在连上之后用 tools/list 从运行时读出来。Sonos 沒有公布。官方技術部落格只寫了「34 carefully designed tools」，說明頁只列功能範圍，並明說工具名、說明和參數會隨時變化、不應當成穩定 API。名字只能在連上之後用 tools/list 從執行時讀出來。Sonos hasn't published them. The tech blog says only "34 carefully designed tools"; the support page gives a capability range and states that tool names, descriptions and schemas evolve without notice and aren't a stable API. You can only read them at runtime with tools/list once connected.
你们 27 个比官方 34 个少，是不是能力更弱？你們 27 個比官方 34 個少，是不是能力更弱？You have 27 versus their 34 — is that weaker?
工具个数不等于能力多少。我们的工具是按动作合并过的，例如 set_volume 与 adjust_volume 分开、分组和移动音乐各自一个工具。按 Sonos 官方帮助页写明的功能范围逐项对下来，八类能力我们都有对应工具。工具個數不等於能力多少。我們的工具是按動作合併過的，例如 set_volume 與 adjust_volume 分開、分組和移動音樂各自一個工具。按 Sonos 官方說明頁寫明的功能範圍逐項對下來，八類能力我們都有對應工具。Tool count isn't capability. Ours are consolidated by action — set_volume and adjust_volume are separate, grouping and moving music are separate tools. Checked line by line against the capability range Sonos documents, all eight areas have a matching tool.
中文版为什么多 3 个工具？中文版為什麼多 3 個工具？Why does the Chinese version have 3 extra tools?
中文端点多了 pause、resume、pause_all。这三个是幂等的：pause 只暂停，不会把已经暂停的房间变成播放。英文端点保持原样，以免影响已经在用的客户端和目录收录。中文端點多了 pause、resume、pause_all。這三個是冪等的：pause 只暫停，不會把已經暫停的房間變成播放。英文端點保持原樣，以免影響已經在用的用戶端和目錄收錄。The Chinese endpoint adds pause, resume and pause_all. They're idempotent — pause only pauses and won't flip an already-paused room to play. The English endpoint is unchanged so existing clients and directory listings aren't affected.
我怎么确认自己接上的是哪一套工具？我怎麼確認自己接上的是哪一套工具？How do I know which tool set I connected?
让 AI「列出我的房间」。接的是我们的服务器就会回你真实的 Sonos 房间名，并且能做播报、提醒这类官方文档没提到的动作；接的是官方 27mcp 就只有官方那 34 个工具能做的事。讓 AI「列出我的房間」。接的是我們的伺服器就會回你真實的 Sonos 房間名，並且能做播報、提醒這類官方文件沒提到的動作；接的是官方 27mcp 就只有官方那 34 個工具能做的事。Ask it to list your rooms. On our server you get real Sonos room names and can do things Sonos's docs don't mention, like announcements and reminders; on the official 27mcp you get only what its 34 tools allow.
工具名以后会变吗？工具名以後會變嗎？Will tool names change later?
官方明说会随时变。我们这边中文端点专有的 pause、resume、pause_all 是为了不牵动已有客户端才另开的，主工具集保持稳定；但按 MCP 的惯例，客户端还是应该以运行时读到的工具表为准。官方明說會隨時變。我們這邊中文端點專有的 pause、resume、pause_all 是為了不牽動已有用戶端才另開的，主工具集保持穩定；但按 MCP 的慣例，用戶端還是應該以執行時讀到的工具表為準。Sonos says theirs will change without notice. Our Chinese-only pause, resume and pause_all were added separately precisely so existing clients aren't disturbed, and the main tool set stays stable — but per MCP convention, clients should always trust the runtime tool list.