AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
feat(mcp): add xerj_status, so an empty node is not read as a dead one (#2515)
snmsoodanf537d2be3d4d
diff --git a/AGENTS.md b/AGENTS.mdindex 8a297b041..2bdcf684c 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -171,10 +171,10 @@ do not inherit a shell `PATH`. Add `"XERJ_AUTH": "ApiKey <key>"` when the nodeis not running `--insecure` — the key is `<data-dir>/admin.key`. `--url` and`--auth` flags override the two environment variables.-Twenty-two tools: `xerj_search`, `xerj_semantic_search`, `xerj_vector_search`,+Twenty-three tools: `xerj_search`, `xerj_semantic_search`, `xerj_vector_search`,`xerj_hybrid_search`, `xerj_memory_store`, `xerj_memory_recall`,`xerj_brain_overview`, `xerj_brain_ego`, `xerj_brain_link`, `xerj_brain_unlink`,-`xerj_plan`, `xerj_map`, `xerj_code_search`, `xerj_index_budget`,+`xerj_plan`, `xerj_map`, `xerj_status`, `xerj_code_search`, `xerj_index_budget`,`xerj_autoindex_remove`, `xerj_field_report`, `xerj_corpus_feedback`,`xerj_hub_find`, `xerj_hub_def`, `xerj_hub_ask`, `xerj_def`, `xerj_batch_search`. The first eleven areeach a *thin proxy*: they build exactly the request the ES-compatible surface already acceptsdiff --git a/engine/crates/xerj-mcp/src/lib.rs b/engine/crates/xerj-mcp/src/lib.rsindex 638b882a4..dd096450b 100644--- a/engine/crates/xerj-mcp/src/lib.rs+++ b/engine/crates/xerj-mcp/src/lib.rs@@ -9,10 +9,10 @@//!//! It speaks the MCP **stdio transport**: newline-delimited//! JSON-RPC 2.0 messages on stdin/stdout. It exposes XERJ to any MCP-capable-//! agent host (Claude Desktop, IDE agents, custom orchestrators) as twenty-two-//! tools: nineteen without a hub key, and three Corpus Hub tools+//! agent host (Claude Desktop, IDE agents, custom orchestrators) as twenty-three+//! tools: twenty without a hub key, and three Corpus Hub tools//! (`xerj_hub_*`) that run the `xerj ask` flow itself. Thirteen of those-//! nineteen construct exactly the request the running engine already accepts+//! twenty construct exactly the request the running engine already accepts//! and forward it to a configurable base URL. `xerj_index_budget` counts a//! folder and returns the budget plans; it does not index. `xerj_autoindex_remove`//! deletes one autoindexed folder after listing what that folder owns, and only@@ -106,6 +106,7 @@ mod batch_cli;mod def;mod hub;mod map;+mod status;mod token_budget;pub use batch_cli::run_batch_cli;@@ -1406,6 +1407,25 @@ pub fn tool_specs_with(include_hub: bool) -> Value {"required": ["prefix"]}},+ {+ "name": "xerj_status",+ "description": concat!(+ "Is this node up, and what is on it? Answers the \"is it running\" ",+ "question in one call, without a search and without reading the ",+ "autoindex catalog: three GETs, a few lines of text. Reports the ",+ "Elasticsearch-compatible version the node claims, cluster health, ",+ "the index count and names, and whether `autoindex-catalog` exists. ",+ "Call this before concluding that a 404 from xerj_map or ",+ "xerj_search means the node is down: on a running but unindexed node ",+ "that 404 is the empty case, and this tool says so in words. Also ",+ "distinguishes a refused key (the node is up, the credentials are not ",+ "accepted) from nothing listening at all."+ ),+ "inputSchema": {+ "type": "object",+ "properties": {}+ }+ },{"name": "xerj_code_search","description": concat!(@@ -2093,6 +2113,9 @@ async fn call_tool(ctx: &Ctx, msg: &Value) -> Value {"xerj_map" => return map::run(ctx, &args).await,"xerj_index_budget" => return run_index_budget(ctx, &args).await,"xerj_autoindex_remove" => return run_autoindex_remove(ctx, &args).await,+ // #2515: liveness + what-is-indexed, so an empty node's 404 is not+ // mistaken for a node that is not there.+ "xerj_status" => return status::run(ctx, &args).await,"xerj_code_search" => return run_code_search(ctx, &args).await,// Corpus Hub v2 (plan §7): the `xerj ask` flow itself, not a proxy.hub_tool if hub_tool.starts_with("xerj_hub_") => {@@ -5962,7 +5985,7 @@ mod tests {.iter().map(|t| t["name"].as_str().unwrap()).collect();- assert_eq!(names.len(), 22);+ assert_eq!(names.len(), 23);for n in ["xerj_def","xerj_search",@@ -5979,6 +6002,8 @@ mod tests {"xerj_map","xerj_index_budget","xerj_autoindex_remove",+ // #2515: liveness and what-is-indexed, before any search tool.+ "xerj_status",// #977: reference-coding retrieval, served by the same pipeline// as `xerj code`."xerj_code_search",@@ -6108,23 +6133,23 @@ mod tests {.collect()};let without = names(false);- assert_eq!(without.len(), 19, "{without:?}");+ assert_eq!(without.len(), 20, "{without:?}");assert!(without.iter().all(|n| !n.starts_with("xerj_hub_")),"{without:?}");let with = names(true);- assert_eq!(with.len(), 22, "{with:?}");+ assert_eq!(with.len(), 23, "{with:?}");for n in ["xerj_hub_find", "xerj_hub_def", "xerj_hub_ask"] {assert!(with.iter().any(|name| name == n), "missing {n}");}let help = tools_paragraph(false);- assert!(help.contains("proxies 19 tools"), "{help}");+ assert!(help.contains("proxies 20 tools"), "{help}");assert!(!help.contains("xerj_hub_"), "{help}");assert!(help.contains("~/xerj-data"), "{help}");let help = tools_paragraph(true);- assert!(help.contains("proxies 22 tools"), "{help}");+ assert!(help.contains("proxies 23 tools"), "{help}");assert!(help.contains("xerj_hub_ask"), "{help}");assert!(help.contains("serves 3 Corpus Hub tools"), "{help}");}diff --git a/engine/crates/xerj-mcp/src/status.rs b/engine/crates/xerj-mcp/src/status.rsnew file mode 100644index 000000000..47de20f8b--- /dev/null+++ b/engine/crates/xerj-mcp/src/status.rs@@ -0,0 +1,402 @@+//! `xerj_status`: is this node up, and what is on it? (#2515)+//!+//! The field report that opened #2515 probed a node by calling `xerj_map`,+//! which answered 404 "no autoindex catalog". Read from an agent's side a 404+//! is hard to tell apart from a connection that never landed, so the reporter+//! fell back to `netstat` and a hand-written `GET /` to answer "is it running".+//!+//! This tool answers that question directly, and separates the states that+//! were previously one error: not reachable, reachable but refusing the+//! credentials, reachable and empty, reachable with data.+//!+//! It is deliberately cheap — three `GET`s, no search, no catalog read — so it+//! can be the first call of a session without spending the budget a real query+//! needs. The answer is a few lines of text.++use serde_json::Value;++use crate::map::CATALOG_INDEX;+use crate::{tool_text, transport_failure_text, Ctx};++/// Index rows printed before the rest are summarized as a count, so a node+/// with hundreds of indices still answers in a readable number of lines.+const MAX_LISTED_INDICES: usize = 20;++/// One `GET`, keeping the status even when it is an error: for a liveness+/// probe a 404 or a 401 is an answer, not a failure.+async fn get(ctx: &Ctx, path: &str) -> Result<(u16, String), (String, reqwest::Error)> {+ let url = format!("{}{}", ctx.base_url, path);+ let mut req = ctx.client.get(&url);+ if let Some(auth) = &ctx.auth {+ req = req.header("Authorization", auth);+ }+ match req.send().await {+ Ok(resp) => {+ let status = resp.status().as_u16();+ Ok((status, resp.text().await.unwrap_or_default()))+ }+ Err(e) => Err((url, e)),+ }+}++fn parse(text: &str) -> Option<Value> {+ serde_json::from_str(text).ok()+}++pub(crate) async fn run(ctx: &Ctx, _args: &Value) -> Value {+ let (status, banner_text) = match get(ctx, "/").await {+ Ok(ok) => ok,+ Err((url, e)) => {+ return tool_text(+ format!(+ "xerj_status: no node is answering at {}.\n{}",+ ctx.base_url,+ transport_failure_text(&ctx.base_url, &url, &e)+ ),+ true,+ );+ }+ };++ // A 401/403 answers the liveness question ("up") but nothing else will+ // work, so say that plainly instead of reporting an empty node.+ if status == 401 || status == 403 {+ return tool_text(+ format!(+ "xerj_status: the node at {} is UP but refused these credentials \+ (root endpoint answered HTTP {status}).\n\+ This is an auth problem, not a connection problem: queries will fail \+ the same way. Point XERJ_AUTH (or `xerj mcp --auth`) at a key this node \+ accepts, or ask its owner for the admin key.",+ ctx.base_url+ ),+ true,+ );+ }++ let banner = parse(&banner_text);+ let es_version = banner+ .as_ref()+ .and_then(|b| b.get("version"))+ .and_then(|v| v.get("number"))+ .and_then(Value::as_str);+ let cluster_name = banner+ .as_ref()+ .and_then(|b| b.get("cluster_name"))+ .and_then(Value::as_str);++ let mut lines = vec![format!(+ "xerj_status: the node at {} is UP (root endpoint answered HTTP {status}).",+ ctx.base_url+ )];+ match es_version {+ Some(v) => lines.push(format!(+ " version: {v} (the Elasticsearch-compatible number this node reports, \+ not XERJ's own version)"+ )),+ None => lines.push(+ " version: not reported — the root endpoint did not return a JSON banner".into(),+ ),+ }+ if let Some(name) = cluster_name {+ lines.push(format!(" cluster name: {name}"));+ }++ match get(ctx, "/_cluster/health").await {+ Ok((code, text)) => match parse(&text) {+ Some(h) if (200..300).contains(&code) => {+ let state = h.get("status").and_then(Value::as_str).unwrap_or("unknown");+ let nodes = h.get("number_of_nodes").and_then(Value::as_u64);+ let shards = h.get("active_shards").and_then(Value::as_u64);+ let mut facts = Vec::new();+ if let Some(n) = nodes {+ facts.push(format!("{n} node{}", if n == 1 { "" } else { "s" }));+ }+ if let Some(s) = shards {+ facts.push(format!("{s} active shards"));+ }+ lines.push(if facts.is_empty() {+ format!(" cluster health: {state}")+ } else {+ format!(" cluster health: {state} ({})", facts.join(", "))+ });+ }+ _ => lines.push(format!(+ " cluster health: unavailable (GET /_cluster/health answered HTTP {code})"+ )),+ },+ Err((url, e)) => lines.push(format!(+ " cluster health: unavailable ({})",+ transport_failure_text(&ctx.base_url, &url, &e)+ )),+ }++ let indices = match get(ctx, "/_cat/indices?format=json&h=index,docs.count").await {+ Ok((code, text)) if (200..300).contains(&code) => parse(&text)+ .and_then(|v| v.as_array().cloned())+ .map(|rows| {+ rows.iter()+ .filter_map(|r| {+ let name = r.get("index").and_then(Value::as_str)?;+ let docs = r.get("docs.count").and_then(|d| {+ d.as_str()+ .and_then(|s| s.parse::<u64>().ok())+ .or_else(|| d.as_u64())+ });+ Some((name.to_string(), docs))+ })+ .collect::<Vec<_>>()+ }),+ _ => None,+ };++ match &indices {+ Some(rows) if rows.is_empty() => {+ lines.push(" indices: none".into());+ }+ Some(rows) => {+ lines.push(format!(+ " indices: {}{}",+ rows.len(),+ if rows.len() > MAX_LISTED_INDICES {+ format!(" (first {MAX_LISTED_INDICES} listed)")+ } else {+ String::new()+ }+ ));+ let width = rows+ .iter()+ .take(MAX_LISTED_INDICES)+ .map(|(n, _)| n.len())+ .max()+ .unwrap_or(0);+ for (name, docs) in rows.iter().take(MAX_LISTED_INDICES) {+ match docs {+ Some(d) => lines.push(format!(" {name:<width$} {d} docs")),+ None => lines.push(format!(" {name}")),+ }+ }+ }+ None => lines+ .push(" indices: unavailable (GET /_cat/indices did not return a JSON list)".into()),+ }++ // The point of the whole tool: an empty node must not read as a broken+ // one. `xerj_map` answers 404 "no autoindex catalog" here, and that is+ // the node saying it has nothing indexed — not a connectivity failure.+ match &indices {+ Some(rows) => {+ let catalog = rows.iter().find(|(name, _)| name == CATALOG_INDEX);+ match catalog {+ Some((_, docs)) => lines.push(format!(+ " autoindex catalog: PRESENT (`{CATALOG_INDEX}`{}, so xerj_map and \+ xerj_search have data to read).",+ match docs {+ Some(d) => format!(" holds {d} docs"),+ None => String::new(),+ }+ )),+ None => {+ lines.push(+ " autoindex catalog: ABSENT — this node is running and has nothing \+ indexed yet."+ .into(),+ );+ lines.push(+ " xerj_map and xerj_search answer \"no autoindex catalog\" on this \+ node. That is an empty node, not a connection failure: index a folder \+ with `xerj autoindex <folder>`, then call this tool again."+ .into(),+ );+ }+ }+ }+ None => lines.push(format!(+ " autoindex catalog: unknown — the index list could not be read, so whether \+ `{CATALOG_INDEX}` exists is not answered here."+ )),+ }++ tool_text(lines.join("\n"), false)+}++#[cfg(test)]+mod tests {+ use super::*;+ use serde_json::json;+ use std::collections::HashMap;++ /// Serve a fixed route table on a loopback port. Keys are paths without+ /// their query string, because the real calls carry `?format=json&...`.+ async fn serve(routes: HashMap<&'static str, (u16, String)>) -> String {+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();+ let addr = listener.local_addr().unwrap();+ tokio::spawn(async move {+ loop {+ let Ok((mut sock, _)) = listener.accept().await else {+ return;+ };+ let mut buf = vec![0u8; 8192];+ let n = tokio::io::AsyncReadExt::read(&mut sock, &mut buf)+ .await+ .unwrap_or(0);+ let request = String::from_utf8_lossy(&buf[..n]).to_string();+ let target = request.split_whitespace().nth(1).unwrap_or("/");+ let path = target.split('?').next().unwrap_or("/").to_string();+ let (status, body) = routes+ .get(path.as_str())+ .cloned()+ .unwrap_or((404, "{}".to_string()));+ let reply = format!(+ "HTTP/1.1 {status} X\r\nContent-Length: {}\r\nConnection: close\r\n\+ Content-Type: application/json\r\n\r\n{body}",+ body.len()+ );+ let _ = tokio::io::AsyncWriteExt::write_all(&mut sock, reply.as_bytes()).await;+ }+ });+ format!("http://{addr}")+ }++ fn ctx(base_url: String) -> Ctx {+ Ctx {+ client: reqwest::Client::new(),+ base_url,+ auth: None,+ }+ }++ fn banner() -> String {+ json!({+ "name": "node-1",+ "cluster_name": "xerj",+ "version": { "number": "8.13.0", "distribution": "xerj" },+ "tagline": "You Know, for Search"+ })+ .to_string()+ }++ fn health(state: &str) -> String {+ json!({+ "cluster_name": "xerj",+ "status": state,+ "number_of_nodes": 1,+ "active_shards": 15+ })+ .to_string()+ }++ fn cat(rows: Value) -> String {+ rows.to_string()+ }++ fn text(v: &Value) -> String {+ v["content"][0]["text"]+ .as_str()+ .unwrap_or_default()+ .to_string()+ }++ /// The bug in #2515: `xerj_map` 404s on an unindexed node, and from the+ /// agent's side that reads like the node is not there. The status tool has+ /// to say UP and EMPTY in one answer, and name the 404 as the empty case.+ #[tokio::test]+ async fn an_unindexed_node_reports_up_and_empty_not_unreachable() {+ let mut routes = HashMap::new();+ routes.insert("/", (200, banner()));+ routes.insert("/_cluster/health", (200, health("green")));+ routes.insert("/_cat/indices", (200, cat(json!([]))));+ let base = serve(routes).await;++ let out = run(&ctx(base), &json!({})).await;+ assert_eq!(out["isError"], false, "{}", text(&out));+ let body = text(&out);+ assert!(body.contains("is UP"), "{body}");+ assert!(body.contains("indices: none"), "{body}");+ assert!(body.contains("autoindex catalog: ABSENT"), "{body}");+ assert!(+ body.contains("not a connection failure"),+ "the empty node must not read as a broken one: {body}"+ );+ assert!(body.contains("xerj autoindex <folder>"), "{body}");+ assert!(body.contains("8.13.0"), "{body}");+ assert!(body.contains("green"), "{body}");+ }++ #[tokio::test]+ async fn an_indexed_node_names_the_catalog_and_its_doc_count() {+ let mut routes = HashMap::new();+ routes.insert("/", (200, banner()));+ routes.insert("/_cluster/health", (200, health("yellow")));+ routes.insert(+ "/_cat/indices",+ (+ 200,+ cat(json!([+ { "index": "autoindex-catalog", "docs.count": "12" },+ { "index": "ax", "docs.count": "812" }+ ])),+ ),+ );+ let base = serve(routes).await;++ let out = run(&ctx(base), &json!({})).await;+ assert_eq!(out["isError"], false, "{}", text(&out));+ let body = text(&out);+ assert!(body.contains("indices: 2"), "{body}");+ assert!(body.contains("autoindex-catalog"), "{body}");+ assert!(body.contains("12 docs"), "{body}");+ assert!(body.contains("autoindex catalog: PRESENT"), "{body}");+ assert!(!body.contains("ABSENT"), "{body}");+ assert!(body.contains("yellow"), "{body}");+ }++ /// Nothing listening: the one case that *is* a connectivity failure, and it+ /// has to say so rather than printing an empty successful answer.+ #[tokio::test]+ async fn nothing_listening_is_the_only_unreachable_answer() {+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();+ let addr = listener.local_addr().unwrap();+ drop(listener);++ let out = run(&ctx(format!("http://{addr}")), &json!({})).await;+ assert_eq!(out["isError"], true, "{}", text(&out));+ let body = text(&out);+ assert!(body.contains("no node is answering"), "{body}");+ }++ /// A 401 means the node is running. Reporting that as "unreachable" would+ /// send an agent looking at ports when the problem is the key.+ #[tokio::test]+ async fn a_refused_key_is_up_with_an_auth_problem_not_down() {+ let mut routes = HashMap::new();+ routes.insert("/", (401, "{\"error\":\"unauthorized\"}".to_string()));+ let base = serve(routes).await;++ let out = run(&ctx(base), &json!({})).await;+ let body = text(&out);+ assert!(body.contains("is UP but refused"), "{body}");+ assert!(+ body.contains("auth problem, not a connection problem"),+ "{body}"+ );+ assert!(body.contains("XERJ_AUTH"), "{body}");+ }++ /// A node that answers the banner but not `_cat/indices` is up. The catalog+ /// question is then unknown, which must not be reported as absent.+ #[tokio::test]+ async fn an_unreadable_index_list_is_unknown_not_absent() {+ let mut routes = HashMap::new();+ routes.insert("/", (200, banner()));+ routes.insert("/_cluster/health", (200, health("green")));+ routes.insert("/_cat/indices", (500, "boom".to_string()));+ let base = serve(routes).await;++ let out = run(&ctx(base), &json!({})).await;+ assert_eq!(out["isError"], false, "{}", text(&out));+ let body = text(&out);+ assert!(body.contains("autoindex catalog: unknown"), "{body}");+ assert!(!body.contains("ABSENT"), "{body}");+ }+}diff --git a/engine/crates/xerj-server/src/main.rs b/engine/crates/xerj-server/src/main.rsindex 1553adabd..baf70071d 100644--- a/engine/crates/xerj-server/src/main.rs+++ b/engine/crates/xerj-server/src/main.rs@@ -3679,13 +3679,13 @@ mod decide_flag_tests {#[test]fn help_counts_the_mcp_tools_actually_served() {// The count is `tool_specs()`, the same list `tools/list` returns:- // nineteen without a hub key, twenty-two with the three hub tools.+ // twenty without a hub key, twenty-three with the three hub tools.let served = super::mcp_tool_count();if xerj_common::hub::hub_key_configured() {- assert_eq!(served, 22, "tool_specs() with a hub key: {served}");+ assert_eq!(served, 23, "tool_specs() with a hub key: {served}");} else {assert_eq!(- served, 19,+ served, 20,"a no-key process must not count the hub tools it does not serve");}diff --git a/landing/docs/agents/schemas/mcp-tools.json b/landing/docs/agents/schemas/mcp-tools.jsonindex 8d3ad02c5..efc5f96ed 100644--- a/landing/docs/agents/schemas/mcp-tools.json+++ b/landing/docs/agents/schemas/mcp-tools.json@@ -731,6 +731,14 @@]}},+ {+ "name": "xerj_status",+ "description": "Is this node up, and what is on it? Answers the \"is it running\" question in one call, without a search and without reading the autoindex catalog: three GETs, a few lines of text. Reports the Elasticsearch-compatible version the node claims, cluster health, the index count and names, and whether `autoindex-catalog` exists. Call this before concluding that a 404 from xerj_map or xerj_search means the node is down: on a running but unindexed node that 404 is the empty case, and this tool says so in words. Also distinguishes a refused key (the node is up, the credentials are not accepted) from nothing listening at all.",+ "inputSchema": {+ "type": "object",+ "properties": {}+ }+ },{"name": "xerj_code_search","description": "Reference-coding retrieval over a corpus of peer projects: how did real codebases solve this problem? Returns the matching definition (not a byte window), the file:line to cite, and per-hit licence warnings — AGPL/SSPL/Elastic/BUSL/GPL/LGPL/MPL sources are approach-only. A corpus marked own (`xerj corpus add --own`, or `xerj corpus own <name>`) is the caller's own first-party code: an unidentified licence (UNKNOWN or NONE-FOUND) stays in the hit header and the do-not-copy banner is omitted for that unidentified licence only. A detected copyleft or source-available licence still warns. Hub pack licence classes are unchanged. Refuses indices older than 30 days (override with stale_ok). A no-match is NOT an error: it says the corpus is wrong for the task. A line `weak match: the corpus may not cover this` means the passages are nearest neighbours, not coverage — fall back to grep or another corpus. Pass `max_tokens` to cap the response at a token budget (never exceeded; see that argument for the tokenizer and the locator-only rule). Corpora: `xerj corpus list`.",diff --git a/landing/docs/cli.html b/landing/docs/cli.htmlindex e91fe7473..69a334f0b 100644--- a/landing/docs/cli.html+++ b/landing/docs/cli.html@@ -530,13 +530,13 @@ Grok CLI | ~/.grok/config.toml or .grok/config.toml<p>Aider is absent because it has no MCP client support, T3 Code hosts an MCP endpoint rather than consuming one, and Grok Bot has no documented local stdio registration.</p>- <p>Twenty-two tools are served (nineteen in a build with no hub key, which omits the three hub tools). Eleven are thin proxies over an endpoint the engine already exposes, and engine errors come back verbatim: <code class="inline">xerj_search</code>, <code class="inline">xerj_semantic_search</code>, <code class="inline">xerj_vector_search</code>, <code class="inline">xerj_hybrid_search</code>, <code class="inline">xerj_memory_store</code>, <code class="inline">xerj_memory_recall</code>, <code class="inline">xerj_brain_overview</code>, <code class="inline">xerj_brain_ego</code>, <code class="inline">xerj_brain_link</code>, <code class="inline">xerj_brain_unlink</code>, <code class="inline">xerj_plan</code> (<code class="inline">POST /_ask</code>). Two are not plain proxies: <code class="inline">xerj_map</code> returns the autoindex catalog's per-index field map (trimmed to a byte cap), and <code class="inline">xerj_code_search</code> runs the <code class="inline">xerj code</code> pipeline and returns its rendered text. <code class="inline">xerj_field_report</code> files an agent field report (a GitHub PR first, the <code class="inline">/api/field-report</code> endpoint when GitHub is unavailable; it sends by default). <code class="inline">xerj_index_budget</code> counts a folder and estimates its index against the node's disk budget before <code class="inline">xerj autoindex</code> hashes anything (it does not index), <code class="inline">xerj_autoindex_remove</code> drops one autoindexed folder after listing it and deletes nothing unless <code class="inline">confirm</code> is true, and <code class="inline">xerj_corpus_feedback</code> rates a hub corpus. <code class="inline">xerj_def</code> (below) finds local definitions, and <code class="inline">xerj_batch_search</code> runs 1 to 50 IDs or questions in one call, in input order, through the same adapter as <code class="inline">xerj batch-search</code>. The three Corpus Hub tools, <code class="inline">xerj_hub_ask</code>, <code class="inline">xerj_hub_def</code> and <code class="inline">xerj_hub_find</code>, run the <a href="#ask"><code class="inline">xerj ask</code></a> flow, but never download a pack and never fetch the catalogue: run <code class="inline">xerj hub sync</code> and <code class="inline">xerj hub pull <slug></code> in a shell first (details on the <a href="/docs/corpus-hub#mcp">Corpus Hub page</a>). Two caveats the tool descriptions carry themselves: <code class="inline">xerj_semantic_search</code> embeds server-side with the <em>lexical</em> feature-hashing embedder unless the node runs <code class="inline">--embed-mode neural</code>, and the <code class="inline">xerj_brain_*</code> tools work a deterministic link index, not a graph database.</p>+ <p>Twenty-three tools are served (twenty in a build with no hub key, which omits the three hub tools). Eleven are thin proxies over an endpoint the engine already exposes, and engine errors come back verbatim: <code class="inline">xerj_search</code>, <code class="inline">xerj_semantic_search</code>, <code class="inline">xerj_vector_search</code>, <code class="inline">xerj_hybrid_search</code>, <code class="inline">xerj_memory_store</code>, <code class="inline">xerj_memory_recall</code>, <code class="inline">xerj_brain_overview</code>, <code class="inline">xerj_brain_ego</code>, <code class="inline">xerj_brain_link</code>, <code class="inline">xerj_brain_unlink</code>, <code class="inline">xerj_plan</code> (<code class="inline">POST /_ask</code>). Two are not plain proxies: <code class="inline">xerj_map</code> returns the autoindex catalog's per-index field map (trimmed to a byte cap), and <code class="inline">xerj_code_search</code> runs the <code class="inline">xerj code</code> pipeline and returns its rendered text. <code class="inline">xerj_field_report</code> files an agent field report (a GitHub PR first, the <code class="inline">/api/field-report</code> endpoint when GitHub is unavailable; it sends by default). <code class="inline">xerj_index_budget</code> counts a folder and estimates its index against the node's disk budget before <code class="inline">xerj autoindex</code> hashes anything (it does not index), <code class="inline">xerj_autoindex_remove</code> drops one autoindexed folder after listing it and deletes nothing unless <code class="inline">confirm</code> is true, <code class="inline">xerj_status</code> answers "is this node up, and is anything indexed" with three GETs so an empty node's 404 is not mistaken for a node that is not there, and <code class="inline">xerj_corpus_feedback</code> rates a hub corpus. <code class="inline">xerj_def</code> (below) finds local definitions, and <code class="inline">xerj_batch_search</code> runs 1 to 50 IDs or questions in one call, in input order, through the same adapter as <code class="inline">xerj batch-search</code>. The three Corpus Hub tools, <code class="inline">xerj_hub_ask</code>, <code class="inline">xerj_hub_def</code> and <code class="inline">xerj_hub_find</code>, run the <a href="#ask"><code class="inline">xerj ask</code></a> flow, but never download a pack and never fetch the catalogue: run <code class="inline">xerj hub sync</code> and <code class="inline">xerj hub pull <slug></code> in a shell first (details on the <a href="/docs/corpus-hub#mcp">Corpus Hub page</a>). Two caveats the tool descriptions carry themselves: <code class="inline">xerj_semantic_search</code> embeds server-side with the <em>lexical</em> feature-hashing embedder unless the node runs <code class="inline">--embed-mode neural</code>, and the <code class="inline">xerj_brain_*</code> tools work a deterministic link index, not a graph database.</p><p><code class="inline">xerj_def</code> finds local definitions with the query, lexical ranking and location deduplication of <code class="inline">xerj def --json</code>. For example, <code class="inline">{"symbol":"Cache","prefix":"project","kind":"struct","lang":"rust","k":5}</code> searches <code class="inline">project-*</code>. Use <code class="inline">index</code> instead of <code class="inline">prefix</code> for an explicit index; non-empty scope arguments cannot be combined, and with neither it searches <code class="inline">ax-*</code>. <code class="inline">symbol</code> also accepts capability phrases. <code class="inline">k</code> is 1–50 (default 5); optional <code class="inline">max_tokens</code> caps the response. Declarations are in <code class="inline">hits.hits[]._source.code</code>, locations in <code class="inline">ax_path</code>/<code class="inline">path</code> and <code class="inline">line</code>/<code class="inline">start_line</code>; older file hits may use <code class="inline">fields._passage</code>. <code class="inline">hits.total</code> counts engine matches before deduplication; no match is a successful empty hit list. As in the CLI, kind/language filters are ignored when no target index maps the field or any maps it as numeric. This queries the configured node; <code class="inline">xerj_hub_def</code> instead searches a named Hub pack.</p><p><code class="inline">xerj_search</code> hits carry <code class="inline">match_line</code> and capped <code class="inline">match_lines</code> when a query term can be located in the passage: the absolute 1-based source line of the best-scoring match (a tie takes the earliest line). Cite <code class="inline">path:match_line</code>. Both fields are omitted when no term is in the passage or the passage start line is unknown. <code class="inline">start_line</code> remains the passage start.</p>- <p>Machine-readable schemas for all twenty-two: <a href="/docs/agents/schemas/mcp-tools.json">/docs/agents/schemas/mcp-tools.json</a>, generated from a live <code class="inline">tools/list</code> and gated against the binary in CI.</p>+ <p>Machine-readable schemas for all twenty-three: <a href="/docs/agents/schemas/mcp-tools.json">/docs/agents/schemas/mcp-tools.json</a>, generated from a live <code class="inline">tools/list</code> and gated against the binary in CI.</p><p class="source-note">Source · engine/crates/xerj-server/src/main.rs · engine/crates/xerj-mcp/src/lib.rs</p>