MCP API 레퍼런스

고객용 Maguyva MCP 도구 11개 전체에 대한 완전한 레퍼런스입니다. 각 도구는 매개변수, 사용 가이드, 적합한 사용 사례 추천을 포함합니다.

API 개요#

Maguyva MCP API는 현재 4개의 주요 카테고리에 걸쳐 11개의 고객용 도구를 제공합니다:

핵심 검색 도구 - 코드베이스 전반에 걸친 고급 검색 기능
구조 및 그래프 도구 - AST 쿼리, 심볼 조회, 의존성 분석
코드 분석 도구 - 심층 코드 분석 및 관계 매핑
시스템 및 유틸리티 도구 - 저장소 컨텍스트, 결정론적 연산, 가이드

모든 도구는 일관된 저장소 식별자 형식을 사용합니다: "owner/repo:branch". 브랜치를 지정하지 않으면 기본값은 main입니다.

MCP 클라이언트가 요청 기본값을 제공하거나 키가 정확히 하나의 저장소에만 접근할 수 있으면 repository을(를) 생략하고, 그 외에는 명시적으로 전달합니다. 저장소가 어떻게 확인되는지 살펴보려면 repository_context(action="info", repository="owner/repo")을(를) 사용합니다.

저장소 매개변수 형식#

모든 MCP 도구는 다음 저장소 식별자 형식을 사용합니다:

브랜치 지정: "owner/repo:branch" - 예: "owner/repository:develop"
기본 브랜치: "owner/repo" - 브랜치를 지정하지 않으면 main 브랜치를 사용합니다 "owner/repository"
요청 또는 단일 저장소 기본값: MCP 클라이언트가 요청 기본값을 제공하거나 키가 정확히 하나의 저장소에만 접근할 수 있으면 저장소를 생략하고, 그 외에는 명시적으로 전달합니다

예시 프롬프트:

특정 저장소에 관해 질문하기:  "owner/my-repo에서 인증 미들웨어를 검색해줘"
접근 가능한 저장소 나열:    "이 Maguyva 키가 접근할 수 있는 저장소는 무엇인가요?"
쿼리 하나만 재정의하기:     "owner/other-repo:develop에서 인증 패턴을 검색해줘"

언어 필터링#

모든 검색 도구는 프로그래밍 언어별로 결과를 필터링할 수 있습니다:

language_filter="python" - Python 파일만 필터링
language_filter="typescript" - TypeScript 파일만 필터링
대소문자 구분: 언어 이름은 소문자로 사용하세요
기본값: 빈 문자열(필터링 없음) - 모든 언어의 결과를 반환합니다
지원 범위: 언어 필터는 지원되는 279개 이상의 언어 및 텍스트 기반 기술 전체에서 작동합니다. 전체 목록은 호환성를 참고하세요.

"Python 파일에서만 인증 미들웨어를 찾아줘"
"TypeScript에서 데이터베이스 연결을 검색해줘"

이 API 레퍼런스는 2026년 7월 22일에 소스 코드로부터 생성되었습니다.

핵심 검색 도구#

intelligent_search안정

코드베이스에 관한 질문은 여기서 시작하세요. 자연어 쿼리(예: "인증은 어떻게 작동하나요", "결제 처리는 어디에 있나요")를 입력하면 인덱싱된 저장소 전체의 시맨틱, 심볼, 구조, 의존성 검색으로 자동 라우팅합니다. 파일을 하나씩 훑지 않고 저장소 전체를 한 번에 검색하므로 탐색과 계획에는 Explore 에이전트와 Grep/Glob보다 우선 사용하세요.

매개변수:

query필수

타입: str
설명: 검색 쿼리

repository선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.

mode선택

타입: Literal[auto, hybrid, semantic, text, structural, ast, graph]
기본값: auto
설명: 검색 모드

limit선택

타입: int
기본값: 10
설명: 이 랭킹된 top-K 윈도우의 최대 결과 수

language_filter선택

타입: str
설명: 언어 필터

path_filter선택

타입: str
설명: 파일 경로 접두사로 필터링

boost_by_importance선택

타입: bool
기본값
설명: 옵트인: 심볼별 그래프 메트릭(is_articulation_point, bridge_count, k_core, centrality 등)을 사용해 중심성 기준으로 재순위화합니다. 에이전트에 안전한 순위화를 위해 기본값은 꺼짐입니다(전역 허브가 구현 관련 결과를 묻히게 할 수 있음). 아키텍처 투어에는 활성화하세요. 각 결과가 심볼과 연결되어 있을 때 4가지 모달리티 전체에 적용됩니다.

branch선택

타입: str
설명: 브랜치 재정의

quality선택

타입: Literal[quick, balanced, thorough]
기본값: balanced
설명: 검색 품질

include_content선택

타입: bool
기본값: true
설명: 결과에 콘텐츠 포함

explain_routing선택

타입: bool
기본값
설명: 라우팅 결정 설명 포함

importance_weight선택

타입: float
기본값: 0.3
설명: 중요도 부스팅 가중치(0=없음, 1=최대)

orphans선택

타입: bool
기본값
설명: 수신 참조가 없는 심볼을 반환합니다(데드 코드일 가능성). 정리 작업에 유용하지만 데코레이터, 내부 함수, CLI 진입점이 포함될 수 있습니다.

include_community_context선택

타입: bool
기본값
설명: 더 넓은 맥락을 위해 같은 코드 커뮤니티에 속한 관련 심볼을 포함합니다. 기능이나 모듈의 동작 방식을 살펴볼 때 유용합니다.

community_depth선택

타입: int
기본값: 1
설명: 커뮤니티 컨텍스트 확장 깊이

graph_view선택

타입: Literal[dependency, type, data_flow, control_flow]
기본값: dependency
설명: 메트릭에 사용할 그래프 뷰

seed_symbol_ids선택

타입: list[str]
설명: Tier-1 작업 시드: 현재 작업의 핵심인 기호 ID입니다. 설정되면 Approach A 깊이 감소 근접성(정확한 시드 일치 + 그래프 가장자리 홉)을 기준으로 융합 히트의 순위를 다시 지정합니다. 추가 — 글로벌 순위를 위해 생략합니다.

seed_file_paths선택

타입: list[str]
설명: Tier-1 작업 시드: 에이전트가 열었거나 방금 편집한 색인화된 파일 경로입니다. 설정되면 1/(1+d) 깊이 감소(동일 파일 → 동일한 디렉토리 → 근처 패키지)를 사용하여 경로 근접성에 따라 융합 적중의 순위를 다시 지정합니다. 추가 — 글로벌 순위를 위해 생략합니다.

매개변수	타입	필수 여부	기본값	설명
`query`	`str`	예	-	검색 쿼리
`repository`	`str`	아니요	-	owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.
`mode`	`Literal[auto, hybrid, semantic, text, structural, ast, graph]`	아니요	`auto`	검색 모드
`limit`	`int`	아니요	`10`	이 랭킹된 top-K 윈도우의 최대 결과 수
`language_filter`	`str`	아니요	-	언어 필터
`path_filter`	`str`	아니요	-	파일 경로 접두사로 필터링
`boost_by_importance`	`bool`	아니요		옵트인: 심볼별 그래프 메트릭(is_articulation_point, bridge_count, k_core, centrality 등)을 사용해 중심성 기준으로 재순위화합니다. 에이전트에 안전한 순위화를 위해 기본값은 꺼짐입니다(전역 허브가 구현 관련 결과를 묻히게 할 수 있음). 아키텍처 투어에는 활성화하세요. 각 결과가 심볼과 연결되어 있을 때 4가지 모달리티 전체에 적용됩니다.
`branch`	`str`	아니요	-	브랜치 재정의
`quality`	`Literal[quick, balanced, thorough]`	아니요	`balanced`	검색 품질
`include_content`	`bool`	아니요	`true`	결과에 콘텐츠 포함
`explain_routing`	`bool`	아니요		라우팅 결정 설명 포함
`importance_weight`	`float`	아니요	`0.3`	중요도 부스팅 가중치(0=없음, 1=최대)
`orphans`	`bool`	아니요		수신 참조가 없는 심볼을 반환합니다(데드 코드일 가능성). 정리 작업에 유용하지만 데코레이터, 내부 함수, CLI 진입점이 포함될 수 있습니다.
`include_community_context`	`bool`	아니요		더 넓은 맥락을 위해 같은 코드 커뮤니티에 속한 관련 심볼을 포함합니다. 기능이나 모듈의 동작 방식을 살펴볼 때 유용합니다.
`community_depth`	`int`	아니요	`1`	커뮤니티 컨텍스트 확장 깊이
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	아니요	`dependency`	메트릭에 사용할 그래프 뷰
`seed_symbol_ids`	`list[str]`	아니요	-	Tier-1 작업 시드: 현재 작업의 핵심인 기호 ID입니다. 설정되면 Approach A 깊이 감소 근접성(정확한 시드 일치 + 그래프 가장자리 홉)을 기준으로 융합 히트의 순위를 다시 지정합니다. 추가 — 글로벌 순위를 위해 생략합니다.
`seed_file_paths`	`list[str]`	아니요	-	Tier-1 작업 시드: 에이전트가 열었거나 방금 편집한 색인화된 파일 경로입니다. 설정되면 1/(1+d) 깊이 감소(동일 파일 → 동일한 디렉토리 → 근처 패키지)를 사용하여 경로 근접성에 따라 융합 적중의 순위를 다시 지정합니다. 추가 — 글로벌 순위를 위해 생략합니다.

