Add Godot ClassDB API introspection

Author: Joshua

AGENTS.md

@@ -23,8 +23,8 @@ AI Client → MCP (stdio/sse/streamable-http) → Python FastMCP server → WebS
 
 - `src/godot_ai/` — Python MCP server (FastMCP v3)
   - `server.py` — entrypoint, lifespan, tool registration, `--exclude-domains` support
-  - `tools/` — MCP tool modules (session, editor, scene, node, project, script, resource, filesystem, signal, autoload, input_map, game, testing, batch, client, ui, theme, animation, material, particle, camera, audio) + `_meta_tool.py` (`register_manage_tool` rollup factory)
-  - `resources/` — `godot://...` read-only URIs (sessions, editor, project, nodes, scripts, scenes, library)
+  - `tools/` — MCP tool modules (session, editor, scene, node, project, script, resource, api, filesystem, signal, autoload, input_map, game, testing, batch, client, ui, theme, animation, material, particle, camera, audio) + `_meta_tool.py` (`register_manage_tool` rollup factory)
+  - `resources/` — `godot://...` read-only URIs (sessions, editor, project, nodes, classes, scripts, scenes, library)
   - `middleware/` — `PreserveGodotCommandErrorData`, `StripClientWrapperKwargs`, `ParseStringifiedParams`, `HintOpTypoOnManage` (registration order is load-bearing — see the docstring above the `mcp.add_middleware(...)` calls in `server.py` and `tests/unit/test_server_middleware_order.py`)
   - `handlers/` — shared sync handlers using `DirectRuntime`; `_readiness.py` gates writes
   - `runtime/direct.py` — `DirectRuntime`, the in-process runtime adapter
@@ -390,7 +390,7 @@ The MCP tool surface is shaped to satisfy two pressures at once:
 1. **Anthropic tool-search clients** (`tool_search_tool_bm25_20251119` / `tool_search_tool_regex_20251119`) — non-core tools are tagged `meta={"defer_loading": True}` so the client only loads schemas it searches for.
 2. **Tool-count caps in non-search clients** (Antigravity, etc., that ignore `defer_loading` and refuse to start past ~40 tools) — long-tail verbs collapse into per-domain `<domain>_manage` rollups (`op="<verb>"` + `params` dict). Schema-aware clients still see every op via the dynamic `Literal[...]` enum built by `register_manage_tool` in `tools/_meta_tool.py`.
 
-Result: ~40 MCP tools (4 core + 15 named verbs + 21 rollups), down from a flat surface that crossed 100. Plugin command names over WebSocket stay independent — they're documented in `tool_catalog.gd` and unchanged by the rollup refactor.
+Result: ~41 MCP tools (4 core + 15 named verbs + 22 rollups), down from a flat surface that crossed 100. Plugin command names over WebSocket stay independent — they're documented in `tool_catalog.gd` and unchanged by the rollup refactor.
 
 - All tools follow `domain_action` namespacing — no ambiguous prefixes
 - Core tools loaded upfront (no `meta=`): `editor_state`, `scene_get_hierarchy`, `node_get_properties`, `session_activate`

README.md

