peek

이 README의 모든 스크린샷은 단 한 번의 set_layout MCP 호출로 생성되었습니다 — 자세한 내용은 apps/desktop/scripts/screenshot.mjs를 참조하세요.

peek은 MCP 서버를 겸하는 데스크톱 데이터베이스 GUI입니다. Claude에게 테이블을 열어 달라고, 쿼리를 실행해 달라고, 또는 비교를 위해 패널을 배치해 달라고 요청하면 — 그 일이 바로 눈앞의 창에서 일어납니다. AI 도구 호출과 사용자의 클릭이 하나의 명령 채널을 공유하기 때문입니다. 내장된 채팅 패널이 앱 안에서 Claude Code를 실행하므로, 대화하는 에이전트가 자신이 살고 있는 창을 직접 조작합니다.

기능

• 🤝 인간과 AI를 위한 하나의 UI — 모든 클릭과 모든 MCP 도구 호출은 동일한 버스 위의 Command입니다. 숨은 상태도, 동기화 단계도 없습니다.

• 💬 Claude Code 내장 — 채팅 패널이 ACP를 통해 Claude Code를 호스팅하며, peek의 자체 MCP 서버에 연결됩니다.

• 🛠️ 16개의 MCP 도구 — 연결, 스키마 탐색, 쿼리 실행, 뷰 열기, 레이아웃 제어, 알림, 사용자 질문

• 🔒 서버가 강제하는 읽기 전용 — 읽기 전용 트랜잭션과 플래그를 사용하며, 어디에도 키워드 필터링이 없습니다.

• 📎 데이터는 사용자가 첨부할 때만 AI에 도달 — 그 외에는 쿼리가 모델에 최대 20행만 반환합니다.

• 📦 데이터베이스는 플러그인 — 6개의 드라이버가 ~/.peek/packages/<id>/에서 로드됩니다. 추가하려면 디렉터리를 설치하면 됩니다.

• ⚡ 백만 행 스크롤 — 드롭된 프레임 0개, 시작 약 0.5초, 번들 6.3MB (성능)

• 🔑 비밀번호는 OS 키체인에 저장 — 디스크에 평문으로 저장되지 않습니다.

지원 데이터베이스: PostgreSQL · MySQL · SQLite · Redis · Qdrant · Neo4j

Related MCP server: MCP Server for Database

설치

Releases에서 peek-v0.0.1-macos-arm64.zip을 다운로드하고, 압축을 푼 다음 peek.app을 응용 프로그램 폴더에 넣으세요. 현재는 Apple Silicon만 지원합니다.

이 빌드는 임시 서명되었습니다 (아직 Developer ID 없음). 따라서 macOS는 첫 실행 시 다운로드한 앱을 "손상됨"으로 거부합니다. 격리 플래그를 한 번만 해제하면 정상적으로 열립니다:

xattr -d com.apple.quarantine /Applications/peek.app

또는: 시스템 설정 → 개인정보 보호 및 보안 → "그래도 열기". 서명 및 공증된 빌드가 계획되어 있습니다.

빠른 시작

요구 사항: Node ≥ 22, pnpm 10.32.1 (packageManager로 고정), 그리고 연결할 데이터베이스. 현재까지 macOS / Apple Silicon에서만 개발 및 테스트되었습니다.

pnpm install
pnpm dev              # opens the window; MCP server on port 7332
pnpm build            # production bundles into apps/desktop/out

앱에서: 사이드바에서 드라이버를 선택하고, 연결 문자열을 붙여넣은 다음 탐색하세요. 핸드셰이크를 완료한 연결은 자동으로 저장됩니다 (비밀번호는 OS 키체인으로 이동). 테이블은 가상화된 그리드로 열리고, SQL은 ⌘⏎로 실행되는 CodeMirror 편집기에서 실행되며, 패널은 ⌘\ / ⌘⇧\로 분할됩니다. 모든 결과 뷰에는 실제 데드라인에 기반한 취소 버튼이 있습니다.

테스트

pnpm -r typecheck     # strict TS across every package
pnpm -r test          # 2567 tests; driver suites need real servers (see below)

