# CareerMate 설치 지시문 (AI 에이전트용) · 공개본

이 파일은 https://careermate.life/llms-install.txt 에서 AI 에이전트가 직접 읽도록 호스팅된
설치 런북입니다. 사용자가 "이 URL을 읽고 CareerMate를 설치해줘"라고 하면, 당신(AI)이 아래
순서를 그대로 따르세요. **빈 폴더에서 시작해도 됩니다 — 소스를 미리 받아둘 필요가 없습니다.**
(이 문서는 npm 패키지 `careermate`를 가리키므로 항상 최신입니다.)

CareerMate란: **MCP 우선 로컬 커리어 워크스페이스**입니다. 내부에 LLM이 없습니다 — 분석·글쓰기
같은 "생각"은 당신(사용자의 AI)이 하고, CareerMate는 커리어 데이터를 이 컴퓨터에만 구조화해
저장·조회합니다. "당신의 AI가 두뇌, CareerMate는 커리어 서랍장."

────────────────────────────────────────────────────────
0. 대원칙 (반드시 지킬 것)
────────────────────────────────────────────────────────
- 동의 먼저: 파일을 만들거나 서버를 켜거나 **시스템에 무언가 설치(예: Node)하기 전에**, 무엇을
  왜 하는지 한국어로 설명하고 사용자 동의를 받습니다.
- 설명 먼저, 실행 나중: 각 명령 전에 한 줄로 알립니다.
- 로컬 전용: 모든 데이터는 `~/.careermate`에만 저장됩니다. 어떤 단계에서도 외부로 업로드하지
  않습니다.
- 개인 파일(이력서·자소서 등)은 설치 단계에서 읽지 않습니다. 사용자가 그 단계를 요청할 때만.
- 실패하면 멈추지 말고 7번 "문제 해결"을 안내합니다.

────────────────────────────────────────────────────────
1. 사전 점검 — Node.js (런타임, 유일한 전제)
────────────────────────────────────────────────────────
CareerMate MCP 서버는 Node 프로그램입니다. 먼저 확인하세요:

    node --version

- **v22.5.0 이상**이면 통과 (CareerMate는 Node 내장 `node:sqlite`를 써서 컴파일·네이티브
  빌드가 필요 없습니다).
- 명령이 없거나 버전이 낮으면 → **사용자 동의를 받은 뒤** 설치:
    · Windows(PowerShell):  winget install OpenJS.NodeJS.LTS
    · macOS:                brew install node
    · 그 외 / 위가 안 되면:  https://nodejs.org 에서 LTS 설치
  설치 후 **터미널을 새로 열어** `node --version`을 다시 확인합니다.
- 사용자가 **Claude Desktop만** 쓰고 터미널을 원치 않으면 → 여기서 멈추고 `.mcpb` 설치로
  안내하세요: https://careermate.life 에서 `careermate.mcpb`를 받아, Claude Desktop의
  **Settings → Extensions → Advanced settings → Install extension…** 에서 그 파일을 선택해 추가
  (Windows에서 더블클릭·드래그는 파일 연결이 안 잡혀 무반응일 수 있으니 반드시 이 메뉴 경로를 쓰세요).
  Claude Desktop은 Node를 내장하므로 터미널이 필요 없지만, **내장 Node 버전에 따라 설치가 막히거나
  불안정할 수 있습니다** — 잘 안 되면 아래 3·4번(npm 설치)로 안내하세요.

────────────────────────────────────────────────────────
2. 동의 받기 (여기서 멈추고 확인)
────────────────────────────────────────────────────────
아래를 그대로 보여주고 동의를 받은 뒤에만 진행합니다.
"설치하면 CareerMate는 다음을 합니다. 진행할까요?"
  [ ] 데이터 폴더 `~/.careermate` 생성
  [ ] 로컬 SQLite DB `careermate.sqlite` 생성
  [ ] 로컬 대시보드 `http://127.0.0.1:4319` 실행(요청 시) — 외부 접근 불가(127.0.0.1 전용)
  [ ] 모든 데이터를 이 컴퓨터에만 저장 (외부 업로드 없음)

