본문으로 건너뛰기

실전 가이드

일상적인 Maguyva MCP 작업을 위한 실용적인 레시피입니다. 각 레시피는 도구와 순서를 설명하지만 전체 매개변수 참조는 아닙니다. 도구 매개변수는 MCP API 참조, 최초 설정은 빠른 시작를 참고하세요.

알맞은 도구 선택#

대부분의 질문은 한 번의 호출로 시작합니다. 첫 답변이 너무 넓거나 빈약할 때만 다음 단계로 넘어가세요.

  • intelligent_search — 자연어로 코드베이스를 묻는 모든 질문은 여기서 시작합니다. 시맨틱, 심볼, 구조 및 종속성 검색으로 자동 라우팅합니다.
  • find_symbol — 함수, 클래스 또는 변수 이름을 이미 알고 있을 때 사용합니다.
  • dependency_search — 편집 전후의 영향 범위, 즉 호출자, 종속 항목 및 영향을 확인합니다.
  • get_task_context — 낯선 영역에서 작업 설명과 관련된 파일, 심볼, 종속성을 하나의 제한된 묶음으로 가져옵니다.
  • repository_context — 접근 가능한 저장소를 나열하거나 저장소 이름이 어떻게 해석되는지 확인합니다.
  • operation="guidance"와 함께 쓰는 ask_maguyva — 저장소를 변경하지 않고 도구 선택과 Maguyva 사용법을 로컬에서 안내합니다.

클라이언트 설치 및 확인#

MCP 클라이언트에 Maguyva를 연결하고 실제 저장소 목록으로 연결을 확인합니다.

  1. app.maguyva.ai에서 API 키를 만드세요. 키는 mgv_로 시작합니다.
  2. 이미 잘 아는 GitHub 저장소를 하나 이상 연결하고 인덱싱하세요.
  3. 설치 가이드에 따라 클라이언트를 설정하세요. Claude Code 플러그인이나 Cursor, VS Code, Windsurf, Zed 등의 기본 원격 구성을 사용할 수 있습니다.
  4. 에이전트에게 "어떤 저장소가 연결되어 있나요?"라고 물어보세요. 인증과 repository_context를 처음부터 끝까지 검증합니다.
  5. 답을 평가할 수 있는 실제 질문 하나를 해당 저장소에 대해 물어보세요. 인덱싱된 트리의 파일 경로와 줄 번호가 보여야 합니다.

키, 브리지 또는 누락된 저장소에서 막혔나요? 문제 해결를 확인하세요.

편집하기 전에 질문하기#

공유 코드를 변경하기 전에 심볼과 영향 범위를 파악하세요. Maguyva 도구는 저장소를 수정하지 않으며, 클라이언트가 로컬에서 수행할 편집에 근거를 제공합니다.

  1. 심볼 이름을 안다면 find_symbol를 호출해 정의와 사용 위치를 찾으세요.
  2. 작업 설명만 있다면(예: ‘SSO 추가’, ‘결제 Webhook 수정’) get_task_context 또는 intelligent_search로 시작하세요.
  3. 공유 심볼을 편집하기 전에 dependency_search로 종속 항목과 영향을 분석하거나, PR 방식의 영향 분석을 위해 변경 경로를 전달해 영향 범위를 확인하세요.
  4. 인용된 파일을 열고(디스크 파일은 로컬에서 읽고, 원격 또는 다른 저장소 경로는 get_file 사용) 실제 코드에 맞춰 계획을 확인하세요.
  5. 편집 후 같은 심볼을 dependency_search로 다시 확인하세요. 클라이언트가 지원하면 편집 후 검증 플래그도 사용해 호출자가 예상대로 해석되는지 확인합니다.

전체 매개변수: MCP API 참조.

검색한 다음 변경하기#

기본 에이전트 루프: 탐색 → 심볼 확정 → 근거를 바탕으로 편집.

  1. intelligent_search와 자연어 질문(예: ‘세션 만료는 어떻게 작동하나요?’, ‘재시도 로직은 어디에 있나요?’)으로 시작하세요.
  2. 첫 결과가 시끄럽다면 언어나 경로 필터로 범위를 좁히세요.
  3. 같은 모호한 질문을 반복하지 말고 유망한 결과를 find_symbol 또는 dependency_search로 구체화하세요.
  4. 디스크에 없는 특정 인덱싱 경로가 필요할 때만 get_file를 사용하세요.
  5. 평소 쓰는 클라이언트 도구로 편집하세요. Maguyva는 탐색과 검증을 위한 것이며 쓰기 도구가 아닙니다.

이 루프가 효과적인 이유: 작동 방식.

결과가 비어 있거나 부족할 때#

도구가 유용한 결과를 내놓지 않으면 쿼리를 끝없이 고쳐 쓰기 전에 해석과 인덱싱부터 바로잡으세요.

  1. app.maguyva.ai에서 저장소가 연결되어 있고 인덱싱이 완료되었는지 확인하세요.
  2. 저장소 문자열을 확인하세요. "owner/repo"는 기본 브랜치를 사용하고 "owner/repo:branch"는 브랜치를 고정합니다. 대소문자는 구분하지 않지만 퍼지 매칭은 아니므로 오타는 자동 수정되지 않습니다.
  3. action="info"와 함께 repository_context를 호출하고 metadata.resolution_reason 같은 해석 메타데이터를 확인하세요.
  4. MCP 클라이언트가 요청 기본값을 제공하거나 키가 정확히 하나의 저장소에만 접근할 수 있을 때만 repository를 생략하세요. 그 외에는 명시적으로 전달해야 합니다.
  5. 더 구체적인 질문, find_symbol에 전달할 알려진 심볼 이름, 또는 언어/경로 필터로 다시 시도하세요. 연결 자체가 고장 났다면 문제 해결를 사용하세요.

설정 오류: 문제 해결.

여러 저장소에서 작업하기#

하나의 키로 여러 저장소를 볼 수 있을 때 올바른 인덱싱 저장소를 지정합니다.

  1. action="list"와 함께 repository_context를 한 번 호출해 키가 검색할 수 있는 정확한 슬러그를 확인하세요.
  2. 기본이 아닌 저장소가 필요하면 검색 및 심볼 도구에 repository를 명시적으로 전달하세요(예: "owner/other-repo" 또는 "owner/other-repo:develop").
  3. 별도 호출에서 의도적으로 저장소를 비교하는 경우가 아니라면 질문 하나는 저장소 하나만 대상으로 하세요.
  4. 파일이 현재 작업 트리가 아닌 인덱싱된 저장소에 있다면 get_file를 사용하세요.
  5. 기억하세요. 도구는 GitHub에 다시 쓰지 않습니다. 여러 저장소 컨텍스트는 읽기와 계획에만 사용됩니다.

저장소 형식 세부 정보: MCP API 참조.

Maguyva가 처음인가요? 먼저 빠른 시작를 완료한 뒤 일상 작업 루프가 필요할 때 여기로 돌아오세요.

다음 단계#