Streamersonglist MCP

🚀 StreamerSongList MCP 服務器

這是一個符合模型上下文協議（MCP）的服務器，它提供了與 StreamerSongList API 交互的工具。該服務器使像 Claude 這樣的 AI 助手能夠管理歌曲請求、監控隊列，並與流媒體平臺的歌曲請求系統進行交互。

🚀 快速開始

前提條件

• Node.js（版本 18 或更高）
• Claude Desktop 或其他兼容 MCP 的客戶端

安裝

選項 1：使用 npx（推薦）

無需安裝！只需將 Claude Desktop 配置為使用以下內容：

{
  "mcpServers": {
    "streamersonglist": {
      "command": "npx",
      "args": ["streamersonglist-mcp"]
    }
  }
}

選項 2：本地安裝

1. 克隆此倉庫：

git clone https://github.com/vuvuvu/streamersonglist-mcp.git
cd streamersonglist-mcp

2. 安裝依賴項：

npm install

3. 測試服務器：

npm test

通過 Smithery 安裝

要通過 Smithery 自動為 Claude Desktop 安裝 streamersonglist-mcp，請執行以下命令：

npx -y @smithery/cli install @vuvuvu/streamersonglist-mcp --client claude

與 Claude Desktop 一起使用

快速設置（npx 方法）

1. 找到你的 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 將服務器添加到你的配置中：

{
  "mcpServers": {
    "streamersonglist": {
      "command": "npx",
      "args": ["streamersonglist-mcp"]
    }
  }
}

3. 重啟 Claude Desktop

4. 進行測試： 詢問 Claude："使用 getStreamerByName 工具獲取某個熱門主播的信息"

替代方法：本地安裝方法

如果你更喜歡從本地克隆運行，可以使用以下配置：

{
  "mcpServers": {
    "streamersonglist": {
      "command": "node",
      "args": ["src/server.js"],
      "cwd": "/path/to/streamersonglist-mcp"
    }
  }
}

✨ 主要特性

🎵 11 種可用工具

核心隊列管理

• getStreamerByName：獲取特定主播的詳細信息
• getQueue：查看當前歌曲隊列，支持分頁
• getQueueStats：獲取歌曲隊列的綜合統計信息，包括歌曲總數、時長和熱門曲目
• manageSongRequest：創建、更新和刪除歌曲請求
• monitorQueue：以可配置的輪詢間隔監控隊列變化

播放歷史和歌曲數據庫

• getPlayHistory：檢索播放歷史，支持過濾和分頁
• searchSongs：使用各種過濾器搜索歌曲數據庫
• getSongDetails：獲取特定歌曲的詳細信息
• manageSongAttributes：添加、更新或刪除歌曲屬性，如標籤和評分

疊加層和分析

• getOverlayData：獲取流媒體軟件的實時疊加層數據
• getStreamStats：獲取全面的流媒體統計信息和分析數據

🔧 技術特性

• 符合 MCP 協議：可與 Claude Desktop、OpenAI 代理和其他 MCP 客戶端配合使用
• 類型安全：具備全面的輸入驗證
• 錯誤處理：強大的錯誤處理和用戶友好的錯誤消息
• 無需身份驗證：簡化設置，無需複雜的身份驗證
  • 更新：由於添加了其他 API 端點，這些端點將需要身份驗證（我沒有使用它們的需求，所以由你自己來解決），否則將返回 404 響應

💻 使用示例

基礎用法

以下是使用 getStreamerByName 工具的示例：

Use getStreamerByName with streamerName "belleune"

高級用法

以下是使用 manageSongRequest 工具創建新請求的示例：

Use manageSongRequest to create a new request:
- action: "create"
- streamerName: "belleune"
- songTitle: "Bohemian Rhapsody"
- artist: "Queen"
- requesterName: "ChatUser123"

📚 詳細文檔

getStreamerByName

獲取特定主播的詳細信息。

參數：

• streamerName（字符串，必需）：主播的名稱

示例：

Use getStreamerByName with streamerName "belleune"

getQueue

查看當前歌曲隊列，支持分頁。

參數：

• streamerName（字符串，必需）：要獲取其隊列的主播名稱
• limit（數字，可選）：返回的最大歌曲數量（默認值：50）
• offset（數字，可選）：分頁時要跳過的歌曲數量（默認值：0）

示例：

Use getQueue with streamerName "belleune" and limit 10

getQueueStats

獲取歌曲隊列的綜合統計信息。

參數：

• streamerName（字符串，必需）：要獲取其隊列統計信息的主播名稱

示例：

Use getQueueStats with streamerName "belleune"

manageSongRequest

創建、更新和刪除歌曲請求。

參數：

• action（字符串，必需）：要執行的操作（"create"、"update" 或 "delete"）
• streamerName（字符串，必需）：主播的名稱
• requestId（字符串，可選）：請求的 ID（更新/刪除時必需）
• songTitle（字符串，可選）：歌曲的標題（創建/更新時必需）
• artist（字符串，可選）：藝術家的名稱
• requesterName（字符串，可選）：請求者的名稱
• message（字符串，可選）：請求附帶的可選消息