적합한 경우:

적합한 도구가 불분명할 때의 인덱스 전체 탐색 또는 콜드 스타트 탐색
시맨틱, 텍스트, 구조, 그래프를 아우르는 멀티모달 융합 랭킹

권장하지 않는 경우:

이미 알고 있는 심볼 이름 — find_symbol을 직접 사용
디스크상의 알려진 경로 — 먼저 로컬 Read/Grep 사용

semantic_search안정

정확한 텍스트가 아니라 의미로 코드를 찾습니다. 키워드나 심볼 이름을 모를 때 "재시도 로직", "사용자 온보딩 흐름" 같은 개념 쿼리에 사용하세요. 중요도에 따라 정렬한 관련 코드 청크를 반환합니다. 개념 검색에는 Grep보다 우선 사용하세요.

매개변수:

query필수

타입: str
설명: 검색 쿼리(개념적, 의미 기반)

repository선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.

limit선택

타입: int
기본값: 5
설명: 이 랭킹된 top-K 윈도우의 최대 결과 수

similarity_threshold선택

타입: float
기본값: 0.6
설명: 최소 유사도 점수

language_filter선택

타입: str
설명: 지정한 프로그래밍 언어로 감지된 파일로 결과를 필터링합니다

path_filter선택

타입: str
설명: 파일 경로 접두사로 필터링

boost_by_importance선택

타입: bool
기본값
설명: 옵트인: PageRank 중심성 기준으로 재순위화합니다(에이전트에 안전한 순위화를 위해 기본값은 꺼짐; 아키텍처 투어에는 활성화).

branch선택

타입: str
설명: 브랜치 재정의(기본값: repository 매개변수 또는 main)

include_content선택

타입: bool
기본값: true
설명: 결과에 청크 콘텐츠 포함

graph_view선택

타입: Literal[dependency, type, data_flow, control_flow]
기본값: dependency
설명: 메트릭에 사용할 그래프 뷰

매개변수	타입	필수 여부	기본값	설명
`query`	`str`	예	-	검색 쿼리(개념적, 의미 기반)
`repository`	`str`	아니요	-	owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.
`limit`	`int`	아니요	`5`	이 랭킹된 top-K 윈도우의 최대 결과 수
`similarity_threshold`	`float`	아니요	`0.6`	최소 유사도 점수
`language_filter`	`str`	아니요	-	지정한 프로그래밍 언어로 감지된 파일로 결과를 필터링합니다
`path_filter`	`str`	아니요	-	파일 경로 접두사로 필터링
`boost_by_importance`	`bool`	아니요		옵트인: PageRank 중심성 기준으로 재순위화합니다(에이전트에 안전한 순위화를 위해 기본값은 꺼짐; 아키텍처 투어에는 활성화).
`branch`	`str`	아니요	-	브랜치 재정의(기본값: repository 매개변수 또는 main)
`include_content`	`bool`	아니요	`true`	결과에 청크 콘텐츠 포함
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	아니요	`dependency`	메트릭에 사용할 그래프 뷰

적합한 경우:

개념적 쿼리("how does auth work?", "caching strategy")
패키지 간 유사도 검색

권장하지 않는 경우:

이미 알고 있는 심볼 이름 — 대신 find_symbol 사용
정확한 문자열이나 오류 메시지 — text_pattern_search 사용

text_pattern_search안정

인덱싱된 콘텐츠를 검색합니다. exact와 regex 모드는 전체 파일/blob 코퍼스를 grep하고, fuzzy content 모드는 범위가 제한된 시맨틱 청크 코퍼스를 검색합니다. file 및 symbol 범위는 fuzzy 전용입니다. 디스크의 좁은 디렉터리를 이미 안다면 로컬 Grep을 사용하세요.

매개변수:

query필수

타입: str
설명: 텍스트 패턴

repository선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.

mode선택

타입: Literal[fuzzy, exact, regex]
기본값: exact
설명: 검색 모드

search_scope선택

타입: Literal[content, symbols, files]
기본값: content
설명: 검색 대상

limit선택

타입: int
기본값: 5
설명: 이 페이지에서 반환되는 최대 결과 수

offset선택

타입: int
설명: 더 이상 사용되지 않는 호환용 offset. pagination.next_cursor의 cursor를 사용하세요.

cursor선택

타입: str
설명: pagination.next_cursor에서 얻은 불투명 cursor. 변경하지 말고 그대로 전달하며 query와 필터도 변경하지 마세요.

language_filter선택

타입: str
설명: 언어 필터

path_filter선택

타입: str
설명: 파일 경로 접두사로 필터링

case_sensitive선택

타입: bool
기본값
설명: 대소문자 구분

branch선택

타입: str
설명: 브랜치 재정의

fuzzy_algorithm선택

타입: Literal[hybrid, trigram, levenshtein]
기본값: hybrid
설명: 퍼지 매칭 알고리즘

threshold선택

타입: float
기본값: 0.05
설명: 퍼지 검색의 최소 유사도 임계값

semantic_fallback선택

타입: bool
기본값
설명: 결과가 없으면 시맨틱 검색으로 폴백

매개변수	타입	필수 여부	기본값	설명
`query`	`str`	예	-	텍스트 패턴
`repository`	`str`	아니요	-	owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.
`mode`	`Literal[fuzzy, exact, regex]`	아니요	`exact`	검색 모드
`search_scope`	`Literal[content, symbols, files]`	아니요	`content`	검색 대상
`limit`	`int`	아니요	`5`	이 페이지에서 반환되는 최대 결과 수
`offset`	`int`	아니요	-	더 이상 사용되지 않는 호환용 offset. pagination.next_cursor의 cursor를 사용하세요.
`cursor`	`str`	아니요	-	pagination.next_cursor에서 얻은 불투명 cursor. 변경하지 말고 그대로 전달하며 query와 필터도 변경하지 마세요.
`language_filter`	`str`	아니요	-	언어 필터
`path_filter`	`str`	아니요	-	파일 경로 접두사로 필터링
`case_sensitive`	`bool`	아니요		대소문자 구분
`branch`	`str`	아니요	-	브랜치 재정의
`fuzzy_algorithm`	`Literal[hybrid, trigram, levenshtein]`	아니요	`hybrid`	퍼지 매칭 알고리즘
`threshold`	`float`	아니요	`0.05`	퍼지 검색의 최소 유사도 임계값
`semantic_fallback`	`bool`	아니요		결과가 없으면 시맨틱 검색으로 폴백

적합한 경우:

정확한 문자열, 오류 메시지, 정규식
근사 텍스트에 대한 트라이그램 퍼지 매칭

권장하지 않는 경우:

디스크상의 알려진 경로 — 로컬 Grep 우선
개념적 쿼리 — semantic_search 사용

구조 및 그래프 도구#

preset=functions|classes|methods|imports|variables(또는 자유로운 pattern=)를 우선 사용하세요. 코드를 텍스트가 아닌 AST 형태로 찾습니다. 중간 계층 필터: name_pattern, node_type, decorator, parent_child. path/ltree/call 계열 필터는 고급 용도입니다. 의도적으로 사용할 때는 advanced=true를 설정하세요. 하위 호환을 위해 평면형 advanced 키도 여전히 허용됩니다. 최소 하나의 구조 선택자를 제공하세요.

매개변수:

repository선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.

preset선택

타입: Literal[functions, classes, methods, imports, variables]
설명: 선호되는 구조 선택자. 언어 간 AST 노드 타입으로 확장됩니다 — functions(각 언어의 function/arrow/method 정의); classes(class/struct/impl 정의); methods(method 정의, method 노드가 없는 언어에서는 function_definition); imports(import/use/include 문); variables(variable/let/const/static 선언). 탐색형 쿼리에서는 자유 형식의 pattern/node_type보다 우선하세요.

pattern선택

타입: str
설명: preset이 너무 거칠 때 사용하는 자유 형식 패턴(자동 감지: 'def foo(' → node_type + name_pattern). 탐색형 쿼리에는 preset=를 우선 사용하세요.

