MCP API Reference

Complete reference for all 11 customer-facing Maguyva MCP tools. Each tool includes parameters, usage guidance, and best-for recommendations.

API Overview #

The Maguyva MCP API currently exposes 11 customer-facing tools across 4 main categories:

Core Search Tools - Advanced search capabilities across your codebase
Structural & Graph Tools - AST queries, symbol lookup, and dependency analysis
Code Analysis Tools - Deep code analysis and relationship mapping
System & Utility Tools - Repository context, deterministic compute, and guidance

All tools use a consistent repository identifier format: "owner/repo:branch". Branch defaults to main if not specified.

Pass repository directly on a tool call, or set the session first with repository_context(action="set", repository="owner/repo"). Some MCP clients validate tool schemas before the server can apply session context; if that happens, include repository explicitly.

Repository Parameter Format #

All MCP tools use this repository identifier format:

With branch: "owner/repo:branch" - e.g., "owner/repository:develop"
Default branch: "owner/repo" - uses main branch when no branch is specified "owner/repository"
Session context: Set the current repository with repository_context(action="set", repository="owner/repo")

Example prompts:

Ask about a specific repo:  "Search owner/my-repo for authentication middleware"
Set session context:        "Use owner/my-repo for this Maguyva session"
Override for one query:     "Search owner/other-repo:develop for auth patterns"

Language Filtering #

All search tools support filtering results by programming language:

language_filter="python" - Filter to Python files only
language_filter="typescript" - Filter to TypeScript files only
Case-sensitive: Use lowercase language names
Default: Empty string (no filtering) - returns results from all languages
Supported coverage: Language filters work across the full 278+ supported languages and text-based technologies. See compatibility for the full list.

"Find authentication middleware in Python files only"
"Search for database connections in TypeScript"

API reference generated from source on June 7, 2026.

Core Search Tools #

intelligent_search Stable

START HERE — Multi-modal code search that auto-routes across semantic, text, AST, and graph. Combines search strategies with importance-aware ranking and dead code detection. Start here — auto-routes your question to the best search mode.

Parameters:

repositoryRequired

Type: str
Description: 'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").

queryRequired

Type: str
Default
Description: Search query

branchOptional

Type: str
Default
Description: Branch name (leave blank to use the session or repository default).

modeOptional

Type: Literal[auto, semantic, text, ast, graph, hybrid]
Default: auto
Description: Search mode

qualityOptional

Type: str
Default: balanced
Description: Search quality

limitOptional

Type: int
Description: Max results

include_contentOptional

Type: bool
Description: Include full content

language_filterOptional

Type: str
Default
Description: Language filter

path_filterOptional

Type: str
Default
Description: Repo-relative prefix or glob (e.g., 'src/pipeline/', '*.py'); routed searches now forward these filters to Supabase RPCs so result limits reflect filtered rows, with client-side trimming retained only as a guard for glob-only expressions.

boost_by_importanceOptional

Type: bool | None
Description: Rank results higher if they have many dependencies (high PageRank). Use for finding core utilities, widely-used interfaces, or important code.

orphansOptional

Type: bool
Default
Description: Return symbols with no incoming references (potential dead code). Useful for cleanup but may include decorators, inner functions, CLI entry points.

min_coupling_scoreOptional

Type: float
Default: 0
Description: Minimum bridging centrality threshold (0.0-1.0). Higher values only return coupling hotspots that connect different code communities.

include_community_contextOptional

Type: bool
Description: Include related symbols from the same code community for broader context. Helpful when exploring how a feature or module works.

