# Warp의 에이전트는 터미널에 삽니다. 저장소 지도를 건네주세요.

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

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

Warp의 에이전트는 명령을 실행하고 출력된 내용을 읽습니다. Maguyva는 저장소 전체를 인덱싱해 MCP로 제공하므로, 에이전트는 무언가 걸릴 때까지 grep과 cat을 돌리는 대신 코드가 어디 있는지 묻습니다.

> ~/.warp/.mcp.json의 mcpServers 항목 하나: URL 하나와 Authorization 헤더 하나.

## Warp에 대해 알아둘 것

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

### ~/.warp/.mcp.json

Warp는 이 전역 파일의 서버를 알아서 시작합니다. 같은 JSON을 Settings → Agents → MCP servers → + Add에 붙여 넣어도 됩니다.

### URL로 원격 연결

`url` 항목은 Streamable HTTP나 SSE로 연결합니다. 로컬에서는 아무것도 실행되지 않고 Node.js도 필요 없습니다.

### 헤더에 그대로 기입

키는 `Authorization` 헤더에 바로 넣습니다. 커밋하는 프로젝트의 `.warp/.mcp.json`이 아니라 전역 파일에 두세요.

### 자동으로 시작되지 않음

Warp는 클론한 저장소의 `.warp/.mcp.json`을 감지하지만, 각 서버는 여러분이 직접 시작할 때까지 기다립니다. 옵션을 켜면 Claude Code와 Codex 설정에 있는 서버도 읽을 수 있습니다.

## 프로젝트 규칙은 작업 약속입니다. 활용하세요.

```text
# AGENTS.md
- 변경을 완료라고 하기 전에 make test를 실행한다.
- 즉흥 명령 대신 bin/의 스크립트를 쓴다.
```

Warp는 프로젝트 규칙을 `AGENTS.md`(둘 다 있으면 `WARP.md`가 우선)에서 읽고, 전역 규칙을 어디서나 적용합니다. 이런 데 쓰세요:

- 빌드, 테스트, 배포 명령.
- 에이전트가 자꾸 틀리는 규칙.
- 에이전트가 절대 실행하면 안 되는 명령.

규칙은 에이전트에게 일하는 방식을 알려 줍니다. 곧 지울 환경 변수를 어떤 서비스가 아직 읽고 있는지는 알려 주지 못합니다.

## 터미널의 grep이 끝나는 곳

셸 세션이 싸게 배울 수 없는 세 가지.

### // 출력은 스쳐 지나간다

에이전트가 실행하는 grep과 cat은 모두 대화에 쌓입니다. 이백 줄을 출력하는 검색 한 번이 본 작업을 시작하기도 전에 컨텍스트를 씁니다.

### // 일치는 호출자가 아니다

grep은 진짜 호출과 주석, fixture, 다른 클래스의 같은 이름 메서드를 구별하지 못합니다.

### // 셸은 백지에서 시작한다

새 세션은 저장소에 대해 아무것도 모릅니다. Maguyva의 인덱스는 이미 만들어져 있으므로 첫 질문부터 순위가 매겨진 답을 받습니다.

## Warp의 MCP 서버로서의 Maguyva

mcpServers 항목 하나로 Warp의 에이전트가 얻는 것:

- **인덱싱된 저장소에 대한 11개의 도구**: 시맨틱, 구조적(AST), 그래프, 텍스트 검색에 더해 심볼 조회, 의존 요소, 파일 검색까지.
- **파일 경로와 줄 번호가 포함된 답**: 285개 이상의 언어에서, 터미널 창에서 읽을 수 있을 만큼 짧게.
- **읽기만 하는 도구**: Maguyva의 도구는 인덱스를 조회할 뿐, 파일을 수정하거나 명령을 실행하지 않습니다.

> Warp는 에이전트에게 *터미널*을 줍니다.
> Maguyva는 에이전트에게 *코드의 지도*를 줍니다.

## 두 가지 워크플로

먼저 지도에 묻고, 그다음 명령을 실행하세요.

### 01. 실패하는 스크립트를 원인까지 추적하기

```text
warp agent> deploy.sh 실패: BUILD_ID가 설정되지 않음. 어디서 설정하지?

text_pattern_search("BUILD_ID=")
  ci/env.sh:9   export BUILD_ID=...
  docs/deploy.md:31   ← 설명 문서

→ 에이전트는 ci/env.sh를 source하고 배포를 다시 실행합니다.
[exit 0]
```

인덱스 검색 한 번이 저장소 전체를 도는 재귀 grep과 그 출력을 대신합니다.

### 02. 부팅 단계를 바꾸기 전에 호출자 확인하기

```text
warp agent> 시작할 때 마이그레이션 실행을 그만둬도 될까?

dependency_search("runMigrations", dependents)
  호출자 3개: server.ts, worker.ts, scripts/seed.ts

→ 에이전트는 세 곳을 모두 릴리스 단계로 옮깁니다.
[exit 0]
```

호출자 목록이 변경 전에 도착하므로 워커가 옛 스키마로 부팅되지 않습니다.

## Warp에서 설정하기

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

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

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

### 02. ~/.warp/.mcp.json에 Maguyva 추가

`~/.warp/.mcp.json`

```json
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}
```

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

`mgv_xxxx`를 여러분의 API 키로 바꾸고 저장하세요. Settings → Agents → MCP servers에서 서버가 실행 중인지 확인한 뒤, 이미 답을 아는 질문 하나를 해 보세요.

Warp의 [MCP 문서](https://docs.warp.dev/agents/capabilities/mcp/)에서 파일 기반 서버, 공유, 인증을 다룹니다.

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

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