Introspection API

Runtime namespace discovery tools for DCC host interpreters (issue #426).

Four read-only MCP tools that let AI agents inspect the live DCC Python namespace without burning tokens on web searches. All tools are registered with read_only_hint=True, idempotent_hint=True and hard-cap their output.

Namespace discovery accepts dotted modules, SDK classes, and dynamic namespaces such as unreal.GeometryScript_BoneWeights or bpy.ops.object. It imports the longest available module prefix, then resolves each remaining attribute without invoking the discovered callable. Import initialization and missing dependency errors are reported rather than hidden by attribute fallback. Names must consist of identifiers separated by dots; expressions and calls are not accepted.

Exported symbols: introspect_eval, introspect_list_module, introspect_search, introspect_signature, register_introspect_tools

register_introspect_tools

register_introspect_tools(server, *, dcc_name="dcc") -> None

Register the four dcc_introspect__* tools on server. Call before server.start().

Registered tools: dcc_introspect__list_module, dcc_introspect__signature, dcc_introspect__search, dcc_introspect__eval.

introspect_list_module

introspect_list_module(module_name: str, *, limit: int = 200) -> dict

Return exported names from module_name.

Parameter	Type	Default	Description
module_name	str		Dotted module path (e.g. "maya.cmds")
limit	int	200	Max names to return

Returns: {"names": [...], "count": N, "truncated": bool}

introspect_signature

introspect_signature(qualname: str) -> dict

Return signature and docstring for qualname (e.g. "maya.cmds.polyCube" or "unreal.GeometryScript_BoneWeights.set_vertex_bone_weights").

Returns: {"signature": str, "doc": str, "source_file": str|None, "kind": str}

introspect_search

introspect_search(pattern: str, module_name: str, *, limit: int = 50) -> dict

Regex-search exported names in module_name (case-insensitive).

Parameter	Type	Default	Description
pattern	str		Case-insensitive regex
module_name	str		Module to search
limit	int	50	Max hits to return

Returns: {"hits": [{"qualname": str, "summary": str}, ...], "count": int}

introspect_eval

introspect_eval(expression: str) -> dict

Evaluate a bounded expression and return its repr. The accepted subset contains literals, bounded arithmetic and indexing, plus allowlisted pure builtins such as len, range, sorted, and type.

Attribute access, comprehensions, imports, assignments, lambdas, dynamic builtin lookup, and unbounded container expansion are rejected before evaluation. Use introspect_list_module, introspect_search, and introspect_signature for DCC API discovery; introspect_eval cannot invoke DCC objects.

introspect_eval("sorted([3, 1, 2], reverse=True)")
# -> {"success": True, "context": {"repr": "[3, 2, 1]", ...}, ...}

Returns: {"repr": str} on success, or {"success": False, "message": err} on error.