概述

tidal-cli 是一个开源的命令行工具，允许用户通过终端与 Tidal 音乐流媒体服务进行交互。该工具由 Node.js 构建，支持搜索、播放列表管理、音乐库控制等功能，专为个人使用和 LLM 代理自动化设计。

核心特点：

• 支持搜索艺术家、专辑、曲目、视频和播放列表
• 完整的播放列表管理功能
• 音乐播放控制
• 发现和推荐功能
• JSON 输出支持，便于脚本和自动化
• MCP Server 集成，可与 Claude Desktop 等 AI 代理配合使用

资料来源：site/app/terms/page.tsx:28-31

1. 整体架构概览

tidal-cli 项目包含三个主要组件：

资料来源：site/app/page.tsx:1-50

graph TB
    subgraph 用户端
        CLI[tidal-cli CLI]
    end
    
    subgraph 云端服务
        MCP[MCP Server<br/>tidal-cli.lucaperret.ch/api/mcp]
        Web[Web Frontend<br/>tidal-cli.lucaperret.ch]
    end
    
    subgraph 第三方服务
        TidalAPI[Tidal API<br/>openapi.tidal.com]
        TidalAuth[Tidal Auth<br/>login.tidal.com<br/>auth.tidal.com]
        Upstash[Upstash Redis<br/>Token 存储]
    end
    
    CLI --> TidalAPI
    CLI --> TidalAuth
    MCP --> TidalAPI
    MCP --> TidalAuth
    MCP --> Upstash
    Web --> MCP

2. CLI 工具架构

2.1 安装与入口

CLI 工具通过 npm 全局安装：

npm install -g @lucaperret/tidal-cli

安装后可通过 tidal-cli 命令调用，支持全局参数 --json 输出 JSON 格式结果。

资料来源：README.md:1-30

2.2 命令模块

CLI 工具按功能划分为以下命令模块：

资料来源：README.md:50-120

3. MCP 服务器架构

3.1 连接配置

MCP 服务器作为远程连接器运行于 https://tidal-cli.lucaperret.ch/api/mcp，可与 Claude Desktop 或 claude.ai 集成。

资料来源：site/app/page.tsx:15-25

graph LR
    A[Claude Desktop<br/>或 claude.ai] -->|MCP Protocol| B[MCP Connector]
    B --> C[Tidal API]
    B --> D[Upstash Redis<br/>Token 存储]

3.2 可用工具

MCP 服务器提供约 40 个工具，涵盖以下功能类别：

• 搜索（Search）
• 播放列表管理（Playlists）
• 音乐库访问（Library）
• 推荐服务（Recommendations）
• 稍后播放（Save-for-later）
• 分享功能（Sharing）

资料来源：site/app/page.tsx:45-55

3.3 认证流程

MCP 服务器模式下的认证流程：

1. 用户通过 OAuth 连接 Tidal 账户
2. 认证令牌存储于 Upstash Redis 数据库（加密存储）
3. MCP 服务器使用存储的令牌访问 Tidal API

资料来源：site/app/privacy/page.tsx:60-80

4. Web 前端架构

4.1 技术栈

Web 前端基于 Next.js 构建，包含以下页面：

资料来源：site/app/page.tsx:1-30 资料来源：site/app/privacy/page.tsx:1-30 资料来源：site/app/terms/page.tsx:1-30

4.2 组件结构

graph TD
    Layout[layout.tsx<br/>根布局] --> Nav[Nav.tsx<br/>导航栏]
    Layout --> Page[page.tsx<br/>主页内容]
    Page --> Terminal[Terminal.tsx<br/>终端模拟组件]
    Page --> Footer[页脚]

Web 前端主要使用 Framer Motion 实现动画效果，采用 Tidal 品牌配色方案。

资料来源：site/app/components/Terminal.tsx:1-30 资料来源：site/app/components/Nav.tsx:1-20

5. 认证与数据存储

5.1 CLI 模式下的数据存储

在命令行模式下使用时，认证令牌存储在用户本地：

~/.tidal-cli/session.json

资料来源：site/app/privacy/page.tsx:45-55

5.2 MCP 模式下的数据存储

资料来源：site/app/privacy/page.tsx:65-75

5.3 OAuth 流程

tidal-cli 使用 OAuth 2.0 与 Tidal 进行认证集权，支持以下端点：

资料来源：site/app/privacy/page.tsx:85-100

6. 数据流

6.1 CLI 命令执行流程

sequenceDiagram
    participant User
    participant CLI
    participant TidalAuth
    participant TidalAPI
    
    User->>CLI: tidal-cli search track "Teardrop"
    CLI->>TidalAuth: 验证本地 token
    alt Token 有效
        CLI->>TidalAPI: 搜索请求
        TidalAPI-->>CLI: 搜索结果
        CLI-->>User: 显示结果
    else Token 无效或过期
        CLI->>TidalAuth: 发起 OAuth 流程
        TidalAuth-->>User: 浏览器授权
        User->>TidalAuth: 确认授权
        TidalAuth-->>CLI: 新 token
        CLI->>TidalAPI: 搜索请求
        TidalAPI-->>CLI: 搜索结果
        CLI-->>User: 显示结果
    end

6.2 MCP 集成流程

sequenceDiagram
    participant User
    participant Claude
    participant MCP
    participant Redis
    participant TidalAPI
    
    User->>Claude: 请求查询音乐
    Claude->>MCP: 调用搜索工具
    MCP->>Redis: 获取认证令牌
    Redis-->>MCP: Token
    MCP->>TidalAPI: API 请求
    TidalAPI-->>MCP: 音乐数据
    MCP-->>Claude: 工具响应
    Claude-->>User: 自然语言回复

7. 服务部署

7.1 部署平台

7.2 可用集成平台

tidal-cli MCP 连接器可在多个平台使用：