Parameter	Type	Required	Default	Description
`repository`	`str`	Yes	-	'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").
`query`	`str`	Yes		Search query
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`mode`	`Literal[auto, semantic, text, ast, graph, hybrid]`	No	`auto`	Search mode
`quality`	`str`	No	`balanced`	Search quality
`limit`	`int`	No	-	Max results
`include_content`	`bool`	No	-	Include full content
`language_filter`	`str`	No		Language filter
`path_filter`	`str`	No		Repo-relative prefix or glob (e.g., 'src/pipeline/', '*.py'); routed searches now forward these filters to Supabase RPCs so result limits reflect filtered rows, with client-side trimming retained only as a guard for glob-only expressions.
`boost_by_importance`	`bool \| None`	No	-	Rank results higher if they have many dependencies (high PageRank). Use for finding core utilities, widely-used interfaces, or important code.
`orphans`	`bool`	No		Return symbols with no incoming references (potential dead code). Useful for cleanup but may include decorators, inner functions, CLI entry points.
`min_coupling_score`	`float`	No	`0`	Minimum bridging centrality threshold (0.0-1.0). Higher values only return coupling hotspots that connect different code communities.
`include_community_context`	`bool`	No	-	Include related symbols from the same code community for broader context. Helpful when exploring how a feature or module works.

Timeout: 60s

semantic_search Stable

Find code by meaning using vector similarity. Use for conceptual queries like 'authentication flow' or 'error handling pattern' when you don't know exact text. Use when you need to find code by meaning rather than exact text.

Parameters:

repositoryRequired

Type: str
Description: 'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").

queryRequired

Type: str
Default
Description: Search query

branchOptional

Type: str
Default
Description: Branch name (leave blank to use the session or repository default).

limitOptional

Type: int
Description: Max results (read-only)

similarity_thresholdOptional

Type: float
Description: Min similarity score

depthOptional

Type: str
Default
Description: Search depth

include_contentOptional

Type: bool
Description: Include full content

boost_by_importanceOptional

Type: bool
Description: Boost by graph centrality

language_filterOptional

Type: str
Default
Description: Filter results to files detected as this programming language

path_filterOptional

Type: str
Default
Description: Repo-relative prefix (e.g., 'src/services/') or glob (e.g., '*.py', 'tree_sitter_queries/**/*.scm'); filters now execute server-side via Supabase RPCs so limits apply after filtering (client-side trimming remains a safety guard for glob-only patterns).

Parameter	Type	Required	Default	Description
`repository`	`str`	Yes	-	'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").
`query`	`str`	Yes		Search query
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`limit`	`int`	No	-	Max results (read-only)
`similarity_threshold`	`float`	No	-	Min similarity score
`depth`	`str`	No		Search depth
`include_content`	`bool`	No	-	Include full content
`boost_by_importance`	`bool`	No	-	Boost by graph centrality
`language_filter`	`str`	No		Filter results to files detected as this programming language
`path_filter`	`str`	No		Repo-relative prefix (e.g., 'src/services/') or glob (e.g., '.py', 'tree_sitter_queries//.scm'); filters now execute server-side via Supabase RPCs so limits apply after filtering (client-side trimming remains a safety guard for glob-only patterns).

Timeout: 30s

text_pattern_search Stable

Search code by exact text, fuzzy match, or regex pattern. Use for known strings, error messages, identifiers, and grep-like queries. Use for regex patterns, exact strings, or when you know the specific text to find.

Parameters:

repositoryRequired

Type: str
Description: 'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").

queryRequired

Type: str
Default
Description: Text pattern

branchOptional

Type: str
Default
Description: Branch name (leave blank to use the session or repository default).

search_scopeOptional

Type: Literal[content, symbols, files, auto]
Default: content
Description: Search scope: 'content' (code chunks, default), 'symbols' (function/class names), 'files' (file paths), 'auto' (system chooses).

modeOptional

Type: Literal[exact, fuzzy, regex]
Default: exact
Description: Search mode: 'exact' (literal match), 'fuzzy' (similarity-based), 'regex' (pattern match). Note: fuzzy mode with search_scope='content' (the default) may route to semantic search for performance (23s→500ms). When routed, response metadata includes search_type='semantic_routed'.

case_sensitiveOptional

Type: bool
Default
Description: Case sensitive

language_filterOptional

Type: str
Default
Description: Language filter

limitOptional

Type: int
Description: Max results

path_filterOptional

Type: str
Default
Description: Repo-relative prefix or glob (e.g., 'src/pipeline/', '*.py', 'queries/**/*.scm'); filters now execute inside Supabase text search RPCs so limits apply after filtering, with client-side trimming kept only as a guard for exotic patterns.

