Repository navigation
fix(mcp): say how to start a node when XERJ_URL is down - #2085
Merged
Merged
Conversation
MCP tool calls turned a refused connection into "request to <url> failed". Field reports on v1.0.0-rc.97 show agents treating that as a dead end and falling back to ripgrep instead of starting the node. A connect failure now says no XERJ node is listening at XERJ_URL, that xerj mcp does not start one, and prints the documented command `xerj --insecure --data-dir ~/xerj-data` (llms.txt "Start here", the README, and the xerj mcp CLI reference). HTTP responses, including 401, stay "XERJ returned HTTP <status>: ...". Written by an AI coding agent. Fixes #2079. Co-authored-by: xerj-org <xerj-org@users.noreply.github.com>
xerj-org
marked this pull request as ready for review
October 21, 2026 16:40
# Conflicts: # CHANGELOG.md
Owner
Author
|
Xerj Merger made the fix: reviewed the diff. When an MCP proxy tool can't connect to XERJ_URL (connection refused, host or network unreachable, DNS failure), the result now says no XERJ node is listening there, that xerj mcp doesn't start one, and gives the documented start command |
This was referenced Oct 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Written by an AI coding agent (Cursor Grok 4.7), run by the account that opens this pull request.
Fixes #2079
What this changes, and why
xerj mcpproxies tool calls toXERJ_URLand does not start a node. When nothing was listening,xerj_search,xerj_map, and the other thin proxies returned onlyrequest to <url> failed: <reqwest error>. rc.97 field reports (#2025, #2027, #2032, #2033) show agents treating that as a dead end and falling back to ripgrep. They recovered only after finding the start command themselves.A connect failure (connection refused, or otherwise unreachable) now says that no XERJ node is listening at that URL, that
xerj mcpdoes not start one, and prints the documented commandxerj --insecure --data-dir ~/xerj-data(llms.txt "Start here" step 1, the README, and thexerj mcpCLI reference). HTTP responses, including 401, stayXERJ returned HTTP <status>: <body>.Evidence
The new cases in that run:
node_not_listening_names_the_url_and_the_documented_start_command,a_refused_connection_on_xerj_search_tells_the_agent_to_start_the_node,an_unreachable_node_is_an_error_not_an_empty_map(connection refused on127.0.0.1:1),an_http_401_is_not_rewritten_as_node_down(local HTTP/1.1 401), anda_non_connect_transport_error_keeps_the_request_failed_text(builder error, not a down node).Checks
cargo fmt --all(CI runsrustfmt --checkandclippy -D warnings) — rancargo +1.97.1 fmt -p xerj-mcp -- --check, the crate this PR touches. Not workspace-wide.cargo build --release -j 32 -p <crate>cargo test -p <crate>passes —cargo +1.97.1 test -p xerj-mcp --lib(102 passed). Integration tests underengine/crates/xerj-mcp/tests/were compiled by clippy--testsand not executed; they boot an in-process node and do not cover this error string.CHANGELOG.mdunder[Unreleased]. The start command is already the one in llms.txt / the README / thexerj mcpCLI reference; this PR quotes it instead of editing those pages.docs/CONTRIBUTION_REVIEW.md— independent branch off currentorigin/main(8b066e4b). No durable state, recovery path, or engine HTTP contract changes. Only the MCP tool text for a failed connect changes.Not run:
cargo build --release -p xerj-mcp(debug tests and clippy covered the crate). ES-YAML runner (no engine change).cargo fmt --all/ workspace clippy (onlyxerj-mcpis touched).Provenance
cargo test,cargo clippy, andcargo fmt --checkcommands above, on Rust 1.97.1. Connection refused was a real connect to127.0.0.1:1. The 401 was a real HTTP/1.1 response from a local listener.Error::is_connect()on every platform we ship, not only this Linux host. A platform where connection refused is notis_connect()and notErrorKind::ConnectionRefused/ the listed unreachable strings would keep the oldrequest to … failedtext.xerj_code_searchuses a separate transport (McpXc) and is unchanged.