name_pattern선택

타입: str
설명: 심볼 이름 패턴(셸 와일드카드, 범위가 제한된 POSIX 정규식 또는 퍼지 텍스트; 최대 256자)

node_type선택

타입: str
설명: AST 노드 타입(function_definition, class_definition 등) — 일반적인 형태에는 preset=를 우선 사용하세요.

decorator선택

타입: str
설명: 데코레이터 이름 필터

base_class선택

타입: str
설명: 기반 클래스 이름 필터(이 클래스를 상속하는 클래스 검색)

language_filter선택

타입: str
설명: 언어 필터

limit선택

타입: int
기본값: 20
설명: 이 페이지에서 반환되는 최대 결과 수

offset선택

타입: int
설명: 더 이상 사용되지 않는 호환용 offset. pagination.next_cursor의 cursor를 사용하세요.

cursor선택

타입: str
설명: pagination.next_cursor에서 얻은 불투명 cursor. 변경하지 말고 그대로 전달하며 query와 필터도 변경하지 마세요.

path_filter선택

타입: str
설명: 파일 경로 접두사로 필터링

branch선택

타입: str
설명: 브랜치 재정의

query_type선택

타입: Literal[node_type, name_pattern, parent_child]
설명: 명시적 쿼리 유형

parent_type선택

타입: str
설명: 부모 AST 노드 유형 필터

relationship선택

타입: Literal[parent, ancestor]
기본값: parent
설명: parent_child 쿼리: 직접 부모만 또는 모든 조상(클래스 본문/블록 아래 중첩된 클래스 메서드에는 ancestor 사용)

has_modifier선택

타입: str
설명: 수정자로 필터링(export, async, static 등)

advanced선택

타입: bool
기본값
설명: 고급 경로, ltree 또는 호출 필터(ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name)를 의도적으로 사용하는 경우 true를 설정합니다. 기본적으로 false는 에이전트 인터페이스를 사전 설정에 집중하도록 유지합니다. 플랫 형식의 고급 키는 메타데이터 경고와 함께 이전 버전과의 호환성을 위해 계속 작동합니다.

callee_text선택

타입: str
설명: 고급 — preset=functions|classes|methods|imports|variables를 우선 사용하세요. 호출 표현식 callee 텍스트 필터. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.

callee_name선택

타입: str
설명: 고급 — preset=functions|classes|methods|imports|variables를 우선 사용하세요. 호출 표현식 callee 이름 필터. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.

field_role선택

타입: str
설명: 고급 — preset=functions|classes|methods|imports|variables를 우선 사용하세요. AST field role 필터. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.

ltree_ancestor선택

타입: str
설명: 고급 — preset=functions|classes|methods|imports|variables를 우선 사용하세요. AST ltree 조상 경로 필터. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.

ltree_descendant선택

타입: str
설명: 고급 — preset=functions|classes|methods|imports|variables를 우선 사용하세요. AST ltree 자손 경로 필터. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.

definition_name선택

타입: str
설명: 고급 — preset=functions|classes|methods|imports|variables를 우선 사용하세요. 정의 이름 필터. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.

min_depth선택

타입: int
설명: 고급 — preset=functions|classes|methods|imports|variables를 우선 사용하세요. 최소 AST 깊이. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.

max_depth선택

타입: int
설명: 고급 — preset=functions|classes|methods|imports|variables를 우선 사용하세요. 최대 AST 깊이. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.

매개변수	타입	필수 여부	기본값	설명
`repository`	`str`	아니요	-	owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.
`preset`	`Literal[functions, classes, methods, imports, variables]`	아니요	-	선호되는 구조 선택자. 언어 간 AST 노드 타입으로 확장됩니다 — functions(각 언어의 function/arrow/method 정의); classes(class/struct/impl 정의); methods(method 정의, method 노드가 없는 언어에서는 function_definition); imports(import/use/include 문); variables(variable/let/const/static 선언). 탐색형 쿼리에서는 자유 형식의 pattern/node_type보다 우선하세요.
`pattern`	`str`	아니요	-	preset이 너무 거칠 때 사용하는 자유 형식 패턴(자동 감지: 'def foo(' → node_type + name_pattern). 탐색형 쿼리에는 preset=를 우선 사용하세요.
`name_pattern`	`str`	아니요	-	심볼 이름 패턴(셸 와일드카드, 범위가 제한된 POSIX 정규식 또는 퍼지 텍스트; 최대 256자)
`node_type`	`str`	아니요	-	AST 노드 타입(function_definition, class_definition 등) — 일반적인 형태에는 preset=를 우선 사용하세요.
`decorator`	`str`	아니요	-	데코레이터 이름 필터
`base_class`	`str`	아니요	-	기반 클래스 이름 필터(이 클래스를 상속하는 클래스 검색)
`language_filter`	`str`	아니요	-	언어 필터
`limit`	`int`	아니요	`20`	이 페이지에서 반환되는 최대 결과 수
`offset`	`int`	아니요	-	더 이상 사용되지 않는 호환용 offset. pagination.next_cursor의 cursor를 사용하세요.
`cursor`	`str`	아니요	-	pagination.next_cursor에서 얻은 불투명 cursor. 변경하지 말고 그대로 전달하며 query와 필터도 변경하지 마세요.
`path_filter`	`str`	아니요	-	파일 경로 접두사로 필터링
`branch`	`str`	아니요	-	브랜치 재정의
`query_type`	`Literal[node_type, name_pattern, parent_child]`	아니요	-	명시적 쿼리 유형
`parent_type`	`str`	아니요	-	부모 AST 노드 유형 필터
`relationship`	`Literal[parent, ancestor]`	아니요	`parent`	parent_child 쿼리: 직접 부모만 또는 모든 조상(클래스 본문/블록 아래 중첩된 클래스 메서드에는 ancestor 사용)
`has_modifier`	`str`	아니요	-	수정자로 필터링(export, async, static 등)
`advanced`	`bool`	아니요		고급 경로, ltree 또는 호출 필터(ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name)를 의도적으로 사용하는 경우 true를 설정합니다. 기본적으로 false는 에이전트 인터페이스를 사전 설정에 집중하도록 유지합니다. 플랫 형식의 고급 키는 메타데이터 경고와 함께 이전 버전과의 호환성을 위해 계속 작동합니다.
`callee_text`	`str`	아니요	-	고급 — preset=functions\|classes\|methods\|imports\|variables를 우선 사용하세요. 호출 표현식 callee 텍스트 필터. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.
`callee_name`	`str`	아니요	-	고급 — preset=functions\|classes\|methods\|imports\|variables를 우선 사용하세요. 호출 표현식 callee 이름 필터. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.
`field_role`	`str`	아니요	-	고급 — preset=functions\|classes\|methods\|imports\|variables를 우선 사용하세요. AST field role 필터. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.
`ltree_ancestor`	`str`	아니요	-	고급 — preset=functions\|classes\|methods\|imports\|variables를 우선 사용하세요. AST ltree 조상 경로 필터. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.
`ltree_descendant`	`str`	아니요	-	고급 — preset=functions\|classes\|methods\|imports\|variables를 우선 사용하세요. AST ltree 자손 경로 필터. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.
`definition_name`	`str`	아니요	-	고급 — preset=functions\|classes\|methods\|imports\|variables를 우선 사용하세요. 정의 이름 필터. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.
`min_depth`	`int`	아니요	-	고급 — preset=functions\|classes\|methods\|imports\|variables를 우선 사용하세요. 최소 AST 깊이. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.
`max_depth`	`int`	아니요	-	고급 — preset=functions\|classes\|methods\|imports\|variables를 우선 사용하세요. 최대 AST 깊이. path/ltree/call 계열 필터를 의도적으로 사용할 때는 advanced=true를 설정하세요.

적합한 경우:

AST 수준의 구조: 클래스, 데코레이터, 함수/메서드 프리셋
텍스트가 아니라 형태로 코드 찾기

권장하지 않는 경우:

자유 텍스트나 개념적 쿼리 — semantic_search 또는 intelligent_search 사용

dependency_search안정

주요 blast-radius／그래프 표면. 실제 호출／임포트 그래프를 통해 "무엇이 이것을 호출하는가?"／"이것이 무엇을 사용하는가?"에 답합니다. 편집 전 영향 분석에는: analysis_type="dependents" 또는 analysis_type="impact"(incoming, impact의 기본 깊이는 shallow), include_metrics는 기본값이 false(중심성 + refactor_risk가 필요하면 옵트인). PR/diff 영향(P1-8): changed_paths 및／또는 patch(unified diff)를 전달하면 경로별로 심볼을 해석하고 심볼 이름 없이도 간결한 shallow-incoming dependents 페이로드를 반환합니다. 편집 후에는 verify_after_edit=true에 targets 및／또는 changed_paths를 지정하면 영향받은 심볼을 간결하게 다중 루트로 재쿼리합니다. dependencies, centrality, orphans도 지원합니다. analyze_dependencies는 impact 경로의 얇은 별칭입니다 — 새 에이전트에서는 이 도구를 우선 사용하세요.

