도구와 리소스

푸시 제목에는 프로젝트 디렉터리 이름이 자동으로 붙는다 — myapp · Build complete — 그래서 여러 세션이 동시에 푸시해도 폰 피드를 훑어보기 좋다.

단방향 도구

zeph_notify

단방향 푸시 알림을 보낸다. URL을 넣으면 푸시 유형이 link로 자동 전환된다.

title:          "Build complete"
body:           "All 42 tests passed"
url:            "https://github.com/org/repo/actions/runs/123"  (선택)
priority:       "low" | "normal" | "high" | "urgent"
targetDeviceId: "dev_..."  (선택, ZEPH_DEVICE_ID를 덮는다)

zeph_clipboard

사용자 디바이스의 클립보드로 텍스트를 복사한다.

text:           "npm install @zeph-to/mcp-server"
targetDeviceId: "dev_..."  (선택)

zeph_file

사용자 디바이스로 파일을 보낸다. 디스크에 이미 있는 파일이면 filePath, 생성한 텍스트면 content 중 하나가 필요하다.

filePath:       "/abs/path/screenshot.png"  (이미지·PDF·로그 등 디스크의 모든 것)
content:        "{\"status\": \"ok\"}"       (텍스트 전용; fileName 필요)
fileName:       "report.json"               (content와 함께 필수; 없으면 filePath의 basename)
title:          "Build Report"              (선택, 없으면 fileName)
targetDeviceId: "dev_..."                   (선택)

이미지는 실제 mime 타입으로 전달돼 디바이스에서 인라인으로 렌더된다. 바이너리 파일을 base64로 만들어 content에 넣지 말 것 — filePath를 넘기면 서버가 디스크에서 바이트를 읽는다.

{ pushId: "...", fileKey: "...", fileSize: 42 }를 반환한다.

zeph_broadcast

채널 구독자 전원에게 알림을 보낸다.

channelId: "ch_..."
title:     "Deploy complete"
body:      "v2.1.0 is live"
url:       "https://..."  (선택)
priority:  "normal"

대화형 도구

아래 셋은 사용자가 응답하거나 타임아웃이 될 때까지 블로킹하며, 전부 ZEPH_HOOK_ID가 필요하다.

zeph_ask

빠른 응답 버튼과 텍스트 입력창을 한 알림에 함께 담아 질문한다.

title:       "What should we do?"
body:        "3 tests failed in auth module"  (선택)
actions:     [{ id: "fix", label: "Fix now", style: "primary" },
              { id: "skip", label: "Skip", style: "secondary" }]  (선택, 1-4개)
placeholder: "Or type a custom response..."  (선택)
inputType:   "text" | "multiline"  (기본값: text)
timeout:     120    (초, 기본값 120, 최대 600)
fallback:    "skip" (타임아웃 시 자동 선택, 선택)

{ actionId: "fix", timedOut: false } 또는 { value: "custom text", timedOut: false }를 반환한다.

사용자는 답에 스크린샷이나 파일을 첨부할 수도 있다. 첨부는 ~/.zeph/attachments/hook-<eventId>/로 내려받아지고, 결과에 로컬 절대 경로 배열 attachments가 버튼이나 텍스트와 함께 실린다:

{ value: "look at this", attachments: ["/Users/you/.zeph/attachments/hook-hevt_1/screen.png"],
  attachmentsNote: "The user attached 1 file(s) to this answer. Read each path above to see them.",
  timedOut: false }

그 경로들을 읽는 것까지가 답을 읽는 것이다. hook 첨부는 종단간 암호화되지 않는다 — hook 경로가 발신자 키를 실어 나르지 않으므로, 질문 자체와 같은 한계다.

zeph_prompt

2~4개 선택지 중에서 고르게 한다.

title:    "Deploy to production?"
body:     "3 migrations pending"
actions:  [{ id: "yes", label: "Deploy", style: "primary" },
           { id: "no",  label: "Cancel", style: "danger" }]
timeout:  120        (초, 기본값 120, 최대 300)
fallback: "no"       (타임아웃 시 자동 선택, 선택)

{ actionId: "yes", timedOut: false }를 반환한다.

zeph_input

자유 형식 텍스트 입력을 요청한다.

title:       "Commit message"
body:        "Summarize the changes"
placeholder: "feat: ..."
inputType:   "text" | "password" | "multiline"
timeout:     120    (초, 기본값 120, 최대 600)

{ value: "feat: add clipboard sync", timedOut: false }를 반환하며, 사용자가 파일을 첨부하면 zeph_ask와 똑같이 attachments가 함께 온다.

클라이언트 타임아웃

zeph_ask·zeph_prompt·zeph_input은 사용자가 응답할 때까지, 최대 600초의 timeout까지 블로킹한다. ZEPH_WS_URL이 설정돼 있으면 제출 즉시 WebSocket으로 응답이 오고, 아니면 서버가 폴링한다. 어느 쪽이든 MCP 요청은 그동안 계속 열려 있다.

클라이언트가 먼저 포기하지 않도록 서버는 대기 중 5초마다 notifications/progress를 보낸다. 클라이언트는 요청별 타임아웃을 도구의 timeout보다 크게 잡거나, progress 알림마다 타임아웃을 재설정해야 한다. Claude Code는 기본적으로 후자를 한다.

관리용 도구

zeph_list

최근 푸시 알림을 나열한다.

limit: 5         (1-20, 기본값 5)
type:  "note"    (선택 필터: note, link, file, clipboard, hook)

{ pushes: [...], total: 5, hasMore: true }를 반환한다.

zeph_dismiss

특정 푸시를 읽음으로 표시한다.

pushId: "push_01HX..."

zeph_dismiss_all

모든 알림을 한 번에 지운다. 파라미터 없음. { dismissed: 12, badge: 0 }을 반환한다.

zeph_session_rename

Zeph 앱의 Streams → Agents에 표시될 현재 에이전트 세션의 이름을 설정한다. 에이전트가 지금 무슨 일을 하는지 스스로 이름 붙일 수 있게 해준다 — "Prod deploy", "Auth refactor" — 그래서 병렬 세션을 폰에서 구별하기 쉬워진다.

이 서버가 도는 세션의 이름을 바꾸며, listener 디바이스 id와 tmux 세션 이름으로 대상을 정한다. 이름은 바꿀 때까지 유지된다.

alias: "Prod deploy watcher"   (1-60자)

{ renamed: true, session: "zeph-myapp", alias: "Prod deploy watcher" }를 반환하거나, 이름을 바꿀 활성 세션이 없을 때 — 즉 zeph listener tmux 세션 안에서 돌고 있지 않을 때 — { renamed: false, reason: "..." }를 반환한다.