# Claude Desktop은 저장소를 못 봅니다. 하나 보여주세요.

Canonical source: https://maguyva.ai/ko/for-claude-desktop

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Claude Desktop은 많은 사람이 지금 편집하고 있지 않은 코드에 대해 묻는 곳입니다. 리뷰, 온보딩, 장애 대응 통화처럼요. Maguyva는 저장소를 인덱싱해 MCP로 제공하므로, 답이 기억이 아니라 파일과 줄을 인용합니다.

> 체크아웃은 필요 없습니다. 인덱스에 물어보세요.

## Claude Desktop에 대해 알아둘 것

Claude Desktop에만 해당하는 네 가지 사실.

### claude_desktop_config.json

Settings → Developer → Edit Config로 엽니다. macOS에서는 `~/Library/Application Support/Claude/`, Windows에서는 `%APPDATA%\Claude\`에 있습니다.

### 로컬 브리지

이 파일은 로컬 프로세스를 시작하므로, 이 가이드는 `npx`로 `@maguyva/mcp`를 실행합니다. Node.js가 설치되어 있어야 합니다.

### env 항목

브리지는 같은 파일에 있는 서버의 `env` 블록에서 `MAGUYVA_API_KEY`를 읽습니다.

### 종료한 뒤 다시 열기

Claude Desktop은 실행할 때 이 파일을 읽습니다. 편집한 뒤에는 앱을 완전히 종료하세요. 다음 실행 때 서버가 시작됩니다.

## 프로젝트 지침이 방향을 정합니다. 활용하세요.

Claude의 프로젝트에는 프로젝트 안의 모든 채팅이 처음부터 받는 지침과 파일을 담을 수 있습니다. 이런 데 적합합니다:

- 답의 독자: 리뷰어, 신규 입사자, 온콜 엔지니어.
- 설명과 요약의 사내 스타일.
- 인용되길 원하는 몇몇 문서. 예를 들면 아키텍처 개요.

업로드한 파일은 스냅숏입니다. 저장소는 업로드한 다음 날 이미 앞으로 나아가 있습니다.

## 붙여넣은 코드가 한계에 부딪히는 곳

코드 없이 코드 이야기를 할 때 채팅이 어긋나는 세 가지 경우.

### // 붙여넣은 스니펫은 낡는다

지난주 채팅에 붙여넣은 파일은 지난주의 코드를 설명합니다. Claude는 받은 버전을 바탕으로 자신 있게 답합니다.

### // 스니펫은 시스템이 아니다

“이게 실패하면 무슨 일이 일어나지?”에 파일 하나로 답할 수 있는 경우는 드뭅니다. 핸들러, 재시도, 알림은 보통 서로 다른 패키지 세 곳에 있습니다.

### // 체크아웃이 없으면 grep도 없다

Claude Desktop에는 저장소의 작업 사본이 없습니다. 도구가 없다면 구조에 관한 모든 답은 여러분이 잊지 않고 붙여넣은 것에 달려 있습니다.

## Claude Desktop의 MCP 서버로서의 Maguyva

mcpServers 항목 하나로 Claude가 얻는 것:

- **인덱싱된 저장소에 대한 11개의 도구**: 시맨틱, 구조적(AST), 그래프, 텍스트 검색에 더해 심볼 조회, 의존 요소, 파일 검색까지.
- **파일 경로와 줄 번호가 포함된 답**: 285개 이상의 언어에서. 모든 주장을 직접 확인할 수 있습니다.
- **브랜치 인식 결과**: Claude는 지난달 누군가 올린 파일이 아니라 여러분이 지정한 브랜치에 대해 답합니다.

> 프로젝트 지침은 Claude에게 *답하는 방법*을 알려줍니다.
> Maguyva는 Claude에게 *답의 근거가 될 코드*를 줍니다.

## 두 가지 워크플로

평소라면 IDE를 열어야 답할 수 있는 질문들.

### 01. 리뷰 중에 코드 경로 설명하기

```text
claude> 결제 웹훅이 서명 검사에 실패하면 그다음엔 어떻게 되나요?

semantic_search("webhook signature verification failure")
  src/payments/webhooks.ts:64   verifySignature()
  src/payments/webhooks.ts:91   rejectAndAlert()

→ Claude가 두 줄을 모두 인용해 답합니다.
[exit 0]
```

답의 모든 단계가 열어 볼 수 있는 파일과 줄을 가리킵니다.

### 02. 계획하기 전에 변경 규모 가늠하기

```text
claude> 레거시 plan_code 필드를 읽는 곳이 몇 군데인가요?

text_pattern_search("plan_code")
  파일 9개에서 14건 일치
dependency_search("getPlanCode", dependents)
  호출자 6개

→ 추정이 짐작이 아니라 숫자에서 시작합니다.
[exit 0]
```

아무도 저장소를 열어 두지 않은 계획 회의에서 유용합니다.

## Claude Desktop에서 설정하기

세 단계로 끝. Free 등급: 저장소 3개, 인덱싱된 저장소 라인 최대 5만 줄, 카드 등록 불필요.

### 01. maguyva.ai에서 저장소 인덱싱하기

답을 채점할 수 있도록 이미 잘 아는 저장소를 고르세요.

### 02. claude_desktop_config.json에 Maguyva 추가하기

`claude_desktop_config.json`

```json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}
```

### 03. 플레이스홀더를 바꾸고, 재시작하고, 질문 하나 해보기

`mgv_xxxx`를 여러분의 API 키로 바꾸고, Claude Desktop을 완전히 종료한 뒤 다시 여세요. 서버가 보이지 않으면 Claude 로그 폴더(macOS에서는 `~/Library/Logs/Claude`)의 `mcp-server-maguyva.log`를 확인하세요.

[로컬 서버에 관한 MCP 가이드](https://modelcontextprotocol.io/docs/develop/connect-local-servers)에서 설정 파일과 로그를 더 자세히 다룹니다.

## 이미 알고 있는 저장소 하나를 인덱싱하세요.

MCP로 Claude Desktop을 연결한 뒤, 확인할 수 있는 질문 하나를 해보세요.