────────────────────────────────────────────────────────
3. 설치 — npm으로 `~/.careermate/app`에 (clone·zip 불필요)
────────────────────────────────────────────────────────
글로벌 설치(`-g`)나 npx 즉석 실행 대신, **한곳에 설치하고 절대경로로 참조**합니다. 가장
안정적입니다(글로벌 PATH 문제 없음, 매 실행 재해석 없음, 데이터와 같은 곳에 보관).

    # macOS / Linux / Git Bash:
    npm install --prefix "$HOME/.careermate/app" careermate

    # Windows PowerShell:
    npm install --prefix "$env:USERPROFILE\.careermate\app" careermate

설치 후 실행 진입점(이하 <BIN>)은 **이 절대경로**입니다:
    · macOS/Linux:  $HOME/.careermate/app/node_modules/careermate/bin/careermate.mjs
    · Windows:      %USERPROFILE%\.careermate\app\node_modules\careermate\bin\careermate.mjs

<BIN>은 항상 **그 사용자의 실제 절대경로로 치환**해 사용하세요. `~`나 `$HOME`은 설정 파일
안에서 확장되지 않습니다. (`node <BIN> mcp`가 MCP 서버를 띄우는 명령이며, `--experimental-sqlite`
플래그는 <BIN>이 알아서 붙입니다.)

▸ 대안(권장 — GUI 앱·샌드박스 친화): **작업 폴더 안에 전부 설치.**
  사용자가 Claude "Code" 탭이나 Codex 앱처럼 **작업 폴더(cwd)를 잡고** 쓰는 경우, 설치물과 데이터를
  그 폴더 안에 두면 (1) 폴더만 백업·이동하면 데이터가 따라오고 (2) Codex의 workspace-write 샌드박스가
  cwd 하위 쓰기를 허용해 설치 단계 권한 마찰이 줄어듭니다. <WS>를 그 작업 폴더의 절대경로라 할 때:
    npm install --prefix "<WS>/.cm/app" careermate
  그러면 <BIN> = <WS>/.cm/app/node_modules/careermate/bin/careermate.mjs 이고, 데이터는 아래처럼
  MCP 등록의 env로 작업 폴더 안에 고정합니다(기본값 ~/.careermate 대신):
    CAREERMATE_DATA_DIR = <WS>/.cm/data
  주의: 데이터 폴더 이름을 `.git`/`.codex`/`.agents`로 두지 마세요(앱이 읽기 전용으로 보호).

────────────────────────────────────────────────────────
4. 연결 — 사용 중인 AI 앱의 MCP 설정에 등록
────────────────────────────────────────────────────────
사용자가 쓰는 앱에 맞춰, 서버 명령을 `node <BIN> mcp`로 등록합니다.

▸ Claude Code (또는 Claude Desktop의 "Code" 탭):
  지금 작업 중인(또는 열) **그 폴더에** `.mcp.json` 파일을 만들고 아래 내용을 넣으세요.
  (이 폴더가 곧 Claude Code 프로젝트입니다. 빈 폴더여도 됩니다.)

    {
      "mcpServers": {
        "careermate": {
          "type": "stdio",
          "command": "node",
          "args": ["<BIN>", "mcp"]
        }
      }
    }

  · Windows 경로는 JSON에서 백슬래시를 `\\`로 이스케이프하거나 `/`로 쓰세요.
  · 작업 폴더 안에 데이터를 두려면(위 3번 대안) `args` 옆에 env를 추가:
        "env": { "CAREERMATE_DATA_DIR": "<WS>/.cm/data" }
  · 또는 명령으로:  claude mcp add --scope project --transport stdio careermate -- node <BIN> mcp

