MCP API 레퍼런스

Maguyva의 MCP 도구 11개와 매개변수, 각 도구의 용도를 살펴보세요. 사용할 수 있는 인수는 연결된 클라이언트의 tools/list 응답에서 확인하세요.

API 개요

도구는 4개 범주로 나뉩니다:

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

저장소를 인수로 받는 도구에는 다음 저장소 식별자 형식을 사용하세요: "owner/repo:branch". 브랜치를 지정하지 않으면 main가 기본값입니다.

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

저장소 매개변수 형식

저장소를 지정할 때 다음 형식을 사용하세요:

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

예시 프롬프트:

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

언어 필터링

지원되는 검색 모드에서 language_filter를 사용하세요. text_pattern_search는 search_scope="content"를 선택하고, get_task_context는 시드나 관련 컨텍스트 없이 scope="semantic"를 사용하세요.

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

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

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

핵심 검색 도구

intelligent_search 안정

코드베이스에 관한 질문은 여기서 시작하세요. 기본 auto/balanced는 의도를 높은 확신으로 판별할 수 있는 정의 질문을 구조적 검색으로, 참조 또는 영향 질문을 그래프로, 정확히 일치하는 항목을 찾는 질문을 텍스트로 라우팅합니다. 그 외 질문에는 의미 기반 검색과 인덱싱된 텍스트를 사용합니다. 네 가지 검색 방식을 모두 요청하려면 mode=hybrid 또는 auto와 quality=thorough를 사용하세요. 명시적으로 지정한 mode가 quality보다 우선합니다. language_filter는 auto/hybrid에서 그래프를 제외하며, 명시적 mode=graph와 함께 사용하면 거부됩니다. 아직 경로를 모른다면 Grep/Glob보다 이 도구를 우선 사용하세요.

매개변수:

query 필수

타입: str minLength=1
설명: 검색 쿼리

repository 선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 정확히 일치하는 인덱싱된 브랜치가 우선 사용됩니다. 사용할 수 없는 브랜치는 main 또는 접근 가능한 유일한 브랜치로 대체될 수 있습니다. 응답 메타데이터에는 요청된 항목과 실제로 해석된 항목이 표시되며, 대체가 발생하면 경고가 표시됩니다.

mode 선택

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

limit 선택

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

language_filter 선택

타입: str
설명: 언어 필터

path_filter 선택

타입: str
설명: 파일 경로 접두사로 검색 후보를 필터링합니다. 그래프의 이웃 노드와 함께 제공되는 커뮤니티 컨텍스트에는 이 접두사 범위 밖의 파일이 포함될 수 있습니다.

boost_by_importance 선택

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

branch 선택

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

quality 선택

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

include_content 선택

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

explain_routing 선택

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

importance_weight 선택

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

orphans 선택

타입: bool
기본값: false
설명: 다른 곳에서 참조하지 않는 고아 심볼도 포함

include_community_context 선택

타입: bool
기본값: false
설명: 같은 코드 커뮤니티의 관련 심볼 포함

community_depth 선택

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

graph_view 선택

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

seed_symbol_ids 선택

타입: list[str] maxItems=20
설명: Tier-1 작업 시드: 현재 작업의 핵심인 심볼 ID입니다. 설정하면 Approach A의 깊이 감쇠 근접도(정확한 시드 일치 + 그래프 엣지를 따라 이동한 홉 수)로 융합 결과의 순위를 다시 매깁니다. 추가적인 순위 기준이므로 전역 순위를 사용하려면 이 매개변수를 생략하세요.

seed_file_paths 선택

타입: list[str] maxItems=10
설명: Tier-1 작업 시드: 에이전트가 열어 두었거나 방금 편집한 인덱싱된 파일 경로입니다. 설정하면 1/(1+d) 깊이 감쇠(같은 파일 → 같은 디렉터리 → 인접 패키지)를 적용한 경로 근접도로 융합 결과의 순위를 다시 매깁니다. 추가적인 순위 기준이므로 전역 순위를 사용하려면 이 매개변수를 생략하세요.

적합한 경우:

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

권장하지 않는 경우:

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

semantic_search 안정

정확한 텍스트가 아닌 의미로 코드를 찾습니다. 키워드나 심볼 이름을 모를 때 '재시도 로직', '사용자 온보딩 흐름' 같은 개념 검색에 사용하세요. 파일 다양성을 제한한 관련 청크를 반환하며, 그래프 중요도 재정렬은 boost_by_importance로 선택해서 켭니다. 개념 검색에서는 Grep보다 우선하세요.

매개변수:

query 필수

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

repository 선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 정확히 일치하는 인덱싱된 브랜치가 우선 사용됩니다. 사용할 수 없는 브랜치는 main 또는 접근 가능한 유일한 브랜치로 대체될 수 있습니다. 응답 메타데이터에는 요청된 항목과 실제로 해석된 항목이 표시되며, 대체가 발생하면 경고가 표시됩니다.

limit 선택

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

similarity_threshold 선택

타입: float minimum=0, maximum=1
기본값: 0.6
설명: 최소 유사도 점수

