fix(MCP): Avoid required search config fields that aren't relevant to the configured search type

[vishal-bala]

Motivation

The RedisVL MCP config validation was treating vector and text settings as universally required, even when the configured search mode did not use them. In practice, that meant a full-text-only deployment still had to provide vector-specific settings such as a vectorizer, a vector field name, and embed-source configuration just to start the server. That made the MCP surface unnecessarily rigid and blocked valid non-vector use cases.

The pain point was most visible in two places. First, search.type: vector was incorrectly forcing runtime.text_field_name, even though vector search does not use a text field for retrieval. Second, search.type: fulltext still inherited vector-only startup and config requirements because the server always initialized a vectorizer and always validated vector mappings. The result was that irrelevant settings became mandatory, which made configs harder to reason about and made full-text-only deployments look unsupported even though the runtime behavior itself did not need those dependencies.

Changes

This change makes RedisVL MCP validation capability-aware instead of globally strict. The YAML shape stays the same, but runtime settings and vectorizer requirements are now enforced only when the configured behavior actually needs them. runtime.text_field_name is required for fulltext and hybrid search, while runtime.vector_field_name and vectorizer are required only for vector-backed search or server-side embedding. runtime.default_embed_text_field is now treated as an embedding capability setting rather than a universal requirement.

Startup behavior was updated to match that model. The server no longer initializes and dimension-checks a vectorizer for deployments that do not need one. That allows a full-text-only MCP config to start cleanly without vector settings, while keeping the existing fail-fast behavior for vector and hybrid search.

The write path was also split into capability-specific branches. upsert-records now supports plain schema-validated writes when no vector field is configured. When a vector field is configured but server-side embedding is not, the caller must provide vectors explicitly and the request fails at upsert time if required vectors are missing. When server-side embedding is configured, the previous embedding flow remains in place. As a small follow-up, the patch also adds a TODO near the embedding call noting that the current implementation can still re-embed records that already include vectors, which is wasteful and may add external embedding cost.

---

Note

Medium Risk
Touches MCP config validation and request-time behavior for search/upsert, which can change startup acceptance and error paths for existing deployments, especially around optional vector/embedding settings.

Overview
RedisVL MCP now treats vector-related settings as optional capabilities rather than universally required, allowing fulltext-only deployments to omit vectorizer, runtime.vector_field_name, and runtime.default_embed_text_field while still enforcing the right requirements for vector and hybrid search.

Config validation was updated to be search-mode aware (new capability helpers and validators), server startup only initializes a vectorizer when required, search-records and upsert-records add explicit runtime checks for missing text/vector fields, and upsert now supports plain writes with no vector config while requiring caller-supplied vectors when a vector field is configured but server-side embedding is not. Docs and tests were expanded to cover fulltext-only configs and the new upsert behaviors.

^{Reviewed by Cursor Bugbot for commit 889c5e2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 889c5e2. Configure here.}