Juicebox MCP

Ein lokaler MCP-Server, der deine Juicebox-Sourcing-Daten in Claude einliest – gespeicherte Suchen und ihre bewerteten Ergebnisse – und dabei deine eigene angemeldete Juicebox-Sitzung verwendet.

Läuft vollständig auf deinem Rechner. Deine Sitzung verlässt ihn nie, und jeder Aufruf erfolgt als du, auf deinem eigenen Sitzplatz.

Lesevorgänge kosten keine Export-Credits. Alles, was die Lese-Tools zurückgeben, stammt von derselben freien Oberfläche, die auch die Suchergebnisseite bereits rendert. Ein Tool schreibt, und sagt das auch: jb_run_search erstellt eine echte gespeicherte Suche in deinem Workspace.

Installation

Option A – Desktop-Erweiterung (am einfachsten)

Lade juicebox-mcp.mcpb von Releases herunter und doppelklicke dann darauf, oder ziehe es in Claude Desktop → Einstellungen → Erweiterungen.

Es gibt keinen API-Schlüssel zum Einfügen. Nach der Installation führe die einmaligen Browser-Schritte unten aus.

Option B – aus dem Quellcode

git clone https://github.com/jnot807/juicebox-mcp.git
cd juicebox-mcp
npm install          # also downloads the Chromium build (see note)
npm run login        # a real browser opens — sign in to Juicebox yourself
npm run check        # proves the session works headless

Registriere es dann bei Claude Code:

claude mcp add -s user juicebox -- node "$(pwd)/server.js"

-s user macht es in jeder Sitzung verfügbar; ohne diese Option ist die Registrierung auf das Verzeichnis beschränkt, in dem du es zufällig ausgeführt hast.

Der einmalige Browser-Download

Dies treibt ein echtes Chromium an, und diese Binärdatei ist nicht Teil von node_modules – es ist ein einmaliger Download von etwa 500 MB in einen gemeinsamen Cache (~/Library/Caches/ms-playwright auf macOS).

npm install lädt es automatisch über einen Postinstall-Schritt herunter. Benutzer der Desktop-Erweiterung müssen es einmal von Hand ausführen, da eine Erweiterung node_modules bündelt, aber nicht diesen Cache:

npx patchright install chromium

Wenn es fehlt, teilt dir der Server das in einfacher Sprache mit, anstatt einen Stack-Trace über eine fehlende ausführbare Datei zu werfen.

Anmelden

Die Authentifizierung ist eine echte Anmeldung, kein Schlüssel. npm run login öffnet ein Browserfenster; melde dich wie gewohnt bei Juicebox an. Die Sitzung wird dann in session/ gespeichert (gitignored, chmod 600) und headless wiederverwendet.

Melde dich erneut an, wenn npm run check fehlschlägt – Sitzungen laufen ab.

Tools

experience[] ist der einzige Weg, vergangene Arbeitgeber zu sehen: Die API-Payload enthält nur den aktuellen, daher sind Alumni eines Zielunternehmens ohne sie unsichtbar.

Welches Projekt es standardmäßig liest

Nichts ist fest verdrahtet. Bei der Anmeldung lädt eine Sonde /projects, was in ein Projekt umleitet, das dein Sitzplatz sehen kann, und diese ID wird als defaultProjectId in session/session-meta.json gespeichert.

Es wird einmal geschrieben und dann in Ruhe gelassen. Die Weiterleitung folgt dem Projekt, das die App zuletzt geöffnet hatte. Wenn man ihr bei jedem Lauf vertrauen würde, würde ein Tool-Aufruf ohne projectId ein anderes Projekt lesen als gestern.

Auflösungsreihenfolge:

1. JUICEBOX_PROJECT_ID (Umgebungsvariable – das ist es, was das optionale Feld „Standardprojekt“ der Desktop-Erweiterung setzt)

2. JUICEBOX_VALIDATOR_PROJECT (Umgebungsvariable – pinnt auch die Authentifizierungsprüfung auf dieses Projekt)

3. defaultProjectId in session/session-meta.json, durch Erkennung gesetzt