• Claude Desktop / claude.ai（主要）
• Smithery AI
• ClawHub

资料来源：site/app/page.tsx:35-45

8. 安全与隐私

8.1 数据收集政策

tidal-cli 本身不收集、存储或传输任何个人数据到第三方服务器。所有用户数据均直接与 Tidal 服务器交互。

资料来源：site/app/privacy/page.tsx:35-45

8.2 数据删除

资料来源：site/app/privacy/page.tsx:130-145

9. 开源许可

tidal-cli 采用 MIT 许可证开源，源代码托管于 GitHub：

• 仓库地址：github.com/lucaperret/tidal-cli
• 许可证：MIT License

资料来源：site/app/terms/page.tsx:110-130

10. 系统要求

资料来源：README.md:25-30

功能概述

搜索与浏览模块是 tidal-cli 的核心功能之一，提供了对 Tidal 音乐目录的全面访问能力。用户可以通过结构化的命令查询各类媒体资源，并获取详细的元数据信息。

核心能力

该模块支持以下主要功能领域：

• 搜索功能：按类型搜索艺术家、专辑、曲目、视频、播放列表
• 艺术家浏览：获取艺术家信息、热门曲目、专辑列表、相似推荐
• 专辑浏览：查看专辑详情、曲目列表、条形码查询
• 曲目浏览：获取曲目信息、ISRC 识别、相似推荐
• 用户历史：查看和管理搜索历史、播放历史

搜索功能详解

搜索命令结构

tidal-cli 的搜索功能采用统一的命令格式，支持多种内容类型的搜索。

tidal-cli search <类型> <查询词>

支持的搜索类型

搜索历史管理

系统会记录用户的搜索历史，并提供管理功能：

tidal-cli search history                          # 查看搜索历史
tidal-cli search history-delete <entry-id>         # 删除单条历史记录
tidal-cli search history-clear                    # 清空所有历史记录

资料来源：README.md

艺术家浏览

艺术家模块提供对艺术家完整信息的访问能力。

可用命令

数据获取流程

graph TD
    A[输入 artist 命令] --> B[解析命令参数]
    B --> C[调用 Tidal API]
    C --> D{查询类型}
    D -->|info| E[获取艺术家详情]
    D -->|tracks| F[获取热门曲目]
    D -->|albums| G[获取专辑列表]
    D -->|similar| H[获取相似艺术家]
    D -->|radio| I[生成艺术家电台]
    E --> J[格式化输出]
    F --> J
    G --> J
    H --> J
    I --> J

专辑浏览

专辑模块支持专辑信息和曲目列表的查询。

可用命令

专辑信息内容

专辑信息通常包含以下内容：

• 专辑标题和艺术家名称
• 发行日期
• 曲目数量
• 专辑封面
• 音频质量信息

曲目浏览

曲目模块提供曲目级别的详细信息和元数据。

可用命令

ISRC 查询功能

ISRC（国际标准录音代码）是曲目的唯一标识符，支持精确的曲目识别：

tidal-cli track isrc <isrc>

此功能允许用户通过已知的 ISRC 码快速定位特定曲目，适用于从其他来源获取的曲目元数据。

资料来源：README.md

发现与推荐

推荐功能

tidal-cli 提供个性化推荐功能，支持多种推荐类型：

tidal-cli recommend                              # 获取所有推荐分类
tidal-cli recommend --type daily                 # 每日推荐
tidal-cli recommend --type discovery             # 发现推荐
tidal-cli recommend --type new-release           # 新发行
tidal-cli recommend --type offline               # 离线推荐

Mix 内容

获取 Mix 详情：

tidal-cli mix items <mix-id> --type daily

支持的 Mix 类型包括 daily、discovery、new-release、offline。

用户历史

查看个人使用历史：

tidal-cli history tracks     # 播放过的曲目
tidal-cli history albums     # 播放过的专辑
tidal-cli history artists    # 播放过的艺术家

用户资料

获取当前登录用户的信息：

tidal-cli user profile

此命令返回用户账户的详细信息，包括订阅状态、用户 ID 等。

资料来源：README.md

JSON 输出

所有搜索和浏览命令支持 JSON 格式输出，便于程序化处理和脚本集成。

使用方式

在命令前添加 --json 标志：

tidal-cli --json search track "Around the World"
tidal-cli --json playlist list
tidal-cli --json artist similar 8992

输出格式

JSON 输出包含完整的 API 响应数据，结构化呈现所有可用字段。

命令索引表

搜索命令

浏览命令

发现命令

技术架构

模块组织

搜索与浏览功能分布在以下核心模块中：

• src/search.ts：搜索命令实现，支持多种类型的搜索查询
• src/artist.ts：艺术家相关功能，包括信息、曲目、专辑、相似推荐
• src/album.ts：专辑浏览和条形码查询功能
• src/track.ts：曲目查询、ISRC 识别、相似曲目
• src/user.ts：用户资料和历史记录管理

API 交互

所有搜索和浏览功能通过 Tidal API 进行数据获取，命令行工具负责：

1. 解析用户输入的命令和参数
2. 调用相应的 Tidal API 端点
3. 格式化并输出返回的数据
4. 支持 JSON 和人类可读两种输出格式

最佳实践

高效搜索

• 使用精确的曲目名称可获得更准确的结果
• 搜索专辑时使用完整的专辑名称
• ISRC 查询是定位精确曲目的最可靠方式

结果处理

• 使用 --json 标志便于程序化处理
• 结合 shell 管道处理大规模数据
• 利用播放历史功能追踪音乐偏好

错误处理

• 确保 Tidal 账户已通过 tidal-cli auth 认证
• 检查网络连接状况
• 确认 API 配额未超限

功能概述

播放列表管理模块的核心职责包括：

• 列表查询：查看用户所有播放列表及其基本信息
• 创建与删除：新建播放列表或删除已有列表
• 曲目管理：向播放列表添加或移除曲目
• 编辑操作：重命名播放列表
• 分享功能：生成可公开访问的分享链接

资料来源：README.md

命令行接口

播放列表查询

播放列表操作

曲目管理

资料来源：README.md

JSON 输出支持

所有播放列表命令均支持 --json 参数，可直接用于程序化处理：

tidal-cli --json playlist list
tidal-cli --json playlist info <playlist-id>

JSON 输出格式示例：

[{
  "id": "a20fff4a-...",
  "name": "Late Night Electronic",
  "numberOfItems": 24,
  "createdAt": "2025-04-20T..."
}, ...]

资料来源：site/app/page.tsx

使用流程图

graph TD
    A[开始] --> B{选择操作}
    B -->|查看列表| C[playlist list]
    B -->|创建列表| D[playlist create]
    B -->|管理曲目| E[playlist add/remove]
    B -->|其他操作| F[info/rename/delete/share]
    
    C --> G[显示播放列表]
    D --> H[输入列表名称]
    H --> I[创建成功]
    E --> J[输入播放列表ID和曲目ID]
    J --> K[操作完成]
    F --> L[执行相应操作]
    
    G --> M[结束]
    I --> M
    K --> M
    L --> M

典型使用场景

创建并填充播放列表

# 1. 创建新播放列表
tidal-cli playlist create "My Favorites"

# 2. 搜索曲目获取ID
tidal-cli search track "Teardrop"

# 3. 添加曲目到播放列表
tidal-cli playlist add <playlist-id> --track-id <track-id>

查看和管理已有列表

# 查看所有播放列表
tidal-cli playlist list

# 查看特定列表详情
tidal-cli playlist info <playlist-id>

# 重命名列表
tidal-cli playlist rename <playlist-id> --name "New Name"

# 移除不需要的曲目
tidal-cli playlist remove <playlist-id> --track-id <track-id>

数据存储

tidal-cli 将用户认证信息和会话数据存储在本地 ~/.tidal-cli 目录中。播放列表数据通过 Tidal API 实时获取，不在本地缓存。

如需清除所有本地数据（包括播放列表相关的认证信息）：

rm -rf ~/.tidal-cli

资料来源：site/app/privacy/page.tsx

与 MCP 集成

播放列表管理功能可通过 MCP（Model Context Protocol）协议供 AI 代理调用：

tidal-cli search history
tidal-cli library favorite-playlists

MCP 端点地址：https://tidal-cli.lucaperret.ch/api/mcp

资料来源：site/app/page.tsx

功能架构概览

媒体库管理功能由四个主要子模块组成，分别负责不同的管理职责。这些模块之间相互协作，共同构成了 tidal-cli 的完整媒体库管理体系。

graph TD
    A[媒体库管理] --> B[library.ts]
    A --> C[saved.ts]
    A --> D[history.ts]
    A --> E[search-history.ts]
    
    B --> F[发现推荐]
    B --> G[用户资料]
    
    C --> H[稍后再听]
    C --> I[分享链接]
    
    D --> J[播放历史]
    
    E --> K[搜索历史]

发现与推荐系统

tidal-cli 提供了强大的音乐发现功能，帮助用户探索 Tidal 平台上的新内容。该功能支持多种推荐类型和播放列表生成。

推荐类型

系统支持三种主要的推荐模式，每种模式针对不同的用户场景：

tidal-cli recommend                              # 获取所有推荐分类
tidal-cli recommend --type daily                 # 仅获取每日推荐
tidal-cli mix items <mix-id> --type daily         # 查看特定推荐中的曲目

播放列表电台

除了固定的推荐列表外，tidal-cli 还支持动态播放列表电台功能。这种模式会根据用户当前播放的内容，实时生成类似风格的播放列表。

tidal-cli artist radio <artist-id>               # 获取艺术家电台
tidal-cli track radio <track-id>                 # 获取歌曲电台

播放历史记录

播放历史模块允许用户查看和管理自己的音乐收听记录。该功能支持多种内容类型的历史查询。

历史查询命令

tidal-cli history tracks      # 查看播放过的歌曲历史
tidal-cli history albums      # 查看播放过的专辑历史
tidal-cli history artists     # 查看播放过的艺术家历史

历史记录数据结构

播放历史记录包含以下关键信息：

历史数据通过 Tidal API 的 user/history 端点获取，支持分页查询以便处理大量历史记录。

搜索历史管理

tidal-cli 提供了完整的搜索历史管理功能，帮助用户追踪和管理过往的搜索记录。

搜索历史操作

tidal-cli search history              # 查看最近的搜索记录
tidal-cli search history-delete <entry-id>   # 删除单条搜索记录
tidal-cli search history-clear        # 清除所有搜索历史

数据存储位置

搜索历史记录存储在本地配置目录中：

• 存储路径: ~/.tidal-cli/search-history.json
• 数据格式: JSON 数组，每条记录包含搜索关键词和时间戳

收藏与稍后再听

saved.ts 模块实现了"稍后再听"（Saved for Later）功能，这是 tidal-cli 中最常用的媒体库管理功能之一。用户可以将任意媒体内容添加到稍后再听列表中稍后播放。

收藏管理命令

tidal-cli saved list                         # 列出所有收藏内容
tidal-cli saved add --type tracks --id <id>  # 添加歌曲到收藏
tidal-cli saved remove --type albums --id <id> # 从收藏中移除专辑

支持的媒体类型

分享功能

tidal-cli 内置了社交分享功能，允许用户为任意媒体内容生成公开分享链接。

分享命令

tidal-cli share track <id>     # 生成歌曲分享链接
tidal-cli share album <id>     # 生成专辑分享链接

分享链接会调用 Tidal API 生成临时或永久的公开访问地址，接收方无需登录即可预览或播放分享的内容（受 Tidal 服务条款限制）。

用户资料查询

通过用户资料命令，用户可以查看与当前账户相关的完整信息。

tidal-cli user profile         # 查看当前用户资料

用户资料包含的信息

• 账户类型: Free、HiFi 或 HiFi Plus 订阅等级
• 用户 ID: Tidal 平台唯一标识符
• 账户状态: 有效、过期等状态信息
• 配额信息: 剩余的下载配额或离线播放限额

数据流与交互

sequenceDiagram
    participant User as 用户终端
    participant CLI as tidal-cli CLI
    participant API as Tidal API
    participant Store as 本地存储

    User->>CLI: 执行媒体库命令
    CLI->>API: 发送认证请求
    API-->>CLI: 返回认证令牌
    CLI->>API: 请求媒体库数据
    API-->>CLI: 返回媒体信息
    CLI->>Store: 缓存热门数据
    CLI-->>User: 格式化输出结果

    Note over CLI,Store: 保存功能 (saved add)
    User->>CLI: 保存媒体到收藏
    CLI->>API: 提交保存请求
    API-->>CLI: 确认保存成功
    CLI->>Store: 更新本地索引

与 MCP 服务器的集成

tidal-cli 的媒体库管理功能也通过 MCP（Model Context Protocol）服务器对外暴露，使得 AI 代理（如 Claude）能够以编程方式控制 Tidal 媒体库。

MCP 工具可用性

以下媒体库操作可通过 MCP 接口调用：

• library list-saved — 列出收藏内容
• library add-saved — 添加收藏
• library remove-saved — 移除收藏
• library history — 查询播放历史
• library recommend — 获取推荐内容
• user profile — 用户资料查询

输出格式

所有媒体库命令支持 JSON 格式输出，便于脚本处理和自动化工作流。

tidal-cli --json search track "Around the World"
tidal-cli --json playlist list
tidal-cli --json artist similar 8992

添加 --json 参数后，命令输出为纯 JSON 格式，不再包含任何装饰性文本或进度提示。

本地数据存储

tidal-cli 在本地存储以下与媒体库相关的数据：

数据以加密形式存储认证敏感信息，本地存储目录权限应限制为仅当前用户可访问。

相关文档

• 安装指南: 请参考 README.md 的安装章节
• 服务条款: 使用本工具需遵守 Tidal 服务条款
• 隐私政策: 详见 隐私政策页面

概述

tidal-cli 的播放系统允许用户通过命令行直接控制 Tidal 音乐的播放功能。该系统提供了播放指定曲目、获取播放信息、获取音频流 URL 等核心能力，并支持多种音频质量级别。

播放命令基于 Tidal API 的播放端点实现，支持通过曲目 ID 进行播放操作。 资料来源：README.md:1-100

播放命令架构

子命令结构

tidal-cli 的播放功能通过 playback 子命令组织，包含以下操作：

资料来源：README.md:1-100

基本使用方式

# 播放指定曲目
tidal-cli playback play <id>

# 以无损质量播放
tidal-cli playback play <id> --quality LOSSLESS

# 获取播放信息
tidal-cli playback info <id>

# 获取音频流 URL
tidal-cli playback url <id>

资料来源：README.md:1-100

音频质量设置

支持的质量级别

tidal-cli 支持四种音频质量级别，通过 --quality 参数指定：

资料来源：README.md:1-100

质量选择示例

# 默认质量播放
tidal-cli playback play 5756235

# 指定无损质量播放
tidal-cli playback play 5756235 --quality LOSSLESS

# 高解析音频播放
tidal-cli playback play 5756235 --quality HI_RES

注意: 实际可用的音频质量取决于用户的 Tidal 订阅计划。例如，HI_RES 质量仅对 HiFi Plus 订阅用户可用。

资料来源：README.md:1-100 资料来源：site/app/terms/page.tsx:1-50

工作流程

播放流程图

graph TD
    A[用户执行 playback play 命令] --> B[解析曲目 ID 和质量参数]
    B --> C{是否指定质量}
    C -->|是| D[使用指定质量级别]
    C -->|否| E[使用账户默认质量]
    D --> F[调用 Tidal API 播放端点]
    E --> F
    F --> G{API 响应状态}
    G -->|成功| H[开始播放音频流]
    G -->|失败| I[输出错误信息]

与其他系统的集成

播放与发现功能结合

播放系统可与搜索、历史等功能结合使用：

# 搜索后播放
tidal-cli search track "Teardrop"
# 获取曲目 ID 后
tidal-cli playback play <找到的ID>

# 播放历史记录中的曲目
tidal-cli history tracks
# 选择曲目 ID 后
tidal-cli playback play <历史曲目ID>

与 AI Agent 的集成

通过 MCP 连接器，用户可以让 AI Agent 智能选择并播放音乐：

# AI Agent 可执行的操作示例
"Play me something by Boards of Canada"  # 搜索并播放

资料来源：site/app/page.tsx:1-50

JSON 输出支持

播放相关命令支持 --json 参数以结构化格式输出：

# JSON 格式获取播放信息
tidal-cli --json playback info <id>

# JSON 格式获取音频 URL
tidal-cli --json playback url <id>

此功能便于脚本处理和程序化调用。

资料来源：README.md:1-100

认证要求

播放功能需要有效的 Tidal 认证会话。用户需在首次使用前完成身份验证：

# 身份验证命令
tidal-cli auth

认证成功后，OAuth 令牌将存储在本地 ~/.tidal-cli/session.json 文件中。令牌会自动刷新以维持会话有效性。

资料来源：README.md:1-100 资料来源：site/app/privacy/page.tsx:1-50

技术限制

