feat(contact): NAVER WORKS 연락처 API 지원 추가 (CLI + MCP)

[hhgyu]

무엇을

개인 연락처(명함첩) API를 CLI와 MCP 도구로 노출합니다.

• CLI: nworks contact list / get / create / update / delete / list-tags
• MCP: nworks_contact_list / _get / _create / _update / _delete / _list_tags (26 → 32 tools)
• src/auth/scopes.ts에 contact / contact.read 추가 + contact → contact.read 의존성 등록

scope 프리셋을 함께 건드린 이유

프리셋에 넣지 않으면 --preset all로 로그인해도 연락처 도구가 전부 403(has not permission api scope)이 납니다. 기능이 실제로 동작하려면 필요한 변경입니다.

참고로 검증 중에 겪은 부분입니다. Developer Console 앱에 연락처 권한이 없는 상태로 contact scope를 요청하면 인증 서버가 에러 없이 로그인 페이지로 되돌립니다(콜백 요청 자체가 오지 않음). scope만 빼고 동일 조건으로 로그인하면 성공하는 것으로 원인을 확정했습니다. 문서의 scope 표에 contact / contact.read 행을 추가해 두었습니다.

구현 노트

타입을 실제 응답에 맞췄습니다. 연락처는 이름 하나에 이메일·전화·소속을 여러 개 달 수 있어 API가 배열로 돌려줍니다.

• 이름 필드는 name이 아니라 contactName
• emails[], telephones[], organizations[] 배열, contactTagIds[] 배열
• 단수 필드(email, tel)로 접으면 두 번째 값부터 조용히 사라지므로 배열 그대로 노출합니다

create/update는 payload를 그대로 통과시킵니다. 연락처 스펙이 넓고 자주 바뀌어 zod로 고정하면 API 변경 때마다 도구가 막힙니다. 대신 실호출로 확인한 필수 조건을 도구 설명과 README에 명시했습니다.

• contactName, permission 필수
• permission.accessibleMembers에 최소 1명 필요 (보통 본인, nworks whoami로 확인)
• 빠뜨리면 INVALID_PARAMETER: permission is required. / INSUFFICIENT: You must add at least 1 member.

update / delete에는 destructiveHint를 달아 클라이언트 승인 게이트를 태웁니다.

검증

실제 NAVER WORKS 계정에서 CLI와 MCP 양쪽으로 전체 사이클을 돌렸습니다.

단계	결과
list / list-tags	연락처 조회 + 커서 페이지네이션 정상, 태그 0건
create	contactId 발급, 이름·이메일·전화 반영 확인
get	생성 내용 그대로 조회
update	전화번호 010-0000-0000 → 010-1234-5678, 재조회로 반영 확인
delete	삭제 후 재조회 시 [NOT_FOUND] The contact does not exist.

MCP 경로에서도 6개 도구 등록·실호출·destructiveHint 확인했고, 테스트로 만든 연락처는 삭제해 잔존 데이터가 없습니다.

npm run lint / npm test (54 passed) / npm run build 통과.

참고

문서의 도구 개수(32)는 이 PR만 머지되는 기준입니다. 다른 PR이 먼저 들어가면 해당 줄만 리베이스하겠습니다.