query-code-migration.md

query_code migration

The seven former read-oriented MCP tools have been replaced by query_code. The current MCP inventory is query_code, ingest_project, ingest_files, get_graph_stats, and delete_repository. Calls to retired tool names receive an unknown-tool error. Update hard-coded callers to send an investigation goal, an absolute repo_path, and any known anchors to query_code.

Retired MCP tool	query_code goal and anchor
search_code	Describe the symbol or behavior to find; optionally set node_type.
graph_context	Ask to understand a symbol's context; pass node_ids or symbol_name when known.
get_related	Ask for relationships; pass node_ids or symbol_name.
list_symbols	Ask for an inventory and pass a symbol node_type.
inspect_file	Ask to inspect files and pass file_paths.
find_references	Ask for references and pass source_position, node_ids, or symbol_name.
regression_risk_report	Ask for change impact and pass changed file_paths.

For example, replace find_references(file_path="/repo/src/main.py", line=42) with query_code(goal="Find references to this symbol", repo_path="/repo", source_position={"file_path": "src/main.py", "line": 42}). The line remains zero-based. Paths in file_paths and source_position must stay within the repository. The default mode is balanced; fast and thorough are also available.

query_code returns one envelope with routing, compact evidence, ordered trace, complete, truncated, degraded_stages, and timings. Its evidence categories are symbols, files, relationships, references, and test_targets. Callers should read the selected playbook and completeness flags before relying on the evidence. The response is not a byte-for-byte replacement for any former tool's output.

The former tools' raw full-node search records, explicit query-angle controls, relationship filters and directions, inventory pagination, and raw file-edge lists are not query_code inputs. Callers needing those lower-level contracts can use the corresponding SCSWire service routes. Those routes remain available for orchestration, evaluation, and rollback; they are no longer model-facing MCP tools.

The optional external classifier receives the goal, anchors, and playbook choices, never source or retrieved evidence. Only eligible choices are offered: REFERENCES needs source_position, node_ids, or symbol_name, and IMPACT needs file_paths. A symbol mentioned in prose does not supply a structured anchor. The response still includes all seven probabilities; excluded choices are zero. A configured daemon requires model readiness before it reports ready. If the service becomes unavailable, SCS holds new queries during bounded recovery. An inference failure returns bounded discovery evidence with a degradation reason. Check routing.degraded_reason when routing matters. ingest_project, ingest_files, delete_repository, and get_graph_stats remain separate MCP operations.

Inspection and readiness

Use the default balanced mode for broad investigations. Use fast for a bounded first pass or known file/symbol anchors: it searches fewer seeds, hydrates fewer files, and skips reranking, so broad-goal recall can be lower.

Bounded file inspection prioritizes declarations before file containers and imports, then uses source order and stable ties. It retains the same node and edge limits. truncated=true with no degraded stage means useful evidence was capped; it does not mean the index needs rebuilding. Read the relevant source files and narrow the next query using returned file or symbol anchors.

Check get_graph_stats once at the start of an investigation. Check again after explicit ingestion or an availability failure, rather than before every query. After ingestion, pass its job ID as wait_job_id with a positive wait_timeout_seconds (at most ten seconds). Inspect the returned wait outcome and job status; if still running, respect retry_after_ms before waiting again. Existing indexes can remain readable during indexing, so ready alone does not prove that a requested ingestion job has finished.

Run just eval-query to compare query_code with versioned internal-route sequences on this repository. The default v3 suite adds natural-goal paraphrases and missing-anchor cases. Evaluation reports truncation separately from routing or execution degradation. The historical v2 fast, balanced, and thorough five-tool reports in evals/reports/ passed the routing, evidence, latency, call-count, and byte gates after wrapper removal.

The 2026-10-09 final v3 balanced report passed every gate on the local snapshot. Its fast report passed routing and latency gates but failed evidence recall and nDCG against the broader baseline. These results preserve the existing mode budgets and make that quality tradeoff visible.