dory-to-dory-mcp 0.1.5 → 0.3.0

package/README.md

@@ -2,14 +2,26 @@
 
 로컬 또는 외부에서 직접 접근할 수 없는 Agent를 dory-to-dory Core에 연결하는 독립 MCP 서버입니다. MCP 호스트가 이 프로세스를 자식 프로세스로 실행하고 JSON-RPC를 `stdio`로 주고받습니다. Agent가 inbound 서버를 열 필요는 없습니다.
 
-## MVP 범위
+## v2 범위
 
 - Core 연결 및 자연어 정책 조회
-- 사용자 검색과 수락된 친구 조회·검색·삭제
-- coordination 생성·조회·취소
-- lease/fencing token이 있는 pending item claim, 구조화된 사용자 확인, 처리 결과 제출
+- 사용자 검색과 수락된 친구 조회·검색. 친구 추가·삭제는 Dashboard에서만 지원
+- 1:N coordination 생성·조회·취소와 host/client 역할별 카드
+- 생성 전 Skill 검색을 최소 1회 시도하고, 적합한 Skill 또는 goal을 바탕으로 plan 생성·결정적 skill code 실행
+- lease/fencing token이 있는 work claim, 사용자 확인, host 갱신과 client 응답 제출
+- 참여자별 nullable session 연결과 revision 기반 명시적 이동·해제
 - Core API key 기반 인증
-- MCP Tools 15개 제공 (`d2d_get_usage_guide`, `d2d_search_friends`, `d2d_check_actionable_items`, `d2d_submit_user_response` 포함)
+- MCP Tools 21개 제공
+
+버전 `0.3.0`은 검색 증빙 발급 API `POST /v2/agent/skill-searches`를 지원하는 Core `/v2` 계약이 필요합니다. 호환 Core를 먼저 적용하고 정확한 MCP 버전을 고정해 설치하십시오. npm 게시 전 검증이나 사내 배포에는 로컬 빌드 또는 tarball을 사용할 수 있습니다. 구형 `/v1` 쓰기를 새 계약으로 자동 변환하지 않으며 진행 중인 구형 작업에는 기존 MCP 버전을 사용합니다.
+
+### 카드와 세션 도구
+
+`d2d_create_coordination`은 `client_handles`, `goal`, `skill_search_id`를 받습니다. `goal_type`은 제거했습니다. 매 새 coordination 생성 전에 `d2d_search_coordination_skills`를 동일한 goal로 최소 한 번 정상 완료해야 합니다. 검색 도구는 `POST /v2/agent/skill-searches`로 증빙을 발급받으며 검색 입력은 `goal`(필수), `query`(최대 200자, 기본 빈 문자열), `operation_id`(선택)입니다. 반환된 `skill_search_id`를 생성에 전달합니다. 관련 후보는 `d2d_get_coordination_skill`로 조건·계획 템플릿·정확한 버전을 확인한 뒤 plan을 작성합니다. 적합한 후보가 없으면 skill 없이 직접 계획하며, Core는 실제 검색 완료 증빙의 호출자·goal·만료·일회 사용을 검증합니다. 결과가 0건이거나 LLM이 유효한 Skill이 없다고 판단하면 `skill=null`로 생성할 수 있습니다. 검색 결과나 선택 판단은 검토하지 않습니다. 검색 오류는 최초 1회와 최대 3회 재시도, 총 4회 HTTP 요청으로 제한하고 `D2D_MAX_RETRIES`와 중첩하지 않습니다. HTTP 408을 포함한 검색 오류를 재시도하되, Core가 명시한 `skill_search_exhausted`·`idempotency_conflict`는 즉시 종료합니다. 동일 `operation_id`와 goal/query의 실행 중·성공·실패 결과는 MCP 프로세스에서 공유하므로 중복·동시 도구 호출로 HTTP 재시도 예산을 초기화할 수 없습니다. 같은 키에 다른 입력은 충돌로 거부합니다. Core는 프로세스 재시작 뒤에도 실제 검색 횟수를 DB에서 제한하지만 Core에 도달하지 않은 전송 오류 횟수는 MCP 프로세스 안에서만 유지됩니다. 실패하면 생성도 종료하며 새 `operation_id`로 예산을 초기화하지 않습니다. 검색 결과의 `operation_id`를 보존하고, 생성은 생략 시 `skill_search_id`를 idempotency key로 사용하므로 불명확한 응답에는 동일 payload와 key를 재사용합니다. `d2d_run_skill_code`는 skill에 등록된 코드와 입력 스키마를 사용합니다.
+
+`d2d_claim_next_item` 결과의 `delivery.work.claim_id`와 카드 revision을 사용합니다. claim 응답에는 skill 본문을 포함하지 않습니다. 필요한 경우 `d2d_get_coordination`으로 저장된 skill을 명시적으로 조회합니다. client는 `d2d_submit_item_result`의 `to_host`만 제출하고 다른 카드 필드는 거부됩니다. host는 `d2d_update_host_card`로 plan, slots, 상태 및 다음 요청을 결정합니다. 회의 commit은 같은 proposal에 전원 준비가 확인된 뒤 host가 결정하며 최종 실행 receipt를 확인해야 완료할 수 있습니다.
+
+생성·claim·결과·host 갱신·사용자 답변에는 현재 `session_id`를 전달할 수 있습니다. 외부 Agent는 `null` 또는 생략을 사용할 수 있으며 기존 연결은 유지됩니다. 명시적 이동·해제는 `d2d_bind_session`에 `expected_session_revision`과 문자열 또는 `null`을 전달합니다. 각 Agent는 자기 연결만 접근합니다. 사용자 답변은 `interaction_id`, `answer`, 승인 질문인 경우 명시적 `decision`으로 제출합니다.
 
 MCP Resources, Prompts, 알림 push, polling daemon, FCM, Runtime Adapter는 포함하지 않습니다. 사용자가 처리할 작업을 묻거나 이메일·Telegram 알림 후 Agent를 열면 `d2d_check_actionable_items`로 사용자 답변 대기 항목을 먼저 확인합니다. Background Watcher는 SSE wake-up을 받은 뒤 `d2d_claim_next_item`으로 pending item만 처리합니다. 최종 도구 호출 여부는 MCP 호스트의 Agent 모델이 결정합니다.
 