매개변수:

repository선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.

query선택

타입: str
설명: 심볼 이름 또는 검색어

target선택

타입: str
설명: 심볼 이름(query의 별칭)

changed_paths선택

타입: list[str]
설명: PR/diff 영향(기본값)에 대한 저장소 상대 경로 또는 verify_after_edit=true를 사용하면 편집 후 루트를 확인합니다. PR/diff: 경로당 기호를 확인하고 얕은 수신 종속 항목을 탐색합니다. patch=와 결합될 수 있습니다. 확인: 루트 확인으로 경로당 최대 5개의 기호를 확인합니다(확인 모드 내부에서는 아래쪽으로 제한됨). PR/diff 충격에는 query/target가 필요하지 않습니다.

patch선택

타입: str
설명: PR/diff 영향: diff/git 패치 텍스트가 통합되었습니다. 경로는 diff --git / --- / +++ 헤더에서 구문 분석됩니다. changed_paths와 동일한 컴팩트한 충격 경로.

analysis_type선택

타입: Literal[centrality, dependencies, dependents, impact, orphans]
기본값: dependencies
설명: 분석 모드. impact = 영향 범위(incoming dependents; depth를 생략하면 shallow 깊이). dependents도 영향 분석에 답합니다. changed_paths 또는 patch가 설정되면 분석은 PR/diff 영향으로 강제됩니다. centrality/orphans는 target이 필요하지 않습니다.

depth선택

타입: Literal[shallow, balanced, deep]
기본값: balanced
설명: 순회 깊이. analysis_type=impact 및 PR/diff 영향의 경우 depth를 명시적으로 설정하지 않는 한 실질 기본값은 shallow입니다.

limit선택

타입: int
기본값: 20
설명: 이 페이지에서 반환되는 최대 결과 수

offset선택

타입: int
설명: 더 이상 사용되지 않는 호환용 offset. pagination.next_cursor의 cursor를 사용하세요.

cursor선택

타입: str
설명: pagination.next_cursor에서 얻은 불투명 cursor. 변경하지 말고 그대로 전달하며 query와 필터도 변경하지 마세요.

path_filter선택

타입: str
설명: 대상 심볼 해석을 지정한 파일 경로 접두사로 제한합니다. 반환되는 그래프 관계는 해당 경로 밖으로 이어질 수 있습니다.

language_filter선택

타입: str
설명: 대상 해석과 탐색 결과를 언어로 필터링합니다

direction선택

타입: Literal[outgoing, incoming, both]
설명: 순회 방향(analysis_type 추론 재정의)

relationship_types선택

타입: list[str]
설명: 에지 타입을 필터링합니다(CALL, IMPORT, INHERITS_FROM 등). 비어 있지 않은 목록은 graph_view 기본값을 재정의합니다.

exclude_test_paths선택

타입: bool
기본값: true
설명: 기본값 true: 순회 및 중심성 결과에서 테스트, 픽스처, 벤더, 예제 경로를 제외합니다. 포함하려면 false로 설정하세요. orphan 분석은 항상 자체의 더 엄격한 노이즈 제외를 적용합니다.

exclude_generated_paths선택

타입: bool
기본값
설명: 순회 결과에서 생성된 선언과 빌드, 적용 범위, 캐시, 소스 맵 및 축소된 아티팩트 경로를 제외합니다.

include_module_symbols선택

타입: bool
기본값
설명: 기본적으로 false는 from_name 또는 to_name가 합성 __module__ 기호(모듈 수준 노이즈)인 경우 그래프 가장자리를 제외합니다. 종속 및 종속 관계에 대한 결과에 모듈 수준 에지를 포함하도록 true를 설정합니다.

branch선택

타입: str
설명: 브랜치 재정의

per_hop_limit선택

타입: int
설명: 홉당 최대 관계 수(1-300)

include_metrics선택

타입: bool
기본값
설명: 결과 행에 대한 옵트인 그래프 메트릭(refactor_risk와 함께 간결화). min_centrality>0일 때 메트릭은 내부적으로도 가져오지만, 이 값이 true가 아니면 반환되지 않습니다.

metrics_detail선택

타입: Literal[summary, full]
기본값: summary
설명: include_metrics=true: summary(기본값)가 결정 신호 + refactor_risk를 반환하는 경우; full는 더 큰 선별된 측정항목 세트를 반환합니다.

include_edge_metadata선택

타입: bool
기본값
설명: 원시 에지 메타데이터 및 가중치(대형)를 포함합니다. 컴팩트 충격 탑재량은 이를 해제합니다.

symbol_types선택

타입: list[str]
설명: 반환되는 심볼을 종류로 필터링합니다(function, class, method 등)

exact_match선택

타입: bool
기본값
설명: 심볼 이름의 완전 일치를 요구합니다(대소문자 구분 없음). 퍼지 매칭이 비활성화됩니다

find_similar_patterns선택

타입: bool
기본값
설명: 유사한 사용 패턴 찾기

min_centrality선택

타입: float
기본값: 0
설명: 최소 PageRank 점수. 메트릭은 필터링을 위해 내부적으로 가져오며; graph_metrics는 include_metrics=true일 때만 반환됩니다.

graph_view선택

타입: Literal[dependency, type, data_flow, control_flow]
기본값: dependency
설명: 순회 관계 기본값, 메트릭, 중심성 순위에 사용되는 그래프 뷰; orphan 분석은 모든 뷰에 걸쳐 계산됩니다.

verify_after_edit선택

타입: bool
기본값
설명: P2-7 편집 후 확인 모드: 하나의 컴팩트 다중 루트 응답에서 최근 편집된 기호에 대해 색인화된 영향 그래프를 다시 쿼리합니다. targets 및/또는 changed_paths(또는 target/query)가 필요합니다. 얕은 수신 종속 항목에 대한 기본값입니다. 결과는 색인된 그래프를 반영합니다(실시간 편집이 지연될 수 있음). true인 경우 동일한 changed_paths에 대한 PR/diff 영향보다 우선합니다.

targets선택

타입: list[str]
설명: verify_after_edit=true인 경우: 재검증할 기호 이름(발신자/종속자). 둘 다 제공되는 경우 target/query와 병합됩니다.

