# Dokumentacja API MCP

Canonical source: https://maguyva.ai/pl/docs/mcp-api

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Poznaj 11 narzędzi MCP Maguyva, ich parametry i zastosowania. Dostępne argumenty znajdziesz w odpowiedzi tools/list podłączonego klienta.

## Core Search Tools

### intelligent_search

Canonical source: https://maguyva.ai/docs/mcp-api#intelligent-search

Start here for any codebase question. Default auto/balanced routes confident definition queries to structural search, reference/impact queries to graph, and exact-match queries to text; other queries use semantic plus text. mode=hybrid or auto with quality=thorough runs all four modalities. An explicit mode takes precedence over quality. language_filter omits graph from auto/hybrid and rejects explicit mode=graph. Prefer this over Grep/Glob when you do not already know the path.

**Parameters**:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | `str` | Yes | -- | Search query Constraints: minLength=1. |
| `repository` | `str` | No | -- | Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. Exact indexed branches are preferred; an unavailable branch may fall back to main or the sole accessible branch. Response metadata shows requested and resolved identity and warns on fallback. |
| `mode` | `Literal[auto, hybrid, semantic, text, structural, ast, graph]` | No | auto | Search mode |
| `limit` | `int` | No | 10 | Maximum results in this ranked top-K window Constraints: maximum=50, minimum=1. |
| `language_filter` | `str` | No | -- | Language filter |
| `path_filter` | `str` | No | -- | Filter retrieval candidates by file path prefix. Graph neighbors and attached community context may include files outside this prefix. |
| `boost_by_importance` | `bool` | No | False | Opt-in: re-rank by centrality using per-symbol graph metrics (is_articulation_point, bridge_count, k_core, centrality, etc.). Default off for agent-safe ranking (global hubs can drown implementation hits); enable for architecture tours. Applies across all 4 modalities when each result carries symbol linkage. |
| `branch` | `str` | No | -- | Branch override |
| `quality` | `Literal[quick, balanced, thorough]` | No | balanced | Search quality preset |
| `include_content` | `bool` | No | True | Include content in results |
| `explain_routing` | `bool` | No | False | Include routing decision explanation |
| `importance_weight` | `float` | No | 0.3 | Weight for importance boosting (0=none, 1=full) Constraints: maximum=1, minimum=0. |
| `orphans` | `bool` | No | False | Include orphan symbols (no incoming references) |
| `include_community_context` | `bool` | No | False | Include related symbols from same code community |
| `community_depth` | `int` | No | 1 | Depth of community context expansion Constraints: maximum=3, minimum=1. |
| `graph_view` | `Literal[dependency, type, data_flow, control_flow]` | No | dependency | Graph view for metrics |
| `seed_symbol_ids` | `list[str]` | No | -- | Tier-1 task seeds: symbol IDs central to the current task. When set, re-ranks fused hits by Approach A depth-decay proximity (exact seed match + graph-edge hops). Additive — omit for global ranking. Constraints: maxItems=20. |
| `seed_file_paths` | `list[str]` | No | -- | Tier-1 task seeds: indexed file paths the agent has open or just edited. When set, re-ranks fused hits by path proximity with 1/(1+d) depth-decay (same file → same dir → nearby packages). Additive — omit for global ranking. Constraints: maxItems=10. |

### semantic_search

Canonical source: https://maguyva.ai/docs/mcp-api#semantic-search

Find code by meaning, not exact text. Use for conceptual queries like "retry logic" or "user onboarding flow" when you don't know the keyword or symbol name. Returns relevant chunks with bounded file diversity; graph-importance re-ranking is opt-in via boost_by_importance. Prefer over Grep when the search is conceptual.