language_filter 선택

타입: str
설명: 언어 필터(python, typescript 등)

path_filter 선택

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

boost_by_importance 선택

타입: bool
기본값: false
설명: 선택해서 활성화: 심볼별로 정규화한 그래프 중요도로 재정렬합니다(기본값 꺼짐, 유사도의 1.5배로 제한).

branch 선택

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

include_content 선택

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

graph_view 선택

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

적합한 경우:

개념적 쿼리("인증은 어떻게 작동하나요?", "캐싱 전략")
패키지 간 유사도 검색

권장하지 않는 경우:

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

text_pattern_search 안정

인덱싱된 콘텐츠를 검색합니다. exact와 regex 모드는 전체 파일/blob 코퍼스를 grep하고, fuzzy content 모드는 범위가 제한된 시맨틱 청크 코퍼스를 검색합니다. file 및 symbol 범위는 트라이그램 전용이며 기본 mode=exact는 fuzzy로 변환됩니다. 언어, 대소문자, 사용자 지정 임계값 제어에는 content 범위가 필요합니다. 파일 경로 필터는 제한된 후보 창을 사용하며 불완전한 검색 범위를 보고합니다. 디스크의 좁은 디렉터리에는 로컬 Grep을 사용하세요.

매개변수:

query 필수

타입: str minLength=1
설명: 텍스트 패턴

repository 선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 정확히 일치하는 인덱싱된 브랜치가 우선 사용됩니다. 사용할 수 없는 브랜치는 main 또는 접근 가능한 유일한 브랜치로 대체될 수 있습니다. 응답 메타데이터에는 요청된 항목과 실제로 해석된 항목이 표시되며, 대체가 발생하면 경고가 표시됩니다.

mode 선택

타입: Literal[fuzzy, exact, regex]
기본값: exact
설명: 검색 모드. 정규식은 PostgreSQL의 고급/POSIX 구문을 사용하여 실행됩니다. 단어 경계에는 \y를 사용하세요(\b는 백스페이스를 의미합니다). 패턴은 JavaScript 안전성 검증기도 통과해야 하므로 인라인 (?i) 플래그와 같은 PostgreSQL 전용 구문은 거부됩니다. 대신 case_sensitive를 사용하세요.

search_scope 선택

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

limit 선택

타입: int minimum=1, maximum=50
기본값: 5
설명: cursor를 사용하지 않을 때 페이지당 최대 결과 수. 연속 조회는 cursor에 저장된 페이지 크기를 사용합니다. 다른 limit로 시작하려면 cursor를 생략하세요.

offset 선택

타입: int minimum=0
설명: 하위 호환용 offset(사용 중단 권장). pagination.next_cursor에서 받은 cursor를 우선 사용하세요.

cursor 선택

타입: str
설명: pagination.next_cursor에서 받은 불투명한 cursor. 값을 그대로 전달하고 query와 필터도 변경하지 마세요. 이 cursor의 위치와 페이지 크기가 offset과 limit보다 우선합니다.

language_filter 선택

타입: str
설명: 언어 필터

path_filter 선택

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

case_sensitive 선택

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

branch 선택

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

fuzzy_algorithm 선택

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

threshold 선택

타입: float minimum=0, maximum=1
기본값: 0.05
설명: 퍼지 검색의 최소 유사도 임계값

semantic_fallback 선택

타입: bool
기본값: false
설명: 첫 번째 어휘 검색 결과가 비어 있으면 시맨틱 검색을 시도합니다. metadata.fallback_status로 used, empty, unavailable 중 어떤 폴백 상태인지 구분할 수 있습니다.

적합한 경우:

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

권장하지 않는 경우:

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

구조 및 그래프 도구

structural_search 안정

preset=functions|classes|methods|imports|variables 또는 자유 형식의 pattern=를 우선 사용하세요. 텍스트가 아닌 AST 형태로 코드를 찾습니다. 중간 수준 필터는 name_pattern, node_type, decorator, parent_child입니다. 경로·ltree·호출 필터는 고급 기능이므로 의도적으로 사용할 때 advanced=true를 설정하세요. 설정하지 않아도 고급 필터는 적용되지만 메타데이터 경고가 추가됩니다. 구조 선택자를 하나 이상 지정하세요.

매개변수:

repository 선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 정확히 일치하는 인덱싱된 브랜치가 우선 사용됩니다. 사용할 수 없는 브랜치는 main 또는 접근 가능한 유일한 브랜치로 대체될 수 있습니다. 응답 메타데이터에는 요청된 항목과 실제로 해석된 항목이 표시되며, 대체가 발생하면 경고가 표시됩니다.

preset 선택

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

pattern 선택

타입: str
설명: 다른 셀렉터가 지정되지 않은 부분을 자유 형식의 pattern으로 채웁니다(자동 감지: 'def foo(' → node_type + name_pattern). preset과 함께 사용할 수 있으며, 명시적인 셀렉터가 우선합니다. 탐색용 쿼리에는 preset= 사용을 권장합니다.

name_pattern 선택

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

node_type 선택

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

decorator 선택

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

base_class 선택