• 播放功能依赖 Tidal API，可能受 Tidal 服务可用性影响
• API 变更可能导致播放功能暂时不可用
• 某些地区可能存在播放限制

tidal-cli is provided "as is" without warranty of any kind. Tidal may change their API at any time, which could affect functionality.

资料来源：site/app/terms/page.tsx:1-50

故障排除

常见问题

资料来源：site/app/privacy/page.tsx:1-50

概述

tidal-cli 的认证与会话管理系统是该项目的核心基础设施，负责处理用户与 Tidal API 之间的安全通信。该模块基于 OAuth 2.0 授权码模式配合 PKCE（Proof Key for Code Exchange）扩展实现无密钥的安全认证流程。系统设计了双轨制架构，分别支持命令行工具（CLI）的本地会话存储和 MCP 服务器的服务端会话管理，确保用户凭证在传输和存储过程中的安全性。

认证机制

OAuth 2.0 + PKCE 架构

tidal-cli 采用公开客户端（Public Client）OAuth 流程，无需客户端密钥即可完成认证。系统利用 PKCE 机制替代传统客户端密钥，通过动态生成的代码挑战和验证器来保障授权码交换的安全性。

graph TD
    A[用户执行 tidal-cli auth] --> B[生成 code_verifier 和 code_challenge]
    B --> C[构建授权 URL]
    C --> D[启动本地回调服务器]
    D --> E[打开浏览器跳转至 Tidal 授权页]
    E --> F[用户登录并授权]
    F --> G[Tidal 重定向至本地回调服务器]
    G --> H[交换授权码获取 Access Token]
    H --> I[保存会话至 ~/.tidal-cli/session.json]
    I --> J[认证成功]

认证流程详解

#### 第一阶段：启动本地服务器

server.listen(REDIRECT_PORT, () => {
  console.log('\nOpening browser for Tidal authorization...');
  console.log(`If the browser doesn't open, visit:\n  ${loginUrl}\n`);
  console.log('Waiting for authorization...');
  openBrowser(loginUrl);
});

系统在本地随机端口启动 HTTP 服务器，监听来自 Tidal OAuth 服务的回调请求。此服务器作为授权码的接收端点，确保令牌交换过程在用户本地完成，避免凭证经过第三方服务器。

#### 第二阶段：令牌交换

授权码交换过程采用 PKCE 验证机制：

CLI 与 MCP 认证差异

tidal-cli 提供两种使用模式，认证存储策略存在本质区别：

资料来源：site/app/privacy/page.tsx

CLI 模式下，用户的 OAuth 令牌以 JSON 格式持久化至用户主目录下的隐藏文件夹，依赖操作系统文件权限机制进行保护。MCP 模式则将令牌托管于 Vercel 部署的 Upstash Redis 缓存服务，通过服务端加密确保传输安全，并设置 30 天生存时间自动过期。

会话存储

本地会话管理

#### Session 模块架构

classDiagram
    class SessionStorage {
        +getItem(key): string | null
        +setItem(key, value): void
        +removeItem(key): void
        +clear(): void
    }
    class EventTarget {
        +addEventListener()
        +removeEventListener()
        +dispatchEvent()
    }
    class StorageEvent {
        +key: string
        +newValue: string
        +oldValue: string
    }

    SessionStorage --|> EventTarget
    SessionStorage ..> StorageEvent : creates

tidal-cli 在 Node.js 环境中实现了 localStorage 和 EventTarget API 的 polyfill，使得标准 Web 存储接口可直接用于服务端环境。

#### 会话文件格式

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": 1710489600000,
  "userId": "123456789"
}

会话文件采用 JSON 格式存储关键认证信息，包含访问令牌、刷新令牌、过期时间戳及用户 ID。访问令牌用于 API 请求认证，刷新令牌用于获取新的访问令牌而无需用户重新授权。

服务端会话管理（MCP）

#### Redis 存储策略

MCP 连接器使用 Upstash Redis 实现跨会话持久化：

// 伪代码示例
const sessionData = {
  token: encryptedOAuthToken,
  userId: extractedUserId,
  createdAt: Date.now()
};

// 设置 30 天过期时间
await redis.setex(sessionKey, 30 * 24 * 60 * 60, JSON.stringify(sessionData));

资料来源：site/app/privacy/page.tsx

服务端存储采用加密机制保护敏感令牌数据，所有通过 MCP 协议进行的 API 调用都需要从 Redis 中提取有效会话信息。30 天 TTL 确保长期未使用的会话自动清理，减少安全风险。

API 客户端

getApiClient 函数

export async function getApiClient(): Promise<any> {
  await ensureInit();

  // Verify we have valid credentials
  const creds = await credentialsProvider.getCredentials();
  if (!creds.token) {
    console.error('Error: Not authenticated. Run `tidal-cli auth` first.');
    process.exit(1);
  }

  return createAPIClient(credentialsProvider);
}

该函数是获取 Tidal API 客户端的主入口点，核心职责包括：

1. 初始化检查：调用 ensureInit() 确保认证模块已正确初始化
2. 凭证验证：从凭证提供者获取当前会话凭证
3. 错误处理：检测到未认证状态时输出错误信息并终止程序
4. 客户端创建：返回配置了凭证的 API 客户端实例

资料来源：src/auth.ts

getCountryCode 函数

let cachedCountryCode: string | null = null;

export async function getCountryCode(): Promise<string> {
  if (cachedCountryCode) return cachedCountryCode;

  try {
    const client = await getApiClient();
    const { data } = await client.GET('/users/{id}' as any, {
      // ...
    });
    // 从用户配置中提取国家代码
  } catch {
    // 降级策略
  }
}

国家代码自动检测机制遵循以下优先级：

该机制确保 API 请求携带正确的地区标识，获取符合用户所在区域的内容目录和播放限制信息。

Token 自动刷新

