Godot MCP

Instructions

Implementation Reference

• src/godot_mcp/godot.py:906-935 (handler)

  The handler method `get_project_structure` inside `GodotController` which executes the logic to retrieve the project structure.

  def get_project_structure(
      self,
      project_path: str,
      folder_path: str | None = None,
      max_depth: int = 6,
      include_hidden: bool = False,
  ) -> dict[str, Any]:
      project_dir = ensure_project_path(project_path)
      if max_depth < 0:
          raise GodotError("`max_depth` must be 0 or greater.")
  
      root_dir, root_resource_path = resolve_project_directory_path(project_dir, folder_path)
      entries, directory_count, file_count = _collect_project_entries(
          project_dir=project_dir,
          current_dir=root_dir,
          max_depth=max_depth,
          include_hidden=include_hidden,
      )
  
      return {
          "project_path": str(project_dir),
          "root_path": str(root_dir),
          "root_resource_path": root_resource_path,
          "max_depth": max_depth,
          "include_hidden": include_hidden,
          "directory_count": directory_count,
          "file_count": file_count,
          "entries": entries,
          "tree_text": _render_project_tree(root_resource_path, entries),
      }

• src/godot_mcp/server.py:124-159 (registration)

  The tool definition and handler registration for "godot_get_project_structure" in the GodotMcpServer class.

  ToolDefinition(
      name="godot_get_project_structure",
      description="Return a nested folder/file view of a Godot project or one of its subfolders.",
      input_schema={
          "type": "object",
          "properties": {
              "project_path": {
                  "type": "string",
                  "description": "Path to the Godot project directory or its project.godot file.",
              },
              "folder_path": {
                  "type": "string",
                  "description": "Optional absolute, relative, or res:// path for the subfolder to inspect. Defaults to the project root.",
              },
              "max_depth": {
                  "type": "integer",
                  "description": "Maximum folder depth to expand below the chosen root.",
                  "default": 6,
                  "minimum": 0,
              },
              "include_hidden": {
                  "type": "boolean",
                  "description": "Whether to include hidden files and folders such as `.godot` or `.godot-mcp`.",
                  "default": False,
              },
          },
          "required": ["project_path"],
          "additionalProperties": False,
      },
      handler=lambda args: self.controller.get_project_structure(
          project_path=args["project_path"],
          folder_path=args.get("folder_path"),
          max_depth=int(args.get("max_depth", 6)),
          include_hidden=bool(args.get("include_hidden", False)),
      ),
  ),