# 문제 해결 (Troubleshooting)

Claude Desktop에서 이 MCP 서버가 연결되지 않거나, 응답이 오지 않을 때 가장 흔한 원인과 해결법입니다.

## 1. 엉뚱한/옛 MCP 서버가 호출되거나 프롬프트가 몇 분씩 멈춤 (가장 흔함)

증상:

- 프롬프트를 보낸 뒤 응답이 몇 분씩 오지 않습니다.
- 로그에 등록한 적 없는 명령이 실행됩니다. 예를 들어 로컬 개발 빌드 경로(`node ...\dist\index.js` -> `MODULE_NOT_FOUND`)나 예전 테스트용 HTTP 브리지(`npx mcp-remote http://127.0.0.1:xxxxx/mcp` -> 404)가 보입니다.
- `claude_desktop_config.json`을 고쳤는데도 반영되지 않습니다.

원인:

Claude Desktop은 MCP 서버 등록을 **`claude_desktop_config.json` 파일과 별개로도** 유지합니다. 개발자 설정에서 추가했거나, 확장(`.mcpb`)으로 설치했거나, 예전에 테스트로 등록한 서버가 앱 내부 상태로 **캐시되어** 남습니다. 같은 이름(예: `tablecloth`)으로 여러 개가 겹치면, 설정 파일에 없는 옛 등록이 대신 호출되어 엉뚱한 프로세스가 뜨거나 멈춥니다. 개발 목적으로 여러 버전을 테스트한 환경에서 특히 잘 발생합니다.

해결:

1. Settings -> Extensions 에서 관련 확장을 **모두 제거**합니다.
2. Settings -> Developer(개발자 도구)에서, JSON 설정 파일과 무관하게 목록에 보이는 MCP 서버를 **휴지통 아이콘으로 직접 삭제**합니다. 여기가 핵심입니다. 설정 파일만 고쳐서는 이 캐시된 등록이 지워지지 않습니다.
3. Claude Desktop을 **완전히 종료**합니다. 창을 닫는 것만으로는 부족합니다. Windows는 시스템 트레이 아이콘에서 종료, macOS는 Cmd+Q로 완전히 끝내야 합니다. 트레이나 백그라운드에 남아 있으면 옛 상태가 그대로 유지됩니다.
4. 다시 시작한 뒤, 필요한 서버 하나만 새로 설치하거나 등록합니다.

확인 방법:

- 로그에서 실제로 실행된 명령을 보면 캐시 문제를 바로 알 수 있습니다.
  - Windows: `%APPDATA%\Claude\logs\mcp.log`
  - macOS: `~/Library/Logs/Claude/mcp.log`
- `Using MCP server command: ...` 줄이 **의도한 명령/경로와 다르면** 위 캐시 문제입니다.
- 멈춘 프롬프트는 `mcp.log`에서 `method="tools/call"`은 있는데 대응하는 `id=N result`가 없는 줄로, 어느 서버의 어느 도구가 매달렸는지 특정할 수 있습니다.

## 2. `No matching version found for tablecloth-mcp@x.y.z` (npx, 릴리스 직후)

증상: 새 버전이 나온 직후 `npx tablecloth-mcp@latest`가 `ETARGET`으로 실패합니다.

원인: npm의 `latest` 태그는 새 버전으로 바뀌었지만, 그 버전의 타르볼이 npm CDN 엣지에 아직 전파되지 않은 짧은 창에 걸린 것입니다.

해결: 1~2분 뒤 클라이언트를 재시작하면 됩니다. `npm cache clean --force` 후 재시도도 도움이 됩니다. 이런 전파 지연을 아예 피하려면 `.mcpb` 확장을 쓰세요. 확장은 바이너리를 번들에 담고 있어 실행 시 npm을 전혀 타지 않습니다.

## 3. 서버 로그가 보이는데 정상인가요?

정상입니다. 서버는 진단 로그를 **stderr**로 보냅니다. MCP stdio 프로토콜은 **stdout**만 쓰므로 로그가 프로토콜을 방해하지 않습니다. Claude Desktop은 stderr를 로그 패널에 모아 보여줄 뿐입니다.

바이너리를 터미널에서 직접 실행하면, 시작 로그를 찍은 뒤 stdin으로 클라이언트 요청이 오길 기다리며 가만히 있습니다. 이것도 멈춘 게 아니라 정상 동작입니다. stdio MCP 서버는 클라이언트가 붙어 요청을 보내야 응답합니다.

## 4. 이름 충돌

커스텀 이름(예: `tablecloth`)으로 직접 등록한 서버와 `.mcpb` 확장(표시명 "TableCloth")을 동시에 두면 항목이 둘이 됩니다. Windows에서는 로그 파일 이름까지 대소문자를 무시해 겹칠 수 있어 로그가 뒤섞여 보입니다. **하나만 남기세요.**

## 5. macOS에서 확장 서버가 뜨지 않음 (Gatekeeper)

`.mcpb`의 네이티브 바이너리는 코드 서명이나 공증이 되어 있지 않습니다. macOS에서 다운로드된 미공증 바이너리는 Gatekeeper가 실행을 막을 수 있습니다. 이 경우 `.mcpb` 대신 **dnx**나 **npx**로 실행하세요. 공증된 .NET/Node 호스트를 거쳐 실행되므로 이 문제가 없습니다.

## 6. 새 버전이 반영되지 않음

MCP 서버는 클라이언트가 시작할 때 프로세스로 떠서 실행되고, 실행 중에는 새 버전으로 교체되지 않습니다. 새 버전은 **클라이언트를 다시 시작해 서버를 새로 띄울 때** 반영됩니다. 자세한 내용은 README의 "업데이트" 절을 참고하세요.

## 알려진 이슈 (Known issues)

### 생성된 `.wsb`를 검토할 때 어시스턴트가 신중해지거나 검토가 끊길 수 있음

- 증상: `launch_sandbox`나 `generate_wsb`가 만든 `.wsb`의 실행 명령을 어시스턴트가 살펴볼 때, 내용을 의심하는 듯한 추론이 보이거나, 실행 전에 경고성 확인을 하거나(사용자가 불안해질 수 있음), 드물게 긴 명령을 검토하다 응답이 끊깁니다.
- 원인: 그 `.wsb`의 `<Command>`는 공식 준비 스크립트를 원격에서 받아 실행하는 형태입니다(`ExecutionPolicy Bypass` + 원격 스크립트 `iex` + DNS 폴백). 이 조합이 일반적인 악성 다운로더와 겉모습이 같아 모델의 안전 검토가 발동합니다. 명령이 매우 긴 단일 라인이라 검토 도중 응답이 끊기기도 합니다.
- 실제 동작: 이 스크립트는 공식 GitHub 릴리스에서 HTTPS로 받아 **일회용 샌드박스 내부에서만** 실행됩니다. 호스트 시스템에는 접근하거나 영향을 주지 않고, 샌드박스를 닫으면 모두 사라집니다. 자격증명이나 로그인은 다루지 않습니다. 따라서 어시스턴트의 실행 전 확인은 정상 동작으로 보시면 됩니다. 참고로 `generate_wsb`와 `launch_sandbox` 응답에는 이 동작을 명시하는 `securityNote` 필드가 포함됩니다.
- 개선 방향: 정본 `.wsb`의 실행 명령을 최소화(로직을 준비 스크립트로 이관)하고, 다운로드 스크립트를 해시로 검증하는 방식으로 바꿔 오탐과 검토 끊김을 줄이는 작업을 추적 중입니다([#1](https://github.com/yourtablecloth/TableClothMcp/issues/1)).