Parameter	Type	Required	Default	Description
`repository`	`str`	Yes	-	'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").
`query`	`str`	Yes		Text pattern
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`search_scope`	`Literal[content, symbols, files, auto]`	No	`content`	Search scope: 'content' (code chunks, default), 'symbols' (function/class names), 'files' (file paths), 'auto' (system chooses).
`mode`	`Literal[exact, fuzzy, regex]`	No	`exact`	Search mode: 'exact' (literal match), 'fuzzy' (similarity-based), 'regex' (pattern match). Note: fuzzy mode with search_scope='content' (the default) may route to semantic search for performance (23s→500ms). When routed, response metadata includes search_type='semantic_routed'.
`case_sensitive`	`bool`	No		Case sensitive
`language_filter`	`str`	No		Language filter
`limit`	`int`	No	-	Max results
`path_filter`	`str`	No		Repo-relative prefix or glob (e.g., 'src/pipeline/', '.py', 'queries//.scm'); filters now execute inside Supabase text search RPCs so limits apply after filtering, with client-side trimming kept only as a guard for exotic patterns.

Timeout: 30s

Structural & Graph Tools #

structural_search Stable

Search code structure by AST node type, symbol name, decorator, or base class. Use when you need structural precision — find all classes inheriting from X, functions with @decorator, or specific AST patterns. Use for AST pattern matching to find code by structure rather than text.

Parameters:

repositoryRequired

Type: str
Description: Repository identifier (owner/repo[:branch]).

patternOptional

Type: str
Default
Description: General search pattern (auto-detected as node_type or name_pattern)

query_typeOptional

Type: Literal[node_type, name_pattern, parent_child]
Default: node_type
Description: Search mode (auto-detected when omitted). Inferred from provided parameters: name_pattern → 'name_pattern', parent_type → 'parent_child', otherwise 'node_type'. Set explicitly to override auto-detection.

node_typeOptional

Type: str
Default
Description: AST node type

name_patternOptional

Type: str
Default
Description: Name pattern

parent_typeOptional

Type: str
Default
Description: Parent node type

presetOptional

Type: str
Default
Description: Search preset

decoratorOptional

Type: str
Default
Description: Decorator name filter

callee_textOptional

Type: str
Default
Description: Full callee expression (exact match). For 'logger.info(msg)', use callee_text='logger.info'. For 'sys.exit()', use callee_text='sys.exit'. Does not support wildcards or partial matching.

callee_nameOptional

Type: str
Default
Description: Final function identifier in a call (exact match). For 'logger.info()', callee_name='info' (not 'logger'). For 'sys.exit()', callee_name='exit'. For 'ValueError(msg)', callee_name='ValueError'.

field_roleOptional

Type: str
Default
Description: Field role filter for AST nodes

ltree_ancestorOptional

Type: str
Default
Description: Ltree ancestor path filter

ltree_descendantOptional

Type: str
Default
Description: Ltree descendant path filter

definition_nameOptional

Type: str
Default
Description: Definition name to search for

base_classOptional

Type: str
Default
Description: Base class name filter (find classes inheriting from this)

min_depthOptional

Type: int
Default: 0
Description: Minimum AST depth filter

max_depthOptional

Type: int
Default: 0
Description: Maximum AST depth filter

branchOptional

Type: str
Default
Description: Branch name (leave blank to use the session or repository default).

limitOptional

Type: int
Description: Max results (capped at 100-200 based on query type)

language_filterOptional

Type: str
Default
Description: Language filter

path_filterOptional

Type: str
Default
Description: Repo-relative prefix or glob (e.g., 'src/pipeline/', '*.py', 'tree_sitter_queries/**/*.scm'); AST RPCs now enforce these filters server-side so limits apply post-filter, with client-side trimming acting only as a safeguard for glob-only cases.

