deaf-intelligence 1.0.1

package/dist/index.js

@@ -0,0 +1,450 @@
+#!/usr/bin/env node
+/**
+ * DEAF Intelligence — MCP Server
+ *
+ * Spotify career intelligence. Track any artist, build history, get insights.
+ * Spotify deletes data after 2 years. We keep it forever.
+ *
+ * https://deaf.audio
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as z from "zod/v4";
+import * as path from "path";
+import * as fs from "fs";
+import Database from "./db.js";
+import { fullScrape } from "./scraper.js";
+// Data directory — ~/.artist-os/ by default
+const DATA_DIR = process.env.ARTIST_OS_DATA_DIR || path.join(process.env.HOME || "~", ".artist-os");
+if (!fs.existsSync(DATA_DIR)) {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+}
+function getDbPath(artistId) {
+    return path.join(DATA_DIR, `${artistId}.db`);
+}
+function dbExists(artistId) {
+    return fs.existsSync(getDbPath(artistId));
+}
+function openDb(artistId) {
+    return new Database(getDbPath(artistId), { readonly: true });
+}
+function extractArtistId(input) {
+    const match = input.match(/artist[/:]([a-zA-Z0-9]+)/);
+    return match ? match[1] : input.trim();
+}
+// Create MCP server
+const server = new McpServer({
+    name: "deaf-intelligence",
+    version: "1.0.1",
+    description: "Your personal Spotify archivist. Tracks everything, forgets nothing.",
+});
+// === TOOL: track_artist ===
+server.registerTool("track_artist", {
+    description: "Start tracking a Spotify artist. Give me a Spotify URL or artist ID. I'll scrape their full profile — all tracks with play counts, cities, related artists — and store everything locally. From this moment, you're building a history that Spotify will delete but we won't.",
+    inputSchema: {
+        spotify_url_or_id: z.string().describe("Spotify artist URL (open.spotify.com/artist/...) or artist ID"),
+    },
+}, async ({ spotify_url_or_id }) => {
+    const artistId = extractArtistId(spotify_url_or_id);
+    const dbPath = getDbPath(artistId);
+    try {
+        const result = await fullScrape(artistId, dbPath);
+        const o = result.overview;
+        const own = result.tracks.filter(t => !t.role.startsWith("FEAT on"));
+        const feats = result.tracks.filter(t => t.role.startsWith("FEAT on"));
+        let text = `# Now tracking: ${o.name}\n\n`;
+        text += `**${o.monthly_listeners.toLocaleString()}** monthly listeners · **${o.followers.toLocaleString()}** followers`;
+        if (o.verified)
+            text += ` · Verified`;
+        text += `\n\n`;
+        text += `**${result.tracks.length}** tracks · **${result.total_streams.toLocaleString()}** total streams\n`;
+        text += `${own.length} own songs · ${feats.length} features\n\n`;
+        if (o.top_cities.length) {
+            text += `## Top Cities\n`;
+            for (const c of o.top_cities) {
+                text += `- ${c.city}, ${c.country}: ${c.listeners.toLocaleString()}\n`;
+            }
+            text += `\n`;
+        }
+        text += `## Top Tracks\n`;
+        const sorted = [...result.tracks].sort((a, b) => b.playcount - a.playcount);
+        for (const t of sorted.slice(0, 10)) {
+            text += `- ${t.title}: ${t.playcount.toLocaleString()} [${t.role}]\n`;
+        }
+        if (sorted.length > 10)
+            text += `- ...and ${sorted.length - 10} more\n`;
+        text += `\n**${result.images.downloaded}** images downloaded`;
+        if (result.images.skipped)
+            text += ` (${result.images.skipped} already cached)`;
+        if (result.s4a)
+            text += `\n**S4A data included** — saves, demographics, segments, playlists`;
+        text += `\nData stored in \`${dbPath}\`. Run daily to build history.`;
+        return { content: [{ type: "text", text }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Error tracking artist: ${e.message}` }], isError: true };
+    }
+});
+// === TOOL: show_stats ===
+server.registerTool("show_stats", {
+    description: "Show current stats and history for a tracked artist.",
+    inputSchema: { artist_id: z.string().describe("Spotify artist ID") },
+}, async ({ artist_id }) => {
+    const aid = extractArtistId(artist_id);
+    if (!dbExists(aid)) {
+        return { content: [{ type: "text", text: `Not tracked yet. Use track_artist first.` }], isError: true };
+    }
+    const db = openDb(aid);
+    const artist = db.prepare("SELECT name, verified, bio, brand_color FROM artist WHERE spotify_id = ?").get(aid);
+    const metrics = db.prepare("SELECT metric_name, metric_value, delta_value, delta_pct, scraped_at FROM daily_stats WHERE artist_id = ? ORDER BY scraped_at DESC").all(aid);
+    const totalStreams = db.prepare("SELECT SUM(play_count) as total FROM song_snapshots WHERE artist_id = ? AND scraped_at = (SELECT MAX(scraped_at) FROM song_snapshots WHERE artist_id = ?)").get(aid, aid);
+    const trackCount = db.prepare("SELECT COUNT(*) as c FROM tracks WHERE artist_id = ?").get(aid);
+    const days = db.prepare("SELECT COUNT(DISTINCT date(scraped_at, 'unixepoch')) as d FROM daily_stats WHERE artist_id = ?").get(aid);
+    const cities = db.prepare("SELECT location_name, listener_count FROM locations WHERE artist_id = ? ORDER BY scraped_at DESC, listener_count DESC LIMIT 5").all(aid);
+    const playlists = db.prepare("SELECT DISTINCT playlist_name, playlist_owner FROM discovered_on WHERE artist_id = ? ORDER BY scraped_at DESC LIMIT 10").all(aid);
+    const links = db.prepare("SELECT link_name, link_url FROM external_links WHERE artist_id = ? ORDER BY link_name").all(aid);
+    const latest = {};
+    const history = {};
+    for (const row of metrics) {
+        if (!latest[row.metric_name])
+            latest[row.metric_name] = row;
+        if (!history[row.metric_name])
+            history[row.metric_name] = [];
+        history[row.metric_name].push(row);
+    }
+    let text = `# ${artist?.name || aid}`;
+    if (artist?.verified)
+        text += ` · Verified`;
+    text += `\n\n`;
+    if (artist?.bio)
+        text += `> ${artist.bio.slice(0, 200)}\n\n`;
+    text += `Tracking for **${days?.d || 1}** day(s)`;
+    if (artist?.brand_color)
+        text += ` · Brand color: ${artist.brand_color}`;
+    text += `\n\n`;
+    text += `| Metric | Value | Change |\n|--------|-------|--------|\n`;
+    const ml = latest.monthly_listeners;
+    if (ml) {
+        const delta = ml.delta_value ? ` ${ml.delta_value > 0 ? "+" : ""}${Math.round(ml.delta_value).toLocaleString()} (${ml.delta_pct?.toFixed(1)}%)` : "—";
+        text += `| Monthly Listeners | ${Math.round(ml.metric_value).toLocaleString()} | ${delta} |\n`;
+    }
+    const fol = latest.followers;
+    if (fol)
+        text += `| Followers | ${Math.round(fol.metric_value).toLocaleString()} | — |\n`;
+    const wr = latest.world_rank;
+    if (wr && wr.metric_value > 0)
+        text += `| World Rank | #${Math.round(wr.metric_value).toLocaleString()} | — |\n`;
+    text += `| Total Streams | ${totalStreams?.total?.toLocaleString() || "?"} | — |\n`;
+    text += `| Tracks | ${trackCount?.c || "?"} | — |\n`;
+    if (cities.length) {
+        text += `\n## Top Cities\n`;
+        for (const c of cities)
+            text += `- ${c.location_name}: ${c.listener_count?.toLocaleString()}\n`;
+    }
+    if (playlists.length) {
+        text += `\n## Discovered On\n`;
+        for (const p of playlists)
+            text += `- ${p.playlist_name}${p.playlist_owner ? ` (by ${p.playlist_owner})` : ""}\n`;
+    }
+    if (links.length) {
+        text += `\n## Links\n`;
+        for (const l of links)
+            text += `- ${l.link_name}: ${l.link_url}\n`;
+    }
+    if ((days?.d || 0) > 1) {
+        text += `\n## Trend (${days.d} days)\n`;
+        for (const metric of ["monthly_listeners", "followers"]) {
+            const h = history[metric];
+            if (h?.length > 1) {
+                const oldest = h[h.length - 1].metric_value;
+                const newest = h[0].metric_value;
+                const change = newest - oldest;
+                const pct = oldest > 0 ? ((change / oldest) * 100).toFixed(1) : "?";
+                text += `- ${metric}: ${Math.round(oldest).toLocaleString()} → ${Math.round(newest).toLocaleString()} (${change > 0 ? "+" : ""}${Math.round(change).toLocaleString()}, ${pct}%)\n`;
+            }
+        }
+    }
+    db.close();
+    return { content: [{ type: "text", text }] };
+});
+// === TOOL: show_tracks ===
+server.registerTool("show_tracks", {
+    description: "Show all tracks with play counts, velocity, and artist roles.",
+    inputSchema: {
+        artist_id: z.string().describe("Spotify artist ID"),
+        sort_by: z.enum(["playcount", "velocity", "title", "date"]).default("playcount").describe("Sort order"),
+    },
+}, async ({ artist_id, sort_by }) => {
+    const aid = extractArtistId(artist_id);
+    if (!dbExists(aid)) {
+        return { content: [{ type: "text", text: `Not tracked yet.` }], isError: true };
+    }
+    const db = openDb(aid);
+    const artist = db.prepare("SELECT name FROM artist WHERE spotify_id = ?").get(aid);
+    const orderClause = sort_by === "velocity" ? "COALESCE(s.delta_value, 0) DESC"
+        : sort_by === "title" ? "s.track_title ASC"
+            : sort_by === "date" ? "t.release_year DESC, t.release_date DESC"
+                : "s.play_count DESC";
+    const tracks = db.prepare(`
+      SELECT s.track_title, s.play_count, s.delta_value, s.delta_pct, t.release_date, t.release_year, t.release_type, t.role
+      FROM song_snapshots s
+      LEFT JOIN tracks t ON s.track_id = t.spotify_id AND s.artist_id = t.artist_id
+      WHERE s.artist_id = ?
+      AND s.scraped_at = (SELECT MAX(scraped_at) FROM song_snapshots WHERE artist_id = ?)
+      ORDER BY ${orderClause}
+    `).all(aid, aid);
+    let total = 0;
+    let text = `# ${artist?.name || aid} — ${tracks.length} tracks\n\n`;
+    text += `| # | Track | Streams | Δ/day | Role | Type | Released |\n`;
+    text += `|---|-------|---------|-------|------|------|----------|\n`;
+    tracks.forEach((t, i) => {
+        total += t.play_count || 0;
+        const delta = t.delta_value != null ? `${t.delta_value > 0 ? "+" : ""}${t.delta_value.toLocaleString()}` : "—";
+        const released = t.release_date ? t.release_date.slice(0, 10) : (t.release_year || "?");
+        text += `| ${i + 1} | ${t.track_title} | ${t.play_count?.toLocaleString()} | ${delta} | ${t.role || "?"} | ${t.release_type || "?"} | ${released} |\n`;
+    });
+    text += `\n**Total: ${total.toLocaleString()} streams**\n`;
+    db.close();
+    return { content: [{ type: "text", text }] };
+});
+// === TOOL: show_cities ===
+server.registerTool("show_cities", {
+    description: "Show top cities where the artist's listeners are.",
+    inputSchema: { artist_id: z.string().describe("Spotify artist ID") },
+}, async ({ artist_id }) => {
+    const aid = extractArtistId(artist_id);
+    if (!dbExists(aid))
+        return { content: [{ type: "text", text: "Not tracked yet." }], isError: true };
+    const db = openDb(aid);
+    const cities = db.prepare("SELECT location_name, listener_count FROM locations WHERE artist_id = ? ORDER BY scraped_at DESC, listener_count DESC LIMIT 10").all(aid);
+    db.close();
+    let text = "## Top Cities\n\n";
+    for (const c of cities)
+        text += `- ${c.location_name}: ${c.listener_count?.toLocaleString()} listeners\n`;
+    return { content: [{ type: "text", text }] };
+});
+// === TOOL: show_related ===
+server.registerTool("show_related", {
+    description: "Show related artists.",
+    inputSchema: { artist_id: z.string().describe("Spotify artist ID") },
+}, async ({ artist_id }) => {
+    const aid = extractArtistId(artist_id);
+    if (!dbExists(aid))
+        return { content: [{ type: "text", text: "Not tracked yet." }], isError: true };
+    const db = openDb(aid);
+    const related = db.prepare("SELECT DISTINCT related_name FROM related_artists WHERE artist_id = ? ORDER BY scraped_at DESC LIMIT 20").all(aid);
+    db.close();
+    let text = "## Related Artists\n\n";
+    for (const r of related)
+        text += `- ${r.related_name}\n`;
+    return { content: [{ type: "text", text }] };
+});
+// === TOOL: list_artists ===
+server.registerTool("list_artists", {
+    description: "List all artists currently being tracked.",
+    inputSchema: {},
+}, async () => {
+    const files = fs.readdirSync(DATA_DIR).filter(f => f.endsWith(".db"));
+    if (!files.length)
+        return { content: [{ type: "text", text: "No artists tracked yet. Use track_artist to start." }] };
+    let text = "## Tracked Artists\n\n";
+    for (const file of files) {
+        const aid = file.replace(".db", "");
+        try {
+            const db = new Database(path.join(DATA_DIR, file), { readonly: true });
+            const artist = db.prepare("SELECT name FROM artist LIMIT 1").get();
+            const days = db.prepare("SELECT COUNT(DISTINCT date(scraped_at, 'unixepoch')) as d FROM daily_stats").get();
+            const tracks = db.prepare("SELECT COUNT(*) as c FROM tracks").get();
+            const total = db.prepare("SELECT SUM(play_count) as t FROM song_snapshots WHERE scraped_at = (SELECT MAX(scraped_at) FROM song_snapshots)").get();
+            text += `- **${artist?.name || aid}** — ${tracks?.c || 0} tracks, ${total?.t?.toLocaleString() || "?"} streams, ${days?.d || 0} days tracked\n`;
+            db.close();
+        }
+        catch {
+            text += `- ${aid} (error reading)\n`;
+        }
+    }
+    return { content: [{ type: "text", text }] };
+});
+// === TOOL: run_scrape ===
+server.registerTool("run_scrape", {
+    description: "Manually trigger a fresh scrape for a tracked artist. Adds new daily snapshot to the database.",
+    inputSchema: { artist_id: z.string().describe("Spotify artist ID") },
+}, async ({ artist_id }) => {
+    const aid = extractArtistId(artist_id);
+    const dbPath = getDbPath(aid);
+    try {
+        const result = await fullScrape(aid, dbPath);
+        const text = `Scrape complete for ${result.overview.name}.\n` +
+            `${result.tracks.length} tracks, ${result.total_streams.toLocaleString()} total streams.\n` +
+            `ML: ${result.overview.monthly_listeners.toLocaleString()} · Followers: ${result.overview.followers.toLocaleString()}`;
+        return { content: [{ type: "text", text }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Scrape error: ${e.message}` }], isError: true };
+    }
+});
+// === TOOL: show_insights ===
+server.registerTool("show_insights", {
+    description: "Pre-computed intelligence for a tracked artist. Lifetime velocity per track, release cadence, catalog health, solo vs feature performance, geographic concentration, projected milestones, and actionable recommendations. Works from the very first scrape — no history needed.",
+    inputSchema: { artist_id: z.string().describe("Spotify artist ID") },
+}, async ({ artist_id }) => {
+    const aid = extractArtistId(artist_id);
+    if (!dbExists(aid))
+        return { content: [{ type: "text", text: "Not tracked yet." }], isError: true };
+    const db = openDb(aid);
+    const artist = db.prepare("SELECT name FROM artist WHERE spotify_id = ?").get(aid);
+    const now = Math.floor(Date.now() / 1000);
+    // All tracks with release dates and latest play counts
+    const tracks = db.prepare(`
+      SELECT t.title, t.release_date, t.role, t.release_type,
+        s.play_count, s.track_id
+      FROM tracks t
+      JOIN song_snapshots s ON s.track_id = t.spotify_id AND s.artist_id = t.artist_id
+      WHERE t.artist_id = ?
+      AND s.scraped_at = (SELECT MAX(scraped_at) FROM song_snapshots WHERE artist_id = ?)
+      ORDER BY s.play_count DESC
+    `).all(aid, aid);
+    const cities = db.prepare("SELECT location_name, listener_count FROM locations WHERE artist_id = ? ORDER BY scraped_at DESC, listener_count DESC LIMIT 10").all(aid);
+    const totalStreams = tracks.reduce((s, t) => s + (t.play_count || 0), 0);
+    const insights = [];
+    for (const t of tracks) {
+        if (!t.release_date || !t.play_count)
+            continue;
+        const releaseTs = new Date(t.release_date).getTime() / 1000;
+        const days = Math.max(1, Math.floor((now - releaseTs) / 86400));
+        insights.push({
+            title: t.title, streams: t.play_count, days,
+            velocity: t.play_count / days,
+            share: totalStreams > 0 ? (t.play_count / totalStreams) * 100 : 0,
+            role: t.role || "?", release_date: t.release_date.slice(0, 10),
+        });
+    }
+    // Sort by velocity for age-normalized ranking
+    const byVelocity = [...insights].sort((a, b) => b.velocity - a.velocity);
+    let text = `# ${artist?.name || aid} — Intelligence Report\n\n`;
+    // --- Velocity ranking (age-normalized) ---
+    text += `## Track Velocity (streams/day since release)\n\n`;
+    text += `| # | Track | Streams/day | Total | Age (days) | Share | Role |\n`;
+    text += `|---|-------|-------------|-------|------------|-------|------|\n`;
+    for (let i = 0; i < byVelocity.length; i++) {
+        const t = byVelocity[i];
+        text += `| ${i + 1} | ${t.title} | **${t.velocity.toFixed(1)}** | ${t.streams.toLocaleString()} | ${t.days} | ${t.share.toFixed(1)}% | ${t.role} |\n`;
+    }
+    // --- Catalog health ---
+    text += `\n## Catalog Health\n\n`;
+    if (byVelocity.length > 0) {
+        const top1Share = byVelocity.length > 0 ? insights.sort((a, b) => b.streams - a.streams)[0]?.share : 0;
+        const top3Share = insights.sort((a, b) => b.streams - a.streams).slice(0, 3).reduce((s, t) => s + t.share, 0);
+        text += `- **Top track concentration:** ${top1Share.toFixed(1)}% of all streams`;
+        if (top1Share > 30)
+            text += ` ⚠️ High dependency on single track`;
+        text += `\n`;
+        text += `- **Top 3 concentration:** ${top3Share.toFixed(1)}% of all streams`;
+        if (top3Share > 70)
+            text += ` ⚠️ Catalog too top-heavy`;
+        text += `\n`;
+        // Old vs new split (6 months = 180 days)
+        const fresh = insights.filter(t => t.days <= 180);
+        const catalog = insights.filter(t => t.days > 180);
+        const freshStreams = fresh.reduce((s, t) => s + t.streams, 0);
+        const catalogStreams = catalog.reduce((s, t) => s + t.streams, 0);
+        const freshPct = totalStreams > 0 ? (freshStreams / totalStreams) * 100 : 0;
+        text += `- **Fresh (<6mo):** ${fresh.length} tracks, ${freshPct.toFixed(1)}% of streams\n`;
+        text += `- **Catalog (>6mo):** ${catalog.length} tracks, ${(100 - freshPct).toFixed(1)}% of streams\n`;
+    }
+    // --- Solo vs Feature ---
+    text += `\n## Solo vs Feature Performance\n\n`;
+    const solo = insights.filter(t => t.role === "SOLO");
+    const feat = insights.filter(t => t.role.startsWith("ft."));
+    const featOn = insights.filter(t => t.role.startsWith("FEAT on"));
+    const avg = (arr) => arr.length ? arr.reduce((s, t) => s + t.velocity, 0) / arr.length : 0;
+    text += `| Type | Tracks | Avg streams/day | Total streams |\n`;
+    text += `|------|--------|-----------------|---------------|\n`;
+    if (solo.length)
+        text += `| Solo | ${solo.length} | ${avg(solo).toFixed(1)} | ${solo.reduce((s, t) => s + t.streams, 0).toLocaleString()} |\n`;
+    if (feat.length)
+        text += `| ft. (own + guest) | ${feat.length} | ${avg(feat).toFixed(1)} | ${feat.reduce((s, t) => s + t.streams, 0).toLocaleString()} |\n`;
+    if (featOn.length)
+        text += `| Featured on others | ${featOn.length} | ${avg(featOn).toFixed(1)} | ${featOn.reduce((s, t) => s + t.streams, 0).toLocaleString()} |\n`;
+    // --- Release cadence ---
+    text += `\n## Release Cadence\n\n`;
+    const dates = insights.map(t => t.release_date).sort();
+    if (dates.length >= 2) {
+        const gaps = [];
+        for (let i = 1; i < dates.length; i++) {
+            const d1 = new Date(dates[i - 1]).getTime();
+            const d2 = new Date(dates[i]).getTime();
+            gaps.push(Math.round((d2 - d1) / 86400000));
+        }
+        const avgGap = gaps.reduce((s, g) => s + g, 0) / gaps.length;
+        const lastRelease = dates[dates.length - 1];
+        const daysSinceLast = Math.floor((now - new Date(lastRelease).getTime() / 1000) / 86400);
+        text += `- **Average gap:** ${Math.round(avgGap)} days between releases\n`;
+        text += `- **Last release:** ${lastRelease} (${daysSinceLast} days ago)`;
+        if (daysSinceLast > avgGap * 1.5)
+            text += ` ⚠️ Overdue (${Math.round(avgGap * 1.5 - daysSinceLast)} days past average)`;
+        text += `\n`;
+        text += `- **Shortest gap:** ${Math.min(...gaps)} days · **Longest:** ${Math.max(...gaps)} days\n`;
+    }
+    else {
+        text += `- Not enough releases to calculate cadence\n`;
+    }
+    // --- Geographic concentration ---
+    text += `\n## Geographic Concentration\n\n`;
+    if (cities.length >= 2) {
+        const totalCity = cities.reduce((s, c) => s + (c.listener_count || 0), 0);
+        const topCity = cities[0];
+        const topPct = totalCity > 0 ? ((topCity.listener_count || 0) / totalCity) * 100 : 0;
+        text += `- **Top city:** ${topCity.location_name} — ${topPct.toFixed(0)}% of top-city listeners`;
+        if (topPct > 50)
+            text += ` (heavily concentrated)`;
+        text += `\n`;
+        for (const c of cities) {
+            const pct = totalCity > 0 ? ((c.listener_count || 0) / totalCity) * 100 : 0;
+            text += `- ${c.location_name}: ${c.listener_count?.toLocaleString()} (${pct.toFixed(1)}%)\n`;
+        }
+    }
+    // --- Projected milestones ---
+    text += `\n## Projected Milestones\n\n`;
+    const milestones = [10000, 50000, 100000, 500000, 1000000];
+    const projections = [];
+    for (const t of byVelocity.slice(0, 5)) {
+        for (const m of milestones) {
+            if (t.streams < m && t.velocity > 0) {
+                const daysToGo = Math.ceil((m - t.streams) / t.velocity);
+                const targetDate = new Date(Date.now() + daysToGo * 86400000).toISOString().slice(0, 10);
+                projections.push(`- **${t.title}** → ${(m / 1000).toFixed(0)}k streams by ~${targetDate} (${daysToGo} days at ${t.velocity.toFixed(1)}/day)`);
+                break; // Only show next milestone per track
+            }
+        }
+    }
+    if (projections.length) {
+        text += projections.join("\n") + "\n";
+    }
+    else {
+        text += `- All top tracks already past major milestones\n`;
+    }
+    // --- Best performer recommendation ---
+    text += `\n## Recommendations\n\n`;
+    if (byVelocity.length > 0) {
+        text += `- **Push:** ${byVelocity[0].title} (${byVelocity[0].velocity.toFixed(1)} streams/day — highest velocity)\n`;
+        if (byVelocity.length > 1) {
+            const newest = [...insights].sort((a, b) => a.days - b.days)[0];
+            if (newest.title !== byVelocity[0].title) {
+                text += `- **Watch:** ${newest.title} (newest release, ${newest.days} days old, ${newest.velocity.toFixed(1)}/day)\n`;
+            }
+        }
+        const topHeavy = insights.sort((a, b) => b.streams - a.streams)[0];
+        if (topHeavy.share > 30) {
+            text += `- **Risk:** ${topHeavy.title} holds ${topHeavy.share.toFixed(0)}% of all streams — diversify catalog\n`;
+        }
+    }
+    db.close();
+    return { content: [{ type: "text", text }] };
+});
+// Start
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/dist/scraper.d.ts

@@ -0,0 +1,111 @@
+export declare function getAnonymousToken(artistId: string): Promise<string>;
+export interface ArtistOverview {
+    artist_id: string;
+    name: string;
+    verified: boolean;
+    bio: string | null;
+    profile_image: string | null;
+    header_image: string | null;
+    gallery_images: string[];
+    brand_color: string | null;
+    monthly_listeners: number;
+    followers: number;
+    world_rank: number;
+    top_cities: {
+        city: string;
+        country: string;
+        listeners: number;
+    }[];
+    top_tracks: {
+        track_id: string;
+        title: string;
+        playcount: number;
+        artists: string[];
+    }[];
+    related_artists: {
+        name: string;
+        id: string;
+        followers: number;
+    }[];
+    discovered_on: {
+        name: string;
+        owner: string;
+    }[];
+    external_links: {
+        name: string;
+        url: string;
+    }[];
+    latest_release: {
+        name: string;
+        type: string;
+        label: string;
+        date: string;
+    } | null;
+    singles_count: number;
+    albums_count: number;
+}
+export declare function getArtistOverview(token: string, artistId: string): Promise<ArtistOverview>;
+export interface TrackData {
+    track_id: string;
+    title: string;
+    playcount: number;
+    popularity: number;
+    artists: string[];
+    artist_ids: string[];
+    role: string;
+    album_name: string;
+    album_id: string;
+    release_date: string;
+    release_type: string;
+    cover_art: string | null;
+}
+export declare function getAllTracks(token: string, artistId: string): Promise<TrackData[]>;
+export declare function storeData(dbPath: string, overview: ArtistOverview, tracks: TrackData[]): void;
+export declare function downloadImages(artistId: string, overview: ArtistOverview, tracks: TrackData[], dataDir: string): Promise<{
+    downloaded: number;
+    skipped: number;
+}>;
+export declare function generateWorkbook(dbPath: string, dataDir: string, s4a?: S4AData | null): Promise<void>;
+export declare function connectS4A(artistId: string): Promise<{
+    success: boolean;
+    name?: string;
+    error?: string;
+}>;
+export declare function hasS4ASession(): boolean;
+export interface S4AData {
+    gender?: any;
+    genderByAge?: any;
+    topCities?: any;
+    locations?: any;
+    segments?: any;
+    audienceStats?: any;
+    catalog?: any;
+    playlists?: {
+        curated?: any;
+        listener?: any;
+        personalized?: any;
+    };
+    upcoming?: any;
+    videos?: any;
+    accountOwner?: any;
+    permissions?: any;
+    canvasPermissions?: any;
+    campaignEligibility?: any;
+    teamMembership?: any;
+    perSong?: Record<string, any>;
+}
+export declare function scrapeS4ADirect(artistId: string): Promise<S4AData | null>;
+export declare function scrapeS4A(artistId: string, outputDir: string): Promise<{
+    files: number;
+}>;
+export interface ScrapeResult {
+    overview: ArtistOverview;
+    tracks: TrackData[];
+    total_streams: number;
+    images: {
+        downloaded: number;
+        skipped: number;
+    };
+    s4a: S4AData | null;
+}
+export declare function fullScrape(artistId: string, dbPath?: string): Promise<ScrapeResult>;