gem-llm-debug-mcp

Claude Code 의 MCP (Model Context Protocol) 서버 문제 진단 스킬.

When to use

• "MCP 안 떠", "MCP 도구가 목록에 없어"
• "github mcp 인증 실패"
• "filesystem mcp 권한 거부"
• "firecrawl/mermaid/pandoc mcp 동작 안 함"
• "npx <pkg> 못 찾음"
• "MCP 로그 어디"

Step 1 — settings.json 검증

python -c "import json; d=json.load(open('/home/jovyan/.claude/settings.json')); print(json.dumps(d.get('mcpServers',{}), indent=2, ensure_ascii=False))"

확인 포인트:

• 각 서버에 command, args(있다면), env(필요시) 존재
• env 의 토큰이 placeholder(<...>)면 진짜 값으로 교체 필요
• JSON 유효한지 (json.load 에러 없어야)

Step 2 — 패키지 resolution

각 MCP 서버 command/args[0]을 추출해 npx로 dry run:

npx -y @modelcontextprotocol/server-github --help 2>&1 | head -20
npx -y @modelcontextprotocol/server-filesystem --help 2>&1 | head -20
npx -y firecrawl-mcp --help 2>&1 | head -20
npx -y mcp-mermaid --help 2>&1 | head -20
npx -y mcp-pandoc --help 2>&1 | head -20

패키지를 못 찾으면 정확한 npm 이름을 npm search 또는 npm registry 로 확인.

Step 3 — 환경변수

env | grep -iE 'GITHUB|FIRECRAWL|ANTHROPIC|HF_' | sed 's/=.*/=***/'

민감 토큰은 마스킹해서 사용자에게 보고. 실제 값을 화면에 출력하지 말 것.

Step 4 — Claude Code MCP 로그

Claude Code 는 보통 ~/.cache/claude-code/ 또는 ~/.claude/logs/ 에 로그를 남김. 위치 자동 탐색:

find ~/.claude ~/.cache/claude-code ~/.local/share/claude-code -maxdepth 4 -name '*.log' -o -name 'mcp*' 2>/dev/null | head

최근 stderr:

tail -n 200 <found-log>

Step 5 — 증상별 분기

Step 6 — 수정 후 재검증

settings.json 변경 시 항상 백업 먼저:

cp ~/.claude/settings.json /home/jovyan/gem-llm/_trash/settings-backup-$(date +%Y%m%d-%H%M%S).json

JSON 유효성:

python -c "import json; json.load(open('/home/jovyan/.claude/settings.json'))" && echo OK

Safety

• 토큰/PAT를 transcript에 절대 기록하지 말 것
• ~/.claude/settings.json 의 hooks (argos hook 포함) 와 다른 키 보존 — mcpServers 만 만지기
• rm 금지, 항상 mv 또는 cp 백업