Tag Per Track README

Tag-per-Track MCP Server

This project is a local Model Context Protocol (MCP) server that allows AI agents (like Claude) to analyze audio files via the Tag-per-Track API. It authenticates either with a Studio API key (prepaid credits bought on tag-per-track.cloud, no crypto needed) or with a wallet, in which case it automatically handles the USDC micro-payment using the x402 protocol on the Base network.

🎯 Vision

Enable an AI to "pay to listen" autonomously. When an AI agent wants to analyze a track, it uses this MCP server, which signs an EIP-3009 (USDC) payment authorization and instantly retrieves the enriched track metadata.

🚀 Features

• analyze_audio Tool (Canonical): Extracts BPM, Genre, Mood, Key, Instruments, production metrics, optional Lyrics (1 credit or 0.15 USDC standard / 2 credits or 0.25 USDC with lyrics), AI-Generated Music Detection (ai_detection: Suno, Udio, neural vocoders with HUMAN, AI_GENERATED, or UNCERTAIN verdicts) and the server-side A&R evaluation (arEvaluation: discovery / signing / beatmaker profiles).
• analyze_audio_with_lyrics Tool (Alias): Extracts complete musical metadata, transcribes full vocal lyrics, and returns AI origin integrity metrics (2 credits or 0.25 USDC).
• analyze_audio_batch Tool (Parallel Processing): Analyzes multiple music tracks concurrently with AI origin detection on every track, dramatically reducing turnaround time for albums and playlists.
• triage_demo_folder Tool (Demo Inbox Triage): Sorts a whole local folder of demos in one call: analysis, artist/title from Artist - Title file names or audio tags, Spotify traction, A&R scoring v2 re-computed with the traction, and a compact ranked report with buckets (priority, listen, pass, ai_flagged, error). Unreliable lyrics (instrumental, no voice, looping hallucination) are flagged instead of quoted.
• lookup_artist_stats Tool (A&R Traction): Fetches public Spotify streaming traction (monthly listeners, followers, popularity score, genres) for hybrid A&R qualification.
• Selective Audio Compression: Automatically compresses heavy uncompressed files (.wav, .aiff, .aif) or audio files larger than 15 MB to 128 kbps AAC (.m4a) before upload (using native macOS afconvert or ffmpeg), reducing upload bandwidth and latency by up to 90% while leaving lightweight files (.mp3, .m4a $\le 15$ MB) untouched.
• Prices in the Right Unit: tool descriptions, prompts and reports state costs in studio credits when a Studio API key is configured, and in USDC only in wallet (x402) mode, so an A&R paying with credits never sees crypto amounts.
• Dual Authentication: Studio API key (Authorization: Bearer tpt_live_…, prepaid credits) takes priority over the Web3 wallet.
• Automated x402 Payment: Manages the x402 challenge-response cycle (HTTP 402), with the platform wallet and USDC contracts pinned client-side.

⚙️ Configuration & Environment Variables

The MCP server supports Dual Authentication:

📦 Installation & Setup

🤖 Option 1: Claude Desktop (Studio SaaS - Zero Crypto, Recommended for A&R)

Add the server to your claude_desktop_config.json (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "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"
      }
    }
  }
}

Note: Generate your Studio API key in 1 click from your Dashboard at https://tag-per-track.cloud.

⚡ Option 2: Claude Desktop (Web3 x402 USDC on Base)

{
  "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"
      }
    }
  }
}

🌐 Option 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

The server is also listed on the official MCP registry as io.github.Lory97/tag-per-track-mcp.

🔧 MCP Tools

1. analyze_audio

Analyzes an audio file to extract musical metadata tags (BPM, key, scale, moods, genres, instruments), optional lyrics, and AI Origin Integrity (ai_detection). Supports both local binary files and remote URLs.

• Arguments:

  • filePath (string, optional): Path to a local audio file on disk (.mp3, .wav, .ogg, .flac, .m4a, .aac, .aiff). The server validates the format, reads the file and streams it securely.
  • fileUrl (string, optional): Direct URL of the audio file. (Note: At least one of filePath or fileUrl must be provided).
  • extractLyrics (boolean, optional): Set to true to also extract vocal lyrics (2 credits / 0.25 USDC instead of 1 credit / 0.15 USDC).