示例：

Use manageSongRequest to create a new request:
- action: "create"
- streamerName: "belleune"
- songTitle: "Bohemian Rhapsody"
- artist: "Queen"
- requesterName: "ChatUser123"

monitorQueue

以可配置的輪詢間隔監控隊列變化。

參數：

• streamerName（字符串，必需）：要監控其隊列的主播名稱
• interval（數字，可選）：輪詢間隔（秒）（默認值：30）
• duration（數字，可選）：監控的時長（秒）（默認值：300）

示例：

Use monitorQueue with streamerName "belleune", interval 60, duration 600

getPlayHistory

檢索播放歷史，支持過濾和分頁。

參數：

• streamerName（字符串，必需）：要獲取其播放歷史的主播名稱
• limit（數字，可選）：返回的最大條目數（默認值：50）
• offset（數字，可選）：分頁時要跳過的條目數（默認值：0）
• startDate（字符串，可選）：開始日期過濾器（ISO 格式）
• endDate（字符串，可選）：結束日期過濾器（ISO 格式）

示例：

Use getPlayHistory with streamerName "belleune", limit 20, startDate "2024-01-01"

searchSongs

使用各種過濾器搜索歌曲數據庫。

參數：

• query（字符串，可選）：歌曲標題或藝術家的搜索查詢
• artist（字符串，可選）：按特定藝術家過濾
• genre（字符串，可選）：按音樂流派過濾
• limit（數字，可選）：返回的最大結果數（默認值：50）
• offset（數字，可選）：要跳過的結果數（默認值：0）

示例：

Use searchSongs with query "bohemian", artist "Queen", limit 10

getSongDetails

獲取特定歌曲的詳細信息。

參數：

• songId（字符串，必需）：歌曲的唯一標識符

示例：

Use getSongDetails with songId "song_12345"

getOverlayData

獲取流媒體軟件的實時疊加層數據。

參數：

• streamerName（字符串，必需）：主播的名稱
• overlayType（字符串，可選）：疊加層數據的類型（"current"、"queue"、"stats"）

示例：

Use getOverlayData with streamerName "belleune", overlayType "current"

getStreamStats

獲取全面的流媒體統計信息和分析數據。

參數：

• streamerName（字符串，必需）：主播的名稱
• period（字符串，可選）：統計的時間段（"day"、"week"、"month"、"year"）
• startDate（字符串，可選）：自定義時間段的開始日期（ISO 格式）
• endDate（字符串，可選）：自定義時間段的結束日期（ISO 格式）

示例：

Use getStreamStats with streamerName "belleune", period "week"

manageSongAttributes

添加、更新或刪除歌曲屬性，如標籤和評分。

參數：

• action（字符串，必需）：要執行的操作（"add"、"update"、"remove"）
• songId（字符串，必需）：歌曲的唯一標識符
• attributeType（字符串，必需）：屬性的類型（"tag"、"rating"、"note"）
• value（字符串，可選）：屬性的值（添加/更新時必需）

示例：

Use manageSongAttributes with action "add", songId "song_12345", attributeType "tag", value "rock"

🔧 技術細節

項目結構

streamersonglist-mcp/
├── src/
│   └── server.js          # 主要的 MCP 服務器實現
├── package.json           # Node.js 依賴項和腳本
├── test-server.js         # 測試腳本
└── README.md             # 本文件

測試

運行測試腳本以驗證服務器是否正常工作：

npm test

這將：

• 啟動 MCP 服務器
• 發送測試請求
• 驗證服務器是否以正確的工具進行響應

手動測試

你也可以手動測試服務器：

npm start

服務器將啟動並等待標準輸入上的 MCP 協議消息。你可以發送以下測試消息：

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

貢獻指南

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 如有必要，添加測試
5. 提交拉取請求

更新日誌

v1.1.0

• 新增：添加了 6 個額外的 StreamerSongList API 端點
• 新增：支持過濾的播放歷史檢索功能（getPlayHistory）
• 新增：歌曲數據庫搜索功能（searchSongs）
• 新增：訪問詳細歌曲信息的功能（getSongDetails）
• 新增：流媒體軟件的實時疊加層數據（getOverlayData）
• 新增：全面的流媒體分析功能（getStreamStats）
• 新增：歌曲屬性管理系統（manageSongAttributes）
• 工具總數從 5 個增加到 11 個，增強了 API 覆蓋範圍
• 改進文檔，增加了工具分類部分
• 擴展 API 端點覆蓋範圍，實現了與 StreamerSongList 的全面集成

v1.0.0

• 初始版本發佈
• 實現了 5 個核心 StreamerSongList 工具
• 符合 MCP 協議
• 集成 Claude Desktop
• 具備全面的錯誤處理功能