Zaturn

Instructions

Implementation Reference

• zaturn/tools/visualizations.py:231-267 (handler)

  Core handler function for the 'bar_plot' tool. Runs an SQL query on a data source to fetch data, creates a bar plot using plotly.express with specified x, y columns, optional color and orientation, encodes the plot as a base64 PNG image, and returns it or an error string.
  def bar_plot(self, source_id: Annotated[ str, Field(description='The data source to run the query on') ], query: Annotated[ str, Field(description='SQL query to run on the data source') ], x: Annotated[ str, Field(description='Column name from SQL result to use for x-axis') ], y: Annotated[ str, Field(description='Column name from SQL result to use for y-axis') ], color: Annotated[ str | None, Field(description='Optional column name from SQL result to use as a 3rd dimension by splitting each bar into colored sections') ] = None, orientation: Annotated[ str, Field(description="Orientation of the box plot, use 'v' for vertical (default) and 'h' for horizontal. Be mindful of choosing the correct X and Y columns as per orientation") ] = 'v', ) -> str | ImageContent: """ Run query against specified source and make a bar plot using result For both csv and parquet sources, use DuckDB SQL syntax Use 'CSV' as the table name in the SQL query for csv sources. Use 'PARQUET' as the table name in the SQL query for parquet sources. This will return an image of the plot """ try: df = self._get_df_from_source(source_id, query) fig = px.bar(df, x=x, y=y, color=color, orientation=orientation) fig.update_xaxes(autotickangles=[0, 45, 60, 90]) return _fig_to_image(fig) except Exception as e: return str(e)
• zaturn/mcp/__init__.py:89-95 (registration)

  MCP server registration: Instantiates ZaturnTools and registers all its tools (including bar_plot) using FastMCP.add_tool.
  def ZaturnMCP(sources): zaturn_tools = ZaturnTools(sources) zaturn_mcp = FastMCP() for tool_function in zaturn_tools.tools: zaturn_mcp.add_tool(Tool.from_function(tool_function)) return zaturn_mcp
• zaturn/tools/__init__.py:6-10 (registration)

  ZaturnTools class aggregates tools from core and visualizations.Visualizations (which includes bar_plot).
  def __init__(self, data_sources): self.tools = [ *core.Core(data_sources).tools, *visualizations.Visualizations(data_sources).tools, ]
• zaturn/tools/visualizations.py:27-40 (registration)

  Visualizations class registers bar_plot in its self.tools list.
  def __init__(self, data_sources): self.data_sources = data_sources self.tools = [ self.scatter_plot, self.line_plot, self.histogram, self.strip_plot, self.box_plot, self.bar_plot, self.density_heatmap, self.polar_scatter, self.polar_line, ]
• zaturn/tools/visualizations.py:13-22 (helper)

  Helper function to convert plotly figure to MCP ImageContent (base64 PNG), used by bar_plot and other visualization tools.
  def _fig_to_image(fig): fig_encoded = b64encode(fig.to_image(format='png')).decode() img_b64 = "data:image/png;base64," + fig_encoded return ImageContent( type = 'image', data = fig_encoded, mimeType = 'image/png', annotations = None, )