Plotnine MCP Server

Instructions

Implementation Reference

• src/plotnine_mcp/server.py:723-787 (handler)

  The main handler function for the 'preview_data' tool. Loads data from the provided data_source, generates a comprehensive preview including dataset shape, column types, sample rows, numeric statistics, and missing value summary, then returns it as TextContent.

  async def preview_data_handler(arguments: dict[str, Any]) -> list[TextContent]:
      """Handle preview_data tool calls."""
      try:
          # Parse data source
          data_source = DataSource(**arguments["data_source"])
          rows = arguments.get("rows", 5)
  
          # Load data
          try:
              data = load_data(data_source)
          except DataLoadError as e:
              return [
                  TextContent(
                      type="text",
                      text=f"Data loading error: {str(e)}\n\nPlease check:\n- File path or URL is correct\n- File format is supported\n- Data is properly formatted",
                  )
              ]
  
          # Build preview message
          message = "Data Preview\n" + "=" * 50 + "\n\n"
  
          # Dataset shape
          message += f"Shape: {data.shape[0]} rows × {data.shape[1]} columns\n\n"
  
          # Column information
          message += "Columns:\n"
          for col in data.columns:
              dtype = str(data[col].dtype)
              message += f"  - {col} ({dtype})\n"
          message += "\n"
  
          # First N rows
          message += f"First {min(rows, len(data))} rows:\n"
          message += "-" * 50 + "\n"
          preview_df = data.head(rows)
          message += preview_df.to_string(index=False) + "\n\n"
  
          # Basic statistics for numeric columns
          numeric_cols = data.select_dtypes(include=['number']).columns
          if len(numeric_cols) > 0:
              message += "Numeric Column Statistics:\n"
              message += "-" * 50 + "\n"
              stats_df = data[numeric_cols].describe()
              message += stats_df.to_string() + "\n\n"
  
          # Missing values
          missing = data.isnull().sum()
          if missing.sum() > 0:
              message += "Missing Values:\n"
              message += "-" * 50 + "\n"
              for col, count in missing[missing > 0].items():
                  pct = (count / len(data)) * 100
                  message += f"  - {col}: {count} ({pct:.1f}%)\n"
          else:
              message += "No missing values found.\n"
  
          return [TextContent(type="text", text=message)]
  
      except Exception as e:
          return [
              TextContent(
                  type="text",
                  text=f"Error previewing data: {str(e)}\n\nPlease check your data source configuration.",
              )
          ]

• src/plotnine_mcp/server.py:301-337 (schema)

  Input schema definition for the 'preview_data' tool, specifying data_source (file/url/inline with format) and optional rows parameter.

  inputSchema={
      "type": "object",
      "properties": {
          "data_source": {
              "type": "object",
              "description": "Data source configuration (file, URL, or inline data)",
              "properties": {
                  "type": {
                      "type": "string",
                      "enum": ["file", "url", "inline"],
                      "description": "Source type",
                  },
                  "path": {
                      "type": "string",
                      "description": "File path or URL (for file/url types)",
                  },
                  "data": {
                      "type": "array",
                      "items": {"type": "object"},
                      "description": "Inline data as array of objects (for inline type)",
                  },
                  "format": {
                      "type": "string",
                      "enum": ["csv", "json", "parquet", "excel"],
                      "description": "Data format (auto-detected if not specified)",
                  },
              },
              "required": ["type"],
          },
          "rows": {
              "type": "integer",
              "default": 5,
              "description": "Number of rows to preview (default: 5)",
          },
      },
      "required": ["data_source"],
  },

• src/plotnine_mcp/server.py:289-338 (registration)

  Registration of the 'preview_data' tool in the list_tools() function, including name, description, and schema.

          Tool(
              name="preview_data",
              description="""Preview and inspect data before creating plots.
  
  Returns a comprehensive summary including:
  - Dataset shape (rows and columns)
  - Column names and data types
  - First few rows of data
  - Basic statistics for numeric columns
  - Missing value counts
  
  This helps verify data loaded correctly and understand its structure.""",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "data_source": {
                          "type": "object",
                          "description": "Data source configuration (file, URL, or inline data)",
                          "properties": {
                              "type": {
                                  "type": "string",
                                  "enum": ["file", "url", "inline"],
                                  "description": "Source type",
                              },
                              "path": {
                                  "type": "string",
                                  "description": "File path or URL (for file/url types)",
                              },
                              "data": {
                                  "type": "array",
                                  "items": {"type": "object"},
                                  "description": "Inline data as array of objects (for inline type)",
                              },
                              "format": {
                                  "type": "string",
                                  "enum": ["csv", "json", "parquet", "excel"],
                                  "description": "Data format (auto-detected if not specified)",
                              },
                          },
                          "required": ["type"],
                      },
                      "rows": {
                          "type": "integer",
                          "default": 5,
                          "description": "Number of rows to preview (default: 5)",
                      },
                  },
                  "required": ["data_source"],
              },
          ),

• src/plotnine_mcp/server.py:533-534 (registration)

  Dispatch/registration logic in the call_tool handler that routes 'preview_data' calls to the preview_data_handler function.

  elif name == "preview_data":
      return await preview_data_handler(arguments)