list_effects

Instructions

Implementation Reference

• fmod_mcp/tools/effects.py:189-207 (handler)

  Core implementation of list_effects: builds a JS snippet that iterates over the target's effectChain, filters out the built-in MixerBusFader, and returns guid/type/position/bypass for each effect.

  async def list_effects(client: StudioClient, target_path: str) -> list[dict[str, Any]]:
      """List every effect on the target's chain (skips the built-in bus fader)."""
      chain_expr = _chain_expr(target_path)
      js = f"""
          var chain = {chain_expr};
          var out = [];
          for (var i = 0; i < chain.effects.length; i++) {{
              var e = chain.effects[i];
              if (e.entity === "MixerBusFader") continue;
              out.push({{
                  guid: e.id,
                  type: e.entity,
                  position: i,
                  bypass: !!e.bypass
              }});
          }}
          return out;
      """
      return await client.eval(js)

• fmod_mcp/server.py:151-154 (registration)

  MCP tool registration using @mcp.tool() decorator, delegates to effects.list_effects() with the lazy singleton StudioClient.

  @mcp.tool()
  async def list_effects(target_path: str) -> list[dict[str, Any]]:
      """List effects on a bus or event-track chain (excludes the built-in fader)."""
      return await effects.list_effects(_studio(), target_path)

• fmod_mcp/tools/effects.py:189-207 (schema)

  The function signature defines the input schema: target_path (str) -> list[dict[str, Any]]. The output dicts contain guid, type, position, bypass.

  async def list_effects(client: StudioClient, target_path: str) -> list[dict[str, Any]]:
      """List every effect on the target's chain (skips the built-in bus fader)."""
      chain_expr = _chain_expr(target_path)
      js = f"""
          var chain = {chain_expr};
          var out = [];
          for (var i = 0; i < chain.effects.length; i++) {{
              var e = chain.effects[i];
              if (e.entity === "MixerBusFader") continue;
              out.push({{
                  guid: e.id,
                  type: e.entity,
                  position: i,
                  bypass: !!e.bypass
              }});
          }}
          return out;
      """
      return await client.eval(js)

• fmod_mcp/tools/effects.py:53-96 (helper)

  _split_target and _chain_expr helpers: parse target_path into canonical path + track selector, and generate a JS expression that resolves to the target's effectChain. Used by list_effects to build the JS query.

  def _split_target(target_path: str) -> tuple[str, str]:
      """Returns ``(canonical_path, track_selector)`` where track_selector is
      ``""`` for a bus, or ``master``/``<index>``/``<name>`` for an event."""
      if "#track=" in target_path:
          path_part, _, track_part = target_path.partition("#track=")
          return path_part, track_part
      return target_path, "master" if target_path.startswith("event:/") else ""
  
  
  def _chain_expr(target_path: str) -> str:
      """Returns a JS expression that evaluates to the target's effect chain."""
      canonical, track = _split_target(target_path)
      canonical_json = json.dumps(canonical)
      if canonical.startswith("bus:/"):
          return (
              "(function(){"
              f"var bus=studio.project.lookup({canonical_json});"
              f'if(!bus)throw new Error("Bus not found: "+{canonical_json});'
              'if(!bus.effectChain)throw new Error("Object has no effectChain");'
              "return bus.effectChain;"
              "})()"
          )
      if canonical.startswith("event:/"):
          track_json = json.dumps(track)
          return (
              "(function(){"
              f"var evt=studio.project.lookup({canonical_json});"
              f'if(!evt)throw new Error("Event not found: "+{canonical_json});'
              f"var sel={track_json};"
              "var track=null;"
              'if(sel==="master")track=evt.masterTrack;'
              "else{var idx=parseInt(sel,10);"
              "if(!isNaN(idx)&&String(idx)===sel){"
              'if(!evt.groupTracks||idx<0||idx>=evt.groupTracks.length)throw new Error("Group track index out of range: "+sel);'
              "track=evt.groupTracks[idx];"
              "}else{"
              "if(evt.groupTracks)for(var i=0;i<evt.groupTracks.length;i++){"
              "if(evt.groupTracks[i].name===sel){track=evt.groupTracks[i];break;}}"
              'if(!track)throw new Error("Group track not found by name: "+sel);}}'
              'if(!track.mixerGroup||!track.mixerGroup.effectChain)throw new Error("Track has no effectChain");'
              "return track.mixerGroup.effectChain;"
              "})()"
          )
      raise ValueError(f"target_path must start with 'bus:/' or 'event:/', got: {target_path!r}")

• tests/test_server_registration.py:6-33 (registration)

  Test confirming 'list_effects' is registered as an expected tool in the MCP server.

  EXPECTED_TOOLS = {
      # discovery
      "ping",
      "list_banks",
      "list_events",
      "list_buses",
      "get_event",
      # audio + events
      "import_audio",
      "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",
  }