vibo-mcp 1.4.2 → 1.5.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Vibo (vibodj.com) — plan & manage event music, song requests, ideas, guests, and playlists via natural language",
-    "version": "1.4.2"
+    "version": "1.5.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Vibo",
       "source": "./",
       "description": "MCP server for Vibo — browse & manage events, timeline, songs, the DJ song ideas/questions, guests, and exports to Spotify/Apple Music",
-      "version": "1.4.2",
+      "version": "1.5.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vibo-mcp",
   "displayName": "Vibo",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "MCP server for Vibo (vibodj.com) — plan & manage event music, song requests, ideas, guests, and playlists via natural language",
   "author": {
     "name": "Chris Hall",

package/dist/bundle.js

@@ -31126,7 +31126,7 @@ function toolAnnotations(opts = {}) {
 }
 
 // src/version.ts
-var VERSION = "1.4.2";
+var VERSION = "1.5.0";
 
 // src/client.ts
 import { dirname as dirname2, join as join2 } from "path";
@@ -32082,6 +32082,134 @@ function registerSectionTools(server, client2) {
   );
 }
 
+// src/song-search.ts
+var NON_ORIGINAL_MARKERS = [
+  "karaoke",
+  "cover",
+  "covers",
+  "tribute",
+  "instrumental",
+  "backing track",
+  "made famous by",
+  "in the style of",
+  "piano version",
+  "acoustic version",
+  "lyric video",
+  "lyrics video",
+  "sped up",
+  "slowed",
+  "nightcore",
+  "8 bit"
+];
+var VARIANT_MARKERS = [
+  "remix",
+  "demo",
+  "live at",
+  "live from",
+  "performance",
+  "radio edit",
+  "extended mix",
+  "reprise"
+];
+var UPLOADER_MARKERS = ["karaoke", "cover", "covers", "tribute", "versions", "lyrics", "sing king", "topic"];
+var JUNK_ARTISTS = ["board", "unknown", "various", "various artists", "na", "none"];
+function normalizeName(value) {
+  return value.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[&+]/g, " and ").replace(/[^a-z0-9]+/g, " ").trim().replace(/\s+/g, " ");
+}
+function containsPhrase(normalizedHaystack, phrase) {
+  const needle = normalizeName(phrase);
+  if (!needle) return false;
+  return ` ${normalizedHaystack} `.includes(` ${needle} `);
+}
+function parseSearchQuery(query) {
+  const raw = query.trim();
+  const match = raw.match(/^(.+?)\s+[-–—]\s+(.+)$/);
+  if (!match) return { raw, structured: false };
+  const artist = match[1].trim();
+  const title = match[2].trim();
+  if (!artist || !title) return { raw, structured: false };
+  return { raw, artist, title, structured: true };
+}
+function streamingLinkCount(links) {
+  if (!links) return 0;
+  return [links.spotify, links.appleMusic, links.tidal, links.deezer, links.soundcloud].filter(
+    (l) => typeof l === "string" && l.length > 0
+  ).length;
+}
+function soundcloudHandleMatchesArtist(url2, artist) {
+  const path = url2.replace(/^https?:\/\/(www\.)?soundcloud\.com\//i, "").split("/")[0] ?? "";
+  const handle = normalizeName(path).split(" ").join("");
+  if (!handle) return false;
+  const tokens = normalizeName(artist).split(" ").filter((t) => t.length >= 4);
+  if (!tokens.length) return false;
+  return tokens.some((t) => handle.includes(t));
+}
+function assessSong(song, intended) {
+  const warnings = [];
+  let hard = false;
+  const title = (song.title ?? "").trim();
+  const artist = (song.artist ?? "").trim();
+  const normalizedArtist = normalizeName(artist);
+  const isJunkArtist = JUNK_ARTISTS.includes(normalizedArtist);
+  if (!artist) {
+    warnings.push("Result has no artist field.");
+    hard = true;
+  } else if (isJunkArtist) {
+    warnings.push(`Artist field is placeholder junk ("${artist}"), not a performer name.`);
+    hard = true;
+  } else {
+    const uploader = UPLOADER_MARKERS.find((m) => containsPhrase(normalizedArtist, m));
+    if (uploader) {
+      warnings.push(`Artist field looks like an uploader/channel ("${artist}"), not the performer.`);
+      hard = true;
+    }
+  }
+  if (intended?.artist && artist && !isJunkArtist) {
+    const wanted = normalizeName(intended.artist);
+    if (wanted && !normalizedArtist.includes(wanted) && !wanted.includes(normalizedArtist)) {
+      warnings.push(`Artist is "${artist}", but the query asked for "${intended.artist}".`);
+      hard = true;
+    }
+  }
+  const normalizedTitle = normalizeName(title);
+  const nonOriginal = NON_ORIGINAL_MARKERS.find((m) => containsPhrase(normalizedTitle, m));
+  if (nonOriginal) {
+    warnings.push(`Title contains "${nonOriginal}" \u2014 not the original studio recording.`);
+    hard = true;
+  }
+  const variant = VARIANT_MARKERS.find((m) => containsPhrase(normalizedTitle, m));
+  if (variant) {
+    warnings.push(`Title contains "${variant}" \u2014 an alternate version; confirm it is the one wanted.`);
+  }
+  if (streamingLinkCount(song.links) === 0) {
+    warnings.push("No streaming-service links (YouTube only) \u2014 typical of a re-upload.");
+    hard = true;
+  }
+  const soundcloud = song.links?.soundcloud;
+  const artistForHandle = isJunkArtist ? intended?.artist : artist || intended?.artist;
+  if (soundcloud && artistForHandle && !soundcloudHandleMatchesArtist(soundcloud, artistForHandle)) {
+    warnings.push(`SoundCloud handle does not obviously belong to "${artistForHandle}".`);
+  }
+  const confidence = hard ? "likely-not-original" : warnings.length ? "uncertain" : "likely-original";
+  return { confidence, warnings };
+}
+function annotateSearchResults(results, query, source = "searchField") {
+  const parsed = parseSearchQuery(query);
+  const annotated = results.map((song) => ({ ...song, quality: assessSong(song, parsed) }));
+  const summary = {
+    total: annotated.length,
+    likelyOriginal: annotated.filter((s) => s.quality.confidence === "likely-original").length,
+    flagged: annotated.filter((s) => s.quality.confidence === "likely-not-original").length
+  };
+  let hint;
+  if (source === "searchField" && !parsed.structured) {
+    hint = `Query "${parsed.raw}" is not in "<Artist> - <Title>" form. Vibo's text index ranks covers, karaoke and re-uploads above official recordings for unhyphenated queries. Retry as "<Artist> - <Title>" (space-hyphen-space) before trusting these results.`;
+  } else if (source === "searchField" && summary.total > 0 && summary.likelyOriginal === 0) {
+    hint = 'No result looks like an official recording. Try reversing to "<Title> - <Artist>", searching the title alone and filtering by artist, or source: "spotify".';
+  }
+  return { query: parsed, ...hint ? { hint } : {}, summary, results: annotated };
+}
+
 // src/tools/songs.ts
 function registerSongTools(server, client2) {
   server.registerTool(
@@ -32120,30 +32248,35 @@ function registerSongTools(server, client2) {
   server.registerTool(
     "vibo_search_songs",
     {
-      description: "Search for songs to add to a section. source 'searchField' (default) searches Vibo's catalog; 'spotify' searches your connected Spotify. Returns songUrl/viboSongId/title/artist to pass to vibo_add_song_to_section.",
+      description: `Search for songs to add to a section. ALWAYS query as "<Artist> - <Title>" with a space-hyphen-space separator (e.g. "Ed Sheeran - Thinking Out Loud"). Vibo's default 'searchField' index is a loose text match over a catalog full of YouTube covers, karaoke tracks and re-uploads: the hyphenated form resolves to the official recording, while the same words unhyphenated rank covers and re-uploads above it (measured live \u2014 "Chris Stapleton - Tennessee Whiskey" returned only the official master; without the hyphen, none of the nine results was the original). Each result carries a \`quality\` verdict (likely-original / uncertain / likely-not-original) plus warnings \u2014 check it before adding, and never add a \`likely-not-original\` result without saying so. source 'spotify' searches your connected Spotify (a structured catalog, so the hyphen matters less). Returns songUrl/viboSongId/title/artist for vibo_add_song_to_section.`,
       annotations: toolAnnotations({ title: "Search Vibo songs", readOnly: true }),
       inputSchema: {
         eventId: external_exports.string().describe("Event id (search is scoped to an event/section)."),
         sectionId: external_exports.string().describe("Section id the search is for."),
-        query: external_exports.string().describe("Song or artist to search for."),
+        query: external_exports.string().describe(
+          `Song to search for, as "<Artist> - <Title>" (space-hyphen-space). Use the artist's own stylization \u2014 the index does not fold variants together, and "Dan + Shay - Speechless" returns the official master while "Dan and Shay - Speechless" returns covers and live cuts without it. Artist alone returns only a short popularity-ranked subset of their catalog, so a specific track may be missing entirely. If the hyphenated query looks wrong, retry as "<Title> - <Artist>", then the title alone filtered by artist.`
+        ),
         source: external_exports.enum(["searchField", "spotify"]).optional().describe("Search source (default 'searchField')."),
         limit: external_exports.number().int().min(1).max(50).optional().describe("Max results (default 20).")
       }
     },
     async ({ eventId, sectionId, query, source, limit }) => {
+      const resolvedSource = source ?? "searchField";
       const data = await client2.gql(SEARCH_SONGS, {
         eventId,
         sectionId,
-        filter: { q: query, source: source ?? "searchField" },
+        filter: { q: query, source: resolvedSource },
         limit: limit ?? 20
       });
-      return textResult(data.getSongs);
+      const songs = data.getSongs;
+      if (!Array.isArray(songs)) return textResult(songs);
+      return textResult(annotateSearchResults(songs, query, resolvedSource));
     }
   );
   server.registerTool(
     "vibo_add_song_to_section",
     {
-      description: "Add a song to a section. Pass a song from vibo_search_songs (songUrl is required; include viboSongId/title/artist when known). Confirm-gated.",
+      description: "Add a song to a section. Pass a song from vibo_search_songs (songUrl is required; include viboSongId/title/artist when known). Before adding, check that result's `quality.confidence`: adding a `likely-not-original` result puts a cover, karaoke track or junk-metadata re-upload in front of a live DJ. If nothing looks original, report the closest matches back rather than adding a best guess. Confirm-gated.",
       annotations: toolAnnotations({ title: "Add song to Vibo section", readOnly: false }),
       inputSchema: {
         eventId: external_exports.string().describe("Event id."),

package/dist/song-search.js

@@ -0,0 +1,237 @@
+/**
+ * Search-quality heuristics for Vibo's song catalog.
+ *
+ * Vibo's `searchField` source is a loose text index over a catalog that mixes
+ * official recordings with YouTube-sourced covers, karaoke tracks and
+ * re-uploads. Two consequences, both confirmed live against the production
+ * catalog rather than assumed:
+ *
+ * 1. Querying `"<Artist> - <Title>"` resolves to the official recording;
+ *    dropping the hyphen falls back to loose matching that ranks re-uploads
+ *    first. Observed: `"Chris Stapleton - Tennessee Whiskey"` returned exactly
+ *    one result — the official master, six streaming links. The same words
+ *    without the hyphen returned nine results, *none* of them the original:
+ *    the top hit was a re-upload whose `artist` field read `board`, followed
+ *    by a Sing King karaoke track, three violin/piano covers, an instrumental
+ *    and a techno edit.
+ *
+ * 2. Bad matches are mechanically detectable. Official recordings carry links
+ *    across several streaming services; re-uploads are typically YouTube-only,
+ *    carry a version marker in the title, or put an uploader/channel name in
+ *    the `artist` field.
+ *
+ * A third, subtler trap: the index does not fold artist stylizations together.
+ * `"Dan + Shay - Speechless"` returns the official master; `"Dan and Shay -
+ * Speechless"` returns an acoustic cut, a `- Topic` upload, a live awards
+ * performance and a cover — the official recording is absent entirely. Query
+ * using the artist's own stylization. {@link normalizeName} folds `+`/`&`/`and`
+ * only for *comparing* results, never for building the query.
+ *
+ * These helpers are pure so they can be unit-tested without a network call.
+ */
+/**
+ * Title markers that mean "someone other than the credited artist performed
+ * this". Any hit downgrades the result to `likely-not-original`.
+ *
+ * Matched on whole words, so `demo` does not fire on "Demolition Man". A title
+ * that legitimately contains one of these words as part of its name (P!nk's
+ * "Cover Me in Sunshine") will still be flagged — that bias is deliberate:
+ * a false warning costs a glance, a missed karaoke track reaches the DJ.
+ */
+const NON_ORIGINAL_MARKERS = [
+    'karaoke',
+    'cover',
+    'covers',
+    'tribute',
+    'instrumental',
+    'backing track',
+    'made famous by',
+    'in the style of',
+    'piano version',
+    'acoustic version',
+    'lyric video',
+    'lyrics video',
+    'sped up',
+    'slowed',
+    'nightcore',
+    '8 bit',
+];
+/**
+ * Title markers for a legitimate alternate version of the real artist's
+ * recording. These warn but do not downgrade: a remix or live cut may be
+ * exactly what was asked for, so the caller decides.
+ */
+const VARIANT_MARKERS = [
+    'remix',
+    'demo',
+    'live at',
+    'live from',
+    'performance',
+    'radio edit',
+    'extended mix',
+    'reprise',
+];
+/** Artist-field markers that name an uploader/channel rather than a performer. */
+const UPLOADER_MARKERS = ['karaoke', 'cover', 'covers', 'tribute', 'versions', 'lyrics', 'sing king', 'topic'];
+/**
+ * Artist values seen in the wild that are pure placeholder junk — no performer
+ * name at all. Matched exactly (normalized), never as a substring, so real
+ * artists containing these words are unaffected.
+ */
+const JUNK_ARTISTS = ['board', 'unknown', 'various', 'various artists', 'na', 'none'];
+/**
+ * Fold a name to a comparable form: lowercase, diacritics stripped, `&`/`+`
+ * spelled as `and`, punctuation dropped. So `"Dan + Shay"`, `"Dan & Shay"` and
+ * `"Dan and Shay"` all normalize alike, and `"Amélie"` matches `"Amelie"`.
+ */
+export function normalizeName(value) {
+    return value
+        .normalize('NFD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[&+]/g, ' and ')
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim()
+        .replace(/\s+/g, ' ');
+}
+/**
+ * Whole-word containment over normalized text. Padding both sides with spaces
+ * turns a substring test into a word-boundary test without a built regex.
+ */
+function containsPhrase(normalizedHaystack, phrase) {
+    const needle = normalizeName(phrase);
+    if (!needle)
+        return false;
+    return ` ${normalizedHaystack} `.includes(` ${needle} `);
+}
+/**
+ * Split a search query on the first ` - ` separator (hyphen, en dash or em
+ * dash). Without a separator the query is returned unstructured, which is the
+ * signal to warn the caller that they are about to get loose-match results.
+ */
+export function parseSearchQuery(query) {
+    const raw = query.trim();
+    const match = raw.match(/^(.+?)\s+[-–—]\s+(.+)$/);
+    if (!match)
+        return { raw, structured: false };
+    const artist = match[1].trim();
+    const title = match[2].trim();
+    if (!artist || !title)
+        return { raw, structured: false };
+    return { raw, artist, title, structured: true };
+}
+/** Count links to real streaming services. YouTube is excluded: re-uploads all have one. */
+function streamingLinkCount(links) {
+    if (!links)
+        return 0;
+    return [links.spotify, links.appleMusic, links.tidal, links.deezer, links.soundcloud].filter((l) => typeof l === 'string' && l.length > 0).length;
+}
+/**
+ * True when a SoundCloud URL's handle plausibly belongs to `artist` — i.e. the
+ * handle contains one of the artist's substantial name tokens. Deliberately
+ * loose: `soundcloud.com/elvissonymusic/...` counts for Elvis Presley (a label
+ * account), while `soundcloud.com/jen-prince-602192391/...` does not.
+ */
+function soundcloudHandleMatchesArtist(url, artist) {
+    const path = url.replace(/^https?:\/\/(www\.)?soundcloud\.com\//i, '').split('/')[0] ?? '';
+    const handle = normalizeName(path).split(' ').join('');
+    if (!handle)
+        return false;
+    const tokens = normalizeName(artist)
+        .split(' ')
+        .filter((t) => t.length >= 4);
+    if (!tokens.length)
+        return false;
+    return tokens.some((t) => handle.includes(t));
+}
+/**
+ * Judge one search result, optionally against what the caller asked for.
+ * Passing `intended` (from {@link parseSearchQuery}) enables the strongest
+ * check by far: whether the result's artist is actually the artist requested.
+ */
+export function assessSong(song, intended) {
+    const warnings = [];
+    let hard = false;
+    const title = (song.title ?? '').trim();
+    const artist = (song.artist ?? '').trim();
+    const normalizedArtist = normalizeName(artist);
+    const isJunkArtist = JUNK_ARTISTS.includes(normalizedArtist);
+    if (!artist) {
+        warnings.push('Result has no artist field.');
+        hard = true;
+    }
+    else if (isJunkArtist) {
+        warnings.push(`Artist field is placeholder junk ("${artist}"), not a performer name.`);
+        hard = true;
+    }
+    else {
+        const uploader = UPLOADER_MARKERS.find((m) => containsPhrase(normalizedArtist, m));
+        if (uploader) {
+            warnings.push(`Artist field looks like an uploader/channel ("${artist}"), not the performer.`);
+            hard = true;
+        }
+    }
+    // The strongest available check: does the result credit the artist we asked
+    // for? Substring both ways so "Ed Sheeran" matches "Ed Sheeran & Beyoncé".
+    if (intended?.artist && artist && !isJunkArtist) {
+        const wanted = normalizeName(intended.artist);
+        if (wanted && !normalizedArtist.includes(wanted) && !wanted.includes(normalizedArtist)) {
+            warnings.push(`Artist is "${artist}", but the query asked for "${intended.artist}".`);
+            hard = true;
+        }
+    }
+    const normalizedTitle = normalizeName(title);
+    const nonOriginal = NON_ORIGINAL_MARKERS.find((m) => containsPhrase(normalizedTitle, m));
+    if (nonOriginal) {
+        warnings.push(`Title contains "${nonOriginal}" — not the original studio recording.`);
+        hard = true;
+    }
+    const variant = VARIANT_MARKERS.find((m) => containsPhrase(normalizedTitle, m));
+    if (variant) {
+        warnings.push(`Title contains "${variant}" — an alternate version; confirm it is the one wanted.`);
+    }
+    if (streamingLinkCount(song.links) === 0) {
+        warnings.push('No streaming-service links (YouTube only) — typical of a re-upload.');
+        hard = true;
+    }
+    // Soft signal: only checkable when a SoundCloud link is present.
+    const soundcloud = song.links?.soundcloud;
+    const artistForHandle = isJunkArtist ? intended?.artist : artist || intended?.artist;
+    if (soundcloud && artistForHandle && !soundcloudHandleMatchesArtist(soundcloud, artistForHandle)) {
+        warnings.push(`SoundCloud handle does not obviously belong to "${artistForHandle}".`);
+    }
+    const confidence = hard
+        ? 'likely-not-original'
+        : warnings.length
+            ? 'uncertain'
+            : 'likely-original';
+    return { confidence, warnings };
+}
+/**
+ * Attach a quality verdict to each search result and, when the query was not
+ * in `"<Artist> - <Title>"` form, tell the caller to retry in that form.
+ */
+export function annotateSearchResults(results, query, source = 'searchField') {
+    const parsed = parseSearchQuery(query);
+    const annotated = results.map((song) => ({ ...song, quality: assessSong(song, parsed) }));
+    const summary = {
+        total: annotated.length,
+        likelyOriginal: annotated.filter((s) => s.quality.confidence === 'likely-original').length,
+        flagged: annotated.filter((s) => s.quality.confidence === 'likely-not-original').length,
+    };
+    // The hyphen rule is specific to the loose `searchField` text index; the
+    // Spotify source queries a structured catalog and does not need it.
+    let hint;
+    if (source === 'searchField' && !parsed.structured) {
+        hint =
+            `Query "${parsed.raw}" is not in "<Artist> - <Title>" form. Vibo's text index ranks ` +
+                'covers, karaoke and re-uploads above official recordings for unhyphenated queries. ' +
+                'Retry as "<Artist> - <Title>" (space-hyphen-space) before trusting these results.';
+    }
+    else if (source === 'searchField' && summary.total > 0 && summary.likelyOriginal === 0) {
+        hint =
+            'No result looks like an official recording. Try reversing to "<Title> - <Artist>", ' +
+                'searching the title alone and filtering by artist, or source: "spotify".';
+    }
+    return { query: parsed, ...(hint ? { hint } : {}), summary, results: annotated };
+}

package/dist/tools/songs.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { textResult, toolAnnotations, schemaConfirm } from '@chrischall/mcp-utils';
 import { GET_SECTION_SONGS, SEARCH_SONGS, ADD_SONG_TO_SECTION, TOGGLE_LIKE } from '../gql.js';
+import { annotateSearchResults } from '../song-search.js';
 import { limitSchema, skipSchema, pagination, previewResult } from './shared.js';
 export function registerSongTools(server, client) {
     server.registerTool('vibo_get_section_songs', {
@@ -36,26 +37,54 @@ export function registerSongTools(server, client) {
         return textResult(data.getSectionSongs);
     });
     server.registerTool('vibo_search_songs', {
-        description: "Search for songs to add to a section. source 'searchField' (default) searches Vibo's catalog; 'spotify' searches your connected Spotify. Returns songUrl/viboSongId/title/artist to pass to vibo_add_song_to_section.",
+        description: 'Search for songs to add to a section. ALWAYS query as "<Artist> - <Title>" with a ' +
+            'space-hyphen-space separator (e.g. "Ed Sheeran - Thinking Out Loud"). Vibo\'s default ' +
+            "'searchField' index is a loose text match over a catalog full of YouTube covers, " +
+            'karaoke tracks and re-uploads: the hyphenated form resolves to the official recording, ' +
+            'while the same words unhyphenated rank covers and re-uploads above it (measured live — ' +
+            '"Chris Stapleton - Tennessee Whiskey" returned only the official master; without the ' +
+            'hyphen, none of the nine results was the original). Each result carries a `quality` ' +
+            'verdict (likely-original / uncertain / likely-not-original) plus warnings — check it ' +
+            'before adding, and never add a `likely-not-original` result without saying so. ' +
+            "source 'spotify' searches your connected Spotify (a structured catalog, so the hyphen " +
+            'matters less). Returns songUrl/viboSongId/title/artist for vibo_add_song_to_section.',
         annotations: toolAnnotations({ title: 'Search Vibo songs', readOnly: true }),
         inputSchema: {
             eventId: z.string().describe('Event id (search is scoped to an event/section).'),
             sectionId: z.string().describe('Section id the search is for.'),
-            query: z.string().describe('Song or artist to search for.'),
+            query: z
+                .string()
+                .describe('Song to search for, as "<Artist> - <Title>" (space-hyphen-space). Use the artist\'s ' +
+                'own stylization — the index does not fold variants together, and "Dan + Shay - ' +
+                'Speechless" returns the official master while "Dan and Shay - Speechless" returns ' +
+                'covers and live cuts without it. Artist alone returns only a short ' +
+                'popularity-ranked subset of their catalog, so a specific track may be missing ' +
+                'entirely. If the hyphenated query looks wrong, retry as "<Title> - <Artist>", ' +
+                'then the title alone filtered by artist.'),
             source: z.enum(['searchField', 'spotify']).optional().describe("Search source (default 'searchField')."),
             limit: z.number().int().min(1).max(50).optional().describe('Max results (default 20).'),
         },
     }, async ({ eventId, sectionId, query, source, limit }) => {
+        const resolvedSource = source ?? 'searchField';
         const data = await client.gql(SEARCH_SONGS, {
             eventId,
             sectionId,
-            filter: { q: query, source: source ?? 'searchField' },
+            filter: { q: query, source: resolvedSource },
             limit: limit ?? 20,
         });
-        return textResult(data.getSongs);
+        const songs = data.getSongs;
+        // Vibo returns a bare array; if that ever changes, pass it through untouched
+        // rather than guessing at a shape.
+        if (!Array.isArray(songs))
+            return textResult(songs);
+        return textResult(annotateSearchResults(songs, query, resolvedSource));
     });
     server.registerTool('vibo_add_song_to_section', {
-        description: 'Add a song to a section. Pass a song from vibo_search_songs (songUrl is required; include viboSongId/title/artist when known). Confirm-gated.',
+        description: 'Add a song to a section. Pass a song from vibo_search_songs (songUrl is required; ' +
+            'include viboSongId/title/artist when known). Before adding, check that result\'s ' +
+            '`quality.confidence`: adding a `likely-not-original` result puts a cover, karaoke ' +
+            'track or junk-metadata re-upload in front of a live DJ. If nothing looks original, ' +
+            'report the closest matches back rather than adding a best guess. Confirm-gated.',
         annotations: toolAnnotations({ title: 'Add song to Vibo section', readOnly: false }),
         inputSchema: {
             eventId: z.string().describe('Event id.'),

package/dist/version.js

@@ -2,4 +2,4 @@
 // literal on the line carrying the release marker; every manifest and the MCP
 // server banner import VERSION from here, so there is exactly one place to keep
 // in sync (and one release-please extra-files entry).
-export const VERSION = '1.4.2'; // x-release-please-version
+export const VERSION = '1.5.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibo-mcp",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "mcpName": "io.github.chrischall/vibo-mcp",
   "description": "Vibo (vibodj.com) MCP server for Claude — host/couple event music planning & management. Developed and maintained by AI (Claude Code).",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -60,7 +60,7 @@
     "@cloudflare/workers-types": "^5.20260708.1",
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.2",
-    "agents": "^0.17.3",
+    "agents": "^0.19.0",
     "esbuild": "^0.28.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.2",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/vibo-mcp",
     "source": "github"
   },
-  "version": "1.4.2",
+  "version": "1.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "vibo-mcp",
-      "version": "1.4.2",
+      "version": "1.5.0",
       "transport": {
         "type": "stdio"
       },