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.

fix(mcp): tell agents how to start a node when XERJ_URL is down (#2085)

xerj-org44b8d653f44b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b994f919..b48cef3a7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
+- An MCP tool call that cannot connect to `XERJ_URL` now says that no XERJ
+ node is listening there, that `xerj mcp` does not start one, and prints
+ `xerj --insecure --data-dir ~/xerj-data`. A bare connection error was the
+ whole tool result, so agents abandoned xerj for the session. HTTP
+ responses, including 401, are unchanged (#2079).
+
- `xerj autoindex` on the graph path no longer counts files that appeared
after the resume plan was frozen as junk. A resume whose plan predates
files now on disk still cannot re-cluster that plan — dataset identity and
diff --git a/engine/crates/xerj-mcp/src/lib.rs b/engine/crates/xerj-mcp/src/lib.rs
index d0f6220d6..988998d20 100644
--- a/engine/crates/xerj-mcp/src/lib.rs
+++ b/engine/crates/xerj-mcp/src/lib.rs
@@ -113,6 +113,11 @@ const DEFAULT_PROTOCOL_VERSION: &str = "2025-06-18";
/// Default XERJ ES-compatible endpoint.
const DEFAULT_XERJ_URL: &str = "http://localhost:9200";
+/// How to start the node `xerj mcp` proxies to. The flags are the local-dev
+/// start in llms.txt ("Start here", step 1), the README, and the `xerj mcp`
+/// CLI reference. `xerj mcp` does not start a node itself.
+const START_LOCAL_NODE: &str = "xerj --insecure --data-dir ~/xerj-data";
+
/// Shared per-process state: the HTTP client + where to proxy to.
/// The MCP client's `clientInfo` (name, version) from `initialize`: the agent
/// family on reviews this server sends. The tool's name only, nothing personal.
@@ -2637,6 +2642,84 @@ async fn fetch_mapping(ctx: &Ctx, index: &str) -> Option<Value> {
resp.json::<Value>().await.ok()
}
+/// Tool text for a proxy request that never got an HTTP response.
+///
+/// A connect failure means nothing accepted a connection at `XERJ_URL`
+/// (#2079). The raw client error does not say so, and agents then drop xerj
+/// for the session. HTTP statuses never reach here: a 401 is a response and
+/// stays `XERJ returned HTTP 401: …`.
+pub(crate) fn transport_failure_text(
+ base_url: &str,
+ request_url: &str,
+ err: &reqwest::Error,
+) -> String {
+ if node_unreachable(err) {
+ node_not_listening(base_url, &error_detail(err))
+ } else {
+ format!("request to {request_url} failed: {err}")
+ }
+}
+
+/// `true` when the failure is "nothing is listening / the host cannot be
+/// reached", not a timeout, a TLS failure after connect, or a builder error.
+fn node_unreachable(err: &reqwest::Error) -> bool {
+ if err.is_connect() {
+ return true;
+ }
+ let mut source = std::error::Error::source(err);
+ while let Some(cur) = source {
+ if let Some(io) = cur.downcast_ref::<std::io::Error>() {
+ return matches!(
+ io.kind(),
+ std::io::ErrorKind::ConnectionRefused
+ | std::io::ErrorKind::HostUnreachable
+ | std::io::ErrorKind::NetworkUnreachable
+ | std::io::ErrorKind::AddrNotAvailable
+ );
+ }
+ let text = cur.to_string().to_ascii_lowercase();
+ if text.contains("connection refused")
+ || text.contains("network is unreachable")
+ || text.contains("host is unreachable")
+ || text.contains("no route to host")
+ || text.contains("failed to lookup address")
+ || text.contains("name or service not known")
+ || text.contains("nodename nor servname")
+ {
+ return true;
+ }
+ source = cur.source();
+ }
+ false
+}
+
+/// The sentence an agent can act on. `err` is the client detail, kept so the
+/// refusal is still diagnosable.
+fn node_not_listening(base_url: &str, err: &dyn std::fmt::Display) -> String {
+ let base = base_url.trim_end_matches('/');
+ format!(
+ "no XERJ node is listening at {base}. xerj mcp does not start a node. \
+ Start one with:\n {START_LOCAL_NODE}\n\
+ then retry this tool. ({err})"
+ )
+}
+
+/// reqwest's `Display` often stops at "error sending request"; the OS reason
+/// (`Connection refused`) is on the source chain.
+fn error_detail(err: &reqwest::Error) -> String {
+ let mut out = err.to_string();
+ let mut source = std::error::Error::source(err);
+ while let Some(cur) = source {
+ let next = cur.to_string();
+ if !out.contains(&next) {
+ out.push_str(": ");
+ out.push_str(&next);
+ }
+ source = cur.source();
+ }
+ out
+}
+
async fn engine_request(
ctx: &Ctx,
method: Method,
@@ -2672,7 +2755,7 @@ async fn engine_request(
tool_text(format!("XERJ returned HTTP {status}: {text}"), true)
}
}
- Err(e) => tool_text(format!("request to {url} failed: {e}"), true),
+ Err(e) => tool_text(transport_failure_text(&ctx.base_url, &url, &e), true),
}
}
@@ -2689,6 +2772,114 @@ mod tests {
(m, p, b.expect("builder should carry a body"))
}
+ /// #2079: the sentence itself, with no network. The connect-vs-HTTP split
+ /// is covered by the tests below.
+ #[test]
+ fn node_not_listening_names_the_url_and_the_documented_start_command() {
+ let msg = node_not_listening(
+ "http://localhost:9200/",
+ &"tcp connect error: Connection refused (os error 111)",
+ );
+ assert!(
+ msg.contains("no XERJ node is listening at http://localhost:9200. xerj mcp"),
+ "{msg}"
+ );
+ assert!(msg.contains("xerj mcp does not start a node"), "{msg}");
+ assert!(
+ msg.contains("\n xerj --insecure --data-dir ~/xerj-data\n"),
+ "{msg}"
+ );
+ assert!(msg.contains("Connection refused (os error 111)"), "{msg}");
+ assert!(!msg.contains("HTTP "), "{msg}");
+ assert!(!msg.contains("-d "), "do not invent a short flag: {msg}");
+ }
+
+ /// The path an agent actually hits: `xerj_search` against a closed port.
+ #[tokio::test]
+ async fn a_refused_connection_on_xerj_search_tells_the_agent_to_start_the_node() {
+ let ctx = Ctx {
+ client: reqwest::Client::new(),
+ base_url: "http://127.0.0.1:1".to_string(),
+ auth: None,
+ };
+ let msg = json!({
+ "params": { "name": "xerj_search", "arguments": { "index": "docs" } }
+ });
+ let res = call_tool(&ctx, &msg).await;
+ assert_eq!(res["isError"], true, "{res}");
+ let text = res["content"][0]["text"].as_str().unwrap();
+ assert!(
+ text.contains("no XERJ node is listening at http://127.0.0.1:1"),
+ "{text}"
+ );
+ assert!(
+ text.contains("xerj --insecure --data-dir ~/xerj-data"),
+ "{text}"
+ );
+ assert!(text.contains("xerj mcp does not start a node"), "{text}");
+ assert!(
+ !text.contains("XERJ returned HTTP"),
+ "a connect failure is not an HTTP status: {text}"
+ );
+ }
+
+ /// A request that never becomes a connect attempt keeps the old text.
+ /// Builder failures are not "no node".
+ #[tokio::test]
+ async fn a_non_connect_transport_error_keeps_the_request_failed_text() {
+ let ctx = Ctx {
+ client: reqwest::Client::new(),
+ base_url: "not a url".to_string(),
+ auth: None,
+ };
+ let msg = json!({
+ "params": { "name": "xerj_search", "arguments": { "index": "docs" } }
+ });
+ let res = call_tool(&ctx, &msg).await;
+ assert_eq!(res["isError"], true, "{res}");
+ let text = res["content"][0]["text"].as_str().unwrap();
+ assert!(
+ text.starts_with("request to not a url/docs/_search failed:"),
+ "{text}"
+ );
+ assert!(!text.contains("no XERJ node is listening"), "{text}");
+ assert!(!text.contains("xerj --insecure"), "{text}");
+ }
+
+ /// 401 is a response from a node that is up. It must not grow a start recipe.
+ #[tokio::test]
+ async fn an_http_401_is_not_rewritten_as_node_down() {
+ use tokio::io::{AsyncReadExt, AsyncWriteExt};
+
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let addr = listener.local_addr().unwrap();
+ tokio::spawn(async move {
+ let (mut sock, _) = listener.accept().await.unwrap();
+ let mut buf = vec![0u8; 2048];
+ let _ = sock.read(&mut buf).await;
+ let resp = b"HTTP/1.1 401 Unauthorized\r\nContent-Length: 13\r\nConnection: close\r\n\r\nunauthorized\n";
+ let _ = sock.write_all(resp).await;
+ });
+ let ctx = Ctx {
+ client: reqwest::Client::new(),
+ base_url: format!("http://{addr}"),
+ auth: None,
+ };
+ let msg = json!({
+ "params": { "name": "xerj_search", "arguments": { "index": "docs" } }
+ });
+ let res = call_tool(&ctx, &msg).await;
+ assert_eq!(res["isError"], true, "{res}");
+ let text = res["content"][0]["text"].as_str().unwrap();
+ assert!(
+ text.contains("XERJ returned HTTP 401 Unauthorized"),
+ "{text}"
+ );
+ assert!(text.contains("unauthorized"), "{text}");
+ assert!(!text.contains("no XERJ node is listening"), "{text}");
+ assert!(!text.contains("xerj --insecure"), "{text}");
+ }
+
#[test]
fn required_string_errors_say_what_to_pass_next() {
let err = build_semantic(&json!({})).unwrap_err();
diff --git a/engine/crates/xerj-mcp/src/map.rs b/engine/crates/xerj-mcp/src/map.rs
index 6f570bb73..770f923c5 100644
--- a/engine/crates/xerj-mcp/src/map.rs
+++ b/engine/crates/xerj-mcp/src/map.rs
@@ -543,7 +543,7 @@ pub(crate) async fn run(ctx: &Ctx, args: &Value) -> Value {
)
}
}
- Err(e) => tool_text(format!("request to {url} failed: {e}"), true),
+ Err(e) => tool_text(crate::transport_failure_text(&ctx.base_url, &url, &e), true),
}
}
@@ -969,9 +969,10 @@ mod tests {
}
}
- /// Transport failure reaches the agent as isError with the URL named —
- /// the same honesty as every other proxied tool. A silently empty map
- /// here would be the worst failure mode: it reads as "no data".
+ /// Transport failure reaches the agent as isError, not as an empty map.
+ /// A silently empty map would be the worst failure mode: it reads as
+ /// "no data". Connection refused names the URL and the start command
+ /// (#2079); the catalog index is not the thing that is missing.
#[tokio::test]
async fn an_unreachable_node_is_an_error_not_an_empty_map() {
let ctx = disconnected_ctx();
@@ -979,7 +980,15 @@ mod tests {
let res = crate::call_tool(&ctx, &msg).await;
assert_eq!(res["isError"], true);
let text = res["content"][0]["text"].as_str().unwrap();
- assert!(text.contains("request to"), "{text}");
- assert!(text.contains(CATALOG_INDEX), "{text}");
+ assert!(
+ text.contains("no XERJ node is listening at http://127.0.0.1:1"),
+ "{text}"
+ );
+ assert!(
+ text.contains("xerj --insecure --data-dir ~/xerj-data"),
+ "{text}"
+ );
+ assert!(text.contains("xerj mcp does not start a node"), "{text}");
+ assert!(!text.contains("\"indexes\""), "{text}");
}
}