MCP tools (bxp-mcp)

Agent-callable tools exposed by the bxp-mcp stdio server.

Tool	Description
bxp_validate	Validate a bxp-cli config (JSON5). Returns annotated JSON with $err_/$warn/$info diagnostics inserted before each offending key.
bxp_validate_expr	Validate one bxp expression the way the GUI config editor does at authoring time: syntax, semantics, AND static lint findings the lenient runtime silently swallows (e.g. a literal SPLIT_PART index of 0 — 1-based, so 0 always yields "" — or a DATE_CONVERT format with an unbracketed non-vocab letter). Returns {ok:true} when the expression is sound, or {ok:false,error,detail,off,len} for the first finding (off/len pin the offending token span). Use this when AUTHORING a config to catch mistakes before a run; use bxp_eval to see what an expression COMPUTES against a row. Mirrors the GUI's bridge_eval_expr.
bxp_eval	Evaluate one bxp expression against an optional row context. Returns {ok,value} or {ok:false,error,detail,off,len}. This is the lenient runtime path (what a real bxp-cli run computes); for authoring-time validation that flags literal mistakes, use bxp_validate_expr.
bxp_eval_batch	Evaluate many bxp expressions against one row in a single call. Returns {results:[{ok,value}|{ok:false,error,detail,off,len}, ...]} aligned to the input order. A well-formed request always succeeds; per-expr failures are carried by each result's ok flag.
bxp_eval_trace	Evaluate one bxp expression with a per-call execution trace. Returns NDJSON (one JSON object per line): one {"fn","src_start","src_end","value"} line per function call as the engine evaluates inside-out, then a terminal line — {"t":"final","value":"..."} on success or {"t":"error","error","detail","off","len"} on failure. Use to debug HOW a complex expression computes its result, beyond bxp_eval's final value.
bxp_docs	Return the full bxp language/schema documentation as JSON (functions, keywords, operators, tokens, config_schema).
bxp_list_templates	List every conversion template declared in a bxp-cli config (JSON5). Returns {templates:[{id,data_dir,file_pattern_in,file_pattern_out,file_type_in,file_type_out,description}, ...]}; no semantic validation, so broken templates still appear with an error field.
bxp_fetch_template	Fetch one conversion template's raw JSON by id from a bxp-cli config (JSON5). Returns the template object, or {"$err_1":"..."} if the id is absent.
bxp_simulate	Run a full conversion end-to-end: stage the config (JSON5) + input CSV in a scratch workspace, run the chosen template through bxp-cli, and return the produced output, a record-count diff, bxp-cli's summary + diagnostics, and a per-row trace (BXTB sidecar): for each input row whether it was written, filtered (with reason: rule_skip / no_rule_match), or errored — each carrying the 1-based input-line number. Verifies a config for real (pre_pass/LOOKUP/row_rules) — what bxp_eval/bxp_validate cannot. CSV-input templates only. ok=true means the run happened; consult exit_code/status/diagnostics (0=ok, 2=warnings, 1=error).

How each tool is served

Every stateless tool is a direct in-process call into bxp-core/src/inspect.zig — the same core the GUI reaches through bxp-gui-bridge, which is why the third column mostly mirrors the second. bxp_simulate is the exception with no inspect entry: a full conversion is not a stateless op, so it spawns the co-located bxp-cli instead. A dash in the last column means the GUI has no equivalent call.

Tool	inspect call	bridge op
bxp_validate	annotateRaw(config, "<config>", 0)	bridge_inspect {config}
bxp_validate_expr	validateExprJson(expr)	bridge_eval_expr
bxp_eval	evalExpr(expr, headers?, fields?)	—
bxp_eval_batch	evalBatch(request)	bridge_inspect {eval_batch}
bxp_eval_trace	evalTrace(expr, ..., out)	bridge_eval_expr_trace
bxp_docs	docsJson()	bridge_inspect {docs}
bxp_list_templates	listTemplates(config)	bridge_inspect {list_templates}
bxp_fetch_template	fetchTemplate(config, id)	bridge_inspect {fetch_template}
bxp_simulate	—	—