@brxce/mcp-server 1.1.16 → 1.1.18

package/skills/brxce-mcp/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: brxce-mcp
+description: BRXCE MCP 89개 툴을 효율적·안전하게 사용하기 위한 가이드. 워크노드 CRUD, 태그/회의/알림 관리, AC(Acceptance Criteria) 강제, batch 처리, 캐시 일관성 등 BRXCE 관련 모든 작업에 사용. 인박스 정리, 일일 보고, 이슈 트리아지, GitHub 이슈/PR 동기화, 워크노드 검색, 멤버별 작업 조회, 미팅 노트 작성 등 BRXCE 워크스페이스 작업이 필요할 때 자동으로 활성화하고 필요하면 `/brxce-mcp`로 직접 호출 가능.
+license: MIT
+compatibility: Designed for Claude Code and OpenClaw via the AgentSkills standard. Requires @brxce/mcp-server >= 1.1.18.
+metadata:
+  author: BRXCE Team
+  version: "1.1.0"
+  brxce:
+    minMcpVersion: "1.1.18"
+    backend: "https://brxce-backend-production-1013529945435.asia-northeast3.run.app"
+---
+
+# BRXCE MCP — Best-Practice Playbook
+
+89개의 BRXCE MCP 툴을 효율적이고 안전하게 사용하기 위한 가이드. 1.1.16까지의 21+개 안정화 fix 전수 검증 결과를 기반으로 작성됨.
+
+## 5대 핵심 원칙
+
+이 5가지는 BRXCE MCP 사용 시 거의 항상 적용된다.
+
+### 1. preview는 기본 true — 명시적으로 끄기
+
+`brxce_create_worknodes`, `brxce_update_worknodes`, `brxce_create_meeting`은 모두 `preview: true`가 기본값이다 (안전장치). 실제 생성/수정을 원하면 **반드시 `preview: false` 명시**.
+
+```ts
+// ❌ dry run으로 끝남
+brxce_create_worknodes({ worknodes: [...] })
+
+// ✅ 실제 생성
+brxce_create_worknodes({ worknodes: [...], preview: false })
+```
+
+### 2. workspaceId는 한 번만 — 컨텍스트가 자동 전파됨
+
+`brxce_read_worknodes`나 `brxce_workspace_overview`로 한 번 workspaceId를 명시하면, MCP 서버가 컨텍스트에 저장한다. 이후 displayId(`#5723`) 기반 호출은 workspaceId 생략 가능.
+
+UUID 기반 호출은 globally unique이므로 workspaceId 없이도 동작한다 (1.1.16부터 `get_worknode_tags` 등에서 자동 fallback resolution).
+
+### 3. UUID는 worknodeIds, displayId는 query
+
+`brxce_read_worknodes` / `brxce_worknode_detail` 호출 시:
+- **UUID 입력** → `worknodeIds: [uuid]` 또는 `nodeIds: [uuid]` (alias)
+- **displayId 입력** (`#5723`, `5723`, `WS-5723`) → `query: "#5723"` 또는 `displayId: 5723`
+
+UUID를 `query`로 넣으면 백엔드는 title 검색만 하므로 0건 반환한다 (#1101 패턴).
+
+### 4. task / subtask는 acceptance_criteria 필수
+
+백엔드가 강제한다 (#1079). task/subtask 생성 시 최소 1개의 AC가 없으면 400 에러. 단순한 보고용 메모는 `nodeType: note`를 사용하면 AC 없이 가능.
+
+```ts
+brxce_create_worknodes({
+  worknodes: [{
+    title: "API 인증 미들웨어 구현",
+    nodeType: "task",
+    acceptance_criteria: [
+      { title: "POST /auth/login 200 응답" },
+      { title: "잘못된 토큰은 401 반환" },
+    ],
+  }],
+  preview: false,
+})
+```
+
+### 5. batch가 가능하면 batch_actions 사용
+
+N개 워크노드에 같은 action을 적용할 때 `brxce_batch_actions`(complete/archive/unarchive/delete/move/update-status/update-priority)나 `brxce_batch_assign` / `brxce_batch_assign_tags` 사용. N+1 update 호출은 피한다.
+
+### 6. 인박스는 단일 `inbox` 배열 — my/shared 분리 없음
+
+**정의**: 인박스 = 내 워크스페이스의 `status === backlog` 노드 전부 (archived/deleted 제외). 프런트엔드 `isBacklogNode` semantics 그대로.
+
+#1021로 워크스페이스가 1:1 personal이 되면서 `myInbox`/`sharedInbox` 분리 개념은 폐기됨. 1.1.18+부터 `brxce_workspace_inbox` 응답은 **단일 `inbox` 배열** + `inboxCount`를 반환한다.
+
+```ts
+// ✅ 1.1.18+
+const { inbox, summary } = await brxce_workspace_inbox({ workspaceId })
+// → inbox: [...], summary: { inboxCount, workspaceId, userId }
+
+// ❌ 1.1.17 이하 (legacy, 더 이상 동작하지 않음)
+// const { myInbox, sharedInbox } = ...
+```
+
+**주의**: 인박스는 "분류 안 된 ROOT 노드"가 아니라 "backlog 상태의 모든 노드"다. BRXCE 프로젝트 하위의 backlog 작업도 인박스에 포함된다 — 이게 정상이다.
+
+## 자주 쓰는 워크플로우 (요약)
+
+상세 단계는 [references/workflows.md](references/workflows.md) 참고.
+
+| 시나리오 | 핵심 흐름 |
+|---------|----------|
+| 인박스 정리 | `workspace_inbox` (통합 `inbox` 배열) → `batch_actions(action: archive/move/complete)` |
+| 일일 보고 | `daily_report` → `goal_progress` → 댓글/노트 정리 |
+| 이슈 트리아지 | `read_worknodes(query)` → 우선순위/assignee 일괄 변경 → 태그 |
+| GitHub 이슈 동기화 | `create_worknodes(task + AC)` → tag `issue-created` 부착 |
+| 회의 준비 | `create_meeting(preview:true → false)` → `add_agenda_item` → `add_meeting_note` |
+| 멤버별 작업 검토 | `worknodes_by_member(memberId or userId)` → `complete_worknode` |
+| 태그 청소 | `get_tag_stats` → 미사용 태그 `delete_tag` |
+
+## 도구 선택 가이드 (요약)
+
+89개 툴의 카테고리별 대표 도구. 상세 분류는 [references/tool-selection.md](references/tool-selection.md) 참고.
+
+| 카테고리 | 대표 툴 | 용도 |
+|---------|--------|-----|
+| 워크스페이스 | `workspace_overview`, `workspace_statistics`, `global_overview` | 트리/통계/전사 |
+| 워크노드 R | `read_worknodes`, `worknode_detail`, `worknode_subtree`, `worknode_history` | 검색/상세/하위/히스토리 |
+| 워크노드 W | `create_worknodes`, `update_worknodes`, `move_worknode`, `complete_worknode` | CRUD + 이동/완료 |
+| 워크노드 일괄 | `batch_actions`, `batch_assign`, `batch_assign_tags`, `archive_worknodes` | bulk 처리 |
+| 정렬/필터 | `filter_worknodes`, `find_worknodes_by_tags`, `worknodes_by_member`, `my_work` | 조건 검색 |
+| 태그 | `list_tags`, `create_tag`, `add_tags_to_worknode`, `tag_changes` | 태그 시스템 |
+| 회의 | `create_meeting`, `add_agenda_item`, `add_meeting_note`, `add_meeting_decision` | 미팅 사이클 |
+| 알림 | `list_notifications`, `mark_all_notifications_read`, `delete_notification` | 인박스 |
+| 댓글/AC | `create_comment`, `create_criteria`, `update_criteria` | 협업/검수 |
+| 반복 | `create_recurring_template`, `list_recurring_templates` | RRULE 기반 자동 생성 |
+| 첨부 | `list_attachments`, `upload_attachment`, `download_attachment` | 파일 |
+| 분석 | `daily_report`, `goal_progress`, `workspace_delta`, `plan_organize` | 보고/델타 |
+| 사용자 | `search_users`, `list_workspace_members` | 멤버 조회 |
+
+## 함정 (footguns)
+
+이번 세션 안정화 전 발견된 모든 함정 + 1.1.16에서 수정된 것은 [references/footguns.md](references/footguns.md). 핵심:
+
+- `workspace_delta`는 sinceVersion=0이면 800KB+ 가능 → `maxChanges` 명시 (default 50)
+- `batch_assign`이 0/N으로 silent fail하던 시기 있었음 — 1.1.15+에서 정상 메시지
+- `permanent_delete` 직후 `workspace_inbox`는 캐시 invalidation 필요 — 1.1.16+에서 자동
+- harness가 array 파라미터를 첫 호출에서 string으로 보내는 경우가 있음 — schema 로드 후 재시도
+- 인박스가 회의 분량으로 비대 → `workspace_inbox` 응답 50건 cap
+
+## 에러 복구
+
+상세는 [references/error-recovery.md](references/error-recovery.md). 빠른 참조:
+
+| HTTP | 의미 | 즉각 액션 |
+|------|------|----------|
+| 401 | 토큰 만료 | `${BRXCE_API_TOKEN}` 갱신 — MCP 서버 재시작 |
+| 403 | 권한 없음 | workspaceId가 본인 owner인지 확인 |
+| 404 | 리소스 없음 / 라우트 없음 | UUID 정확성 + MCP 서버 버전 (>=1.1.16) 확인 |
+| 410 | Gone (#1021로 제거된 기능) | invitation/workspace_member 툴 — 사용 중단 |
+| 500 + Prisma | 백엔드 raw SQL 버그 | 재시도 후 GitHub 이슈 |
+| `Network error: Server error` | api-client 5xx wrap | 1.1.13 미만 사용 중 — 업데이트 |
+
+## 안전 규칙
+
+- **테스트 데이터**: 항상 `[테스트]` prefix + `note` 타입 + 끝나면 `permanent_delete_worknode`
+- **대량 변경**: `preview: true` 한 번 → 결과 검토 → `preview: false`
+- **삭제**: soft delete(`delete_worknode`)는 idempotent. permanent delete는 owner만 가능 + cascade
+- **인박스 stale 데이터**: deletion 후 inbox에 잔존하면 1회 한정 (cache pre-fix data). 1.1.16부터는 invalidation 자동
+
+## MCP 서버 버전 의존성
+
+- **>= 1.1.18 권장** — 통합 인박스 (`inbox` 단일 배열), 이 skill의 모든 권고가 동작
+- **>= 1.1.16** — 대부분 동작하지만 인박스가 아직 `myInbox`/`sharedInbox`로 분리 반환
+- **>= 1.1.13** — cache/route 미수정 다수
+- **< 1.1.10** — 사용 비추천 (응답 파싱, 5xx 처리, slug 자동 생성 등 다수 fix 누락)
+
+업데이트: `npm install -g @brxce/mcp-server@latest` 후 Claude Code / OpenClaw 재시작.
+
+## 더 알아보기
+
+- [references/workflows.md](references/workflows.md) — 실제 사용 패턴 카탈로그
+- [references/tool-selection.md](references/tool-selection.md) — 89 툴 전체 분류 + 결정 트리
+- [references/footguns.md](references/footguns.md) — 함정 카탈로그
+- [references/error-recovery.md](references/error-recovery.md) — 에러 코드별 복구

package/skills/brxce-mcp/references/error-recovery.md

@@ -0,0 +1,274 @@
+# BRXCE MCP Error Recovery
+
+HTTP 코드 / 에러 메시지별 진단 + 복구 절차.
+
+---
+
+## HTTP Status Codes
+
+### 401 Unauthorized
+
+**에러 형태**:
+```
+API request failed: 401 Unauthorized
+Response: {"success":false,"error":{"code":"UNAUTHORIZED","message":"User not authenticated"}}
+```
+
+**원인**:
+- MCP 서버에 로드된 `BRXCE_API_TOKEN` 만료
+- 토큰 자체가 잘못됨
+- 1.1.13 이하에서 동시 refresh race condition (자체 fix됨)
+
+**복구**:
+1. 새 토큰 발급 (BRXCE 웹앱 settings)
+2. `~/.brxce/config` 또는 환경변수 `BRXCE_API_TOKEN` 갱신
+3. **MCP 서버 재시작 필수** — 토큰은 startup 시 로드됨
+   - Claude Code: 세션 종료 → 재시작
+   - OpenClaw: `openclaw gateway restart`
+
+---
+
+### 403 Forbidden
+
+**에러 형태**:
+```
+{"code":"FORBIDDEN","message":"No access to workspace ..."}
+```
+
+**원인**:
+- 다른 사용자의 워크스페이스 ID를 사용
+- workspaceId가 본인 owner가 아님 (#1021 이후 워크스페이스 = 1:1 personal)
+- permanent_delete를 owner가 아닌 사용자가 시도
+
+**복구**:
+1. `brxce_list_workspaces` → 본인 owner 워크스페이스 확인
+2. workspaceId 정정
+3. 회의/노트의 경우: 대상 회의의 워크스페이스 owner인지 확인
+
+---
+
+### 404 Not Found
+
+**두 가지 원인 분리 필요**:
+
+#### A. 리소스 자체가 없음
+```
+{"code":"NOT_FOUND","message":"WorkNode <uuid> not found or already deleted"}
+```
+
+**원인**:
+- UUID 오타
+- 이미 hard delete됨
+- soft delete된 항목을 다시 delete (1.1.13+에서 idempotent — 이젠 정상 404 반환)
+
+**복구**: ID 재확인 또는 무시 (idempotent라면 의도된 동작).
+
+#### B. 라우트 자체가 미구현 (백엔드 버그)
+```
+{"message":"Route POST:/api/v1/mcp/... not found","statusCode":404}
+```
+
+**원인**: MCP 툴은 호출하지만 백엔드에 그 라우트가 없음. 1.1.16 이전 공통 패턴.
+
+**복구**:
+1. MCP 서버 버전 확인 (`npm list -g @brxce/mcp-server`)
+2. < 1.1.16 → 업데이트: `npm install -g @brxce/mcp-server@latest`
+3. backend 미배포 가능성 → main 배포 상태 확인
+
+영향 받았던 라우트 (모두 1.1.16+에서 fix):
+- `POST /mcp/worknodes/filter`
+- `POST/GET/PUT/DELETE /mcp/meetings/:id/agenda/:itemId/notes`
+- `DELETE /mcp/notifications/:id`
+- `PUT /mcp/notifications/read-all`
+- `DELETE /mcp/worknodes/:id/permanent`
+
+---
+
+### 400 Bad Request
+
+**원인 패턴**:
+
+#### A. Validation 실패
+```
+{"code":"VALIDATION_ERROR","message":"body/workspaceId must match format \"uuid\""}
+```
+
+**복구**: 파라미터 형태 확인. 특히:
+- workspaceId는 UUID 문자열 (`null` 금지)
+- dueDate/scheduledAt은 ISO 8601 with timezone
+
+#### B. AC enforcement
+```
+{"code":"BAD_REQUEST","message":"task requires at least 1 acceptance criteria..."}
+```
+
+**복구**: `acceptance_criteria: [{ title: "..." }]` 추가, 또는 `nodeType: "note"`로 변경.
+
+#### C. Confirmation 누락
+```
+{"code":"VALIDATION_ERROR","message":"confirmation must be exactly \"PERMANENTLY DELETE\""}
+```
+
+**복구**: `permanent_delete_worknode`는 `confirm: true` 필수.
+
+#### D. Evidence 누락
+```
+{"message":"Evidence is required to complete boolean acceptance criteria \"...\""}
+```
+
+**복구**: `update_criteria`로 isCompleted=true 시 `currentValue` 또는 `evidenceUrl` 함께 전달.
+
+---
+
+### 410 Gone (사용 중단된 기능)
+
+**에러 형태**:
+```
+{"code":"GONE","message":"Workspace invitations have been removed..."}
+{"code":"GONE","message":"Workspace member management has been removed..."}
+```
+
+**원인**: #1021 (워크스페이스 = personal model 전환)으로 폐기. invitation, workspace_member, bot 계열 전체 폐기.
+
+**복구**: 사용 중단. 1.1.11+ 이후 MCP 툴 자체도 제거됨. 만약 1.1.10 이하에서 보인다면 업데이트.
+
+---
+
+### 500 Internal Server Error
+
+**에러 형태별 분기**:
+
+#### A. Prisma raw query 에러
+```
+Raw query failed. Code: `42P01`. Message: `relation "..." does not exist`
+Raw query failed. Code: `42703`. Message: `column "..." does not exist`
+Raw query failed. Code: `42883`. Message: `operator does not exist: uuid = text`
+```
+
+**원인**: 백엔드 raw SQL 버그. global_overview, tag_changes 등에서 발생.
+
+**복구**: 1.1.16+에서 모두 fix됨. 그 미만 버전이면 업데이트.
+
+#### B. Prisma other
+```
+Invalid `prisma.$queryRaw()` invocation
+```
+
+**원인**: 다양. 새 버그 가능성.
+
+**복구**: 재시도 → 영구적이면 GitHub issue 등록 (스택트레이스 + nodeId 포함).
+
+#### C. 일반 INTERNAL_ERROR
+```
+{"code":"INTERNAL_ERROR","message":"<some message>"}
+```
+
+**복구**: 메시지 분석. service 레이어 throw일 가능성. 재시도 후 영구면 보고.
+
+---
+
+## MCP 클라이언트 에러 (서버 도달 전)
+
+### "Network error when calling ...: Server error"
+
+**원인**: 1.1.13 미만 api-client가 5xx를 "Server error"로 wrap하고 outer catch가 다시 "Network error"로 감쌌음. 실제로는 backend 5xx.
+
+**복구**: 1.1.13+로 업데이트. 1.1.13+부터는 5xx도 "API request failed: 500" 형태로 그대로 노출.
+
+### "API request failed: 500" (구조화된 에러)
+
+**원인**: 백엔드 5xx. 위 #500 섹션 참고.
+
+**복구**: 1.1.13+에서 정상 패턴.
+
+### `Cannot read properties of undefined (reading 'length')` 또는 `(reading 'name')`
+
+**원인**: 1.1.10 ~ 1.1.13 시기 search_users / worknode_detail 응답 파싱 버그.
+
+**복구**: 1.1.14+로 업데이트.
+
+### MCP error -32602: Invalid arguments
+
+**원인**: Zod schema validation 실패. 보통 내가 잘못 호출함.
+
+**복구**: 에러 메시지의 `path` 확인 → 해당 필드 형식 점검.
+
+### `Found 0 WorkNodes`
+
+**원인**: UUID를 `query` 필드로 보냈을 가능성 (footguns.md 참고).
+
+**복구**: `worknodeIds` 또는 `nodeIds` 필드로 전환.
+
+---
+
+## Cache / Stale 데이터
+
+### 삭제했는데 inbox에 그대로
+
+**원인**: 1.1.16 이전 cache invalidation 미발행.
+
+**복구**:
+- 1.1.16+로 업데이트 (가장 좋은 방법)
+- 또는 새 노드 1개 만들고 다시 삭제해서 cache update를 강제 트리거
+- 또는 노드를 직접 read해서 진짜 존재 확인 (`Found 0`이면 실제 삭제됨, inbox만 stale)
+
+### 새로 만든 태그가 list_tags에 안 보임
+
+**원인**: 태그 생성 캐시 invalidation 누락 가능성 (확인 안 됨).
+
+**복구**: 한 번 더 호출 또는 `search_tags`로 직접 검색.
+
+---
+
+## Token / Context 폭발
+
+### 응답이 token limit 초과
+```
+Error: result (888,501 characters) exceeds maximum allowed tokens
+```
+
+**원인 후보**:
+- `workspace_delta(sinceVersion: 0)` — 첫 sync → `maxChanges` 설정
+- `read_worknodes` 무필터 → `query`/`limit`/필터 추가
+- `worknodes_by_member`로 1500+ 노드 반환 → status 필터 또는 `limit`
+
+**복구**: 항상 페이지네이션 + 필터링 사용. 1회 호출로 모든 데이터를 가져오려 하지 말 것.
+
+---
+
+## 진단 명령
+
+빠르게 어디서 막힌 건지 파악하고 싶을 때:
+
+```bash
+# MCP 서버 버전
+npm list -g @brxce/mcp-server
+
+# Backend 라이브 체크
+curl -sS -o /dev/null -w "%{http_code}\n" \
+  https://brxce-backend-production-1013529945435.asia-northeast3.run.app/api/v1/mcp/status
+
+# 401이면 토큰 환경변수 확인
+echo $BRXCE_API_TOKEN | head -c 20
+```
+
+---
+
+## 에러 → 액션 빠른 표
+
+| 에러 | 1순위 액션 |
+|------|----------|
+| 401 | 토큰 갱신 + MCP 서버 재시작 |
+| 403 | 본인 워크스페이스 확인 |
+| 404 (not found) | UUID 정정 / idempotent면 무시 |
+| 404 (route not found) | MCP 서버 1.1.16+ 업데이트 |
+| 400 (uuid format) | workspaceId 형태 점검 |
+| 400 (AC required) | acceptance_criteria 추가 또는 note 사용 |
+| 400 (confirmation) | `confirm: true` 추가 |
+| 400 (evidence) | currentValue/evidenceUrl 추가 |
+| 410 | 해당 기능 폐기됨, 사용 중단 |
+| 500 (Prisma raw) | 1.1.16+ 업데이트 |
+| Found 0 WorkNodes | nodeIds로 전환 |
+| Cannot read properties of undefined | 1.1.14+ 업데이트 |
+| Network error: Server error | 1.1.13+ 업데이트 |
+| 토큰 폭발 | 페이지/필터 추가 |