Parameter	Type	Required	Default	Description
`repository`	`str`	Yes	-	Repository identifier (owner/repo[:branch]).
`pattern`	`str`	No		General search pattern (auto-detected as node_type or name_pattern)
`query_type`	`Literal[node_type, name_pattern, parent_child]`	No	`node_type`	Search mode (auto-detected when omitted). Inferred from provided parameters: name_pattern → 'name_pattern', parent_type → 'parent_child', otherwise 'node_type'. Set explicitly to override auto-detection.
`node_type`	`str`	No		AST node type
`name_pattern`	`str`	No		Name pattern
`parent_type`	`str`	No		Parent node type
`preset`	`str`	No		Search preset
`decorator`	`str`	No		Decorator name filter
`callee_text`	`str`	No		Full callee expression (exact match). For 'logger.info(msg)', use callee_text='logger.info'. For 'sys.exit()', use callee_text='sys.exit'. Does not support wildcards or partial matching.
`callee_name`	`str`	No		Final function identifier in a call (exact match). For 'logger.info()', callee_name='info' (not 'logger'). For 'sys.exit()', callee_name='exit'. For 'ValueError(msg)', callee_name='ValueError'.
`field_role`	`str`	No		Field role filter for AST nodes
`ltree_ancestor`	`str`	No		Ltree ancestor path filter
`ltree_descendant`	`str`	No		Ltree descendant path filter
`definition_name`	`str`	No		Definition name to search for
`base_class`	`str`	No		Base class name filter (find classes inheriting from this)
`min_depth`	`int`	No	`0`	Minimum AST depth filter
`max_depth`	`int`	No	`0`	Maximum AST depth filter
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`limit`	`int`	No	-	Max results (capped at 100-200 based on query type)
`language_filter`	`str`	No		Language filter
`path_filter`	`str`	No		Repo-relative prefix or glob (e.g., 'src/pipeline/', '.py', 'tree_sitter_queries//.scm'); AST RPCs now enforce these filters server-side so limits apply post-filter, with client-side trimming acting only as a safeguard for glob-only cases.

Timeout: 30s

dependency_search Stable

Graph-powered dependency and relationship analysis with centrality ranking. Use for finding dependencies, impact radius, module boundaries, orphan detection, and coupling hotspots. Use for import tracking, caller/callee discovery, and coupling assessment.

Parameters:

repositoryRequired

Type: str
Description: 'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").

analysis_typeOptional

Type: str
Default: centrality
Description: Query mode: centrality|dependencies|modules|impact_radius|orphans

branchOptional

Type: str
Default
Description: Branch name (leave blank to use the session or repository default).

symbol_typesOptional

Type: tuple[str, Ellipsis] | list[str]
Default
Description: Symbol type filter

limitOptional

Type: int
Description: Max graph nodes

min_centralityOptional

Type: float
Default: 0
Description: Min centrality score

find_similar_patternsOptional

Type: bool
Default
Description: Find similar symbols

targetOptional

Type: str | None
Default
Description: Target symbol or file

directionOptional

Type: str
Default: both
Description: Traversal direction: 'outgoing' = what this symbol depends on (its dependencies), 'incoming' = what depends on this symbol (its dependents), 'both' = full context. Use 'incoming' to find all callers/users of a symbol.

depthOptional

Type: int | str | None
Default
Description: Traversal depth (1-3, or aliases: shallow, balanced, deep)

include_metricsOptional

Type: bool | None
Default
Description: Include graph metrics

language_filterOptional

Type: str
Default
Description: Filter results to files detected as this programming language

relationship_typesOptional

Type: tuple[str, Ellipsis] | list[str] | None
Default
Description: Explicit edge types (e.g., CALL, IMPORT). Overrides analysis_type if provided.

exact_matchOptional

Type: bool
Default
Description: Require exact symbol name match (case-insensitive). Disables fuzzy matching

path_filterOptional

Type: str
Default
Description: Repo-relative prefix or glob (e.g., 'src/services/', '*.py')

exclude_test_pathsOptional

Type: bool
Default
Description: Exclude common test/fixture paths from results. When true, filters paths matching fixtures/, test_fixtures/, __fixtures__/. Default false (no filtering).

