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 42 host/couple tools to Claude over stdio (15 reads + 27 writes/actions, confirmation-gated where they mutate). Built on @chrischall/mcp-utils (runMcp, minifiedResult, toolAnnotations, confirmWrite, 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);
                  #   adoptVerifiedTokens() verifies a browser-captured pair on an
                  #   isolated client before adopting it (never the env login,
                  #   never session.json — the tool persists after it succeeds)
  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)
  reorder.ts      # planMoves() — "move these after X" as single-item reorder
                  #   calls (Vibo: source lands after target; null = first)
  brief.ts        # view: "brief" lines (title — date — status, ≤ 120 chars,
                  #   "-- " note lines) in the untrusted-data envelope
  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
    section-manage.ts   # create_section, delete_section, reorder_sections
    lookups.ts          # read-before-write helpers (sections, event perms,
                        #   section song ids, id validation)
    uploads.ts          # set_profile_photo
    session.ts          # capture_session (SSO browser token capture)
    shared.ts           # pagination + confirmWrite (confirmation gate) helpers
    hints.ts            # familyMeta() — context-group `_meta.mint` hints