velog_mcp: Instructions file for Codex

AGENTS.md

프로젝트 개요

velog-mcp-claude는 Claude가 Velog 콘텐츠를 초안 작성, 발행, 수정, 삭제, 조회할 수 있게 해주는 Node.js 18+ 기반 MCP 서버입니다. Velog의 비공개 GraphQL 및 REST API를 사용합니다.

이 프로젝트는 리버스 엔지니어링 기반의 비공식 연동입니다. Velog API 동작은 언제든 바뀔 수 있다고 보고, 발행이나 삭제처럼 되돌리기 어렵거나 공개 범위에 영향을 주는 작업은 반드시 사용자의 검토를 거치세요.

스택과 명령어

• 런타임: Node.js 18+, ESM ("type": "module").
• 언어: TypeScript, strict 활성화, NodeNext 모듈 해석.
• 원본 소스: src/.
• 빌드 결과물: dist/; 생성된 파일을 직접 수정하지 마세요.
• 포맷/린트: Biome, 공백 2칸 들여쓰기, 큰따옴표.

저장소 루트에서 다음 명령을 사용하세요.

npm run build      # TypeScript를 dist/로 컴파일
npm run lint       # Biome 검사
npm run lint:fix   # Biome 자동 수정 및 import 정리
npm run health     # 실제 Velog API 스모크 테스트; ~/.velog-mcp.json 필요
npm run dev        # tsc --watch
npm start          # dist/index.js 실행
npm run setup      # dist/setup.js 실행

TypeScript를 변경한 뒤에는 npm run build를 실행하세요. Biome 검사 대상인 소스나 문서를 변경했다면 npm run lint를 실행하세요. npm run health는 실제 Velog 토큰 접근이 필요하다고 명확히 판단될 때만 실행하세요.

아키텍처

• src/index.ts는 MCP 툴 스키마를 정의하고 툴 호출을 라우팅합니다.
• src/tools/index.ts는 개별 툴 구현을 다시 export합니다.
• src/tools/*.ts는 포스트, 초안, 댓글, 좋아요, 검색, 트렌딩, 알림, 읽을 목록, RSS, 시리즈, 태그, 임시저장, 업로드, GitHub 가져오기 등 기능 영역별 구현을 담습니다.
• src/auth.ts는 Velog 토큰 로드, Set-Cookie 기반 토큰 갱신, 공용 GraphQL 래퍼를 담당합니다.
• src/setup.ts는 설정 CLI 진입점입니다.
• scripts/health-check.mjs는 실제 인증/읽기/트렌딩/쓰기-삭제 검사를 수행합니다.
• docs/overview.md, docs/security.md, docs/roadmap.md에는 로컬 아키텍처, 안전 주의사항, 기능 방향이 정리되어 있습니다.

새 MCP 툴을 추가할 때는 관련 위치를 모두 갱신하세요.

1. src/tools/<name>.ts에 툴을 구현합니다.
2. src/tools/index.ts에서 export합니다.
3. src/index.ts의 ListToolsRequestSchema에 툴 스키마를 추가합니다.
4. CallToolRequestSchema의 switch 문에 Zod 검증과 호출 분기를 추가합니다.
5. 사용자에게 노출되는 동작이 바뀌면 README.md와 관련 문서를 갱신합니다.

API와 동작 메모

• Velog GraphQL 엔드포인트: https://v2.velog.io/graphql.
• 이미지 업로드 엔드포인트: https://v3.velog.io/api/files/v3/upload.
• 트렌딩 데이터는 https://cache.velcdn.com에서 가져옵니다.
• GraphQL 요청에는 유효한 operationName을 포함하세요. 일부 mutation은 이것이 없으면 실패하거나 null을 반환합니다.
• 작성/수정 mutation에서는 기존 코드가 명시적으로 null을 전달하는 필드를 유지하세요. 특히 thumbnail, series_id, token에 주의하세요.
• 초안은 프로세스 메모리에만 저장됩니다(src/tools/draft.ts). MCP 서버를 재시작하면 발행하지 않은 초안은 사라집니다.