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.

mcp: xerj_search defaults its index to ax-* — the autoindex prefix (#962)

xerj-org12e7a26b680f
diff --git a/engine/crates/xerj-mcp/src/lib.rs b/engine/crates/xerj-mcp/src/lib.rs
index e2b71a691..44325b2dc 100644
--- a/engine/crates/xerj-mcp/src/lib.rs
+++ b/engine/crates/xerj-mcp/src/lib.rs
@@ -472,7 +472,12 @@ pub fn tool_specs() -> Value {
"inputSchema": {
"type": "object",
"properties": {
- "index": { "type": "string", "description": "Index name to search." },
+ "index": {
+ "type": "string",
+ "description": "Index name or pattern to search. Defaults to `ax-*` — \
+ the prefix `xerj autoindex` writes — so the common case needs \
+ no argument. Pass an explicit name to search anything else."
+ },
"query": {
"type": ["object", "string"],
"description": "Plain string (definition-first code search) or ES query-DSL clause. Omit for match_all.",
@@ -482,8 +487,7 @@ pub fn tool_specs() -> Value {
"sort": { "description": "ES sort clause (array or object)." },
"_source": { "description": "Source filtering (bool, field, or {includes,excludes})." },
"rerank": rerank_arg_schema(false)
- },
- "required": ["index"]
+ }
}
},
{
@@ -960,7 +964,17 @@ fn apply_rerank(
}
fn build_search(args: &Value) -> Result<BuiltRequest, String> {
- let index = req_str(args, "index")?;
+ // #962: `index` used to be required, but nothing an agent reads said what
+ // to pass — the first real tool call after `xerj autoindex` was an error
+ // until the agent guessed `ax-*`. Default to the prefix autoindex writes
+ // (matching the CLI's `xerj search`, which defaults to "ax"); an explicit
+ // index still wins.
+ let index = args
+ .get("index")
+ .and_then(Value::as_str)
+ .map(str::trim)
+ .filter(|s| !s.is_empty())
+ .unwrap_or("ax-*");
let mut body = serde_json::Map::new();
let mut plain_string = false;
match args.get("query") {
@@ -1311,8 +1325,18 @@ mod tests {
}
#[test]
- fn search_requires_index() {
- assert!(build_search(&json!({})).is_err());
+ fn search_index_defaults_to_the_autoindex_prefix() {
+ // #962: an agent that ran `xerj autoindex` and then called
+ // xerj_search with no index got isError on its first real tool
+ // call — nothing said the corpus lives under `ax-*`. The default
+ // now matches what autoindex writes (and what `xerj search` uses).
+ let (_, path, _) = built(build_search(&json!({})));
+ assert_eq!(path, "/ax-*/_search");
+ // Whitespace-only is treated as absent; explicit index still wins.
+ let (_, path, _) = built(build_search(&json!({ "index": " " })));
+ assert_eq!(path, "/ax-*/_search");
+ let (_, path, _) = built(build_search(&json!({ "index": "docs" })));
+ assert_eq!(path, "/docs/_search");
}
#[test]
@@ -1507,9 +1531,8 @@ mod tests {
assert!(
!spec["inputSchema"]["required"]
.as_array()
- .unwrap()
- .iter()
- .any(|r| r == "rerank"),
+ .map(|r| r.iter().any(|r| r == "rerank"))
+ .unwrap_or(false),
"{tool}: `rerank` is optional"
);
}
diff --git a/landing/docs/agents/schemas/mcp-tools.json b/landing/docs/agents/schemas/mcp-tools.json
index 9ffbdf745..841234fc6 100644
--- a/landing/docs/agents/schemas/mcp-tools.json
+++ b/landing/docs/agents/schemas/mcp-tools.json
@@ -8,7 +8,7 @@
"properties": {
"index": {
"type": "string",
- "description": "Index name to search."
+ "description": "Index name or pattern to search. Defaults to `ax-*` — the prefix `xerj autoindex` writes — so the common case needs no argument. Pass an explicit name to search anything else."
},
"query": {
"type": [
@@ -38,10 +38,7 @@
],
"description": "Optional second-stage reranking. XERJ sends the text of the top `window` hits plus the question to an external relevance model, which returns a calibrated probability (0..1) per document. Hits are reordered by it, that probability REPLACES `_score`, and `min_score` prunes by it — an absolute relevance cut, which a BM25 score cannot give you. WORTH IT WHEN: a natural-language question over prose where the right document is probably in the top 30 but not at the top; or you need a yes/no relevance threshold rather than a relative rank. NOT WORTH IT FOR: exact identifier or symbol lookups (the first stage already ranks the definition first), filters, sorted or aggregation-only requests — it adds a paid network round-trip per search. NEEDS A CONFIGURED PROVIDER: the node's operator must have set a provider key (`[rerank] api_key` or TYPESAFE_API_KEY). You cannot supply one in this call. Without it the search fails with HTTP 503 `rerank_exception`; do not retry, repeat the search without `rerank`. HTTP 403 means the operator disabled it. PRIVACY: this is the only search-time feature that sends document text off the node. Proxy embeddings (`[embedding] default_endpoint`) and the WAL tap also send text off the node when an operator configures them, so never tell a user that nothing else leaves the machine — do not use rerank on data that must stay local unless the user has agreed. Only fields the response returns are sent, so `_source` filtering also limits what leaves. Pass true or {} for defaults, or an object with: `query` (string): the natural-language question to judge documents against. Filled in for you when the tool's `query` is a plain string (that mode also returns the matching passage, which leads the text the judge reads); REQUIRED when the tool's `query` is a `bool`, a `knn`, or anything else with no single question in it (the node refuses rather than guess). `window` (int, default 30, max 300): how many top hits are judged — every one is a paid judgement; `from`+`size` must fit inside it. `min_score` (0..1): drop hits judged below this probability. `fields` (string[]): which returned fields to send; default is every returned string field. `instructions` (string): override what \"relevant\" means for this corpus. `timeout_ms` (int, default 10000). `model` (string). Cannot be combined with `sort`. READ THE RESPONSE'S `_rerank` BLOCK: `applied: true` means the order is the judge's and every `_score` is a probability or null (a hit with no verdict, counted in `unjudged`, sorts last); `applied: false` means the provider missed the deadline or answered nothing usable, and you are looking at the engine's own order with engine scores, stated in `reason`."
}
- },
- "required": [
- "index"
- ]
+ }
}
},
{