刷新机制流程

sequenceDiagram
    participant U as 用户
    participant CLI as tidal-cli
    participant T as Tidal API
    participant FS as 文件系统

    U->>CLI: 执行任意命令
    CLI->>T: 发送带 Access Token 的请求
    T-->>CLI: Token 有效
    CLI-->>U: 返回请求结果

    Note over CLI,T: Token 过期场景
    U->>CLI: 执行任意命令
    CLI->>T: 发送带 Access Token 的请求
    T-->>CLI: 401 Unauthorized
    CLI->>T: 使用 Refresh Token 获取新 Token
    T-->>CLI: 返回新 Access Token + 新 Refresh Token
    CLI->>FS: 更新 session.json
    CLI->>T: 重试原请求
    CLI-->>U: 返回请求结果

刷新触发条件

自动刷新机制在以下场景触发：

• 令牌过期：API 返回 401 状态码时自动尝试刷新
• 令牌临近过期：部分实现会在令牌即将过期前主动刷新
• 首次认证：执行 tidal-cli auth 命令后立即保存初始令牌

刷新成功后，新的访问令牌和刷新令牌会持久化至 ~/.tidal-cli/session.json，确保下次启动时使用最新凭证。

数据安全

隐私保护措施

tidal-cli 在设计层面采取多重数据保护策略：

资料来源：site/app/privacy/page.tsx

第三方服务依赖

认证流程涉及以下 Tidal 官方服务端点：

所有通信遵循 Tidal 官方隐私政策，用户凭证永远不会经过 tidal-cli 维护者的服务器（除 MCP 模式的服务端存储）。

数据删除

用户可通过以下方式清除所有本地认证数据：

rm -rf ~/.tidal-cli

此命令删除包含 OAuth 令牌和会话信息的整个目录。删除后用户需重新执行 tidal-cli auth 进行认证。

相关命令

auth 命令

tidal-cli auth

启动 OAuth 认证流程，打开浏览器引导用户完成 Tidal 账户授权。

依赖模块

总结

tidal-cli 的认证与会话管理系统通过 OAuth 2.0 + PKCE 协议实现了安全的无密钥认证，结合本地和服务端双轨存储策略兼顾了 CLI 用户的数据主权和 MCP 用户的使用便利性。Token 自动刷新机制确保长时间使用的连贯体验，而清晰的数据安全设计让用户对自己的凭证拥有完全控制权。

概述

tidal-cli 的发现与推荐系统为用户提供了一套完整的音乐探索功能，包括个性化推荐、智能混音、用户历史记录管理以及社交分享能力。该系统与 Tidal API 深度集成，使用户能够在命令行环境中完成传统桌面或移动应用中的所有发现操作。

系统架构

发现与推荐系统由多个相互协作的模块组成，每个模块负责特定的功能域：

推荐与混音

获取推荐内容

tidal-cli recommend 命令用于获取系统推荐的各种混音类型：

tidal-cli recommend                              # 获取所有混音类别
tidal-cli recommend --type daily                 # 每日推荐混音
tidal-cli recommend --type discovery            # 发现混音
tidal-cli recommend --type new-release          # 新发行混音
tidal-cli recommend --type offline             # 离线可用混音

混音曲目管理

获取特定混音后，可通过 mix items 命令查看混音内的所有曲目：

tidal-cli mix items <mix-id> --type daily

历史记录系统

播放历史

tidal-cli 记录并管理用户的三类播放历史：

搜索历史

系统同时维护用户的搜索历史，支持以下操作：

tidal-cli search history              # 查看最近的搜索记录
tidal-cli search history-delete <entry-id>   # 删除单条搜索记录
tidal-cli search history-clear        # 清空全部搜索历史

保存与收藏

稍后播放列表

saved 命令提供对“稍后播放”列表的管理功能：

tidal-cli saved list                          # 列出所有已保存的项目
tidal-cli saved add --type tracks --id <id>   # 添加曲目到保存列表
tidal-cli saved add --type albums --id <id>   # 添加专辑到保存列表
tidal-cli saved add --type artists --id <id>  # 添加艺术家到保存列表
tidal-cli saved add --type playlists --id <id> # 添加播放列表
tidal-cli saved add --type videos --id <id>   # 添加视频到保存列表

移除已保存项目

tidal-cli saved remove --type albums --id <id>

分享功能

tidal-cli 支持生成公开分享链接，允许用户与他人共享音乐内容：

tidal-cli share track <id>     # 创建曲目的公开分享链接
tidal-cli share album <id>      # 创建专辑的公开分享链接

分享功能会通过 Tidal API 生成标准化的分享 URL，接收方可直接在浏览器中打开查看。

用户资料

获取当前登录用户的完整资料：

tidal-cli user profile

该命令返回用户账户信息，包括订阅状态、用户名等个人资料数据。

JSON 输出

所有发现与推荐相关的命令都支持 JSON 格式输出，便于脚本处理和程序化调用：

tidal-cli --json recommend
tidal-cli --json history tracks
tidal-cli --json saved list
tidal-cli --json search history

数据流向

graph TD
    A[用户请求] --> B[tidal-cli CLI]
    B --> C{命令类型}
    C -->|recommend| D[Tidal API: /recommendations]
    C -->|history| E[Tidal API: /history]
    C -->|saved| F[Tidal API: /library]
    C -->|share| G[Tidal API: /share]
    C -->|user| H[Tidal API: /user]
    D --> I[JSON 输出]
    E --> I
    F --> I
    G --> I
    H --> I

典型使用场景

每日音乐探索流程

# 1. 查看每日推荐混音
tidal-cli recommend --type daily

# 2. 获取混音中的曲目
tidal-cli mix items <mix-id> --type daily

# 3. 播放感兴趣的曲目
tidal-cli playback play <track-id>

