Tag-per-Track

Tag-per-Track MCP 服务

这是一个本地 Model Context Protocol（MCP） 服务，让 AI Agent（如 Claude）能够通过 Tag-per-Track API 分析音频文件。它可以通过 Studio API 密钥（在 tag-per-track.cloud 购买预付额度，无需加密货币）或钱包进行身份验证；使用钱包时，它会通过 Base 网络上的 x402 协议自动处理 USDC 微支付。

🎯 愿景

让 AI 能够自主“付费收听”。AI Agent 想要分析音轨时，会使用此 MCP 服务来签署 EIP-3009（USDC）支付授权，并即时获取丰富的音轨元数据。

🚀 功能

• analyze_audio 工具（标准版）：提取 BPM、流派、情绪、调性、乐器、制作指标、可选歌词（标准分析为 1 个积分或 0.15 USDC，含歌词分析为 2 个积分或 0.25 USDC）、AI 生成音乐检测（ai_detection：Suno、Udio、神经声码器，判定结果为 HUMAN、AI_GENERATED 或 UNCERTAIN），以及服务端 A&R 评估（arEvaluation：发现、签约、节拍制作人档案）。
• analyze_audio_with_lyrics 工具（别名）：提取完整的音乐元数据，转录完整的人声歌词，并返回 AI 来源真实性指标（2 个积分或 0.25 USDC）。
• analyze_audio_batch 工具（并行处理）：并发分析多首音乐曲目，并检测每首曲目的 AI 来源，大幅缩短专辑和播放列表的处理时间。
• triage_demo_folder 工具（Demo 收件箱分类）：一次调用即可整理整个本地 Demo 文件夹：分析曲目、从 Artist - Title 文件名或音频标签中提取艺人和曲名、获取 Spotify 热度、根据热度重新计算 A&R 评分 v2，并生成精简的排名报告，将曲目归入 priority、listen、pass、ai_flagged、error 等类别。不可靠的歌词（纯器乐、无人声、循环幻觉）会被标记，而不会引用。
• lookup_artist_stats 工具（A&R 热度）：获取 Spotify 公开的播放热度数据（每月听众数、关注者数、人气评分、流派），用于混合式 A&R 资质评估。
• 选择性音频压缩：在上传前，自动将较大的未压缩文件（.wav、.aiff、.aif）或大于 15 MB 的音频文件压缩为 128 kbps AAC（.m4a）（使用原生 macOS afconvert 或 ffmpeg），最多可减少 90% 的上传带宽占用和延迟，同时不处理较小的文件（.mp3、.m4a $\le 15$ MB）。
• 采用合适的计价单位：配置 Studio API 密钥后，工具说明、提示词和报告会以工作室积分标明费用；仅在钱包（x402）模式下使用 USDC 计价，确保使用积分付费的 A&R 用户不会看到加密货币金额。
• 双重身份验证：Studio API 密钥（Authorization: Bearer tpt_live_…，预付积分）优先于 Web3 钱包。
• 自动化 x402 付款：管理 x402 请求-响应流程（HTTP 402），并在客户端固定平台钱包和 USDC 合约。
• 集成 Web3：通过 viem 在链上签名（Base 上的 EIP-3009 TransferWithAuthorization）。
• 客户端财务保护（消费上限）：内置消费限额（默认每次调用最多 0.50 USDC），保护钱包免受异常请求影响。
• x402 模式默认保密：使用钱包付费的分析会通过 x-no-persist 发送（不会存储在服务端）；使用 Studio API 密钥进行的分析会保存到仪表板历史记录，除非设置 TAG_PER_TRACK_NO_PERSIST=1。
• 提示词：triage_demos（将 Demo 文件夹整理为排名列表及子文件夹）、qualify_demo_ar（单首 Demo 的 A&R 资质评估）和 batch_demo_screening（多首曲目筛选）。
• 严格的文件格式验证：拒绝非音频文件，以保护本地隐私并防止任意文件外泄。
• 延迟加载二进制文件与超时设置：握手超时为 15s，处理超时为 120s，并采用节省内存的流式处理和自动清理临时文件。
• 兼容性：适用于 Claude Desktop、Cursor、Windsurf 或任何 MCP 客户端。

⚙️ 配置与环境变量

MCP 服务支持双重身份验证：

