@brxce/mcp-server 1.1.15 → 1.1.17

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+ 업데이트 |
+| 토큰 폭발 | 페이지/필터 추가 |

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

@@ -0,0 +1,277 @@
+# BRXCE MCP Footguns
+
+이번 안정화 세션에서 발견된 실제 함정 카탈로그. 각 항목은 **증상 → 원인 → 해결**.
+
+---
+
+## Frontmatter 안전성
+
+### preview 기본값 변경
+
+**증상**: `brxce_create_worknodes`나 `brxce_update_worknodes`로 만들었는데 실제로 생성/수정되지 않음.
+
+**원인**: 1.1.10 이후 preview 기본값이 `true`로 변경됨 (#1108). 이전에는 `undefined`였고 즉시 실행됐음.
+
+**해결**:
+```ts
+brxce_create_worknodes({ worknodes: [...], preview: false })
+brxce_update_worknodes({ updates: [...], preview: false })
+brxce_create_meeting({ ..., preview: false })
+brxce_update_meeting({ ..., preview: false })
+```
+
+명시적이지 않으면 항상 dry-run으로 끝난다. 안전하지만 기억하지 않으면 실행 안 됨.
+
+---
+
+## 응답 파싱 / Schema
+
+### "Found 0 WorkNodes" — UUID를 query로 보냄
+
+**증상**: 분명 존재하는 UUID인데 `read_worknodes`/`worknode_detail`/`list_attachments`가 0건 반환.
+
+**원인**: 백엔드 `query` 필드는 title 텍스트 검색 + displayId 정규식만 매칭한다. UUID는 어디에도 매칭되지 않음.
+
+**해결**:
+```ts
+// ❌
+brxce_read_worknodes({ query: "ca585177-df9b-408a-bd1f-55f8cba99a37" })
+
+// ✅
+brxce_read_worknodes({ nodeIds: ["ca585177-..."] })
+brxce_read_worknodes({ worknodeIds: ["ca585177-..."] })
+brxce_worknode_detail({ nodeId: "ca585177-..." })   // 1.1.16+에서 자동 분기
+```
+
+내부 영향 받는 툴: `worknode_detail`, `list_attachments`, `download_attachment`, `upload_attachment`. 1.1.12~1.1.16에서 단계적 fix됨.
+
+### task/subtask 생성 시 acceptance_criteria 누락
+
+**증상**: `brxce_create_worknodes`로 task 생성 시 `400 BAD_REQUEST: task requires at least 1 acceptance criteria`.
+
+**원인**: 백엔드가 #1079 이후 강제. task/subtask는 최소 1개 AC 필요.
+
+**해결**:
+```ts
+brxce_create_worknodes({
+  worknodes: [{
+    title: "...",
+    nodeType: "task",
+    acceptance_criteria: [{ title: "검수 기준 1" }],
+  }],
+  preview: false,
+})
+```
+
+또는 단순 메모면 `nodeType: "note"` 사용 (AC 불필요).
+
+### update_worknodes는 PATCH, post가 아님
+
+**증상**: `batch_assign`이 항상 "Success: 0/N"으로 silent fail.
+
+**원인**: 1.1.15 이전 `batch-assign-tool.ts`가 `apiClient.post('/mcp/worknodes/update', ...)` 호출. 백엔드 라우트는 PATCH였음. 게다가 응답 shape도 `{ updated, failed, summary }`인데 옛 코드는 `successCount`를 읽음.
+
+**해결**: 1.1.15+로 업그레이드. 에이전트는 모르고 사용해도 무방.
+
+---
+
+## Cache / Stale Data
+
+### permanent_delete 후 inbox/global_overview에 잔존
+
+**증상**: 분명 영구 삭제했는데 `workspace_inbox`에 그대로 보임.
+
+**원인**: `permanent_delete_worknode` 라우트가 워크스페이스 스냅샷 캐시 invalidation 이벤트를 발행하지 않음 (#45).
+
+**해결**: 1.1.16+ (PR #1108)에서 자동. 그 미만 버전을 쓰는 동안에는:
+1. 영구 삭제 후 한 번 더 read해서 캐시 강제 갱신, 또는
+2. 새 노드를 만들어 삭제 cycle을 한 번 더 돌림
+
+### inbox 50건 cap
+
+**증상**: `workspace_inbox` 결과가 항상 50건만 반환됨.
+
+**원인**: 백엔드 기본 limit. 그 이상은 페이지네이션 필요.
+
+**해결**: `limit` 파라미터로 조정 (max 200), 또는 카테고리별로 필터 후 호출.
+
+---
+
+## 파라미터 직렬화 (Harness 측)
+
+### 첫 호출에서 array가 string으로 도착
+
+**증상**:
+```
+Invalid arguments for tool ...:
+  expected: array
+  received: string
+  path: [nodeIds]
+```
+
+**원인**: Claude Code 클라이언트가 처음 보는 툴의 schema가 로드되지 않은 상태에서 array 파라미터를 JSON 문자열로 직렬화. MCP 서버 side 버그가 아님.
+
+**해결**:
+1. 같은 호출을 한 번 더 (schema가 로드된 상태)
+2. 또는 미리 ToolSearch로 schema 강제 로드: `select:mcp__brxce__brxce_archive_worknodes`
+
+이건 OpenClaw에서는 보통 발생하지 않는다.
+
+### number 파라미터에 string이 들어감
+
+**증상**: `limit`, `pageSize` 등에 `"3"`을 전달하면 `expected: number, received: string`.
+
+**원인**: 일부 툴이 strict number 파싱.
+
+**해결**: `worknodes_by_member`는 1.1.15+에서 string→number coerce 지원. 다른 툴은 항상 number 리터럴로 호출.
+
+---
+
+## 명명 / Alias 혼란
+
+### memberId vs userId
+
+**증상**: `worknodes_by_member` 호출 시 `memberId is required` 에러.
+
+**원인**: 1.1.14 미만에서 `memberId`만 받음.
+
+**해결**: 1.1.15+에서 `userId` alias 추가. 둘 다 사용 가능.
+
+### nodeIds vs worknodeIds
+
+**증상**: `read_worknodes({ nodeIds: [...] })`가 동작하지 않음.
+
+**원인**: 원래 `worknodeIds`만 정식 필드.
+
+**해결**: 1.1.13+에서 `nodeIds` alias 추가. 두 필드 동시 제공 시 `worknodeIds` 우선.
+
+### tagIds/tagSlugs는 array OR string
+
+**증상**: `find_worknodes_by_tags({ tagSlugs: ["brxce"] })`가 400.
+
+**원인**: 1.1.14 이하에서 string만 받음 (comma-separated).
+
+**해결**: 1.1.15+에서 array도 받음. 두 형태 모두 지원.
+
+---
+
+## 이미 제거된 기능 사용
+
+### invitation 계열 410 Gone
+
+**증상**: `brxce_list_invitations`, `brxce_create_invitation` 등이 410 반환.
+
+**원인**: #1021로 워크스페이스 = 개인 모델로 전환되면서 invitation 기능 자체 제거됨. 1.1.11+에서 MCP 툴도 제거됨.
+
+**해결**: 사용 중단. 외부 협업이 필요하면 다른 메커니즘 사용.
+
+### workspace_member 계열 410 Gone
+
+**증상**: `brxce_add_workspace_member` 등이 410.
+
+**원인**: 동일 (#1021).
+
+**해결**: 1.1.15+에서 MCP 툴 자체 제거. `list_workspace_members`(읽기)만 남음.
+
+### Bot 계열 전체 제거
+
+**증상**: `brxce_create_bot`, `brxce_list_bots` 등 미존재.
+
+**원인**: #1029로 bot 기능 전체 제거.
+
+**해결**: 사용 중단.
+
+---
+
+## Backend Raw SQL 함정
+
+### Prisma raw query 컬럼/테이블명 불일치
+
+**증상**: `brxce_global_overview` 500 with Prisma error.
+
+**원인**: 1.1.16 이전에는 4 layered 버그 누적:
+1. `Prisma.sql/Prisma.empty` 미사용 → `syntax error at or near $5`
+2. 테이블명 `work_nodes` (실제는 `worknode`)
+3. 컬럼명 `status` (실제는 `node_status`)
+4. UUID array binding without `::uuid[]` cast
+
+**해결**: 1.1.16+에서 모두 수정됨. 그 미만에서는 사용 불가.
+
+---
+
+## 응답 크기 / Token 폭발
+
+### workspace_delta 800KB 응답
+
+**증상**: `workspace_delta({ workspaceId, sinceVersion: 0 })`이 token limit 초과로 실패.
+
+**원인**: 큰 워크스페이스의 첫 sync는 수백 개 변경 + 각 변경마다 전체 노드 payload.
+
+**해결**: 1.1.15+에서 `maxChanges` 파라미터 (기본 50, 최대 200) + `truncated`/`nextSinceVersion` 응답.
+
+```ts
+brxce_workspace_delta({
+  workspaceId,
+  sinceVersion: 0,
+  maxChanges: 50,   // 명시 권장
+})
+// → truncated: true, nextSinceVersion: <next>
+// → 다음 호출에 sinceVersion=nextSinceVersion
+```
+
+### read_worknodes 무필터로 큰 워크스페이스
+
+**증상**: `read_worknodes({ workspaceId })`가 50건 + 모두 풀 페이로드.
+
+**원인**: 페이지네이션 없이는 limit 50 + offset 0이 기본.
+
+**해결**: 항상 `limit`/`offset` 명시, `query`/`nodeTypes`/`statuses` 등으로 필터, 또는 `compact` 모드 옵션.
+
+---
+
+## 미묘한 동작 차이
+
+### Note 타입의 status는 제한적
+
+**증상**: `update_worknodes`로 note의 status를 `in_progress`로 바꾸려 하면 에러.
+
+**원인**: note 타입은 `backlog | static | archived`만 허용. `static`은 note 전용.
+
+**해결**: 종류가 task처럼 진행되어야 하면 처음부터 `nodeType: "task"`로 만들 것.
+
+### Note의 complete는 status를 static으로 만듦
+
+**증상**: `complete_worknode`을 note에 호출하면 `status: completed`가 아니라 `status: static`이 됨.
+
+**원인**: 의도된 동작. note의 "완료"는 "참고용으로 박제"의 의미.
+
+**해결**: 정상. 혼란 없도록 인지만.
+
+### update_criteria isCompleted=true는 evidence 필요
+
+**증상**: `update_criteria({ criteriaId, isCompleted: true })`가 400.
+
+**원인**: AC enforcement #1079. boolean criteria를 만족시키려면 `evidenceUrl` 또는 `currentValue`(설명) 필요.
+
+**해결**:
+```ts
+brxce_update_criteria({
+  criteriaId,
+  isCompleted: true,
+  currentValue: "https://github.com/foo/bar/pull/123",  // or 텍스트
+})
+```
+
+---
+
+## 빠른 진단 체크리스트
+
+새 에러를 만났을 때:
+
+1. **MCP 서버 버전?** `npm list -g @brxce/mcp-server` → < 1.1.16이면 업데이트
+2. **preview 명시했나?** create/update/meeting CRUD는 명시 필수
+3. **UUID인가 displayId인가?** 적절한 필드(`worknodeIds` vs `query`)
+4. **task/subtask인데 AC 있나?** 없으면 400
+5. **Schema 로드됐나?** array 파라미터 첫 호출 실패는 재시도 또는 ToolSearch
+6. **삭제된 기능?** invitation/member/bot은 모두 폐기
+7. **캐시 stale?** 새 데이터로 한 번 더 read