feat(fts): 8e — sqlrite-mcp bm25_search tool

[joaoh82]

Summary

Fifth sub-phase of Phase 8. Adds the bm25_search MCP tool — symmetric with vector_search (Phase 7h), surfaces FTS prominently to LLM clients driving SQLRite over MCP. Resolves Q9.

// MCP tool call
{
  "name": "bm25_search",
  "arguments": {
    "table": "docs",
    "column": "body",
    "query": "rust embedded database",
    "k": 5
  }
}
// → { rows: [...], k_requested: 5, ... }

Wraps SELECT * FROM <t> WHERE fts_match(<col>, 'q') ORDER BY bm25_score(<col>, 'q') DESC LIMIT k so the LLM doesn't have to remember the WHERE pre-filter, the DESC direction, or SQL string quoting. Picks up the Phase 8b optimizer hook automatically.

What landed

• New tool sqlrite-mcp/src/tools/bm25_search.rs:
  • Metadata declares the JSON schema (required: table, column, query; optional: k clamped to 1..=100, default 10).
  • Pre-flight checks (table exists, column is TEXT, FTS index attached) surface clean errors before any SQL runs — useful for an LLM trying to recover.
  • SQL string-literal escaper handles embedded apostrophes per SQL standard (doubled quote).
• Wiring sqlrite-mcp/src/tools/mod.rs:
  • mod bm25_search;
  • tools/list lists it after vector_search and before ask.
  • tools/call dispatches by name.

Test plan

MCP test count went 16 → 19 (+3 bm25-specific):

• bm25_search_returns_top_ranked_rows — 4-doc corpus, the doc with tf=2 wins; the doc without rust is filtered out (verifies the optimizer hook + WHERE pre-filter both work end-to-end through MCP).
• bm25_search_without_index_errors_clearly — actionable error pointing at the missing CREATE INDEX … USING fts step.
• bm25_search_rejects_non_text_column — clean error on INTEGER columns.
• tools_list_returns_expected_set_in_default_mode updated to include bm25_search.
• Internal: tools::bm25_search::tests::sql_string_literal_doubles_quotes.
• cargo test -p sqlrite-mcp — 19 / 19 green
• cargo test --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs — engine 303 + 73 across other crates green
• cargo fmt --all -- --check — no diff
• cargo clippy --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --all-targets — no new warnings on bm25_search code
• cargo doc --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --no-deps — no doc warnings on bm25_search

Out of scope (last sub-phase)

Concern	Lands in
Docs sweep — docs/fts.md, docs/file-format.md, docs/supported-sql.md, docs/mcp.md (bm25_search entry)	8f

🤖 Generated with Claude Code