Traverses a view element tree and derives namespaced MCP tools from widgets.

The view tree is the output of a TEA app's view/1 function -- nested maps with :type, :id, :attrs, :children keys. TreeWalker walks this tree, finds widgets that implement Raxol.MCP.ToolProvider, calls mcp_tools/1 to get tool specs, namespaces them by session and widget ID, and wraps callbacks that dispatch TEA messages through the session's Dispatcher.

Usage

context = %{dispatcher_pid: dispatcher_pid, session_id: "demo"}
tools = TreeWalker.derive_tools(view_tree, context)
Raxol.MCP.Registry.register_tools(tools)

Tool names are namespaced as "session_id.widget_id.action", e.g., "demo.search_input.type_into", so two sessions rendering the same widget each get their own tool. Nodes without an :id key are skipped (layout containers like :column, :row). The session id and the widget id become part of a tool name the client lists, so a session whose id is not 1-32 characters of [A-Za-z0-9_-] derives no tools at all, and a provider whose widget id is not derives none of its own (id?/1). Neither may hold a ., so the first segment of a derived name is always its whole session id. The action name is the last segment: one that is not a lowercase letter followed by up to 31 of [a-z0-9_] derives no tool.

Everything else a provider writes reaches the client's tool list as well, which a model reads as instructions. Control, format (bidi, zero-width, BOM, tag), line/paragraph separator, private-use and invisible filler characters (variation selectors, combining grapheme joiner, Hangul fillers, braille blank) are stripped from a tool's description and from every string and every key inside its inputSchema (titles, enums, defaults, examples, property names). Of a spec's annotations only sensitive: true and destructiveHint: true are kept: they can only add the authorizer requirement, while any other key (title, readOnlyHint, ...) is a provider's self-report a client would act on.

An atom is encoded as its name, so it is cleaned as that name: a description atom becomes its cleaned name, and a schema key or leaf atom stays an atom when its name is clean and becomes the cleaned string otherwise. A spec derives no tool, and is refused like a misnamed action, when its description is neither a string nor an atom (nil means none), when its inputSchema holds anything JSON cannot encode (a tuple, a struct, a pid, a function, an improper list, a key that is neither a string nor an atom), when two keys of one map are equal once cleaned and stringified (:amount and "amount", or "amount" and "amount\u200B"), or when its inputSchema nests maps and lists deeper than 32 levels or holds more than 10,000 values (each map, list and leaf counts one). One such spec would otherwise make every client's tools/list unencodable, let one property definition silently replace another, or hold up every render while it is cleaned.

A derived tool is registered as one by Raxol.MCP.ToolSynchronizer (Raxol.MCP.Registry.register_tools/3 with derived: true), which is what Raxol.MCP.Server's boot check reads to tell it from a static tool.

Excluding Widgets

Set mcp_exclude: true in a widget's attrs to suppress tool derivation:

%{type: :text_input, id: "internal", attrs: %{mcp_exclude: true}}

The widget and its children still render normally -- only MCP tool exposure is suppressed. Useful for decorative or internal widgets.

Explicit provider marker (attrs.component_module)

Components whose root emits a plain layout type (:column, :row) can declare their providing module explicitly instead of growing this package's type map (the harness block Components do this):

%{type: :column, id: "blk", attrs: %{component_module: MyBlock}}

An explicit marker wins over the built-in type map; the same ToolProvider guard applies, so a module that does not implement the behaviour still derives nothing, and a non-atom marker is ignored.