타입: str
설명: 기반 클래스 필터

language_filter 선택

타입: str
설명: 언어 필터(python, typescript 등)

limit 선택

타입: int minimum=1, maximum=50
기본값: 20
설명: cursor를 사용하지 않을 때 페이지당 최대 결과 수. 연속 조회는 cursor에 저장된 페이지 크기를 사용합니다. 다른 limit로 시작하려면 cursor를 생략하세요.

offset 선택

타입: int minimum=0
설명: 하위 호환용 offset(사용 중단 권장). pagination.next_cursor에서 받은 cursor를 우선 사용하세요.

cursor 선택

타입: str
설명: pagination.next_cursor에서 받은 불투명한 cursor. 값을 그대로 전달하고 query와 필터도 변경하지 마세요. 이 cursor의 위치와 페이지 크기가 offset과 limit보다 우선합니다.

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
기본값: false
설명: 고급 경로·ltree·호출 필터(ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name)를 의도적으로 사용하면 true로 설정하세요. false여도 전달한 고급 필터는 적용되지만 메타데이터 경고가 추가됩니다. 일반적인 구조 쿼리에는 preset=를 우선 사용하세요.

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 필드 역할 필터. 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 안정

영향 범위／그래프 분석의 기본 인터페이스. 실제 호출／임포트 그래프를 통해 "무엇이 이것을 호출하는가?"／"이것이 무엇을 사용하는가?"에 답합니다. 편집 전 영향 분석에는: analysis_type="dependents" 또는 analysis_type="impact"(incoming, impact의 기본 깊이는 shallow), include_metrics는 기본값이 false(중심성 + refactor_risk가 필요하면 옵트인). PR/diff 영향: changed_paths 및／또는 patch(unified diff)를 전달하면 경로별로 심볼을 해석하고 심볼 이름 없이도 간결한 shallow-incoming dependents 페이로드를 반환합니다. 편집 후에는 verify_after_edit=true에 targets 및／또는 changed_paths를 지정하면 영향받은 심볼을 간결하게 다중 루트로 재쿼리합니다. dependencies, centrality, orphans도 지원합니다. analyze_dependencies는 같은 순회 방식으로 여러 홉에 걸친 영향 분석을 수행합니다. dependents/impact는 기본적으로 production_callers를 포함합니다. 테스트를 제외한 고유한 프로덕션 사용 위치를 종류(call, instantiate, 값으로 전달되는 함수의 value_reference)와 IMPORT 위치로 구분하고 EXTRACTED/INFERRED 신뢰도 분류를 제공합니다. 단순한 메트릭 나열이 아닙니다.

매개변수:

repository 선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 정확히 일치하는 인덱싱된 브랜치가 우선 사용됩니다. 사용할 수 없는 브랜치는 main 또는 접근 가능한 유일한 브랜치로 대체될 수 있습니다. 응답 메타데이터에는 요청된 항목과 실제로 해석된 항목이 표시되며, 대체가 발생하면 경고가 표시됩니다.

query 선택

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

target 선택

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

symbol_id 선택

타입: UUID
설명: 네임스페이스, 경로, 언어로 필터링한 뒤 이름으로 지정한 query/target 후보 중 특정 출현 위치를 UUID로 선택합니다. find_symbol 또는 그래프의 대체 후보에서 반환한 ID를 사용하세요. 이름을 지정한 순회에만 사용할 수 있으며, 제한된 후보 범위 밖의 ID는 오류를 발생시킵니다.

changed_paths 선택

타입: list[str] maxItems=50
설명: PR/diff 영향 분석(기본값)에 사용할 정확한 저장소 상대 파일 경로입니다. verify_after_edit=true이면 편집 후 검증의 시작점으로 사용합니다. 해석되지 않은 경로는 라벨이 붙은 제안을 반환할 수 있지만, 제안된 파일이 영향 분석의 시작점이 되는 일은 없습니다. PR/diff: 줄 정보가 없으면 경로마다 최상위 정의(내보낸 정의 우선, 파일 내 순서)를 순회하고 changed_lines_unknown을 보고합니다. 줄 단위로 변경된 심볼이 필요하면 patch=를 전달하세요. 검증: 경로당 최대 5개의 최상위 정의를 검증 시작점으로 사용합니다(검증 모드 내부에서는 더 낮은 상한 적용). PR/diff 영향 분석에는 query/target이 필요하지 않습니다.

patch 선택

타입: str maxLength=500000
설명: PR/diff 영향 분석: unified diff / git patch 텍스트입니다. 경로는 diff --git / --- / +++ 헤더에서 가져옵니다. 헌크의 줄(이전 쪽 = 인덱싱된 커밋)은 이를 감싸는 함수/메서드/클래스에 매핑되고, 이들을 순회해 정확한 의존 코드, public_api_changed, 그리고 변경 사항이 건드리지 않은 호출자를 찾습니다.

head_commit 선택

