nexus-mcp

Nexus/TaskBridge PM 시스템을 Claude Code에 노출하는 MCP 서버 — 에이전트가 사람이 수동으로 상태를 중계하는 대신 작업을 직접 읽고 업데이트할 수 있게 해줍니다. claude-templates의 두 스킬과 함께 사용됩니다 — nexus-plan-work(PM/BA/팀 리드용, 작성) 및 nexus-pick-up-task(개발자용, 소비).

PM 시스템의 공개 /api/v1/* API와 통신합니다 — 공식 확장을 위해 예약된 nexus-vscode의 내부 엔드포인트가 아닙니다. 이유와 전체 빌드 내역은 DEVLOG.md를 참조하세요.

설정(1회, 사람별)

순서대로 4단계 — 로그인만으로는 Claude Code가 nexus-mcp의 존재를 인식하지 못합니다. 그건 별도의 단계입니다(아래 2단계). 이 목록 어디에도 git clone은 필요 없습니다 — npx가 GitHub에서 직접 가져와 빌드하고 실행합니다.

1. 로그인 — Developer Portal을 통해 토큰을 생성하고 OS 키체인(@napi-rs/keyring — 절대 파일에 저장하지 않음)에 저장합니다:

export NEXUS_API_URL=http://27.254.62.17:8090
npx -y -p github:tanakorncode/nexus-mcp nexus-mcp-login

$NEXUS_API_URL/developer → 앱 생성 → 스코프 tasks:read tasks:write projects:read members:read sprints:read 부여 → 토큰 생성 과정을 안내한 다음, 해당 토큰과 계정 이메일을 붙여넣도록 요청합니다.

2. Claude Code에 등록 — 하나를 선택하세요(둘 다 필요하진 않지만 공존할 수 있습니다):

• 자신에게, 모든 저장소에, 1회(claude CLI 필요 — 먼저 npm install -g @anthropic-ai/claude-code 실행):

  claude mcp add nexus-mcp -s user -e NEXUS_API_URL=http://27.254.62.17:8090 -- npx -y github:tanakorncode/nexus-mcp

  이후에는 어디에도 .mcp.json이 필요 없습니다.

• 또는, 여는 저장소 루트에 이미 .mcp.json이 커밋되어 있다면(예: pea-thailand-backoffice-be) — 할 일이 없습니다. Claude Code가 해당 저장소를 열 때 자동으로 인식합니다. 위 단계를 수행하지 않은 경우에만 관련됩니다.

3. Claude Code 다시 로드(새 창 / 세션 재시작) — 어느 쪽이든 필수입니다. 실행 중인 세션은 새로 등록된 서버를 자동으로 인식하지 못합니다. 첫 연결은 더 느립니다(npx가 새로 가져와 빌드). 이후에는 캐시됩니다. 일회성 신뢰 프롬프트를 승인하세요.

4. 확인 — Claude에게 whoami 호출을 요청하세요. 이름이 확인되면 4단계 모두 성공한 것입니다.

스킬도 설치하세요(사람별 1회 — 자세한 내용은 claude-templates/README.md 참조):

mkdir -p ~/.claude/skills
git clone --depth 1 https://github.com/tanakorncode/claude-templates /tmp/claude-templates
cp -r /tmp/claude-templates/skills/nexus-pick-up-task ~/.claude/skills/
cp -r /tmp/claude-templates/skills/nexus-plan-work ~/.claude/skills/

nexus-mcp 자체 개발

이 저장소의 코드를 사용만 하는 게 아니라 변경하는 경우, 편집 내용이 재배포 없이 적용되도록 대신 클론하세요:

git clone https://github.com/tanakorncode/nexus-mcp
cd nexus-mcp
npm install
npm run build
npm link          # makes the `nexus-mcp` command available anywhere on this machine

반복 작업 중에는 .mcp.json을 npx 형식 대신 "command": "nexus-mcp"(args 없음)로 지정하세요 — 변경 사항을 적용하려면 재빌드(npm run build)하고 Claude Code 창을 다시 로드하세요. 그렇지 않으면 MCP 서버 프로세스가 이전 코드를 메모리에 보관합니다.

Related MCP server: project-manager

두 스킬, 그리고 각각이 적용되는 시점

• nexus-plan-work — 기능을 epic/story/task로 분해. 작업이 존재하기 전에 사용. 여기서 중요한 규율: 저장소에 걸친 기능당 하나의 story, 그 아래 저장소당 하나의 task, 모든 task에 repositoryId 설정(가장 자주 누락되는 필드이자, 나중에 놓치면 복구할 수 없는 필드).

• nexus-pick-up-task — 작업 찾기, 이해, 실행, PR 및 상태 업데이트로 끝맺음. 작업이 존재하고 누군가(사람 또는 예약된 확인)가 실행할 준비가 되면 사용.

전체 단계별 지침은 스킬 파일 자체를 읽으세요 — 이 README는 중복하지 않습니다.

도구

신원 및 탐색

작업 읽기

작성(nexus-plan-work 참조)

핸드오프

선택 사항: 예약된 작업 확인(알림 전용)

scripts/check-my-tasks.sh는 헤드리스(claude -p)로 실행되며 타이머에 따라 list_my_tasks를 확인하고 준비된 항목이 있으면 macOS 알림을 발생시킵니다 — 자체적으로 코드 작성을 시작하지는 않습니다(--allowedTools는 읽기 전용 도구와 Bash(osascript*)로만 잠겨 있으므로, 원하더라도 구조적으로 파일을 편집할 수 없습니다).

launchctl load ~/Library/LaunchAgents/com.pea-thailand.nexus-task-check.plist   # enable, runs every 2h
launchctl unload ~/Library/LaunchAgents/com.pea-thailand.nexus-task-check.plist # disable
tail -f ~/Library/Logs/nexus-task-check.log                                     # watch it run
./scripts/check-my-tasks.sh                                                     # run once, right now

plist 자체는 이 저장소에 없습니다(사람별 로컬 머신 구성) — DEVLOG.md의 2026-08-22 항목에 있는 것을 복사하거나, 설정한 사람에게 물어보세요.

이것은 확인만 합니다. 알림을 받은 후 사람이 여전히 Claude Code를 열고 "go"라고 말해야 합니다 — 그 이유가 궁금하다면 DEVLOG.md를 참조하세요.

알려진 제한 사항

• 댓글 지원 없음, 커밋 연결 없음 — 해당 라우트는 확장 전용 내부 API에만 존재하며 /api/v1/*에는 없습니다. 추가하려면 새 pm-system 라우트가 필요합니다.

• API를 통한 epic 생성 없음 — epic은 드물게 생성되며 리드가 계획합니다. 제품 UI를 사용하세요.

• API를 통한 첨부/임베드 업로드 없음(읽기는 작동 — get_task가 둘 다 반환) — Figma 링크/스크린샷은 제품 UI를 통해 첨부하세요.

• 저장소 범위, story 범위, 레이블 필터 쿼리는 누군가 task에 repositoryId/storyId/labelIds를 실제로 설정한 경우에만 결과를 반환합니다 — 자동으로 추론되는 것은 없습니다.