chrome-bookmarks-mcp

진행 중 — 워킹 스켈레톤입니다. 도구는 조각조각 추가되며, docs/milestones/를 참조하세요.

이 MCP 서버는 Claude에게 Chrome(및 Brave/Edge) 북마크에 대한 읽기/쓰기 접근 권한을 제공하여 에이전트 기반 재구성을 지원합니다: 트리 분석, 폴더 구조 제안, 스냅샷 및 롤백이 포함된 일괄 이동/이름 변경/삭제 계획, 중복 제거, 끊어진 링크 감지, 그리고 Chrome의 History 데이터베이스를 통한 오래된 북마크 감지.

아키텍처

Claude Desktop / Claude Code
        ⇅ stdio (MCP)
  packages/mcp-server   (Node.js / TypeScript, SDK-free tool seam)
        ⇅ WebSocket on 127.0.0.1:<PORT>   (localhost only)
  packages/extension    (Manifest V3 service worker)
        ⇅ chrome.bookmarks API
  Live Chrome — changes visible instantly, sync-safe

쓰기는 오직 확장 프로그램(chrome.bookmarks)을 통해서만 이루어집니다. Chrome의 Bookmarks 파일은 절대 쓰지 않습니다. 읽기는 현재 Bookmarks 파일을 파싱하며, 확장 프로그램을 통한 실시간 읽기는 이후 마일스톤에서 제공됩니다.

도구

쓰기 도구(계획: plan_*, apply_plan, rollback)는 BOOKMARKS_ENABLE_WRITE=1일 때만 표시됩니다. 각각은 기본적으로 dryRun: true로 설정되고 먼저 스냅샷을 만듭니다. docs/adr/0002-write-path-and-safety.md를 참조하세요.

빠른 시작 (Claude Code, 이 저장소에서)

pnpm install && pnpm build

저장소 루트의 .mcp.json이 서버를 chrome-bookmarks로 등록합니다. *"내 북마크 브리지 상태는 무엇인가요?"*라고 물어보면 → bookmarks_status입니다. 실시간 액세스를 위해서는 확장 프로그램을 로드하세요: chrome://extensions → 개발자 모드 → 압축 해제된 확장 프로그램 로드 → packages/extension/dist.

구성(env): BOOKMARKS_BROWSER (chrome|brave|edge) · BOOKMARKS_PROFILE (Default) · BOOKMARKS_WS_PORT (48765; 확장 프로그램은 chrome.storage.local.wsPort를 읽으며 기본값은 48765) · BOOKMARKS_ENABLE_WRITE · BOOKMARKS_FILE (경로 재정의) · BOOKMARKS_LOG_LEVEL.

개발

./init.sh            # deps, typecheck, build, smoke
pnpm verify          # typecheck + lint + test — the only definition of "done"
make ext             # build the unpacked extension → packages/extension/dist
pnpm -F @chrome-bookmarks-mcp/server inspect   # MCP Inspector

이 저장소가 에이전트와 함께 개발되는 방식: CLAUDE.md (규칙), CONTEXT.md (용어), docs/adr/ (결정 사항), docs/milestones/ (현재 진행 중인 유일한 계획), docs/blessed-paths/ (레시피), .claude/ (권한, 훅, 서브에이전트, 경로 범위 규칙).

AI 출처 표기

AI 생성 라인은 git notes를 통해 Git AI로 추적됩니다 (git log --show-notes=ai, git ai stats).

라이선스

MIT