타입: str pattern=^[0-9a-fA-F]{7,64}$
설명: 질문하는 코드의 커밋 SHA(git rev-parse HEAD 또는 패치의 기준 커밋). complete:true가 되려면 인덱스가 이 커밋 시점이어야 하고 현재 리졸버로 빌드되어 있어야 합니다. 그렇지 않으면 index_stale / index_freshness_unverified / index_built_by_older_resolver와 함께 complete:false로 유지되며, 답변이 어느 범위에서 완전한지는 index_basis.statement가 알려 줍니다. 패치의 'base-commit:' 줄(git format-patch --base)로도 지정할 수 있습니다.

analysis_type 선택

타입: Literal[centrality, dependencies, dependents, impact, orphans]
기본값: dependencies
설명: 분석 모드. impact = 영향 범위(incoming dependents; depth를 생략하면 shallow 깊이). dependents도 영향 분석에 답합니다. changed_paths 또는 patch가 설정되면 분석은 PR/diff 영향으로 강제됩니다. centrality/orphans는 target이 필요하지 않습니다. orphans는 사용되지 않는 코드의 후보일 뿐 안전하게 제거해도 된다는 증거가 아닙니다. 소스의 참조를 확인하세요.

depth 선택

타입: Literal[shallow, balanced, deep]
설명: 순회 깊이. 기본값은 balanced이며, impact와 PR/diff impact는 기본적으로 shallow를 사용합니다. depth를 명시적으로 지정하면 이 기본값을 재정의합니다. 검증 모드는 항상 shallow를 사용합니다.

limit 선택

타입: int minimum=1, maximum=50
기본값: 20
설명: cursor를 사용하지 않을 때 페이지당 최대 결과 수. 연속 조회는 cursor에 저장된 페이지 크기를 사용합니다. 다른 limit로 시작하려면 cursor를 생략하세요.

offset 선택

타입: int minimum=0
설명: 하위 호환용 offset(사용 중단 권장). pagination.next_cursor에서 받은 cursor를 우선 사용하세요.

cursor 선택

타입: str
설명: pagination.next_cursor에서 받은 불투명한 cursor. 값을 그대로 전달하고 query와 필터도 변경하지 마세요. 이 cursor의 위치와 페이지 크기가 offset과 limit보다 우선합니다.

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
기본값: false
설명: 순회 결과에서 자동 생성된 선언과 빌드, 코드 커버리지, 캐시, 소스 맵, 압축된 산출물 경로를 제외합니다.

include_module_symbols 선택

타입: bool
기본값: false
설명: 기본값 false: from_name 또는 to_name이 합성 심볼 __module__인 엣지(모듈 수준 노이즈)를 제외합니다. dependents/dependencies 결과에 모듈 수준 엣지를 포함하려면 true로 설정하세요.

include_isolated 선택

타입: bool
설명: orphan 전용입니다. 기본값 false. true로 설정하면 그래프 메트릭 행이 없는(어디에도 그래프 엣지가 없는) 심볼도 반환합니다. exclude_test_paths가 true인 동안에는 백엔드가 지원하는 경우 스타일시트/마크업/데이터 심볼(CSS, HTML 등), .d.ts 선언, test/fixture/vendor/example 경로가 계속 제외되며, language_filter가 해당 언어를 지정한 경우는 예외입니다. TypeScript 객체 리터럴 속성은 여전히 고립된 함수로 나타날 수 있습니다.

exclude_exported 선택

타입: bool
기본값: false
설명: 고립 심볼에만 적용됩니다. 기본값은 false이며, 저장소에서 사용하지 않는 내보낸 심볼(공개 API)도 is_exported=true로 반환합니다. 내부 후보만 보려면 true로 설정하세요.

branch 선택

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

per_hop_limit 선택

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

include_metrics 선택

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

metrics_detail 선택

타입: Literal[summary, full]
기본값: summary
설명: include_metrics=true일 때: summary(기본값)는 판단에 필요한 신호와 refactor_risk를 반환하고, full은 선별된 메트릭을 더 폭넓게 반환합니다.

include_edge_metadata 선택

타입: bool
기본값: false
설명: 원시 엣지 메타데이터와 가중치(대용량)를 포함합니다. 간결한 영향 분석 응답에서는 이 옵션을 끕니다.

symbol_types 선택

타입: list[str]
설명: 반환되는 심볼을 종류(function, class, method 등)로 필터링합니다. orphan 분석에서는 지원되지 않으며, 이 경우 path_filter나 language_filter를 사용하세요. 빈 목록을 지정하면 종류 필터가 적용되지 않습니다.

exact_match 선택

타입: bool
기본값: false
설명: 심볼 이름의 정확한 일치 요구

find_similar_patterns 선택

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

min_centrality 선택

타입: float minimum=0
기본값: 0
설명: 이름이 지정된 심볼 순회와 PR/diff 영향 분석에 사용되는 최소 PageRank 점수. centrality/orphans 브라우즈 모드에서는 0보다 큰 임계값을 지원하지 않습니다. 메트릭은 필터링을 위해 내부적으로 가져오며; graph_metrics는 include_metrics=true일 때만 반환됩니다. 고정된 간결한 제어를 사용하는 verify_after_edit에서는 무시됩니다.

graph_view 선택

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

