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
• 具备全面的错误处理功能