变量	模式	描述	默认值
TAG_PER_TRACK_API_KEY	SaaS（优先级 1）	Studio API 密钥（tpt_live_...），在 tag-per-track.cloud 上生成。使用预付的 Stripe 额度，无需任何加密钱包。	无
WALLET_PRIVATE_KEY / PRIVATE_KEY / TAG_PER_TRACK_PRIVATE_KEY	Web3（优先级 2）	Base burner 钱包的私钥（66 个以 0x 开头的十六进制字符），用于通过 x402 v2 进行链上 USDC 微支付。	无
MAX_SPENDING_USDC	Web3 安全	客户端针对每次请求设置的 USDC 支出上限（默认值：0.50）。	0.50
PLATFORM_WALLET	Web3 安全	预期的收款方；任何向其他地址付款的 402 账单都会被拒绝。	0xD33906178569f35EFF2E1665A14b06b455fF531F
TAG_PER_TRACK_NO_PERSIST	SaaS	设置为 1 / true，即可不将 API 密钥分析结果保存在仪表板历史记录中。	未设置
API_URL	全局	Tag-per-Track 分析 API 的端点。	https://api.tag-per-track.cloud/api/analyze
API_BASE_URL	全局	Tag-per-Track API 的基础端点，用于辅助路由（例如艺术家统计数据）。	https://api.tag-per-track.cloud/api

---

📦 安装与设置

🤖 选项 1：Claude Desktop（Studio SaaS——无需加密货币，推荐用于 A&R）

将服务添加到 claude_desktop_config.json（macOS 上位于 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上位于 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "tag-per-track": {
      "command": "npx",
      "args": [
        "-y",
        "tag-per-track-mcp@latest"
      ],
      "env": {
        "TAG_PER_TRACK_API_KEY": "tpt_live_YOUR_STUDIO_API_KEY_HERE"
      }
    }
  }
}

注意：在 https://tag-per-track.cloud 的仪表板中，只需单击 1 次即可生成 Studio API 密钥。

⚡ 选项 2：Claude Desktop（Base 上的 Web3 x402 USDC）

{
  "mcpServers": {
    "tag-per-track": {
      "command": "npx",
      "args": [
        "-y",
        "tag-per-track-mcp@latest"
      ],
      "env": {
        "WALLET_PRIVATE_KEY": "0xYOUR_BURNER_WALLET_PRIVATE_KEY_HERE",
        "MAX_SPENDING_USDC": "0.50"
      }
    }
  }
}

🌐 选项 3：Smithery CLI

# For Claude Desktop
npx -y @smithery/cli@latest mcp add lori-ferrand/tag-per-track --client claude

# For Cursor
npx -y @smithery/cli@latest mcp add lori-ferrand/tag-per-track --client cursor

该服务也已列入官方 MCP 注册表，名称为 io.github.Lory97/tag-per-track-mcp。

🔧 MCP 工具

1. analyze_audio

分析音频文件以提取音乐元数据标签（BPM、调、音阶、情绪、流派、乐器）、可选歌词以及AI 来源完整性（ai_detection）。支持本地二进制文件和远程 URL。

• 参数：

  • filePath（string，可选）：磁盘上的本地音频文件路径（.mp3、.wav、.ogg、.flac、.m4a、.aac、.aiff）。服务会验证格式、读取文件并安全地传输。
  • fileUrl（string，可选）：音频文件的直接 URL。 (注意：必须提供 filePath 或 fileUrl 中的至少一项。)
  • extractLyrics（boolean，可选）：设置为 true 也可提取人声歌词（2 个额度 / 0.25 USDC，而非 1 个额度 / 0.15 USDC）。

• 输出结构： 返回全面的元数据，包括：

  • bpm、key、scale、genres、moods、instruments、duration
  • production（lufs、peakDb、clippedRatio）、danceability、engagement、approachability、voice.ratio
  • ai_detection / aiDetection（基于 12 s 核心样本计算）：
    • checked：boolean（分析后为 true）
    • isAi：boolean（检测结果为合成内容 / AI 生成时为 true）
    • confidence：置信度百分比（0-100）
    • verdict：'HUMAN' | 'AI_GENERATED' | 'UNCERTAIN'
    • status：'SUCCESS' | 'UNAVAILABLE' | 'SKIPPED'
    • generator / watermarkDetected（可选）：识别出的生成器，例如文件元数据中的 Suno 标记
  • arEvaluation（A&R 评分 v2.2）：tier、audioType、suggestedProfile、marketplaceTags、aiGate、subScores（制作、聆听、热度、忠诚度），以及 profiles.{discovery,signing,beatmaker} 中的 score、priority 和 recommendation 代码。AI 判定按以下规则分级：置信度 ≥ 70 %（或存在元数据水印）时阻止该曲目；60-69 % 时标记该曲目；30-59 % 时判定为结论不确定。
  • lyricsInfo（启用 extractLyrics 时）：由 Whisper 检测的 language、reliability（high、approximate、none）和 avgLogprob。