@@ -21,12 +33,14 @@ Agent가 dory-to-dory의 목적, Watcher 설치와 device pairing, SSE 처리,
 - dory-to-dory 계정. 권장 Watcher setup이 device-code pairing으로 Agent API key를 발급하고 안전하게 저장합니다.
 - `stdio` MCP 서버를 실행할 수 있는 Agent/MCP 호스트
 
-## 권장 사용자 설치: Watcher
+## Watcher를 통한 설치
+
+Watcher `0.2.0`에는 MCP `0.2.0`이 고정되어 있습니다. 검색 증빙이 필수인 Core에서 새 coordination을 생성하려면 MCP `0.3.0`을 포함한 Watcher `0.3.0` 릴리스가 필요합니다. Watcher는 별도 게시 단위입니다. 해당 버전이 registry에 게시되기 전에는 검증된 Dory 앱 번들 또는 아래의 MCP 직접 등록 방식으로 새 MCP를 실행합니다. 기존 Watcher 설치의 의존성은 자동으로 바뀌지 않습니다.
 
-일반 사용자는 Watcher를 설치하고 대화형 setup을 실행합니다. setup이 Codex CLI, Claude Code, Gemini CLI를 탐색하고 브라우저 device pairing, credential 파일 저장, MCP 등록과 연결 검사를 안내합니다. 호환되는 정확한 MCP 버전이 Watcher 의존성으로 함께 설치되므로 MCP를 별도로 설치할 필요가 없습니다.
+아래는 Watcher `0.3.0` 게시 후 사용할 설치 예시입니다. setup이 Codex CLI, Claude Code, Gemini CLI를 탐색하고 브라우저 device pairing, credential 파일 저장, MCP 등록과 연결 검사를 안내합니다.
 
 ```sh
-npm install --global dory-to-dory-watcher@latest
+npm install --global dory-to-dory-watcher@0.3.0
 dory-watcher setup
 ```
 
@@ -36,20 +50,20 @@ Watcher는 Agent별로 지원되는 비대화식 승인과 격리 방식을 사
 
 `dory-watcher doctor`는 Core와 Agent 로그인뿐 아니라 실제 무인 실행 모드도 검사합니다. Codex와 macOS Gemini에서는 빈 임시 작업공간에서 도구를 사용하지 않는 짧은 모델 진단을 한 번 실행하므로 소량의 사용량 또는 API 요금이 발생할 수 있지만, dory-to-dory item을 claim하거나 처리하지 않습니다.
 
