feat(MCP): [4/5] add RedisVL MCP CLI

[vishal-bala]

Builds on top of #540

Summary

• The repo did not have an end-to-end MCP entrypoint, which made the MCP design in spec/MCP.md incomplete in practice and left users without a supported way to run RedisVL as an MCP server.
• That gap creates friction for local agent integrations: the server contract, config, filters, and tools existed as design and implementation work, but there was no polished CLI path and no clear packaging/runtime story for using it.
• This change completes the MCP implementation by adding the rvl mcp command, wiring in lazy optional-dependency handling, and rounding out the MCP server/config/tooling surface with tests and documentation updates.
• It also adds task-oriented help text for the new subcommand and keeps the base CLI usable without MCP extras installed.

Testing

• uv run python -m pytest tests/unit/test_cli_mcp.py -q
• uv run python -m pytest tests/unit/test_mcp -q
• uv run rvl
• uv run rvl mcp --help
• Manual smoke check: started uv run rvl mcp --config /tmp/redisvl_mcp_smoke/config.yaml against a live Redis container
• uvx --from 'redisvl[mcp]' rvl mcp --config ... currently resolves the published package, which does not yet include the new extra/CLI path, so that install-path check is not green until a release is cut

---

Note

Medium Risk
Adds a new MCP CLI entrypoint and introduces an upsert-records tool that can write data into Redis indexes (including embedding generation/serialization), which could impact data integrity and runtime behavior if misconfigured.

Overview
Adds a new rvl mcp subcommand that lazily loads optional MCP dependencies, enforces Python >=3.10, and runs the MCP server over stdio with improved help/usage and error handling.

Extends the MCP server to conditionally register a new upsert-records tool when not in read-only mode, and exports it via redisvl.mcp.tools. The upsert tool validates request shape and schema, optionally generates missing embeddings via the configured vectorizer (with async/sync fallbacks), serializes HASH vector fields to buffers, and annotates backend failures as potentially partial writes.

Includes comprehensive unit/integration tests covering CLI behavior, read-only tool registration, embedding/serialization behavior, and request validation; plus minor typing tweaks in mcp/filters.py to avoid newer annotation syntax.

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9441c1d942

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[rbs333]

LGTM! figure this goes after the other stuff

[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.}