get_exchanges

Instructions

Implementation Reference

• src/mcp_massive/server.py:687-704 (handler)

  The primary handler function for the 'get_exchanges' MCP tool. It is registered via the @poly_mcp.tool decorator, validates inputs via type hints, calls the underlying massive_client.get_exchanges method with optional asset_class, locale, and params, processes the raw binary response by decoding and converting to CSV using json_to_csv helper, and returns the formatted string or an error message.

  @poly_mcp.tool(annotations=ToolAnnotations(readOnlyHint=True))
  async def get_exchanges(
      asset_class: Optional[str] = None,
      locale: Optional[str] = None,
      params: Optional[Dict[str, Any]] = None,
  ) -> str:
      """
      List exchanges known by Massive.com.
      """
      try:
          results = massive_client.get_exchanges(
              asset_class=asset_class, locale=locale, params=params, raw=True
          )
  
          return json_to_csv(results.data.decode("utf-8"))
      except Exception as e:
          return f"Error: {e}"

• src/mcp_massive/formatters.py:7-74 (helper)

  Supporting utility function json_to_csv that flattens nested JSON responses from the Massive API (handling 'results' or 'last' keys, lists, dicts) into a CSV string with headers, used by get_exchanges and all other tools to format output.

  def json_to_csv(json_input: str | dict) -> str:
      """
      Convert JSON to flattened CSV format.
  
      Args:
          json_input: JSON string or dict. If the JSON has a 'results' key containing
                     a list, it will be extracted. Otherwise, the entire structure
                     will be wrapped in a list for processing.
  
      Returns:
          CSV string with headers and flattened rows
      """
      # Parse JSON if it's a string
      if isinstance(json_input, str):
          try:
              data = json.loads(json_input)
          except json.JSONDecodeError:
              # If JSON parsing fails, return empty CSV
              return ""
      else:
          data = json_input
  
      if isinstance(data, dict) and "results" in data:
          results_value = data["results"]
          # Handle both list and single object responses
          if isinstance(results_value, list):
              records = results_value
          elif isinstance(results_value, dict):
              # Single object response (e.g., get_last_trade returns results as object)
              records = [results_value]
          else:
              records = [results_value]
      elif isinstance(data, dict) and "last" in data:
          # Handle responses with "last" key (e.g., get_last_trade, get_last_quote)
          records = [data["last"]] if isinstance(data["last"], dict) else [data]
      elif isinstance(data, list):
          records = data
      else:
          records = [data]
  
      # Only flatten dict records, skip non-dict items
      flattened_records = []
      for record in records:
          if isinstance(record, dict):
              flattened_records.append(_flatten_dict(record))
          else:
              # If it's not a dict, wrap it in a dict with a 'value' key
              flattened_records.append({"value": str(record)})
  
      if not flattened_records:
          return ""
  
      # Get all unique keys across all records (for consistent column ordering)
      all_keys = []
      seen = set()
      for record in flattened_records:
          if isinstance(record, dict):
              for key in record.keys():
                  if key not in seen:
                      all_keys.append(key)
                      seen.add(key)
  
      output = io.StringIO()
      writer = csv.DictWriter(output, fieldnames=all_keys, lineterminator="\n")
      writer.writeheader()
      writer.writerows(flattened_records)
  
      return output.getvalue()

• src/mcp_massive/server.py:687-687 (registration)

  The @poly_mcp.tool decorator registers the get_exchanges function as an MCP tool with readOnlyHint=True annotation.

  @poly_mcp.tool(annotations=ToolAnnotations(readOnlyHint=True))