VisiData MCP Server

Instructions

Implementation Reference

• src/visidata_mcp/server.py:687-765 (handler)

  The main handler function that creates a correlation heatmap from numeric columns in a dataset. It loads data using pandas, selects numeric columns (or user-specified columns), calculates the correlation matrix, and creates a visualization using seaborn with matplotlib. The function saves the heatmap to the specified output path and returns metadata about the created visualization.

  @mcp.tool()
  def create_correlation_heatmap(file_path: str, output_path: str, 
                                columns: Optional[List[str]] = None) -> str:
      """
      Create a correlation heatmap from numeric columns in the dataset.
      
      Args:
          file_path: Path to the data file
          output_path: Path where to save the heatmap image
          columns: Optional list of specific columns to include (if None, uses all numeric columns)
      
      Returns:
          Information about the created heatmap
      """
      try:
          if not VISUALIZATION_AVAILABLE:
              return f"Error: {VISUALIZATION_ERROR}"
              
          import pandas as pd
          from pathlib import Path
          
          # Load the data
          file_extension = Path(file_path).suffix.lower()
          if file_extension == '.csv':
              df = pd.read_csv(file_path)
          elif file_extension == '.json':
              df = pd.read_json(file_path)
          elif file_extension in ['.xlsx', '.xls']:
              df = pd.read_excel(file_path)
          elif file_extension == '.tsv':
              df = pd.read_csv(file_path, sep='\t')
          else:
              df = pd.read_csv(file_path)
          
          # Select numeric columns
          if columns:
              # Validate specified columns exist
              missing_cols = [col for col in columns if col not in df.columns]
              if missing_cols:
                  return f"Error: Columns not found: {missing_cols}"
              numeric_df = df[columns].select_dtypes(include=['number'])
          else:
              numeric_df = df.select_dtypes(include=['number'])
          
          if numeric_df.empty:
              return "Error: No numeric columns found for correlation analysis"
          
          # Calculate correlation matrix
          correlation_matrix = numeric_df.corr()
          
          # Create the heatmap
          plt.figure(figsize=(10, 8))
          sns.heatmap(correlation_matrix, 
                     annot=True, 
                     cmap='coolwarm', 
                     center=0,
                     fmt='.2f',
                     square=True,
                     linewidths=0.5)
          
          plt.title('Correlation Heatmap')
          plt.tight_layout()
          
          # Save the plot
          plt.savefig(output_path, dpi=300, bbox_inches='tight')
          plt.close()
          
          result = {
              "heatmap_created": True,
              "columns_analyzed": list(correlation_matrix.columns),
              "total_correlations": len(correlation_matrix.columns) ** 2,
              "output_file": output_path,
              "file_size": Path(output_path).stat().st_size if Path(output_path).exists() else 0
          }
          
          return json.dumps(result, indent=2)
          
      except Exception as e:
          return f"Error creating correlation heatmap: {str(e)}\n{traceback.format_exc()}"

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

  The tool is registered as an MCP tool using the @mcp.tool() decorator on line 687, which exposes the create_correlation_heatmap function to the MCP server.

  @mcp.tool()
  def create_correlation_heatmap(file_path: str, output_path: str, 
                                columns: Optional[List[str]] = None) -> str: