careermate 0.1.0

package/docs/INSTALL_AND_USAGE.md

@@ -0,0 +1,99 @@
+# 설치 & 사용법 — 두 가지 방식
+
+CareerMate는 LLM을 포함하지 않습니다. 사용자의 AI(Claude)가 MCP 도구로 로컬 데이터를 읽고 씁니다.
+배포 방식은 두 갈래이고, **코어(DB + 도구 24개)는 동일**합니다.
+
+| | 대상 | 설치 난이도 | Node 필요 |
+| --- | --- | --- | --- |
+| **A. `.mcpb` 번들** | 비개발자 + Claude Desktop | 더블클릭 1번 | ❌ (Claude Desktop 내장) |
+| **B. npm / 터미널** | 개발자 + 다른 MCP 클라이언트 | 클론 후 npm | ✅ |
+
+---
+
+## A. `.mcpb` — 비개발자용 (Claude Desktop 원클릭)
+
+### 만드는 쪽 (배포자)
+```bash
+node scripts/build-mcpb.mjs        # → dist/careermate.mcpb 생성
+```
+`manifest.json` + 서버 코드 + 런타임 의존성을 하나의 번들로 묶습니다. 이 파일을 GitHub Releases 등에 올립니다.
+
+### 쓰는 쪽 (유저) — 터미널 0, Node 설치 0
+1. `careermate.mcpb` 파일 다운로드
+2. **더블클릭** (또는 Claude Desktop → Settings → Extensions 로 끌어다 놓기)
+3. "설치" 클릭 → Claude Desktop 재시작
+4. 끝. 이제 Claude에게 말로 시키면 됩니다.
+
+> Claude Desktop이 Node를 내장 제공하므로 유저는 아무것도 미리 깔 필요가 없습니다.
+> ⚠️ 단, 내장 Node가 22.5 미만이면 `node:sqlite`가 안 되므로 manifest의 `compatibility.runtimes.node`로 막아둡니다.
+
+---
+
+## B. npm / 터미널 — 개발자 · 다른 MCP 클라이언트
+
+Cursor · Cline · Windsurf · Claude Code 등 로컬 stdio MCP를 지원하는 클라이언트에서 동작합니다.
+**준비물은 Node.js 22.5 이상** 하나뿐입니다(내장 SQLite 사용, 네이티브 빌드 없음).
+
+### 소스에서 설치 (현재 권장)
+```bash
+git clone https://github.com/osntak/CareerMate.git   # 비공개 저장소 — 접근 권한 필요(없으면 npx 방식 사용)
+cd CareerMate
+npm install
+npm run init          # 감지된 클라이언트(Claude Desktop·Codex·Cursor) 자동 등록 + Claude Code .mcp.json 항상 작성 → 재시작
+```
+
+자동 등록 대상은 감지된 클라이언트(Claude Desktop·Codex·Cursor)이고, Claude Code 프로젝트 `.mcp.json`은 항상 작성됩니다. 그 외 클라이언트(Cline·Windsurf 등)는 설정만 출력해 직접 붙여넣으세요:
+```bash
+npm run init -- --print
+```
+> ⚠️ 등록된 설정에는 이 폴더의 절대 경로가 박힙니다. 폴더를 옮기거나 이름을 바꾸면 `npm run init`을 다시 실행하세요.
+
+### 기타 명령
+```bash
+npm start             # 로컬 대시보드 (http://127.0.0.1:4319)
+npm run doctor        # 설치/환경 점검
+```
+
+### npx — 클론 불필요 (게시 완료)
+`careermate`가 npm에 게시되어 클론 없이 한 줄로 끝납니다.
+```bash
+npx -y careermate init         # 자동 등록
+npx -y careermate init --print # 설정만 출력
+```
+이때 `mcpServers` 항목은 다음 형태로 등록됩니다.
+```json
+{
+  "mcpServers": {
+    "careermate": {
+      "command": "npx",
+      "args": ["-y", "careermate", "mcp"]
+    }
+  }
+}
+```
+
+---
+
+## 실제 사용법 (설치 후 — A·B 공통)
+
+설치가 끝나면 평소처럼 AI에게 한국어로 말하면 됩니다. AI가 알아서 MCP 도구를 호출합니다.
+
+**1) 온보딩**
+> 🧑 "내 이력서 정리해서 등록해줘" (+이력서 파일 업로드)
+> 🤖 `get_onboarding_status` → `save_profile` → `add_resume` → "프로필과 이력서를 저장했어요. 대시보드에서 확인하실래요?"
+
+**2) 공고 분석**
+> 🧑 "이 공고 나랑 잘 맞아? [공고 붙여넣기]"
+> 🤖 `get_application_context` → `save_job_posting` → `save_fit_analysis` → "적합도 78점이에요. 강점은 …, 보완할 점은 …. 이 공고에 맞춘 자소서를 써드릴까요?"
+
+**3) 자기소개서 작성 (AI 티 제거 적용)**
+> 🧑 "응, 써줘"
+> 🤖 `get_application_context` → `get_writing_style_guide` → (번역투·클리셰·기계적 병렬 제거하며 작성) → `save_cover_letter_version` → "초안을 저장했어요. 파일로 받으실래요?"
+> 🧑 "PDF로 줘"
+> 🤖 `export_cover_letter` → "exports 폴더에 저장했어요."
+
+**4) 지원 관리 / 면접 준비**
+> 🧑 "이 회사 서류 합격했어"
+> 🤖 `update_application_status` → "축하해요! 면접 준비를 도와드릴까요?" → `save_interview_prep`
+
+모든 데이터는 `~/.careermate` 에만 저장되고 외부로 나가지 않습니다.

package/docs/MCP_TOOLS.md

@@ -0,0 +1,233 @@
+# MCP 도구 레퍼런스
+
+CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자는 자신의 ChatGPT/Claude/Gemini와 대화하고, 그 AI가 여기 정의된 MCP 도구를 호출해 로컬 커리어 DB(`~/.careermate/careermate.sqlite`)를 읽고 씁니다. **CareerMate 내부에는 LLM이 없습니다.** 적합도 분석·자기소개서 작성 같은 추론은 모두 사용자의 AI가 수행하고, CareerMate는 데이터를 저장하고 다시 돌려주는 역할만 합니다.
+
+이 문서는 `packages/mcp-tools/src/tools.ts`에 정의된 **24개 도구**의 레퍼런스입니다. 도구의 입력 파라미터는 `packages/shared/src/schemas.ts`의 zod 스키마와 일치합니다.
+
+> 설계 원칙: 이 도구들은 단순 CRUD 래퍼가 아닙니다. 각 도구는 AI가 사용자를 대신해 수행하는 실제 작업에 대응하며, 설명에 *언제* 그리고 *어떻게* 호출해야 하는지가 담겨 있습니다. 가장 중요한 도구는 [`get_application_context`](#get_application_context-) 입니다.
+
+관련 문서: 전체 워크플로우는 `get_workflow_guide` 도구 또는 `packages/workflows`를, 데이터 구조는 `packages/shared/src/schemas.ts`를 참고하세요.
+
+---
+
+## 읽기 전용(read-only) 표기 안내
+
+각 도구 항목의 **읽기전용** 열은 `tools.ts`의 `readOnly: true` 플래그를 그대로 반영합니다. 읽기전용 도구는 DB를 변경하지 않고 조회만 하며, 그 외 도구는 데이터를 생성·갱신하거나(쓰기) 브라우저를 여는 등의 부수효과를 가집니다.
+
+| 읽기전용(✅) 도구 | 쓰기/부수효과(✏️) 도구 |
+| --- | --- |
+| `get_onboarding_status`, `start_onboarding`, `get_profile`, `get_resumes`, `get_cover_letters`, `get_job_posting`, `list_jobs`, `parse_job_posting`, `get_application_context`, `list_recent_activity`, `get_workflow_guide`, `get_writing_style_guide` | `save_profile`, `update_profile`, `add_resume`, `add_cover_letter`, `save_cover_letter_version`, `save_job_posting`, `save_fit_analysis`, `update_application_status`, `save_interview_prep`, `export_cover_letter`, `open_dashboard`, `open_application` |
+
+---
+
+## 1. 온보딩 (Onboarding)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `get_onboarding_status` | CareerMate에 어떤 정보(프로필·이력서·경력·스킬·자소서·공고)가 준비되어 있는지 확인하고 다음 단계를 제시 | 없음 | `completed`, `has_profile`/`has_resume`/`has_cover_letter`/`has_experience`/`has_skills`/`has_job`, `profile_completeness`(0~100), `next_steps[]` | AI 클라이언트 연결 직후 가장 먼저 | ✅ |
+| `start_onboarding` | 가이드형 온보딩 시작. 현재 상태 + AI가 사용자를 안내하는 단계별 지침 반환 | 없음 | `status`(온보딩 상태), `guide`(온보딩 프롬프트 텍스트) | 사용자가 "시작하자 / 설정 도와줘"라고 할 때 | ✅ |
+
+안내 흐름(가이드): 프로필 입력 → 이력서/자소서 추가 → 대시보드 열기.
+
+---
+
+## 2. 프로필 (Profile)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `get_profile` | 기본 프로필 조회(이름, 한 줄 소개, 요약, 희망 직무/조건, 선호 문체, 강조 포인트, 링크) | 없음 | `ProfileRecord` 또는 `null` | 프로필 확인이 필요할 때 | ✅ |
+| `save_profile` | 프로필 저장(부분 저장 안전 — 전달한 필드만 갱신, 나머지는 유지) | 아래 프로필 필드 | 저장된 `ProfileRecord` | 이력서 구조화 후 이름/소개/희망 직무/선호 문체/강조 포인트를 채워 저장할 때 | ✏️ |
+| `update_profile` | 기존 프로필을 유지하며 일부 필드만 수정(`save_profile`과 동일 동작, 의미 명확화용) | 프로필 필드(모두 선택) | 저장된 `ProfileRecord` | 한두 개 항목만 바꿀 때 | ✏️ |
+
+프로필 입력 필드(`ProfileInputSchema`):
+
+- `name`(이름), `email`, `phone`, `location`
+- `headline`(한 줄 소개 / 직무 타이틀), `summary`(자기소개 요약)
+- `desired_roles[]`(희망 직무), `desired_conditions`(희망 근무 조건: 연봉·지역·근무형태)
+- `preferred_tone`(자기소개서 선호 문체, 예: "담백하고 구체적")
+- `emphasis_points[]`(강조하고 싶은 핵심 포인트)
+- `links[]`(`{ label, url }` — 포트폴리오/깃허브/링크드인)
+
+> `preferred_tone`과 `emphasis_points`는 이후 자기소개서 작성 품질에 직접 영향을 줍니다.
+
+---
+
+## 3. 이력서 (Resumes / Documents)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `add_resume` | 이력서·경력기술서·포트폴리오 등 문서 저장 | `title`, `content`(필수), `kind?`, `source?`, `is_primary?`, `tags?` | 저장된 `DocumentRecord` | 사용자가 업로드/붙여넣은 텍스트(또는 정리한 Markdown)를 보관할 때 | ✏️ |
+| `get_resumes` | 저장된 문서 조회(종류 필터 가능) | `kind?` | `DocumentRecord[]` | 저장된 이력서/문서를 확인할 때 | ✅ |
+
+- `kind` 값: `resume`(이력서, 기본값) / `career_description`(경력기술서) / `portfolio` / `other`
+- `is_primary: true`로 대표 문서를 지정하면 `get_application_context`의 `primary_resume`로 노출됩니다.
+
+---
+
+## 4. 자기소개서 (Cover Letters)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `add_cover_letter` | 기존 자기소개서를 등록(`content`를 주면 첫 버전 v1로 저장) | `title`, `content?`, `job_id?`, `is_primary?`, `note?`, `source?` | 생성/저장된 `CoverLetterRecord` | 사용자가 이미 쓴 자소서를 학습용으로 보관할 때 | ✏️ |
+| `get_cover_letters` | 저장된 자기소개서 조회(공고별 필터 가능). 각 항목은 현재 버전 내용·버전 수 포함 | `job_id?` | `CoverLetterRecord[]` | 자소서 목록/내용을 확인할 때 | ✅ |
+| `save_cover_letter_version` | 자기소개서의 새 버전 저장 — 자소서 작성 워크플로우의 핵심 저장 단계 | `content`(필수), `cover_letter_id?`, `title?`, `job_id?`, `note?`, `source?`, `set_current?` | `{ coverLetter, version }` | 새 공고용 자소서를 생성·갱신해 버전으로 남길 때 | ✏️ |
+
+`save_cover_letter_version` 동작(`CoverLetterVersionInputSchema`):
+
+- `cover_letter_id`를 주면 기존 자소서에 **새 버전을 추가**하고, 없으면 새 자소서를 만들어 **v1**로 저장합니다(이때 `title` 권장).
+- `note`에 변경 요약(예: "지원동기 보강")을 남기면 대시보드 버전 히스토리에서 이해하기 쉽습니다.
+- `job_id`로 공고에 연결하면 지원(application) 항목과 자동 연결됩니다.
+- `set_current`(기본 `true`): 이 버전을 현재 버전으로 지정.
+
+> 새 공고용 자소서를 "생성"해서 저장할 때는 버전 관리를 위해 `add_cover_letter`보다 `save_cover_letter_version`을 사용하는 편이 좋습니다.
+
+---
+
+## 5. 채용공고 (Jobs)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `save_job_posting` | 채용공고 저장(있으면 갱신). 저장 시 지원(application) 항목 자동 생성 | `company`, `position`(필수), `url?`, `location?`, `employment_type?`, `description?`, `requirements?`, `keywords?`, `deadline?`, `source?` | 저장된 `JobRecord`(`job_id` 포함) | 공고를 DB에 등록/갱신할 때 | ✏️ |
+| `get_job_posting` | 공고 1건 상세 조회 | `job_id` | `{ job, fit, application, cover_letters, interview }` | 한 공고의 분석·상태·자소서·면접 자료를 한 번에 볼 때 | ✅ |
+| `list_jobs` | 저장된 모든 공고를 지원 상태·적합도 점수와 함께 목록화 | 없음 | 공고 메타 포함 배열 | 전체 공고를 훑어볼 때 | ✅ |
+| `parse_job_posting` | 붙여넣은 공고 원문을 정리해 회사명/직무/마감일 추정 + 기술 키워드 추출 | `raw`(공고 원문 텍스트) | 정리된 공고 구조 | `save_job_posting` 전에 빠르게 구조화할 때(보조) | ✅ |
+
+- `url`이 같으면 중복 생성 없이 갱신됩니다.
+- `requirements`에는 자격요건/우대사항 핵심, `keywords`에는 핵심 키워드를 정리해 넣으면 이후 적합도 분석·자소서 작성에 활용됩니다.
+- `parse_job_posting`은 텍스트 정리만 하며 판단/분석은 AI가 직접 수행합니다.
+
+---
+
+## 6. 적합도 (Fit Analysis)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `save_fit_analysis` | AI가 도출한 적합도 분석 결과 저장(같은 공고에 다시 저장하면 갱신) | `job_id`(필수), `score?`(0~100), `summary?`, `strengths?`, `gaps?`, `matched_keywords?`, `missing_keywords?`, `recommendations?` | 저장된 `FitAnalysisRecord` | 공고와 사용자 정보를 비교 분석한 결과를 저장할 때 | ✏️ |
+
+- `job_id`는 필수이며, 먼저 `save_job_posting`으로 공고가 저장되어 있어야 합니다.
+- 분석 자체는 AI가 수행하고, 이 도구는 결과만 저장합니다. 분석 전에는 반드시 [`get_application_context`](#get_application_context-)로 맥락을 가져오세요.
+
+---
+
+## 7. 지원 상태 (Application Status)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `update_application_status` | 지원 상태 변경. `document_passed` 이상이면 면접 준비를 제안하는 힌트 동봉 | `job_id`, `status`, `note?` | 변경 결과(`hint` 포함 가능) | 지원 진행 단계가 바뀔 때 | ✏️ |
+
+지원 상태 8단계(`APPLICATION_STATUSES`):
+
+| 상태 | 라벨 |
+| --- | --- |
+| `draft` | 작성 중 |
+| `planned` | 지원 예정 |
+| `applied` | 지원 완료 |
+| `document_passed` | 서류 합격 |
+| `interview` | 면접 진행 |
+| `final_passed` | 최종 합격 |
+| `rejected` | 불합격 |
+| `on_hold` | 보류 |
+
+> `document_passed`(서류 합격) 이상에서 면접 준비가 해금되며, 상태 변경 응답에 면접 준비 제안 힌트가 함께 돌아옵니다.
+
+---
+
+## 8. 면접 준비 (Interview Prep)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `save_interview_prep` | 예상 질문·꼬리 질문·STAR 답변 가이드·1분 자기소개 초안 등 면접 준비 자료 저장(같은 공고면 갱신) | `job_id`(필수), `questions?`, `star_guides?`, `self_introduction?`, `notes?` | 저장된 `InterviewPrepRecord`(질문 수 포함) | 보통 서류 합격 후, AI가 생성한 면접 자료를 저장할 때 | ✏️ |
+
+입력 구조(`InterviewPrepInputSchema`):
+
+- `questions[]`: `{ question, intent?(질문 의도), followups?(예상 꼬리 질문), answer_outline?(답변 가이드/핵심 포인트) }`
+- `star_guides[]`: `{ question, situation?, task?, action?, result? }`
+- `self_introduction`: 1분 자기소개 초안
+- `notes`: 면접 후기/메모
+
+---
+
+## 9. 내보내기 (Exports)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `export_cover_letter` | 자기소개서를 Markdown 또는 인쇄용 HTML 파일로 데이터 폴더 `exports/`에 저장 | `cover_letter_id`, `format?`(`md`(기본)/`html`) | `{ path, filename, content }` | 사용자가 "자소서 파일로 받고 싶어"라고 할 때 | ✏️ |
+
+- HTML은 인쇄용으로, 브라우저에서 PDF로 저장할 수 있습니다.
+- 대시보드의 Documents 페이지에서 직접 다운로드할 수도 있습니다.
+
+---
+
+## 10. 대시보드 (Dashboard UI)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `open_dashboard` | 로컬 대시보드를 사용자 브라우저에서 열기(서버 미실행 시 자동 시작) | 없음 | `{ url, running }` | 저장 결과를 사용자가 눈으로 확인하게 할 때(예: 분석/자소서 저장 후) | ✏️ |
+| `open_application` | 특정 공고의 지원 상세 페이지(`/#/jobs/{job_id}`)를 브라우저에서 열기 | `job_id` | `{ url, running }` | 적합도·자소서·면접 준비를 바로 확인하도록 안내할 때 | ✏️ |
+
+- 대시보드 기본 주소: `http://127.0.0.1:4319` (포트 사용 중이면 다음 포트로 폴백).
+- 서버가 실행 중이 아니면 안내 메시지에 `npm start` 실행을 권고합니다.
+
+---
+
+## 11. 활동 (Activity)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `list_recent_activity` | 최근 활동 내역(공고 저장, 적합도 분석, 자소서 버전, 상태 변경, 면접 준비 등) 조회 | `limit?`(기본 20) | `ActivityRecord[]` | "최근에 뭐 했지?" 또는 이어서 작업할 맥락이 필요할 때 | ✅ |
+
+---
+
+## 12. 워크플로우 가이드 (Workflow Guide)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `get_workflow_guide` | 표준 워크플로우의 단계별 안내 반환 | `workflow_id?` | 단일 워크플로우 Markdown 또는 전체 목록(`{ id, title, trigger }[]`) | 어떤 순서로 어떤 도구를 호출할지 확인할 때 | ✅ |
+
+`workflow_id` 값: `onboarding`, `analyze_job`, `write_cover_letter`, `manage_application_status`, `prepare_interview`. 생략하면 전체 목록을 돌려줍니다.
+
+---
+
+## 13. 글쓰기 스타일 가이드 (Writing Style Guide)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `get_writing_style_guide` | "AI 티 안 나는" 한국어 글쓰기 규칙 반환 | 없음 | `{ guide }` (작성 규칙 + 저장 전 자가 점검) | 자기소개서·자기 PR·지원 메일 등 사람이 쓴 듯한 글을 작성하기 직전 | ✅ |
+
+번역투·클리셰·기계적 병렬·상투적 연결어·균일한 문장 리듬 같은 AI-tell을 제거하면서, 사실·수치·고유명사는 그대로 보존하도록 안내합니다. `write_cover_letter` / `analyze_job` 워크플로우의 작성 단계에서 함께 적용합니다. (규칙 출처: `epoko77-ai/im-not-ai`, MIT.)
+
+---
+
+## ⭐ get_application_context — 분석/작성 전 필수 호출
+
+> `get_application_context`는 **가장 중요한 도구**입니다. 공고를 분석하거나 자기소개서를 작성하기 **전에 반드시 먼저** 호출하세요. 한 번의 호출로 사용자에 대한 모든 맥락을 돌려줍니다. 읽기전용(✅)입니다.
+
+**입력**
+
+- `job_id?`(선택) — 특정 공고 기준으로 맥락을 모을 때.
+
+**한 번에 반환하는 데이터 전체**(`ApplicationContextSchema`):
+
+| 필드 | 내용 |
+| --- | --- |
+| `profile` | 사용자 프로필(`ProfileRecord` 또는 `null`) |
+| `primary_resume` | 대표 이력서(`is_primary` 문서, 없으면 `null`) |
+| `resumes` | 전체 이력서/문서 배열 |
+| `experiences` | 전체 경력 배열 |
+| `projects` | 프로젝트 배열 |
+| `skills` | 기술스택 배열 |
+| `cover_letters` | 기존 자기소개서 배열(버전 정보 포함) |
+| `recent_applications` | 최근 지원 이력 배열 |
+| `job` | (`job_id` 제공 시) 대상 공고(`JobRecord` 또는 `null`) |
+| `fit_analysis` | (`job_id` 제공 시) 대상 공고의 이전 적합도 분석(`FitAnalysisRecord` 또는 `null`) |
+| `related_history` | 같은 회사/직무 관련 이전 기록 배열 — 각 항목 `{ job, application, fit_analysis }` |
+| `writing_preferences` | 자소서 작성 선호 — `{ preferred_tone, emphasis_points[] }` |
+
+**사용 흐름**
+
+1. (자소서/분석 대상이 있으면) `save_job_posting`으로 공고를 먼저 저장해 `job_id`를 확보.
+2. `get_application_context({ job_id })`로 위 데이터를 한 번에 가져옴.
+3. 이 데이터를 근거로 **AI가** 적합도 분석 또는 자기소개서를 작성.
+4. 결과를 `save_fit_analysis` / `save_cover_letter_version`으로 다시 저장.
+
+> CareerMate는 데이터를 제공할 뿐이고, 분석·작성은 사용자의 AI가 수행합니다. 맥락 없이 작성하지 말고 항상 이 도구로 먼저 사용자 데이터를 확보하세요.

package/docs/ROADMAP.md

@@ -0,0 +1,134 @@
+# CareerMate 로드맵
+
+CareerMate는 MCP-우선 로컬 커리어 관리 도구다. 사용자는 자신의 ChatGPT/Claude/Gemini와 대화하고, 그 AI가 CareerMate의 로컬 MCP 도구를 호출해 로컬 커리어 DB를 읽고 쓴다. CareerMate 내부에는 LLM이 없으며(분석·작성은 사용자의 AI가 수행), 모든 데이터는 로컬에만 저장된다.
+
+이 문서는 현재 버전(`0.1.0`)의 MVP 완료 범위와, 지금은 제외하되 구조는 열어둔 향후 과제를 정리한다.
+
+관련 문서: [README](../README.md), [설치 안내](./INSTALL.md), [워크플로우](./WORKFLOWS.md), [시작하기 워크플로우](./START_WORKFLOW.md)
+
+---
+
+## 현재 버전
+
+- 버전: `0.1.0` (`package.json`)
+- 런타임 요구: Node `>=22.5.0` (`node:sqlite` 내장 사용, 네이티브 컴파일 없음)
+- 실행 방식: 무빌드(tsx) — `node --no-warnings --import tsx ...`
+
+---
+
+## MVP 완료 항목 (Done)
+
+현재 코드/설정과 일치하는, 동작 검증된 범위다.
+
+### 코어 런타임 / 인프라
+- [x] **모노레포 구조**: `packages/{shared,db,core,mcp-tools,exporters,parsers,prompts,workflows}`, `apps/{web,mcp}`, `install-page`, `docs`, `scripts`
+- [x] **무빌드 실행**: TypeScript(ESM)를 `tsx`로 직접 실행 (`npm start`, `npm run dev --watch`, `npm run mcp`)
+- [x] **내장 SQLite**: `node:sqlite` 사용 — 별도 네이티브 모듈/컴파일 불필요
+- [x] **데이터 디렉터리**: 기본 `~/.careermate`, 환경변수 `CAREERMATE_DATA_DIR`로 변경 가능
+- [x] **DB 파일 및 부속 디렉터리**: `careermate.sqlite`, `exports/`, `backups/`, `uploads/`, 런타임 핸드셰이크 `server.json`
+- [x] **환경변수 지원**: `CAREERMATE_DATA_DIR`, `CAREERMATE_PORT`, `CAREERMATE_NO_OPEN`
+- [x] **npm 스크립트**: `start`, `dev`, `mcp`, `migrate`, `seed`, `doctor`, `test`, `test:ui`, `typecheck`
+
+### 로컬 대시보드 + API (`apps/web`)
+- [x] **로컬 대시보드 서버**: 기본 `http://127.0.0.1:4319`, 포트 사용 중이면 다음 포트로 폴백, 브라우저 자동 오픈(`CAREERMATE_NO_OPEN`으로 비활성화)
+- [x] **프레임워크/CDN 없는 프런트엔드**: 바닐라 JS + 자체 CSS 디자인시스템
+- [x] **7개 페이지**: Home, Profile, Jobs(목록+상세), Applications(칸반), Documents(자소서 버전 타임라인 + 이력서), Interview, Settings
+- [x] **다크모드** 지원
+
+### 데이터베이스 (`packages/db`)
+- [x] **12개 테이블**: `profile`, `experiences`, `projects`, `skills`, `documents`, `cover_letters`, `cover_letter_versions`, `jobs`, `fit_analyses`, `applications`, `interview_preps`, `activities` (+ 스키마 버전용 `_meta`)
+- [x] **마이그레이션/시드**: `npm run migrate`, `npm run seed`
+- [x] **지원 상태 8단계**: `draft`(작성 중), `planned`(지원 예정), `applied`(지원 완료), `document_passed`(서류 합격), `interview`(면접 진행), `final_passed`(최종 합격), `rejected`(불합격), `on_hold`(보류) — `document_passed` 이상에서 면접 준비 해금
+
+### MCP 서버 (`apps/mcp`) + 도구 (`packages/mcp-tools`)
+- [x] **MCP stdio 서버**: `@modelcontextprotocol/sdk` 기반, AI 클라이언트가 `npm run mcp`로 기동, 대시보드와 동일 DB 공유
+- [x] **24개 MCP 도구**:
+  - 온보딩/프로필: `get_onboarding_status`, `start_onboarding`, `save_profile`, `get_profile`, `update_profile`
+  - 문서: `add_resume`, `get_resumes`, `add_cover_letter`, `get_cover_letters`
+  - 공고: `save_job_posting`, `get_job_posting`, `list_jobs`, `parse_job_posting`
+  - 컨텍스트(핵심): `get_application_context`
+  - 분석/작성: `save_fit_analysis`, `save_cover_letter_version`
+  - 지원/면접: `update_application_status`, `save_interview_prep`
+  - 글쓰기: `get_writing_style_guide`
+  - 출력/연동: `export_cover_letter`, `open_dashboard`, `open_application`, `list_recent_activity`, `get_workflow_guide`
+
+### 워크플로우 (`packages/workflows`)
+- [x] **5종 워크플로우**: `onboarding`, `analyze_job`, `write_cover_letter`, `manage_application_status`, `prepare_interview`
+
+### 기능 흐름 (저장/관리)
+- [x] **온보딩**: 프로필·경력·프로젝트·스킬 입력 흐름
+- [x] **공고 저장 및 파싱**: 공고 본문 저장 + `parse_job_posting`로 구조화
+- [x] **적합도(fit) 분석 저장**: `save_fit_analysis`
+- [x] **자소서 버전 관리**: `cover_letter_versions` 테이블 + 타임라인 (Documents 페이지)
+- [x] **지원 상태 관리**: 8단계 칸반 (Applications 페이지) + `update_application_status`
+- [x] **면접 준비 저장**: `save_interview_prep` (서류 합격 이상 해금)
+
+### Export
+- [x] **자소서 export**: `export_cover_letter` → `exports/` 디렉터리에 저장 (`format`: `md`(Markdown) 또는 `html`(인쇄용 HTML, 브라우저에서 PDF로 저장), 기본값 `md`)
+
+### 보안
+- [x] `127.0.0.1` 전용 바인딩
+- [x] **Host 허용목록**(DNS 리바인딩 차단)
+- [x] **CSRF 세션 토큰**: 변경 요청 보호, HTML `<meta>` 주입 방식
+- [x] **외부 Origin 차단**
+- [x] **정적 파일 경로 traversal 차단**
+- [x] **8MB 본문 제한**
+- [x] **민감 본문 보호**: 이력서/자소서 본문은 로그·에러 응답에 미노출
+
+### 설치 안내 / 문서 / 테스트
+- [x] **설치**: `npm install` → `npm start` (대시보드 자동 오픈), MCP 서버는 AI 클라이언트가 `npm run mcp`로 기동
+- [x] **설치 페이지**: `install-page`
+- [x] **문서**: `docs`
+- [x] **진단**: `npm run doctor`
+- [x] **타입 검사**: `npm run typecheck` (`tsc --noEmit`)
+- [x] **E2E 테스트** (`scripts/test.ts`, `npm test`): 17개 — 보안 / 업무 흐름 / MCP stdio / 대시보드↔MCP 동일 DB 양방향
+- [x] **UI 스모크 테스트** (`scripts/ui-smoke.ts`, `npm run test:ui`): Playwright로 8개 페이지 렌더 검증
+- [x] 두 테스트 스위트 모두 통과
+
+---
+
+## 후순위 / 향후 과제 (Backlog)
+
+아래 항목은 **지금은 제외하되, 구조는 열어둔다**. 즉 현재 MVP 범위에서 구현하지 않지만, 패키지 경계·데이터 모델·도구 인터페이스가 이후 추가를 수용할 수 있도록 설계되어 있다.
+
+### 공고 크롤링 (사람인 / 잡코리아 / 원티드)
+- 현재는 사용자가 공고 본문을 붙여넣으면 `parse_job_posting`이 구조화한다. URL 입력 시 자동 크롤링은 미구현.
+- 구조 개방: 파싱 로직이 `packages/parsers`로 분리되어 있어, 사이트별 크롤러/어댑터를 추가하는 형태로 확장 가능.
+- **지금은 제외, 구조는 열어둠.**
+
+### 클라우드 동기화
+- 현재 모든 데이터는 로컬(`~/.careermate`)에만 저장되며 외부 전송이 없다.
+- 구조 개방: 데이터 접근이 `packages/db`로 일원화되어 있어, 동기화 계층을 별도 어댑터로 얹을 여지가 있다.
+- **지금은 제외, 구조는 열어둠.** (로컬 전용·프라이버시가 현재 설계 원칙)
+
+### ChatGPT App / Claude Extension 마켓 등록
+- 현재는 사용자가 로컬에서 `npm run mcp`로 직접 MCP 서버를 연결한다.
+- 구조 개방: MCP stdio 서버(`apps/mcp`)가 표준 `@modelcontextprotocol/sdk`를 사용하므로, 패키징/배포 형태로 마켓 등록을 추진할 수 있다.
+- **지금은 제외, 구조는 열어둠.**
+
+### 브라우저 확장
+- 채용 사이트에서 공고를 바로 CareerMate로 보내는 확장.
+- 구조 개방: 로컬 API(`apps/web`)와 파서가 이미 분리되어 있어 확장에서 호출할 엔드포인트를 노출하는 형태로 연결 가능.
+- **지금은 제외, 구조는 열어둠.**
+
+### Tauri / Electron 데스크톱 래퍼
+- 현재는 Node + 브라우저 기반 로컬 앱으로 동작한다.
+- 구조 개방: 대시보드가 프레임워크/CDN 의존이 없는 정적 자산이라 데스크톱 셸로 감싸기에 적합하다.
+- **지금은 제외, 구조는 열어둠.**
+
+### DOCX export
+- 현재 export는 Markdown과 인쇄용 HTML(브라우저에서 PDF로 저장) 두 포맷만 지원한다(`packages/exporters`). 바이너리 DOCX 출력은 미구현.
+- 구조 개방: 출력 로직이 `packages/exporters`로 분리되어 있어, DOCX 등 포맷별 익스포터를 추가하는 형태로 확장 가능.
+- **지금은 제외, 구조는 열어둠.**
+
+### 다국어 (i18n)
+- 현재 UI/프롬프트는 단일 언어 중심이다.
+- 구조 개방: 프롬프트가 `packages/prompts`로, UI 문자열이 대시보드 자산으로 분리되어 있어 다국어 리소스 도입 여지가 있다.
+- **지금은 제외, 구조는 열어둠.**
+
+---
+
+## 비목표 (Non-Goals)
+
+- **CareerMate 내부에 LLM을 두지 않는다.** 분석·작성은 사용자의 AI(ChatGPT/Claude/Gemini)가 MCP를 통해 수행한다.
+- **로컬 우선 원칙을 깨지 않는다.** 위 향후 과제(특히 클라우드 동기화)는 사용자 선택형·옵트인 전제하에서만 검토한다.

package/docs/START_WORKFLOW.md

@@ -0,0 +1,125 @@
+# CareerMate 시작 런북 (연결 직후 AI용)
+
+설치·연결(`INSTALL.md`)이 끝난 직후, AI(당신)가 사용자를 빠르게 생산적으로 만들기 위해 따라가는 런북입니다. 도구는 정해진 순서로 호출하고, 매 단계 무엇을 하고 있는지 쉬운 한국어로 설명하세요. MCP·job_id 같은 기술 용어는 노출하지 마세요. 확실하지 않은 정보는 지어내지 말고 사용자에게 확인하세요.
+
+> 핵심 원칙: **분석과 글쓰기는 당신(AI)이 수행하고, CareerMate는 데이터를 제공·보관**합니다. 공고 분석이나 자기소개서 작성 전에는 항상 `get_application_context`를 먼저 호출해 근거 데이터를 가져오세요.
+
+---
+
+## A. 온보딩 (첫 연결 시 한 번)
+
+### 1. 현재 상태 확인 — `get_onboarding_status`
+
+- 연결 직후 가장 먼저 호출합니다.
+- 결과의 `has_profile` / `has_resume` / `has_cover_letter` / `has_experience` / `has_skills` / `has_job`, `profile_completeness`(0~100), `next_steps`를 확인합니다.
+- 사용자에게 "지금까지 등록된 정보"와 "앞으로 채우면 좋은 정보"를 짧게 안내합니다. **이미 채워진 항목은 다시 묻지 마세요.**
+- (선택) 가이드형 안내가 필요하면 `start_onboarding`을 호출해 단계별 지침을 받을 수 있습니다.
+
+### 2. 프로필 수집 및 저장 — `save_profile`
+
+- 사용자가 올린 이력서/자기소개서 파일 또는 직접 알려준 내용을 바탕으로 프로필을 구조화합니다.
+- 정리 항목: 이름, 연락처, 한 줄 소개(`headline`), 요약(`summary`), 희망 직무(`desired_roles`), 희망 근무 조건(`desired_conditions`).
+- **글쓰기 선호도**를 함께 물어보세요: 선호 문체(`preferred_tone`, 예: "담백하고 구체적")와 강조 포인트(`emphasis_points`). 이 두 값은 이후 자기소개서 품질에 직접 영향을 줍니다.
+- `save_profile`로 저장합니다. 전달한 필드만 갱신되고 나머지는 유지됩니다(부분 저장 안전). 한두 개만 바꿀 때는 `update_profile`을 사용해도 됩니다.
+- 파일에서 읽은 정보는 `source`를 `upload`, 사용자가 말로 준 정보는 `manual`로 표시합니다.
+
+### 3. 이력서 등록 — `add_resume`
+
+- 업로드한 이력서/경력기술서/포트폴리오 본문을 `add_resume`로 저장합니다.
+- `kind`(resume / career_description / portfolio / other)와 `title`을 적절히 지정하고, 대표 문서는 `is_primary=true`로 설정합니다. 대표 문서는 이후 `get_application_context`의 `primary_resume`로 노출됩니다.
+- `source`는 `upload`를 사용합니다.
+
+### 4. 자기소개서 등록 (있는 경우) — `add_cover_letter`
+
+- 기존 자기소개서가 있으면 `add_cover_letter`로 저장합니다(`title` + `content`). 특정 공고용이면 `job_id`를 연결합니다.
+- `content`를 함께 주면 첫 버전(v1)으로 저장됩니다. 학습/참고용 보관에 적합합니다.
+- 없으면 "나중에 공고를 분석한 뒤 맞춤 자기소개서를 써드릴 수 있어요"라고 안내만 합니다.
+
+### 5. 대시보드 열기 & 다음 단계 — `open_dashboard`
+
+- `open_dashboard`를 호출해 사용자가 자기 데이터를 눈으로 확인하게 합니다. (서버가 꺼져 있으면 `npm start` 안내를 돌려줍니다.)
+- 다시 `get_onboarding_status`로 완성도를 확인하고, 비어 있는 부분이 있으면 채우자고 제안합니다.
+- 마무리 제안: "지원하고 싶은 공고가 있으면 링크나 내용을 붙여주세요. 적합도를 분석해드릴게요."
+
+---
+
+## B. 공고 분석하기 (핵심 흐름)
+
+사용자가 공고 링크나 내용을 주면 아래 순서로 진행합니다.
+
+### 1. 공고 저장 — `save_job_posting`
+
+- `company`, `position`은 필수입니다. 공고 원문은 `description`에, 핵심 자격/우대는 `requirements` 배열에, 키워드는 `keywords`에 정리해 넣습니다.
+- (선택) 붙여넣은 원문을 빠르게 구조화하려면 먼저 `parse_job_posting`으로 회사명/직무/마감일 추정과 기술 키워드를 추출할 수 있습니다. 판단은 AI가 직접 하세요.
+- 저장하면 지원(application) 항목이 자동 생성되고 `job_id`가 반환됩니다. 같은 `url`이면 중복 없이 갱신됩니다.
+
+### 2. 지원 맥락 가져오기 — `get_application_context` ⭐ (반드시 먼저)
+
+- **공고 분석/자소서 작성 전에 반드시 호출합니다.** `job_id`를 넘기면 한 번의 호출로 다음을 모두 돌려줍니다:
+  프로필, 대표 이력서, 전체 경력·프로젝트·스킬, 기존 자기소개서, 최근 지원 이력, 대상 공고와 이전 적합도 분석, 같은 회사/직무 관련 기록, 사용자의 선호 문체·강조 포인트.
+- 이 데이터를 **근거로** 분석/작성하고, 결과는 아래 저장 도구로 다시 저장합니다.
+
+### 3. 적합도 분석 결과 저장 — `save_fit_analysis`
+
+- AI가 공고와 사용자 정보를 비교해 도출한 분석을 저장합니다. `job_id` 필수(2단계의 공고가 먼저 저장돼 있어야 함).
+- 채울 필드: `score`(0~100), `summary`, `strengths`(강점), `gaps`(보완 필요), `matched_keywords` / `missing_keywords`, `recommendations`(자소서·지원 전략 제안).
+- 같은 공고에 다시 저장하면 갱신됩니다.
+
+---
+
+## C. 맞춤 자기소개서 쓰기
+
+### 1. (아직 안 했다면) `get_application_context`로 근거 확보
+
+- 선호 문체·강조 포인트·경력·대상 공고를 가져와 작성의 근거로 삼습니다.
+
+### 2. 새 버전 저장 — `save_cover_letter_version`
+
+- AI가 작성한 자기소개서를 새 버전으로 저장합니다(자소서 작성 워크플로우의 핵심 저장 단계).
+- `cover_letter_id`를 주면 기존 자소서에 새 버전을 추가하고, 없으면 새 자소서를 만들어 v1로 저장합니다(이때 `title` 권장).
+- `note`에 이 버전의 변경 요약(예: "지원동기 보강")을 남기면 사용자가 대시보드 버전 히스토리를 이해하기 쉽습니다.
+- `job_id`로 공고에 연결하면 지원 항목과 자동 연결됩니다.
+
+### 3. (요청 시) 파일로 내보내기 — `export_cover_letter`
+
+- 사용자가 "파일로 받고 싶어"라고 하면 `cover_letter_id`와 `format`(`md` 기본 / 인쇄용 `html`)으로 내보냅니다. 파일은 `~/.careermate/exports`에 저장되고 경로를 알려줍니다.
+
+---
+
+## D. 지원 상태 관리
+
+### `update_application_status`
+
+- 지원 상태를 변경합니다. 가능한 상태: saved(저장됨), applied(지원함), document_passed(서류 합격), interview(면접), offer(합격/오퍼), rejected(불합격), closed(종료) 등.
+- `note`에 변경 사유를 남길 수 있습니다.
+- 상태가 **서류 합격(document_passed) 이상**으로 바뀌면 면접 준비를 제안하는 힌트를 함께 돌려줍니다 → 다음 단계(E)로 이어집니다.
+
+---
+
+## E. 면접 준비
+
+### `save_interview_prep`
+
+- 보통 상태가 서류 합격으로 바뀐 뒤 진행합니다. 먼저 `get_application_context`(또는 `get_job_posting`)로 공고·직무·자소서를 가져와 근거로 삼으세요.
+- AI가 생성한 자료를 저장합니다: 예상 면접 질문, 꼬리 질문, STAR 답변 가이드, 1분 자기소개 초안 등. `job_id` 필수. 같은 공고에 다시 저장하면 갱신됩니다.
+- 저장 후 `open_application`(또는 `open_dashboard`)으로 사용자가 면접 페이지에서 바로 확인하게 안내합니다.
+
+---
+
+## 보조 도구
+
+- `get_workflow_guide` — 표준 워크플로우(온보딩, 공고 분석, 자소서 작성, 상태 관리, 면접 준비)의 단계별 안내. 어떤 순서로 어떤 도구를 호출할지 확인할 때 사용. `workflow_id` 생략 시 전체 목록.
+- `list_recent_activity` — 최근 활동(공고 저장, 적합도 분석, 자소서 버전, 상태 변경, 면접 준비 등). "최근에 뭐 했지?" 또는 작업을 이어갈 맥락이 필요할 때.
+- `list_jobs` / `get_job_posting` — 저장된 공고 목록 / 단건 상세(적합도·상태·연결 자소서·면접 준비 포함).
+- `get_profile` / `get_resumes` / `get_cover_letters` — 저장된 데이터 조회.
+- `open_dashboard` / `open_application` — 사용자가 결과를 눈으로 확인하도록 브라우저에서 페이지 열기.
+
+## 빠른 요약 — 공고 1건을 끝까지 처리하는 표준 경로
+
+1. `save_job_posting` — 공고 저장 (`job_id` 획득)
+2. `get_application_context` (`job_id`) — 근거 데이터 확보 ⭐
+3. `save_fit_analysis` — 적합도 분석 저장
+4. `save_cover_letter_version` — 맞춤 자소서 버전 저장
+5. `update_application_status` — 지원 상태 갱신
+6. `save_interview_prep` — (서류 합격 후) 면접 준비 저장
+7. `open_application` / `open_dashboard` — 사용자에게 결과 보여주기

package/docs/SUPPORTED_AI_APPS.md

@@ -0,0 +1,60 @@
+# 지원 AI 앱 (Supported AI Apps)
+
+CareerMate는 LLM이 없는 **로컬 MCP 도구**입니다. 그래서 *내 컴퓨터에서 로컬 프로그램을 직접 실행할 수 있는* AI 앱에서만 동작합니다. 1차 지원(first-class) 앱은 다음 셋입니다.
+
+| 앱 | 영구 지침 | MCP 등록 위치 |
+| --- | --- | --- |
+| **Claude Desktop** | — | `.mcpb` 번들 (원클릭) |
+| **Claude Code** | 루트 `CLAUDE.md` | 프로젝트 `.mcp.json` |
+| **Codex** (OpenAI Codex CLI) | 루트 `AGENTS.md` | `~/.codex/config.toml` |
+
+---
+
+## Claude Desktop
+
+Claude Desktop이 Node를 내장 제공하므로 미리 깔 것이 없습니다.
+
+1. **Claude Desktop 설치**
+2. **`careermate.mcpb` 받기** — Release `v0.1.0`에 첨부돼 있으나 저장소가 **비공개**라 접근 권한이 있어야 받을 수 있습니다. 그 외에는 소스에서 `npm run build:mcpb`로 직접 빌드하세요.
+3. **더블클릭** (또는 Settings → Extensions 로 끌어다 놓기)
+4. **Claude Desktop 재시작**
+
+---
+
+## Claude Code
+
+CareerMate 폴더 안에서 실행하는 것이 핵심입니다.
+
+1. **Claude Code 실행** (CareerMate 폴더에서)
+2. 프롬프트 입력:
+   > "CareerMate를 설치하고 설정해줘. INSTALL.md를 따라 진행해줘."
+
+프로젝트 스코프 `.mcp.json`을 CareerMate 폴더에 등록하고, 첫 실행 때 **1회 승인**을 묻습니다. 승인하면 끝입니다.
+
+---
+
+## Codex
+
+OpenAI Codex CLI(로컬 코딩 에이전트)에서 동작합니다.
+
+1. **Codex 실행** (CareerMate 폴더에서)
+2. 프롬프트 입력:
+   > "CareerMate를 설치하고 설정해줘. INSTALL.md를 따라 진행해줘."
+
+`~/.codex/config.toml`의 `[mcp_servers.careermate]` 항목을 등록합니다. Codex 안에서 `/mcp` 명령으로 연결을 확인하세요.
+
+---
+
+## 그 외 — 기타 MCP 클라이언트
+
+Cursor · Cline · Windsurf 등 로컬 stdio MCP를 지원하는 클라이언트도 동작합니다. CareerMate 폴더에서 `npm run init`(또는 설정만 출력하는 `npm run init -- --print`)으로 등록하세요.
+
+## 동작하지 않는 것
+
+**ChatGPT / Gemini 웹·모바일은 동작하지 않습니다.** 이들은 클라우드에서 실행되므로 내 컴퓨터의 **로컬 stdio MCP 서버에 닿을 수 없습니다.** 로컬에서 도는 Codex(CLI) · Claude Code · Claude Desktop만 CareerMate를 쓸 수 있습니다.
+
+---
+
+설치 절차 전체는 [/INSTALL.md](../INSTALL.md)(AI용 런북)를 따르세요. 클라이언트별 **수동 MCP 설정 스니펫**은 [docs/INSTALL.md](./INSTALL.md), 사람용 두 갈래 설치는 [docs/INSTALL_AND_USAGE.md](./INSTALL_AND_USAGE.md)를 참고하세요.
+
+각 모드의 **영구 지침 파일**: Claude Code → [/CLAUDE.md](../CLAUDE.md), Codex → [/AGENTS.md](../AGENTS.md).