{"$schema":"https://wellknown.network/schemas/agent-record-v1.json","schemaVersion":"1","id":"ag_txfxp3jg93yd","handle":"play-music-mcp","url":"https://wellknown.network/agents/play-music-mcp","links":{"self":"https://wellknown.network/agents/play-music-mcp/record.json","html":"https://wellknown.network/agents/play-music-mcp","markdown":"https://wellknown.network/agents/play-music-mcp/record.md","api":"https://wellknown.network/api/v1/agents/play-music-mcp","status":"https://wellknown.network/api/v1/agents/play-music-mcp/status","claim":"https://wellknown.network/agents/play-music-mcp/claim","claimApi":"https://wellknown.network/api/v1/claims","claimDescriptor":"https://wellknown.network/agents/play-music-mcp/claim.json","badge":"https://wellknown.network/agents/play-music-mcp/badge.svg","openapi":"https://wellknown.network/openapi.json","history":"https://wellknown.network/api/v1/agents/play-music-mcp/history","tools":"https://wellknown.network/api/v1/agents/play-music-mcp/tools"},"ard":{"identifier":"urn:air::server:play-music-mcp","type":"application/mcp-server-card+json"},"kind":"mcp_server","declared":{"name":"play-music-mcp","summary":"Local music playback MCP server powered by pygame and FastMCP.","description":"# play-music-mcp\n\n一个基于 [FastMCP](https://github.com/modelcontextprotocol/fastmcp) 和 `pygame` 的本地音乐播放 Model Context Protocol (MCP) 服务器。通过 MCP 工具可以管理播放列表、播放/暂停/上一首/下一首等控制动作，并提供音乐文件维护工具，适合在 Copilot / Claude Desktop 等遵循 MCP 标准的客户端中使用。\n\n## 功能特性\n- 异步 MCP 工具：播放、暂停、恢复、停止、上一首、下一首、查看播放列表、列出本地音乐文件等。\n- 后台播放线程：使用 `pygame.mixer` 长时间保持播放状态，支持单曲循环、列表循环、随机播放三种模式。\n- 自动扫描 `music_file/` 目录，将匹配到的音频文件加载到播放列表。\n- 标准输出 (STDIO) 传输：与大多数 MCP 客户端兼容，部署简单。\n\n## 安装\n```bash\npip install play-music-mcp\n```\n或在本地源码目录下构建并安装：\n```bash\ncd 音乐\npython -m build\npip install dist/play_music_mcp-*.whl\n```\n\n## 运行方式\n包中提供了一个 `play-music-mcp` 控制台脚本，或直接运行模块：\n```bash\nplay-music-mcp --music-dir /absolute/path/to/music_dir\n# 等价于\npython -m play_music --music-dir /absolute/path/to/music_dir\n```\n通过 `--music-dir` 参数指定存放 `.mp3/.wav` 等文件的目录；若未提供，则默认使用当前工作目录下的 `music_file/`。服务器启动后会在 STDIO 上传输 MCP 消息，可直接由支持 MCP 的客户端托管。\n\n## MCP 工具列表\n| 工具名 | 说明 |\n| --- | --- |\n| `play_musics_local` | 扫描 `music_file/` 并按设定模式播放（single/list/random）。 |\n| `pause_music` / `unpause_music` | 暂停或恢复当前曲目。 |\n| `stop_music` | 停止播放并重置内部状态。 |\n| `next_song` / `previous_song` | 在当前播放列表内切歌。 |\n| `get_playlist` | 返回当前播放列表及正在播放的歌曲。 |\n| `list_music_files` | 新增工具，列出目录下可用的音频文件，便于先行确认。 |\n\n## 开发说明\n1. 确保本地已安装 `SDL`/`pygame` 所需的系统依赖。\n2. 在 `music_file/` 文件夹中放置 `.mp3/.wav/.ogg` 文件。\n3. 运行 `play-music-mcp`，并在 MCP 客户端侧配置好服务器（STDIO 传输无需额外参数）。\n4. 若要发布到 PyPI：\n   - 更新 `pyproject.toml` 中的版本号与项目信息。\n   - 运行 `python -m build` 生成分发包。\n   - 使用 `twine upload dist/*` 上传。\n\n## 许可证\n本项目使用 MIT License，详见 `LICENSE` 文件。","publisher":{"name":"MCP Contributors","url":null},"homepage":"https://github.com/yourname/play-music-mcp","repository":"https://github.com/yourname/play-music-mcp","version":"0.1.1","license":"MIT License\n        \n        Copyright (c) 2024 MCP Contributor…","protocols":["mcp"],"tags":["mcp","music","pygame","automation","agent"],"pricing":null,"endpoints":[{"url":"pypi:play-music-mcp","type":"package_pypi","auth":null,"probeable":false}],"skills":null,"tools":null,"extra":null,"attribution":{"kind":"pypi","name":"pypi","license":"pypi","repoUrl":"pypi","summary":"pypi","version":"pypi","description":"pypi","homepageUrl":"pypi","publisherName":"pypi"}},"derived":{"capabilities":[{"slug":"media.music","name":"Music & Audio","confidence":1,"provenance":"declared"}],"categories":["media"],"language":"en"},"observed":{"status":"unknown","statusReason":"Distributed as a package to run locally; no network endpoint to check.","lastOkAt":null,"lastProbedAt":null,"statusComputedAt":null,"reliability30d":null,"latestObservations":[],"tools":null,"package":{"name":"play-music-mcp","registry":"pypi","observedAt":"2026-11-03T22:25:28.999Z","publishedAt":"2025-11-20T09:14:37.568085Z","latestVersion":"0.1.1"},"toolSurface":null,"endpointFacts":[]},"verification":{"claimed":false,"claimedAt":null,"proofs":[]},"provenance":{"sources":[{"source":"pypi","key":"play-music-mcp","url":"https://pypi.org/project/play-music-mcp/","firstSeenAt":"2026-09-10T10:23:12.083Z","fetchedAt":"2026-11-03T22:23:35.069Z","normalizedAt":"2026-11-03T22:23:35.069Z"}]},"firstSeenAt":"2026-09-10T10:23:12.083Z","updatedAt":"2026-11-03T22:25:28.999Z"}