Claude가 직접 해결한 MCP Filesystem Server의 Windows UNC 경로 버그 수정

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

Claude Desktop의 MCP Filesystem 서버에서 Windows UNC 네트워크 공유 경로 접근 시 발생하는 경로 검증 로직의 결함과 Claude Opus를 통한 디버깅 및 해결 과정을 다룬다.

배경

Windows 환경에서 Claude Desktop의 MCP Filesystem 확장 기능을 사용하여 UNC 네트워크 공유 경로를 연결했으나, 하위 디렉토리 접근 시 보안 오류가 발생하여 Claude Opus와 함께 소스 코드를 분석하고 패치를 적용했다.

의미 / 영향

이 사례는 AI 에이전트가 단순히 텍스트를 생성하는 것을 넘어 자신의 도구 체인과 실행 환경의 결함을 스스로 진단하고 수정할 수 있는 능력을 보여준다. 특히 MCP와 같은 표준 프로토콜 환경에서 모델이 인프라 레벨의 디버깅에 참여함으로써 개발자 경험을 크게 향상시킬 수 있음을 시사한다.

커뮤니티 반응

작성자가 Claude를 활용해 인프라 버그를 직접 고친 사례에 대해 흥미롭다는 반응이며, 유사한 UNC 경로 문제를 겪는 사용자들에게 실질적인 해결책을 제공했다는 평가이다.

실용적 조언

Windows에서 MCP Filesystem 서버를 UNC 경로와 함께 사용할 때 접근 오류가 발생하면 path-validation.js 파일의 startsWith 로직을 확인하라.
네트워크 드라이브 매핑으로 문제를 해결하려 하기보다 UNC 경로 자체의 정규화 로직을 수정하는 것이 근본적인 해결책이다.
확장 프로그램 자동 업데이트 시 수동 패치가 덮어씌워질 수 있으므로 수정된 스크립트를 보관해두는 것이 좋다.

언급된 도구

MCP Filesystem Server추천

Claude가 로컬 파일 시스템에 접근할 수 있도록 하는 서버 확장

Claude Desktop추천

Anthropic의 공식 데스크톱 AI 클라이언트

섹션별 상세

Windows UNC 경로(\\server\share\)를 사용 시 발생하는 특정 오류 증상을 확인했다. MCP Filesystem 서버의 list_directory 명령이 루트 디렉토리에서는 정상 작동하지만, 하위 폴더나 파일 작업 시에는 '허용된 디렉토리 외부의 경로'라는 에러와 함께 접근이 거부되는 현상이 나타났다.

설정 파일의 실제 위치를 파악하는 과정에서 혼선이 있었다. 일반적인 claude_desktop_config.json이 아닌, 데스크톱 확장으로 설치된 경우 %APPDATA% 내의 별도 JSON 파일에 설정이 저장됨을 확인했다. 또한 Node.js의 fs.realpath()가 매핑된 네트워크 드라이브를 다시 UNC 경로로 변환하여 문제를 우회하기 어렵게 만든다는 점을 발견했다.

버그의 근본 원인은 path-validation.js 내의 isPathWithinAllowedDirectories 함수 로직에 있었다. UNC 루트 경로는 이미 백슬래시로 끝나는데, 여기에 시스템 경로 구분자(path.sep)를 무조건 추가하면서 '\\server\share\\'와 같은 이중 백슬래시가 생성되어 실제 경로와 매칭되지 않는 결함이 확인됐다.

javascript

// 기존 버그가 있는 코드
return normalizedPath.startsWith(normalizedDir + path.sep);

UNC 경로 루트에서 이중 백슬래시 문제를 일으키는 기존 경로 검증 로직

해결을 위해 경로가 구분자로 끝나는지 여부를 먼저 확인하고 조건부로 구분자를 추가하도록 로직을 수정했다. 사용자는 PowerShell 스크립트를 작성하여 설치된 확장 프로그램의 배포용 JS 파일을 직접 패치했으며, 재시작 후 Claude가 스스로 MCP 도구를 사용하여 수정 사항을 검증하는 데 성공했다.

javascript

// 수정된 코드
const dirWithSep = normalizedDir.endsWith(path.sep) ? normalizedDir : normalizedDir + path.sep;
return normalizedPath.startsWith(dirWithSep);

경로 구분자가 이미 존재하는지 확인하여 중복 추가를 방지하는 수정 로직

powershell

$file = "$env:APPDATA\Claude\Claude Extensions\ant.dir.ant.anthropic.filesystem\node_modules\@modelcontextprotocol\server-filesystem\dist\path-validation.js"
$content = Get-Content $file -Raw
$content = $content.Replace(
    'return normalizedPath.startsWith(normalizedDir + path.sep);',
    'const dirWithSep = normalizedDir.endsWith(path.sep) ? normalizedDir : normalizedDir + path.sep; return normalizedPath.startsWith(dirWithSep);'
)
[System.IO.File]::WriteAllText($file, $content)

컴파일된 JS 파일에 패치를 직접 적용하는 PowerShell 스크립트

실무 Takeaway

MCP Filesystem 서버의 경로 검증 로직은 Windows UNC 루트 경로의 트레일링 백슬래시 처리에 결함이 있어 하위 디렉토리 접근을 차단한다.
Claude Desktop 확장의 설정은 %APPDATA%\Claude\Claude Extensions Settings 경로 내의 개별 JSON 파일에 저장된다.
Node.js 환경에서 네트워크 드라이브 매핑은 실시간으로 UNC 경로로 해석되므로 파일 시스템 로직 설계 시 이를 고려해야 한다.
Claude Opus는 자신의 실행 환경 인프라 내 소스 코드를 분석하고 실행 가능한 패치 코드를 생성하여 스스로의 버그를 진단할 수 있다.