**Parameters**:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | `str` | Yes | -- | Search query (conceptual, meaning-based) Constraints: minLength=1. |
| `repository` | `str` | No | -- | Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. Exact indexed branches are preferred; an unavailable branch may fall back to main or the sole accessible branch. Response metadata shows requested and resolved identity and warns on fallback. |
| `limit` | `int` | No | 5 | Maximum results in this ranked top-K window Constraints: maximum=50, minimum=1. |
| `similarity_threshold` | `float` | No | 0.6 | Minimum similarity score Constraints: maximum=1, minimum=0. |
| `language_filter` | `str` | No | -- | Language filter (python, typescript, etc.) |
| `path_filter` | `str` | No | -- | Filter by file path prefix |
| `boost_by_importance` | `bool` | No | False | Opt-in: re-rank by normalized per-symbol graph importance (default off; capped at 1.5x similarity) |
| `branch` | `str` | No | -- | Branch override (default: from repository param or main) |
| `include_content` | `bool` | No | True | Include chunk content in results |
| `graph_view` | `Literal[dependency, type, data_flow, control_flow]` | No | dependency | Graph view for metrics |

### text_pattern_search

Canonical source: https://maguyva.ai/docs/mcp-api#text-pattern-search

Search indexed content. Exact and regex modes grep the full file/blob corpus; fuzzy content mode searches the bounded semantic chunk corpus. File and symbol scopes are trigram-only — default mode=exact is coerced to fuzzy. Language/case/custom-threshold controls require content scope. File path filtering uses a bounded candidate window and reports incomplete coverage. Use local Grep for a tight directory already on disk.

**Parameters**:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | `str` | Yes | -- | Text pattern to search for Constraints: minLength=1. |
| `repository` | `str` | No | -- | Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. Exact indexed branches are preferred; an unavailable branch may fall back to main or the sole accessible branch. Response metadata shows requested and resolved identity and warns on fallback. |
| `mode` | `Literal[fuzzy, exact, regex]` | No | exact | Search mode. Regex executes PostgreSQL advanced/POSIX syntax; use \\y for word boundaries (\\b means backspace). Patterns also pass a JavaScript safety validator, so PostgreSQL-only constructs such as inline (?i) flags are rejected; use case_sensitive instead. |
| `search_scope` | `Literal[content, symbols, files]` | No | content | What to search |
| `limit` | `int` | No | 5 | Maximum results per page without cursor. Continuation uses the page size stored in cursor; omit cursor to start with a different limit. Constraints: maximum=50, minimum=1. |
| `offset` | `int` | No | -- | Deprecated compatibility offset. Prefer cursor from pagination.next_cursor. Constraints: minimum=0. |
| `cursor` | `str` | No | -- | Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged. Its position and page size override offset and limit. |
| `language_filter` | `str` | No | -- | Language filter |
| `path_filter` | `str` | No | -- | Filter by file path prefix |
| `case_sensitive` | `bool` | No | False | Case-sensitive matching |
| `branch` | `str` | No | -- | Branch override |
| `fuzzy_algorithm` | `Literal[hybrid, trigram, levenshtein]` | No | hybrid | Fuzzy matching algorithm |
| `threshold` | `float` | No | 0.05 | Minimum similarity threshold for fuzzy Constraints: maximum=1, minimum=0. |
| `semantic_fallback` | `bool` | No | False | Try semantic search after an empty first lexical page; metadata.fallback_status distinguishes used, empty, and unavailable fallback |

## Structural & Graph Tools

### structural_search

Canonical source: https://maguyva.ai/docs/mcp-api#structural-search

Prefer preset=functions|classes|methods|imports|variables (or free pattern=). Find code by AST shape (not text). Mid-tier filters: name_pattern, node_type, decorator, parent_child. Path/ltree/call filters are advanced — set advanced=true when using them deliberately. Without it, advanced filters are applied with a metadata warning. Supply at least one structural selector.

