@backendx/mcp 1.0.0 → 1.0.1

package/README.md

@@ -1,550 +1,360 @@
-# backendx-mcp
-
-BackendX API를 AI 에이전트가 사용할 수 있도록 MCP(Model Context Protocol) 서버로 래핑한 프로젝트입니다.
-프로젝트 인터뷰 → 코드 생성 → 로컬 실행 → 배포 → 운영 → 구독 관리까지, backendx-frontend가 제공하는
-워크플로우를 터미널 에이전트가 수행할 수 있도록 하는 도구들을 제공합니다.
-도구 수와 전체 목록은 아래 "등록된 MCP 도구" 절이 정본입니다.
-
-## 기술 스택
-
-- **MCP SDK**: `@modelcontextprotocol/sdk` v1.29.0
-- **입력 검증**: `zod` v4
-- **빌드**: `tsup` (ESM, ES2022)
-- **런타임**: Node.js >= 18
-- **언어**: TypeScript
-
-## 등록된 MCP 도구 (76종)
-
-### 인증 · 계정
-
-| 도구                 | 설명                                                      |
-| -------------------- | --------------------------------------------------------- |
-| `authenticate`       | Google 토큰으로 BackendX 인증                             |
-| `get_account`        | 계정 정보 조회 — 연결된 로그인 제공자, legacy 크레딧, 인트로·쿠폰 플래그(`held_coupons` 파생) |
-| `get_github_account` | 연결된 GitHub 계정 조회 (소스 레포 collaborator 등록용)   |
-| `link_github`        | GitHub PAT로 계정 연결 (OAuth 대안, 소스코드 접근에 필요) |
-| `unlink_github`      | GitHub 연결 해제 (`confirm=true` 필요 — 모든 미러 레포의 collaborator 권한 즉시 회수) |
-
-### 프로젝트 생명주기 (인터뷰 → 생성)
-
-| 도구                    | 설명                                                                 |
-| ----------------------- | -------------------------------------------------------------------- |
-| `get_consent_questions` | 생성 전 동의 질문지 정의 조회 (프로젝트·인증 불요, `stage` 필터)     |
-| `create_project`        | 새 프로젝트 생성 (직후 project_start 5종 답변 적재가 정본 순서)      |
-| `list_projects`         | 프로젝트 목록 조회                                                   |
-| `get_project_status`    | 프로젝트 상태 조회 (+ 구독 요약·첨부 허용량·내 역할, `has_failed_stage` 로 요구사항 단계의 **입력 대기 vs 멈춤** 판정) |
-| `rename_project`        | 프로젝트 이름(label) 변경                                            |
-| `get_deletion_preview`  | 프로젝트 삭제 가능 여부·차단 사유·**즉시 정산될 금액** 미리보기 (revision 발급, TTL 15분) |
-| `delete_project`        | 프로젝트 영구 삭제 (`confirm=true` + `preview_revision` 필요, 구독 즉시 해지·미청구분 즉시 결제) |
-| `send_message`          | 메시지 전송 및 AI 응답 수신 (변경 한도 402 는 사유별 분기)           |
-| `get_messages`          | 대화 이력(인터뷰 문답 + progress) 조회, 최신 우선 (부모 리비전 포함) |
-| `upload_attachment`     | 로컬 파일을 요구사항 첨부로 업로드 (비동기 SRS 반영, 플랜별 한도)    |
-| `download_attachment`   | 첨부 파일 다운로드 (id 는 `get_messages` 의 attachment 메시지에서, 410 = 보존기간 만료) |
-| `list_revisions`        | SRS 리비전 이력(변경 요약) 조회                                      |
-| `wait_for_pipeline`     | 코드 생성 파이프라인 완료 대기 (현재 단계 실측 평균 소요 동반)       |
-| `retry_pipeline`        | 멈추거나 실패한 파이프라인 재시도 (`restart_point` 로 재시작 지점 구분 — `interview` 는 SRS 를 비우고 인터뷰 재개, 점검 대기 중엔 `MAINTENANCE_PENDING`) |
-| `get_system_status`     | 플랫폼 health + 점검 대기 여부 (파라미터·인증 불요 — 새 실행이 보류되는 이유를 가르는 유일한 조회) |
-| `get_progress`          | 단계별 파이프라인 진행 메시지 조회 (페이지네이션)                    |
-
-### 문서 · 산출물
-
-| 도구                | 설명                                                                                                         |
-| ------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `get_docs`          | 프로젝트 문서 조회 — SRS, 아키텍처, DB 스키마, Dockerfile, API 문서, 스케줄 작업(`tasks`), 도커 이미지, 소스 저장소 URL |
-| `purchase_docs`     | 문서 접근 가능 여부 판정 + GitHub 소스 미러 개설(`repo`) — 문서 접근은 플랜이 결정하며 개별 구매는 없다      |
-| `get_api_clipboard` | 프론트·클라이언트 앱 구현용 완성형 프롬프트 조회 — API 문서를 연동 지시문에 얹어 그대로 붙여넣을 수 있게 준다 (웹 콘솔 "AI 프롬프트 복사"와 동일 경로). 배포된 프로젝트의 실 base URL 을 기본으로 싣는다(`include_deployed_base_url` 기본 true — 원 API 기본값을 뒤집음). `link=true`는 문서를 미인증 공개 URL 로 대체해 응답을 수 KB 로 줄이지만, **사용자 확인 후에만** 켠다 |
-| `download_source`   | 생성된 소스코드 ZIP 다운로드 및 추출 (Builder 플랜 이상, 받는 시점의 스냅샷 — `type` 으로 env 버킷 선택, **아카이브에 실제 시크릿 동봉**) |
-| `get_er_diagram`    | ER 다이어그램 조회 — `format="mermaid"` 는 **텍스트를 응답으로** 돌려주므로 에이전트가 스키마를 읽는 경로다. 이미지(svg/png/pdf/zip)는 `output_directory` 지정 시 파일 저장, 생략 시 presigned URL 메타데이터. DB 스키마와 같은 플랜 게이트 |
-
-### 로컬 실행
-
-| 도구                    | 설명                                                                          |
-| ----------------------- | ----------------------------------------------------------------------------- |
-| `configure_environment` | 환경변수 조회·저장·초기화 (`local`/`deployment` 버킷 분리, `reset_keys` 지원) |
-| `download_project`      | 로컬 실행 설정 ZIP 다운로드 및 추출                                           |
-| `get_project_file`      | 단일 파일을 텍스트로 조회 (파일명은 `get_project_status` 의 `files_available`). `env.txt` 는 `env_type=deployment` 로 배포 버킷까지 — 웹 콘솔에는 없는 경로. credential 파일은 플레이스홀더 |
-| `verify_local_run`      | 로컬 컨테이너 기동 확인용 health check URL 조회                               |
-
-### 배포 (게이트 → 실행 → 수명주기)
-
-| 도구                             | 설명                                                                                      |
-| -------------------------------- | ----------------------------------------------------------------------------------------- |
-| `get_deploy_readiness`           | 배포 가능 여부 진단 — 요금 동의 + 배포 설문 게이트를 한 번에 조회                         |
-| `accept_pricing_consent`         | managed-hosting 요금 정책 동의 기록 (`confirm=true` 필요, 정책 5개 조항 제시 후 매 배포마다) |
-| `submit_deploy_questionnaire`    | 배포 설문 답변 저장 (법적 고지 기록, blocking 선택지는 `confirm_blocking=true` 필요)       |
-| `get_deployment_data_categories` | 파이프라인이 도출한 개인정보 카테고리 정본 조회 (`data_categories_confirmed` 답변의 근거) |
-| `get_privacy_block`              | 처리방침 게시 본문 생성·조회 (첫 호출이 본문과 `block_hash` 를 고정)                      |
-| `deploy_project`                 | 완성된 프로젝트(ReadyToRun)를 managed-shared 풀에 배포 (리비전 지정 가능)                 |
-| `get_deployment_status`          | 배포 상태·엔드포인트(URL)·배포 가능 리비전 조회                                           |
-| `pause_deployment`               | 배포 일시정지 — 스택만 내리고 도메인·데이터·secrets 유지 (`resume_deployment` 로 복구)    |
-| `resume_deployment`              | 일시정지한 배포 재기동 (추가 과금 없음)                                                   |
-| `stop_deployment`                | managed-shared 배포 삭제 (`confirm=true` 필요, 배포 DB 영구 삭제)                         |
-
-### 운영 대시보드
-
-| 도구                          | 설명                                                                  |
-| ----------------------------- | --------------------------------------------------------------------- |
-| `get_ops_summary`             | 배포 운영 요약(KPI) 조회 — `server_status` 는 실측이 아닌 고정값      |
-| `list_incidents`              | 운영 인시던트 목록 조회 (`category` **필수**, range 는 1h~72h)        |
-| `get_incident`                | 단일 인시던트 상세(타임라인·triage 판정·autofix 진행·뮤트 상태) 조회  |
-| `get_incident_ai_prompt`      | 4xx 인시던트의 클라이언트 수리 프롬프트 조회 (409 = 대기·플랫폼 수리·비대상 분기) |
-| `update_incident_status`      | 인시던트 상태 전이 (전진 3종만, `resolved` 는 되돌릴 수 없음)         |
-| `mute_incident_notifications` | 인시던트 단위 알림 뮤트·해제 (프로젝트 전체 설정과 별개)              |
-| `get_ops_usage`               | 사용량(트래픽 게이지·일별 막대) 조회 — 한도 초과는 차단이 아니라 과금 |
-| `get_usage_by_date`           | 특정일(YYYY-MM-DD) API 호출 분석 조회 (당일 수치는 집계 중)           |
-| `get_ops_resources`           | 컨테이너 자원(CPU/메모리/네트워크) 조회 — 절댓값 합산, 디스크는 없음  |
-| `configure_hard_stop`         | API 호출 하드 스톱 조회·변경 (API 호출 한정 — DB 초과는 막을 수 없다) |
-| `configure_ops_notifications` | 운영 알림 preference 조회·변경 (부분 머지)                            |
-
-### 결제 · 구독 · 좌석
-
-| 도구                        | 설명                                                                                |
-| --------------------------- | ----------------------------------------------------------------------------------- |
-| `get_plan`                  | 프로젝트 구독·엔타이틀먼트·좌석/변경횟수/업로드 허용량 조회 — **체험 판정(`is_trialing`)의 단일 출처**, 다음 청구서는 플랜(`next_invoice`)·좌석(`seat_invoice`) 둘로 나뉜다 |
-| `list_invoices`             | 청구 내역 조회 (최신순, owner 전용 — overage 실청구 확인 경로)                      |
-| `list_members`              | 멤버·대기 초대·좌석 요청 현황 조회 (좌석 회계 상세)                                 |
-| `preview_seats`             | 좌석 추가(delta) 금액 미리보기 — 부작용·과금 없음 (`prorated_now` 는 **오늘 결제될 금액**) |
-| `set_seats`                 | 총 좌석 수 설정 (`confirm=true` 필요, **절대값** — 증가는 **오늘 즉시 청구**, 감소는 다음 좌석 주기 예약) |
-| `purchase_seats_and_invite` | 좌석 추가 + 초대 (`confirm=true` 필요, 좌석은 **즉시 청구**, 부분 롤백 없음)        |
-| `create_seat_request`       | admin 의 좌석 부족 초대 — 여유분 즉시 초대 + 초과분을 owner 승인 대기로 큐잉 (과금 없음) |
-| `resolve_seat_request`      | 좌석 요청 승인·반려 (owner 전용, `approve` 는 좌석 구매라 `confirm=true` 필요)      |
-| `purchase_change_runs`      | 요구사항 변경 횟수 추가 구매 (`confirm=true` 필요, **구매 시점 즉시 결제** — 402 는 아무것도 적립 안 됨) |
-| `cancel_subscription`       | 구독 취소 (`confirm=true` 필요, 사유 선택 — 평시엔 기간말 예약·철회 가능, **체험 중이면 즉시·철회 불가**) |
-| `preview_plan_change`       | 플랜·주기 변경 시 **오늘** 청구액 미리보기 — 부작용 없음 (`mode=immediate` 일 때만 금액, `proration_date` 를 `change_plan` 에 되돌려야 표시가=청구가) |
-| `change_plan`               | 플랜·주기 변경 (`confirm=true` 필요, 업그레이드는 **즉시 청구**, 다운그레이드는 기간말 예약 — **기능 호환이 가격에 우선**해 Pro→Builder 는 예약·배포 회수, 체험 중 변경은 체험 소멸) |
-| `withdraw_scheduled_plan_change` | 예약된 플랜 변경·기간말 취소 철회 (`confirm=true` 필요, 주기를 건드리지 않음)     |
-| `get_billing_portal_url`    | Stripe 고객 포털 링크 발급 (결제수단 변경·구독 재개 경로, 링크만 반환)              |
-| `get_upgrade_url`           | 플랜 업그레이드 화면 딥링크 조립 (백엔드 호출 없음)                                 |
-| `get_pricing`               | legacy 크레딧 단가 조회 (현행 가격 모델 아님 — `get_plan` 참조)                     |
-| `get_credits`               | 잔여 크레딧 조회 (legacy 계정 잔액 — 산출물 접근을 결정하지 않는다)                 |
-| `redeem_coupon`             | 사전신청 프로모 코드 등록 (계정당 1개 — 혜택은 다음 Pro 월간 결제에 자동 부착)      |
-
-### 멤버 · 권한 · 공유
-
-| 도구                  | 설명                                                                                     |
-| --------------------- | ---------------------------------------------------------------------------------------- |
-| `get_role_matrix`     | 역할↔capability 매트릭스 조회 (본문 없는 403 의 사유를 역산하는 기준점, custom 역할 포함) |
-| `manage_invite`       | 초대 발송·취소·재발송 (과금 없음 — 발송 시 좌석 **선점**, 좌석 부족은 배치 전체 거부)      |
-| `manage_member`       | 멤버 역할 변경·좌석 변경·제거 (`remove` 와 접근 차단 좌석 변경에 `confirm=true` 필요)      |
-| `transfer_ownership`  | 소유권 이전 (`confirm=true` 필요, **되돌리려면 새 owner 가 호출해야 함** — 기존 owner 는 admin 강등) |
-| `leave_project`       | 스스로 프로젝트 나가기 (`confirm=true` 필요 — owner·admin 은 불가, 좌석 없어도 호출 가능)  |
-| `claim_invite`        | 초대 토큰·링크로 멤버십 수락 (`project_uuid` 를 받지 않는 유일한 도구, 이미 멤버면 성공)   |
-| `manage_share_link`   | 공유 링크 목록·발행·회수 (`get_api_clipboard(link=true)` 공개 URL 의 **유일한 회수 경로**, public 발행에 `confirm=true`) |
-
-## 대표 워크플로우
-
-### 인터뷰 → 생성 → 배포
+# @backendx/mcp
 