Jedes Tool akzeptiert auch eine explizite projectId, die immer gewinnt.

Juicebox-Projekt-IDs sind ~20 Zeichen lange Schlüssel wie c5PheL2fANnX6uBQVUdo – der /project/<id>/-Teil einer URL. Wenn du eine UUID übergibst, lehnt der Server sie mit einer Erklärung ab, anstatt still zu einem Projekt zu navigieren, das nicht existiert.

Zwei Regeln, die die Tools mit sich tragen

• verdictFound: false → unknown, niemals eine Verneinung. „Keine Beweise gefunden“ und „Beweise sagen nein“ sind unterschiedliche Bewertungen. Sie zusammenzufassen bewertet einen Kandidaten für ein Kriterium schlechter, das niemand tatsächlich prüfen konnte.

• Breite Skill-Begriffe verwässern das Ranking. Skills sind ODER-gewichtet; ein bevölkerungsweiter Begriff wie „Account Management“ bei einer Customer-Success-Suche bläht den Pool um etwa das 3,4-fache auf. Entferne die generischen Begriffe und befördere die eine harte Anforderung zu einem Skill-Filter.

Skripte ausführen, während der Server läuft

Du kannst das Browserprofil nicht teilen: session/profile/ ist Single-Writer, und der MCP-Server hält es, wann immer er läuft. Ein zweiter Prozess, der es öffnen will, schlägt bei der Authentifizierungsprüfung fehl – die sich selbst als „Sitzung abgelaufen“ meldet und dich im Kreis herum zum erneuten Anmelden schickt.

Für Diagnosen erstelle stattdessen einen frischen Kontext aus dem Checkpoint. Keine Sperre, dieselbe Sitzung:

const { chromium } = require('patchright');
const browser = await chromium.launch({ headless: true });
const context = await browser.newContext({ storageState: 'session/storage-state.json' });

Wie es funktioniert und die Fallstricke

Die Ergebnisseite wird beim ersten Laden serverseitig gerendert, daher feuert /api/profiles/results nur bei Interaktion. Der Client stößt den Pager an, damit die App ihre eigene Anfrage auslöst, und erfasst dann die Antwort – die den gesamten bewerteten Satz enthält, nicht nur die sichtbare Seite.

Drei Dinge, die jeden beißen werden, der client.js bearbeitet:

1. Verwende niemals addInitScript. Patchright ignoriert es still als Anti-Erkennungsmaßnahme – kein Fehler, das Skript läuft einfach nie. Verwende page.on('response').

2. Die linkedin_url der API ist verschlüsselt (hex:hex), ebenso wie profiles[].url und profileDetails.id. Echte URLs kommen von den gerenderten Karten und werden über normalisiertes full_name verknüpft – gemessen bei 100 % bei einer Live-Suche.

3. Die Liste wird mitten in der Paginierung leer. Ein null-Pager-Wert bedeutet „bewegt sich noch“, nicht „fehlgeschlagen“. Etwas an die Pager-Änderungserkennung während eines Übergangs zu koppeln, ist die Ursache für zwei frühere Fehler.

Wenn es kaputtgeht

Dies reitet auf der internen API von Juicebox. Es gibt keinen Stabilitätsvertrag, und sie kann sich ohne Vorankündigung ändern.

• npm run check schlägt fehl → Sitzung abgelaufen: npm run login.

• Der Server sagt, Chromium fehlt → npx patchright install chromium.

• jb_get_results gibt source: "dom-fallback" zurück → die API-Erfassung ist kaputt; du verlierst matchRate und Kriterien. Prüfe, ob RESULTS_PATH noch übereinstimmt.

• jb_get_results meldet joinedLinkedInUrls: 0 → das Karten-Markup hat sich geändert; überarbeite harvestCards / rewindToFirstPage.

• Leere Suchliste → das Projektseiten-Markup hat sich geändert; siehe listSavedSearches.

Anforderungen

• Node.js 18 oder neuer

• Ein Juicebox-Konto, bei dem du dich anmelden kannst

• ~500 MB freier Speicherplatz für den Chromium-Download

Lizenz

MIT. Nicht verbunden mit oder unterstützt von Juicebox.