실전 가이드

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

JSON 블록은 MCP tools/call 입력입니다. owner/repo, 브랜치 이름, 심볼 이름을 해당 저장소의 값으로 바꾸세요.

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

• intelligent_search — 코드베이스에 관해 자연어로 질문할 때 여기서 시작하세요. 기본 auto/balanced는 의도를 높은 확신으로 판별할 수 있는 정의 질문을 구조적 검색으로, 참조 또는 영향 질문을 그래프로, 정확히 일치하는 항목을 찾는 질문을 텍스트로 라우팅합니다. 그 외 질문에는 의미 기반 검색과 인덱싱된 텍스트를 사용합니다. 네 가지 검색 방식을 모두 요청하려면 mode=hybrid 또는 auto와 quality=thorough를 사용하세요. 명시적으로 지정한 mode가 quality보다 우선합니다.
• 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, Devin Desktop, Zed 등의 기본 원격 구성을 사용할 수 있습니다.
4. 에이전트에게 "어떤 저장소가 연결되어 있나요?"라고 물어보세요. 인증과 repository_context를 처음부터 끝까지 검증합니다.
5. 답을 평가할 수 있는 실제 질문 하나를 해당 저장소에 대해 물어보세요. 인덱싱된 트리의 파일 경로와 줄 번호가 보여야 합니다.

{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}

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

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

1. 심볼 이름을 안다면 find_symbol를 호출해 정의와 사용 위치를 찾으세요.
2. 작업 설명만 있다면(예: ‘SSO 추가’, ‘결제 Webhook 수정’) get_task_context 또는 intelligent_search로 시작하세요.
3. 공유 심볼을 편집하기 전에 dependency_search로 dependents/impact 분석을 수행해 해당 심볼에 의존하는 코드와 영향을 확인하거나, PR 방식의 영향 분석을 위해 변경 경로를 전달해 영향 범위를 확인하세요.
4. 인용된 파일을 열고(디스크 파일은 로컬에서 읽고, 원격 또는 다른 저장소 경로는 get_file 사용) 실제 코드에 맞춰 계획을 확인하세요.
5. 편집 후 dependency_search에 verify_after_edit=true와 targets 또는 changed_paths를 지정하여 같은 심볼을 다시 확인하세요. 이는 커밋되지 않은 로컬 변경이 아니라 인덱싱된 그래프를 읽습니다. 새 리비전의 근거로 삼기 전에 indexed_commit_sha와 인덱스 최신성을 확인하고 로컬 테스트도 실행하세요.

{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}

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

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

1. intelligent_search와 자연어 질문(예: ‘세션 만료는 어떻게 작동하나요?’, ‘재시도 로직은 어디에 있나요?’)으로 시작하세요.
2. 첫 결과에 불필요한 항목이 많으면 언어 또는 경로 필터로 범위를 좁히세요. language_filter는 auto/hybrid에서 그래프를 제외합니다. 그래프로만 라우팅된 auto 쿼리는 의미 기반 검색과 텍스트 검색으로 대체됩니다. 명시적 그래프 모드와 language_filter를 함께 사용하면 거부됩니다. routing_decision.modalities_used를 확인하면 선택된 검색 계획을 알 수 있습니다. warnings는 서버가 경고를 냈을 때만 나타납니다.
3. 같은 모호한 질문을 반복하지 말고 유망한 결과를 find_symbol 또는 dependency_search로 구체화하세요.
4. 디스크에 없는 특정 인덱싱 경로가 필요할 때만 get_file를 사용하세요.
5. 평소 쓰는 클라이언트 도구로 편집하세요. Maguyva는 탐색과 검증을 위한 것이며 쓰기 도구가 아닙니다.

{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}

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

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

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

{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}

설정 오류: 문제 해결.

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

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

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

• 빠른 시작 — 키, 인덱스, 연결, 처음으로 평가 가능한 답변
• 설치 가이드 — 클라이언트별 MCP 구성
• MCP API 참조 — 모든 도구를 매개변수별로 설명
• 문제 해결 — API 키, 브리지 및 저장소 오류