매개변수	타입	필수 여부	기본값	설명
`repository`	`str`	아니요	-	owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.
`query`	`str`	아니요	-	심볼 이름 또는 검색어
`target`	`str`	아니요	-	심볼 이름(query의 별칭)
`changed_paths`	`list[str]`	아니요	-	PR/diff 영향(기본값)에 대한 저장소 상대 경로 또는 verify_after_edit=true를 사용하면 편집 후 루트를 확인합니다. PR/diff: 경로당 기호를 확인하고 얕은 수신 종속 항목을 탐색합니다. patch=와 결합될 수 있습니다. 확인: 루트 확인으로 경로당 최대 5개의 기호를 확인합니다(확인 모드 내부에서는 아래쪽으로 제한됨). PR/diff 충격에는 query/target가 필요하지 않습니다.
`patch`	`str`	아니요	-	PR/diff 영향: diff/git 패치 텍스트가 통합되었습니다. 경로는 diff --git / --- / +++ 헤더에서 구문 분석됩니다. changed_paths와 동일한 컴팩트한 충격 경로.
`analysis_type`	`Literal[centrality, dependencies, dependents, impact, orphans]`	아니요	`dependencies`	분석 모드. impact = 영향 범위(incoming dependents; depth를 생략하면 shallow 깊이). dependents도 영향 분석에 답합니다. changed_paths 또는 patch가 설정되면 분석은 PR/diff 영향으로 강제됩니다. centrality/orphans는 target이 필요하지 않습니다.
`depth`	`Literal[shallow, balanced, deep]`	아니요	`balanced`	순회 깊이. analysis_type=impact 및 PR/diff 영향의 경우 depth를 명시적으로 설정하지 않는 한 실질 기본값은 shallow입니다.
`limit`	`int`	아니요	`20`	이 페이지에서 반환되는 최대 결과 수
`offset`	`int`	아니요	-	더 이상 사용되지 않는 호환용 offset. pagination.next_cursor의 cursor를 사용하세요.
`cursor`	`str`	아니요	-	pagination.next_cursor에서 얻은 불투명 cursor. 변경하지 말고 그대로 전달하며 query와 필터도 변경하지 마세요.
`path_filter`	`str`	아니요	-	대상 심볼 해석을 지정한 파일 경로 접두사로 제한합니다. 반환되는 그래프 관계는 해당 경로 밖으로 이어질 수 있습니다.
`language_filter`	`str`	아니요	-	대상 해석과 탐색 결과를 언어로 필터링합니다
`direction`	`Literal[outgoing, incoming, both]`	아니요	-	순회 방향(analysis_type 추론 재정의)
`relationship_types`	`list[str]`	아니요	-	에지 타입을 필터링합니다(CALL, IMPORT, INHERITS_FROM 등). 비어 있지 않은 목록은 graph_view 기본값을 재정의합니다.
`exclude_test_paths`	`bool`	아니요	`true`	기본값 true: 순회 및 중심성 결과에서 테스트, 픽스처, 벤더, 예제 경로를 제외합니다. 포함하려면 false로 설정하세요. orphan 분석은 항상 자체의 더 엄격한 노이즈 제외를 적용합니다.
`exclude_generated_paths`	`bool`	아니요		순회 결과에서 생성된 선언과 빌드, 적용 범위, 캐시, 소스 맵 및 축소된 아티팩트 경로를 제외합니다.
`include_module_symbols`	`bool`	아니요		기본적으로 false는 from_name 또는 to_name가 합성 __module__ 기호(모듈 수준 노이즈)인 경우 그래프 가장자리를 제외합니다. 종속 및 종속 관계에 대한 결과에 모듈 수준 에지를 포함하도록 true를 설정합니다.
`branch`	`str`	아니요	-	브랜치 재정의
`per_hop_limit`	`int`	아니요	-	홉당 최대 관계 수(1-300)
`include_metrics`	`bool`	아니요		결과 행에 대한 옵트인 그래프 메트릭(refactor_risk와 함께 간결화). min_centrality>0일 때 메트릭은 내부적으로도 가져오지만, 이 값이 true가 아니면 반환되지 않습니다.
`metrics_detail`	`Literal[summary, full]`	아니요	`summary`	include_metrics=true: summary(기본값)가 결정 신호 + refactor_risk를 반환하는 경우; full는 더 큰 선별된 측정항목 세트를 반환합니다.
`include_edge_metadata`	`bool`	아니요		원시 에지 메타데이터 및 가중치(대형)를 포함합니다. 컴팩트 충격 탑재량은 이를 해제합니다.
`symbol_types`	`list[str]`	아니요	-	반환되는 심볼을 종류로 필터링합니다(function, class, method 등)
`exact_match`	`bool`	아니요		심볼 이름의 완전 일치를 요구합니다(대소문자 구분 없음). 퍼지 매칭이 비활성화됩니다
`find_similar_patterns`	`bool`	아니요		유사한 사용 패턴 찾기
`min_centrality`	`float`	아니요	`0`	최소 PageRank 점수. 메트릭은 필터링을 위해 내부적으로 가져오며; graph_metrics는 include_metrics=true일 때만 반환됩니다.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	아니요	`dependency`	순회 관계 기본값, 메트릭, 중심성 순위에 사용되는 그래프 뷰; orphan 분석은 모든 뷰에 걸쳐 계산됩니다.
`verify_after_edit`	`bool`	아니요		P2-7 편집 후 확인 모드: 하나의 컴팩트 다중 루트 응답에서 최근 편집된 기호에 대해 색인화된 영향 그래프를 다시 쿼리합니다. targets 및/또는 changed_paths(또는 target/query)가 필요합니다. 얕은 수신 종속 항목에 대한 기본값입니다. 결과는 색인된 그래프를 반영합니다(실시간 편집이 지연될 수 있음). true인 경우 동일한 changed_paths에 대한 PR/diff 영향보다 우선합니다.
`targets`	`list[str]`	아니요	-	verify_after_edit=true인 경우: 재검증할 기호 이름(발신자/종속자). 둘 다 제공되는 경우 target/query와 병합됩니다.

적합한 경우:

공유 심볼을 편집하기 전의 영향 범위/영향 분석
changed_paths 또는 patch를 통한 PR/디프 영향 분석
verify_after_edit를 통한 편집 후 검증

권장하지 않는 경우:

단순한 텍스트나 심볼 조회 — text_pattern_search 또는 find_symbol 사용

코드 분석 도구#

find_symbol안정

함수, 클래스, 변수의 정의와 사용 위치로 이동합니다. 이름(예: "getCurrentUser")을 알 때 사용하세요. Grep보다 빠르고 정확하며 인덱싱된 저장소 전체를 다룹니다. 참조와 중요도 메트릭도 선택적으로 반환합니다.

매개변수:

symbol_name선택

타입: str
설명: 검색할 심볼 이름(선택 사항 — 생략하면 메트릭으로 탐색)

repository선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.

scope선택

타입: Literal[definitions, references, both]
기본값: both
설명: 범위: definitions|references|both

limit선택

타입: int
기본값: 15
설명: 이 페이지에서 반환되는 최대 결과 수

offset선택

타입: int
설명: 더 이상 사용되지 않는 호환용 offset. pagination.next_cursor의 cursor를 사용하세요.

cursor선택

타입: str
설명: pagination.next_cursor에서 얻은 불투명 cursor. 변경하지 말고 그대로 전달하며 query와 필터도 변경하지 마세요.

find_similar선택

타입: bool
기본값
설명: 유사 심볼 찾기

include_metrics선택

타입: bool
기본값
설명: 중심성 메트릭 포함

metrics_detail선택

타입: Literal[summary, full]
기본값: summary
설명: include_metrics=true: summary(기본값)가 결정 신호 + refactor_risk를 반환하는 경우; full는 더 큰 선별된 측정항목 세트를 반환합니다.

path_filter선택

타입: str
설명: 파일 경로 접두사로 필터링

branch선택

타입: str
설명: 브랜치 재정의

symbol_type선택

타입: Literal[function, class, variable, method, constant, module, interface, type]
설명: 심볼 타입 필터

high_impact선택

타입: bool
기본값
설명: 아키텍처적으로 중요한 심볼을 탐색합니다(symbol_name 생략). 기본 모드는 인기도(PageRank 상위 10퍼센타일에서 유틸리티 메가허브를 제외)입니다. 절단점／브리지 컷 정점에는 high_impact_mode=risk를 설정하세요.

high_impact_mode선택

타입: Literal[popularity, risk]
기본값: popularity
설명: high_impact=true인 경우: 인기 = 상위 PageRank 십분위수에서 유틸리티 메가 허브/모듈을 뺀 값; 위험 = SMV bridge_count, k_core 순으로 순위가 매겨진 연결 지점(허브 인기가 아닌 구조적 리팩터링 위험)

in_cycle선택

타입: bool
기본값
설명: 순환 구조 내에서만

exclude_test_paths선택

타입: bool
기본값: true
설명: 그래프 지표로 탐색할 때 순위를 매기기 전에 테스트, fixtures, 타사 코드 및 예제를 제외하세요. 명명된 기호에 의한 조회는 변경되지 않습니다.

매개변수	타입	필수 여부	기본값	설명
`symbol_name`	`str`	아니요	-	검색할 심볼 이름(선택 사항 — 생략하면 메트릭으로 탐색)
`repository`	`str`	아니요	-	owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.
`scope`	`Literal[definitions, references, both]`	아니요	`both`	범위: definitions\|references\|both
`limit`	`int`	아니요	`15`	이 페이지에서 반환되는 최대 결과 수
`offset`	`int`	아니요	-	더 이상 사용되지 않는 호환용 offset. pagination.next_cursor의 cursor를 사용하세요.
`cursor`	`str`	아니요	-	pagination.next_cursor에서 얻은 불투명 cursor. 변경하지 말고 그대로 전달하며 query와 필터도 변경하지 마세요.
`find_similar`	`bool`	아니요		유사 심볼 찾기
`include_metrics`	`bool`	아니요		중심성 메트릭 포함
`metrics_detail`	`Literal[summary, full]`	아니요	`summary`	include_metrics=true: summary(기본값)가 결정 신호 + refactor_risk를 반환하는 경우; full는 더 큰 선별된 측정항목 세트를 반환합니다.
`path_filter`	`str`	아니요	-	파일 경로 접두사로 필터링
`branch`	`str`	아니요	-	브랜치 재정의
`symbol_type`	`Literal[function, class, variable, method, constant, module, interface, type]`	아니요	-	심볼 타입 필터
`high_impact`	`bool`	아니요		아키텍처적으로 중요한 심볼을 탐색합니다(symbol_name 생략). 기본 모드는 인기도(PageRank 상위 10퍼센타일에서 유틸리티 메가허브를 제외)입니다. 절단점／브리지 컷 정점에는 high_impact_mode=risk를 설정하세요.
`high_impact_mode`	`Literal[popularity, risk]`	아니요	`popularity`	high_impact=true인 경우: 인기 = 상위 PageRank 십분위수에서 유틸리티 메가 허브/모듈을 뺀 값; 위험 = SMV bridge_count, k_core 순으로 순위가 매겨진 연결 지점(허브 인기가 아닌 구조적 리팩터링 위험)
`in_cycle`	`bool`	아니요		순환 구조 내에서만
`exclude_test_paths`	`bool`	아니요	`true`	그래프 지표로 탐색할 때 순위를 매기기 전에 테스트, fixtures, 타사 코드 및 예제를 제외하세요. 명명된 기호에 의한 조회는 변경되지 않습니다.