Parameter	Type	Required	Default	Description
`repository`	`str`	Yes	-	'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").
`analysis_type`	`str`	No	`centrality`	Query mode: centrality\|dependencies\|modules\|impact_radius\|orphans
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`symbol_types`	`tuple[str, Ellipsis] \| list[str]`	No		Symbol type filter
`limit`	`int`	No	-	Max graph nodes
`min_centrality`	`float`	No	`0`	Min centrality score
`find_similar_patterns`	`bool`	No		Find similar symbols
`target`	`str \| None`	No		Target symbol or file
`direction`	`str`	No	`both`	Traversal direction: 'outgoing' = what this symbol depends on (its dependencies), 'incoming' = what depends on this symbol (its dependents), 'both' = full context. Use 'incoming' to find all callers/users of a symbol.
`depth`	`int \| str \| None`	No		Traversal depth (1-3, or aliases: shallow, balanced, deep)
`include_metrics`	`bool \| None`	No		Include graph metrics
`language_filter`	`str`	No		Filter results to files detected as this programming language
`relationship_types`	`tuple[str, Ellipsis] \| list[str] \| None`	No		Explicit edge types (e.g., CALL, IMPORT). Overrides analysis_type if provided.
`exact_match`	`bool`	No		Require exact symbol name match (case-insensitive). Disables fuzzy matching
`path_filter`	`str`	No		Repo-relative prefix or glob (e.g., 'src/services/', '*.py')
`exclude_test_paths`	`bool`	No		Exclude common test/fixture paths from results. When true, filters paths matching fixtures/, test_fixtures/, __fixtures__/. Default false (no filtering).

Timeout: 60s

Code Analysis Tools #

find_symbol Stable

Look up symbol definitions and references with graph metrics. Use when you know the exact function, class, or variable name and need its location, callers, or importance.

Parameters:

repositoryRequired

Type: str
Description: 'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").

symbol_nameRequired

Type: str
Default
Description: Symbol name

symbol_typeOptional

Type: str
Default
Description: Symbol type filter

branchOptional

Type: str
Default
Description: Branch name (leave blank to use the session or repository default).

scopeOptional

Type: str
Default: both
Description: Scope: definitions|references|both

limitOptional

Type: int
Description: Max results

find_similarOptional

Type: bool
Default
Description: Find similar symbols

include_metricsOptional

Type: bool
Default
Description: Include graph metrics

high_impactOptional

Type: bool
Default
Description: High-impact only

in_cycleOptional

Type: bool
Default
Description: In-cycle only

language_filterOptional

Type: str
Default
Description

path_filterOptional

Type: str
Default
Description: Path glob (e.g., 'src/', '*.py')

Parameter	Type	Required	Default	Description
`repository`	`str`	Yes	-	'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").
`symbol_name`	`str`	Yes		Symbol name
`symbol_type`	`str`	No		Symbol type filter
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`scope`	`str`	No	`both`	Scope: definitions\|references\|both
`limit`	`int`	No	-	Max results
`find_similar`	`bool`	No		Find similar symbols
`include_metrics`	`bool`	No		Include graph metrics
`high_impact`	`bool`	No		High-impact only
`in_cycle`	`bool`	No		In-cycle only
`language_filter`	`str`	No
`path_filter`	`str`	No		Path glob (e.g., 'src/', '*.py')

Timeout: 30s

analyze_dependencies Stable

Analyze import chains and dependency relationships for a symbol or directory. Use for understanding module coupling and dependency depth. Use for comprehensive dependency analysis of a file or symbol.

Parameters:

targetRequired

Type: str
Description: Symbol or module name to analyze (e.g., 'SupabaseService', 'get_config'). Use symbol names for reliable results.

repositoryRequired

Type: str
Description: 'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").

analysis_typeOptional

Type: str
Default: imports
Description: Analysis type - supports the 16 canonical relationship types across 6 tiers (compatibility metadata such as DEFINITION/USES remains internal): Tier 1 (imports/exports), Tier 2 (inheritance/overrides/decorators), Tier 3 (instantiation/type_info), Tier 4 (exception_flow/throws/catches), Tier 5 (data_flow/reads/writes), Tier 6 (control_flow/cfg)

branchOptional

Type: str
Default
Description: Branch name (leave blank to use the session or repository default).

depthOptional

Type: int
Default: 1
Description: Analysis depth (supports aliases: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)

directionOptional

Type: str
Default: both
Description: Traversal direction: 'outgoing' = what this symbol depends on (its dependencies), 'incoming' = what depends on this symbol (its dependents), 'both' = full context. Use 'incoming' to find all callers/users of a symbol.

limitOptional

Type: int
Description: Max relationships