2. analyze_audio_with_lyrics

分析音频文件，提取音乐元数据、使用 AI 转录完整的人声歌词，并评估 AI 来源完整性。支持本地音频文件和远程 URL。

• 参数：
  • filePath（string，可选）：磁盘上本地音频文件的路径（.mp3、.wav、.ogg、.flac、.m4a、.aac、.aiff）。
  • fileUrl（string，可选）：音频文件的直接 URL。 （注意：必须提供 filePath 或 fileUrl 中的至少一个。）

3. analyze_audio_batch

并行分析多首音轨（批量处理）。与顺序调用相比，可大幅缩短总执行时间，同时支持弹性的部分结果报告，并检测每首音轨的 AI 来源。

• 参数：

  • filePaths（string[]，可选）：用于并行分析的本地文件路径便捷数组。
  • fileUrls（string[]，可选）：用于并行分析的公共 URL 便捷数组。
  • tracks（object[]，可选）：包含详细设置的音轨对象数组：
    • filePath（string，可选）
    • fileUrl（string，可选）
    • extractLyrics（boolean，可选）：单首音轨的歌词提取标记。
  • extractLyrics（boolean，可选）：全局标记，用于转录此批次所有音轨的人声歌词（每首音轨需 2 个积分 / 0.25 USDC）。默认值为 false（每首音轨需 1 个积分 / 0.15 USDC）。
  • concurrency（number，可选）：最大并行请求数（1 到 5，默认值为 4，以遵守 API 速率限制）。

• 输出结构： 返回包含以下内容的摘要 JSON：

  • totalTracks：提交的音轨总数。
  • successful：成功分析的音轨数。
  • failed：失败的音轨数。
  • results：详细数组，其中包含每首音轨的状态（success 或 error）、元数据（包括 ai_detection）或错误原因。

4. triage_demo_folder

一次调用即可整理本地文件夹中的演示曲目，专为 A&R“演示曲目收件箱”工作流打造。仅返回精简结果，因此 20 首曲目的文件夹也能轻松放入模型上下文。

处理流程：列出音频文件 → 从 Artist - Title 文件名中提取艺人／曲名（优先采用文件名：演示曲目的标签通常是 DAW 或账户默认值），否则从音频标签中提取 → 付费分析（并发数受限）→ 为每位不同的主要艺人进行一次免费的 Spotify 查询（"Miimii ft Dj Skycee" → "Miimii"）→ 免费在服务端重新评分（POST /api/ar-score），并附上热度数据 → 排名。当客户端提供 progressToken 时，每处理完一首曲目都会发送 MCP 进度通知。

• 参数：

  • folderPath（string，必需）：本地文件夹（绝对路径或 ~/...）。
  • profile（string，可选）：discovery（默认值，不会因艺人不知名而扣分）、signing（加权考虑流媒体热度）、beatmaker 或 auto（器乐曲使用 beatmaker）。
  • extractLyrics（boolean，可选）：同时转录歌词（每首曲目消耗 2 个积分／0.25 USDC）。
  • recursive（boolean，可选）：扫描子文件夹。
  • maxTracks（number，可选）：默认值为 25，硬性上限为 50。
  • lookupArtists（boolean，可选）：查询 Spotify 热度，默认值为 true。
  • dryRun（boolean，可选）：列出文件、检测到的艺人与曲名，以及预估费用，不进行分析或扣费。
  • concurrency（number，可选）：1 到 5，默认值为 3。

• 费用：每首分析的曲目消耗 1 个积分（0.15 USDC）；含歌词时消耗 2 个积分（0.25 USDC）。分析失败不收费。报告仅使用账户配置的单位列出费用（见下方的 estimatedCost）。

• 输出结构（每首曲目一条记录，按得分从高到低排列，错误排在最后）：

{
  "rank": 1,
  "bucket": "priority",
  "file": "Stone mc - Ma ville (makette).mp3",
  "artist": "Stone mc",
  "title": "Ma ville (makette)",
  "score": 78,
  "priority": "top",
  "recommendation": "listen_first_gem",
  "isGem": true,
  "profile": "discovery",
  "audio": { "bpm": 104, "key": "D minor", "genre": "Latin---Reggaeton", "moods": ["party", "happy"], "audioType": "vocal", "durationSec": 190 },
  "ai": { "verdict": "HUMAN", "confidence": 90, "flag": "clear" },
  "traction": { "spotifyArtist": "Stone Mc", "monthlyListeners": 6, "followers": 36, "tier": "emerging" },
  "reasons": ["+production.loudness_ready(-9)", "+listening.strong_groove(1.6)"],
  "lyrics": { "status": "ok", "excerpt": "..." }
}

