ShadowGit MCP 서버
Claude Code, Cursor 및 Claude Desktop이 ShadowGit에 접근할 수 있도록 합니다. ShadowGit은 사용자의 프로젝트를 몇 분마다 자동으로 스냅샷으로 기록하며, 이 스냅샷들은 사용자의 기존 git 히스토리와는 별도로 보관됩니다. 따라서 사용자 지원 도구(assistant)는 무엇이 언제 변경되었는지 확인할 수 있으며, 여러 개의 부분적인 스냅샷 대신 하나의 이름이 지정된 체크포인트로 자신의 편집 내용을 저장할 수 있습니다.
요구 사항 (Requirements)
- Node.js 20 이상 버전
- ShadowGit 앱 (체크포인트를 위해서는 0.3.4 이상, Lens를 위해서는 0.3.5 이후 버전, 연결된 단어(linked words)를 위해서는 0.3.7 이후 버전, 맵(map)을 위해서는 0.3.9 이후 버전, Lens의 종속성 사실(dependency facts)을 위해서는 0.3.10 이후 버전, 프로젝트 규칙(project's rules)을 위해서는 0.3.11 이상, 세션이 종료될 때 스냅샷 내에서 저장되지 않은 편집 내용을 확인하거나 새로운 내용이 없어 체크포인트를 확인할 때는 0.3.13 이상, 검토 코멘트(review comments) 및 모든 범위의 문서 페이지를 위해서는 0.4.0 이상)을 추적하며 최소 하나의 프로젝트에 연결되어 있어야 합니다.
앱이 종료된 상태에서도 히스토리 읽기는 작동합니다. 다만, 세션, 체크포인트, Lens, 맵, 검토 코멘트 기능은 앱이 실행 중이어야 합니다.
- PATH에 Git 설치
설정 (Setup)
Claude Code (프로젝트별로 한 번 설치):
claude mcp add --scope user shadowgit -- npx -y shadowgit-mcp-server
Cursor: ~/.cursor/mcp.json 파일에 다음 내용을 추가합니다:
{ "mcpServers": { "shadowgit": { "command": "npx", "args": ["-y", "shadowgit-mcp-server"] } } }
Claude Desktop: macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json 또는 Windows의 경우 %APPDATA%\Claude\claude_desktop_config.json에 동일한 항목을 추가합니다.
Claude Code에서는 서버가 현재 작업 중인 프로젝트를 인식합니다. Cursor와 Claude Desktop에서는 ShadowGit이 여러 개 이상의 프로젝트를 추적하는 경우, 해당 프로젝트 이름을 지정해야 합니다 (예: "in webshop").
무엇을 물어볼까요
- "지난 한 시간 동안 무엇이 변경되었나요?"
- "로그인 페이지에 오류가 발생한 시점은 언제인가요?"
- "Header.tsx의 히스토리를 보여주세요."
- "이 프로젝트는 어떻게 구성되어 있나요?"
- "chargeCard에 무엇이 의존하고 있나요?"
- "이 리팩토링을 위해 ShadowGit 세션을 시작한 다음, 'Fixed login redirect'라는 체크포인트를 생성하고, 마지막으로 ShadowGit 세션을 종료하세요."
- "이 세션에 대한 Lens 단어를 작성해 주세요."
- "결제(billing) 영역은 무엇을 하나요?"
- "ShadowGit에 이 프로젝트를 문서화하세요."
- "저의 ShadowGit 검토 의견들을 다뤄주세요."
| Tool | 기능 |
|---|
list_repos | 추적 중인 프로젝트 목록, 현재 프로젝트, 마지막 스냅샷 및 활성 세션을 나열합니다. |
git_command | 스냅샷 히스토리에 읽기 전용 git 명령어(log, diff, show, blame, ...)를 실행합니다. |
get_map | 프로젝트가 어떻게 구성되어 있는지 제공합니다: 영역(areas), 레이어(layers) 및 그 사이의 링크, 또는 하나의 영역에 대해 프로젝트 규칙과 문서 페이지 요약 정보를 제공합니다. |
get_code_context | 파일과 심볼의 위치, 무엇이 그것들에 의존하는지, 변경 사항이 어디에 영향을 미치는지, 프로젝트 규칙 및 해당 영역의 문서 페이지 요약 정보를 제공합니다. |
start_session | 어시스턴트가 편집하는 동안 자동 스냅샷을 일시 중지합니다. |
checkpoint | 현재 변경 사항을 하나의 이름이 지정된 체크포인트로 저장하고(.shadowgit-ignore를 따름), 프로젝트의 .shadowgit-rules와 비교합니다. |
end_session | 자동 스냅샷을 재개합니다. |
get_lens | 범위에 대한 ShadowGit의 렌즈(Lens)를 읽습니다. 기본적으로 가장 최근의 AI 세션이며, 무엇이 무엇에 의존하는지 및 규칙 이름과 링크를 보여줍니다. |
write_lens_words | 해당 범위에 대한 렌즈의 단어(words)를 작성하여 히스토리에 보관하며, 링크, 이유(why), 발췌문(excerpt)을 포함합니다. |
get_docs | 프로젝트의 문서 페이지를 읽습니다(맵 영역별로 하나씩 + 개요). 기본적으로 가장 최근 AI 세션에서 변경되어 단어가 필요한 항목이며, 각 항목은 사실(facts), 현재까지 작성된 단어(words so far), 그리고 이후 변경된 내용을 포함합니다. |
| write_docs | 페이지의 단어와 심볼 및 영역에 대한 링크를 포함하여 작성하거나 여전히 유효한 단어를 유지합니다. 기록에는 보존되지만 프로젝트 파일에는 절대 포함되지 않습니다. |
| get_review_comments | ShadowGit에서 보내서 아직 해결하지 않은 검토 코멘트(review comments)를 해당 라인, 단어 및 답장과 함께 읽습니다. |
| reply_to_review_comment | 하나의 코멘트에 답장합니다: ShadowGit은 변경 사항을 담고 있는 스냅샷과 함께 그 아래에 답장을 표시합니다. |
다른 도구들은 repo가 주어지지 않는 한 현재 프로젝트에서 작동합니다.
보안 (Security)
git_command는 셸(shell) 없이 읽기 전용 하위 명령어만 실행하며, 스냅샷 기록 외부의 파일을 읽거나 쓰려고 시도하는 옵션(--output, --no-index, blame --contents 및 축약형/묶음 형태를 포함한 기타 옵션), git 설정에서 헬퍼 명령어를 실행하는 옵션(--ext-diff, --textconv, --filters), 그리고 프로젝트 외부의 경로는 거부합니다. 체크포인트는 ShadowGit 앱이 사용자가 추가한 프로젝트 내에서만 생성합니다. 서버 자체는 로컬호스트(localhost)에 있는 ShadowGit 앱과만 통신하며, 반환되는 내용은 다른 도구 결과와 마찬가지로 어시스턴트에게 전달됩니다.
서버는 ShadowGit 앱이 생성하는 프로젝트의 .shadowgit.git 기록을 신뢰합니다. Git은 해당 기록의 구성을 존중하기 때문에, 악성 코드가 심어진 경우 이 서버를 통해서뿐만 아니라 앱 자체 스냅샷을 통해서도 git이 프로그램을 실행하도록 만들 수 있습니다. 직접 생성하지 않은 .shadowgit.git 폴더가 포함된 프로젝트는 ShadowGit에 추가하지 마십시오.
설정 (Configuration)
| 변수 (Variable) | 기본값 (Default) | 용도 (Purpose) |
|---|
SHADOWGIT_TIMEOUT | 10000 | git 명령이 실행될 수 있는 밀리초(Milliseconds) 시간 |
SHADOWGIT_SESSION_API | http://localhost:45289/api | ShadowGit 앱의 로컬 API |
SHADOWGIT_STORAGE_DIR | platform default | ShadowGit이 repos.json을 저장하는 위치 |
개발 (Development)
npm install
npm test
npm run eval
라이선스 (License)
MIT