Module tool_script 

Lua MCP tool extensions.

Loads .lua tool scripts at server startup, extracts their parameter schemas, and provides execution with a context bridge back into the Rust core (search, get, sources).

Architecture

Tool scripts follow the same sandboxed Lua VM model as connectors (crate::connector_script), reusing all host APIs from crate::lua_runtime. In addition, tools receive a context table with:

• context.search(query, opts?) — search the knowledge base
• context.get(id) — retrieve a document by UUID
• context.sources() — list connector status
• context.config — tool-specific configuration from ctx.toml

Script Interface

Every tool script defines a global tool table:

tool = {
    name = "my_tool",
    description = "Does something useful",
    parameters = {
        { name = "query", type = "string", required = true, description = "Search query" },
    },
}

function tool.execute(params, context)
    local results = context.search(params.query)
    return { results = results }
end

Configuration

[tools.script.my_tool]
path = "tools/my-tool.lua"
timeout = 30
api_key = "${MY_API_KEY}"

See docs/LUA_TOOLS.md for the full specification.

Structs

LuaToolAdapter

Adapter that wraps a Lua ToolDefinition as a Tool trait object.

ToolDefinition

Metadata extracted from a loaded Lua tool script.

ToolInfo

Serializable tool info for the /tools/list endpoint.

Functions

build_tool_list

Build the list of all tools (built-in + Lua) for the /tools/list endpoint.

doc_response_to_lua 🔒

Convert a document response to a Lua table.

execute_tool

Execute a tool script with the given parameters.

json_type_name 🔒

Return a human-readable name for a JSON value’s type.

list_tools

List all configured tools and print their info.

load_single_tool

Load a single tool script and extract its definition.

load_tool_definitions

Load all tool scripts from config and extract their definitions.

lua_params_to_json_schema 🔒

Convert Lua parameter declarations to OpenAI function-calling JSON Schema.

register_context_bridge 🔒

Register the context table in the Lua VM.

run_lua_tool 🔒

Run the Lua tool synchronously on a blocking thread.

scaffold_tool

Scaffold a new tool script from a template.

search_results_to_lua 🔒

Convert search results to a Lua array table.

sources_to_lua 🔒

Convert source statuses to a Lua array table.

test_tool

Test a tool script with sample parameters.

validate_params

Validate incoming JSON parameters against a tool’s schema.