# Copilot은 워크스페이스를 봅니다. Maguyva는 저장소의 지도를 그립니다.

Canonical source: https://maguyva.ai/ko/for-vscode

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).

VS Code의 에이전트는 여러분이 첨부한 파일과 스스로 찾은 파일만 읽습니다. Maguyva는 저장소 전체를 인덱싱해 MCP로 제공하므로, 에이전트는 편집하기 전에 심볼이 어디에 있고 누가 호출하는지 먼저 묻습니다.

> .vscode/mcp.json의 servers 항목 하나: URL 하나와 Authorization 헤더 하나.

## VS Code에 대해 알아둘 것

VS Code에만 해당하는 네 가지 사실.

### .vscode/mcp.json

서버는 `mcpServers`가 아니라 `servers` 아래에 둡니다. 모든 워크스페이스에서 쓰려면 `MCP: Open User Configuration`을 실행하고 프로필의 `mcp.json`에 같은 항목을 추가하세요.

### type: http

VS Code는 Streamable HTTP로 Maguyva 엔드포인트에 연결하고, 서버가 지원하지 않을 때만 SSE로 전환합니다. 로컬에서는 아무것도 실행되지 않습니다.

### 환경 변수 참조

헤더는 `Bearer ${env:MAGUYVA_API_KEY}`이며, VS Code가 자신이 시작된 환경에서 이 값을 읽으므로 키가 커밋하는 파일에 들어가지 않습니다. 직접 입력받고 싶다면 입력 변수를 쓰세요. 한 번 묻고 키를 저장합니다.

### 작업 영역 신뢰

워크스페이스를 신뢰하면 `.vscode/mcp.json`의 서버는 별도 확인 없이 시작되고, 제한 모드에서는 절대 시작되지 않습니다. 채팅 입력창의 Configure Tools로 도구를 하나씩 켜고 끌 수 있습니다.

## 사용자 지정 지침은 작업 합의서입니다. 이를 활용하세요.

```text
# .github/copilot-instructions.md
- 변경을 완료라고 하기 전에 npm test를 실행한다.
- src/gen/ 아래의 생성 파일은 절대 수정하지 않는다.
```

VS Code는 프로젝트 전체 지침을 `.github/copilot-instructions.md` 또는 `AGENTS.md`에서, 대상별 지침을 `applyTo` 패턴이 있는 `.github/instructions/*.instructions.md` 파일에서 읽습니다. 이런 데 쓰세요:

- 빌드, 테스트, lint 명령.
- 에이전트가 자꾸 틀리는 규칙.
- 에이전트가 건드리면 안 되는 폴더.

지침은 에이전트에게 일하는 방식을 알려 줍니다. 곧 이름을 바꿀 타입을 4천 개 파일 중 어디서 import하는지는 알려 주지 못합니다.

## 워크스페이스 시야가 끝나는 곳

에이전트가 열어 둔 파일만으로는 알 수 없는 세 가지.

### // 첨부한 것이 전부는 아니다

에이전트는 여러분이 첨부한 것과 검색 결과를 바탕으로 일합니다. 변경 후 깨지는 다른 패키지의 호출자는 어느 목록에도 없었습니다.

### // 텍스트 일치는 참조가 아니다

워크스페이스 검색은 문자열을 찾습니다. 진짜 호출과 주석, mock, 다른 클래스의 같은 이름 메서드를 구별하지 못합니다.

### // 읽을 때마다 컨텍스트가 줄어든다

에이전트가 상황 파악을 위해 여는 파일마다 변경에 필요한 컨텍스트를 씁니다. file:line이 붙은 순위 답변 하나가 탐색용 읽기 열 번보다 쌉니다.

## VS Code의 MCP 서버로서의 Maguyva

servers 항목 하나로 에이전트가 얻는 것:

- **인덱싱된 저장소에 대한 11개의 도구**: 시맨틱, 구조적(AST), 그래프, 텍스트 검색에 더해 심볼 조회, 의존 요소, 파일 검색까지.
- **파일 경로와 줄 번호가 포함된 답**: 285개 이상의 언어에서. 에이전트가 처음부터 올바른 파일을 엽니다.
- **읽기만 하는 도구**: Maguyva의 도구는 인덱스를 조회할 뿐입니다. 파일을 수정하는 도구가 없으므로 모든 승인은 쓰기가 아니라 읽기에 관한 것입니다.

> VS Code는 에이전트에게 *여러분의 워크스페이스*를 줍니다.
> Maguyva는 에이전트에게 *저장소의 지도*를 줍니다.

## 두 가지 워크플로

먼저 지도에 묻고, 그다음 편집하세요.

### 01. 파서를 바꾸기 전에 테스트 찾기

```text
vscode agent> parseConfig를 거치는 테스트는?

dependency_search("parseConfig", dependents)
  tests/config/parse.test.ts:12
  tests/cli/flags.test.ts:88

→ 에이전트는 수정 후 전체 스위트가 아니라 이 두 파일을 실행합니다.
[exit 0]
```

답변이 파서에 닿는 두 테스트 파일을 짚어 주므로, 에이전트는 깨질 수 있는 곳에서 변경을 확인합니다.

### 02. 첫 수정 전에 이름 변경 규모 가늠하기

```text
vscode agent> OrderStatus.PENDING을 OrderStatus.QUEUED로 이름 바꿔 줘

find_symbol("OrderStatus", references)
  9개 파일에 참조 23개

→ 에이전트는 아홉 개 파일을 한 번에 처리할 계획을 세웁니다.
[exit 0]
```

참조 개수는 타입 검사가 실패한 뒤가 아니라 수정 전에 도착합니다.

## VS Code에서 설정하기

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

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

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

### 02. .vscode/mcp.json에 Maguyva 추가

`.vscode/mcp.json`

```json
{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. 키를 설정하고 서버 시작하기

VS Code를 실행하는 환경에서 `MAGUYVA_API_KEY`를 설정한 뒤, 항목 위의 코드 렌즈에서 서버를 시작하세요. 이미 답을 아는 질문 하나를 에이전트에게 해 보세요.

VS Code의 [MCP 문서](https://code.visualstudio.com/docs/agent-customization/mcp-servers)에서 입력 변수, 이식 가능한 .mcp.json 형식, 서버 신뢰를 다룹니다.

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

MCP로 VS Code를 연결하고, 확인할 수 있는 질문 하나를 해 보세요.