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

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}