zeropoint-mcp

ZEROPOINT의 portable MCP client. Claude·Codex·MCP stdio 하네스에서 Slack 작업과 native Focus Contract·Context Packet·Decision·WorkSession·Execution Clock을 같은 로그인 신원으로 연결한다.

구조

로컬 stdio MCP → Bearer session → Vercel backend → 두 adapter.

• /api/mcp/*: 기존 Slack Lists 운영 경로(v0, 계속 보존)

• /api/mcp/v2/*: PostgreSQL native Focus/Context/Session 경로(N3 PoC)

• /api/mcp/work-brief: Rec/DD/Native 식별자를 카드·최신 Slack thread·이미지·Native Artifact/Handoff로 합치는 전환 bridge

• 신원은 Slack "Sign in with Slack"(OIDC) 로 확증(위조 불가).

• 비밀(client_secret·봇토큰)은 Vercel 서버에만. 로컬엔 자체 세션 토큰만 캐시(~/.config/zeropoint-mcp/token.json, 0600).

• 첫 도구 호출 시 브라우저가 열려 Slack 로그인 1회 → 30일 세션 토큰.

현재 릴리스 경계

현재 공개 후보는 **[email protected]**이다. get_dd_capabilities·Work Brief·private image content·Native Context/Capsule·WorkSession·Mailbox·완료 후 다음 작업 제안과, 에이전트가 준비한 Markdown을 proposal-only 실행안으로 고정하는 draft_execution_plan을 포함한다. 다만 패키지 버전만으로 backend 기능을 추정하지 않고, 실제 착수 전에는 항상 get_dd_capabilities를 호출한다. 팀 기본 권장 버전은 canary와 rollback 확인 뒤에 별도로 승격한다.

dnd-task-mcp는 이전 패키지명으로 더 이상 설치 기준이 아니다. 기존 설정은 backend가 새 이름 전환 안내를 반환하고, 새 패키지는 기존 ~/.config/dnd-task-mcp/token.json을 새 캐시 경로로 한 번 자동 승계한다. 따라서 보통은 Slack 재로그인이 필요 없다.

MCP는 자기 package version을 capability 요청에 포함한다. backend는 최소 호환 버전과 권장 공개 버전을 반환하며, 업데이트가 있으면 연결 시 logging notification과 첫 ZEROPOINT 도구 응답에 한 번 표시한다. 호스트가 logging을 숨겨도 첫 도구 응답이 폴백이 된다. check_dd_updates는 캐시를 무시하고 즉시 다시 확인한다. MCP가 닫혀 있는 Claude/Codex를 깨우는 push는 아니며, 실행 중인 프로세스를 자동 교체하거나 shell 명령을 자동 실행하지 않는다.

도구 가용성

npm 공개 후보 0.3.0

| 도구 | 설명 | | --- | --- | | list_my_tasks | legacy Slack List에서 내 관련자 미완료 카드 조회(진행중 우선·우선순위 순) | | recommend_tasks | 대기중 카드 우선순위 추천(limit 선택) | | start_task | legacy Slack List 대기중→진행중 + 나를 관련자로 추가. Native DRI/R&R 배정은 변경하지 않음; 남이 진행중이면 taken(안 뺏음) | | create_card | 카드 생성(기본 대기중·미정·오늘, 생성자를 관련자로) | | login | 재로그인 강제(토큰 만료·워크스페이스 변경 시) |

기본 흐름은 check_dd_updates → get_dd_capabilities → get_work_brief → 사람의 선택 → start_task 또는 Context 수락·Session 시작이다. Native Task에서는 get_task_context가 반환하는 DRI와 PM·Design·FE·BE·QA 역할별 R&R을 먼저 읽는다. Slack 관련자는 진행 공유 대상일 뿐 실행 배정이나 Focus 대상으로 해석하지 않는다. source membership을 증명할 수 없거나 capability가 없으면 카드 댓글·이미지를 읽었다고 전제해 작업하지 않는다.

native Work Loop 0.3.0

공개 후보 0.3.0은 위 legacy Slack 작업 도구에 아래 native 도구를 더한다.

| 도구 | 설명 | | --- | --- | | handoff_task | 합의된 새 담당자로 관련자를 교체하고 상태는 유지 | | reject_task | QA 반려를 명시적으로 기록하며 완료 카드를 진행중으로 되돌림 | | get_dd_capabilities | 현재 배포 백엔드가 실제 제공하는 protocol/capability 확인 | | check_dd_updates | 현재 package와 backend의 최소 호환·권장 공개 버전을 재확인하고 안전한 업데이트·재시작 절차 표시 | | get_work_brief | Rec·DD 티켓·Native UUID의 카드·최신 댓글·이미지·Feature·accepted Artifact/Handoff 통합 조회 | | get_focus_contract | 내 WIP 약속·interrupt budget·승인 대기 Decision 조회 | | get_task_context | Task의 DRI·PM/Design/FE/BE/QA R&R·Focus·Decision·Session·Mailbox·Artifact/Handoff 기준선과 content hash 조회 | | get_resume_capsule | 복귀·인계·AI 교체 시 목표·마지막 결정/checkpoint·근거·막힘·변경·다음 도구 순서를 출처와 hash로 복원 | | draft_execution_plan | 에이전트가 준비한 구조화 Markdown을 immutable 실행 제안으로 고정. Task·DRI·R&R·Focus·Slack은 변경하지 않으며, 사람이 Planning 화면에서 검토·선택·적용해야 함 | | accept_task_context | AI가 읽은 정확한 Context Packet hash를 명시 수락 | | propose_focus_change | 밀려날 약속을 계산하되 적용하지 않고 Decision만 생성 | | resolve_focus_decision | 사람의 명시 판단 뒤 승인/거절; 승인 시 Focus와 Agent Mailbox 원자 갱신 | | open_work_session | 수락된 Context와 현재 Focus 약속을 확인한 뒤 Execution Clock 시작 | | checkpoint_work_session | 미확인 Mailbox가 없고 Task가 Focus에 있을 때 완료·다음 행동·Evidence 공유 | | pull_agent_mailbox | 현재 세션에 도착한 Focus·Decision·Evidence 변경 지시를 cursor 순서로 수신 | | ack_agent_message | 메시지의 nextAction을 처리한 뒤 ack-only 확인; 반복 호출 안전 | | pause_work_session / resume_work_session | 비작업 구간 분리; resume은 Mailbox 처리와 현재 Focus를 다시 검증 | | close_work_session | 결과와 PR/commit/test Evidence를 봉인하고 실행 구간 종료 | | complete_work_and_get_next | 완료 세션을 Evidence와 함께 닫고 최신 Focus에서 다음 후보를 다시 계산. 자동 착수는 금지하고 사람에게 확인 |

권장 agent 순서는 check_dd_updates → get_dd_capabilities → get_work_brief → get_resume_capsule → Capsule nextActions 순서대로 처리 → checkpoint/pause/resume → complete_work_and_get_next이다. 처음 착수할 때도 Capsule은 Feature의 승인 개정·Focus·Decision·Artifact/Handoff·Mailbox를 정확한 hash로 묶고, 복귀 때는 마지막 유효 checkpoint와 검증 근거를 더해 준다. Native가 아직 연결되지 않은 카드는 Work Brief를 읽은 뒤 start_task로 legacy 착수한다. pendingMailbox > 0이면 pull_agent_mailbox → payload.nextAction 처리 → ack_agent_message → get_resume_capsule → accept_task_context 순서를 지킨다. 미확인 메시지를 무시한 checkpoint/resume과 Focus 밖 open/checkpoint/resume은 서버가 409로 차단한다. 긴급 작업은 바로 착수하지 않고 propose_focus_change로 사람의 Decision을 먼저 받는다. Context 수락 해시는 Task·승인된 Feature revision·Focus·Decision·미확인 Mailbox·최신/accepted ArtifactVersion·Handoff review 기준선에 반응한다. 에이전트 자신의 checkpoint는 방금 수락한 맥락을 stale로 만들지 않는다. 완료 뒤 반환된 다음 후보는 추천일 뿐이며 사람의 확인 없이는 자동 착수하지 않는다.

같은 작업자가 Claude에서 Codex로 바꾸면 자기 WorkSession·Mailbox·checkpoint를 그대로 이어받는다. 다른 팀원이 인수할 때는 이전 사람의 개인 Mailbox나 raw 대화를 복제하지 않고 task-level checkpoint·검증된 milestone·accepted Artifact/Handoff만 공유한다. 이전 세션이 아직 active라면 Capsule이 먼저 handoff/close와 재조회를 지시하고, 종료된 뒤 새 담당자가 현재 Context hash를 수락해 자신의 WorkSession을 연다. 이 복귀 투영은 기존 원장을 읽으므로 별도 대화 저장소를 만들지 않는다.

Slack 이미지는 private URL을 모델에 노출하지 않는다. 신규 캡처도 공유 카드 비고에는 source/thread marker와 permalink만 저장하고 raw 원문 발췌·private 첨부 URL을 복사하지 않는다. Work Brief는 기존 카드에 남아 있는 legacy 원문:·첨부: 줄을 응답 전에 제거한다. 단, 원본 Slack List 비고의 과거 줄은 별도 backfill 전까지 남을 수 있다. Work Brief 서버가 카드/스레드 소속·요청 사용자의 Slack conversation 멤버십(파일 소유자는 직접 허용)·MIME·4MB 제한을 검증한 뒤 로컬 MCP가 최대 3장을 image content로 전달한다. 멤버십을 증명할 scope가 없으면 fail-closed한다. 최신 Slack thread는 요청마다 Slack ACL로 다시 읽고, Native에는 원문을 workspace 공개로 복제하지 않은 채 viewer별 private slack-thread ArtifactVersion의 hash·개수 신호만 저장해 그 사용자의 Context hash와 활성 Agent Mailbox에 반영한다. Task에 다른 작업자의 세션이 함께 있어도 session·pending mailbox 조회와 source 변경 알림은 요청 actor가 owner/agent인 세션으로만 격리한다.

현재 연결된 Slack 테스트 복제본 smoke에서 Rec·DD 티켓·Native UUID는 같은 Task로 수렴했고, Feature Artifact 4개와 Handoff Pack 2개가 함께 반환됐다. 요청자가 소유한 private-channel 카드 첨부 이미지 3/3은 인증된 경로로 실제 바이트까지 읽혔고 관계없는 file id는 403이었다. 다른 사용자는 원본 conversation membership을 증명해야 한다. 반면 복제본 127개 카드 중 Native 매핑은 3개, source thread 표식은 2개뿐이며 표식 2개는 현재 읽히지 않았다. 프로덕션 List는 이 수치의 검증 대상이 아니다. 이는 Work Brief 기능 자체와 별개인 production 재검증·기존 카드 backfill·source 권한/보존 점검 과제다.

선행: Slack 앱 설정 (운영자 1회)

1. Slack 앱 → OAuth & Permissions → Redirect URLs에 정확히 추가: http://localhost:3117/callback (다른 포트를 쓰려면 그 포트로 등록하고 MCP_CALLBACK_PORT를 맞춘다. Slack은 가변 포트를 허용하지 않음)
2. Sign in with Slack 활성화 — 스코프 openid, profile.
3. client_id(공개)·client_secret(비밀)·워크스페이스 team_id 확보.
4. Bot scopes에 기존 history 권한과 함께 channels:read, groups:read, im:read, mpim:read를 추가하고 앱을 재설치한다. Work Brief가 bot의 넓은 읽기 권한을 요청 사용자에게 그대로 전가하지 않고 source conversation membership을 대조하기 위해 필요하다.
5. Vercel 환경변수 설정: SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_TEAM_ID, MCP_SESSION_SECRET(랜덤 32B+), 기존 SLACK_BOT_TOKEN/SLACK_LIST_ID.
6. native v2 사용 시 DATABASE_URL, DD_WORKSPACE_ID, DD_PROJECT_ID를 설정하고 Slack user ID를 native actor에 매핑한다. 모든 v2 요청은 서명뿐 아니라 SLACK_TEAM_ID 일치도 서버에서 다시 검증한다. 저장소 루트의 pnpm db:bootstrap-poc -- --config db/poc.example.json을 사용할 수 있다.

설치·설정 (팀원)

한 줄이면 끝. 팀 공통값(API URL·client_id·team_id)은 내장돼 있어 env 설정이 필요 없다. MCP 표준이라 Claude Code·Codex 등 어느 클라이언트든 동일하게 동작한다.

웹에서는 ZEROPOINT의 설정 → AI 에이전트에서 환경별 명령, 연결 검증 문장, AGENTS.md·CLAUDE.md 작업 규칙을 한 번에 받을 수 있다. Codex/Claude 외의 MCP stdio 하네스도 같은 JSON 설정과 Work Loop를 사용한다. 하네스나 skill이 도구 순서를 자동화하더라도 사람의 Focus 결정, Context hash 수락, Mailbox ack, Evidence 요구를 우회하면 안 된다.

Claude Code

claude mcp add zeropoint -- npx -y [email protected]

Codex CLI

codex mcp add zeropoint -- npx -y [email protected]

또는 ~/.codex/config.toml:

[mcp_servers.zeropoint]
command = "npx"
args = ["-y", "[email protected]"]

위 명령은 현재 공개 버전을 재현 가능하게 고정한다. 팀 공유 문서에는 무버전 설치 대신 명시 버전을 사용한다.

첫 도구 호출 시 브라우저 Slack 로그인 1회 → 30일 자동. 그게 전부다. 토큰 캐시(~/.config/zeropoint-mcp/token.json)는 클라이언트 간 공유 — 한 번 로그인하면 같은 노트북의 다른 클라이언트도 재로그인 없이 쓴다.

0.3.0은 capability handshake에서 실제 MCP host 이름·버전·transport를 ZEROPOINT에 알린다. 서버는 이를 개인 설정의 최근 연결 확인에 표시하지만, 대화 내용·로컬 파일·prompt를 수집하지 않는다.

고급(다른 배포/워크스페이스로 덮어쓸 때만): MCP_API_BASE·SLACK_CLIENT_ID·SLACK_TEAM_ID·MCP_CALLBACK_PORT env로 override 가능.

업데이트 안내를 받았을 때

기존 dnd-task-mcp를 사용 중이거나 새 공개 버전 안내를 받았다면:

1. AI에게 check_dd_updates를 실행해 달라고 하거나 직접 “DD MCP 업데이트 확인해줘”라고 요청한다.
2. npx 등록 사용자라면 MCP 설정의 서버 명령을 응답의 npx -y zeropoint-mcp@버전으로 맞춘다. 전역 설치 사용자만 npm install -g zeropoint-mcp@버전을 사용한다.
3. Claude/Codex를 재시작해 기존 MCP 프로세스를 종료한다.
4. check_dd_updates를 다시 실행해 up-to-date를 확인한다.

업데이트 알림은 권장과 필수 호환을 구분하지만 현재 enforcement는 notify-only다. 업데이트 확인 API가 실패하거나 구버전 backend가 이 계약을 아직 제공하지 않아도 기존 작업 도구는 중단하지 않는다.

• MCP_API_BASE: ZEROPOINT API URL (선택, 기본 https://zeropoint.lazysaturday.online)
• SLACK_CLIENT_ID: Slack 앱 client_id — 공개값이라 로컬에 둬도 안전 (필수)
• SLACK_TEAM_ID: 로그인 워크스페이스 힌트 (선택)
• MCP_CALLBACK_PORT: 콜백 포트, 기본 3117 (Slack에 등록한 값과 일치)

첫 도구 호출 시 브라우저 Slack 로그인 → 이후 30일간 자동.

배포 (운영자, npm publish)

cd mcp
npm login                 # npm 계정 인증 1회
# 버전 올리고 배포 (prepare가 dist 빌드 → files의 dist/README만 tarball에 포함)
npm version patch         # 0.1.0 → 0.1.1 등
pnpm publish --access public --no-git-checks

코드에 비밀 없음(client_id는 공개값, 봇토큰·secret은 Vercel에만)이라 공개 배포 안전. 배포는 backend 호환 route(정책은 기존 stable 유지) → candidate canary → npm publish → DD_MCP_RECOMMENDED_CLIENT_VERSION 승격 → 사용자 알림 순서다. 최소 호환 버전은 실제 grace period와 rollback 확인 뒤에만 올린다. 팀원의 무버전 npx도 재시작 때 최신본을 찾지만, 안내에는 재현 가능한 명시 버전 명령을 제공한다.

개발

pnpm test:run    # 단위 테스트
pnpm typecheck
pnpm build       # dist/ 빌드