**Parameters**:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `repository` | `str` | No | -- | Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. Exact indexed branches are preferred; an unavailable branch may fall back to main or the sole accessible branch. Response metadata shows requested and resolved identity and warns on fallback. |
| `preset` | `Literal[functions, classes, methods, imports, variables]` | No | -- | Preferred structural selector. Expands to cross-language AST node types — functions (function/arrow/method definitions across languages); classes (class/struct/interface declarations, type bodies, and implementations); methods (method definitions (and function_definition for languages without a method node)); imports (import/use/include statements); variables (variable/let/const/static declarations). Prefer over free-form pattern/node_type for browse-style queries. |
| `pattern` | `str` | No | -- | Free-form pattern fills missing selectors (auto-detected: 'def foo(' → node_type + name_pattern). May combine with preset; explicit selectors take precedence. Prefer preset= for browse queries. |
| `name_pattern` | `str` | No | -- | Symbol name pattern (shell wildcard, bounded POSIX regex, or fuzzy text; max 256 characters) Constraints: maxLength=256. |
| `node_type` | `str` | No | -- | AST node type (function_definition, class_definition, etc.) — prefer preset= for common shapes |
| `decorator` | `str` | No | -- | Decorator name filter |
| `base_class` | `str` | No | -- | Base class filter |
| `language_filter` | `str` | No | -- | Language filter (python, typescript, etc.) |
| `limit` | `int` | No | 20 | Maximum results per page without cursor. Continuation uses the page size stored in cursor; omit cursor to start with a different limit. Constraints: maximum=50, minimum=1. |
| `offset` | `int` | No | -- | Deprecated compatibility offset. Prefer cursor from pagination.next_cursor. Constraints: minimum=0. |
| `cursor` | `str` | No | -- | Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged. Its position and page size override offset and limit. |
| `path_filter` | `str` | No | -- | Filter by file path prefix |
| `branch` | `str` | No | -- | Branch override |
| `query_type` | `Literal[node_type, name_pattern, parent_child]` | No | -- | Explicit query type |
| `parent_type` | `str` | No | -- | Parent AST node type filter |
| `relationship` | `Literal[parent, ancestor]` | No | parent | For parent_child queries: direct parent only, or any ancestor (use ancestor for class methods nested under a class body/block) |
| `has_modifier` | `str` | No | -- | Filter by modifier (export, async, static, etc.) |
| `advanced` | `bool` | No | False | Set true when intentionally using advanced path/ltree/call filters (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). When false, supplied advanced filters are applied with a metadata warning. Prefer preset= for common structural queries. |
| `callee_text` | `str` | No | -- | Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. Call expression callee text filter. Set advanced=true when intentionally using path/ltree/call filters. |
| `callee_name` | `str` | No | -- | Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. Call expression callee name filter. Set advanced=true when intentionally using path/ltree/call filters. |
| `field_role` | `str` | No | -- | Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. AST field role filter. Set advanced=true when intentionally using path/ltree/call filters. |
| `ltree_ancestor` | `str` | No | -- | Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. AST ltree ancestor path filter. Set advanced=true when intentionally using path/ltree/call filters. |
| `ltree_descendant` | `str` | No | -- | Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. AST ltree descendant path filter. Set advanced=true when intentionally using path/ltree/call filters. |
| `definition_name` | `str` | No | -- | Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. Definition name filter. Set advanced=true when intentionally using path/ltree/call filters. |
| `min_depth` | `int` | No | -- | Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. Minimum AST depth. Set advanced=true when intentionally using path/ltree/call filters. |
| `max_depth` | `int` | No | -- | Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. Maximum AST depth. Set advanced=true when intentionally using path/ltree/call filters. |

### dependency_search

Canonical source: https://maguyva.ai/docs/mcp-api#dependency-search

Primary blast-radius / graph surface. Answer "what calls this?" / "what does this use?" via the real call/import graph. For impact before edit: analysis_type="dependents" or analysis_type="impact" (incoming, shallow default for impact), include_metrics=false by default (opt in for centrality + refactor_risk). Dependents/impact include production_callers by default: unique production usage sites by kind (call, instantiate, value_reference for functions passed as values) plus IMPORT sites, tests excluded, EXTRACTED/INFERRED confidence — not a metrics dump. PR/diff impact: pass changed_paths and/or patch (unified diff) — resolves symbols per path and returns a compact shallow-incoming dependents payload without requiring a symbol name. After an edit, set verify_after_edit=true with targets and/or changed_paths for a compact multi-root re-query of impacted symbols. Also supports dependencies, centrality, and orphans. analyze_dependencies uses the same traversal for multi-hop impact analysis.