verify_after_edit 선택

타입: bool
기본값: false
설명: 편집된 심볼에 대해 인덱싱된 영향 그래프를 하나의 간결한 다중 루트 응답으로 재조회합니다. targets 및/또는 changed_paths(또는 target/query)가 필요합니다. 고정된 shallow 순회와 간결한 예산을 사용하며, depth/limit/cursor/metrics 제어는 적용되지 않습니다. 기본값은 incoming dependents이며, 결과는 인덱싱된 그래프를 반영합니다(실시간 편집보다 지연될 수 있음). true인 경우 동일한 changed_paths에 대해 PR/diff impact보다 우선합니다.

targets 선택

타입: list[str] maxItems=15
설명: 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] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 정확히 일치하는 인덱싱된 브랜치가 우선 사용됩니다. 사용할 수 없는 브랜치는 main 또는 접근 가능한 유일한 브랜치로 대체될 수 있습니다. 응답 메타데이터에는 요청된 항목과 실제로 해석된 항목이 표시되며, 대체가 발생하면 경고가 표시됩니다.

scope 선택

타입: Literal[definitions, references, both]
기본값: both
설명: 검색 범위. references를 사용하려면 비어 있지 않은 symbol_name이 필요합니다.

limit 선택

타입: int minimum=1, maximum=50
기본값: 15
설명: cursor를 사용하지 않을 때 페이지당 최대 결과 수. 연속 조회는 cursor에 저장된 페이지 크기를 사용합니다. 다른 limit로 시작하려면 cursor를 생략하세요.

offset 선택

타입: int minimum=0
설명: 하위 호환용 offset(사용 중단 권장). pagination.next_cursor에서 받은 cursor를 우선 사용하세요.

cursor 선택

타입: str
설명: pagination.next_cursor에서 받은 불투명한 cursor. 값을 그대로 전달하고 query와 필터도 변경하지 마세요. 이 cursor의 위치와 페이지 크기가 offset과 limit보다 우선합니다.

find_similar 선택

타입: bool
기본값: false
설명: 이름이 비슷한 심볼도 포함

include_metrics 선택

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

metrics_detail 선택

타입: Literal[summary, full]
기본값: summary
설명: include_metrics=true일 때: summary(기본값)는 판단에 필요한 신호와 refactor_risk를 반환하고, full은 선별된 메트릭을 더 폭넓게 반환합니다.

path_filter 선택

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

branch 선택

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

symbol_type 선택

타입: str minLength=1
설명: 인덱싱된 심볼 종류로 필터링합니다(예: function, class, struct, enum, trait). 심볼 결과에서 반환된 종류를 사용하세요. 종류는 언어에 따라 다릅니다.

high_impact 선택

타입: bool
기본값: false
설명: 아키텍처적으로 중요한 심볼을 탐색합니다(symbol_name 생략). 기본 모드는 popularity이며, PageRank 상위 10% 심볼에서 유틸리티 메가허브를 제외합니다. 단절점/브리지 절단 정점을 찾으려면 high_impact_mode=risk로 설정하세요.

high_impact_mode 선택

타입: Literal[popularity, risk]
기본값: popularity
설명: high_impact=true일 때: popularity = PageRank 상위 10% 심볼에서 유틸리티 메가허브/모듈을 제외한 집합; risk = SMV의 bridge_count, 그다음 k_core 순으로 순위를 매긴 단절점(허브 인기도가 아닌 구조적 리팩터링 위험).

in_cycle 선택

타입: bool
기본값: false
설명: 의존성 순환 소속이 기록된 심볼로 필터링합니다.

exclude_test_paths 선택

타입: bool
기본값: true
설명: 그래프 메트릭으로 탐색할 때 순위를 매기기 전에 테스트, 테스트 픽스처, 서드파티 코드, 예제를 제외합니다. 이름을 지정한 심볼 조회 동작은 바뀌지 않습니다.

reference_views 선택

타입: list[Literal[dependency, type, data_flow, control_flow, all]] minItems=1, maxItems=5
설명: 들어오는 간선으로 references/reference_count를 채울 그래프 뷰(scope는 references/both). 기본값 ["dependency", "type"]은 호출, 가져오기, 내보내기, 참조, 인스턴스화, 상속, 재정의, 데코레이터, 타입 사용을 포함합니다. data_flow를 선택하지 않으면 정확히 해석된 data_flow 사용(콜백, 핸들러, 정렬 키)은 value_references/value_reference_count로 별도 반환되며, 이름만으로 추론한 일치는 제외됩니다. data_flow나 control_flow를 추가하거나 모든 간선 타입과 계층을 포함하려면 ["all"]을 전달하세요. 뷰 분류는 dependency_search의 graph_view와 같습니다.

relationship_types 선택

타입: list[str]
설명: 참조 간선 타입을 명시합니다(CALL, IMPORT, READS 등). 비어 있지 않은 목록은 reference_views보다 우선합니다.

적합한 경우:

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

권장하지 않는 경우:

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

analyze_dependencies 안정