적합한 경우:

알려진 심볼의 정의, 참조, 그래프 지표 확정
symbol_name을 생략했을 때 centrality, high_impact, in_cycle로 탐색

권장하지 않는 경우:

개념적이거나 미지 영역에 대한 쿼리 — intelligent_search 또는 semantic_search 사용

analyze_dependencies안정

dependency_search(dependents/incoming)를 통한 blast-radius 별칭. 새 에이전트에서는 analysis_type="dependents" 또는 "impact"를 지정한 dependency_search를 우선 사용하세요. 기존의 다중 홉 impact 응답 형태(graph, connection_summary, refactor_risk를 포함한 선택적 메트릭)를 유지합니다. 관계 계열을 범위 지정하려면 graph_view를 사용하세요: dependency(기본값), type, data_flow, control_flow.

매개변수:

repository선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.

target필수

타입: str
설명: 분석할 심볼 이름

depth선택

타입: Literal[shallow, balanced, deep]
기본값: balanced
설명: 분석 깊이(별칭 지원: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)

limit선택

타입: int
기본값: 10
설명: 이 페이지에서 반환되는 최대 결과 수

offset선택

타입: int
설명: 더 이상 사용되지 않는 호환용 offset. pagination.next_cursor의 cursor를 사용하세요.

cursor선택

타입: str
설명: pagination.next_cursor에서 얻은 불투명 cursor. 변경하지 말고 그대로 전달하며 query와 필터도 변경하지 마세요.

direction선택

타입: Literal[incoming, outgoing, both]
기본값: incoming
설명: 탐색 방향: 'outgoing' = 이 심볼이 의존하는 것(의존 대상), 'incoming' = 이 심볼에 의존하는 것(의존하는 쪽), 'both' = 전체 맥락. 심볼의 모든 호출자/사용자를 찾으려면 'incoming'을 사용하세요.

relationship_types선택

타입: list[str]
설명: 엣지 유형(CALL, IMPORT, INHERITS_FROM 등)으로 필터링합니다. 제공하면 아래 graph_view에서 파생한 기본값을 항상 재정의합니다.

graph_view선택

타입: Literal[dependency, type, data_flow, control_flow]
기본값: dependency
설명: 그래프 뷰: include_metrics=true일 때 기본 순회 엣지 유형과 메트릭에 사용할 뷰를 모두 결정합니다. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES](기본값), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. relationship_types를 명시하지 않은 경우에만 그 기본값으로 적용됩니다. 도구 간 일관성을 위해 dependency_search의 기존 graph_view 매개변수 이름과 맞췄습니다.

path_filter선택

타입: str
설명: 대상 심볼 해석을 지정한 파일 경로 접두사로 제한합니다. 반환되는 그래프 관계는 해당 경로 밖으로 이어질 수 있습니다.

language_filter선택

타입: str
설명: 결과를 특정 언어로 제한합니다

branch선택

타입: str
설명: 브랜치 재정의

per_hop_limit선택

타입: int
설명: 홉당 최대 관계 수(1-300)

include_metrics선택

타입: bool
기본값
설명: 결과에 그래프 메트릭을 포함하고 각각에 파생 refactor_risk 블록({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons})을 추가합니다. 선택한 뷰에서 단절점이 아니면 위험도는 "low", 적은 엣지를 잇는 단절점이면 "medium", 많은 엣지를 이으면 "high"입니다(경험적으로 검증되지 않은 휴리스틱 임계값). 해당 심볼/뷰에 메트릭 행이 없으면 생략됩니다.

metrics_detail선택

타입: Literal[summary, full]
기본값: summary
설명: include_metrics=true: summary(기본값)가 결정 신호 + refactor_risk를 반환하는 경우; full는 더 큰 선별된 측정항목 세트를 반환합니다.

include_edge_metadata선택

타입: bool
기본값
설명: 원시 에지 메타데이터와 가중치를 포함합니다. 추출기 메타데이터가 클 수 있으므로 기본적으로 비활성화되어 있습니다. 강화 적용 범위는 활성화된 경우 보고됩니다.

exclude_test_paths선택

타입: bool
기본값: true
설명: 기본 true: 반환된 그래프 가장자리에서 테스트, 고정 장치, 공급업체 및 예제 경로를 제외합니다. 이를 포함하도록 false를 설정하십시오.

include_module_symbols선택

타입: bool
기본값
설명: 기본적으로 false는 from_name 또는 to_name가 합성 __module__ 기호인 경우 그래프 가장자리를 제외합니다. 모듈 수준 에지를 포함하도록 true를 설정합니다.

매개변수	타입	필수 여부	기본값	설명
`repository`	`str`	아니요	-	owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.
`target`	`str`	예	-	분석할 심볼 이름
`depth`	`Literal[shallow, balanced, deep]`	아니요	`balanced`	분석 깊이(별칭 지원: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)
`limit`	`int`	아니요	`10`	이 페이지에서 반환되는 최대 결과 수
`offset`	`int`	아니요	-	더 이상 사용되지 않는 호환용 offset. pagination.next_cursor의 cursor를 사용하세요.
`cursor`	`str`	아니요	-	pagination.next_cursor에서 얻은 불투명 cursor. 변경하지 말고 그대로 전달하며 query와 필터도 변경하지 마세요.
`direction`	`Literal[incoming, outgoing, both]`	아니요	`incoming`	탐색 방향: 'outgoing' = 이 심볼이 의존하는 것(의존 대상), 'incoming' = 이 심볼에 의존하는 것(의존하는 쪽), 'both' = 전체 맥락. 심볼의 모든 호출자/사용자를 찾으려면 'incoming'을 사용하세요.
`relationship_types`	`list[str]`	아니요	-	엣지 유형(CALL, IMPORT, INHERITS_FROM 등)으로 필터링합니다. 제공하면 아래 graph_view에서 파생한 기본값을 항상 재정의합니다.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	아니요	`dependency`	그래프 뷰: include_metrics=true일 때 기본 순회 엣지 유형과 메트릭에 사용할 뷰를 모두 결정합니다. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES](기본값), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. relationship_types를 명시하지 않은 경우에만 그 기본값으로 적용됩니다. 도구 간 일관성을 위해 dependency_search의 기존 graph_view 매개변수 이름과 맞췄습니다.
`path_filter`	`str`	아니요	-	대상 심볼 해석을 지정한 파일 경로 접두사로 제한합니다. 반환되는 그래프 관계는 해당 경로 밖으로 이어질 수 있습니다.
`language_filter`	`str`	아니요	-	결과를 특정 언어로 제한합니다
`branch`	`str`	아니요	-	브랜치 재정의
`per_hop_limit`	`int`	아니요	-	홉당 최대 관계 수(1-300)
`include_metrics`	`bool`	아니요		결과에 그래프 메트릭을 포함하고 각각에 파생 refactor_risk 블록({risk: "low"\|"medium"\|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons})을 추가합니다. 선택한 뷰에서 단절점이 아니면 위험도는 "low", 적은 엣지를 잇는 단절점이면 "medium", 많은 엣지를 이으면 "high"입니다(경험적으로 검증되지 않은 휴리스틱 임계값). 해당 심볼/뷰에 메트릭 행이 없으면 생략됩니다.
`metrics_detail`	`Literal[summary, full]`	아니요	`summary`	include_metrics=true: summary(기본값)가 결정 신호 + refactor_risk를 반환하는 경우; full는 더 큰 선별된 측정항목 세트를 반환합니다.
`include_edge_metadata`	`bool`	아니요		원시 에지 메타데이터와 가중치를 포함합니다. 추출기 메타데이터가 클 수 있으므로 기본적으로 비활성화되어 있습니다. 강화 적용 범위는 활성화된 경우 보고됩니다.
`exclude_test_paths`	`bool`	아니요	`true`	기본 true: 반환된 그래프 가장자리에서 테스트, 고정 장치, 공급업체 및 예제 경로를 제외합니다. 이를 포함하도록 false를 설정하십시오.
`include_module_symbols`	`bool`	아니요		기본적으로 false는 from_name 또는 to_name가 합성 __module__ 기호인 경우 그래프 가장자리를 제외합니다. 모듈 수준 에지를 포함하도록 true를 설정합니다.