# 4. 查看播放历史
tidal-cli history tracks

个人资料管理

# 查看个人资料
tidal-cli user profile

# 查看播放历史
tidal-cli history tracks
tidal-cli history albums
tidal-cli history artists

# 管理已保存内容
tidal-cli saved list

隐私说明

根据 tidal-cli 隐私政策，使用 CLI 模式时所有数据直接在你的设备与 Tidal API 服务器之间传输，不经过任何中介服务器。认证令牌存储在本地文件 ~/.tidal-cli/session.json 中。

如需清除所有本地存储的发现历史和缓存数据，可执行：

rm -rf ~/.tidal-cli

概述

MCP（Model Context Protocol）服务器集成为 tidal-cli 提供了与 AI 助手（特别是 Claude Desktop 和 claude.ai）的无缝集成能力。通过这一集成，用户可以通过自然语言指令与 Tidal 账户进行交互，实现音乐搜索、播放列表管理、资料库操作等功能。

tidal-cli 作为远程 MCP 服务器运行，允许 AI 代理直接调用 Tidal API 的各项功能，无需用户在本地安装任何软件。所有认证令牌存储在 Upstash 托管的加密 Redis 数据库中，确保了安全性和跨设备访问能力。

架构设计

系统组件

认证流程

sequenceDiagram
    participant User
    participant Claude
    participant MCP_Server
    participant Tidal_API
    participant Redis

    User->>Claude: 请求连接 Tidal
    Claude->>MCP_Server: 通过 /api/mcp 连接
    MCP_Server->>User: 重定向到授权页面
    User->>Tidal_API: 输入 Tidal 凭据
    Tidal_API->>MCP_Server: 返回 OAuth Code
    MCP_Server->>Tidal_API: 交换 Access Token
    Tidal_API->>MCP_Server: 返回 Token
    MCP_Server->>Redis: 加密存储会话
    Redis->>MCP_Server: 确认存储
    MCP_Server->>Claude: 连接成功
    Claude->>User: 显示可用工具

MCP 连接配置

连接地址

MCP 服务器通过以下端点对外提供服务：

https://tidal-cli.lucaperret.ch/api/mcp

该端点托管在 Vercel 平台上，响应 MCP 协议的标准请求。

Claude Desktop 配置

在 Claude Desktop 中配置自定义连接器的步骤如下：

1. 打开 Claude Desktop 设置页面
2. 导航至 Connectors（连接器）部分
3. 点击 Add custom connector（添加自定义连接器）
4. 输入上述 MCP 端点 URL
5. 点击 Connect（连接）并使用 Tidal 账户登录

可用工具

tidal-cli MCP 集成提供了 40 个工具，覆盖以下功能类别：

搜索功能

播放列表管理

资料库操作

艺术家相关

专辑相关

曲目相关

播放控制

推荐与历史

其他功能

工具定义规范

每个 MCP 工具都遵循统一的定义规范，包含以下元数据：

server.tool(
  'tool_name',                    // 工具标识符
  'Tool description',            // 工具描述
  { /* 参数 Schema */ },          // Zod 参数验证
  { 
    readOnlyHint: boolean,       // 是否只读操作
    destructiveHint: boolean,     // 是否为破坏性操作
    openWorldHint: boolean,       // 是否涉及外部网络
    title: string                // 人类可读标题
  },
  async (params, extra) => {
    // 工具实现
  }
);

工具提示语义

认证与令牌管理

OAuth 认证流程

MCP 服务器使用标准的 OAuth 2.0 流程进行身份验证：

1. 授权请求：用户发起连接请求后，被重定向至 Tidal 登录页面
2. 用户授权：用户在 Tidal 页面输入凭据并授权 tidal-cli 访问
3. 回调处理：Tidal 通过回调 URL 返回授权码
4. 令牌交换：服务器将授权码交换为访问令牌和刷新令牌
5. 会话存储：加密后的令牌存储至 Upstash Redis

令牌存储

CLI 模式下，令牌存储在本地：~/.tidal-cli/session.json

MCP 模式下，令牌存储在服务器端加密的 Redis 数据库中，由 Upstash（Vercel 生态）托管。

使用示例

自然语言交互

用户可以通过以下方式与 Tidal 交互：

质量参数

播放功能支持指定音质：

tidal-cli playback play <id> --quality LOSSLESS

可用质量选项：LOW、HIGH、LOSSLESS、HI_RES

隐私与安全

数据存储

根据隐私政策，MCP 集成遵循以下数据处理原则：

• tidal-cli 不向开发者服务器收集或传输任何个人数据
• 认证令牌加密存储在 Upstash Redis 中
• 所有 Tidal API 通信直接通过用户设备与 Tidal 服务器进行

数据删除

用户可通过以下方式删除所有存储的数据：

1. 在 Tidal 账户设置中撤销 tidal-cli 的访问权限
2. 删除本地会话文件（CLI 模式）：rm -rf ~/.tidal-cli

Smithery 集成

除 Claude Desktop 外，tidal-cli MCP 服务器还可在 Smithery 平台获取：

https://smithery.ai/servers/lucaperret/tidal

相关资源

• 官方文档：github.com/lucaperret/tidal-cli
• 隐私政策：tidal-cli.lucaperret.ch/privacy
• 服务条款：tidal-cli.lucaperret.ch/terms

概述

tidal-cli 项目不仅包含核心的命令行工具，还维护了一个完整的 Web 前端站点（位于 site/ 目录）。该站点主要用于：

• 展示项目功能和使用说明
• 提供 MCP（Model Context Protocol）服务器端点，供 AI 代理（如 Claude）远程调用 Tidal API
• 生成社交分享用的 OG（Open Graph）图片和横幅

站点采用 Next.js 框架构建，部署在 Vercel 平台，并集成了 Upstash Redis 用于 MCP 模式下的认证令牌存储。