dependency_search와 같은 순회 방식(dependents/incoming)으로 영향 범위를 분석합니다. 영향 분석에는 analysis_type="dependents" 또는 "impact"를 지정한 dependency_search를 우선 사용하세요. graph, connection_summary, 선택적으로 refactor_risk를 포함하는 지표를 갖춘 다중 홉 영향 응답을 반환합니다. 관계 계열을 범위 지정하려면 graph_view를 사용하세요: dependency(기본값), type, data_flow, control_flow. connection_summary는 선택한 루트에 대해 관계 유형으로 한정된 간선을 테스트/경로 필터링 이전에 집계합니다. 기존의 incoming_production/outgoing_production 필드는 테스트를 포함한 비모듈 간선을 의미하며, 운영 코드 호출자 수가 아닙니다.

매개변수:

repository 선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 정확히 일치하는 인덱싱된 브랜치가 우선 사용됩니다. 사용할 수 없는 브랜치는 main 또는 접근 가능한 유일한 브랜치로 대체될 수 있습니다. 응답 메타데이터에는 요청된 항목과 실제로 해석된 항목이 표시되며, 대체가 발생하면 경고가 표시됩니다.

target 필수

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

symbol_id 선택

타입: UUID
설명: 네임스페이스, 경로, 언어로 필터링한 뒤 target 후보 중 특정 출현 위치를 UUID로 선택합니다. 제한된 후보 범위 밖의 ID는 오류를 발생시킵니다.

depth 선택

타입: Literal[shallow, balanced, deep]
기본값: balanced
설명: 분석 깊이

limit 선택

타입: int minimum=1, maximum=50
기본값: 10
설명: cursor를 사용하지 않을 때 페이지당 최대 결과 수. 연속 조회는 cursor에 저장된 페이지 크기를 사용합니다. 다른 limit로 시작하려면 cursor를 생략하세요.

offset 선택

타입: int minimum=0
설명: 하위 호환용 offset(사용 중단 권장). pagination.next_cursor에서 받은 cursor를 우선 사용하세요.

cursor 선택

타입: str
설명: pagination.next_cursor에서 받은 불투명한 cursor. 값을 그대로 전달하고 query와 필터도 변경하지 마세요. 이 cursor의 위치와 페이지 크기가 offset과 limit보다 우선합니다.

direction 선택

