Skip to content

fix(mcp): ignore empty semantic queries and clarify mode conflicts - #3016

Open
Cianidos wants to merge 2 commits into
DeusData:mainfrom
Cianidos:fix/search-graph-empty-semantic-query
Open

Cianidos wants to merge 2 commits into
DeusData:mainfrom
Cianidos:fix/search-graph-empty-semantic-query

Conversation

@Cianidos

@Cianidos Cianidos commented Nov 16, 2026 •

Copy link
Copy Markdown

What does this PR do?

Fixes #3015.

Accept semantic_query: [] as an unused optional parameter instead of rejecting a BM25 request. The same empty-array meaning applies to structural search and the empty-query fallback, so it cannot accidentally select semantic-only output.

Nonempty semantic arrays still conflict with query, including when semantic output is disabled with a limit. Malformed semantic inputs remain errors; no requested ranking mode is silently discarded.

The conflict error now tells callers exactly how to recover:

query and semantic_query are mutually exclusive. For BM25 search, remove the semantic_query key (an empty array is also accepted). For vector search, remove the query key entirely. To run both modes, send two separate requests; do not retry unchanged arguments.

The tool parameter description also documents empty-array acceptance and key omission for active semantic search.

Claude Code failure mode

The report records seven failed tool calls retaining query together with semantic_query: [] before the user interrupted. The error was already marked isError: true; it explained the ranking modes without spelling out the concrete key-removal repair. This change removes that deterministic empty-placeholder trap and improves recovery for genuine conflicts. It does not claim to prevent every agent retry loop or identify which client/model layer supplied the placeholders.

Verification

Reproduce-first: with only the regression tests applied to upstream cdfdf264, the focused run reports 0 passed, 2 failed:

  • Empty-array acceptance fails because the handler returns isError: true.
  • Conflict wording fails because it does not contain remove the semantic_query key.

After the fix, the same focused ASan+UBSan run reports 2 passed, 0 failed.

The complete mcp, mcp_mutation_guard, and cli run through scripts/test.sh --suites "mcp mcp_mutation_guard cli" reports 878 passed, 1 failed, 5 platform skips under ASan+UBSan.

  • All MCP and mutation-guard tests pass, including the new regressions and mcp_metadata_byte_budget.
  • The initial longer parameter description exceeded the existing metadata budget by 21 bytes. Commit 5772a50 shortens the description; the budget remains unchanged and its test now passes.
  • The remaining failure is cli_registry_installs_gitlab_and_devin_lifecycle_context at tests/test_cli.c:11583. It reports plan=1 clean_plan=1 installed=0 cleaned=1 gitlab=1 devin=1 uninstall=0.
  • Baseline verification: built a separate ASan+UBSan runner with upstream cdfdf264's src/mcp/mcp.c substituted back into the otherwise unchanged production sources. Running only that CLI test yields the same failure and diagnostic (0 passed, 1 failed, 410 deselected). The baseline check does not run the modified MCP tests. No unrelated installer changes or test skips are included.

Additional checks pass: production-file clang-format --dry-run --Werror, formatting of changed test ranges, git diff --check, the no-skips policy, NOLINT whitelist, memory-core ratchet, vendored-scanner lint, and DCO verification.

The new acceptance test compares responses with and without the empty array across BM25, semantic_limit: 0, empty-query fallback, filtered structural, and unfiltered structural calls in both JSON and tree formats. The conflict test also checks actionable wording and rejection of malformed semantic values.

Local CI lint is blocked by missing cppcheck and pre-existing formatting drift in unchanged source (src/cypher/cypher.c:146, also reproduced from HEAD). No unrelated formatting changes are included.

Live Claude Code agent validation (2026-11-17)

Tested through a real Claude Code agent session and the MCP transport, not only the CLI or unit tests:

  • Built and installed the production arm64 binary with UI, version 0.12.1+pr3016.5772a50, on macOS.
  • Reconnected the configured MCP server using Claude Code's /mcp command.
  • The agent replayed the original failing search_graph arguments, including query: "create_indexes", semantic_query: [], semantic_limit: 0, and the original optional filters. The call succeeded with search_mode: "bm25", total: 0, and no validation error. Zero matches is a valid search response, not a claim about index completeness.
  • The agent then supplied a nonempty semantic_query: ["indexes"] alongside query, keeping semantic_limit: 0. The server correctly rejected the conflict and returned the new error naming the keys to remove and saying do not retry unchanged arguments.

This verifies both requested behaviors in a live agent session; it does not establish that all possible agent retry loops are prevented.

Checklist

  • Tested through a real Claude Code agent session over MCP

  • Every commit is signed off (git commit -s) with the contributor's authorized DCO certification

  • Full test suite passes locally (MCP/mutation-guard/CLI suites run; one baseline CLI failure documented above)

  • Full CI lint passes locally (environment/baseline blockers described above)

  • New behavior has reproduce-first regression coverage

AI assistance was used to write this change; the contributor authorized the DCO sign-off.

Signed-off-by: Aleksandrov Nikita <aleksandrov.ni@icloud.com>
@Cianidos
Cianidos requested a review from DeusData as a code owner November 16, 2026 19:29
@github-actions

Copy link
Copy Markdown

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

  • It will not be closed for inactivity. No stale bot touches pull requests here.
  • It may still sit a while before a human reads it. That is on us, not on you.
  • Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

  • Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
  • Get CI green, or say which failures you believe are pre-existing.
  • Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
  • Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.

Signed-off-by: Aleksandrov Nikita <aleksandrov.ni@icloud.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

search_graph: empty semantic_query array rejects BM25 calls and traps Claude Code in repeated validation failures

1 participant