include_metricsOptional

Type: bool
Default
Description: Include metrics

language_filterOptional

Type: str
Default
Description: Restrict results to a language

relationship_typesOptional

Type: list[str] | tuple[str, Ellipsis] | None
Default
Description: Explicit edge types (e.g., CALL, IMPORT). Overrides analysis_type if provided.

Parameter	Type	Required	Default	Description
`target`	`str`	Yes	-	Symbol or module name to analyze (e.g., 'SupabaseService', 'get_config'). Use symbol names for reliable results.
`repository`	`str`	Yes	-	'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").
`analysis_type`	`str`	No	`imports`	Analysis type - supports the 16 canonical relationship types across 6 tiers (compatibility metadata such as DEFINITION/USES remains internal): Tier 1 (imports/exports), Tier 2 (inheritance/overrides/decorators), Tier 3 (instantiation/type_info), Tier 4 (exception_flow/throws/catches), Tier 5 (data_flow/reads/writes), Tier 6 (control_flow/cfg)
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`depth`	`int`	No	`1`	Analysis depth (supports aliases: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)
`direction`	`str`	No	`both`	Traversal direction: 'outgoing' = what this symbol depends on (its dependencies), 'incoming' = what depends on this symbol (its dependents), 'both' = full context. Use 'incoming' to find all callers/users of a symbol.
`limit`	`int`	No	-	Max relationships
`include_metrics`	`bool`	No		Include metrics
`language_filter`	`str`	No		Restrict results to a language
`relationship_types`	`list[str] \| tuple[str, Ellipsis] \| None`	No		Explicit edge types (e.g., CALL, IMPORT). Overrides analysis_type if provided.

Timeout: 60s

get_task_context Stable

Gather multi-layered context for a task description. Combines semantic search, symbol lookup, and dependency analysis in one call. Use when working on a specific task to get relevant context snippets.

Parameters:

task_descriptionRequired

Type: str
Description: Task description

repositoryRequired

Type: str
Description: 'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").

branchOptional

Type: str
Default
Description: Branch name (leave blank to use the session or repository default).

scopeOptional

Type: list[str] | str
Default
Description: Context layers to include. Valid: 'semantic', 'symbols', 'dependencies', 'all'. Default: ['semantic', 'symbols', 'dependencies']

language_filterOptional

Type: str
Default
Description: Filter results to files detected as this programming language

include_related_contextOptional

Type: bool
Default
Description: Include related context (neighbors + community members)

limitOptional

Type: int | None
Default: 0
Description: Max context items

Parameter	Type	Required	Default	Description
`task_description`	`str`	Yes	-	Task description
`repository`	`str`	Yes	-	'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`scope`	`list[str] \| str`	No		Context layers to include. Valid: 'semantic', 'symbols', 'dependencies', 'all'. Default: ['semantic', 'symbols', 'dependencies']
`language_filter`	`str`	No		Filter results to files detected as this programming language
`include_related_context`	`bool`	No		Include related context (neighbors + community members)
`limit`	`int \| None`	No	`0`	Max context items

Timeout: 60s

get_file Stable

Retrieve file content with optional line range and metadata. Use for reading specific source files or code sections. Use to read a specific file's content from the indexed repository.

Parameters:

file_pathRequired

Type: str
Description: File path

repositoryRequired

Type: str
Description: 'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").

branchOptional

Type: str
Default
Description: Branch name (leave blank to use the session or repository default).

line_rangeOptional

Type: list[int] | dict[str, int] | str | None
Default
Description: [start, end] or 'start-end'

max_tokensOptional

Type: int
Description: Max tokens

include_metadataOptional

Type: bool
Default: true
Description: Include metadata

include_syntax_highlightingOptional

Type: bool
Default
Description: Include syntax highlighting

chunk_startOptional

Type: int
Default: 0
Description: Chunk start position

Parameter	Type	Required	Default	Description
`file_path`	`str`	Yes	-	File path
`repository`	`str`	Yes	-	'owner/repo' or 'owner/repo:branch'. Pass explicitly, or set session context first with repository_context(action="set", repository="owner/repo").
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`line_range`	`list[int] \| dict[str, int] \| str \| None`	No		[start, end] or 'start-end'
`max_tokens`	`int`	No	-	Max tokens
`include_metadata`	`bool`	No	`true`	Include metadata
`include_syntax_highlighting`	`bool`	No		Include syntax highlighting
`chunk_start`	`int`	No	`0`	Chunk start position

