democut 0.2.0 → 0.4.0

package/README.md

@@ -80,7 +80,7 @@ democut video status <job_id> [--wait] [--output <경로>]
 - **생성이 성공하면 과금된다** — 서버는 성공을 처음 관측한 시점에 원장에 기록한다(폴링을 반복해도 한 번).
   실패한 생성은 원장에 남지 않지만, 제출이 업스트림에 접수된 뒤의 재시도는 별개 생성이라 다시 과금된다.
 - **산출물 URL 은 24시간 후 만료된다** — `--output` 으로 즉시 받아두지 않으면 재생성해야 한다(재과금).
-- **CLI 는 제출을 자동 재시도하지 않는다** — BytePlus 가 멱등키(Idempotency-Key)를 지원하지 않아 재시도가 곧 재과금이다.
+- **CLI 는 제출을 자동 재시도하지 않는다** — 공급자가 멱등키(Idempotency-Key)를 지원하지 않아 재시도가 곧 재과금이다.
   실패해 보여도 먼저 `democut video status <job_id>` 로 확인할 것.
 - **`--wait` 시한 초과는 실패가 아니다** — 작업은 서버에서 계속 진행된다(종료 코드 5). 새로 제출하지 말고 `status` 로 확인한다.
 
@@ -117,53 +117,99 @@ npm test
 npm run build      # dist/cli.js (bin: democut) 번들
 ```
 
+## MCP 서버 (에이전트에 도구로 붙이기)
+
+`democut mcp` 는 **stdio MCP 서버**다. Claude Code·Cursor 등 MCP 클라이언트에 붙이면
+에이전트가 도구로 직접 영상을 만든다.
+
+```bash
+claude mcp add democut -- npx -y democut mcp
+```
+
+`npx -y` 를 붙이는 이유는 전역 설치가 **연결의 선행 조건이 되지 않게** 하기 위해서다.
+설치가 빠지면 등록은 성립하는데(등록은 바이너리 존재를 검사하지 않는다) 연결만 실패하고,
+그 실패는 클라이언트의 `Failed to reconnect …` 한 줄로만 드러난다 — 서버가 뜨지 못하므로
+진단을 낼 주체가 없다. 자격증명은 패키지가 아니라 `~/.democut/credentials.json` 에 있어
+실행 방식을 바꿔도 로그인 상태는 그대로다. 전역 설치는 선택이다.
+
+노출 도구 4개:
+
+| 도구 | 부작용 |
+|---|---|
+| `democut_auth_status` | 없음 — 로그인·워크스페이스·티어 확인 |
+| `democut_estimate_video_cost` | **없음** — 비용만 계산 |
+| `democut_generate_video` | **과금** — `confirmed_cost_usd` 필수 |
+| `democut_get_video_status` | 없음 — 상태 조회 + 선택적 저장 |
+
+### 비용 승인이 프로토콜에 맞게 바뀐다
+
+CLI 는 TTY 에 `y/N` 을 물어 사람을 막지만 MCP 에는 물어볼 화면이 없다. 대신 두 겹이다:
+
+1. **호스트의 도구 승인** — Claude Code 등이 도구 호출 전에 사용자에게 확인을 받는다.
+   우리가 제어할 수 없으므로 이것만 믿지 않는다.
+2. **`confirmed_cost_usd` 재확인** — 생성 도구는 호출자가 *직접 본* 추정 금액을 다시 실어
+   보내야 하고, 서버가 방금 계산한 값과 대조해 어긋나면 거부한다. 모델이 추정을 건너뛰고
+   바로 생성하는 것을 막고, 사람에게 보여준 금액과 실제 청구액이 갈라지지 않게 한다.
+
+### stdio 와 원격 HTTP — 대체가 아니라 병존
+
+**stdio(이 CLI)가 기본이다.** 이 프로세스가 `~/.democut/credentials.json` 을 읽고 만료 시
+refresh 로 회전하므로 **클라이언트 설정 파일에 토큰이 남지 않는다.** 그 장점은 원격이
+생겨도 사라지지 않는다.
+
+**원격 HTTP 도 이미 있다** — `https://democut.ai/mcp` (2026-08-25 배포). 로컬 바이너리를 못
+띄우는 클라이언트용이다:
+
+```bash
+claude mcp add --transport http --client-id <client_id> --callback-port <포트> \
+    democut https://democut.ai/mcp
+```
+
+`--client-id` 와 `--callback-port` 가 필요한 이유는 서버 쪽 설계에서 온다 — 동적 클라이언트
+등록(DCR)을 **일부러 꺼 두고**, Clerk 이 loopback redirect 의 포트를 정확 일치로 요구하기
+때문이다. 근거는 `apps/api/app/mcp/auth.py` docstring 이 SSOT.
+
+> ⚠️ 이 문단은 원래 "원격은 동적 클라이언트 등록을 요구해서 체인을 새로 쌓아야 한다" 고
+> 적혀 있었는데 **틀렸다.** DCR 은 MCP 명세에서 MUST 가 아니라 SHOULD 이고, 무엇보다 우리
+> 인증 공급자(Clerk)가 이미 완전한 OAuth 2.1 인가서버라 **우리가 만든 AS 는 0줄**이다.
+> 오류의 모양이 재발 포인트라 남긴다 — *우리 코드*만 재고 조사하고 **이미 구입한 SaaS
+> 기능은 세지 않았다.**
+
 ## 게시 (npm publish)
 
