MCP Tools

sqry exposes 37 tools over MCP when run standalone (sqry-mcp). When connecting through the sqryd daemon (sqry-mcp --daemon), a curated 16-tool subset is exposed — the 21 standalone-only tools remain available only on direct sqry-mcp. Every tool returns a JSON payload with version, data, and execution_ms fields wrapped in the standard MCP content array. Use tools/list or sqry-mcp --list-tools to retrieve the authoritative parameter schema at runtime.

All parameter names are snake_case (matching the serde-deserialized schema in sqry-mcp/src/tools/params.rs). The path parameter on every tool defaults to "." (the current working directory) and selects the workspace root.

Serialised tool responses are truncated at 50 000 bytes by default (UTF-8 boundary safe). Override with SQRY_MCP_MAX_OUTPUT_BYTES=<n> when your transport accepts larger payloads.

Fuzzy, typo-tolerant symbol search with structured filters and pagination. The query string accepts the core query parser grammar (lang:, kind:, path:, name:, visibility:, parent:, combinators AND/OR/NOT, and inline regex name~=/regex/).

Key parameters: query (string, required), path (string), filters (object — language[], visibility, symbol_kind[], score_min), max_results (int, default 200), context_lines (int, default 3), include_classpath (bool), pagination (object — cursor, page_size), budget_rows (int), framework (string, optional — filter by detected web framework; route coverage expanding), resolved_via (string, optional — filter Calls edges by resolution provenance: direct, type_match, binding_plane)

Example: Find all public async functions whose name contains “auth”:

{
  "query": "kind:function AND visibility:public AND name~=/auth/",
  "path": ".",
  "filters": { "language": ["rust"], "symbol_kind": ["function"] },
  "max_results": 50
}

RAG-optimized search that returns results grouped by file → container → symbol. Useful when an AI needs to build a structured context window.

Key parameters: query (string, required), path (string), filters (object), max_results (int, default 200), max_total_symbols (int, default 2000), context_lines (int, default 3), auto_merge (bool, default true), merge_threshold (int, default 256), max_files (int, default 20), max_containers_per_file (int, default 50), max_symbols_per_container (int, default 100), file_target_tokens (int, default 2000), container_target_tokens (int, default 1500), symbol_target_tokens (int, default 500), context_cluster_target_tokens (int, default 768), include_file_context (bool), include_container_context (bool), pagination (object), expand_files (string[]), budget_rows (int)

Example:

{
  "query": "kind:class name:UserService",
  "path": ".",
  "max_files": 5,
  "max_symbols_per_container": 10,
  "include_file_context": true,
  "include_container_context": true
}

search_similar

Find symbols that are semantically similar to a reference symbol using fuzzy matching. The reference parameter is a nested object with file_path and symbol_name.

Key parameters: reference (object, required — file_path, symbol_name), path (string), similarity_threshold (float 0.0–1.0, default 0.7), max_results (int, default 20), page_token (string), page_size (int, default 20)

Example:

{
  "reference": { "file_path": "src/auth/service.ts", "symbol_name": "authenticate" },
  "similarity_threshold": 0.75
}

Substring match on symbol names. Faster than semantic search for exact-prefix or suffix queries.

Key parameters: pattern (string, required), path (string), max_results (int, default 100), include_classpath (bool), pagination (object)

Example:

{ "pattern": "Handler", "max_results": 50 }

Code Understanding

explain_code

Return a symbol’s signature, documentation, callers, and callees in a single response.

Key parameters: file_path (string, required), symbol_name (string, required), path (string), include_context (bool, default true), include_relations (bool, default true)

Example:

{ "file_path": "src/auth.ts", "symbol_name": "validateToken", "include_context": true }

relation_query

Query any relation type for a target symbol: callers, callees, imports, exports, or returns.

Key parameters: symbol (string, required), relation_type (callers/callees/imports/exports/returns, required), path (string), max_depth (int, default 1), max_results (int, default 200), page_token (string), page_size (int, default 50), budget_rows (int), framework (string, optional — filter by detected web framework; route coverage expanding), resolved_via (string, optional — filter Calls edges by resolution provenance: direct, type_match, binding_plane)

Example:

{ "symbol": "processUser", "relation_type": "callers", "max_results": 20 }

show_dependencies

Return the dependency tree for a file or symbol up to a configurable depth. At least one of file_path or symbol_name is required.

Key parameters: file_path (string, optional), symbol_name (string, optional), path (string), max_depth (int, default 2), max_results (int, default 500), page_token (string), page_size (int, default 100). Constraint: file_path XOR symbol_name — at least one must be provided.

Example:

{ "file_path": "src/payment/service.ts", "max_depth": 3 }

dependency_impact

Reverse-dependency analysis: given a symbol, return all symbols that would be affected if it changed.

Key parameters: symbol (string, required), path (string), file_path (string, optional disambiguator), max_depth (int, default 3), include_files (bool, default true), include_indirect (bool, default true), max_results (int, default 500), page_token (string), page_size (int, default 100)

Example:

{ "symbol": "UserRepository", "include_indirect": true, "max_depth": 4 }