Timeout: 60s

System & Utility Tools #

repository_context Stable

Manage repository session context — list, set, or inspect available repositories and branches.

Parameters:

actionRequired

Type: Literal[list, set, info]
Description: Operation

repositoryOptional

Type: str
Default
Description: Repository identifier (owner/repo[:branch]).

branchOptional

Type: str
Default
Description: Branch name (leave blank to use the session or repository default).

patternOptional

Type: str | None
Default
Description: Filter pattern

include_statsOptional

Type: bool
Default
Description: Include statistics

limitOptional

Type: int
Description: Max repositories

include_graph_metricsOptional

Type: bool
Default
Description: Include graph topology metrics in info response

Parameter	Type	Required	Default	Description
`action`	`Literal[list, set, info]`	Yes	-	Operation
`repository`	`str`	No		Repository identifier (owner/repo[:branch]).
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`pattern`	`str \| None`	No		Filter pattern
`include_stats`	`bool`	No		Include statistics
`limit`	`int`	No	-	Max repositories
`include_graph_metrics`	`bool`	No		Include graph topology metrics in info response

Timeout: 30s

ask_maguyva Stable

Maguyva's Swiss army knife — guidance, feedback, and 52+ deterministic compute functions. • Guidance: ask_maguyva(operation='guidance', query='getting_started') • Compute: ask_maguyva(operation='evaluate', query="sha256('hello')") • Bug: ask_maguyva(operation='report_bug', query='description of issue') • Feature: ask_maguyva(operation='request_feature', query='description of request')

Parameters:

operationRequired

Type: str
Description: One of: guidance, evaluate, report_bug, request_feature

queryOptional

Type: str
Default
Description: Guide topic, expression to evaluate, or feedback message

Parameter	Type	Required	Default	Description
`operation`	`str`	Yes	-	One of: guidance, evaluate, report_bug, request_feature
`query`	`str`	No		Guide topic, expression to evaluate, or feedback message

Timeout: 30s

Best Practices #

Use Repository Context: Set the current repository for the session to avoid repeating it in every call.
Choose the Right Search Mode: Use intelligent_search with mode="auto" for most cases. Specify a mode when you know exactly what you need.
Leverage Language Filters: Use language_filter to narrow results and improve performance.
GraphRAG Boosting: GraphRAG importance boosting is enabled by default for semantic search. Set boost_by_importance=False to disable it for pure vector similarity.
Fuzzy Resolution Is Built-In: repository_context automatically resolves close repository matches to handle minor typos.
Combine Tools: Use multiple API methods together for comprehensive analysis.
Handle Large Results: Use limit and tool-specific paging controls (for example chunk_start in get_file).
Deterministic Operations: Use ask_maguyva for hash, base64, JSON, and math operations to avoid hallucination.

Performance Characteristics #

Operation	Latency
Semantic search	Sub-second
Text search	Sub-second
Structural search	Fast (optimized AST indexing)
Dependency search	Efficient (depth limiting)
File retrieval	Near-instant
Repository context	Cached
ask_maguyva (deterministic ops)	Near-instant (no database call)

Error Handling #

All API methods return a structured envelope:

status: String — "success", "error", or "partial"
tool: Name of the tool that generated the response
data: Result payload when successful (structure varies by tool)
error: Structured error object when status is "error" — includes type, message, suggestions, and recovery_actions
metadata: Additional information about the operation (routing, caching, parameter adjustments)
pagination: Present on list responses — includes has_more and next_cursor

Always check the status field before processing results. A "partial" status indicates fuzzy match suggestions when the exact repository was not found.

Getting Started #

Configure MCP Client: Point your MCP client to the Maguyva server endpoint
Set Repository Context: Use repository_context to set the current repository for the session
Start Searching: Begin with intelligent_search and explore specialized tools as needed
Combine Tools: Use multiple tools together for comprehensive code analysis

For detailed integration instructions, see the installation guide.