Juicebox MCP

Juicebox 소싱 데이터를 Claude로 읽어들이는 로컬 MCP 서버 — 저장된 검색과 점수화된 결과를, 로그인한 Juicebox 세션을 사용하여 처리합니다.

전적으로 사용자 머신에서 실행됩니다. 세션이 머신을 떠나지 않으며, 모든 호출은 사용자 본인으로, 사용자 자신의 시트에서 이루어집니다.

읽기 작업은 내보내기 크레딧을 소모하지 않습니다. 읽기 도구가 반환하는 모든 것은 검색 결과 페이지가 이미 렌더링하는 동일한 무료 표면에서 나옵니다. 하나의 도구만 쓰기 작업을 하며, 그렇게 명시합니다: jb_run_search는 워크스페이스에 실제 저장된 검색을 생성합니다.

설치

옵션 A — 데스크톱 확장 (가장 쉬움)

Releases에서 juicebox-mcp.mcpb를 다운로드한 후, 더블클릭하거나 Claude Desktop → 설정 → 확장으로 드래그하세요.

붙여넣을 API 키는 없습니다. 설치 후 아래의 일회성 브라우저 단계를 수행하세요.

옵션 B — 소스에서

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

그런 다음 Claude Code에 등록하세요:

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

-s user는 모든 세션에서 사용할 수 있게 합니다. 없으면 등록은 실행한 디렉토리로 범위가 제한됩니다.

일회성 브라우저 다운로드

이것은 실제 Chromium을 구동하며, 해당 바이너리는 node_modules의 일부가 아닙니다 — 공유 캐시(macOS의 ~/Library/Caches/ms-playwright)에 약 500MB를 일회성으로 다운로드합니다.

npm install은 postinstall 단계를 통해 자동으로 가져옵니다. 데스크톱 확장 사용자는 한 번 수동으로 실행해야 합니다. 확장은 node_modules를 번들하지만 해당 캐시는 번들하지 않기 때문입니다:

npx patchright install chromium

없으면 서버는 누락된 실행 파일에 대한 스택 트레이스를 던지는 대신 평이한 언어로 알려줍니다.

로그인

인증은 키가 아닌 실제 로그인입니다. npm run login은 브라우저 창을 엽니다. 평소처럼 Juicebox에 로그인하세요. 세션은 session/(gitignore, chmod 600)에 저장되며 헤드리스로 재사용됩니다.

npm run check가 실패하기 시작할 때마다 다시 로그인하세요 — 세션은 만료됩니다.

도구

experience[]는 과거 고용주를 볼 수 있는 유일한 방법입니다. API 페이로드는 현재 고용주만 전달하므로, 대상 회사의 동문은 이것 없이는 보이지 않습니다.

기본으로 읽는 프로젝트

하드코딩된 것은 없습니다. 로그인 시 프로브가 /projects를 로드하며, 이는 사용자 시트가 볼 수 있는 프로젝트로 리디렉션되고, 해당 id는 session/session-meta.json의 defaultProjectId로 저장됩니다.

한 번 기록된 후 그대로 둡니다. 리디렉션은 앱이 가장 최근에 열었던 프로젝트를 따르므로, 매 실행마다 신뢰하면 projectId 없이 호출된 도구가 어제와 다른 프로젝트를 읽게 됩니다.

해결 순서:

1. JUICEBOX_PROJECT_ID (환경 변수 — 데스크톱 확장의 선택적 "기본 프로젝트" 필드가 설정하는 것)

2. JUICEBOX_VALIDATOR_PROJECT (환경 변수 — 인증 확인도 해당 프로젝트로 고정)

3. session/session-meta.json의 defaultProjectId (탐색으로 설정)

모든 도구는 명시적 projectId도 받으며, 항상 우선합니다.

Juicebox 프로젝트 id는 c5PheL2fANnX6uBQVUdo와 같은 ~20자 키입니다 — URL의 /project/<id>/ 부분입니다. UUID를 전달하면 서버는 존재하지 않는 프로젝트로 조용히 이동하는 대신 설명과 함께 거부합니다.

도구가 지니는 두 가지 규칙

• verdictFound: false → unknown, 결코 부정이 아님. "증거 없음"과 "증거가 아니라고 말함"은 다른 판정입니다. 이 둘을 합치면 아무도 실제로 확인할 수 없는 기준에 대해 후보를 낮게 평가하게 됩니다.

• 광범위한 기술 용어는 순위를 희석시킵니다. 기술은 OR 가중치가 적용됩니다. 고객 성공 검색에서 "Account Management"와 같은 인구 전체 용어는 풀을 약 3.4배 부풀립니다. 일반 용어를 제거하고 하나의 핵심 요구 사항을 기술 필터로 승격하세요.

서버가 실행되는 동안 스크립트 실행

브라우저 프로필을 공유할 수 없습니다. session/profile/은 단일 작성자이며, MCP 서버는 실행 중일 때 항상 이를 보유합니다. 이를 열려고 하는 두 번째 프로세스는 인증 확인에 실패합니다 — 이는 "세션 만료"로 보고되며, 재로그인을 반복하게 만듭니다.

진단을 위해 체크포인트에서 새 컨텍스트를 빌드하세요. 잠금 없음, 동일한 세션:

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

작동 방식 및 함정

결과 페이지는 첫 로드 시 서버 렌더링되므로 /api/profiles/results는 상호작용 시에만 발생합니다. 클라이언트는 페이저를 움직여 앱이 자체 요청을 발행하게 한 다음 응답을 캡처합니다 — 응답은 보이는 페이지만이 아니라 전체 순위 세트를 전달합니다.

client.js를 편집하는 사람을 물릴 세 가지:

1. addInitScript를 절대 사용하지 마세요. Patchright는 탐지 방지 조치로 이를 조용히 무시합니다 — 오류 없이 스크립트가 실행되지 않습니다. page.on('response')를 사용하세요.

2. API의 linkedin_url은 암호화되어 있습니다 (hex:hex), profiles[].url 및 profileDetails.id도 마찬가지입니다. 실제 URL은 렌더링된 카드에서 오며 정규화된 full_name으로 조인됩니다 — 라이브 검색에서 100%로 측정되었습니다.

3. 목록은 페이지 매김 중간에 비워집니다. null 페이저 읽기는 "아직 이동 중"을 의미하며 "실패"가 아닙니다. 전환 중 페이저 변경 감지에 무엇이든 게이트하는 것이 이전 두 버그가 발생한 방법입니다.

문제 발생 시

이것은 Juicebox의 내부 API를 사용합니다. 안정성 계약이 없으며, 통지 없이 변경될 수 있습니다.

• npm run check 실패 → 세션 만료: npm run login.

• 서버가 Chromium이 없다고 말함 → npx patchright install chromium.

• jb_get_results가 source: "dom-fallback" 반환 → API 캡처가 깨졌습니다. matchRate와 기준을 잃게 됩니다. RESULTS_PATH가 여전히 일치하는지 확인하세요.

• jb_get_results가 joinedLinkedInUrls: 0 보고 → 카드 마크업이 변경되었습니다. harvestCards / rewindToFirstPage를 다시 검토하세요.

• 빈 검색 목록 → 프로젝트 페이지 마크업이 변경되었습니다. listSavedSearches를 참조하세요.

요구 사항

• Node.js 18 이상

• 로그인할 수 있는 Juicebox 계정

• Chromium 다운로드를 위한 약 500MB 여유 디스크

라이선스

MIT. Juicebox와 제휴하거나 보증하지 않습니다.