타입: Literal[incoming, outgoing, 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가 생략되거나 비어 있으면 이 값이 relationship_types의 기본값으로 적용됩니다. 도구 간 일관성을 위해 dependency_search의 기존 graph_view 매개변수 이름과 일치합니다.

path_filter 선택

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

language_filter 선택

타입: str
설명: 언어 필터

branch 선택

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

per_hop_limit 선택

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

include_metrics 선택

타입: bool
기본값: false
설명: 결과에 그래프 메트릭을 포함하고 각각에 파생 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
기본값: false
설명: 원시 엣지 메타데이터와 가중치를 포함합니다. 추출기 메타데이터가 클 수 있으므로 기본적으로 비활성화되어 있습니다. 활성화하면 메타데이터 보강 비율도 보고됩니다.

exclude_test_paths 선택

타입: bool
기본값: true
설명: 기본값 true: 반환되는 그래프 엣지에서 테스트, 테스트 픽스처, 서드파티 코드, 예제 경로를 제외합니다. 포함하려면 false로 설정하세요.

include_module_symbols 선택

타입: bool
기본값: false
설명: 기본값 false: from_name 또는 to_name이 합성 심볼 __module__인 엣지를 제외합니다. 모듈 수준 엣지를 포함하려면 true로 설정하세요.

head_commit 선택

타입: str pattern=^[0-9a-fA-F]{7,64}$
설명: 질문하는 코드의 커밋 SHA(git rev-parse HEAD 또는 패치의 기준 커밋). complete:true가 되려면 인덱스가 이 커밋 시점이어야 하고 현재 리졸버로 빌드되어 있어야 합니다. 그렇지 않으면 index_stale / index_freshness_unverified / index_built_by_older_resolver와 함께 complete:false로 유지되며, 답변이 어느 범위에서 완전한지는 index_basis.statement가 알려 줍니다. 패치의 'base-commit:' 줄(git format-patch --base)로도 지정할 수 있습니다.

적합한 경우:

graph와 connection_summary 응답 필드가 필요한 다중 홉 영향 분석

권장하지 않는 경우:

일반적인 영향 분석에는 유연한 순회와 여러 시작점 확인을 지원하는 dependency_search를 우선 사용하세요

get_task_context 안정

낯선 영역에서 작업을 시작하시나요? 작업을 설명하면(예: "SSO 지원 추가", "청구 웹훅 수정") 관련 파일, 코드, 심볼, 의존성을 한 번의 호출로 묶어서 받을 수 있습니다. 시드로 전달된 파일은 심볼을 정의하지 않아도 직접 인덱싱된 콘텐츠로 반영됩니다. 실패한 레이어에는 표시가 붙으며, 모든 조회가 실패하면 도구 오류가 반환됩니다. 더 많은 결과가 필요하면 해당 레이어의 전용 검색 도구를 이어서 사용하세요.

매개변수:

task_description 필수

타입: str minLength=1
설명: 작업 설명

repository 선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 정확히 일치하는 인덱싱된 브랜치가 우선 사용됩니다. 사용할 수 없는 브랜치는 main 또는 접근 가능한 유일한 브랜치로 대체될 수 있습니다. 응답 메타데이터에는 요청된 항목과 실제로 해석된 항목이 표시되며, 대체가 발생하면 경고가 표시됩니다.

limit 선택

타입: int minimum=1, maximum=50
기본값: 15
설명: 레이어당 최대 결과 수

scope 선택

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

language_filter 선택

타입: str
설명: 언어 필터: 명시적 시드나 관련 컨텍스트 없이 scope=semantic이어야 합니다. 다른 계층 인덱스에서는 언어를 강제할 수 없습니다.

path_filter 선택

타입: str
설명: 시맨틱 검색과 키워드 검색의 시작점이 되는 파일 경로 접두사입니다. 명시적 시드는 이 접두사 범위 밖에 있을 수 있습니다. 그래프 컨텍스트는 디렉터리 경계를 넘나들 수 있습니다.

branch 선택

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

include_related_context 선택

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

seed_symbol_ids 선택

타입: list[str] maxItems=20
설명: 명시적 작업 시드: 심볼 레이어에서 가장 먼저 나타나며, 범위가 제한된 dependencies/related_context 창 내에 유지됩니다. 그래프 레이어는 키워드 폴백보다 명시적 시드와 그 최근접 이웃을 먼저 정렬하며, 중요도는 관련성이 동일할 때만 순위를 가릅니다. 그래프 확장에는 scope=all|dependencies가 필요합니다(scope=symbols|semantic은 의존성 순회를 실행하지 않습니다). 키워드만으로 깊이 감쇠 중요도 순위를 쓰려면 생략하세요.

seed_file_paths 선택

타입: list[str] maxItems=10
설명: 명시적 시드: 에이전트가 열어 두었거나 방금 편집한 정확한 인덱싱된 파일 경로입니다. 제한된 분량의 파일 내용을 직접 근거로 반환하고 파일당 최대 5개의 그래프 시드를 제공하며, 범위가 제한된 심볼 조회에서 작업 이름과 정확히 일치하는 항목을 정의나 부수적인 심볼보다 우선합니다. 심볼이 없는 파일도 근거를 제공합니다. 존재하지 않는 파일은 라벨이 붙은 제안을 반환할 수 있지만, 이는 시드가 아닙니다. 그래프 확장에는 scope=all|dependencies가 필요합니다.

적합한 경우:

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

권장하지 않는 경우:

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

get_file 안정

경로로 인덱싱된 저장소에서 파일을 읽습니다. 디스크에 있는 파일에는 로컬 파일 도구를 우선 사용하고, 이 도구는 원격 인덱싱된 스냅샷에 사용하세요. metadata.next_line_start와 next_character_start로 경계가 있는 응답을 계속 받을 수 있습니다. 후행 줄바꿈과 [truncated] 마커는 metadata.truncated=true일 때만 제거하세요. 그렇지 않으면 실제 소스 텍스트일 수 있습니다.

매개변수:

file_path 필수

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

repository 선택

타입: str
설명: owner/repo[:branch] 형식의 저장소입니다. 선택 사항 — 생략하면 요청 범위의 클라이언트 기본값(제공된 경우) 또는 접근 가능한 유일한 저장소를 사용합니다. 다른 인덱싱된 저장소를 대상으로 할 때만 명시적으로 전달하세요. 정확히 일치하는 인덱싱된 브랜치가 우선 사용됩니다. 사용할 수 없는 브랜치는 main 또는 접근 가능한 유일한 브랜치로 대체될 수 있습니다. 응답 메타데이터에는 요청된 항목과 실제로 해석된 항목이 표시되며, 대체가 발생하면 경고가 표시됩니다.

line_start 선택

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

line_end 선택

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

character_start 선택

타입: int minimum=0
기본값: 0
설명: 시작 행 안에서만 적용되는 UTF-16 코드 단위 오프셋입니다(0부터 시작). 일부만 읽은 행을 이어서 읽으려면 metadata.next_character_start를 사용하세요.

branch 선택

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

max_tokens 선택

타입: int minimum=1, maximum=50000
기본값: 5000
설명: 대략적인 콘텐츠 예산(토큰당 UTF-16 코드 단위 4개로 계산하며, 정확한 토크나이저 한도가 아님).

include_metadata 선택

타입: bool
기본값: true
설명: 파일 설명 메타데이터를 포함합니다. 잘림 및 이어 읽기 메타데이터는 항상 반환됩니다.

적합한 경우:

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

권장하지 않는 경우:

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

시스템 및 유틸리티 도구

repository_context 안정

검색 가능한 저장소를 나열하거나 특정 저장소의 식별 정보(namespace/branch, indexed_commit_sha / 인덱스 최신성)를 가져옵니다. 저장소 slug를 모를 때는 action:"list"를 사용하세요. 검색 도구는 알려진 slug를 직접 받아들이거나, 키에 연결된 단일 저장소를 기본값으로 사용합니다. list는 pattern과 페이지네이션을 사용하며, info는 repository가 필수이고 branch와 옵트인 include_statistics=true를 지원합니다.

매개변수:

action 필수

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

repository 선택

타입: str
설명: info 전용: owner/repo 또는 owner/repo:branch 형식의 저장소(info에는 필수)

branch 선택

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

pattern 선택

타입: str
설명: list 전용: 대소문자를 구분하지 않는 저장소 이름 부분 문자열

include_statistics 선택

타입: bool
기본값: false
설명: 정보 전용: 경계가 있는 인덱스 데이터 개수를 포함합니다. file/blob 개수는 정확하지만, 더 큰 인덱스 개수는 추정값입니다. count_accuracy와 estimate_analyzed_at을 확인하세요. 기본값은 false입니다.

limit 선택

타입: int minimum=1, maximum=50
기본값: 20
설명: cursor를 사용하지 않을 때 페이지당 최대 결과 수. 연속 조회는 cursor에 저장된 페이지 크기를 사용합니다. 다른 limit로 시작하려면 cursor를 생략하세요.

offset 선택

타입: int minimum=0
설명: 하위 호환용 offset(사용 중단 권장). pagination.next_cursor에서 받은 cursor를 우선 사용하세요.

cursor 선택

타입: str
설명: pagination.next_cursor에서 받은 불투명한 cursor. 값을 그대로 전달하고 query와 필터도 변경하지 마세요. 이 cursor의 위치와 페이지 크기가 offset과 limit보다 우선합니다.

적합한 경우:

접근 가능한 저장소 목록 표시
저장소 식별, 브랜치, 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 maxLength=500
설명: 안내 주제(예: tool_selection, semantic_search) 또는 evaluate용 표현식 문자열입니다.

description 선택

타입: str minLength=1, maxLength=4000
설명: 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 유지관리자를 위해 저장되는 버그 리포트와 기능 요청

권장하지 않는 경우:

수학·해시·문자열 계산에는 로컬 계산이나 호스트 도구를 우선 사용하세요

모범 사례

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

성능 특성

작업	성능 관련 참고
시맨틱 검색	쿼리 임베딩 생성과 벡터 검색을 포함합니다. 지연 시간은 두 작업 모두에 따라 달라집니다.
텍스트 검색	내용의 유사 검색에서는 뒤쪽 페이지일수록 더 많은 후보를 가져옵니다. path_filter와 language_filter로 쿼리 범위를 좁히세요.
구조 검색	인덱싱된 AST 노드를 조회합니다. 구체적인 프리셋이나 패턴을 사용하고 결과 수를 제한하세요.
의존성 검색	깊이가 늘어나면 비용도 증가합니다. 멀티홉 컨텍스트가 필요하지 않다면 depth="shallow"를 권장합니다. per_hop_limit로 확산을 제한합니다
파일 조회	line_start/line_end 또는 max_tokens로 필요한 범위를 읽고, 잘린 내용은 반환된 이어 읽기 메타데이터를 활용하세요.
저장소 컨텍스트	저장소 이름 해석은 도구 호출마다 실행됩니다. 특정 저장소가 필요하면 repository를 명시적으로 전달하세요.
ask_maguyva (guidance / evaluate)	저장소 인덱스를 조회하지 않고 MCP 서버에서 실행됩니다.

오류 처리

도구 응답은 최상위에 공통 상태 필드와 도구별 페이로드 필드를 포함합니다. 검색은 results를 반환하고 get_file은 content를 반환합니다. 공통 필드는 다음과 같습니다:

status: 문자열 — "success" 또는 "error". 저하된 매칭과 신선도 신호는 각자의 필드에 담깁니다. metadata 아래의 metadata.resolution_reason, 그리고 repository_context info 액션 최상위의 index_freshness.status입니다.
timing_ms: 도구 실행에 걸린 시간(밀리초)
applied_filters: 작업에 대해 기록된 실제 적용 요청 매개변수
error: status가 "error"일 때의 오류 메시지 문자열이며, 복구 지침이 포함될 수 있습니다.
metadata: 작업에 관한 추가 정보(라우팅, 캐싱, 매개변수 조정)
pagination: 커서로 페이지를 나눈 컬렉션 응답에 있으며 has_more와 next_cursor를 포함합니다. 순위 기반 검색 창은 제한된 top-K 결과이며, 전체 항목을 페이지별로 제공하는 컬렉션이 아닙니다.

도구 페이로드를 처리하기 전에 status 필드를 확인하세요. 값은 "success" 또는 "error"입니다. 도구 페이로드가 만들어지기 전에 발생할 수 있는 MCP/JSON-RPC 전송 오류와 요청 검증 오류도 함께 처리하세요. 저하된 매칭이나 신선도 신호는 전용 필드를 읽으면 됩니다. metadata 아래의 metadata.resolution_reason, 또는 repository_context info 액션 최상위의 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 안정

모범 사례

성능 특성

오류 처리

시작하기

다음 읽을거리