적합한 경우:

이미 그 응답 형태(graph, connection_summary)에 연결된 레거시 호출자

권장하지 않는 경우:

새로운 에이전트 루프 — 동일한 순회 코어를 공유하는 dependency_search를 우선 사용

get_task_context안정

익숙하지 않은 영역에서 작업을 시작하나요? 작업을 설명하면(예: "add SSO support", "fix the billing webhook") 관련 파일, 코드, 심볼, 의존성을 경계가 있는 한 번의 호출로 묶어 가져옵니다. 시드 파일은 심볼을 정의하지 않더라도 직접 인덱싱된 내용을 제공합니다. 더 많은 결과가 필요하면 해당 계층 전용 검색 도구로 이어가세요.

매개변수:

task_description필수

타입: str
설명: 작업 설명

repository선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.

limit선택

타입: int
기본값: 15
설명: 레이어당 최대 결과 수

scope선택

타입: Literal[semantic, symbols, dependencies, all]
기본값: all
설명: 포함할 컨텍스트 레이어. 유효한 값: 'semantic', 'symbols', 'dependencies', 'all'. 기본값: ['semantic', 'symbols', 'dependencies']

language_filter선택

타입: str
설명: 지정한 프로그래밍 언어로 감지된 파일로 결과를 필터링합니다

path_filter선택

타입: str
설명: 파일 경로 접두사로 필터링

branch선택

타입: str
설명: 브랜치 재정의

include_related_context선택

타입: bool
기본값
설명: 인접 심볼의 관련 컨텍스트 포함

seed_symbol_ids선택

타입: list[str]
설명: 1단계 명시적 시드: 에이전트가 이미 작업의 핵심이라고 알고 있는 심볼 ID(예: 열어 둔 파일의 심볼). dependencies/related_context 레이어에서 키워드로 도출한 시드보다 먼저 순위가 매겨집니다. 추가 방식이므로 현재의 키워드 전용 동작을 유지하려면 생략하세요.

seed_file_paths선택

타입: list[str]
설명: Tier-1 명시적 시드: 에이전트가 열어 두었거나 방금 편집한 인덱싱된 파일 경로. 경계가 있는 직접 파일 증거를 반환하고, 그래프 컨텍스트를 위해 파일당 최대 5개의 심볼을 해석합니다(심볼이 없는 문서와 설정 포함). 부가적입니다 — 키워드 전용 동작을 원하면 생략하세요.

매개변수	타입	필수 여부	기본값	설명
`task_description`	`str`	예	-	작업 설명
`repository`	`str`	아니요	-	owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.
`limit`	`int`	아니요	`15`	레이어당 최대 결과 수
`scope`	`Literal[semantic, symbols, dependencies, all]`	아니요	`all`	포함할 컨텍스트 레이어. 유효한 값: 'semantic', 'symbols', 'dependencies', 'all'. 기본값: ['semantic', 'symbols', 'dependencies']
`language_filter`	`str`	아니요	-	지정한 프로그래밍 언어로 감지된 파일로 결과를 필터링합니다
`path_filter`	`str`	아니요	-	파일 경로 접두사로 필터링
`branch`	`str`	아니요	-	브랜치 재정의
`include_related_context`	`bool`	아니요		인접 심볼의 관련 컨텍스트 포함
`seed_symbol_ids`	`list[str]`	아니요	-	1단계 명시적 시드: 에이전트가 이미 작업의 핵심이라고 알고 있는 심볼 ID(예: 열어 둔 파일의 심볼). dependencies/related_context 레이어에서 키워드로 도출한 시드보다 먼저 순위가 매겨집니다. 추가 방식이므로 현재의 키워드 전용 동작을 유지하려면 생략하세요.
`seed_file_paths`	`list[str]`	아니요	-	Tier-1 명시적 시드: 에이전트가 열어 두었거나 방금 편집한 인덱싱된 파일 경로. 경계가 있는 직접 파일 증거를 반환하고, 그래프 컨텍스트를 위해 파일당 최대 5개의 심볼을 해석합니다(심볼이 없는 문서와 설정 포함). 부가적입니다 — 키워드 전용 동작을 원하면 생략하세요.

적합한 경우:

시드 파일을 시맨틱, 심볼, 의존성 레이어와 결합하는 태스크 인식 컨텍스트

권장하지 않는 경우:

더 특화된 도구가 이미 답을 줄 수 있는 단일 도구 조회

get_file안정

경로로 인덱싱된 저장소에서 파일을 읽습니다. 디스크상의 파일에는 로컬 Read 도구를 우선 사용하세요 — 이 도구는 작업 트리에 없는 교차 저장소 또는 원격 조회에 사용합니다. 선택적 행 범위를 지원하며; token으로 잘린 응답은 metadata.next_line_start부터 이어가세요.

매개변수:

file_path필수

타입: str
설명: 저장소 루트 기준 파일 경로

repository선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.

line_start선택

타입: int
설명: 시작 줄(1부터 시작)

line_end선택

타입: int
설명: 종료 행(1부터 시작, 경계 포함; line_start 이상이어야 함)

branch선택

타입: str
설명: 브랜치 재정의

max_tokens선택

타입: int
기본값: 5000
설명: 최대 토큰 수

include_metadata선택

타입: bool
기본값: true
설명: 메타데이터 포함

매개변수	타입	필수 여부	기본값	설명
`file_path`	`str`	예	-	저장소 루트 기준 파일 경로
`repository`	`str`	아니요	-	owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 응답에는 사용된 저장소가 표시됩니다.
`line_start`	`int`	아니요	-	시작 줄(1부터 시작)
`line_end`	`int`	아니요	-	종료 행(1부터 시작, 경계 포함; line_start 이상이어야 함)
`branch`	`str`	아니요	-	브랜치 재정의
`max_tokens`	`int`	아니요	`5000`	최대 토큰 수
`include_metadata`	`bool`	아니요	`true`	메타데이터 포함

적합한 경우:

원격 또는 인덱싱된 파일 스냅샷(행 범위, 토큰 한도)

권장하지 않는 경우:

이미 로컬 디스크에 있는 경로 — 로컬 Read 도구 사용

시스템 및 유틸리티 도구#

repository_context안정

검색할 수 있는 저장소를 나열하거나 그중 하나의 신원 정보(namespace/branch, indexed_commit_sha／인덱스 신선도)를 가져옵니다. 검색 도구가 받아들이는 정확한 저장소 slug를 알려면 action:"list"로 한 번 호출하세요. (키에 저장소가 하나뿐이면 검색 도구가 이를 기본값으로 사용하므로 생략할 수 있습니다.) namespace 전체의 파일／blob／에지 수는 include_statistics=true로 옵트인할 수 있습니다.

매개변수:

action필수

타입: Literal[list, info]
설명: 작업: 사용 가능한 저장소 나열 또는 저장소 정보 조회

repository선택

타입: str
설명: owner/repo 또는 owner/repo:branch 형식의 저장소(info 작업에 필요)

branch선택

타입: str
설명: 브랜치 재정의

pattern선택

타입: str
설명: 필터 패턴

include_statistics선택

타입: bool
기본값
설명: 옵트인: namespace 전체의 인덱싱된 데이터 수(파일／blob／에지)를 포함합니다. 기본값 false — 저장소 신원에는 이 느린 집계가 필요하지 않습니다.

limit선택

타입: int
기본값: 20
설명: 이 페이지에서 반환되는 최대 결과 수

offset선택

타입: int
설명: 더 이상 사용되지 않는 호환성 오프셋입니다. pagination.next_cursor보다 cursor를 선호하세요.

cursor선택

타입: str
설명: pagination.next_cursor의 불투명 cursor. 변경하지 않고 전달하고 쿼리와 필터를 변경하지 않고 유지합니다.

매개변수	타입	필수 여부	기본값	설명
`action`	`Literal[list, info]`	예	-	작업: 사용 가능한 저장소 나열 또는 저장소 정보 조회
`repository`	`str`	아니요	-	owner/repo 또는 owner/repo:branch 형식의 저장소(info 작업에 필요)
`branch`	`str`	아니요	-	브랜치 재정의
`pattern`	`str`	아니요	-	필터 패턴
`include_statistics`	`bool`	아니요		옵트인: namespace 전체의 인덱싱된 데이터 수(파일／blob／에지)를 포함합니다. 기본값 false — 저장소 신원에는 이 느린 집계가 필요하지 않습니다.
`limit`	`int`	아니요	`20`	이 페이지에서 반환되는 최대 결과 수
`offset`	`int`	아니요	-	더 이상 사용되지 않는 호환성 오프셋입니다. pagination.next_cursor보다 cursor를 선호하세요.
`cursor`	`str`	아니요	-	pagination.next_cursor의 불투명 cursor. 변경하지 않고 전달하고 쿼리와 필터를 변경하지 않고 유지합니다.