데스크톱 테스트 스위트는 순수 로직만으로 구성되어 아무것도 필요하지 않습니다. 각 드라이버 스위트는 환경에서 대상 서버를 읽고, 서버에 연결할 수 없으면 스스로 건너뛰는 통합 테스트입니다:

PEEK_TEST_PG_URL="postgresql://user@localhost:5432/your_db" \
PEEK_TEST_REDIS_URL="redis://localhost:6379" \
PEEK_TEST_QDRANT_URL="http://localhost:6333" \
PEEK_TEST_MYSQL_URL="mysql://root:pw@localhost:3306/peek_test" \
PEEK_TEST_NEO4J_URL="bolt://localhost:7687" PEEK_TEST_NEO4J_PASSWORD="…" \
pnpm -r test

주의 사항: Redis / Qdrant / MySQL / SQLite 스위트는 자체 픽스처를 생성하고 정리합니다. PostgreSQL 스위트는 현재 특정 개발 데이터베이스를 대상으로 검증합니다 (자체 프로비저닝은 TODO). Neo4j는 항상 명시적인 비밀번호가 필요합니다. 또한 빌드된 앱의 엔드투엔드 스모크 테스트 (smoke-drivers.mjs)가 있으며, 구성된 모든 드라이버를 MCP를 통해 구동합니다.

Claude Code에서 사용하기

peek은 시작 시 MCP 서버를 실행하고 (루프백 전용, bearer 토큰 인증), 엔드포인트를 ~/.peek/mcp.json에 기록합니다 (모드 0600). 한 번 등록하세요:

claude mcp add peek --transport http http://127.0.0.1:7332/mcp \
  --header "Authorization: Bearer <token from ~/.peek/mcp.json>"

정확한 명령과 토큰이 채워진 상태로 설정 → MCP 엔드포인트에서 한 번의 클릭으로 확인할 수 있습니다. 포트를 변경하거나 토큰을 교체하는 것도 같은 곳에서 가능합니다.

도구

의도적으로 전체 결과 집합을 모델에 전달하는 도구는 없습니다.

채팅 패널

사용자가 답할 때까지 일시 중지된 ask 호출 — 에이전트는 자신의 질문에 답할 수 없습니다.

자체 클라이언트를 가져올 필요가 없습니다: peek은 Claude Code 자체를 탭으로 호스팅합니다. 내장 에이전트는 파일 도구, 셸, 그리고 peek 자체의 MCP 서버 외의 다른 MCP 서버 없이 시작됩니다 — 사용자의 settings.json, CLAUDE.md, 또는 구성된 MCP 서버를 상속하지 않으며, verify-chat-security.mjs가 실제 에이전트를 대상으로 이를 검증합니다. 두 가지 설정(기본적으로 모두 꺼짐)으로 다시 선택할 수 있습니다: 파일/명령 도구, 그리고 사용자 자체의 MCP 서버. 각 설정은 스위치 옆에 그 비용을 설명합니다 — 보안 모델 참조.

보안 모델

• MCP 서버: 루프백 전용, Authorization: Bearer 필수, Host/Origin을 DNS 리바인딩에 대해 검사, 토큰은 상수 시간으로 비교하며 로그에 기록되지 않습니다.

• 읽기 전용: 가능한 곳에서는 데이터베이스 서버가 강제합니다 (트랜잭션, 플래그). Redis와 Qdrant 드라이버는 쓰기 명령을 아예 발행하지 않습니다. 한 가지 허점: 자체 읽기-쓰기 트랜잭션을 여는 기존 저장 프로시저 — 중요한 데이터에는 읽기 전용 데이터베이스 계정을 사용하세요.

• 프로세스 격리: 드라이버는 연결당 하나의 자식 프로세스에서 실행됩니다. 멈춘 쿼리나 충돌이 창을 죽일 수 없으며, 프로세스를 종료하는 것은 무조건적인 취소입니다. 패키지 코드는 메인 프로세스에서 실행되지 않습니다.

