@brxce/mcp-server 1.1.16 → 1.1.17

package/skills/brxce-mcp/references/tool-selection.md

@@ -0,0 +1,245 @@
+# BRXCE MCP Tool Selection
+
+89개 툴 전체 분류 + "이럴 때 무엇을 쓰는가" 결정 트리. SKILL.md 본문은 카테고리 표만 보여주고 여기는 결정 트리 + 모든 툴의 한 줄 설명.
+
+---
+
+## 결정 트리: 무엇을 쓸 것인가
+
+### "워크노드를 찾고 싶다"
+
+```
+nodeId/displayId/UUID를 이미 안다?
+├── UUID + 상세 한 건
+│   └── brxce_worknode_detail({ nodeId: <uuid> })
+│
+├── UUID + 단순 11 필드
+│   └── brxce_read_worknodes({ nodeIds: [<uuid>] })   # alias of worknodeIds
+│
+├── displayId (#5723)
+│   └── brxce_worknode_detail({ nodeId: "#5723", workspaceId })
+│
+└── ID 모름 — 검색해야 함
+    │
+    ├── title/description 키워드
+    │   └── brxce_read_worknodes({ workspaceId, query: "..." })
+    │
+    ├── 필터 조합 (status + tags + priority + due date)
+    │   └── brxce_filter_worknodes({ workspaceId, status: [...], tags: [...], ... })
+    │
+    ├── 특정 멤버에게 할당된 것 전부
+    │   └── brxce_worknodes_by_member({ workspaceId, userId })
+    │
+    ├── 특정 태그 붙은 것
+    │   └── brxce_find_worknodes_by_tags({ workspaceId, tagSlugs: ["..."] })
+    │
+    ├── 미할당 / 인박스
+    │   └── brxce_workspace_inbox({ workspaceId })
+    │
+    └── 내가 작업 중인 것 (활성 / 완료 / 긴급)
+        └── brxce_my_work({ workspaceId, mode: "active" })
+```
+
+### "워크노드를 만들거나 바꾸고 싶다"
+
+```
+혼자 vs 여러 개?
+├── 1개 단순 생성/수정 → create_worknodes / update_worknodes (single-element array)
+│
+├── 여러 개 같은 액션 (complete / archive / delete / move / status / priority)
+│   └── brxce_batch_actions({ action, nodeIds, params })
+│
+├── 여러 개에 같은 사람 할당 → brxce_batch_assign({ nodeIds, assigneeId })
+│
+└── 여러 개에 같은 태그 → brxce_batch_assign_tags({ worknodeIds, tagIds })
+```
+
+### "회의 작업"
+
+```
+├── 회의 만들기 → brxce_create_meeting (preview:true → false)
+├── 아젠다 → brxce_add_agenda_item / list_agenda_items / update / delete
+├── 아젠다별 노트 (1.1.16+) → brxce_add_agenda_note / list / update / delete
+├── 회의 노트 (전체) → brxce_add_meeting_note / list / update / delete
+├── 결정 사항 → brxce_add_meeting_decision / list / update / delete
+└── 회의 자체 수정 → brxce_update_meeting({ meetingId, changes: {...}, preview: false })
+```
+
+### "삭제"
+
+```
+├── 일반 삭제 (soft, 복구 가능) → brxce_delete_worknode (single) / batch_actions(delete)
+├── 영구 삭제 (cascade, 복구 불가) → brxce_permanent_delete_worknode({ confirm: true })
+│   ⚠️ owner만 가능, children/criteria/comments/tags 함께 삭제
+└── 아카이브 (status만 변경) → brxce_archive_worknodes / unarchive_worknodes
+```
+
+### "에러 / 디버깅"
+
+```
+├── 캐시 stale 의심 → 노드 다시 read하면 최신 (1.1.16+ 자동 invalidation)
+├── 401 → MCP 토큰 갱신 + 서버 재시작
+├── 410 Gone → invitation/workspace_member 툴은 폐기됨, 사용 중단
+├── 500 + Prisma → backend 버그, GitHub 이슈
+└── "Found 0 WorkNodes" → UUID를 query로 보냈을 가능성, worknodeIds로 변경
+```
+
+---
+
+## 89 툴 전체 분류
+
+### Workspace (8)
+
+| 툴 | 한 줄 설명 |
+|----|----------|
+| `brxce_list_workspaces` | 접근 가능한 전체 워크스페이스 |
+| `brxce_workspace_overview` | 단일 워크스페이스 트리 (depth-first) + stats |
+| `brxce_workspace_statistics` | 통계 (status/priority/type/멤버/dueDate/goal progress) |
+| `brxce_workspace_inbox` | 미할당 / 내 인박스 (캐시 기반) |
+| `brxce_workspace_delta` | sinceVersion 이후 변경 (incremental sync) — `maxChanges` 필수 |
+| `brxce_workspace_ascii_export` | 사람이 읽기 좋은 ASCII 트리 |
+| `brxce_global_overview` | 워크스페이스 통합 요약 (1.1.16+에서 4 layered fix) |
+| `brxce_list_workspace_members` | 멤버 + role + 가입일 |
+
+### WorkNode Read (10)
+
+| 툴 | 한 줄 설명 |
+|----|----------|
+| `brxce_read_worknodes` | query / worknodeIds / nodeIds(alias) / 필터 / 페이지 |
+| `brxce_worknode_detail` | 단일 노드 + AC + children summary |
+| `brxce_worknode_subtree` | 노드 + 모든 descendant tree |
+| `brxce_worknode_history` | CREATE/UPDATE 이벤트 히스토리 |
+| `brxce_worknode_tag_relations` | 노드의 모든 태그 + 누가 언제 |
+| `brxce_get_worknode_tags` | UUID-only로도 동작 (1.1.16+) |
+| `brxce_filter_worknodes` | status + tags(name) + assignee + dueDate + priority + page |
+| `brxce_find_worknodes_by_tags` | tagIds / tagSlugs (string OR array) + matchAll |
+| `brxce_worknodes_by_member` | userId/memberId(alias) + status |
+| `brxce_my_work` | mode: active/completed/urgent/inbox/all |
+
+### WorkNode Write (10)
+
+| 툴 | 한 줄 설명 |
+|----|----------|
+| `brxce_create_worknodes` | 배열, preview 기본 true, task/subtask는 AC 필수 |
+| `brxce_update_worknodes` | updates[{nodeId, changes, cascade?}], preview 기본 true |
+| `brxce_move_worknode` | newParentId 지정 |
+| `brxce_complete_worknode` | status → completed (note는 static) |
+| `brxce_archive_worknodes` | nodeIds[] |
+| `brxce_unarchive_worknodes` | nodeIds[] |
+| `brxce_delete_worknode` | soft, idempotent (1.1.13+) |
+| `brxce_permanent_delete_worknode` | hard + cascade, owner only |
+| `brxce_batch_actions` | action: complete/archive/unarchive/delete/move/update-status/update-priority |
+| `brxce_plan_organize` | 인박스/노이즈 자동 분류 제안 |
+
+### Bulk (3)
+
+| 툴 | 한 줄 설명 |
+|----|----------|
+| `brxce_batch_assign` | nodeIds[] + assigneeId (1.1.15+에서 PATCH로 수정) |
+| `brxce_batch_assign_tags` | worknodeIds[] + tagIds[] |
+| `brxce_create_tags_batch` | tags[] + workspaceId (slug 자동 생성 가능) |
+
+### Tags (10)
+
+| 툴 | 한 줄 설명 |
+|----|----------|
+| `brxce_list_tags` | 카테고리별 그룹 |
+| `brxce_list_tag_categories` | 카테고리 메타 (color, allow_multiple) |
+| `brxce_search_tags` | 키워드 검색 |
+| `brxce_get_tag_stats` | 사용/미사용 + 카테고리 utilization |
+| `brxce_tag_changes` | sinceDate 이후 태그 변경 (uuid cast 1.1.15+) |
+| `brxce_create_tag` | name 필수, slug 자동 생성, categoryId 필수 |
+| `brxce_update_tag` | tagId + 변경 필드 |
+| `brxce_delete_tag` | tagId |
+| `brxce_create_tag_category` | name + slug |
+| `brxce_update_tag_category` / `brxce_delete_tag_category` | 카테고리 관리 |
+
+### Tag–WorkNode (3)
+
+| 툴 | 설명 |
+|----|------|
+| `brxce_add_tags_to_worknode` | worknodeId + tagIds[] |
+| `brxce_remove_tag_from_worknode` | worknodeId + tagId |
+| `brxce_get_worknode_tags` | UUID-only (1.1.16+) |
+
+### Meeting (15)
+
+| 툴 | 설명 |
+|----|------|
+| `brxce_create_meeting` | preview 기본 true, auto-review 포함 |
+| `brxce_list_meetings` | workspaceId 필터 |
+| `brxce_get_meeting` | 단일 회의 + review/agenda/notes/decisions |
+| `brxce_update_meeting` | changes 객체, preview 기본 true |
+| `brxce_delete_meeting` | soft delete |
+| `brxce_add_agenda_item` / `list_agenda_items` / `update_agenda_item` / `delete_agenda_item` | 아젠다 CRUD |
+| `brxce_add_agenda_note` / `list_agenda_notes` / `update_agenda_note` / `delete_agenda_note` | 아젠다별 노트 (1.1.16+) |
+| `brxce_add_meeting_note` / `list_meeting_notes` / `update_meeting_note` / `delete_meeting_note` | 회의 전체 노트 |
+| `brxce_add_meeting_decision` / `list_meeting_decisions` / `update_meeting_decision` / `delete_meeting_decision` | 결정 사항 |
+
+### Comments (4)
+
+| 툴 | 설명 |
+|----|------|
+| `brxce_create_comment` | nodeId + content |
+| `brxce_list_comments` | nodeId |
+| `brxce_update_comment` | commentId + content |
+| `brxce_delete_comment` | commentId |
+
+### Acceptance Criteria (4)
+
+| 툴 | 설명 |
+|----|------|
+| `brxce_create_criteria` | nodeId + title + (type/priority/measurementType) |
+| `brxce_list_criteria` | nodeId |
+| `brxce_update_criteria` | criteriaId + 필드 (isCompleted=true는 evidence 필요) |
+| `brxce_delete_criteria` | criteriaId |
+
+### Notifications (5)
+
+| 툴 | 설명 |
+|----|------|
+| `brxce_list_notifications` | total + unreadCount + meta |
+| `brxce_get_unread_counts` | 빠른 카운트만 |
+| `brxce_mark_notification_read` | 단일 |
+| `brxce_mark_all_notifications_read` | workspaceId 필터 (1.1.16+) |
+| `brxce_delete_notification` | 1.1.16+ |
+
+### Recurring (4)
+
+| 툴 | 설명 |
+|----|------|
+| `brxce_create_recurring_template` | rrule (RFC 5545) + nodeType |
+| `brxce_list_recurring_templates` | workspaceId |
+| `brxce_update_recurring_template` | templateId + 변경 |
+| `brxce_delete_recurring_template` | templateId |
+
+### Attachments (3)
+
+| 툴 | 설명 |
+|----|------|
+| `brxce_list_attachments` | nodeId — 1.1.15+에서 UUID 정상 |
+| `brxce_upload_attachment` | nodeId + filename + contentType + base64Data |
+| `brxce_download_attachment` | nodeId + attachmentId — signed URL |
+
+### Analysis / Reporting (4)
+
+| 툴 | 설명 |
+|----|------|
+| `brxce_daily_report` | 오늘 완료 + 미달성 AC + 산출물 누락 |
+| `brxce_goal_progress` | goalId 없으면 전체 goal 일괄 (1.1.15+) |
+| `brxce_workspace_delta` | 변경 델타 |
+| `brxce_plan_organize` | AI 제안 인박스 정리 |
+
+### Users (1)
+
+| 툴 | 설명 |
+|----|------|
+| `brxce_search_users` | query (email/username/name) |
+
+---
+
+## 폐기된 툴 (사용 금지)
+
+`brxce_create_invitation`, `brxce_list_invitations`, `brxce_accept_invitation`, `brxce_decline_invitation` (모두 #1094로 제거됨), `brxce_add_workspace_member`, `brxce_update_member_role`, `brxce_remove_workspace_member` (#1021로 백엔드 410, #1108로 MCP 제거됨), `brxce_create_bot`, `brxce_list_bots`, `brxce_delete_bot`, `brxce_update_bot`, `brxce_regenerate_bot_key`, `brxce_upload_bot_avatar`, `brxce_delete_bot_avatar` (#1029로 전체 bot 기능 제거).
+
+이 툴들은 1.1.11+ 이후 더 이상 등록되지 않는다.

package/skills/brxce-mcp/references/workflows.md

@@ -0,0 +1,274 @@
+# BRXCE MCP Workflows
+
+실전에서 자주 쓰는 워크플로우 카탈로그. 각 패턴은 step-by-step + 권장 도구 + 안전 체크를 포함한다.
+
+---
+
+## 1. 인박스 트리아지 (Inbox Triage)
+
+새로 들어온 미할당 노드를 빠르게 정리.
+
+```
+1. brxce_workspace_inbox(workspaceId)
+   → myInboxCount, sharedInboxCount 확인
+
+2. 각 노드를 카테고리별로 분류 (head로 5~10건씩)
+   - 즉시 완료 가능 → batch_actions(action: complete, nodeIds: [...])
+   - 다른 부모로 이동 → batch_actions(action: move, nodeIds, params: {newParentId})
+   - 노이즈/중복 → batch_actions(action: archive)
+   - 검토 필요 → 본인 assignee + 우선순위 설정 (update_worknodes)
+
+3. 인박스 재확인 → 0건 또는 진짜 검토 필요한 항목만 남도록
+```
+
+**팁**: 같은 부모로 이동할 그룹은 한 번의 `batch_actions(action: move)` 호출로 묶을 것. 50건씩 페이지네이션으로 처리.
+
+---
+
+## 2. 일일 보고 (Daily Report)
+
+매일 아침 어제 무엇을 끝냈고 오늘 무엇을 할지 정리.
+
+```
+1. brxce_daily_report(workspaceId)
+   → 오늘 완료된 노드, 충족 미달 AC, 산출물 누락 자동 집계
+
+2. brxce_my_work(workspaceId, mode: "active")
+   → 진행 중인 작업 리스트
+
+3. brxce_goal_progress(workspaceId)        # goalId 생략 = 전체 goal 일괄
+   → 목표별 AC 충족률
+
+4. (선택) brxce_workspace_statistics(workspaceId)
+   → memberStats, dueDates 등 매크로 통계
+```
+
+**팁**: `daily_report` 응답의 `unmetCriteria` 항목들이 우선순위 1순위. 거기 노드를 `worknode_detail`로 열어 상세 검토.
+
+---
+
+## 3. GitHub 이슈 → BRXCE 워크노드 동기화
+
+새 GitHub 이슈가 만들어지면 BRXCE에 대응 task 생성.
+
+```
+1. brxce_create_worknodes({
+     worknodes: [{
+       title: "[Bug] 로그인 시 401 — 토큰 갱신 누락 (#123)",
+       nodeType: "task",
+       parentNodeId: <"이슈 처리" 프로젝트 UUID>,
+       priority: "high",
+       acceptance_criteria: [
+         { title: "재로그인 없이 토큰 자동 갱신" },
+         { title: "401 에러 로깅 + 알림" },
+       ],
+     }],
+     preview: false,
+   })
+
+2. brxce_add_tags_to_worknode({
+     worknodeId: <위에서 받은 ID>,
+     tagIds: [<"issue-created" 태그 UUID>],
+     workspaceId,
+   })
+
+3. (선택) brxce_create_comment({
+     nodeId: <ID>,
+     content: "GitHub: https://github.com/foo/bar/issues/123",
+   })
+```
+
+**팁**: 태그 ID는 `brxce_search_tags(query: "issue-created")` 한 번으로 캐시. 반복 호출하지 말 것.
+
+---
+
+## 4. 회의 준비 + 노트 작성
+
+회의 자동 리뷰 → 아젠다 → 노트/결정 → 후속 작업.
+
+```
+1. brxce_create_meeting({
+     workspaceId,
+     title: "Sprint 23 Review",
+     scheduledAt: "2026-04-15T09:00:00Z",
+     preview: true,    # 먼저 dry run으로 review period + 완료 워크노드 확인
+   })
+
+2. (검토 후) 동일 호출에 preview: false
+   → meetingId 받음
+
+3. brxce_add_agenda_item({
+     meetingId,
+     title: "Sprint 23 결과 리뷰",
+   })
+   → itemId 받음
+
+4. 회의 진행 중:
+   brxce_add_agenda_note({ meetingId, itemId, content: "..." })
+   brxce_add_meeting_decision({ meetingId, title: "다음 sprint는 X에 집중" })
+
+5. 회의 종료:
+   brxce_update_meeting({ meetingId, changes: { status: "completed" }, preview: false })
+```
+
+**팁**: agenda note는 1.1.16+에서 fully working. 이전 버전은 add/list/update/delete 모두 404였음.
+
+---
+
+## 5. 멤버별 작업 리뷰 (1:1 준비)
+
+각 팀원의 진행 중인 작업과 미달성 AC를 한눈에.
+
+```
+1. brxce_search_users(query: "member name")
+   → userId 확인
+
+2. brxce_worknodes_by_member({
+     workspaceId,
+     userId: <user UUID>,    # memberId alias도 동일
+     status: "in_progress",
+     limit: 50,
+   })
+
+3. 각 노드에 대해 worknode_detail로 AC 진행도 확인
+4. 막힌 작업이 있으면 brxce_create_comment로 이슈 코멘트
+```
+
+**팁**: 1.1.16부터 `userId`와 `memberId` 둘 다 alias로 동작. 이전 버전은 `memberId`만.
+
+---
+
+## 6. 태그 거버넌스 (Tag Governance)
+
+중복/미사용 태그 정리.
+
+```
+1. brxce_get_tag_stats(workspaceId)
+   → unused tags, total assignments
+
+2. 미사용 태그 발견 시:
+   brxce_delete_tag({ workspaceId, tagId })
+
+3. 새 카테고리/태그 생성:
+   brxce_create_tag_category({ workspaceId, name: "환경", slug: "environment" })
+   brxce_create_tags_batch({
+     workspaceId,
+     tags: [
+       { name: "Production", categoryId: <위에서 받음> },  # slug 자동 생성
+       { name: "Staging", categoryId: <...> },
+       { name: "Local", categoryId: <...> },
+     ],
+   })
+
+4. brxce_batch_assign_tags({
+     workspaceId,
+     worknodeIds: [...],
+     tagIds: [<production 태그 UUID>],
+   })
+```
+
+**팁**: `create_tag` slug는 1.1.15+부터 자동 derive (`Backend/Node.js` → `backend-nodejs`). 명시 가능.
+
+---
+
+## 7. 대량 검색 → 일괄 변경 (Bulk Update)
+
+특정 조건의 모든 노드에 동일 변경 적용.
+
+```
+1. brxce_filter_worknodes({
+     workspaceId,
+     status: ["backlog"],
+     tags: ["urgent"],
+     pageSize: 100,
+   })
+   → worknodes[] + total
+
+2. 결과에서 nodeId 추출
+
+3. brxce_batch_actions({
+     action: "update-priority",
+     nodeIds: [...],
+     params: { priority: "critical" },
+   })
+```
+
+**팁**: `filter_worknodes`는 1.1.15+에서 도입된 새 backend 라우트. 이전 버전은 404. 큰 결과는 페이지로 나눠 호출.
+
+---
+
+## 8. 워크스페이스 델타 동기화 (Incremental Sync)
+
+외부 시스템(Notion 미러, 백업 등)에 최신 변경만 sync.
+
+```
+1. brxce_workspace_delta({
+     workspaceId,
+     sinceVersion: <마지막 동기화 버전>,
+     maxChanges: 100,
+   })
+
+2. response.changes를 순회해서 외부 시스템 갱신
+3. response.currentVersion (또는 truncated 시 nextSinceVersion) 저장
+4. truncated: true이면 다음 호출에서 nextSinceVersion부터 이어가기
+```
+
+**경고**: `sinceVersion: 0` 첫 동기화는 800KB+ 가능. 반드시 `maxChanges` 명시 + 페이지 처리.
+
+---
+
+## 9. 반복 작업 템플릿 (Recurring)
+
+매주/매일 자동 생성되는 작업.
+
+```
+1. brxce_create_recurring_template({
+     workspaceId,
+     title: "주간 회고",
+     rrule: "FREQ=WEEKLY;BYDAY=FR",
+     nodeType: "task",
+     priority: "medium",
+     timezone: "Asia/Seoul",
+   })
+
+2. 백엔드가 cron으로 매주 금요일에 실제 task 자동 생성
+3. brxce_list_recurring_templates(workspaceId)로 활성 템플릿 확인
+4. 변경 필요 시 brxce_update_recurring_template
+```
+
+**팁**: AC가 필요한 task는 템플릿에 `acceptance_criteria` 함께 정의 (작성 시점에 제공해야 함, 자동 생성된 인스턴스에는 없음).
+
+---
+
+## 10. 클린업 (테스트 데이터 제거)
+
+세션 끝낼 때 테스트 노드 정리.
+
+```
+1. brxce_read_worknodes({
+     workspaceId,
+     query: "[테스트]",       # title prefix로 검색
+     limit: 200,
+   })
+
+2. brxce_batch_actions({
+     action: "delete",        # soft delete
+     nodeIds: [...],
+   })
+
+3. (필요 시) 각 노드를 brxce_permanent_delete_worknode로 hard delete
+   → cascade로 children, criteria, comments, tagRelations 모두 제거
+```
+
+**경고**: `permanent_delete`는 owner만 가능. cascade가 큰 트리에서는 시간 걸릴 수 있음.
+
+---
+
+## 안티 패턴 (피해야 할 것)
+
+- ❌ N개 노드에 N번 `update_worknodes` 호출 → ✅ `batch_actions` 한 번
+- ❌ task 생성 시 AC 생략 → ✅ 항상 최소 1개
+- ❌ `preview` 명시 없이 create/update → ✅ 명시적 `false`
+- ❌ UUID를 `query`로 read → ✅ `worknodeIds` / `nodeIds`
+- ❌ workspace_delta sinceVersion=0 무한정 → ✅ maxChanges + 페이지
+- ❌ permanent_delete 후 즉시 inbox 신뢰 → ✅ 1.1.16+에서 자동, 그 미만은 한 번 더 read