**Parameters**:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `repository` | `str` | No | -- | Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. Exact indexed branches are preferred; an unavailable branch may fall back to main or the sole accessible branch. Response metadata shows requested and resolved identity and warns on fallback. |
| `query` | `str` | No | -- | Symbol name or search term |
| `target` | `str` | No | -- | Symbol name (alias for query) |
| `symbol_id` | `UUID` | No | -- | Choose a specific UUID occurrence among the named query/target candidates after namespace, path and language filtering. Use an ID returned by find_symbol or graph alternates. Named traversal only; an ID outside the bounded candidate window errors. |
| `changed_paths` | `list[str]` | No | -- | Exact repo-relative file paths for PR/diff impact (default) or, with verify_after_edit=true, post-edit verify roots. Unresolved paths may return labelled suggestions; suggested files never become impact roots. PR/diff: without line info, walks each path's top-level definitions (exported first, file order) and reports changed_lines_unknown; pass patch= for line-level changed symbols. Verify: up to 5 top-level definitions per path as verify roots (capped lower inside verify mode). Does not require query/target for PR/diff impact. Constraints: maxItems=50. |
| `patch` | `str` | No | -- | PR/diff impact: unified diff / git patch text. Paths come from diff --git / --- / +++ headers; hunk lines (old side = the indexed commit) map to the enclosing functions/methods/classes, which are walked for exact dependents, public_api_changed and the callers the diff does not touch. Constraints: maxLength=500000. |
| `head_commit` | `str` | No | -- | Commit SHA of the code you are asking about (git rev-parse HEAD, or the base commit of the patch). complete:true requires the index to be at this commit and built by the current resolver; otherwise complete stays false with index_stale / index_freshness_unverified / index_built_by_older_resolver and index_basis.statement says what the answer is complete within. A patch's 'base-commit:' line (git format-patch --base) also supplies it. Constraints: pattern=^[0-9a-fA-F]{7,64}$. |
| `analysis_type` | `Literal[centrality, dependencies, dependents, impact, orphans]` | No | dependencies | Analysis mode. impact = blast radius (incoming dependents; shallow depth when depth omitted). dependents also answers impact. When changed_paths or patch is set, analysis is forced to PR/diff impact. centrality/orphans do not require a target. Orphans are unused-code candidates, not proof of safe removal; verify source references. |
| `depth` | `Literal[shallow, balanced, deep]` | No | -- | Traversal depth. Defaults to balanced; impact and PR/diff impact default to shallow. Explicit depth overrides these defaults. Verify mode always uses shallow. |
| `limit` | `int` | No | 20 | Maximum results per page without cursor. Continuation uses the page size stored in cursor; omit cursor to start with a different limit. Constraints: maximum=50, minimum=1. |
| `offset` | `int` | No | -- | Deprecated compatibility offset. Prefer cursor from pagination.next_cursor. Constraints: minimum=0. |
| `cursor` | `str` | No | -- | Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged. Its position and page size override offset and limit. |
| `path_filter` | `str` | No | -- | Restrict target symbol resolution by file path prefix; returned graph relationships may cross outside that path |
| `language_filter` | `str` | No | -- | Filter target resolution and browse results by language |
| `direction` | `Literal[outgoing, incoming, both]` | No | -- | Traversal direction (overrides analysis_type inference) |
| `relationship_types` | `list[str]` | No | -- | Filter edge types (CALL, IMPORT, INHERITS_FROM, etc.). A non-empty list overrides graph_view defaults. |
| `exclude_test_paths` | `bool` | No | True | Default true: exclude test, fixture, vendor, and example paths from traversal and centrality results. Set false to include them. Orphan analysis honours this only where the deployed backend supports it; otherwise it keeps its own stricter noise exclusions and reports the adjustment. |
| `exclude_generated_paths` | `bool` | No | False | Exclude generated declarations plus build, coverage, cache, source-map, and minified artifact paths from traversal results |
| `include_module_symbols` | `bool` | No | False | Default false: drop edges whose from_name or to_name is the synthetic __module__ symbol (module-level noise). Set true to include module-level edges in dependents/dependencies results. |
| `include_isolated` | `bool` | No | -- | Orphans only. Default false. Set true to also return symbols with no graph-metrics row (zero graph edges anywhere). While exclude_test_paths is true, stylesheet/markup/data symbols (CSS, HTML, ...), .d.ts declarations and test/fixture/vendor/example paths stay excluded where the backend supports it, unless language_filter names that language; TypeScript object-literal properties can still appear as isolated functions |
| `exclude_exported` | `bool` | No | False | Orphans only. Default false: exported symbols (public API) that nothing in the repository uses are returned with is_exported=true. Set true for internal-only candidates. |
| `branch` | `str` | No | -- | Branch override |
| `per_hop_limit` | `int` | No | -- | Maximum relationships per hop (1-300) Constraints: maximum=300, minimum=1. |
| `include_metrics` | `bool` | No | False | Opt-in graph metrics on result rows (compacted with refactor_risk). Metrics are also fetched internally when min_centrality>0 but not returned unless this is true. |
| `metrics_detail` | `Literal[summary, full]` | No | summary | When include_metrics=true: summary (default) returns decision signals + refactor_risk; full returns the larger curated metric set |
| `include_edge_metadata` | `bool` | No | False | Include raw edge metadata and weights (large). Compact impact payloads leave this off. |
| `symbol_types` | `list[str]` | No | -- | Filter returned symbols by kind (function, class, method, etc.). Not supported in orphan analysis; use path_filter or language_filter there. An empty list applies no kind filter. |
| `exact_match` | `bool` | No | False | Require exact symbol name match |
| `find_similar_patterns` | `bool` | No | False | Find similar usage patterns |
| `min_centrality` | `float` | No | 0 | Minimum PageRank score for named-symbol traversal and PR/diff impact. Positive thresholds are unsupported in centrality/orphans browse modes. Metrics are fetched internally for filtering; graph_metrics are returned only when include_metrics=true. Ignored by verify_after_edit, which uses fixed compact controls. Constraints: minimum=0. |
| `graph_view` | `Literal[dependency, type, data_flow, control_flow]` | No | dependency | Graph view used for traversal relationship defaults, metrics, and centrality ranking; orphan analysis is calculated across all views |
| `verify_after_edit` | `bool` | No | False | Re-query the indexed impact graph for edited symbols in one compact multi-root response. Requires targets and/or changed_paths (or target/query). Uses fixed shallow traversal and compact budgets; depth/limit/cursor/metrics controls do not apply. Defaults to incoming dependents; results reflect the indexed graph (may lag live edits). When true, takes precedence over PR/diff impact on the same changed_paths. |
| `targets` | `list[str]` | No | -- | When verify_after_edit=true: symbol names to re-verify (callers/dependents). Merged with target/query if both are supplied. Constraints: maxItems=15. |

