feat(mcp): load code tools from modules named in the config

[vishal-bala]

Motivation

server.code_tool(...) from the previous PR only helps when the caller's own code constructs the server. The common deployment is rvl mcp --config, which imports no user code. This PR lets the config name modules for the server to import. Because importing a module runs its code with the server's privileges, nothing is imported unless the operator opts in separately.

Changes

@code_tool(...), exported from redisvl.mcp, takes the same arguments as server.code_tool. It checks the function and attaches its spec as an attribute, without registering it anywhere:

# myapp/support_tools.py
from redisvl.mcp import ToolContext, code_tool


@code_tool(index="tickets", namespace="support")
async def count_open_tickets(ctx: ToolContext, product: str) -> dict:
    """Count open support tickets for a product."""
    ...

server:
  redis_url: redis://localhost:6379
  allow_code_tools: true
  code_tool_modules: [myapp.support_tools]

At startup, the server imports each listed module before any binding connects. Every function marked with @code_tool is validated and registered alongside tools from server.code_tool, under the same startup checks.

Startup refuses, naming the module or setting:

Refused when	Why
code_tool_modules is set without allow_code_tools: true (default false)	The import runs operator code; the opt-in keeps a profiles-only config from running any Python. Checked at config load.
A module entry is blank, padded or listed twice	Almost certainly a typo.
A module cannot be imported, or raises while importing	Reported by module name, with the cause chained.
A module defines no @code_tool function	A misspelled module name should not quietly produce a server with fewer tools.
A decorator is applied over @code_tool	functools.wraps copies the marker while the spec still calls the inner function, so the outer decorator would silently never run.

The marker lives on the function, not in a module-level registry. Importing a module therefore registers nothing anywhere, and two servers in one process stay independent, as do tests that import a tool module. The loader considers only functions and reads the marker from each function's own __dict__, so a module attribute with a permissive __getattr__, such as a lazy module proxy, is never consulted. A tool one listed module re-exports from another registers once.

The docs gain "Code Tools Loaded From Modules" and a troubleshooting entry. They state that rvl does not put the working directory on the import path: modules must be installed or on PYTHONPATH, and under uvx installed in the environment it builds.

Notes

The loader does not edit sys.path. Adding the config's directory would make import resolution depend on where the config file happens to live.

I verified the end-to-end flow manually with rvl mcp --transport streamable-http, a scratch module on PYTHONPATH and the server started from outside the project directory. A FastMCP client listed support-count-open-tickets with only product in its schema, and a call returned the expected count.

Release Notes

rvl mcp can load code tools from Python modules. Mark async functions with @code_tool from redisvl.mcp, list their modules under server.code_tool_modules, and set server.allow_code_tools: true, which defaults to false because importing a module runs its code with the server's privileges. Modules must be importable by the server process.

Next Steps

• Update the custom-tools proposal to record where v1.1 departs from it: the code_tool names, no ctx.guarded (the handle applies the limits itself), id-only writes and no filter-wide bulk writes, no code tools on tenant-scoped indexes, async tools only, and the whole-call timeout.