• 패키지는 신뢰 기반이며 샌드박스가 아닙니다. 설치하는 것이 곧 신뢰하는 것입니다 — VS Code 확장이나 MCP 서버와 같은 방식입니다. peek은 패키지의 매니페스트 형태를 검증하고, 프로세스를 격리하며, 환경에서 자격 증명을 제거하지만, 서명 검사나 샌드박스는 없습니다. 자세한 내용은 설계 문서에 있습니다.

• 에이전트의 파일 도구를 활성화하면 실제 비용이 발생합니다: ~/.peek/mcp.json을 읽을 수 있는 에이전트는 bearer 토큰을 보유하게 되며, 권한 프롬프트는 더 이상 장벽이 되지 않습니다. 설정 패널은 스위치가 켜져 있을 때 정확히 이 점을 알려줍니다.

성능

Apple M2 Max (macOS, 120Hz Retina)에서 생성된 1,000,000행 SQLite 픽스처를 대상으로, 두 개의 재현 가능한 벤치마크 스크립트 (bench-startup.mjs, bench-scroll.mjs)로 측정했습니다:

결과는 역압력과 LRU 캐시가 있는 컬럼형 청크로 스트리밍되며, 가상 스크롤은 Chromium이 Retina 해상도에서 약 699,000행에서 요소 높이를 조용히 제한하기 때문에 직접 작성되었습니다 — peek의 어떤 DOM 치수도 행 수에서 파생되지 않습니다.

상태 및 제한 사항

초기 단계이지만 실제로 작동합니다: 6개 데이터베이스 모두 연결, 탐색, 행 스트리밍이 가능합니다. 위에서 설명한 레이아웃, 채팅, MCP 표면, 패키지 시스템은 구현되어 테스트되었습니다. pnpm build는 번들을 생성하고, package-mac.mjs는 macOS .app을 생성합니다. 서명된 설치 프로그램은 아직 없습니다. 쓰기는 읽기 전용 경로가 완전히 안정화될 때까지 의도적으로 범위 밖입니다.

알려진 제한 사항 (자세한 내용은 docs/PLAN.md 및 docs/design/ 참조):

• 대규모 쿼리는 (설계상) 약 20만 행에서 일시 중지되며, 더 스크롤하면 계속됩니다. 약 200MB 캐시에서 축출된 행은 제자리에서 다시 가져올 수 없습니다 — 쿼리를 다시 실행하세요.

• 고정 24px 행 높이; 큰 값은 모달로 열립니다.

• 접근성은 레이아웃 수준에서 견고하지만 (ARIA tablist, 로빙 tabindex, 포커스 관리) 패널 본문 내부에서는 최소한이며, 실제 화면 판독기로 검증되지 않았습니다.

• 복원된 작업 공간은 레이아웃, 탭, 편집기 텍스트를 다시 열지만 쿼리는 다시 실행하지 않습니다.

• Qdrant: 쿼리 취소 없음 (API에 취소 기능이 없음 — 버튼에 그렇게 표시됨), 테이블 헤더 정렬은 아직 불가능.

• 저장된 자격 증명은 OS 사용자 계정만큼만 비공개입니다. 바이너리 서명은 첫 번째 공개 빌드와 함께 제공됩니다.

저장소 구조

peek/
├─ packages/
│  ├─ core/           # command schemas, workspace types, capability + chunk protocol, driver-host runtime
│  ├─ db-postgres/    # PostgreSQL driver
│  ├─ db-sql/         # MySQL + SQLite behind one dialect layer
│  ├─ db-redis/       # Redis driver
│  ├─ db-qdrant/      # Qdrant driver
│  └─ db-neo4j/       # Neo4j driver, plus the `graph` view kind
├─ apps/desktop/      # Electron app: main / preload / renderer, plus scripts/ (benchmarks, smoke tests)
└─ docs/              # PLAN.md (design record) and docs/design/ (per-change design docs)

docs/PLAN.md는 권위 있는 설계 기록입니다 — 아키텍처 결정, 성능 예산, 마일스톤 정의를 포함합니다 (PLAN.zh-CN.md는 중국어 원본입니다). 변경별 설계 문서는 docs/design/에 있습니다.

라이선스

MIT. LICENSE를 참조하세요.