적합한 경우:

접근 가능한 저장소 목록 표시
저장소 식별, 브랜치, HEAD 대 인덱스 최신성 확인

권장하지 않는 경우:

기본적으로 네임스페이스 전체 통계 — 확인보다 느릴 수 있으므로 include_statistics=true를 명시적으로 전달

ask_maguyva안정

Maguyva 도움말 및 피드백. 주요 용도: 도구 안내를 받거나 Maguyva 관리자를 위해 저장되는 버그 리포트／기능 요청을 제출합니다. 피드백에 비밀 정보나 민감한 개인 데이터를 포함하지 마세요. evaluate 작업은 하위 호환용으로만 남아 있습니다 — 계산／해시／문자열 작업에는 로컬 계산이나 호스트 도구를 우선 사용하세요.

매개변수:

operation필수

타입: Literal[guidance, report_bug, request_feature, evaluate]
설명: 주요 용도: guidance, report_bug, request_feature. 레거시／호환 전용: evaluate(결정론적 표현식 엔진; 주요 에이전트 워크플로의 일부가 아님).

query선택

타입: str
설명: 안내 주제(예: tool_selection, semantic_search). 레거시 evaluate 전용: 표현식 문자열.

description선택

타입: str
설명: report_bug와 request_feature에 필수입니다. Maguyva 관리자를 위한 자유 형식 피드백입니다. 비밀 정보나 민감한 개인 데이터를 포함하지 마세요.

related_tool선택

타입: Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
설명: 피드백과 가장 밀접하게 관련된 선택적 Maguyva 도구

매개변수	타입	필수 여부	기본값	설명
`operation`	`Literal[guidance, report_bug, request_feature, evaluate]`	예	-	주요 용도: guidance, report_bug, request_feature. 레거시／호환 전용: evaluate(결정론적 표현식 엔진; 주요 에이전트 워크플로의 일부가 아님).
`query`	`str`	아니요	-	안내 주제(예: tool_selection, semantic_search). 레거시 evaluate 전용: 표현식 문자열.
`description`	`str`	아니요	-	report_bug와 request_feature에 필수입니다. Maguyva 관리자를 위한 자유 형식 피드백입니다. 비밀 정보나 민감한 개인 데이터를 포함하지 마세요.
`related_tool`	`Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]`	아니요	-	피드백과 가장 밀접하게 관련된 선택적 Maguyva 도구

적합한 경우:

도구 안내(operation="guidance")
Maguyva 관리자를 위한 지속적인 버그 리포트와 기능 요청

권장하지 않는 경우:

수학/해시/문자열 계산 — evaluate 작업은 레거시/하위 호환 전용이므로 로컬 호스트 계산을 우선

모범 사례#

명시적 재정의를 신중하게 사용: MCP 클라이언트가 요청 기본값을 제공하거나 키가 정확히 하나의 저장소에만 접근할 수 있으면 저장소를 생략하고, 그 외에는 명시적으로 전달하세요.
올바른 검색 모드 선택하기: 대부분의 경우 mode="auto"와 함께 intelligent_search를 사용하세요. 정확히 무엇이 필요한지 안다면 모드를 직접 지정하세요.
언어 필터 활용하기: language_filter를 사용해 결과 범위를 좁히고 성능을 개선하세요.
GraphRAG 부스팅: GraphRAG 중요도 부스팅은 랭킹을 에이전트에 안전하게 유지하기 위해 시맨틱 검색에서 기본적으로 비활성화되어 있습니다(boost_by_importance=false). 아키텍처 투어에서는 boost_by_importance=true를 전달해 중심성 기반 재랭킹을 활성화하세요.
저장소 매칭은 대소문자를 구분하지 않으며 퍼지가 아닙니다: repository_context는 저장소 이름을 대소문자를 구분하지 않고 매칭합니다. 오타를 교정하지는 않습니다. 이름이 어떻게 해석되었는지는 info 액션의 metadata.resolution_reason("exact" 대 "corrected")에서 확인하세요.
도구 조합하기: 여러 API 메서드를 함께 사용해 포괄적인 분석을 수행하세요.
큰 결과 처리하기: limit와 도구별 페이징 제어(예: get_file의 line_start/line_end)를 사용하세요.
도구 안내에는 ask_maguyva 사용하기: ask_maguyva의 evaluate 연산(해시, base64, JSON, 수학)은 레거시/하위 호환 전용입니다. 로컬 도구 우선 매트릭스와 도구별 전체 치트시트를 얻으려면 대신 ask_maguyva를 operation="guidance"와 query="tool_selection"로 호출하세요.
편집 전후로 영향 확인하기: 공유 심볼을 편집하기 전에 dependency_search를 analysis_type="impact"로 호출하여(또는 PR/diff 영향을 보려면 changed_paths를 전달하여) 그 영향 범위를 확인하세요. 편집 후에는 verify_after_edit=true를 targets 또는 changed_paths와 함께 설정하면 동일한 심볼을 간결하게 다시 확인할 수 있습니다.

성능 특성#

작업	성능 관련 참고
시맨틱 검색	1초 미만이지만 매번 실시간 임베딩 API 호출을 포함합니다(캐시되지 않음). 벡터 쿼리에 더해 추가 지연 시간이 발생할 수 있습니다
텍스트 검색	exact/regex는 1초 미만입니다. 퍼지 콘텐츠 검색은 클라이언트 측에서 페이지를 나누므로 깊은 오프셋일수록 비용이 커집니다. path_filter/language_filter로 범위를 좁히세요
구조 검색	AST로 인덱싱되어 있어 비용은 저장소 크기가 아니라 결과 개수에 비례합니다
의존성 검색	비용은 깊이에 비례합니다. 멀티홉 컨텍스트가 필요하지 않다면 depth="shallow"를 권장합니다. per_hop_limit로 확산을 제한합니다
파일 조회	단일 파일은 거의 즉시입니다. 큰 파일은 한 번에 크게 가져오지 말고 line_start/line_end 또는 max_tokens로 페이지를 나누세요
저장소 컨텍스트	네임스페이스 해석은 요청 단위로만 캐시되며 호출 간에는 유지되지 않습니다. 도구를 호출할 때마다 다시 해석합니다
ask_maguyva (guidance / evaluate)	거의 즉시입니다. 데이터베이스 호출 없이 Worker 내에서 실행됩니다

오류 처리#

모든 API 메서드는 구조화된 응답 형식을 반환합니다:

status: 문자열 — "success" 또는 "error". 저하된 매칭 및 신선도 신호는 repository_context의 metadata.resolution_reason이나 metadata.index_freshness.status와 같은 중첩 필드에 들어 있습니다.
tool: 응답을 생성한 도구의 이름
data: 성공 시 결과 페이로드(구조는 도구에 따라 다름)
error: status가 "error"일 때의 구조화된 오류 객체 — type, message, suggestions, recovery_actions를 포함합니다
metadata: 작업에 관한 추가 정보(라우팅, 캐싱, 매개변수 조정)
pagination: 목록 응답에 존재합니다 — has_more와 next_cursor를 포함합니다

결과를 처리하기 전에 항상 status 필드를 확인하세요. 값은 언제나 "success" 또는 "error"뿐입니다. 저하된 매칭이나 신선도 신호는 대신 중첩 필드를 읽으세요: repository_context의 metadata.resolution_reason, 또는 metadata.index_freshness.status(known/partial/unknown/unavailable).

시작하기#

MCP 클라이언트 설정: MCP 클라이언트가 Maguyva 서버 엔드포인트를 가리키도록 설정하세요
저장소 접근 확인: repository_context의 list 또는 info를 사용해 API 키가 접근할 수 있는 저장소를 확인합니다
검색 시작하기: intelligent_search로 시작해서 필요에 따라 전문 도구를 탐색하세요
도구 조합하기: 여러 도구를 함께 사용해 포괄적인 코드 분석을 수행하세요

자세한 연동 방법은 설치 가이드를 참고하세요.

MCP API 레퍼런스

API 개요#

저장소 매개변수 형식#

언어 필터링#

핵심 검색 도구#

intelligent_search안정

semantic_search안정

text_pattern_search안정

구조 및 그래프 도구#

structural_search안정

dependency_search안정

코드 분석 도구#

find_symbol안정

analyze_dependencies안정

get_task_context안정

get_file안정

시스템 및 유틸리티 도구#

repository_context안정

ask_maguyva안정

모범 사례#

성능 특성#

오류 처리#

시작하기#