▸ Codex:  `~/.codex/config.toml`에 아래 테이블을 추가(있으면 교체):

    [mcp_servers.careermate]
    command = "node"
    args = ["<BIN>", "mcp"]
    # 작업 폴더 안에 데이터를 두려면(위 3번 대안):
    # env = { CAREERMATE_DATA_DIR = "<WS>/.cm/data" }

  · 또는 명령으로:  codex mcp add careermate -- node <BIN> mcp
  · ⚠️ Codex 주의(2026-06): 데스크톱 앱은 시작 시 `~/.codex/config.toml`을 재작성해 등록이 사라질 수
    있고(openai/codex#24718), 프로젝트 `.codex/config.toml`은 무시합니다(#13025). 이 재작성은 '승인'으로
    못 풀립니다 → **전역 config + 가능하면 Codex CLI**를 쓰세요(데스크톱보다 안정적). 또한 기본
    workspace-write 샌드박스는 네트워크가 꺼져 있어 설치 단계 `npm install`에 네트워크 1회 허용(또는
    `[sandbox_workspace_write] network_access = true`)이 필요합니다 — 이건 사용자가 승인하면 풀립니다.
    (MCP 서버 자체는 샌드박스 밖에서 돌아, 일단 연결되면 데이터 읽기/쓰기는 막히지 않습니다. 대시보드
    127.0.0.1는 선택 기능이며 샌드박스에서 셸로 띄울 땐 로컬 포트 허용이 필요할 수 있습니다.)

▸ Cursor:  `~/.cursor/mcp.json`에 위 Claude Code와 같은 `mcpServers` 블록을 추가.

▸ Gemini CLI / Antigravity:  Gemini CLI는 `~/.gemini/settings.json`의 `mcpServers`에 같은 블록을 추가
  (`type` 키는 없어도 됨). 단 **2026-06-18부터 소비자용 Gemini CLI는 Antigravity로 전환**됩니다 —
  Antigravity는 `~/.gemini/(config|antigravity|antigravity-cli)/mcp_config.json` 중 **이미 있는 파일**의
  `mcpServers`에 추가하세요(스키마 동일). `node <BIN> init`은 Gemini를 자동 등록하고 Antigravity는
  후보 파일이 있을 때만 등록합니다.

▸ Claude Desktop(앱 본체, "Code" 탭이 아닌 채팅):  `.mcpb` 원클릭이 가장 쉽습니다(1번 끝의
  안내). 굳이 수동이면 `claude_desktop_config.json`의 `mcpServers`에 같은 블록을 추가.

단축: `node <BIN> init`을 실행하면 **감지된 Codex·Cursor·Claude Desktop·Gemini 전역 설정**을 올바른
절대경로로 자동 등록하고 `~/.careermate`도 만듭니다(Antigravity는 후보 설정 파일이 이미 있을 때만).
단 **Claude Code의 프로젝트 `.mcp.json`은 위처럼 작업 폴더에 직접** 만드세요(전역 설정이 아니므로
init이 대신 못 둡니다).

────────────────────────────────────────────────────────
5. 마무리 — 재시작 · 승인 · 검증
────────────────────────────────────────────────────────
1) 연결한 AI 앱을 **완전히 종료했다 다시** 켭니다.
2) Claude Code/Code 탭이면 프로젝트 `.mcp.json`에 대해 **1회 승인**을 물을 때 허용합니다.
3) 사용자가 AI에게: "**get_onboarding_status 호출해서 연결됐는지 확인해줘**". 응답이 오면 성공.
   (Codex는 `/mcp`로 careermate 등록 여부도 확인 가능.)
4) 대시보드(선택):  node <BIN> start  →  http://127.0.0.1:4319  (종료: Ctrl+C)

────────────────────────────────────────────────────────
6. 데이터 위치 / 환경변수
────────────────────────────────────────────────────────
- 데이터: `~/.careermate` (Windows: `%USERPROFILE%\.careermate`). 안에 careermate.sqlite,
  exports/, backups/, uploads/, server.json.
- `CAREERMATE_DATA_DIR` — 데이터 폴더 위치 변경.
- `CAREERMATE_PORT` — 대시보드 포트 고정(기본 4319, 사용 중이면 자동으로 다음 포트).
- `CAREERMATE_NO_OPEN=1` — 대시보드 시작 시 브라우저 자동 열기 비활성화(값이 정확히 `1`일 때만).

