careermate 0.1.0

package/dist/mcpb-stage/README.md

@@ -0,0 +1,219 @@
+# CareerMate
+
+**MCP 우선(MCP-first) 로컬 커리어 관리 도구.** ChatGPT·Claude·Gemini 같은 당신의 AI를 인터페이스로 쓰고, CareerMate는 당신의 커리어 데이터를 **이 컴퓨터에만** 저장한 뒤 MCP로 노출합니다.
+
+---
+
+## 핵심 철학
+
+- **MCP 우선** — 새 앱 사용법을 익힐 필요가 없습니다. 평소 쓰던 AI(ChatGPT·Claude·Gemini)와 대화하면, 그 AI가 CareerMate의 로컬 MCP 도구를 호출해 당신의 커리어 DB를 읽고 씁니다.
+- **로컬 우선** — 모든 데이터는 당신의 컴퓨터에만 저장됩니다(`~/.careermate`). 외부 서버로 전송하지 않습니다. 대시보드 웹 서버는 `127.0.0.1`(이 컴퓨터)에만 연결됩니다.
+- **LLM 비내장** — CareerMate 안에는 AI가 들어 있지 않습니다. 분석·글쓰기 같은 “생각하는 일”은 **당신의 AI**가 하고, CareerMate는 데이터를 **안전하게 보관·조회**하는 역할만 합니다.
+
+> 쉽게 말해: 당신의 AI가 “두뇌”, CareerMate는 그 두뇌가 꺼내 쓰는 “커리어 서랍장”입니다.
+
+---
+
+## 무엇을 하나요?
+
+프로필·이력서·자기소개서·채용공고·지원 현황·면접 준비를 로컬 SQLite에 구조화해 저장하고, AI 어시스턴트가 MCP 도구로 그 데이터를 읽고 씁니다. 전형적인 흐름은 이렇습니다.
+
+1. 프로필·이력서 등록 → 2. 채용공고 저장·파싱 → 3. 적합도(핏) 분석 → 4. 맞춤 자기소개서 작성·버전 관리 → 5. 지원 상태 관리 → 6. 면접 준비
+
+언제든 대시보드를 열어 저장된 데이터를 눈으로 확인할 수 있습니다. 자세한 단계별 런북은 [`docs/START_WORKFLOW.md`](docs/START_WORKFLOW.md)를 참고하세요.
+
+---
+
+## 주요 기능
+
+- **AI와 대화로 모든 작업** — MCP 도구 23개로 온보딩·프로필·이력서·자소서·공고·핏 분석·지원 상태·면접 준비까지 처리.
+- **지원 상태 8단계 관리** — `draft`(작성 중) · `planned`(지원 예정) · `applied`(지원 완료) · `document_passed`(서류 합격) · `interview`(면접 진행) · `final_passed`(최종 합격) · `rejected`(불합격) · `on_hold`(보류). `document_passed` 이상에서 면접 준비가 해금됩니다.
+- **자기소개서 버전 관리** — 공고별로 자소서 버전을 쌓고 타임라인으로 비교, 파일로 내보내기.
+- **채용공고 파싱** — 붙여넣은 공고 텍스트를 구조화해 저장.
+- **로컬 대시보드** — 프레임워크·CDN 없는 바닐라 JS로 만든 7페이지 웹 화면(다크모드 지원).
+- **데이터 내보내기/삭제** — Settings 페이지에서 직접.
+
+---
+
+## 구성
+
+두 개의 로컬 프로세스가 같은 데이터베이스를 공유합니다.
+
+| 프로세스 | 실행 | 역할 |
+| --- | --- | --- |
+| **대시보드 웹 서버** | `npm start` | `http://127.0.0.1:4319` — 내 데이터를 눈으로 확인·관리. `127.0.0.1`에만 바인딩. |
+| **MCP 서버** | `npm run mcp` | stdio 기반. 보통 AI 클라이언트가 자동 실행. 도구 23개 제공. |
+
+---
+
+## 빠른 시작
+
+### 요구사항
+
+- **Node.js >= 22.5.0** — 내장 `node:sqlite`를 사용하므로 컴파일러나 네이티브 빌드가 **필요 없습니다**.
+- 버전 확인:
+  ```bash
+  node --version
+  ```
+  `v22.5.0` 미만이거나 명령을 찾지 못하면 https://nodejs.org 에서 최신 LTS를 설치하세요.
+
+### 1) 설치
+
+빌드 단계가 없습니다. TypeScript는 `tsx`로 바로 실행됩니다.
+
+```bash
+npm install
+```
+
+### 2) 대시보드 실행
+
+```bash
+npm start
+```
+
+- 기본 주소는 `http://127.0.0.1:4319` 이며 브라우저가 자동으로 열립니다.
+- 포트가 사용 중이면 자동으로 다음 빈 포트로 폴백하니, 터미널에 출력된 실제 주소를 확인하세요.
+- 종료는 터미널에서 `Ctrl+C`.
+
+### 3) 데모 데이터로 둘러보기(선택)
+
+빈 화면이 낯설다면 예시 데이터를 넣어 기능을 미리 체험할 수 있습니다.
+
+```bash
+npm run seed
+```
+
+### 4) AI(MCP)에 연결
+
+당신의 AI가 CareerMate를 사용하려면 AI 클라이언트에 MCP 서버를 등록해야 합니다. Claude Desktop·ChatGPT·Cursor 등 클라이언트별 설정과 검증 방법은 **[`docs/INSTALL.md`](docs/INSTALL.md)** 를 따라가세요.
+
+---
+
+## 대시보드 7페이지
+
+| 페이지 | 설명 |
+| --- | --- |
+| **Home** | 현재 상태·다음 할 일 한눈에. |
+| **Profile** | 프로필, 경력(experiences), 프로젝트, 스킬 관리. |
+| **Jobs** | 저장한 채용공고 목록과 상세(공고 내용·핏 분석). |
+| **Applications** | 지원 현황을 8단계 상태로 보는 칸반 보드. |
+| **Documents** | 자기소개서 버전 타임라인과 이력서. |
+| **Interview** | 면접 준비 자료(`document_passed` 이상에서 해금). |
+| **Settings** | 데이터 내보내기·삭제, 환경 정보. |
+
+다크모드를 지원합니다.
+
+---
+
+## MCP 도구 한눈에 (23개)
+
+| 분류 | 도구 |
+| --- | --- |
+| 온보딩 | `get_onboarding_status` · `start_onboarding` |
+| 프로필 | `save_profile` · `get_profile` · `update_profile` |
+| 이력서 | `add_resume` · `get_resumes` |
+| 자기소개서 | `add_cover_letter` · `get_cover_letters` · `save_cover_letter_version` · `export_cover_letter` |
+| 채용공고 | `save_job_posting` · `get_job_posting` · `list_jobs` · `parse_job_posting` |
+| 핵심 컨텍스트 | **`get_application_context`** (지원에 필요한 맥락을 한 번에 모아줌) |
+| 핏 분석 | `save_fit_analysis` |
+| 지원 상태 | `update_application_status` |
+| 면접 준비 | `save_interview_prep` |
+| 대시보드/활동 | `open_dashboard` · `open_application` · `list_recent_activity` · `get_workflow_guide` |
+
+이 도구들 위에 5종의 워크플로우(`onboarding`, `analyze_job`, `write_cover_letter`, `manage_application_status`, `prepare_interview`)가 정의되어 있어, AI가 단계별로 자연스럽게 안내합니다.
+
+---
+
+## 프로젝트 구조
+
+```
+CareerMate/
+├─ apps/
+│  ├─ web/            # 대시보드 + 로컬 API 서버 (npm start)
+│  └─ mcp/            # MCP stdio 서버 (npm run mcp)
+├─ packages/
+│  ├─ shared/         # 공용 타입·zod 스키마·유틸
+│  ├─ db/             # node:sqlite DB 접근·스키마·마이그레이션
+│  ├─ core/           # 도메인 유스케이스
+│  ├─ mcp-tools/      # MCP 도구 23개 정의
+│  ├─ exporters/      # 내보내기(자소서 등)
+│  ├─ parsers/        # 채용공고 파싱
+│  ├─ prompts/        # 프롬프트·안내 문구
+│  └─ workflows/      # 워크플로우 5종
+├─ install-page/      # 설치 안내 페이지
+├─ docs/              # 문서
+├─ scripts/           # migrate / seed / doctor / test 등
+└─ package.json
+```
+
+- **스택**: TypeScript(ESM), 무빌드 실행(`tsx`), 내장 `node:sqlite`(네이티브 컴파일 없음), `zod`, `@modelcontextprotocol/sdk`. 대시보드는 프레임워크·CDN 없는 바닐라 JS + 자체 CSS 디자인 시스템.
+- **데이터 저장소**: 12개 테이블(profile, experiences, projects, skills, documents, cover_letters, cover_letter_versions, jobs, fit_analyses, applications, interview_preps, activities). 두 프로세스(대시보드·MCP)가 **같은 SQLite DB**를 공유합니다.
+
+---
+
+## npm 스크립트
+
+| 스크립트 | 설명 |
+| --- | --- |
+| `npm install` | 의존성 설치 (빌드 없음) |
+| `npm start` | 대시보드 웹 서버 실행 |
+| `npm run dev` | 대시보드 실행 (파일 변경 시 자동 재시작) |
+| `npm run mcp` | MCP 서버 실행 (stdio) |
+| `npm run migrate` | DB 생성/업그레이드 |
+| `npm run doctor` | 설치/환경 점검 |
+| `npm run seed` | 예시 데이터 삽입 |
+| `npm test` | E2E 테스트 실행 |
+| `npm run test:ui` | Playwright UI 스모크 테스트 |
+| `npm run typecheck` | 타입 검사 (`tsc --noEmit`) |
+
+---
+
+## 데이터 위치 & 환경변수
+
+- 기본 폴더: `~/.careermate` (Windows: `%USERPROFILE%\.careermate`).
+  - `careermate.sqlite` — 데이터베이스 파일
+  - `exports/` — 내보낸 파일
+  - `backups/` — 백업
+  - `uploads/` — 업로드 파일
+  - `server.json` — 실행 중 핸드셰이크 정보
+- 환경변수로 동작을 바꿀 수 있습니다.
+  - `CAREERMATE_DATA_DIR` — 데이터 폴더 위치 변경
+  - `CAREERMATE_PORT` — 대시보드 포트 고정
+  - `CAREERMATE_NO_OPEN` — 시작 시 브라우저 자동 열기 끄기
+
+---
+
+## 보안 / 프라이버시
+
+- **로컬 전용 바인딩** — 대시보드 서버는 `127.0.0.1`(loopback)에만 바인딩되어 외부에서 접근할 수 없습니다.
+- **DNS 리바인딩 차단** — Host 허용목록으로 검증.
+- **변경 요청 보호** — CSRF 세션 토큰(HTML `meta`로 주입), 외부 Origin 차단.
+- **정적 파일 보호** — 경로 traversal(상위 폴더 탈출) 차단.
+- **본문 크기 제한** — 요청 본문 8MB 제한.
+- **민감 정보 비노출** — 이력서·자기소개서 본문은 로그나 에러 응답에 노출되지 않습니다.
+- **외부 전송 없음** — MCP 서버는 네트워크 호출을 하지 않으며, 모든 데이터는 당신의 컴퓨터에만 남습니다. 내보내기·삭제는 대시보드 **Settings**에서 직접 할 수 있습니다.
+
+---
+
+## 문서
+
+- [`docs/INSTALL.md`](docs/INSTALL.md) — 설치 및 AI 클라이언트(MCP) 연결 가이드.
+- [`docs/START_WORKFLOW.md`](docs/START_WORKFLOW.md) — 등록부터 면접 준비까지 단계별 작업 런북.
+
+---
+
+## 테스트
+
+```bash
+npm test        # E2E 테스트 (보안·업무흐름·MCP stdio·대시보드↔MCP 동일 DB 양방향)
+npm run test:ui # 대시보드 페이지 렌더 스모크 (Playwright)
+npm run typecheck
+```
+
+기타 유용한 스크립트: `npm run migrate`(DB 생성/업그레이드), `npm run seed`(예시 데이터), `npm run doctor`(설치·환경 점검).
+
+---
+
+## 라이선스
+
+MIT.