-```
-authenticate
-  → get_consent_questions                (stage="project_start" 5종 질문지 — 생성 전에 사용자에게 제시)
-  → create_project
-  → submit_deploy_questionnaire          (5종 답변 적재 — 반드시 첫 send_message 이전)
-  → send_message ⇄ get_messages          (요구사항 인터뷰)
-  → wait_for_pipeline                    (SRS → 아키텍처 → 코드 → 도커 이미지)
-  → get_docs / download_source …         (산출물 확인)
-  → 배포 게이트 통과 (아래 "배포 전제조건 체인")
-  → deploy_project → get_deployment_status
-```
+MCP (Model Context Protocol) server for [BackendX](https://www.backendx.ai). It lets an AI agent such as
+Claude Code drive the whole BackendX workflow from your terminal: describe a backend in a requirements
+interview, generate it, run it locally, deploy it, operate it and manage billing, all without leaving the
+agent.
 
-### 플랜 변경 · 취소 · 철회
+The server exposes 76 tools that mirror the BackendX web console. Everything the console can do, the
+agent can do, with the same permission checks and the same billing rules.
 
-```
-get_plan                                 (현재 플랜·pending_state: active | scheduled | canceled)
-  → preview_plan_change                  (mode=immediate 면 amount_due_now 를 사용자에게 제시)
-  → change_plan(confirm)                 (업그레이드 즉시 청구 / 다운그레이드·주기 단축은 기간말 예약)
-  → cancel_subscription(confirm)         (기간말 취소 — 예약된 변경·좌석 감소도 함께 해제)
-  → withdraw_scheduled_plan_change(confirm)  (예약·취소 되돌리기 — 주기를 건드리지 않음)
-```
+## Requirements
 
-Sandbox → 유료 최초 구독만 브라우저(`get_upgrade_url`)가 필요하다.
+- **Node.js 18 or later.**
+- **A BackendX account** signed in with Google at https://www.backendx.ai.
+- **Google Cloud CLI (`gcloud`)**, logged in with the same Google account. The `authenticate` tool
+  exchanges a Google ID token obtained with `gcloud auth print-identity-token`.
+- **`unzip`** on your PATH for the two download tools (`download_project`, `download_source`). It is
+  preinstalled on macOS and most Linux distributions but not on Windows; every other tool works without it.
+- An MCP client. The examples below use Claude Code; any client that speaks MCP over stdio works.
 
-### 프로젝트 삭제
-
-```
-get_deletion_preview                     (can_delete · blocker · 즉시 정산액 · revision)
-  → (deployment_blocker 면) stop_deployment(confirm) → get_deletion_preview 재호출
-  → delete_project(preview_revision, confirm)   (구독 즉시 해지 + 미청구분 즉시 결제)
-```
-
-### 인시던트 대응
-
-```
-list_incidents(category)
-  → get_incident                         (ai_prompt_available · triage_verdict · fix.state)
-  → get_incident_ai_prompt               (4xx 클라이언트 수리 프롬프트 — 409 는 대기·플랫폼 수리·비대상)
-  → (fix.state=ready, auto_redeploy=false 면) deploy_project
-  → update_incident_status(resolved)
-```
+## Install
 
-### 로컬 테스트
+### Claude Code
 
-```
-configure_environment(type:"local")      (환경변수 채우기 — 배포용은 type:"deployment", 별개 저장소)
-  → download_project                     (docker-compose 실행 설정 ZIP)
-  → 컨테이너 기동 (docker compose up)
-  → verify_local_run                     (health check URL 로 기동 확인)
+```bash
+claude mcp add -s user backendx -- npx @backendx/mcp
 ```
 
-### 소스코드 접근 (Builder 플랜 이상)
+Restart Claude Code (or reconnect with `/mcp`). `-s user` registers the server for every project
+directory. The first start takes a few seconds while `npx` downloads the package.
 
-```
-get_plan                                 (플랜에 source_code 포함 여부 확인)
-  → link_github / get_github_account     (GitHub 계정 연결)
-  → purchase_docs(docs:["repo"])         (미러 개설 — 플랜 포함이어도 이 POST 없이는 repo 404)
-  → get_docs(doc:"repo")                 (레포 URL) 또는 download_source (ZIP)
-```
-
-### 배포 후 운영·비용 방어
+To turn off usage analytics (see below), add the environment variable at registration time:
 
-```
-get_ops_summary / list_incidents / get_ops_usage    (모니터링)
-  → configure_hard_stop(api_hard_stop:true)         (quota 초과 시 차단 — 켜지 않으면 초과분 자동 과금)
-  → configure_ops_notifications                     (장애·사용량 이메일 알림)
-  → pause_deployment / resume_deployment            (일시정지·재개)
+```bash
+claude mcp add -s user backendx -e DO_NOT_TRACK=1 -- npx @backendx/mcp
 ```
 
-### 배포 전제조건 체인
+### Other MCP clients
 
-`deploy_project` 는 두 게이트를 모두 통과해야 수락된다. 실패 시 412 가 오는데, MCP 는 이를
-`PRICING_CONSENT_REQUIRED` 와 `QUESTIONNAIRE_INCOMPLETE` 로 구분해 해소 도구를 안내한다.
+Add a stdio server entry to your client's configuration:
 
-```
-get_deploy_readiness            (막힌 이유 한 번에 진단)
-   ├─ accept_pricing_consent    (요금 동의 — confirm=true 필요)
-   └─ submit_deploy_questionnaire
-         ├─ get_consent_questions           (항목·선택지 정의 — 프로젝트 없이도 조회 가능)
-         ├─ get_deployment_data_categories  (data_categories_confirmed 의 key 정본)
-         └─ get_privacy_block               (privacy_block_embedded 가 pin 할 block_hash)
-                ↓
-         deploy_project → get_deployment_status
+```json
+{
+  "mcpServers": {
+    "backendx": {
+      "command": "npx",
+      "args": ["-y", "@backendx/mcp"]
+    }
+  }
+}
 ```
 
-설문은 `stage` 축으로 두 시점에 나뉘어 수집되지만 게이트 판정은 통합이다(전부 필수).
-`stage: project_start` 5종(`restricted_services_ack` · `end_user_jurisdictions` ·
-`minors_in_scope` · `age_gating_measures` · `sensitive_data_in_scope`)은 배포가 아니라
-**프로젝트 생성 직후·첫 `send_message` 이전**에 받는 것이 정본 순서다 — 이 답이 인터뷰
-컨텍스트로 주입되어 첫 SRS 초안에 반영되고, 없으면 인터뷰가 같은 질문을 대화로 되묻는다
-(대화형 답변은 법적 기록으로 쓰이지 않아 결국 두 번 답하게 된다).
-`get_deploy_readiness` 응답의 `questionnaire.stages` 로 `missing` 항목이 어느 시점 것인지
-가를 수 있다. 요금 동의는 웹 콘솔이 **배포할 때마다** 새로 받으므로, `consented: true` 는
-과거 기록이지 이번 배포를 건너뛸 근거가 아니다.
-
-MCP 로 생성한 프로젝트는 설문 답변이 하나도 없는 상태로 시작하므로, 이 체인을 거치지 않으면
-배포가 412 로 막힌다.
-
-### 플랜 게이팅과 과금
-
-구독 모델에서 **소스 접근·배포·요구사항 변경·첨부 업로드는 전부 프로젝트 플랜이 결정**한다.
-크레딧(`get_credits`)은 계정 단위 legacy 잔액이라 이 판정과 무관하다 — 402/403 을 받으면
-`get_plan` 을 먼저 본다.
-
-- **402 는 두 사유가 공유한다**: 요구사항 변경 횟수 소진(`CHANGE_RUN_LIMIT_REACHED`)과
-  첨부 업로드 한도 소진(`FILE_UPLOAD_LIMIT_REACHED`). 상태 코드가 아니라 응답 body 의
-  `error` 코드로만 갈린다 — 판별자는 `src/billing-errors.ts` 한 곳에 있다.
-- **403 도 두 사유가 공유한다**: 역할 권한 부족과 플랜 미포함(`PLAN_UPGRADE_REQUIRED`).
-  body 판별 없이 잠금으로 읽으면 역할이 부족한 멤버에게 결제를 권하게 된다.
-- **한도 초과는 차단이 아니라 과금이다.** API 호출·DB 용량이 플랜 quota 를 넘어도 서비스는
-  계속 돌아가고 초과분이 다음 청구서에 합산된다(에러 없음). `configure_hard_stop` 이 이를
-  막는 유일한 스위치이며, 켜면 quota 소진 시 트래픽이 차단되므로 양방향으로 위험하다.
-- **과금 쓰기는 즉시 결제가 아니라 다음 청구서 이연이다 — 단 하나의 예외가 `change_plan` 이다.**
-  좌석 추가·변경 횟수 구매는 `create_prorations` 로 다음 renewal invoice 에 실린다 — 카드가
-  그 자리에서 긁히지 않는다. `preview_seats` 의 `prorated_now` 도 "지금 청구액"이 아니라 그
-  청구서에 실릴 잔여 기간 일할분이다. 반면 **플랜 업그레이드(`change_plan`)는 `always_invoice`
-  로 차액을 즉시 청구**하므로 반드시 `preview_plan_change` 의 `amount_due_now` 를 사용자에게
-  보인 뒤 호출한다. 다운그레이드·주기 단축은 기간말 예약(청구 없음)이다. 청구가 확정되는
-  구속력 있는 조작은 전부 `confirm=true` 가드를 유지한다.
-- **프로젝트 삭제는 즉시 정산이다.** `delete_project` 는 구독을 그 자리에서 해지하고 미청구분
-  (구매한 변경 횟수 잔여·미납 인보이스)을 즉시 결제한다. `get_deletion_preview` 가 그 금액과
-  차단 사유를 먼저 보여주며, 그 `revision` 없이는 삭제를 호출할 수 없다.
-- **금액은 전부 minor units 정수 + currency** 로 전달한다. 포맷하지 않는다 —
-  KRW 같은 zero-decimal 통화를 1/100 로 표시하는 사고를 막기 위함이다.
-- **브라우저가 필수인 결제는 이제 둘뿐이다**: Sandbox 프로젝트의 **최초** 유료 구독(hosted
-  checkout, `get_upgrade_url`)과 결제수단 변경(`get_billing_portal_url`). 이미 구독 중인
-  프로젝트의 플랜·주기 변경(`change_plan`), 취소(`cancel_subscription`), 예약·취소 철회
-  (`withdraw_scheduled_plan_change`)는 API 로 완결된다. 링크를 받은 것이 작업 성공은 아니다.
-
-## 프로젝트 구조
+### Updating
 
-```
-src/
-├── index.ts        # 진입점 (stdio transport)
-├── server.ts       # MCP 서버 생성 및 도구 등록
-├── state.ts        # 인메모리 상태 관리 (토큰)
-├── client.ts       # BackendX API 클라이언트
-├── polling.ts      # 폴링/재시도/복구 로직
-├── constants.ts    # 워크플로우 상태, 임계값
-├── types.ts        # API 응답 타입 정의
-├── analytics.ts    # GA4 Measurement Protocol 계측
-├── version.ts      # package.json 의 version 을 읽어 MCP 서버 버전·버전 체크 헤더로 사용
-├── tool-utils.ts   # MCP 도구 공용 유틸리티
-└── tools/          # 워크플로우 도구
-tsup.config.ts      # 번들 설정 — 빌드 시 GA 키 내장 (아래 "배포 빌드")
-```
+`npx @backendx/mcp` resolves the latest published version every time the server starts, so restarting
+the MCP server (restart Claude Code or run `/mcp`) picks up updates. If you installed globally, run
+`npm install -g @backendx/mcp@latest` and restart.
 
-## 요구 사항
+## Quick start
 
-- **Node.js 18 이상** — 전역 `fetch`·`AbortController` 를 사용한다.
-- **`unzip` 명령** — `download_project`·`download_source` 가 내려받은 zip 을 풀 때 외부
-  `unzip` 바이너리를 호출한다. macOS·대부분의 Linux 에는 기본 탑재되어 있으나
-  **Windows 에는 없다** (해당 2종만 영향, 나머지 도구는 정상 동작).
+1. **Authenticate.** Ask the agent to log in to BackendX. It runs `gcloud auth print-identity-token`
+   and calls `authenticate`. The token lives only in the server process's memory, so you authenticate
+   again after each restart.
 
-## 설치
+2. **Build a backend.** Describe what you want:
 
-### npm (배포 후 권장 경로)
+   > Build the backend for a futsal player-matching service in Korea.
 
-```bash
-claude mcp add -s user backendx -- npx @backendx/mcp
-```
+   The agent shows you the five project-start consent questions (`get_consent_questions`), creates
+   the project, records your answers, then runs the requirements interview through `send_message`.
+   When the interview is done it waits for the pipeline (`wait_for_pipeline`) to produce the SRS,
+   architecture, code and Docker images, and summarises the result from `get_docs` and
+   `get_er_diagram`.
 
-> npm 배포는 아직 진행 전이다(BETA3-32). 배포 전까지는 아래 로컬 빌드 방식을 쓴다.
+3. **Run it locally.** `configure_environment` fills in environment values, `download_project`
+   fetches the docker-compose bundle, and `verify_local_run` gives you the health-check URL.
 
-이 패키지는 오픈소스가 아니라 **BackendX 서비스 이용 목적의 설치·실행만 허용하는 proprietary
-소프트웨어**다. 설치·실행은 패키지에 동봉된 [`LICENSE`](LICENSE) 의 이용 조건에 동의하는 것으로
-본다. 기동 시 외부 통신(버전 체크)과 사용 계측이 있으며 자세한 내용은 아래
-"라이선스와 고지 사항" 절과 `LICENSE` §4·§5 를 참고한다.
+4. **Build a client.** `get_api_clipboard` returns the full API reference wrapped in integration
+   instructions, ready to hand to whatever writes your frontend or mobile app.
 
-### 로컬 빌드 (개발용)
+5. **Deploy.** `get_deploy_readiness` tells the agent exactly what is missing. It collects the
+   deployment questionnaire, records pricing consent, calls `deploy_project`, and reports the live
+   URL from `get_deployment_status`.
 
-```bash
-npm install
-npm run build
-claude mcp add -s user backendx -- node /path/to/backendx-mcp/dist/index.js
-```
-
-### 인증 유지 범위
+6. **Operate.** Incidents, usage against quota, container resources, notifications and hard stops
+   are all one question away.
 
-인증 토큰은 **프로세스 메모리에만** 보관하고 디스크에 저장하지 않는다.
-따라서 MCP 서버가 재시작될 때마다 `authenticate` 를 다시 호출해야 한다.
+## Tools
 
-### 버전 게이트와 업데이트
+### Authentication and account
 
-MCP 서버는 **기동할 때마다** `{BACKENDX_FRONTEND_URL}/api/mcp/version-check` 에 자기 버전을 보내
-판정을 받고, 그 결과를 프로세스가 살아 있는 동안 캐시한다.
-
-| 판정 | 동작 |
+| Tool | What it does |
 | --- | --- |
-| `ok` | 정상 |
-| `update_recommended` | 정상 동작. stderr 에 `[version-check] update_recommended: …` 한 줄만 남긴다 |
-| `update_required` | **모든 tool 이 `UPDATE_REQUIRED` 로 차단**되고 `authenticate` 도 426 으로 거절된다 |
-| `fail` — 판정 불가(네트워크·타임아웃·서버 미구성) | **모든 tool 이 `VERSION_CHECK_FAILED` 로 차단**된다 (fail-closed) |
-
-차단 응답에는 `current_version`·`latest_version`·`min_supported_version`·`update_url` 과 함께
-조치 방법(`how_to_update` / `how_to_fix`)이 실려 있어 에이전트가 그대로 사용자에게 안내한다.
-
-**업데이트 방법:** `npx @backendx/mcp` 는 기동 때마다 레지스트리의 latest 를 확인하므로
-**MCP 서버를 재시작**하면 된다 (Claude Code: `/mcp` 재연결 또는 재시작). 버전을 고정했거나
-전역 설치했다면 `npm install -g @backendx/mcp@latest` 후 재시작한다.
+| `authenticate` | Exchange a Google ID token for a BackendX session. Also checks EULA status and returns account info. |
+| `get_account` | Connected login providers, legacy credit balance, intro and coupon flags that affect what a plan costs you. |
+| `get_github_account` | The GitHub account linked to your BackendX user (used to add you as a collaborator on generated repos). |
+| `link_github` | Link a GitHub account with a personal access token. Needed for source repository access. |
+| `unlink_github` | Unlink GitHub (`confirm=true`). Collaborator access to all mirrored repos is revoked immediately. |
 
-**사용자 고지:** 기동 시 BackendX 서버로 버전을 전송한다는 것과 지원 종료 버전·판정 불가 시
-전체 도구가 차단된다는 것은 배포 패키지의 `LICENSE` §4 에 이용 조건으로 명시되어 있다
-(BETA3-524). 이 동작을 바꾸면 `LICENSE` §4 와 이 절을 함께 고친다.
+### Project lifecycle
 
-환경변수:
-
-- `BACKENDX_API_URL` (기본값: `https://api.backendx.ai`)
-- `BACKENDX_FRONTEND_URL` (기본값: `https://www.backendx.ai`)
-- `GA_MEASUREMENT_ID` (선택): GA4 측정 ID. npm 배포본에는 프로덕션 키가 **빌드 시 내장**되어 있어 평소엔 설정할 필요가 없다. 설정하면 내장값을 덮어쓴다 — 스테이징 속성으로 보내거나 로컬 개발에서 바꿀 때 쓴다. `GA_API_SECRET` 와 **함께** 있어야 계측이 활성이며, 둘 중 하나라도 비면(내장값도 env 도 없음) 완전 비활성(no-op).
-- `GA_API_SECRET` (선택): GA4 Measurement Protocol API secret. 위와 같은 우선순위(런타임 env > 내장값). GA4 콘솔 → 관리 → 데이터 스트림 → Measurement Protocol API secrets 에서 발급.
-- `DO_NOT_TRACK` (선택): `1`·`true`·`yes` 중 하나면 GA 키가 설정돼 있어도 계측을 보내지 않는다. CLI 생태계의 사실상 표준 스위치.
-- `BACKENDX_TELEMETRY_DISABLED` (선택): 위와 동일하게 동작하는 제품 전용 스위치.
+| Tool | What it does |
+| --- | --- |
+| `get_consent_questions` | The consent questionnaire definition. Needs no project or login; use `stage` to pick the project-start or deploy items. |
+| `create_project` | Create a project. Record the five project-start answers right after, before the first message. |
+| `list_projects` | All your projects with their pipeline state. |
+| `get_project_status` | Pipeline stage, recent events, available files, plan summary and your role. `has_failed_stage` separates "waiting for you" from "stopped". |
+| `rename_project` | Change a project's label. |
+| `get_deletion_preview` | Whether a project can be deleted, what blocks it, and what deleting it would charge. Returns the revision `delete_project` needs. |
+| `delete_project` | Permanently delete a project (`confirm=true` and a fresh preview revision). Cancels the subscription and settles outstanding charges immediately. |
+| `send_message` | Send a message in the requirements interview and receive the AI reply. |
+| `get_messages` | Conversation history (interview turns and progress events), newest first. |
+| `upload_attachment` | Upload a local file as a requirements attachment. Plan-limited. |
+| `download_attachment` | Download an attachment by id. |
+| `list_revisions` | SRS revision history with change summaries. |
+| `wait_for_pipeline` | Block until the generation pipeline finishes, with per-stage expected durations. |
+| `retry_pipeline` | Retry a stalled or failed pipeline from a chosen restart point. |
+| `get_system_status` | Platform health and pending maintenance. Works before login and needs no project. |
+| `get_progress` | Paginated step-by-step pipeline progress. |
+
+### Documents and artifacts
+
+| Tool | What it does |
+| --- | --- |
+| `get_docs` | Project documents: API reference, scheduled tasks, Docker images (free); SRS, architecture, DB schema, Dockerfiles, repository URL (plan-gated). |
+| `purchase_docs` | Report which documents your plan grants and open the GitHub source mirror (`repo`). Access is decided by the plan; nothing is bought per document. |
+| `get_api_clipboard` | One ready-to-paste prompt for building a client against this backend, with the live base URL when deployed. Same output as the console's "Copy AI prompt" button. |
+| `download_source` | Download and extract the generated source code as a ZIP (Builder plan and above). The archive contains real secrets. |
+| `get_er_diagram` | Entity-relationship diagram. `format="mermaid"` returns text the agent can read; svg/png/pdf/zip return files or presigned URLs. |
 
-## 사용 계측 (GA4, 서버사이드)
+### Local run
 
-브라우저가 없는 MCP 는 gtag 대신 GA4 **Measurement Protocol**로 프론트와 동일한 GA4 속성에 이벤트를 보낸다(`origin: "mcp"` 파라미터로 브라우저 트래픽과 구분). 전송은 fire-and-forget — 실패해도 tool 응답에 영향이 없다.
+| Tool | What it does |
+| --- | --- |
+| `configure_environment` | Read, set or reset environment values, separately for the local and deployment buckets. |
+| `download_project` | Download and extract the docker-compose bundle for running locally. |
+| `get_project_file` | Read a single project file as text (names come from `get_project_status`). Credential files return placeholders. |
+| `verify_local_run` | The health-check URL for confirming the local containers are up. |
 
-**npm 배포본은 계측이 기본으로 켜져 있다.** GA 키가 배포 빌드 때 번들에 내장되기 때문이며(아래 "배포 빌드" 참고), 사용자는 환경변수 하나로 끌 수 있다. 키가 내장되지 않은 로컬 빌드는 env 로 키를 주지 않는 한 아무것도 보내지 않는다.
+### Deployment
 
-| 이벤트          | 발화 시점                                | 주요 파라미터                         |
-| --------------- | ---------------------------------------- | ------------------------------------- |
-| `mcp_started`   | 서버 기동(버전 체크 직후) 1회            | `version_status`, `mcp_version`       |
-| `mcp_tool_used` | 모든 tool 호출(단일 길목 `registerTool`) | `tool_name`, `outcome`(success/error), 실패 시 `error_code`(fail code, 예: `UPDATE_REQUIRED`/`AUTH_FAILED`) |
+| Tool | What it does |
+| --- | --- |
+| `get_deploy_readiness` | Can this project deploy, and if not, what is missing: pricing consent and questionnaire state in one call. |
+| `accept_pricing_consent` | Record consent to the managed-hosting pricing policy (`confirm=true`). Recorded fresh for every deployment. |
+| `submit_deploy_questionnaire` | Record deployment questionnaire answers. Blocking answers need `confirm_blocking=true`. |
+| `get_deployment_data_categories` | The personal-data categories derived from the schema, which the questionnaire confirmation must match. |
+| `get_privacy_block` | Generate or fetch the privacy-disclosure text you must publish with the deployed service. |
+| `deploy_project` | Deploy a finished project to the managed shared pool, optionally a specific revision. |
+| `get_deployment_status` | Deployment state, API base URL and deployable revisions. |
+| `pause_deployment` | Pause a deployment. Domain, data and secrets are kept. |
+| `resume_deployment` | Resume a paused deployment at no extra charge. |
+| `stop_deployment` | Remove a deployment (`confirm=true`). The deployment database is deleted permanently. |
+
+### Operations
+
+| Tool | What it does |
+| --- | --- |
+| `get_ops_summary` | Incident KPI counts over a time range. |
+| `list_incidents` | Incidents by category: needs attention, in progress, resolved. |
+| `get_incident` | One incident's timeline, triage verdict, automatic-fix progress and mute state. |
+| `get_incident_ai_prompt` | A ready-made prompt for fixing a 4xx incident in the client that calls this backend. |
+| `update_incident_status` | Move an incident forward. `resolved` cannot be undone. |
+| `mute_incident_notifications` | Mute or unmute notifications for one incident. |
+| `get_ops_usage` | API calls and database size against the plan quota, with per-day counts. Exceeding the quota bills overage rather than stopping the service. |
+| `get_usage_by_date` | API-call breakdown for one day. |
+| `get_ops_resources` | CPU, memory and network usage across the project's containers. |
+| `configure_hard_stop` | Read or set the API-call hard stop that blocks traffic at the quota instead of billing overage. |
+| `configure_ops_notifications` | Read or change operational notification preferences. |
+
+### Billing, subscription and seats
+
+| Tool | What it does |
+| --- | --- |
+| `get_plan` | The project's plan, status, trial state, scheduled changes, seat and change-run allowances, and next-invoice estimates. Read this before any billing action. |
+| `list_invoices` | Billing history, newest first. Owner only. |
+| `list_members` | Members, pending invites and seat requests, with seat accounting. |
+| `preview_seats` | Price adding seats. No side effects. |
+| `set_seats` | Set the total seat count (`confirm=true`). Increases are charged today; decreases apply next cycle. |
+| `purchase_seats_and_invite` | Add seats and invite people in one step (`confirm=true`). Seats are charged immediately. |
+| `create_seat_request` | Admin-side invite when seats are short: invites into free seats and queues the rest for owner approval. |
+| `resolve_seat_request` | Approve or reject a seat request. Owner only; approval buys seats and needs `confirm=true`. |
+| `purchase_change_runs` | Buy additional requirement-change runs (`confirm=true`). Charged at purchase. |
+| `cancel_subscription` | Cancel the subscription (`confirm=true`). Normally takes effect at period end and can be withdrawn; during a trial it is immediate. |
+| `preview_plan_change` | What a plan or interval change would charge today. No side effects. |
+| `change_plan` | Change plan or billing interval (`confirm=true`). Upgrades are charged immediately; downgrades are scheduled for period end. |
+| `withdraw_scheduled_plan_change` | Cancel a scheduled plan change or a pending cancellation (`confirm=true`). |
+| `get_billing_portal_url` | One-time link to the billing portal for payment methods, past invoices and resuming a subscription. |
+| `get_upgrade_url` | Link to the plan page in the web console. Required for a Sandbox project's first paid subscription. |
+| `get_pricing` | Legacy per-item credit prices, kept for compatibility. Not the current pricing model. |
+| `get_credits` | Remaining legacy credits. They do not gate artifacts, deployment or changes. |
+| `redeem_coupon` | Register a pre-signup promo code. |
+
+### Members, roles and sharing
+
+| Tool | What it does |
+| --- | --- |
+| `get_role_matrix` | Which capabilities each role carries and which are owner-only. Read this after a permission refusal. |
+| `manage_invite` | Send, cancel or resend invitations. An open invite holds a seat. |
+| `manage_member` | Change a member's role or seat, or remove them (`confirm=true` for removal). |
+| `transfer_ownership` | Transfer project ownership (`confirm=true`). The previous owner becomes an admin. |
+| `leave_project` | Leave a project you are not the owner or admin of (`confirm=true`). |
+| `claim_invite` | Accept an invitation by token or link. |
+| `manage_share_link` | List, create or revoke share links, including the public API-doc link `get_api_clipboard(link=true)` mints. |
 
-**사용자 단위 식별자는 보내지 않는다.** 페이로드의 최상위 키는 프로세스마다 새로 발급하는
-무작위 `client_id` 와 `events` 둘뿐이고, `authenticate` 성공 후에도 GA4 `user_id` 는 설정하지
-않는다 — 이메일은 원문은 물론 해시 형태로도 계측에 넘기지 않는다(BETA3-555,
-`tests/analytics.test.ts` 가 페이로드 모양을 고정). 이벤트는 프로세스 단위 `client_id` ·
-`session_id` 로만 묶이므로 GA 의 활성 사용자·리텐션 리포트는 "MCP 프로세스" 단위로 읽어야 한다.
+## Workflows
 
-**끄는 방법:** `DO_NOT_TRACK=1` 또는 `BACKENDX_TELEMETRY_DISABLED=1` 을 설정하면 GA 키가
-내장·설정돼 있어도 아무것도 전송하지 않는다.
+### Interview, generate, deploy
 
-```bash
-claude mcp add -s user backendx -e DO_NOT_TRACK=1 -- npx @backendx/mcp
+```
+authenticate
+  → get_consent_questions            (stage="project_start": five questions shown to you first)
+  → create_project
+  → submit_deploy_questionnaire      (record those five answers before the first message)
+  → send_message ⇄ get_messages      (requirements interview)
+  → wait_for_pipeline                (SRS → architecture → code → Docker images)
+  → get_docs / get_er_diagram / download_source
+  → deployment gate (below)
+  → deploy_project → get_deployment_status
 ```
 
-**프론트엔드와의 차이:** 웹(backendx-frontend)은 쿠키 동의 배너로 GA 를 opt-in 게이트하고
-GPC 신호가 있으면 gtag 자체를 로드하지 않는다. MCP 는 브라우저가 없어 동의 배너도 GPC
-신호도 받을 수 없으므로 위 opt-out 스위치로 대체한다. 수집 범위는 웹과 같다 — 둘 다 GA 에
-사용자 단위 식별자를 보내지 않는다. BETA3-524 법무 검토는 옵트아웃 방식과 api_secret 내장을
-현행 유지해도 되되, 이메일 해시 `user_id` 전송만은 제거하라고 결론냈고(BackendX 가 원문
-이메일을 보유하므로 해시는 익명정보가 아닌 가명정보), 그 제거가 BETA3-555 다. 수집 항목·
-옵트아웃 방법의 사용자 고지는 `LICENSE` §5 가 담당한다. **`LICENSE` §5 는 실제 전송 항목의
-사용자 고지이므로 코드와 항상 붙어 다녀야 한다** — 수집 항목을 바꾸면 `src/analytics.ts`·
-이 절·`LICENSE` §5 를 같은 PR 에서 함께 고친다. §5 의 문언 자체를 손보는 게 아니라 수집
-항목을 좁히는 동기화라면 그대로 진행하고, 조항의 취지나 범위를 넓히는 변경이면 법무 검토를
-먼저 받는다.
-
-GA4 콘솔에서 `tool_name`·`outcome`·`origin`·`version_status` 를 맞춤 측정기준(이벤트 범위)으로 등록해야 표준 리포트에 축으로 나온다(비소급).
+### Deployment gate
 
-### 배포 빌드 (GA 키 내장)
+`deploy_project` is accepted only when both gates pass. The agent diagnoses what is missing with a
+single call and resolves each item:
 
-`npx` 로 실행되는 사용자 환경에는 우리 GA 키가 env 로 없으므로, `tsup.config.ts` 가 빌드 시
-`GA_MEASUREMENT_ID`·`GA_API_SECRET` 를 번들 상수(`__GA_MEASUREMENT_ID__` 등)로 치환해 내장한다.
-`src/analytics.ts` 는 "런타임 env > 내장값" 순으로 읽으므로 내장 후에도 env 로 덮어쓸 수 있다.
+```
+get_deploy_readiness
+   ├─ accept_pricing_consent           (pricing policy shown, then confirm=true)
+   └─ submit_deploy_questionnaire
+         ├─ get_consent_questions          (item definitions and allowed answers)
+         ├─ get_deployment_data_categories (keys the data-category confirmation must match)
+         └─ get_privacy_block              (the block_hash the privacy confirmation pins)
+```
 
-| 빌드 | 명령 | 키 출처 | 키가 비면 |
-| --- | --- | --- | --- |
-| 개발 | `npm run build` | 셸 env > `.env`(gitignore, `.env.example` 참고) | 경고 후 계측 비활성 번들 |
-| 배포 | `npm run build:release` (= `npm publish` 의 `prepublishOnly`) | **셸 env 만** — `.env` 는 읽지 않는다 | **빌드 실패** |
+The five project-start items (restricted services, end-user jurisdictions, minors, age gating,
+sensitive data) are legal disclosures recorded under your identity. The agent asks you and never
+answers on your behalf. Some answers rule out BackendX-managed deployment; the agent warns you before
+recording one.
 
-배포 빌드가 `.env` 를 무시하는 이유: 로컬 `.env` 에는 보통 스테이징 키가 활성돼 있어, 그대로
-publish 하면 스테이징 키가 프로덕션 패키지에 들어간다. 프로덕션 키는 publish 시점에 셸로 넘긴다.
+### Plan changes
 
-```bash
-GA_MEASUREMENT_ID=G-XXXXXXXXXX GA_API_SECRET=xxxxxxxx npm publish
+```
+get_plan                               (current plan and pending_state)
+  → preview_plan_change                (today's charge, shown to you first)
+  → change_plan(confirm)               (upgrade charged now / downgrade scheduled for period end)
+  → cancel_subscription(confirm)
+  → withdraw_scheduled_plan_change(confirm)
 ```
 
-빌드 로그의 `[build] GA 키 내장: measurement_id=G-...` 줄로 어느 속성이 들어갔는지 확인한다
-(api_secret 은 출력하지 않는다). Measurement Protocol 의 api_secret 은 공개 패키지에 내장되면
-읽을 수 있지만, 노출 시 영향은 제3자가 우리 GA 속성에 가짜 이벤트를 보낼 수 있는 정도이며 GA4
-콘솔에서 즉시 회전할 수 있다(Angular CLI 등 CLI 계측의 통상 관행). 그래도 내장이 불가하다는
-결론이 나면 BE 프록시 방식으로 전환한다(BETA3-524 법무 검토 항목 5-ⓔ).
-
-## 라이선스와 고지 사항
+A Sandbox project's first paid subscription is the one step that needs a browser: the agent hands you
+the link from `get_upgrade_url`.
 
-외부 사용자에게 이용 조건이 전달되는 공식 경로는 레포 루트의 [`LICENSE`](LICENSE) 파일이다.
-`npm publish` 는 `package.json` 의 `files` 화이트리스트와 무관하게 `LICENSE` 를 항상 패키지에
-포함하므로, 사용자는 `node_modules/@backendx/mcp/LICENSE` 와 npmjs.com 패키지 페이지에서 볼 수
-있다. `package.json` 의 `license` 필드는 `"SEE LICENSE IN LICENSE"` 로, "조건은 LICENSE 파일을
-보라"는 npm 표준 표기다(BETA3-524 항목 3).
+### Deleting a project
 
-`LICENSE` 의 구성과 이 README 의 대응 절:
+```
+get_deletion_preview                   (can_delete, blockers, amount settled immediately)
+  → stop_deployment(confirm)           (only if a live deployment blocks deletion)
+  → delete_project(preview_revision, confirm)
+```
 
-| `LICENSE` 절 | 내용 | 코드·README 대응 |
-| --- | --- | --- |
-| §1–§3 | proprietary 고지, 설치·실행 허용, 수정·재배포·경쟁 목적 사용·과금 우회 금지 | — |
-| §4 | 기동 시 버전 체크 외부 통신, 지원 종료 버전·판정 불가 시 전체 도구 차단(fail-closed) | `src/client.ts` `checkVersion`, "버전 게이트와 업데이트" 절 |
-| §5 | 사용 계측: 기본 활성, 수집 항목·미수집 항목, `DO_NOT_TRACK`/`BACKENDX_TELEMETRY_DISABLED` 옵트아웃 | `src/analytics.ts`, "사용 계측" 절 |
-| §6 | AI 에이전트가 자율 호출하는 삭제·과금 도구에 대한 사용자 책임 | `delete_project`, `purchase_*`, `change_plan`, 배포 조작 도구 |
-| §7–§8 | 보증 부인, 책임 제한 | — |
-| §9 | 서드파티 의존성은 별도 라이선스(번들에 미포함) | `tsup` 기본 external 처리 |
-| §10–§12 | 종료, 준거법(대한민국), 일반 조항 | — |
+### Incident response
 
-**변경 규칙:** 외부 통신 대상, 계측 수집 항목, 옵트아웃 방법, 과금·삭제 도구의 동작 중 하나라도
-바뀌면 `LICENSE` 의 해당 절을 같은 PR 에서 고친다. `LICENSE` 문구의 확정·변경 이력은 BETA3-524
-가 정본이다.
+```
+list_incidents(category)
+  → get_incident                       (triage verdict, automatic fix state)
+  → get_incident_ai_prompt             (client-side fix prompt for 4xx incidents)
+  → deploy_project                     (when a repaired revision is ready and not auto-deployed)
+  → update_incident_status(resolved)
+```
 
-## 배포 절차 (npm publish)
+### Source code access (Builder plan and above)
 
-"버전" 은 두 곳에 있고 역할이 다르다.
+```
+get_plan                               (does the plan include source_code?)
+  → link_github / get_github_account
+  → purchase_docs(docs: ["repo"])      (opens the GitHub mirror)
+  → get_docs(doc: "repo") or download_source
+```
 
-| 위치 | 값 | 역할 |
+## How billing works through the agent
+
+- Access to artifacts, deployment, requirement changes and uploads is decided by the **project's
+  plan**, not by account credits. When something is refused, the agent reads `get_plan` first.
+- Every action that charges money or destroys data requires `confirm=true`, and the preview tools
+  (`preview_seats`, `preview_plan_change`, `get_deletion_preview`) exist so the agent can show you
+  the exact amount before asking.
+- Seat additions, change-run purchases and plan upgrades are charged immediately. Downgrades and
+  cancellations take effect at the end of the billing period.
+- Deleting a project cancels its subscription and settles outstanding amounts at once.
+- Exceeding the API-call or database quota does not stop the service; the excess is billed on the
+  next invoice. `configure_hard_stop` is the switch that blocks traffic instead.
+- Amounts are reported in the currency's minor units alongside a currency code, exactly as billed.
+- Two things need a browser: a Sandbox project's first paid subscription (`get_upgrade_url`) and
+  changing the payment method (`get_billing_portal_url`). Everything else completes through the API.
+
+## Safety
+
+The tools are designed to be called by AI agents. They can create, modify, deploy, stop and
+permanently delete resources in your BackendX account, and they can incur charges. Actions taken
+through this server with your credentials are treated as authorised by you, whether you issued them
+directly or an agent did so on your behalf. Review what the agent proposes before confirming
+destructive or billable actions, and grant it access only in environments you control.
+
+## Configuration
+
+| Variable | Default | Purpose |
 | --- | --- | --- |
-| 이 레포 `package.json` → `version` | **패키지 버전** | 배포물이 몇 버전인지. `src/version.ts` 가 런타임에 읽어 MCP 서버 버전·`X-MCP-Version` 헤더·기동 시 버전 체크 요청에 쓴다 |
-| backendx-frontend `backend/docker-compose.yaml` → `MCP_MIN_VERSION` / `MCP_LATEST_VERSION` | **지원 정책** | FE(`lib/mcp-version.ts`)가 클라이언트 버전을 판정하는 기준. `MIN` 미만이면 `update_required` → **모든 tool 차단**·인증 426. `LATEST` 미만이면 `update_recommended` → stderr 경고만 |
-
-패키지는 스스로 최신 여부를 알 수 없고, 한 번 publish 된 버전은 고칠 수 없다. 그래서 옛
-클라이언트를 밀어내는 기준(정책)은 서버 쪽에 둔다. 두 값이 서로 다른 레포에 있으므로
-**순서가 중요하다** — FE 값을 먼저 올리면 npm 에 아직 없는 버전을 요구하게 되어, 사용자
-전원이 `update_recommended`(LATEST) 또는 tool 차단(MIN)을 본다. 항상 **npm 먼저, FE 나중**.
+| `BACKENDX_API_URL` | `https://api.backendx.ai` | BackendX API endpoint. |
+| `BACKENDX_FRONTEND_URL` | `https://www.backendx.ai` | Web console endpoint, used for the version check and console links. |
+| `DO_NOT_TRACK` | unset | Set to `1`, `true` or `yes` to disable usage analytics. |
+| `BACKENDX_TELEMETRY_DISABLED` | unset | Same effect as `DO_NOT_TRACK`. |
 
-### 순서
+No configuration is needed for normal use. Authentication tokens are kept in memory only and are
+never written to disk.
 
-1. **검증.** 워킹 트리가 깨끗해야 `npm version` 이 동작한다.
+## Version check and updates
 
-   ```bash
-   git status                              # clean 이어야 한다
-   npm test
-   npm run build && npm pack --dry-run     # 타르볼: README.md · dist/index.js · package.json 3개뿐인지
-   ```
+Each time the server starts it sends its version to `https://www.backendx.ai/api/mcp/version-check`
+and caches the answer for the life of the process.
 
-2. **버전 올림.** `package.json` 갱신 + 커밋 + `v{version}` git 태그를 한 번에 만든다.
-
-   ```bash
-   npm version patch -m "chore: 배포 버전 %s (BETA3-xx)"   # patch | minor | major
-   ```
-
-   | 단계 | 언제 |
-   | --- | --- |
-   | `patch` | 버그 수정, 문구·설명 변경 |
-   | `minor` | 도구 추가, BE 계약 동기화 등 옛 버전도 계속 동작하는 변경 |
-   | `major` | FE·BE 계약이 바뀌어 옛 버전이 더 이상 동작하지 않을 때 (→ 5단계에서 `MIN` 도 올린다) |
-
-3. **publish.** `prepublishOnly` 가 `build:release` 를 돌리므로 프로덕션 GA 키를 셸로 넘긴다
-   (위 "배포 빌드"). 키가 없으면 빌드가 실패해 publish 되지 않는다.
-
-   ```bash
-   GA_MEASUREMENT_ID=G-XXXXXXXXXX GA_API_SECRET=xxxxxxxx npm publish
-   git push && git push --tags
-   ```
-
-4. **전파 확인.** 새 버전은 현재 FE 정책(`MIN` ≤ 새 버전) 아래서 그대로 `ok` 판정이므로,
-   FE 를 건드리기 전에 실제 배포본으로 기동을 확인한다.
-
-   ```bash
-   npm view @backendx/mcp version          # 방금 올린 버전
-   npx -y @backendx/mcp@latest             # stderr 에 [version-check] 경고가 없어야 한다 (Ctrl+C 로 종료)
-   ```
-
-5. **FE 정책 갱신.** backendx-frontend `backend/docker-compose.yaml` 의 `MCP_LATEST_VERSION` 을
-   새 버전으로 올리고 배포한다. 이 compose 는 서버에서도 쓰이며, 값을 바꾼 뒤
-   `docker compose up -d nextjs` 로 컨테이너를 다시 만들어야 반영된다.
-
-   `MCP_MIN_VERSION` 은 **옛 버전을 실제로 막아야 할 때만** 올린다 — 올리는 순간 그 미만
-   사용자는 tool 이 전부 막히므로, `LATEST` 를 먼저 올려 경고를 내보낸 뒤 시차를 두고 올린다.
-
-### 사용자에게 반영되는 시점
-
-`npx @backendx/mcp` 는 기동 때마다 레지스트리의 latest 를 확인하므로, 사용자는 MCP 서버가
-**재시작될 때**(Claude Code 재시작 또는 `/mcp` 재연결) 새 버전을 받는다. 이미 떠 있는
-프로세스는 옛 버전 그대로다. 버전 판정도 기동 시 1회 받아 프로세스 수명 동안 캐시하므로,
-그 사이 FE `MIN` 이 올라가도 재시작 전까지는 tool 이 막히지 않는다(단 `authenticate` 재호출은
-인증 라우트가 헤더를 새로 판정해 426 으로 거절한다).
-
-### 롤백
-
-publish 된 버전은 덮어쓸 수 없다(`npm unpublish` 는 72시간 제한이 있고 권장되지 않는다).
-문제가 있는 버전은 `latest` 태그를 이전 버전으로 되돌리고 deprecate 한 뒤, 고친 patch 를 새로 올린다.
-
-```bash
-npm dist-tag add @backendx/mcp@1.0.0 latest        # latest 를 이전 버전으로
-npm deprecate @backendx/mcp@1.0.1 "1.0.2 로 올려주세요"
-```
-
-FE `MCP_LATEST_VERSION` 을 이미 올렸다면 같이 되돌린다. `MIN` 을 되돌린 버전보다 높게
-올렸다면 되돌린 버전 사용자가 전부 막히므로 `MIN` 도 반드시 낮춘다.
+| Result | Behaviour |
+| --- | --- |
+| `ok` | Normal operation. |
+| `update_recommended` | Normal operation. One line is written to stderr suggesting an update. |
+| `update_required` | Every tool refuses with `UPDATE_REQUIRED` until you update. |
+| Check failed (network error, timeout, server error) | Every tool refuses with `VERSION_CHECK_FAILED` until the check succeeds. |
 
-## 로컬 개발
+A refused call includes the current, latest and minimum supported versions and the steps to update.
+Restarting the MCP server is enough when running through `npx`. This behaviour is part of the licence
+terms (see LICENSE §4).
 
-기본값이 운영 서버(prod)로 설정되어 있으므로, 로컬 개발 시에는 환경변수로 로컬 URL을 오버라이드해야 합니다.
+## Usage analytics
 
-사전 준비: 백엔드 서버(`localhost:8000`)와 프론트엔드 서버(`backendx-frontend`, `localhost:3000`)를 먼저 실행해주세요.
+The server sends limited usage analytics to Google Analytics 4 and they are **on by default** in the
+published package.
 
-### 방법. 설정 파일 직접 편집 (env 변경 시 편리)
+- **Collected:** the name of each tool invoked; whether it succeeded or failed and, on failure, an
+  error code; the server version; a random per-process client identifier; a session identifier.
+- **Not collected:** your email address in any form, authentication tokens, environment values,
+  project contents, prompts, generated code, or the arguments and results of tool calls.
+- **Opt out:** set `DO_NOT_TRACK=1` or `BACKENDX_TELEMETRY_DISABLED=1`. Nothing is sent and nothing
+  else changes.
 
-`~/.claude.json`의 최상단 `mcpServers.backendx.env` 값을 직접 수정합니다. user scope(최상단)에 두면 모든 경로에서 동일하게 적용됩니다.
+The full description is in LICENSE §5 and the [BackendX Privacy Policy](https://www.backendx.ai/landing/en/privacy).
 
-```json
-{
-  "mcpServers": {
-    "backendx": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["/path/to/backendx-mcp/dist/index.js"],
-      "env": {
-        "BACKENDX_API_URL": "http://localhost:8000",
-        "BACKENDX_FRONTEND_URL": "http://localhost:3000"
-      }
-    }
-  }
-}
-```
+## License
 
-> 주의: `projects.*.mcpServers`에 같은 이름의 항목이 있으면 user scope를 덮어씁니다. 전역으로 쓰고 싶다면 project scope의 동일 항목은 제거해주세요.
+This package is proprietary software, not open source. You may install and run it to use BackendX
+services through your own account; modification, redistribution and use in competing products are not
+permitted. Installing or running the package means you accept the terms in the bundled
+[LICENSE](LICENSE) file, which also governs the version check and analytics described above. Use of
+the services themselves is governed by the
+[BackendX Terms of Service](https://www.backendx.ai/landing/en/terms).
 
-편집 후 Claude Code에서 `/mcp`로 재연결하거나 재시작해야 반영됩니다.
+Copyright (c) 2026 BackendX Inc. All rights reserved.
 
-### 코드 수정 후
+## Support
 
-코드를 수정한 뒤에는 `npm run build`로 재빌드해야 변경 사항이 반영됩니다.
+Questions and issues: https://www.backendx.ai

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backendx/mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for BackendX API — workflow-oriented tools for AI agents",
   "type": "module",
   "main": "dist/index.js",