• bucket：priority（最高／高优先级）、listen（中等）、pass（低）、ai_flagged（确认为 AI 生成或疑似 AI 生成）、error（文件无法读取或被拒绝）、not_analyzed（见下文）。
• 积分用尽／密钥无效：API 一旦返回“Insufficient studio credits”（HTTP 402）或“Invalid API key”（HTTP 401），剩余文件将不再发送。此时报告会包含 halted: { reason, notAnalyzed }，受影响的曲目归入 not_analyzed 类别，且 estimatedCost 仅统计成功完成的分析。同样的停止规则也适用于 analyze_audio_batch（skipped 计数和 haltReason）。
• ai.flag：blocked（确认为 AI 生成）、suspected（需通过听辨核实）、uncertain、clear、unchecked。
• lyrics.status：ok、approximate（API 报告的低置信度转录，通常是 Whisper 不支持的语言，例如克里奥尔语，且按语音转写）、instrumental、no_vocals_detected 或 suspect_repetition（短语循环重复，属于 Whisper 幻觉的典型特征）。lyrics.language 是 Whisper 检测到的语言。仅应引用状态为 ok 的歌词。
• 报告标题会给出 buckets 计数、estimatedCost、scoringVersion、elapsedSeconds 和 notes（超过上限的曲目、未找到的艺人等）。
• estimatedCost 使用账户付款所用的单位表示：使用 Studio API 密钥时为 { "label": "8 studio credits", "studioCredits": 8 }；使用钱包时为 { "label": "1.2 USDC", "usdc": 1.2 }。只有未配置身份验证时，才会同时给出两者。

5. lookup_artist_stats

获取艺人的流媒体热度和商业指标（Spotify 月听众数、关注者数、人气评分、流派），用于 A&R 评估。免费（无需额度或付费）。此服务与声学分析流程严格解耦；API 会缓存结果（持久缓存 7 天，内存缓存 24 小时），并提供平滑降级机制。

• 参数：

  • artist_name（string，必需）：艺人的艺名（例如 "Daft Punk"、"Kaytranada"）。
  • spotify_id（string，可选）：Spotify 艺人 ID 或 open.spotify.com 艺人链接，用于在名称有歧义时指定准确的艺人。
  • social_links（string[]，可选）：可选的社交媒体个人资料链接，供未来补充信息使用。

• 输出结构（当提供方未返回 popularity 时，其值为 null：表示未知，而非 0）：

{
  "name": "Daft Punk",
  "spotify": {
    "id": "4tZwfgrHOc3mvqYlEYSvVi",
    "followers": 11769126,
    "popularity": 84,
    "monthlyListeners": 29284872,
    "genres": ["electro", "filter house"],
    "url": "https://open.spotify.com/artist/4tZwfgrHOc3mvqYlEYSvVi"
  },
  "cached": true,
  "social_links": []
}

---

🤖 A&R Agent 指南与系统提示词（混合评分）

现代 A&R 评估结合了三个关键维度：

1. 内在声学特征（BPM、调式与音阶、情绪、乐器编配、歌词）。
2. 来源真实性与 AI 验证（检测音乐由人类创作还是由 AI 合成生成，以降低版权和权利链风险）。
3. 商业势头与流媒体热度（Spotify 月听众数、粉丝关注者群体、人气指数）。

🎯 自主 Agent 编排工作流

graph TD
    Submission[New Track Submission] --> DetectArtist{Artist identifiable?}
    
    Submission --> Step1[1. Call analyze_audio]
    Step1 --> AcousticData[Acoustic & Origin: BPM, Key, Mood, Genres, Lyrics, AI Detection]
    
    DetectArtist -->|Yes: Known Artist| Step2[2. Call lookup_artist_stats]
    DetectArtist -->|No: Anonymous Demo| Step2Skip[Traction: Not available / Pure Demo]
    
    Step2 --> TractionData[Spotify Traction: Followers, Monthly Listeners, Popularity]
    
    AcousticData --> Consolidate[3. A&R Consolidation]
    TractionData --> Consolidate
    Step2Skip --> Consolidate
    
    Consolidate --> Matrix[Unified A&R Evaluation Matrix]