• Output Structure: Returns comprehensive metadata including:

  • bpm, key, scale, genres, moods, instruments, duration
  • production (lufs, peakDb, clippedRatio), danceability, engagement, approachability, voice.ratio
  • ai_detection / aiDetection (computed on a 12 s core sample):
    • checked: boolean (true when analyzed)
    • isAi: boolean (true if detected as synthetic/AI)
    • confidence: confidence percentage (0-100)
    • verdict: 'HUMAN' | 'AI_GENERATED' | 'UNCERTAIN'
    • status: 'SUCCESS' | 'UNAVAILABLE' | 'SKIPPED'
    • generator / watermarkDetected (optional): identified generator, e.g. a Suno signature in the file metadata
  • arEvaluation (A&R scoring v2.2): tier, audioType, suggestedProfile, marketplaceTags, aiGate, subScores (production, listening, traction, loyalty) and profiles.{discovery,signing,beatmaker} with score, priority and a recommendation code. AI verdicts are graded: ≥ 70 % confidence (or a metadata watermark) blocks the track, 60-69 % flags it, 30-59 % is inconclusive.

2. analyze_audio_with_lyrics

Analyzes an audio file to extract musical metadata, transcribe full vocal lyrics using AI, and evaluate AI Origin Integrity. Supports local audio files and remote URLs.

• Arguments:
  • filePath (string, optional): Path to a local audio file on disk (.mp3, .wav, .ogg, .flac, .m4a, .aac, .aiff).
  • fileUrl (string, optional): Direct URL of the audio file. (Note: At least one of filePath or fileUrl must be provided).

3. analyze_audio_batch

Analyzes multiple audio tracks in parallel (batch processing). Vastly reduces total execution time compared to sequential calls, with resilient partial reporting and AI origin detection on every track.

• Arguments:

  • filePaths (string[], optional): Convenience array of local file paths to analyze in parallel.
  • fileUrls (string[], optional): Convenience array of public URLs to analyze in parallel.
  • tracks (object[], optional): Array of track objects with granular settings:
    • filePath (string, optional)
    • fileUrl (string, optional)
    • extractLyrics (boolean, optional): Per-track lyrics flag.
  • extractLyrics (boolean, optional): Global flag to transcribe vocal lyrics for all tracks in this batch (2 credits / 0.25 USDC per track). Default is false (1 credit / 0.15 USDC per track).
  • concurrency (number, optional): Maximum simultaneous parallel requests (1 to 5, default is 4 to respect API rate limits).

• Output Structure: Returns a summary JSON containing:

  • totalTracks: Total number of tracks submitted.
  • successful: Count of successfully analyzed tracks.
  • failed: Count of failed tracks.
  • results: Detailed array containing status (success or error), metadata (including ai_detection), or error reason for each track.

4. triage_demo_folder

Sorts a local folder of demo submissions in one call, built for the A&R "demo inbox" workflow. Only compact results are returned, so a 20-track folder fits comfortably in the model context.

Pipeline: list the audio files → artist/title from an Artist - Title file name (preferred: tags on demos are often DAW or account defaults), else from the audio tags → paid analyses (bounded concurrency) → one free Spotify lookup per distinct main artist ("Miimii ft Dj Skycee" → "Miimii") → free server-side re-scoring (POST /api/ar-score) with the traction attached → ranking. MCP progress notifications are sent after each track when the client provides a progressToken.

• Arguments:

  • folderPath (string, required): Local folder (absolute or ~/...).
  • profile (string, optional): discovery (default, an unknown artist is never penalized), signing (weighs streaming traction), beatmaker, or auto (beatmaker for instrumentals).
  • extractLyrics (boolean, optional): Also transcribe lyrics (2 credits / 0.25 USDC per track).
  • recursive (boolean, optional): Scan sub-folders.
  • maxTracks (number, optional): Default 25, hard limit 50.
  • lookupArtists (boolean, optional): Spotify traction lookup, default true.
  • dryRun (boolean, optional): List the files, detected artists/titles and the estimated cost without analyzing or charging.
  • concurrency (number, optional): 1 to 5, default 3.

