Plotnine MCP Server

Instructions

Implementation Reference

• src/plotnine_mcp/server.py:1074-1128 (handler)

  The handler function that executes the tool: processes optional category argument, calls helpers to retrieve palettes and categories, formats a detailed text response listing available palettes with previews, and returns as TextContent.

  async def list_color_palettes_handler(arguments: dict[str, Any]) -> list[TextContent]:
      """Handle list_color_palettes tool calls."""
      try:
          category = arguments.get("category")
  
          message = "Color Palettes\n" + "=" * 60 + "\n\n"
  
          if category:
              # Show specific category
              palettes = list_palettes(category)
              categories = palette_categories()
              desc = categories.get(category, "")
  
              message += f"Category: {category}\n"
              message += f"{desc}\n\n"
  
              for name, colors in sorted(palettes.items()):
                  # Remove category prefix for display
                  display_name = name.replace(f"{category}_", "")
                  message += f"• {display_name} ({len(colors)} colors)\n"
                  message += f"  Colors: {', '.join(colors[:5])}"
                  if len(colors) > 5:
                      message += f" ... and {len(colors) - 5} more"
                  message += "\n\n"
          else:
              # Show all categories
              categories = palette_categories()
              message += "Available Categories:\n\n"
  
              for cat, desc in categories.items():
                  palettes = list_palettes(cat)
                  message += f"• {cat} ({len(palettes)} palettes)\n"
                  message += f"  {desc}\n\n"
  
              message += "\n" + "=" * 60 + "\n"
              message += "Usage:\n"
              message += "- Use list_color_palettes with a category to see specific palettes\n"
              message += "- Add palettes to plots via the 'scales' parameter\n\n"
              message += "Example:\n"
              message += '  "scales": [{\n'
              message += '    "aesthetic": "color",\n'
              message += '    "type": "discrete",\n'
              message += '    "params": {"values": ["#E69F00", "#56B4E9", ...]}\n'
              message += '  }]'
  
          return [TextContent(type="text", text=message)]
  
      except Exception as e:
          return [
              TextContent(
                  type="text",
                  text=f"Error listing palettes: {str(e)}",
              )
          ]

• src/plotnine_mcp/server.py:476-498 (registration)

  Tool registration including name, description, and input schema defining optional 'category' parameter.

          Tool(
              name="list_color_palettes",
              description="""List available color palettes with preview colors.
  
  Palettes are organized by category:
  - colorblind_safe: Accessible palettes (Okabe-Ito, Tol)
  - scientific: Perceptually uniform (viridis, plasma, inferno, magma)
  - categorical: Distinct colors for categories
  - corporate: Professional business colors
  - sequential: Gradual scales for ordered data
  - diverging: Two-tone scales for data with midpoints
  
  Use these palettes by adding a scale configuration to your plot.""",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "category": {
                          "type": "string",
                          "description": "Optional category filter (colorblind_safe, scientific, categorical, corporate, sequential, diverging)",
                      },
                  },
              },
          ),

• src/plotnine_mcp/palettes.py:225-239 (helper)

  Core helper function that filters and returns the dictionary of available color palettes by category or all palettes from ALL_PALETTES.

  def list_palettes(category: str = None) -> dict[str, list[str]]:
      """
      List available color palettes.
  
      Args:
          category: Optional category filter (colorblind_safe, scientific, categorical, corporate, sequential, diverging)
  
      Returns:
          Dictionary of palette names to color lists
      """
      if category:
          prefix = f"{category}_"
          return {k: v for k, v in ALL_PALETTES.items() if k.startswith(prefix)}
      return ALL_PALETTES

• src/plotnine_mcp/palettes.py:241-255 (helper)

  Helper function returning palette categories and their descriptions, used for formatting the response.

  def palette_categories() -> dict[str, str]:
      """
      Get palette categories with descriptions.
  
      Returns:
          Dictionary mapping category names to descriptions
      """
      return {
          "colorblind_safe": "Accessible color schemes for colorblind viewers",
          "scientific": "Perceptually uniform palettes (viridis, plasma, inferno, magma)",
          "categorical": "Distinct colors for categorical data",
          "corporate": "Professional color schemes for business presentations",
          "sequential": "Gradual color scales for ordered data",
          "diverging": "Two-tone scales for data with a midpoint",
      }