1-mcp-resolver
Resolve symbol definitions, types, and cross-file references via Serena MCP before source analysis begins.
Input
You receive these values from the orchestrator:
| Parameter | Description |
|---|---|
workdir | Run working directory (e.g. /tmp/zeroize-audit-{run_id}/) |
repo_root | Repository root path |
compile_db | Path to compile_commands.json |
config_path | Path to merged config file ({workdir}/merged-config.yaml) |
input_file | Path to {workdir}/agent-inputs/mcp-resolver.json containing sensitive_candidates |
mcp_timeout_ms | Timeout budget for all MCP queries |
Process
Step 0 — Load Configuration and Inputs
Read config_path to load the merged config (sensitive patterns, approved wipes). Read input_file to load sensitive_candidates (JSON array of {name, file, line}).
Step 1 — Activate Project
Call activate_project with repo_root. This must succeed before any other Serena tool.
Tool: activate_project
Arguments:
project: "<repo_root>"
If activation fails, write status.json with "status": "failed" and stop.
Step 2 — Resolve Symbols
For each candidate in sensitive_candidates:
- Resolve definition and type:
find_symbolwithsymbol_nameandinclude_body: true. Record file, line, kind, type info, array sizes, and struct layout. - Collect use sites:
find_referencing_symbolswithsymbol_name. Record all cross-file references. - Trace wipe wrappers: For any detected wipe function, use
find_referencing_symbolsto find callers. Read function bodies viafind_symbolwithinclude_body: trueand resolve called symbols. - Survey unfamiliar TUs: Use
get_symbols_overviewwhen needed.
Respect mcp_timeout_ms — if the budget is exhausted, stop querying and write partial results.
Step 3 — Build Reference Graph
From the collected results, build:
- A symbol-keyed map of definitions with resolved types
- A cross-file reference graph (caller -> callee relationships)
- Wipe wrapper chains (function A calls B which calls explicit_bzero)
Step 4 — Normalize Evidence
Pipe all raw MCP output through the normalizer:
python {baseDir}/tools/mcp/normalize_mcp_evidence.py \
--input <raw_results> \
--output <workdir>/mcp-evidence/symbols.json
For Serena tool parameters, query patterns, and empty-response troubleshooting, see {baseDir}/references/mcp-analysis.md.
Output
Write all output files to {workdir}/mcp-evidence/:
| File | Content |
|---|---|
status.json | `{"status": "success |
symbols.json | Normalized symbol definitions keyed by name: {name, file, line, kind, type, body, array_size, struct_fields} |
references.json | Cross-file reference graph: {symbol: [{file, line, kind, referencing_symbol}]} |
notes.md | Human-readable observations, unresolved symbols, and relative paths to JSON files |
Error Handling
- Activation failure: Write
status.jsonwith"status": "failed", exit. The orchestrator will setmcp_available=false. - Timeout: Write partial results. Set
status.jsonto"status": "partial"with the count of resolved vs. total candidates. - Individual query failure: Log the error, skip the symbol, continue with others. Record skipped symbols in
status.json.errors. - Always write
status.json— even on total failure, so downstream agents can check MCP availability.
Cross-Reference Convention
This agent does not assign finding IDs. It produces evidence consumed by 2-source-analyzer and 3-tu-compiler-analyzer. Evidence files use relative paths from {workdir} (e.g., mcp-evidence/symbols.json).