-**아직 게시되지 않았다** — `npm install -g democut` 은 현재 404 다.
-게시는 사람이 한다(에이전트 범위 밖).
-
-> ⚠️ **게시가 문서 승격보다 먼저다.** `democut` 은 **무스코프**라 우리가 게시하기 전까지
-> **누구나 그 이름으로 올릴 수 있다**(스코프 패키지와 달리 네임스페이스 보호가 없다).
-> `/docs/agents` 의 복사 버튼과 `/updates` 공지가 먼저 나가면, 그 사이 제3자가 악성
-> `democut` 을 선점해 사용자가 그것을 설치하는 창이 열린다 —
-> `democut auth login` 이 워크스페이스 토큰을 다루므로 토큰 탈취로 이어질 수 있다
-> (CWE-829, faceta 리뷰 2026-08-21).
->
-> 따라서 **머지 → npm publish → 승격(promote)** 순서를 지킨다. 승격 전에 확인:
-> ```bash
-> curl -s -o /dev/null -w '%{http_code}\n' https://registry.npmjs.org/democut   # 200 이어야 한다
-> ```
-
-순서:
-
-1. **서버 라우터가 프로덕션에 있어야 한다.** `democut video` 는 `/api/videogen` 을 호출하고
-   기본 base URL 이 프로덕션(`https://democut.ai`)이다. 그 라우터가 없으면 게시해도 모든
-   video 커맨드가 404 다. 확인:
-   ```bash
-   curl -s -o /dev/null -w '%{http_code}\n' -X POST https://democut.ai/api/videogen/estimate
-   # 401 이면 배포됨(인증 필요) · 404 면 미승격
-   ```
-2. **org 는 필요 없다.** 이 패키지는 **무스코프**(`democut`)라 개인 계정으로 바로 게시되고,
-   무스코프는 기본이 public 이라 `--access public` 도 필요 없다.
+**CI 가 자동으로 한다.** 사람이 순서를 기억할 필요가 없다.
 
-   > `@democut` **스코프**는 쓸 수 없다 — 그 이름은 이미 npm 계정 하나가 점유하고 있고
-   > (username 과 org 는 같은 네임스페이스다) 그래서 `democut` org 를 만들 수 없다.
-   > **패키지 이름은 그와 별개 네임스페이스**라 무스코프 `democut` 은 그대로 쓸 수 있다.
-   > 향후 `@democut/mcp` 같은 스코프 패키지가 필요해지면 그 계정을 되찾아야 한다
-   > (이메일을 못 받는 미인증 계정이면 로그인 후 계정 설정에서 이메일을 교체하거나,
-   > 비밀번호를 모르면 npm Support 로 문의).
+```
+promote(사람이 누르는 버튼)  →  npm-publish-cli  →  deploy-dgx
+```
 
-3. `npm login` 후:
-   ```bash
-   cd cli
-   npm run build          # prepublishOnly 가 자동으로도 돌지만 먼저 확인
-   npm publish            # 무스코프는 기본 public — --access 불필요
-   ```
+`deploy-dgx` 가 게시 성공을 `needs` 로 요구하므로, **게시가 실패하면 문서가 프로덕션에
+나가지 않는다.** `/docs/agents` 가 아직 없는 패키지를 안내하는 창이 구조적으로 열리지 않는다
+(무스코프 이름이라 그 창에서 제3자가 선점하면 토큰 탈취로 이어질 수 있다 — CWE-829).
 
-> **토큰을 코드나 대화에 넣지 않는다.** `npm login` 은 브라우저 인증이고 토큰은 `~/.npmrc`
-> 에만 남는다. CI 에서 자동 게시가 필요해지면 npm **Automation token**(publish 전용,
-> 이 패키지로 스코프 제한)을 발급해 **GitLab CI/CD 변수**(masked + protected)에 두고
-> `NODE_AUTH_TOKEN` 으로 주입한다 — 이 레포가 배포 시크릿에 쓰는 방식과 같다.
+버전이 그대로면 잡은 "이미 게시됨" 으로 즉시 통과한다. 그러니 **게시하려면 `cli/package.json`
+의 version 을 올리기만 하면 된다** — `VERSION` ↔ `package.json` 정합은 테스트가 강제하므로
+`src/version.ts` 도 같이 올린다.
+
+순서를 강제하는 것은 `.gitlab-ci.yml` 의 `deploy-dgx.needs` 하나뿐이고, 그것이 지워지면
+아무 신호 없이 보장이 사라진다 — `scripts/tests/promote.sh` 가 지킨다(`make test-scripts`).
+
+### 선행 설정 (1회)
+
+npm **Automation token** 을 발급해(2FA 를 우회하도록 설계된 종류다) GitLab CI/CD 변수
+`NPM_TOKEN` 에 **masked + protected** 로 넣는다. 토큰이 없으면 잡이 명확한 메시지로 실패한다.
+
+> **토큰을 코드나 대화에 넣지 않는다.** 값은 GitLab 변수에만 두고, 레포에도 로컬 파일에도
+> 남기지 않는다.
+
+### 수동 게시 (긴급시)
+
+```bash
+cd cli
+npm run build
+npm publish        # 무스코프는 기본 public — --access 불필요
+```
 
-게시되는 것은 `files` 에 적힌 **`dist/` 뿐**이다(소스·테스트는 포함되지 않는다).
+2FA 가 보안 키(WebAuthn)면 `npm publish` 가 브라우저 승인 URL 을 띄운다.
+게시되는 것은 `files` 에 적힌 **`dist/` 뿐**이다(소스·테스트 미포함).
 `npm pack --dry-run` 으로 목록을 먼저 확인할 수 있다.