Skip to content

armgit / xerj

Public Imported from GitHub
0

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.

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.md
index 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 node
is 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 are
each a *thin proxy*: they build exactly the request the ES-compatible surface already accepts
diff --git a/engine/crates/xerj-mcp/src/lib.rs b/engine/crates/xerj-mcp/src/lib.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.json
index 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.html
index 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 &lt;slug&gt;</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 &lt;slug&gt;</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>