• Cost: 1 credit (0.15 USDC) per analyzed track, 2 credits (0.25 USDC) with lyrics. Failed analyses are not charged. The report states it in the configured unit only (see estimatedCost below).

• Output Structure (one entry per track, best score first, errors last):

{
  "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 (top/high priority), listen (medium), pass (low), ai_flagged (confirmed or suspected AI-generated), error (unreadable or rejected file), not_analyzed (see below).
• Credits exhausted / invalid key: as soon as the API answers "Insufficient studio credits" (HTTP 402) or "Invalid API key" (HTTP 401), the remaining files are not sent. The report then carries halted: { reason, notAnalyzed }, the affected tracks are in the not_analyzed bucket, and only the successful analyses are counted in estimatedCost. The same stop rule applies to analyze_audio_batch (skipped count and haltReason).
• ai.flag: blocked (confirmed AI), suspected (to verify by ear), uncertain, clear, unchecked.
• lyrics.status: ok, approximate (low-confidence transcription reported by the API, typically a language Whisper does not support such as Creole, transcribed phonetically), instrumental, no_vocals_detected or suspect_repetition (a short phrase looping, typical of a Whisper hallucination). lyrics.language is the language detected by Whisper. Only ok lyrics should be quoted.
• The report header gives buckets counts, estimatedCost, scoringVersion, elapsedSeconds and notes (tracks over the limit, artists not found...).
• estimatedCost is expressed in the unit the account pays with: { "label": "8 studio credits", "studioCredits": 8 } with a Studio API key, { "label": "1.2 USDC", "usdc": 1.2 } with a wallet. Both are given only when no authentication is configured.

5. lookup_artist_stats

Retrieves streaming traction and commercial metrics for an artist (Spotify monthly listeners, followers, popularity score, genres) for A&R qualification. Free (no credit or payment). This service is strictly decoupled from the acoustic analysis pipeline; the API caches results (7 days persistent, 24 hours in memory) with graceful fallback.

• Arguments:

  • artist_name (string, required): Stage name of the artist (e.g. "Daft Punk", "Kaytranada").
  • spotify_id (string, optional): Spotify artist ID or open.spotify.com artist URL, to target an exact artist when the name is ambiguous.
  • social_links (string[], optional): Optional social media profile links for future enrichment.

• Output Structure (popularity is null when the provider does not return it: unknown, not zero):

{
  "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": []
}

🤖 Guide & System Prompts for A&R Agents (Hybrid Scoring)

Modern A&R evaluation combines three essential dimensions:

1. Intrinsic Acoustic Profile (BPM, musical key & scale, mood, instrumentation, vocal lyrics).
2. Origin Integrity & AI Verification (detecting human vs synthetic AI-generated music to mitigate copyright and chain-of-title risks).
3. Commercial Momentum & Streaming Traction (Spotify monthly listener volume, follower fan base, popularity index).

🎯 Orchestration Workflow for Autonomous Agents

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. Step 1 — Acoustic & Origin Analysis: Invoke analyze_audio (or analyze_audio_with_lyrics when vocal lyrics transcription is essential) with filePath or fileUrl. This consumes Studio credits (API key mode) or triggers the x402 micro-payment (0.15 or 0.25 USDC on Base), and evaluates musical attributes alongside AI origin integrity (ai_detection) and the A&R evaluation (arEvaluation).
2. Step 2 — Artist Traction Lookup: Whenever the artist's stage name is identifiable (from submission filename, user prompt, or ID3 tags), invoke lookup_artist_stats(artist_name: "...").
3. Step 3 — Consolidation into the Unified A&R Evaluation Matrix: The agent consolidates findings into a standardized Markdown evaluation matrix with the required 7 columns:

📋 Ready-to-Use A&R Agent System Prompt

Here is a turnkey system prompt template to configure an autonomous A&R scouting agent (compatible with Claude Desktop, Cursor, Windsurf, or 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.

📄 License

MIT