joblet-mcp-grok

독립형 MCP 서버로, 읽기 전용 joblet.ai 채용 검색을 Grok 및 기타 표준 준수 MCP 호스트에 노출합니다. 독립 배포 — Joblet의 다른 커넥터와 인프라, 브랜치, 릴리스 트레인을 공유하지 않습니다.

두 가지 도구, 모두 읽기 전용(readOnlyHint: true):

• search_jobs — 실제 업스트림 위치 필터, MCP 계층 관련성 필터링(제목/카테고리/산업/역할 토큰 일치, 설명 전용 일치 거부), expVer/근접 중복 제거, 최대 8개 결과 상한을 갖춘 키워드 검색. 텍스트 + structuredContent를 제공하며, 이를 렌더링하는 호스트를 위한 MCP Apps 작업 카드 위젯도 포함합니다.

• get_job_details — 작업 ID로 전체 게시물(설명, 요구 사항, 책임, 알려진 경우 급여 및 근무지, 지원 링크)을 제공합니다.

지원 URL은 바이트 단위로 그대로 전달됩니다(Joveo 추적 보존, 프록시 또는 리디렉션 없음). 고용 유형은 의도적으로 표시하거나 필터링하지 않습니다. 업스트림 검색은 권위 있는 필드를 제공하지 않기 때문입니다.

요구 사항

• Node.js 18+ (Node 24에서 개발 및 테스트됨)

• API 키나 비밀번호 없음 — 업스트림 joblet.ai API는 공개입니다.

로컬 설정

npm ci
npm run build        # bundles the widget to dist/mcp-app.html (required before start)
PORT=3010 npm start  # MCP endpoint at http://localhost:3010/mcp

상태 확인:

# GET /health  ->  {"status":"ok","version":"1.1.0"}

MCP 엔드포인트: POST /mcp — Streamable HTTP, JSON 응답, 상태 비저장(세션 ID 없음). 사양 표준 Accept: application/json, text/event-stream 헤더가 필요합니다. GET /는 서비스 배너를 반환합니다.

MCP 계약을 로컬에서 검증

MCP_URL="http://localhost:3010/mcp" node test_client.mjs
MCP_URL="http://localhost:3010/mcp" node test_widget.mjs

또는 대화형으로: npm run inspect (MCP Inspector → Streamable HTTP → /mcp URL).

개발

npm run typecheck    # server + widget/tests configs
npm test             # vitest suites (server pipeline, widget, a11y, logging)
npm run build        # production widget bundle

구성

.env.example을 참조하세요. 모든 것은 선택 사항이며, 기본값은 프로덕션에 적합합니다. MCP_REQUEST_LOG=1은 정리된 호출별 로깅을 활성화합니다(해시/길이/개수만 — 원시 쿼리 텍스트, 위치, 지원 URL 또는 자격 증명은 절대 기록하지 않음).

위젯 참고 사항

작업 카드 위젯은 MCP Apps sendSizeChanged 알림을 통해 호스트에 고유 높이를 보고합니다(높이만, requestAnimationFrame 후 측정, 크기 조정 루프를 방지하기 위해 변경 게이트 적용) 및 선언된 경우 고정 호스트 컨테이너 높이를 존중합니다. 호스트가 그에 따라 iframe 크기를 조정하는지 여부는 호스트 동작입니다. View & Apply CTA는 표준 준수 ui/open-link 요청을 사용하며, 호스트가 거부하거나 지원하지 않을 때마다 표시되고 접근 가능한 카드 내 대체(링크 + 복사 작업)를 제공합니다 — 절대 조용히 실패하지 않습니다.