get_definition

Look up the definition location of a symbol — equivalent to LSP go-to-definition.

Key parameters: symbol (string, required), path (string)

Example:

{ "symbol": "authenticate" }

get_references

Return all reference locations for a symbol across the workspace.

Key parameters: symbol (string, required), path (string), include_declaration (bool, default true), max_results (int, default 100), pagination (object)

Example:

{ "symbol": "UserService", "max_results": 100 }

get_hover_info

Return signature, documentation, and type information for a symbol by name.

Key parameters: symbol (string, required), path (string)

Example:

{ "symbol": "authenticate" }

get_document_symbols

List all symbols defined in a specific file.

Key parameters: file_path (string, required), path (string)

Example:

{ "file_path": "src/models/user.ts" }

get_workspace_symbols

Search for symbols by name across the entire indexed workspace.

Key parameters: query (string, required), path (string), max_results (int, default 100), pagination (object)

Example:

{ "query": "PaymentService", "max_results": 10 }

Call Hierarchy

call_hierarchy

Return a call hierarchy tree rooted at a symbol, traversing callers or callees to a configurable depth.

Key parameters: symbol (string, required), direction (incoming/outgoing, required), file_path (string, optional disambiguator), path (string), max_depth (int, default 1), max_results (int, default 200), page_token (string), page_size (int, default 50)

Example:

{ "symbol": "checkout", "direction": "incoming", "max_depth": 3 }

direct_callers

Single-hop callers only — faster than call_hierarchy when depth-1 is sufficient.

Key parameters: symbol (string, required), path (string), max_results (int, default 100), pagination (object), framework (string, optional — filter by detected web framework; route coverage expanding), resolved_via (string, optional — filter Calls edges by resolution provenance: direct, type_match, binding_plane)

Example:

{ "symbol": "validatePayment", "max_results": 25 }

direct_callees

Single-hop callees only.

Key parameters: symbol (string, required), path (string), max_results (int, default 100), pagination (object), framework (string, optional — filter by detected web framework; route coverage expanding), resolved_via (string, optional — filter Calls edges by resolution provenance: direct, type_match, binding_plane)

Example:

{ "symbol": "processOrder", "max_results": 25 }

Graph Operations

export_graph

Export a subgraph as DOT, D2, Mermaid, or JSON for visualization or external tooling. At least one of file_path, symbol_name, or symbols must be provided.

Key parameters: path (string), file_path (string, optional), symbol_name (string, optional), symbols (string[], optional), format (json/dot/d2/mermaid, default json), verbose (bool), max_depth (int, default 2), max_results (int, default 1000), page_token (string), page_size (int, default 200), include (edge-kind array — calls/imports/exports/returns, default [] = calls only), languages (string[])

Example:

{ "format": "mermaid", "symbol_name": "AuthService", "max_depth": 2 }

subgraph

Extract a focused subgraph around one or more seed symbols, including their immediate callers and callees.

Key parameters: symbols (string[], required non-empty), path (string), max_depth (int, default 2), max_nodes (int, default 50), include_callers (bool, default true), include_callees (bool, default true), include_imports (bool), cross_language (bool, default true), page_token (string), page_size (int, default 50)

Example:

{ "symbols": ["UserService", "AuthService"], "max_depth": 2, "max_nodes": 30 }

trace_path

Find all call paths between two symbols. Useful for understanding how control flows from an entry point to a target function.

Key parameters: from_symbol (string, required), to_symbol (string, required), path (string), max_hops (int, default 5), max_paths (int, default 5), cross_language (bool, default true), min_confidence (float 0.0–1.0, default 0.5)

Example:

{ "from_symbol": "handleRequest", "to_symbol": "writeDatabase", "max_hops": 6 }

cross_language_edges

List edges that cross language boundaries (e.g., a Python module calling a Rust extension, or a TypeScript file importing a Go-compiled WASM module).

Key parameters: path (string), from_lang (string, optional), to_lang (string, optional), max_results (int, default 500), page_token (string), page_size (int, default 200)

Example:

{ "from_lang": "python", "to_lang": "rust", "max_results": 100 }

Introspection

list_files

List all files in the index, optionally filtered by language.

Key parameters: path (string), language (string, optional), max_results (int, default 500), pagination (object)

Example:

{ "language": "rust", "max_results": 100 }

list_symbols

List indexed symbols, optionally filtered by kind and/or language.

Key parameters: path (string), kind (string, optional — e.g. function, class, method), language (string, optional), max_results (int, default 500), pagination (object)

Example:

{ "kind": "class", "max_results": 50 }

get_graph_stats

Return aggregate graph statistics: total nodes, total edges, total files, breakdown by symbol kind, and breakdown by language.

Key parameters: path (string)

Example:

{ "path": "." }

get_insights

Return codebase health indicators: language distribution, symbol kind distribution, cycle count, unused symbol count, duplicate group count, and cross-language edge count.

Key parameters: path (string)

Example:

{ "path": "." }

complexity_metrics

Return cyclomatic complexity and line counts for symbols, sorted by complexity.