@@ -9,7 +9,7 @@
 [![Godot Asset Library](https://img.shields.io/badge/Godot-Asset%20Library-478cbf?logo=godotengine&logoColor=white)](https://godotengine.org/asset-library/asset/5050)
 [![Discord](https://img.shields.io/badge/Discord-Join%20chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/FDZ5fr2QkP)
 
-**Connect MCP clients directly to a live Godot editor** via the [Model Context Protocol](https://modelcontextprotocol.io/introduction). Over **120 ops across ~39 MCP tools** ([full list](docs/TOOLS.md)) let AI assistants (Claude Code, Codex, Antigravity, etc.) build scenes, edit nodes and scripts, wire signals, and configure UI, materials, animations, particles, cameras, and environments.
+**Connect MCP clients directly to a live Godot editor** via the [Model Context Protocol](https://modelcontextprotocol.io/introduction). Over **120 ops across ~41 MCP tools** ([full list](docs/TOOLS.md)) let AI assistants (Claude Code, Codex, Antigravity, etc.) build scenes, edit nodes and scripts, wire signals, and configure UI, materials, animations, particles, cameras, and environments.
 
 > 🎉 **Now on the [Godot Asset Library](https://godotengine.org/asset-library/asset/5050) and the [new Godot Asset Store](https://store.godotengine.org/asset/dlight/godot-ai/)** — one-click install from Godot's **AssetLib** tab. You'll still need [uv](https://docs.astral.sh/uv/) for the Python server (see [Quick Start](#quick-start)).
 

docs/TOOLS.md

@@ -1,6 +1,6 @@
 # Available Tools
 
-Godot AI exposes ~39 MCP tools — ~18 high-traffic verbs as named tools, plus
+Godot AI exposes ~41 MCP tools — ~18 high-traffic verbs as named tools, plus
 one rolled-up `<domain>_manage` per domain that takes `op="..."` + a `params`
 dict. The rollup pattern keeps the tool count well below the 100-tool caps
 some clients enforce while still exposing every action.
@@ -82,8 +82,16 @@ Calls take the form:
 | `theme_manage` | `create`, `set_color`, `set_constant`, `set_font_size`, `set_stylebox_flat`, `apply` |
 | `ui_manage` | `set_anchor_preset`, `set_text`, `build_layout`, `draw_recipe` |
 | `resource_manage` | `search`, `load`, `assign`, `get_info`, `create`, `curve_set_points`, `environment_create`, `physics_shape_autofit`, `gradient_texture_create`, `noise_texture_create` |
+| `api_manage` | `get_class` |
 | `client_manage` | `status`, `configure`, `remove` |
 
+`api_manage(op="get_class")` inspects Godot API/ClassDB metadata for a class
+without creating an instance. By default it returns direct class members only,
+with each returned section capped at 100 items. Pass `sections` (`properties`,
+`methods`, `signals`, `enums`, `constants`, `inheritors`),
+`include_inherited=true`, `include_inheritors=true`, `offset`, or `limit=0`
+when a fuller class reference is needed.
+
 Every rolled-up tool also accepts an optional top-level `session_id` for
 per-call multi-editor routing (sibling of `op` and `params`, *not* nested
 inside `params`).
@@ -106,6 +114,7 @@ don't, and the only path that supports `session_id` pinning.
 | `godot://node/{path}/properties` | All properties of a node by scene path |
 | `godot://node/{path}/children` | Direct children (name, type, path each) |
 | `godot://node/{path}/groups` | Group memberships for a node |
+| `godot://class/{class_name}` | ClassDB metadata: properties, methods, signals, enums, constants, inheritance, and defaults |
 | `godot://script/{path}` | GDScript source by res:// path (drop the `res://` prefix) |
 | `godot://project/info` | Active project metadata |
 | `godot://project/settings` | Common project settings subset |

plugin/addons/godot_ai/dispatcher.gd

@@ -21,6 +21,7 @@ const DEFERRED_TIMEOUT_MS_BY_COMMAND := {
 	"game_command": 15000,
 }
 const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd")
+const FuzzySuggestions := preload("res://addons/godot_ai/utils/fuzzy_suggestions.gd")
 
 
 func _init(log_buffer: McpLogBuffer) -> void:
@@ -61,18 +62,7 @@ func has_command(command: String) -> bool:
 ## array if no candidates clear the threshold. Used by batch_execute to surface
 ## "did you mean" suggestions when an unknown command is passed.
 func suggest_similar(cmd_name: String, limit: int = 3, threshold: float = 0.5) -> Array[String]:
-	if cmd_name.is_empty() or _handlers.is_empty():
-		return []
-	var scored: Array = []
-	for name in _handlers.keys():
-		var score: float = cmd_name.similarity(name)
-		if score >= threshold:
-			scored.append([score, name])
-	scored.sort_custom(func(a, b): return a[0] > b[0])
-	var result: Array[String] = []
-	for i in range(min(limit, scored.size())):
-		result.append(scored[i][1])
-	return result
+	return FuzzySuggestions.rank(cmd_name, _handlers.keys(), limit, threshold, 0.0, 0.0)
 
 
 ## Enqueue a raw command dict received from the WebSocket.

plugin/addons/godot_ai/handlers/api_handler.gd

@@ -0,0 +1,84 @@
+@tool
+extends RefCounted
+
+## Read-only access to version-correct Godot class metadata.
+
+const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd")
+const ClassIntrospection := preload("res://addons/godot_ai/utils/class_introspection.gd")
+const FuzzySuggestions := preload("res://addons/godot_ai/utils/fuzzy_suggestions.gd")
+
+func get_class_info(params: Dictionary) -> Dictionary:
+	var requested_class: String = params.get("class_name", "")
+	if requested_class.is_empty():
+		return ErrorCodes.make(
+			ErrorCodes.MISSING_REQUIRED_PARAM,
+			"Missing required param: class_name"
+		)
+	if not ClassDB.class_exists(requested_class):
+		var script_class := _global_script_class(requested_class)
+		if not script_class.is_empty():
+			return _script_class_error(requested_class, script_class)
+		return _unknown_class_error(requested_class)
+	var section_check := ClassIntrospection.validate_sections(
+		params.get("sections", ClassIntrospection.DEFAULT_SECTIONS)
+	)
+	if not section_check.invalid.is_empty():
+		return _invalid_sections_error(section_check.invalid)
+	return {"data": ClassIntrospection.build(requested_class, params)}
+
+
+static func _unknown_class_error(requested_class: String) -> Dictionary:
+	var suggestions := _suggest_classes(requested_class)
+	var message := "Unknown Godot class: %s" % requested_class
+	if not suggestions.is_empty():
+		message += ". Did you mean: %s?" % ", ".join(suggestions)
+	var result := ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, message)
+	result["error"]["data"] = {"suggestions": suggestions}
+	return result
+
+
+static func _suggest_classes(requested_class: String) -> Array[String]:
+	return FuzzySuggestions.rank(requested_class, ClassDB.get_class_list())
+
+
+static func _global_script_class(requested_class: String) -> Dictionary:
+	for raw_info in ProjectSettings.get_global_class_list():
+		var info: Dictionary = raw_info
+		if info.get("class", "") == requested_class:
+			return info
+	return {}
+
+
+static func _script_class_error(requested_class: String, script_class: Dictionary) -> Dictionary:
+	var path := str(script_class.get("path", ""))
+	var base := str(script_class.get("base", ""))
+	var message := (
+		"%s is a project script class, not a ClassDB class. "
+		+ "Use script_manage(op=\"find_symbols\", params={\"path\": \"%s\"}) for script symbols."
+	) % [requested_class, path]
+	var result := ErrorCodes.make(ErrorCodes.WRONG_TYPE, message)
+	result["error"]["data"] = {
+		"script_class": true,
+		"class_name": requested_class,
+		"base_class": base,
+		"path": path,
+	}
+	return result
+
+
+static func _invalid_sections_error(invalid_sections: Array[String]) -> Dictionary:
+	var suggestions := {}
+	for section in invalid_sections:
+		suggestions[section] = FuzzySuggestions.rank(
+			section,
+			ClassIntrospection.KNOWN_SECTIONS,
+			3,
+			0.3
+		)
+	var message := "Unknown class-info section(s): %s. Valid sections: %s" % [
+		", ".join(invalid_sections),
+		", ".join(ClassIntrospection.KNOWN_SECTIONS),
+	]
+	var result := ErrorCodes.make(ErrorCodes.INVALID_PARAMS, message)
+	result["error"]["data"] = {"suggestions": suggestions}
+	return result

plugin/addons/godot_ai/handlers/api_handler.gd.uid

@@ -0,0 +1 @@
+uid://v3rkd7ueunii

plugin/addons/godot_ai/handlers/node_handler.gd

@@ -2,6 +2,7 @@
 extends RefCounted
 
 const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd")
+const VariantSerializer := preload("res://addons/godot_ai/utils/variant_serializer.gd")
 
 ## Handles node creation and manipulation with undo/redo support.
 
@@ -862,67 +863,4 @@ static func _reject_if_scene_root(node: Node, scene_root: Node, op: String) -> V
 ## dicts/arrays so agents can inspect fields instead of parsing Godot's
 ## debug repr — see issue #214.
 static func _serialize_value(value: Variant) -> Variant:
-	if value == null:
-		return null
-	match typeof(value):
-		TYPE_BOOL, TYPE_INT, TYPE_FLOAT, TYPE_STRING:
-			return value
-		TYPE_STRING_NAME:
-			return str(value)
-		TYPE_VECTOR2, TYPE_VECTOR2I:
-			return {"x": value.x, "y": value.y}
-		TYPE_VECTOR3, TYPE_VECTOR3I:
-			return {"x": value.x, "y": value.y, "z": value.z}
-		TYPE_VECTOR4, TYPE_VECTOR4I, TYPE_QUATERNION:
-			return {"x": value.x, "y": value.y, "z": value.z, "w": value.w}
-		TYPE_COLOR:
-			return {"r": value.r, "g": value.g, "b": value.b, "a": value.a}
-		TYPE_RECT2, TYPE_RECT2I, TYPE_AABB:
-			return {
-				"position": _serialize_value(value.position),
-				"size": _serialize_value(value.size),
-			}
-		TYPE_PLANE:
-			return {"normal": _serialize_value(value.normal), "d": value.d}
-		TYPE_BASIS:
-			return {
-				"x": _serialize_value(value.x),
-				"y": _serialize_value(value.y),
-				"z": _serialize_value(value.z),
-			}
-		TYPE_TRANSFORM2D:
-			return {
-				"x": _serialize_value(value.x),
-				"y": _serialize_value(value.y),
-				"origin": _serialize_value(value.origin),
-			}
-		TYPE_TRANSFORM3D:
-			return {
-				"basis": _serialize_value(value.basis),
-				"origin": _serialize_value(value.origin),
-			}
-		TYPE_PROJECTION:
-			return {
-				"x": _serialize_value(value.x),
-				"y": _serialize_value(value.y),
-				"z": _serialize_value(value.z),
-				"w": _serialize_value(value.w),
-			}
-		TYPE_NODE_PATH:
-			return str(value)
-		TYPE_ARRAY, TYPE_PACKED_BYTE_ARRAY, TYPE_PACKED_INT32_ARRAY, TYPE_PACKED_INT64_ARRAY, TYPE_PACKED_FLOAT32_ARRAY, TYPE_PACKED_FLOAT64_ARRAY, TYPE_PACKED_STRING_ARRAY, TYPE_PACKED_VECTOR2_ARRAY, TYPE_PACKED_VECTOR3_ARRAY, TYPE_PACKED_COLOR_ARRAY:
-			var arr: Array = []
-			for item in value:
-				arr.append(_serialize_value(item))
-			return arr
-		TYPE_DICTIONARY:
-			var out := {}
-			for k in value:
-				out[str(k)] = _serialize_value(value[k])
-			return out
-		TYPE_OBJECT:
-			if value is Resource and value.resource_path:
-				return value.resource_path
-			return str(value)
-		_:
-			return str(value)
+	return VariantSerializer.serialize(value)

plugin/addons/godot_ai/handlers/resource_handler.gd

@@ -2,6 +2,7 @@
 extends RefCounted
 
 const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd")
+const ClassIntrospection := preload("res://addons/godot_ai/utils/class_introspection.gd")
 
 ## Handles resource search, inspection, and assignment to nodes.
 
@@ -373,37 +374,25 @@ func get_resource_info(params: Dictionary) -> Dictionary:
 			"%s is not a Resource type (extends %s)" % [type_str, parent]
 		)
 
-	var properties: Array[Dictionary] = []
-	for prop in ClassDB.class_get_property_list(type_str):
-		var usage: int = prop.get("usage", 0)
-		if not (usage & PROPERTY_USAGE_EDITOR):
-			continue
-		properties.append({
-			"name": prop.name,
-			"type": type_string(prop.type),
-			"hint": prop.get("hint", 0),
-			"usage": usage,
-		})
-	properties.sort_custom(func(a, b): return a.name < b.name)
-
 	var can_instantiate: bool = ClassDB.can_instantiate(type_str)
+	var class_info := ClassIntrospection.build(type_str, {
+		"sections": ["properties"],
+		"include_inherited": true,
+		"include_inheritors": not can_instantiate,
+		"limit": 0,
+	})
 	var data: Dictionary = {
 		"type": type_str,
-		"parent_class": ClassDB.get_parent_class(type_str),
+		"parent_class": class_info.parent_class,
 		"can_instantiate": can_instantiate,
 		"is_abstract": not can_instantiate,
-		"properties": properties,
-		"property_count": properties.size(),
+		"properties": class_info.properties,
+		"property_count": class_info.property_count,
 	}
 
 	# For abstract bases (Shape3D, Material, Texture, StyleBox, ...) surface
 	# the concrete Resource subclasses an agent could try next.
 	if not can_instantiate:
-		var subclasses: Array[String] = []
-		for cls in ClassDB.get_inheriters_from_class(type_str):
-			if ClassDB.can_instantiate(cls) and ClassDB.is_parent_class(cls, "Resource"):
-				subclasses.append(cls)
-		subclasses.sort()
-		data["concrete_subclasses"] = subclasses
+		data["concrete_subclasses"] = class_info.concrete_inheritors
 
 	return {"data": data}

plugin/addons/godot_ai/plugin.gd

@@ -64,6 +64,7 @@ const ProjectHandler := preload("res://addons/godot_ai/handlers/project_handler.
 const ClientHandler := preload("res://addons/godot_ai/handlers/client_handler.gd")
 const ScriptHandler := preload("res://addons/godot_ai/handlers/script_handler.gd")
 const ResourceHandler := preload("res://addons/godot_ai/handlers/resource_handler.gd")
+const ApiHandler := preload("res://addons/godot_ai/handlers/api_handler.gd")
 const FilesystemHandler := preload("res://addons/godot_ai/handlers/filesystem_handler.gd")
 const SignalHandler := preload("res://addons/godot_ai/handlers/signal_handler.gd")
 const AutoloadHandler := preload("res://addons/godot_ai/handlers/autoload_handler.gd")
@@ -243,6 +244,7 @@ func _enter_tree() -> void:
 	var client_handler := ClientHandler.new()
 	var script_handler := ScriptHandler.new(get_undo_redo(), _connection)
 	var resource_handler := ResourceHandler.new(get_undo_redo(), _connection)
+	var api_handler := ApiHandler.new()
 	var filesystem_handler := FilesystemHandler.new()
 	var signal_handler := SignalHandler.new(get_undo_redo())
 	var autoload_handler := AutoloadHandler.new()
@@ -261,7 +263,7 @@ func _enter_tree() -> void:
 	var texture_handler := TextureHandler.new(get_undo_redo(), _connection)
 	var curve_handler := CurveHandler.new(get_undo_redo(), _connection)
 	var control_draw_recipe_handler := ControlDrawRecipeHandler.new(get_undo_redo())
-	_handlers = [editor_handler, scene_handler, node_handler, project_handler, client_handler, script_handler, resource_handler, filesystem_handler, signal_handler, autoload_handler, input_handler, test_handler, batch_handler, ui_handler, theme_handler, animation_handler, material_handler, particle_handler, camera_handler, audio_handler, physics_shape_handler, environment_handler, texture_handler, curve_handler, control_draw_recipe_handler]
+	_handlers = [editor_handler, scene_handler, node_handler, project_handler, client_handler, script_handler, resource_handler, api_handler, filesystem_handler, signal_handler, autoload_handler, input_handler, test_handler, batch_handler, ui_handler, theme_handler, animation_handler, material_handler, particle_handler, camera_handler, audio_handler, physics_shape_handler, environment_handler, texture_handler, curve_handler, control_draw_recipe_handler]
 
 	_dispatcher.register("get_editor_state", editor_handler.get_editor_state)
 	_dispatcher.register("get_scene_tree", scene_handler.get_scene_tree)
@@ -312,6 +314,7 @@ func _enter_tree() -> void:
 	_dispatcher.register("assign_resource", resource_handler.assign_resource)
 	_dispatcher.register("create_resource", resource_handler.create_resource)
 	_dispatcher.register("get_resource_info", resource_handler.get_resource_info)
+	_dispatcher.register("get_class_info", api_handler.get_class_info)
 	_dispatcher.register("read_file", filesystem_handler.read_file)
 	_dispatcher.register("write_file", filesystem_handler.write_file)
 	_dispatcher.register("reimport", filesystem_handler.reimport)

plugin/addons/godot_ai/tool_catalog.gd

@@ -30,6 +30,7 @@ const CORE_TOOLS := [
 ##   tools: flat list of tool names registered by this domain (non-core only)
 const DOMAINS := [
 	{"id": "animation", "label": "animation", "count": 2, "tools": ["animation_create", "animation_manage"]},
+	{"id": "api", "label": "api", "count": 1, "tools": ["api_manage"]},
 	{"id": "audio", "label": "audio", "count": 1, "tools": ["audio_manage"]},
 	{"id": "autoload", "label": "autoload", "count": 1, "tools": ["autoload_manage"]},
 	{"id": "batch", "label": "batch", "count": 1, "tools": ["batch_execute"]},