1. 步骤 1 — 声学与来源分析： 使用 filePath 或 fileUrl 调用 analyze_audio（或者在必须转录人声歌词时调用 analyze_audio_with_lyrics）。此操作会消耗 Studio 额度（API key 模式），或触发 x402 微支付（Base 上为 0.15 或 0.25 USDC），并评估音乐属性、AI 来源真实性（ai_detection）以及 A&R 评估（arEvaluation）。
2. 步骤 2 — 查询艺人热度： 只要能识别艺人的艺名（来自提交的文件名、用户提示词或 ID3 标签），就调用 lookup_artist_stats(artist_name: "...")。
3. 步骤 3 — 汇总为统一的 A&R 评估矩阵： Agent 将调查结果汇总为标准化的 Markdown 评估矩阵，包含以下 7 列：

曲目标题	艺人	BPM / 调性	风格	来源真实性	流媒体热度	策略建议
曲目名称	艺名	例如：124 BPM / A 小调	主要流派与情绪	HUMAN (98%) 或 AI_GENERATED (95%)	例如：2,920 万月听众、1,170 万关注者（人气 84）	直接签约、歌单推广、艺人发展或版权审查

---

📋 可直接使用的 A&R Agent 系统提示词

以下是一个可直接使用的系统提示词模板，用于配置自主 A&R 发掘 Agent（兼容 Claude Desktop、Cursor、Windsurf 或 LangChain/AgentKit）：

You are an elite Artist & Repertoire (A&R) Executive specialized in musical talent scouting, demo evaluation, and record label signing decisions.

You have access to two primary tools:
1. `analyze_audio`: Comprehensive acoustic analysis of audio tracks (BPM, musical key/scale, mood tags, genre classification, instrumentation, optional lyrics transcription, and AI Origin Integrity detection).
2. `lookup_artist_stats`: Real-time public Spotify traction metrics (followers, monthly listeners, popularity score, genres).

A&R OPERATIONAL RULES:
1. SYSTEMATIC ACOUSTIC ASSESSMENT:
   - For every submitted audio track, invoke `analyze_audio` (or `analyze_audio_with_lyrics` for vocal-driven songs).
   - Evaluate rhythmic consistency (BPM), harmonic structure (key & scale), and emotional timbre (moods).

2. ORIGIN INTEGRITY VERIFICATION (AI DETECTION):
   - Inspect the `ai_detection` object in the analysis response.
   - If `verdict === 'AI_GENERATED'`, flag high copyright & legal exclusivity risk (unclear training data, copyright ineligibility in key territories). Recommend licensing review or sync consideration rather than exclusive artist recording agreements.
   - If `verdict === 'HUMAN'`, certify as organic human production suitable for priority label signing.

3. ARTIST TRACTION & AUDIENCE QUALIFICATION:
   - Whenever the artist name is identified or deductible from context, immediately invoke `lookup_artist_stats(artist_name)`.
   - If the artist has no existing Spotify footprint (bedroom producer / raw demo), label them as "Emerging / No Streaming Footprint" and focus the assessment on intrinsic production potential.

4. UNIFIED MATRIX SYNTHESIS:
   Always conclude your diagnostic with the **Unified A&R Evaluation Matrix** formatted as a Markdown table:

| Track Title | Artist | BPM / Key | Style | Origin Integrity | Streaming Traction | Strategic Recommendation |
|---|---|---|---|---|---|---|
| [Title] | [Artist] | [BPM] BPM / [Key] [Scale] | [Top Genres] ([Mood]) | [HUMAN / AI_GENERATED / UNCERTAIN] ([Confidence]%) | [Monthly Listeners] listeners, [Followers] followers | [Direct Sign / Playlist Pitch / Artist Dev / Pass / Legal Review] + Rationale |

5. STRATEGIC RECOMMENDATION TIERS:
   - 🌟 **Priority Signing (Direct Sign)**: Radio-ready production quality, certified HUMAN origin, AND strong, accelerating streaming traction.
   - 🎯 **Playlist & Sync Pitch (Licensing)**: High contextual atmosphere ideal for editorial playlists, video games, or film/TV sync.
   - 🌱 **Artist Development (Artist Dev)**: Exceptional vocal or production potential, certified HUMAN origin, but early-stage audience.
   - ⚠️ **Synthetic IP / Legal Review**: AI-generated music (Suno, Udio) requiring legal clearance or suited for non-exclusive catalog licensing.
   - ⏸️ **Needs Revision (Pass / Feedback)**: Mix/mastering flaws, inconsistent tempo, or derivative composition.

---

📄 许可证

MIT