feat(mcp): add index routing + per-index write policy to upsert-records (RAAE-1607)

[vishal-bala]

Motivation

This completes the multi-index tool surface for the RedisVL MCP server. After RAAE-1606 taught search-records to route by logical index, upsert-records (RAAE-1607) needs the same explicit routing — but writes also carry a policy dimension that reads do not. A single server can now host a mix of writable and read-only bindings, and the tool must respect both the global --read-only override and each binding's own read_only flag while staying backwards-safe for existing single-index clients.

The design keeps single-index behavior identical: when one binding is configured and index is omitted, the write resolves to that binding exactly as before. Routing becomes mandatory only once multiple bindings exist. Write enforcement happens at two complementary levels so the contract is unambiguous: a server with no writable bindings should not advertise the tool at all, while a server with some writable bindings still needs to protect the read-only ones on a per-call basis.

Implemented changes

upsert-records gains an optional index argument naming the logical binding to write to, resolved through the shared resolve_binding routing introduced in RAAE-1604. An omitted index with one binding resolves to that binding; an omitted index with multiple bindings returns invalid_request; and an unknown id returns invalid_request. The resolved logical id is echoed back as the index field of the response, and the selected binding's embedding, runtime limits, and schema validation drive the rest of the write unchanged.

Write availability is enforced at two levels. The tool registration gate is refined from "global read-only is off" to "at least one binding is writable" — expressed via effective_read_only, which already folds in both global read-only mode and a binding's own read_only policy — so an all-read-only server does not expose upsert-records at all. When the tool is registered, a per-call guard rejects writes to any individual read-only binding with invalid_request before any embedding or backend write occurs, so a writable server can still protect specific indexes.

Minor additional changes:

• The FastMCP wrapper exposes index as a tool parameter.
• Unit coverage for default-to-sole-binding, named routing, unknown-id rejection, read-only-binding rejection, the wrapper param, and both registration-gate outcomes (any-writable exposes the tool; all-read-only hides it).
• Integration coverage on a two-binding server (one writable vector index, one read-only fulltext index): routing to the writable binding, omitted-index rejection, unknown-id rejection, read-only-binding rejection, and single-binding echo.

Verification

• make format (isort + black) and mypy clean on changed files.
• Full MCP suite: 244 passed, 2 skipped (Redis-version-gated) across unit + integration.

Stacking

This PR targets feature/raae-1606-search-routing so its diff stays scoped to upsert routing + write policy. Review/merge bottom-up: #629 → #630 → #631 → this PR.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes write routing and when the upsert tool is exposed on multi-index servers; mistakes could allow writes to the wrong index or hide/show the tool unexpectedly, though enforcement is fail-closed before backend writes.

Overview
upsert-records now accepts an optional index logical binding id (via shared resolve_binding), matching multi-index search-records: omit index when one binding is configured; require it when several exist; reject unknown ids. Successful responses include an index field naming the binding that was written.

Write policy is split between tool advertisement and per-call enforcement. upsert-records is registered only when at least one binding is writable (effective_read_only is false for some binding), not merely when global read-only mode is off. Each call still rejects writes to read-only bindings (FORBIDDEN, before embedding or Redis load) with a clearer message naming the binding.

The FastMCP wrapper exposes index as a tool parameter. Unit and integration tests cover routing, registration gating, and read-only rejection.

^{Reviewed by Cursor Bugbot for commit 98aded7. 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}

[nkanu17]

lgtm!

[nkanu17]

lgtm

[vishal-bala]

Failing tests are from the Redis 8.8 race condition issue that's been flagged before