create_event

Instructions

Implementation Reference

• fmod_mcp/tools/events.py:40-79 (handler)

  Core handler: creates an event, assigns it to a bank, optionally routes to a bus. Builds JS with _FOLDER_HELPER to ensure ancestor folders exist, then sends it to the FMOD Studio client.

  async def create_event(
      client: StudioClient,
      event_path: str,
      bank_path: str,
      bus_path: str | None = None,
  ) -> dict[str, Any]:
      """Create a new event, assign it to a bank, and optionally route to a bus.
  
      ``event_path`` is the full path including the event name, e.g.
      ``event:/bumpers/hit_soft``. Any missing ancestor folders are created.
      ``bank_path`` like ``bank:/pinball_sound_effects``. ``bus_path`` like
      ``bus:/SFX`` (optional).
      """
      if "/" not in event_path or not event_path.startswith("event:/"):
          raise ValueError("event_path must look like 'event:/folder/name'")
      parent_prefix, _, name = event_path.rpartition("/")
      # Ensure trailing slash on parent for the helper
      parent_with_slash = parent_prefix + "/"
      js = (
          _FOLDER_HELPER
          + f"""
          var parent = __mcp_ensureEventFolder({json.dumps(parent_with_slash)});
          var existing = studio.project.lookup({json.dumps(event_path)});
          if (existing) throw new Error("Event already exists: " + {json.dumps(event_path)});
          var evt = studio.project.create("Event");
          evt.name = {json.dumps(name)};
          evt.folder = parent;
          var bank = studio.project.lookup({json.dumps(bank_path)});
          if (!bank) throw new Error("Bank not found: " + {json.dumps(bank_path)});
          evt.relationships.banks.add(bank);
          var busPath = {json.dumps(bus_path) if bus_path else "null"};
          if (busPath) {{
              var bus = studio.project.lookup(busPath);
              if (!bus) throw new Error("Bus not found: " + busPath);
              try {{ evt.masterTrack.mixerGroup.output = bus; }} catch (e) {{ throw new Error("Could not route to bus: " + e.message); }}
          }}
          return {{ guid: evt.id, path: evt.getPath(), bank: bank.getPath(), bus: busPath }};
      """
      )
      return await client.eval(js)

• fmod_mcp/tools/events.py:14-37 (helper)

  JavaScript helper function __mcp_ensureEventFolder that walks/creates nested EventFolders under the master event folder.

  _FOLDER_HELPER = r"""
  function __mcp_ensureEventFolder(pathPrefix) {
      if (pathPrefix.indexOf("event:/") !== 0) throw new Error("Event path must start with 'event:/'");
      var remainder = pathPrefix.substring("event:/".length);
      if (remainder.charAt(remainder.length - 1) === "/") remainder = remainder.substring(0, remainder.length - 1);
      var segments = remainder.length > 0 ? remainder.split("/") : [];
      var cur = studio.project.workspace.masterEventFolder;
      if (!cur) throw new Error("Could not locate masterEventFolder");
      var builtPath = "event:/";
      for (var i = 0; i < segments.length; i++) {
          var seg = segments[i];
          if (!seg) continue;
          builtPath += seg + "/";
          var next = studio.project.lookup(builtPath);
          if (!next) {
              next = studio.project.create("EventFolder");
              next.name = seg;
              next.folder = cur;
          }
          cur = next;
      }
      return cur;
  }
  """

• fmod_mcp/server.py:74-84 (registration)

  FastMCP @mcp.tool() decorator that registers 'create_event' as an MCP tool, delegating to events.create_event.

  @mcp.tool()
  async def create_event(
      event_path: str,
      bank_path: str,
      bus_path: str | None = None,
  ) -> dict[str, Any]:
      """Create an empty event, assign it to a bank, optionally route to a bus.
  
      Missing parent folders in event_path are created automatically.
      """
      return await events.create_event(_studio(), event_path, bank_path, bus_path)

• fmod_mcp/server.py:74-84 (schema)

  Input schema defined via function parameters: event_path (str), bank_path (str), bus_path (str | None).

  @mcp.tool()
  async def create_event(
      event_path: str,
      bank_path: str,
      bus_path: str | None = None,
  ) -> dict[str, Any]:
      """Create an empty event, assign it to a bank, optionally route to a bus.
  
      Missing parent folders in event_path are created automatically.
      """
      return await events.create_event(_studio(), event_path, bank_path, bus_path)

• tests/test_server_registration.py:15-42 (helper)

  Test registration confirms 'create_event' is in the expected tool set.

      "create_event",
      "add_single_sound",
      "set_event_property",
      "assign_to_bank",
      "assign_to_bus",
      # effects
      "list_effect_types",
      "add_effect",
      "list_effects",
      "get_effect",
      "set_effect_param",
      "remove_effect",
      "bypass_effect",
      # project
      "save_project",
      "build_banks",
      # escape
      "run_js",
  }
  
  
  def test_all_tools_registered():
      tools = set(mcp._tool_manager._tools.keys())
      missing = EXPECTED_TOOLS - tools
      extra = tools - EXPECTED_TOOLS
      assert not missing, f"Missing tools: {missing}"
      assert not extra, f"Unexpected extra tools: {extra}"