技术架构

技术栈

目录结构

site/
├── app/
│   ├── components/          # React 组件
│   │   ├── Nav.tsx          # 顶部导航栏
│   │   └── Terminal.tsx     # 终端模拟展示组件
│   ├── api/                 # API 路由
│   │   └── mcp/             # MCP 服务器端点
│   ├── terms/               # 服务条款页面
│   ├── privacy/             # 隐私政策页面
│   ├── og-banner/           # OG 图片生成路由
│   ├── banner/              # 横幅生成路由
│   └── page.tsx             # 首页
├── package.json
└── vercel.json

核心组件

导航组件

site/app/components/Nav.tsx 提供了站点的顶部导航栏功能：

• 左侧显示 tidal-cli Logo
• 右侧提供 GitHub 链接入口
• 响应式设计，在移动端隐藏部分链接

// Nav.tsx 核心结构
<nav className="flex items-center justify-between">
  <a href="/" className="text-white font-medium">tidal-cli</a>
  <div className="flex items-center gap-6">
    <a href="/terms">Terms</a>
    <a href="/privacy">Privacy</a>
    <a href="https://github.com/lucaperret/tidal-cli">GitHub</a>
  </div>
</nav>

资料来源：site/app/components/Nav.tsx

终端展示组件

site/app/components/Terminal.tsx 是一个用于模拟命令行终端界面的 React 组件，支持动画效果和命令展示：

interface Line {
  prompt?: boolean;  // 是否显示 $ 提示符
  text: string;      // 命令文本
  dim?: boolean;     // 是否显示为灰色（注释）
}

组件使用 Framer Motion 实现逐行动画效果，每行动画延迟 80ms：

<motion.div
  transition={{ duration: 0.3, delay: i * 0.08 }}
>
  {line.prompt && <span>$ </span>}
  <span className={line.dim ? "text-tidal-gray-400" : "text-white"}>
    {line.text}
  </span>
</motion.div>

资料来源：site/app/components/Terminal.tsx

首页结构

site/app/page.tsx 是站点的首页，包含以下主要区域：

功能展示区

展示 tidal-cli 的核心命令功能，包括搜索、艺术家信息、播放列表、播放控制、媒体库管理等。

资料来源：site/app/page.tsx

安装区域

提供 npm 安装命令和 OAuth 认证流程说明：

npm install -g @lucaperret/tidal-cli
tidal-cli auth

资料来源：site/app/page.tsx

MCP 集成区域

说明如何将 tidal-cli 作为远程 MCP 服务器连接到 Claude Desktop：

1. 在 Claude 设置中添加自定义连接器
2. 输入 MCP 端点 URL：https://tidal-cli.lucaperret.ch/api/mcp

资料来源：site/app/page.tsx

AI 代理示例区域

展示用户可以通过自然语言让 AI 代理执行复杂的 Tidal 操作：

MCP 服务器端点

MCP 服务器通过 API 路由 /api/mcp 提供服务，允许 AI 代理远程调用 tidal-cli 功能。

认证机制

根据隐私政策，MCP 模式下的认证令牌存储在服务器端：

当使用 tidal-cli 作为 MCP 连接器时（例如通过 Claude Desktop 或 claude.ai），认证令牌存储在 Upstash（通过 Vercel）托管的加密 Redis 数据库中。

资料来源：site/app/privacy/page.tsx

数据流向

graph TD
    A[Claude Desktop] -->|MCP Protocol| B[tidal-cli.lucaperret.ch/api/mcp]
    B --> C[Upstash Redis]
    C -->|Session Tokens| B
    B -->|Tidal API| D[openapi.tidal.com]
    B -->|OAuth| E[login.tidal.com / auth.tidal.com]

OG 图片与横幅生成

OG Banner 路由

site/app/og-banner/route.tsx 和 site/app/banner/route.tsx 提供了动态生成 Open Graph 图片的功能。

这些路由使用 Next.js 的 Image Response API 生成 SVG 格式的横幅图片：

new ImageResponse(
  (
    <div style={...}>
      <div style={{ fontSize: 56, fontWeight: 700, color: "#fff" }}>
        tidal-cli
      </div>
    </div>
  ),
  { width: 1280, height: 240 }
);

生成内容包括：

• tidal-cli 标题文字
• 功能标签（Search、Playlists、Playback、Discovery）
• AI Agent Ready 标识

资料来源：site/app/og-banner/route.tsx

隐私与合规

数据收集策略

资料来源：site/app/privacy/page.tsx

外部服务依赖

资料来源：site/app/privacy/page.tsx

数据删除

用户可通过以下方式删除所有本地存储数据：

rm -rf ~/.tidal-cli

资料来源：site/app/privacy/page.tsx

服务条款

site/app/terms/page.tsx 明确了使用条款：

用户责任

• 遵守 Tidal 的服务条款
• 对账户所有操作负责

可接受使用

用户同意不：

• 将 tidal-cli 用于任何非法目的
• 尝试绕过 Tidal 的访问控制或 DRM
• 使用服务下载或重新分发受版权保护的内容
• 进行超出正常使用的过度或自动请求

免责声明

tidal-cli 按"原样"提供，不提供任何明示或暗示的保证。维护者不保证不间断或无错误的运行。Tidal 可能随时更改其 API，这可能影响功能。

资料来源：site/app/terms/page.tsx

部署流程

Vercel 部署

站点部署在 Vercel 平台，利用边缘函数提供低延迟的 MCP 服务。

部署检查清单

1. 确保 site/ 目录包含所有必要的配置文件
2. 配置环境变量（如有）
3. 通过 GitHub 集成连接到 Vercel
4. 启用自动部署

相关链接

Pitfall Log / 踩坑日志

项目：lucaperret/tidal-cli

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown