# velog-mcp

Claude Code(또는 다른 MCP 클라이언트)에서 벨로그(velog.io)에 직접 글을 발행할 수 있게 해주는
개인용 MCP 서버입니다.

**중요: 벨로그는 공식 글쓰기 API를 제공하지 않습니다.** 이 프로젝트는 velog.io 프론트엔드가
내부적으로 쓰는 비공식 GraphQL 엔드포인트(`v3.velog.io/graphql`)를 사용합니다. 벨로그 측이 이
스키마를 언제든 바꾸거나 접근을 막을 수 있으므로, 실패 시 Playwright로 실제 브라우저를 띄워
에디터를 조작하는 방식으로 자동 폴백하도록 만들었습니다.

## 동작 방식

1. `velog_login` 도구로 최초 1회 브라우저 로그인 (이후 세션은 프로필에 저장되어 재사용됨)
2. `velog_create_post` 호출 시 저장된 프로필에서 현재 세션 쿠키를 읽어와 GraphQL `writePost`
   뮤테이션으로 시도 (페이지를 한 번 로드해서 velog 자체 토큰 갱신 로직이 동작할 기회를 줌)
3. 그래도 실패하면(스키마 변경, 세션 만료 등) Playwright로 `velog.io/write` 페이지를
   직접 조작해 발행 (같은 로그인 프로필 재사용)

## 설치

\`\`\`bash
npm install
npx playwright install chromium
npm run build
\`\`\`

## 계정/세션 설정 (가장 중요한 단계)

토큰을 수동으로 복사할 필요 없습니다. Claude Code에서 `velog_login` 도구를 호출하면:

1. 브라우저 창이 뜸
2. 평소처럼 velog에 로그인 (아이디/비번, 소셜 로그인 다 가능)
3. 로그인 인식되면 창이 자동으로 닫히고 세션이 저장됨

> 오늘 벨로그 main 계정으로 로그인해줘

세션은 프로젝트 폴더가 아니라 홈 디렉토리에 저장됩니다:
- `~/.velog-mcp/accounts.json` — 별칭 ↔ username 매핑 (파일 권한 600)
- `~/.velog-mcp/profiles/<별칭>/` — 실제 로그인 쿠키가 담긴 Chromium 프로필

여러 벨로그 계정을 쓴다면 `velog_login`을 다른 `account` 별칭으로 여러 번 실행하면 됩니다.
도구 호출 시 `account` 파라미터로 별칭을 지정합니다.

⚠️ **보안 주의**
- `~/.velog-mcp/profiles/<별칭>/`은 로그인 쿠키를 담고 있어 사실상 비밀번호와 동일합니다.
  절대 git에 커밋하거나 다른 사람과 공유/백업하지 마세요.
- `~/.velog-mcp/` 는 `.gitignore`에도 걸려있지만, 애초에 프로젝트 폴더 밖에 두는 것이 안전합니다.
- 세션이 이상하면 벨로그에서 로그아웃 후 `velog_login`을 다시 실행해서 프로필을 새로 만드세요.
- 세션 완전히 폐기하려면 해당 `~/.velog-mcp/profiles/<별칭>/` 폴더를 직접 삭제하면 됩니다.

## Claude Code에 등록하기

Claude Code의 MCP 설정 파일(`~/.claude/mcp_servers.json` 또는 프로젝트별 설정)에 추가:

\`\`\`json
{
  "mcpServers": {
    "velog": {
      "command": "node",
      "args": ["/절대/경로/velog-mcp/dist/index.js"]
    }
  }
}
\`\`\`

등록 후 Claude Code에서 예:

> 오늘 작업한 내용 정리해서 velog 계정 main으로 "이번 주 SM 작업 정리"라는 제목으로 발행해줘

## 제공 도구

| 도구 | 설명 |
|---|---|
| `velog_login` | 브라우저로 로그인, 세션 저장/갱신 |
| `velog_list_accounts` | 등록된 계정 별칭 조회 |
| `velog_create_post` | 새 글 작성 (GraphQL → 실패 시 Playwright 폴백) |
| `velog_edit_post` | 기존 글 수정 (GraphQL 전용) |
| `velog_list_posts` | 최근 글 목록 조회 |

## 알려진 한계

- 세션 쿠키를 읽어올 때마다 헤드리스 브라우저로 `velog.io`를 한 번 로드합니다(약 1~3초 오버헤드).
  글 하나 쓸 때 크게 문제되는 수준은 아닙니다.
- Playwright 폴백의 CSS 셀렉터(`textarea[placeholder*="제목"]` 등)는 velog 에디터 UI가
  바뀌면 깨질 수 있습니다. 문제가 생기면 `playwrightFallback.ts`의
  `chromium.launchPersistentContext(..., { headless: false })`로 바꿔서
  직접 화면을 보며 셀렉터를 갱신하세요.
- 로그인 세션(`~/.velog-mcp/profiles/<별칭>/`)이 완전히 만료되면 `velog_login`을
  다시 실행해야 합니다. velog 쪽 세션 유효 기간에 따라 달라져 정확한 주기는 알 수 없습니다.
- 이 방식은 velog의 이용약관 범위를 벗어나지 않는 "본인 계정으로 본인 글 발행 자동화"에
  한정해서 쓰는 것을 전제로 합니다.