mcp-mpv-player 1.0.2 → 1.0.3

package/README.md

@@ -1,106 +1,84 @@
-# mpv-mcp
+# mcp-mpv-player
 
-MCP server for controlling **mpv media player** on Windows via opencode (or any MCP client).
+[中文文档](./README.zh.md)
 
-## Features
+Control mpv media player through AI conversation. Play music and video, manage playlists — all via natural language.
 
-| Tool | Description |
-|------|-------------|
-| `player_play` | Open file or URL (auto-starts mpv) |
-| `player_pause` | Toggle pause/resume |
-| `player_stop` | Stop playback |
-| `player_next` | Next track |
-| `player_prev` | Previous track |
-| `player_seek` | Seek by seconds / absolute time / percent |
-| `player_set_volume` | Set volume 0–130 |
-| `player_set_speed` | Set speed (0.5x, 1x, 2x…) |
-| `player_status` | Get current playback state |
-| `playlist_create` | Create a new .m3u playlist |
-| `playlist_add` | Append files to a playlist |
-| `playlist_remove` | Remove an item by index |
-| `playlist_load` | Load & play a saved playlist |
-| `playlist_list` | List all playlists or inspect one |
-| `playlist_delete` | Delete a playlist file |
-
-Playlists are saved as `.m3u` files in `%USERPROFILE%\mpv-playlists\`.
-
----
-
-## Requirements
-
-- **Node.js** 18+
-- **mpv** installed and in PATH  
-  Download: https://mpv.io/installation/  
-  Recommended: `winget install mpv` or `scoop install mpv`
-
----
+Works with [opencode](https://opencode.ai/) and any MCP-compatible AI tool.
 
 ## Installation
 
+Make sure [Node.js](https://nodejs.org) is installed, then run:
+
 ```bash
-cd mpv-mcp
-npm install
+npx mcp-mpv-player
 ```
 
----
+The setup wizard will automatically:
+- Detect or install mpv
+- Locate your opencode config file
+- Register the MCP tool
 
-## opencode Configuration
+Restart opencode when done.
 
-Add this to your opencode config (`~/.config/opencode/config.json` or similar):
+## Usage Examples
 
-```json
-{
-  "mcpServers": {
-    "mpv": {
-      "command": "node",
-      "args": ["C:/path/to/mpv-mcp/index.js"]
-    }
-  }
-}
+Just talk to your AI naturally:
+
+```
+Play D:/Music/song.mp3
+Pause
+Next track
+Skip forward 30 seconds
+Jump to 2 minutes 30 seconds
+Set volume to 80
+Create a playlist called "chill" with D:/Music/a.mp3 and D:/Music/b.mp3
+Play the "chill" playlist
+Shuffle
 ```
 
-> **Tip:** If mpv is not in PATH, add an env var:
-> ```json
-> {
->   "mcpServers": {
->     "mpv": {
->       "command": "node",
->       "args": ["C:/path/to/mpv-mcp/index.js"],
->       "env": {
->         "MPV_PATH": "C:/tools/mpv/mpv.exe"
->       }
->     }
->   }
-> }
-> ```
-
----
+## Tools
 
-## How It Works
+### Playback Control
 
-mpv exposes a **JSON IPC** interface via a Windows Named Pipe (`\\.\pipe\mpv-ipc`).
+| Tool | Description |
+|------|-------------|
+| `player_play` | Play a file or URL, auto-starts mpv |
+| `player_pause` | Toggle pause / resume |
+| `player_stop` | Stop playback |
+| `player_next` | Next track |
+| `player_prev` | Previous track |
+| `player_seek` | Seek by seconds / absolute time / percent |
+| `player_set_volume` | Set volume (0–130) |
+| `player_set_speed` | Set playback speed (0.5x / 1x / 2x …) |
+| `player_status` | Get current playback status |
+| `player_shuffle` | Shuffle playlist and play from the start |
 
-- If mpv is **not running** when you call `player_play`, the server auto-launches it with `--idle --keep-open` so it stays open between tracks.
-- All other tools check the pipe first and return a helpful error if mpv isn't running.
-- Playlist files are plain `.m3u` text files — you can edit them manually too.
+### Playlist Management
 
----
+| Tool | Description |
+|------|-------------|
+| `playlist_create` | Create a new playlist |
+| `playlist_load` | Load and play a saved playlist |
+| `playlist_add` | Add files to a playlist |
+| `playlist_remove` | Remove a track from a playlist |
+| `playlist_list` | List all playlists or inspect one |
+| `playlist_delete` | Delete a playlist |
 