## Code Analysis Tools

### find_symbol

Canonical source: https://maguyva.ai/docs/mcp-api#find-symbol

Jump to where a function, class, or variable is defined and used. Use when you know the name (e.g. "getCurrentUser") — faster and more precise than Grep, and it spans the whole indexed repo. Optionally returns references and importance metrics.

**Parameters**:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `symbol_name` | `str` | No | -- | Symbol name to search for (optional — omit to browse by metrics) |
| `repository` | `str` | No | -- | Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. Exact indexed branches are preferred; an unavailable branch may fall back to main or the sole accessible branch. Response metadata shows requested and resolved identity and warns on fallback. |
| `scope` | `Literal[definitions, references, both]` | No | both | Search scope; references requires a nonempty symbol_name |
| `limit` | `int` | No | 15 | Maximum results per page without cursor. Continuation uses the page size stored in cursor; omit cursor to start with a different limit. Constraints: maximum=50, minimum=1. |
| `offset` | `int` | No | -- | Deprecated compatibility offset. Prefer cursor from pagination.next_cursor. Constraints: minimum=0. |
| `cursor` | `str` | No | -- | Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged. Its position and page size override offset and limit. |
| `find_similar` | `bool` | No | False | Include similar symbol names |
| `include_metrics` | `bool` | No | False | Include centrality metrics |
| `metrics_detail` | `Literal[summary, full]` | No | summary | When include_metrics=true: summary (default) returns decision signals + refactor_risk; full returns the larger curated metric set |
| `path_filter` | `str` | No | -- | Filter by file path prefix |
| `branch` | `str` | No | -- | Branch override |
| `symbol_type` | `str` | No | -- | Filter by indexed symbol kind, e.g. function, class, struct, enum, or trait. Use the kind returned by a symbol result; kinds vary by language. Constraints: minLength=1. |
| `high_impact` | `bool` | No | False | Browse architecturally important symbols (omit symbol_name). Default mode is popularity (top PageRank decile minus utility mega-hubs). Set high_impact_mode=risk for articulation/bridge cut-vertices. |
| `high_impact_mode` | `Literal[popularity, risk]` | No | popularity | When high_impact=true: popularity = top PageRank decile minus utility mega-hubs/modules; risk = articulation points ranked by SMV bridge_count then k_core (structural refactor risk, not hub popularity) |
| `in_cycle` | `bool` | No | False | Filter to symbols with recorded dependency-cycle membership |
| `exclude_test_paths` | `bool` | No | True | When browsing by graph metrics, exclude tests, fixtures, vendor code, and examples before ranking; named symbol lookup is unchanged |
| `reference_views` | `list[Literal[dependency, type, data_flow, control_flow, all]]` | No | -- | Graph views whose incoming edges fill references/reference_count (scope references/both). Default ["dependency", "type"]: calls, imports, exports, references, instantiations, inheritance, overrides, decorators, type use. Unless data_flow is selected, exact-resolved data_flow uses (callbacks, handlers, sort keys) come back separately as value_references/value_reference_count, without bare-name inferred matches. Add data_flow or control_flow, or pass ["all"] for every edge type and tier. Same view families as dependency_search graph_view. Constraints: maxItems=5, minItems=1. |
| `relationship_types` | `list[str]` | No | -- | Explicit reference edge types (CALL, IMPORT, READS, etc.). A non-empty list overrides reference_views. |

