vibo-mcp: Instructions file for Claude Code

vibo-mcp

MCP server for Vibo. Wraps the Vibo consumer GraphQL API (https://api.vibodj.com/v2/graphql) and exposes 39 host/couple tools to Claude over stdio (15 reads + 24 writes/actions, confirm-gated where they mutate). Built on @chrischall/mcp-utils (runMcp, textResult, toolAnnotations, schemaConfirm, error classes).

Commands

npm run build          # tsc + esbuild bundle → dist/index.js + dist/bundle.js
npm test               # vitest run
npm run test:watch     # vitest watch
npm run test:coverage  # vitest run --coverage (v8 reporter, no thresholds)

Run locally (requires built dist/ + credentials):

[email protected] VIBO_PASSWORD=… node dist/index.js

Tool naming

All tools are prefixed vibo_ (e.g. vibo_list_sections, vibo_add_song_to_section).

Architecture

src/
  version.ts      # single source of truth for VERSION (x-release-please-version)
  index.ts        # entry — runMcp({ name, version, banner, tools })
  client.ts       # ViboClient — GraphQL POST w/ x-token, deferred config error,
                  #   single-flight login + refresh-on-expiry + replay-once;
                  #   gqlUpload() for multipart (Upload scalar); setTokens() for
                  #   adopting a browser-captured session
  auth.ts         # captureViboSession() — fetchproxy browser-bridge token capture (SSO)
  session-store.ts# persist {accessToken,refreshToken} to ~/.vibo-mcp/session.json (0600)
  gql.ts          # all GraphQL operation documents (selections from introspection)
  song-search.ts  # pure search-quality heuristics — parseSearchQuery, assessSong,
                  #   annotateSearchResults; grades each search hit
                  #   likely-original / uncertain / likely-not-original
  tools/
    profile.ts          # vibo_get_me, vibo_healthcheck
    events.ts           # list_events, get_event, join_event, leave_event, create_event_contact
    sections.ts         # vibo_list_sections
    songs.ts            # get_section_songs, search_songs, add_song_to_section, toggle_song_like
    playlists.ts        # get_playlists, get_playlist_songs, export_event_to_{spotify,apple_music}
    notifications.ts    # list_notifications, get_notifications_count, mark_notifications_read
    questions.ts        # list_section_questions, answer_question (incl. image/file uploads)
    song-management.ts  # remove_song_from_section, update_song, move_song, reorder_songs
    comments.ts         # comment_on_song/section, delete_song/section_comment
    ideas.ts            # list_section_song_ideas, list_song_ideas_songs
    imports.ts          # import_playlist_to_section
    collaboration.ts    # list_event_users, invite_users, change_user_role, remove_user
    section-edit.ts     # update_section
    uploads.ts          # set_profile_photo
    session.ts          # capture_session (SSO browser token capture)
    shared.ts           # pagination + confirm-preview helpers