Key parameters: path (string), target (string, optional — file path or symbol name), min_complexity (uint, default 1), sort_by_complexity (bool, default true), max_results (int, default 100)

Example:

{ "min_complexity": 10, "max_results": 20 }

Analysis

find_duplicates

Detect duplicate symbol bodies, signatures, or struct shapes by comparing hashes. Returns groups of symbols that share identical implementations.

Key parameters: path (string), duplicate_type (body/signature/struct, default body), threshold (int 0–100, default 80), exact (bool), max_results (int, default 100), max_members_per_group (int 0–10000, default 10; 0 = unlimited), pagination (object)

Each duplicate group is capped to 10 members by default; raise max_members_per_group or set it to 0 to disable the cap. Every group includes total_members (the full member count before truncation) and a members_truncated boolean indicating whether the cap elided any members.

Example:

{ "duplicate_type": "body", "max_results": 50 }

find_cycles

Detect cycles in call graphs, import graphs, or module graphs.

Key parameters: path (string), cycle_type (calls/imports/modules, default calls), min_depth (int ≥2, default 2), max_depth (int, optional unbounded), include_self_loops (bool), max_results (int, default 100), pagination (object)

Example:

{ "cycle_type": "imports", "include_self_loops": false }

find_unused

Detect dead code — symbols with no incoming references within the indexed workspace.

Key parameters: path (string), scope (public/private/function/struct/all, default all), language (string[]), symbol_kind (string[]), max_results (int, default 100), pagination (object)

Example:

{ "scope": "public", "max_results": 100 }

context_propagation

Detect Go context.Context propagation breaks: synchronous call sites that fail to thread context, goroutines that call context-accepting functions without context, and HTTP handlers that call context-accepting functions without r.Context().

Key parameters: path (string), scope (object, default { "kind": "global" }; file scope uses { "kind": "file", "path": "src/handler.go" }), mode (all/break_site/unthreaded_goroutine/http_handler_leak, default all), max_results (int, default 200)

Example:

{
  "path": ".",
  "scope": { "kind": "file", "path": "src/handler.go" },
  "mode": "http_handler_leak",
  "max_results": 50
}

is_node_in_cycle

Check whether a specific symbol participates in a cycle and optionally return the cycle path.

Key parameters: symbol (string, required), path (string), file_path (string, optional disambiguator), cycle_type (calls/imports/modules, default calls), min_depth (uint ≥1, default 2), max_depth (uint, optional unbounded), include_self_loops (bool)

Example:

{ "symbol": "OrderService", "cycle_type": "calls" }

Index & Diff

get_index_status

Return index metadata: file path, symbol count, edge count, last-built timestamp, and format version.

Key parameters: path (string)

Example:

{ "path": "." }

rebuild_index

Trigger a full rebuild of the unified graph index for the workspace.

Key parameters: path (string), force (bool, default true)

Example:

{ "path": ".", "force": true }

semantic_diff

Compare semantic changes between two git refs. Returns added, removed, modified, renamed, and signature-changed symbols — not raw text diffs. The base and target parameters are nested GitVersionRefParams objects with a ref (renamed from git_ref) field and an optional file_path.

Key parameters: base (object, required — ref, optional file_path), target (object, required — ref, optional file_path), path (string), include_unchanged (bool), filters (object — change_types[], symbol_kinds[]), max_results (int, default 500), page_token (string), page_size (int, default 100)

Example:

{
  "base": { "ref": "main" },
  "target": { "ref": "feature-branch" },
  "filters": { "change_types": ["added", "removed"] }
}

Natural Language

sqry_ask

Translate a natural language query into a sqry command. Responds with an execute, confirm, disambiguate, or reject result along with the translated command and confidence score.

Key parameters: query (string, required), path (string), execute (bool — when true, run the translated command and include results), model_dir (string, optional override of intent-classifier model directory), allow_unverified_model (bool), allow_model_download (bool)

Example:

{ "query": "find all public functions that return a Promise", "execute": true }

sqry_query

Run the structural query planner directly. Accepts the planner predicate-chain text syntax documented under query syntax (kind:, name:, path:, lang:, has:caller:, has:callee:, has:import:, has:export:), and returns matching nodes with file/line metadata.

Key parameters: query (string, required), path (string), limit (uint, optional — default 1000), budget_rows (uint, optional)

Example:

{ "query": "kind:function has:caller:main", "limit": 50 }

Workspace and Cache

workspace_status

Return the aggregate WorkspaceIndexStatus for the active logical workspace, including workspace identity, structure projection, and per-source-root health. Mirrors the data exposed by sqry workspace status and the LSP sqry/workspaceStatus request.

Key parameters: path (string), workspace_id (string, optional — 64-char hex BLAKE3 digest; echoed back for identity validation)

Example:

{ "path": "." }

expand_cache_status

Report Rust macro-expansion cache state: hit rate, cache directory, total cached entries, and last refresh timestamp. Useful when debugging stale MacroExpansion edges or planning a sqry cache expand --force run.

Key parameters: path (string)

Example:

{ "path": "." }
Edit this page on GitHub →