-## Usage Examples (via opencode)
+Playlists are saved as `.m3u` files in `%USERPROFILE%\mpv-playlists\`.
 
-```
-播放一个文件:
-  "播放 D:/Music/song.mp3"
+## Requirements
 
-快进30秒:
-  "快进30秒"  →  player_seek(30, relative)
+- Windows 10 / 11
+- Node.js 18+
+- mpv (can be installed automatically by the setup wizard)
 
-跳到第2分30秒:
-  "跳到2分30秒"  →  player_seek(150, absolute)
+## How It Works
 
-创建播放列表:
-  "创建一个叫 jazz 的播放列表，包含 D:/Music/a.mp3 和 D:/Music/b.mp3"
+mpv exposes a JSON IPC interface via a Windows Named Pipe (`\\.\pipe\mpv-ipc`). This tool runs as an MCP server, receives commands from the AI, and forwards them to mpv.
 
-加载并播放播放列表:
-  "播放 jazz 播放列表"
-```
+When `player_play` is called and mpv is not running, it is launched automatically with the IPC flag and stays running in the background between tracks.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,84 @@
+# mcp-mpv-player
+
+[English](./README.md)
+
+通过 AI 对话控制 mpv 播放器，支持播放音乐、视频，管理播放列表。
+
+适用于 [opencode](https://opencode.ai/) 等支持 MCP 协议的 AI 编程工具。
+
+## 安装
+
+确保电脑上已安装 [Node.js](https://nodejs.org)，然后运行：
+
+```bash
+npx mcp-mpv-player
+```
+
+安装向导会自动完成以下步骤：
+- 检测或安装 mpv 播放器
+- 找到 opencode 配置文件
+- 自动注册 MCP 工具
+
+完成后重启 opencode 即可使用。
+
+## 使用示例
+
+安装完成后，直接用自然语言对 AI 说：
+
+```
+播放 D:/Music/周杰伦 - 晴天.mp3
+暂停
+下一曲
+快进30秒
+跳到第2分30秒
+音量调到80
+创建一个叫 "周末" 的播放列表，包含 D:/Music/a.mp3 和 D:/Music/b.mp3
+播放 "周末" 播放列表
+随机播放
+```
+
+## 功能列表
+
+### 播放控制
+
+| 工具 | 说明 |
+|------|------|
+| `player_play` | 播放文件或 URL，自动启动 mpv |
+| `player_pause` | 暂停 / 继续 |
+| `player_stop` | 停止播放 |
+| `player_next` | 下一曲 |
+| `player_prev` | 上一曲 |
+| `player_seek` | 快进快退 / 跳到指定时间 / 按百分比跳转 |
+| `player_set_volume` | 设置音量（0–130） |
+| `player_set_speed` | 设置播放速度（0.5x / 1x / 2x …） |
+| `player_status` | 查看当前播放状态 |
+| `player_shuffle` | 随机打乱播放列表并播放 |
+
+### 播放列表管理
+
+| 工具 | 说明 |
+|------|------|
+| `playlist_create` | 创建新播放列表 |
+| `playlist_load` | 加载并播放已保存的播放列表 |
+| `playlist_add` | 向播放列表添加文件 |
+| `playlist_remove` | 从播放列表移除指定曲目 |
+| `playlist_list` | 查看所有播放列表或列表内容 |
+| `playlist_delete` | 删除播放列表 |
+
+播放列表以 `.m3u` 格式保存在 `%USERPROFILE%\mpv-playlists\`。
+
+## 系统要求
+
+- Windows 10 / 11
+- Node.js 18+
+- mpv（安装向导可自动安装）
+
+## 工作原理
+
+mpv 提供了 JSON IPC 接口，通过 Windows Named Pipe（`\\.\pipe\mpv-ipc`）通信。本工具作为 MCP server 运行，接收 AI 发来的指令并转发给 mpv 执行。
+
+调用 `player_play` 时如果 mpv 未运行，会自动启动并附带 IPC 参数，之后保持后台运行。
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-mpv-player",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "MCP server for controlling mpv media player on Windows",
   "type": "module",
   "main": "index.js",
@@ -22,5 +22,13 @@
     "media-player",
     "opencode"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/guodaxia9527/mcp-mpv-player"
+  },
+  "homepage": "https://github.com/guodaxia9527/mcp-mpv-player#readme",
+  "bugs": {
+    "url": "https://github.com/guodaxia9527/mcp-mpv-player/issues"
+  }
 }