### analyze_dependencies

Canonical source: https://maguyva.ai/docs/mcp-api#analyze-dependencies

Analyze blast radius using the same traversal as dependency_search (dependents/incoming). Prefer dependency_search with analysis_type="dependents" or "impact" for impact analysis. Returns a multi-hop impact response with graph, connection_summary, and optional metrics with refactor_risk. connection_summary counts relationship-scoped edges for the chosen root before test/path filtering. Legacy incoming_production/outgoing_production fields mean non-module edges, including tests; they are not production caller counts. Use graph_view to scope relationship family: dependency (default), type, data_flow, control_flow.

**Parameters**:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `repository` | `str` | No | -- | Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. Exact indexed branches are preferred; an unavailable branch may fall back to main or the sole accessible branch. Response metadata shows requested and resolved identity and warns on fallback. |
| `target` | `str` | Yes | -- | Symbol name to analyze Constraints: minLength=1. |
| `symbol_id` | `UUID` | No | -- | Choose a specific UUID occurrence among target candidates after namespace, path and language filtering; outside-window IDs error. |
| `depth` | `Literal[shallow, balanced, deep]` | No | balanced | Analysis depth |
| `limit` | `int` | No | 10 | Maximum results per page without cursor. Continuation uses the page size stored in cursor; omit cursor to start with a different limit. Constraints: maximum=50, minimum=1. |
| `offset` | `int` | No | -- | Deprecated compatibility offset. Prefer cursor from pagination.next_cursor. Constraints: minimum=0. |
| `cursor` | `str` | No | -- | Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged. Its position and page size override offset and limit. |
| `direction` | `Literal[incoming, outgoing, both]` | No | incoming | Traversal direction |
| `relationship_types` | `list[str]` | No | -- | Filter edge types (CALL, IMPORT, INHERITS_FROM, etc.). A non-empty list overrides graph_view defaults; an empty list uses those defaults. |
| `graph_view` | `Literal[dependency, type, data_flow, control_flow]` | No | dependency | Graph view: determines both the default traversal edge types and which view's metrics are used when include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (default), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Applied as the relationship_types default when relationship_types is omitted or empty. Matches dependency_search's existing graph_view parameter name for consistency across tools. |
| `path_filter` | `str` | No | -- | Restrict target symbol resolution by file path prefix; returned graph relationships may cross outside that path |
| `language_filter` | `str` | No | -- | Language filter |
| `branch` | `str` | No | -- | Branch override |
| `per_hop_limit` | `int` | No | -- | Maximum relationships per hop (1-300) Constraints: maximum=300, minimum=1. |
| `include_metrics` | `bool` | No | False | Include graph metrics in results, each enriched with a derived refactor_risk block ({risk: "low"\|"medium"\|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk is "low" when not an articulation point (in the selected view), "medium" when an articulation point bridging few edges, "high" when bridging many (heuristic threshold, not empirically validated). Omitted per-symbol when no metrics row exists for that symbol/view. |
| `metrics_detail` | `Literal[summary, full]` | No | summary | When include_metrics=true: summary (default) returns decision signals + refactor_risk; full returns the larger curated metric set |
| `include_edge_metadata` | `bool` | No | False | Include raw edge metadata and weights. Disabled by default because extractor metadata can be large; enrichment coverage is reported when enabled. |
| `exclude_test_paths` | `bool` | No | True | Default true: exclude test, fixture, vendor, and example paths from returned graph edges. Set false to include them. |
| `include_module_symbols` | `bool` | No | False | Default false: drop edges whose from_name or to_name is the synthetic __module__ symbol. Set true to include module-level edges. |
| `head_commit` | `str` | No | -- | Commit SHA of the code you are asking about (git rev-parse HEAD, or the base commit of the patch). complete:true requires the index to be at this commit and built by the current resolver; otherwise complete stays false with index_stale / index_freshness_unverified / index_built_by_older_resolver and index_basis.statement says what the answer is complete within. A patch's 'base-commit:' line (git format-patch --base) also supplies it. Constraints: pattern=^[0-9a-fA-F]{7,64}$. |

### get_task_context

Canonical source: https://maguyva.ai/docs/mcp-api#get-task-context

Starting work in an unfamiliar area? Describe the task (e.g. "add SSO support", "fix the billing webhook") and get a bounded one-call bundle of relevant files, code, symbols, and dependencies. Seeded files contribute direct indexed content even when they define no symbols. Failed layers are labelled; total retrieval failure returns a tool error. For more results, continue with the specialized search tool for that layer.

**Parameters**:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `task_description` | `str` | Yes | -- | Description of the task you need context for Constraints: minLength=1. |
| `repository` | `str` | No | -- | Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. Exact indexed branches are preferred; an unavailable branch may fall back to main or the sole accessible branch. Response metadata shows requested and resolved identity and warns on fallback. |
| `limit` | `int` | No | 15 | Maximum results per layer Constraints: maximum=50, minimum=1. |
| `scope` | `Literal[semantic, symbols, dependencies, all]` | No | all | Which context layers to include |
| `language_filter` | `str` | No | -- | Language filter: requires scope=semantic without explicit seeds or related context; other layer indexes cannot enforce language |
| `path_filter` | `str` | No | -- | File path prefix for semantic and keyword retrieval roots. Explicit seeds may be outside this prefix; graph context may cross directory boundaries. |
| `branch` | `str` | No | -- | Branch override |
| `include_related_context` | `bool` | No | False | Include related context from adjacent symbols |
| `seed_symbol_ids` | `list[str]` | No | -- | Explicit task seeds: first in the symbols layer and retained within the bounded dependencies/related_context window. Graph layers rank explicit seeds and their nearest neighborhood before keyword fallback; importance breaks relevance ties. Graph expansion requires scope=all\|dependencies (scope=symbols\|semantic never runs the dependency traversal). Omit for keyword-only depth-decayed importance ranking. Constraints: maxItems=20. |
| `seed_file_paths` | `list[str]` | No | -- | Explicit seeds: exact indexed file paths the agent has open or just edited. Returns bounded direct file evidence and up to 5 graph seeds per file, prioritizing exact task-name matches from bounded symbol lookup before definitions and incidental symbols. Symbol-free files still supply evidence. Missing files may return labelled suggestions that are not seeds. Graph expansion requires scope=all\|dependencies. Constraints: maxItems=10. |

### get_file

Canonical source: https://maguyva.ai/docs/mcp-api#get-file

Read a file from the indexed repo by path. Prefer local file tools for files on disk; use this for remote indexed snapshots. Continue bounded responses with metadata.next_line_start and next_character_start. Remove the trailing newline plus [truncated] marker only when metadata.truncated=true; otherwise it may be literal source text.

**Parameters**:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `file_path` | `str` | Yes | -- | File path relative to repository root |
| `repository` | `str` | No | -- | Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. Exact indexed branches are preferred; an unavailable branch may fall back to main or the sole accessible branch. Response metadata shows requested and resolved identity and warns on fallback. |
| `line_start` | `int` | No | -- | Start line (1-indexed) Constraints: minimum=1. |
| `line_end` | `int` | No | -- | End line (1-indexed, inclusive; must be at or after line_start) Constraints: minimum=1. |
| `character_start` | `int` | No | 0 | UTF-16 code-unit offset within the starting line only (0-indexed). Use metadata.next_character_start for partial-line continuation. Constraints: minimum=0. |
| `branch` | `str` | No | -- | Branch override |
| `max_tokens` | `int` | No | 5000 | Approximate content budget (4 UTF-16 code units per token; not an exact tokenizer limit) Constraints: maximum=50000, minimum=1. |
| `include_metadata` | `bool` | No | True | Include descriptive file metadata. Truncation and continuation metadata are always returned. |

## System & Utility Tools

### repository_context

Canonical source: https://maguyva.ai/docs/mcp-api#repository-context

List the repositories you can search, or get identity info on one (namespace/branch, indexed_commit_sha / index freshness). Use action:"list" when the repo slug is unknown; searches accept a known slug directly or default to your key's single repo. List uses pattern and pagination; info requires repository and supports branch and opt-in include_statistics=true.

**Parameters**:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `action` | `Literal[list, info]` | Yes | -- | Action: list available repos or get repo info |
| `repository` | `str` | No | -- | Info only: repository in owner/repo or owner/repo:branch format (required for info) |
| `branch` | `str` | No | -- | Info only: branch override |
| `pattern` | `str` | No | -- | List only: case-insensitive repository-name substring |
| `include_statistics` | `bool` | No | False | Info only: include bounded indexed-data counts. File/blob counts are exact; larger index counts are estimates. Read count_accuracy and estimate_analyzed_at. Default false. |
| `limit` | `int` | No | 20 | Maximum results per page without cursor. Continuation uses the page size stored in cursor; omit cursor to start with a different limit. Constraints: maximum=50, minimum=1. |
| `offset` | `int` | No | -- | Deprecated compatibility offset. Prefer cursor from pagination.next_cursor. Constraints: minimum=0. |
| `cursor` | `str` | No | -- | Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged. Its position and page size override offset and limit. |

### ask_maguyva

Canonical source: https://maguyva.ai/docs/mcp-api#ask-maguyva

Get Maguyva tool guidance, or submit a bug report / feature request stored for Maguyva's maintainers. Never include secrets or sensitive personal data in feedback. The evaluate operation supports deterministic expressions; prefer local compute or host tools for math/hash/string work.

**Parameters**:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `operation` | `Literal[guidance, report_bug, request_feature, evaluate]` | Yes | -- | Use guidance for tool help, report_bug for bugs, or request_feature for suggestions. evaluate runs deterministic expressions; prefer local compute for calculations. |
| `query` | `str` | No | -- | Guidance topic (e.g. tool_selection, semantic_search), or an expression string for evaluate. Constraints: maxLength=500. |
| `description` | `str` | No | -- | Required for report_bug and request_feature. Free-form feedback for Maguyva's maintainers. Never include secrets or sensitive personal data. Constraints: maxLength=4000, minLength=1. |
| `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]` | No | -- | Optional Maguyva tool most closely related to the feedback |