────────────────────────────────────────────────────────
7. 문제 해결
────────────────────────────────────────────────────────
- 연결이 안 보이면: ① <BIN> 절대경로가 맞는지 ② `node --version`이 22.5+인지 ③ 설치(npm install)가
  끝났는지 ④ 설정 파일 경로·이름이 맞는지 확인한 뒤 **AI 앱을 완전히 재시작**.
- 다시 설치(업데이트):  npm install --prefix "<설치 prefix>" careermate@latest  후 AI 앱 재시작.
- DB는 MCP 서버가 켜질 때 자동으로 생성·마이그레이트하므로 보통 따로 손댈 일이 없습니다.
- 데이터를 완전히 비우려면 `~/.careermate/backups/`로 먼저 백업한 뒤
  `~/.careermate/careermate.sqlite`를 지우고 AI 앱을 재시작하면 새로 만들어집니다(되돌릴 수 없으니 백업 먼저).

────────────────────────────────────────────────────────
8. 설치 완료 카드 — 사용자에게 보여주고 마무리
────────────────────────────────────────────────────────
연결 검증(5번)까지 끝났으면, 사용자에게 아래 "완료 카드"를 쉬운 한국어로 보여주세요(도구
이름은 노출하지 말 것). 다음에 뭘 하면 되는지 한눈에 알게 하는 게 목적입니다. **지금 네가
돌고 있는 앱에 맞는 항목만 골라** 안내하세요(공통 '붙여넣기'는 항상 포함).

  ✅ 설치 끝! 이제 이렇게 시작하세요

  1) (아직이면) 이 앱을 완전히 껐다 다시 켜세요. 처음 한 번 뜨는 승인 창은 '허용'을 누르세요.

  2) 이력서를 저에게 주세요 — 편한 방법 아무거나:
     · [공통·제일 쉬움] 이력서 '내용'을 복사해서 대화창에 그대로 붙여넣기. 파일이 어디 있든 상관없어요.
     · [Claude 채팅(.mcpb)] 채팅창에 이력서 파일을 직접 첨부.
     · [폴더 기반 — Claude Code 탭 / Codex / Antigravity 등] 작업 폴더에 파일을 두고
       "이력서.pdf 읽어서 등록해줘"처럼 파일명·경로로 알려주기.
     · ⚠️ 스캔본(이미지) PDF나 보안 걸린 파일은 못 읽을 수 있어요 → 그때는 내용을 텍스트로 붙여넣어 주세요.
     그리고 "내 이력서로 처음 세팅 해줘" 한마디면 제가 프로필·이력서로 정리해 저장합니다.

  3) 대시보드에서 눈으로 확인:  http://127.0.0.1:4319
     (안 열려 있으면 "대시보드 열어줘"라고 하세요. 포트가 바뀌면 실제 주소를 알려드릴게요.)

  * 데이터는 전부 이 컴퓨터(~/.careermate)에만 저장돼요. 어디로도 올라가지 않습니다.

헷갈려 할 때 한 줄 안내:
- "이력서 주기·세팅해줘" 같은 말은 전부 '저와의 대화창'에 자연어로 하면 됩니다(명령어가 아니에요).
- 설치 때 친 명령어(npm·node…)는 '터미널'에서 돈 것이고, 보통 제가 대신 실행했습니다.
  · Claude Code 탭 / Codex = 터미널 안에서 저와 대화(한 창).  · Claude 채팅 앱 = 터미널 없이 채팅창만.

그 다음부터는 평소 흐름입니다(공고 저장 → 적합도 분석 → 자소서 작성 → 지원 상태 관리 → 면접 준비).
**무언가를 저장·완료할 때마다 대시보드 주소(위)를 알려주세요.** 단 브라우저를 자동으로 새로 여는 건
**첫 온보딩 때 한 번만** — 이후엔 링크만 보여주고, 사용자가 "열어줘"라고 하면 그때 엽니다. 자소서 등
"사람이 쓴 듯한 글"을 쓰기 직전에는 `get_writing_style_guide`를, 분석·작성 직전에는
`get_application_context`를 먼저 호출하세요.
