set_dashcard_parameter_mappings

Instructions

Implementation Reference

• server.py:1182-1305 (handler)

  The main handler/implementation of the set_dashcard_parameter_mappings tool. It wires dashboard parameters to card template tags on specific dashcards by grouping mappings by dashcard_id, fetching the current dashboard state, updating parameter_mappings on each target dashcard (with optional replace mode), and sending the updated dashcards array back to the Metabase API.

  async def set_dashcard_parameter_mappings(
      dashboard_id: int,
      mappings: list[dict[str, Any]],
      ctx: Context,
      replace: bool = False,
  ) -> dict[str, Any]:
      """
      Wire dashboard parameters to card template tags on specific dashcards.
  
      Each mapping entry must include:
        - dashcard_id: the dashcard to target (from get_dashboard_cards)
        - parameter_id: the dashboard parameter's `id` (set via update_dashboard)
        - template_tag: the tag name used in the card's SQL (e.g. "start_date")
  
      Optional per-entry fields:
        - kind: "variable" (default) for plain `{{tag}}` vars, or "dimension" for
          field-filter tags. Produces the correct `target` shape.
        - card_id: overrides the dashcard's own card_id in the mapping (rare —
          needed for series cards).
        - target: raw Metabase `target` array; if provided, used verbatim and
          overrides `kind`/`template_tag`.
  
      Existing parameter_mappings on each touched dashcard are preserved and
      extended, unless `replace=True` (in which case the mappings for each
      touched dashcard are fully replaced by the entries provided here).
      Dashcards not referenced in `mappings` are left untouched.
  
      Args:
          dashboard_id: The ID of the dashboard.
          mappings: List of mapping entries as described above.
          replace: If True, replace parameter_mappings on touched dashcards
              instead of appending.
  
      Returns:
          The updated dashboard object.
      """
      if not mappings:
          raise ToolError("`mappings` must contain at least one entry.")
  
      grouped: dict[int, list[dict[str, Any]]] = {}
      for idx, entry in enumerate(mappings):
          dc_id = entry.get("dashcard_id")
          param_id = entry.get("parameter_id")
          if dc_id is None or param_id is None:
              raise ToolError(
                  f"mappings[{idx}] must include 'dashcard_id' and 'parameter_id'."
              )
          raw_target = entry.get("target")
          if raw_target is None:
              tag = entry.get("template_tag")
              if not tag:
                  raise ToolError(
                      f"mappings[{idx}] must include 'template_tag' or 'target'."
                  )
              kind = entry.get("kind", "variable")
              if kind not in ("variable", "dimension"):
                  raise ToolError(
                      f"mappings[{idx}] has invalid kind '{kind}'; use 'variable' or 'dimension'."
                  )
              raw_target = [kind, ["template-tag", tag]]
          grouped.setdefault(int(dc_id), []).append(
              {
                  "parameter_id": param_id,
                  "card_id": entry.get("card_id"),
                  "target": raw_target,
              }
          )
  
      try:
          await ctx.info(
              f"Updating parameter mappings on {len(grouped)} dashcard(s) of dashboard {dashboard_id}"
          )
          dashboard = await metabase_client.request("GET", f"/dashboard/{dashboard_id}")
          existing_dashcards = dashboard.get("dashcards", dashboard.get("ordered_cards", []))
  
          existing_ids = {dc.get("id") for dc in existing_dashcards}
          unknown = [dc_id for dc_id in grouped if dc_id not in existing_ids]
          if unknown:
              raise ToolError(
                  f"Dashcard(s) {unknown} not found on dashboard {dashboard_id}."
              )
  
          dashcards = []
          for dc in existing_dashcards:
              entry = {
                  "id": dc["id"],
                  "card_id": dc.get("card_id"),
                  "row": dc.get("row"),
                  "col": dc.get("col"),
                  "size_x": dc.get("size_x"),
                  "size_y": dc.get("size_y"),
                  "parameter_mappings": list(dc.get("parameter_mappings") or []),
                  "visualization_settings": dc.get("visualization_settings") or {},
                  "inline_parameters": list(dc.get("inline_parameters") or []),
              }
              new_for_dc = grouped.get(dc.get("id"))
              if new_for_dc is not None:
                  filled = [
                      {
                          "parameter_id": m["parameter_id"],
                          "card_id": m["card_id"] if m["card_id"] is not None else dc.get("card_id"),
                          "target": m["target"],
                      }
                      for m in new_for_dc
                  ]
                  if replace:
                      entry["parameter_mappings"] = filled
                  else:
                      entry["parameter_mappings"].extend(filled)
              dashcards.append(entry)
  
          result = await metabase_client.request(
              "PUT", f"/dashboard/{dashboard_id}", json={"dashcards": dashcards}
          )
          await ctx.info(
              f"Successfully updated parameter mappings on dashboard {dashboard_id}"
          )
          return result
      except ToolError:
          raise
      except Exception as e:
          error_msg = f"Error updating parameter mappings on dashboard {dashboard_id}: {e}"
          await ctx.error(error_msg)
          raise ToolError(error_msg) from e

• server.py:1181-1181 (registration)

  The @mcp.tool decorator that registers set_dashcard_parameter_mappings as a FastMCP tool.

  @mcp.tool