-## 친구 초대 관리
+## 친구 추가·삭제 및 초대 관리
 
 친구 초대 생성, 확인, 수락, 거절과 취소는 MCP 도구가 아니라 [dory-to-dory 친구 관리 화면](https://dory-to-dory.dnotitia.ai/friends)에서 사용자가 직접 처리합니다. 초대가 도착하면 Core는 사용자가 활성화한 이메일과 Telegram으로 일반 알림을 보냅니다. 반복 초대에는 발신자 제한과 수신자별 알림 cooldown이 적용되며, 알림이 억제되어도 초대는 Dashboard에 표시됩니다. 상대가 초대를 수락해 친구 관계가 된 뒤에만 Coordination을 생성할 수 있습니다.
 
 ## 고급 사용자: MCP 직접 추가
 
-패키지가 npm에 게시된 뒤 MCP 호스트 설정에 다음을 추가합니다.
+호환 Core와 MCP 패키지의 게시 여부를 확인한 뒤 호스트 설정에 정확한 버전을 지정합니다.
 
 ```json
 {
   "mcpServers": {
     "dory-to-dory": {
       "command": "npx",
-      "args": ["-y", "dory-to-dory-mcp@0.1.5"],
+      "args": ["-y", "dory-to-dory-mcp@0.3.0"],
       "env": {
         "D2D_API_KEY": "d2d_live_replace_me"
       }
@@ -60,9 +74,9 @@ Watcher는 Agent별로 지원되는 비대화식 승인과 격리 방식을 사
 
 호스트마다 설정 파일 위치와 최상위 키 이름은 다를 수 있지만 핵심은 같습니다. 호스트가 `npx`를 실행하고 환경 변수로 API key를 넘깁니다. Core URL은 기본적으로 `https://dory-to-dory.dnotitia.ai`를 사용하며, 다른 Core에 연결할 때만 `D2D_CORE_URL`로 재정의합니다. 패키지 버전을 고정하면 예기치 않은 자동 업데이트를 피할 수 있습니다.
 
-`pnpm dlx`를 쓰는 호스트라면 command를 `pnpm`, args를 `["dlx", "dory-to-dory-mcp@0.1.5"]`로 바꿉니다.
+`pnpm dlx`를 쓰는 호스트라면 command를 `pnpm`, args를 `["dlx", "dory-to-dory-mcp@0.3.0"]`로 바꿉니다.
 
-## 게시 전 로컬 설치
+## 로컬 소스 또는 tarball 설치
 
 ```sh
 pnpm install
@@ -90,7 +104,7 @@ MCP 호스트 설정:
 또는 `pnpm pack`으로 생성한 `.tgz` 파일을 다른 장비에 전달해 설치할 수 있습니다.
 
 ```sh
-npm install --global ./dory-to-dory-mcp-0.1.5.tgz
+npm install --global ./dory-to-dory-mcp-0.3.0.tgz
 ```
 
 이후 MCP command를 `d2d-mcp`로 설정합니다.
@@ -103,7 +117,7 @@ npm install --global ./dory-to-dory-mcp-0.1.5.tgz
 | `D2D_API_KEY` | 조건부 | - | Core가 발급한 Agent API key. `D2D_API_KEY_FILE`과 동시에 설정하지 않음 |
 | `D2D_API_KEY_FILE` | 조건부 | - | Agent API key 한 줄을 저장한 credential 파일. `D2D_API_KEY` 대신 사용 |
 | `D2D_REQUEST_TIMEOUT_SECONDS` | 아니요 | `15` | HTTP 요청 timeout |
-| `D2D_MAX_RETRIES` | 아니요 | `2` | GET 및 idempotent 쓰기 요청의 추가 재시도 횟수 |
+| `D2D_MAX_RETRIES` | 아니요 | `2` | GET 및 idempotent 쓰기 요청의 추가 재시도 횟수. 검색 증빙 요청은 별도 최대 3회로 고정 |
 
 API key는 tool input이나 stdout에 노출하지 않습니다. MCP 설정 파일의 권한을 제한하고, 유출 가능성이 있으면 Core 대시보드에서 즉시 키를 재발급하십시오.