# Plotly MCP Server - Implementation Plan

## Project Overview
**Goal**: Graph Objects-only Plotly MCP server for Cursor  
**Output**: HTML visualizations from natural language  
**Control**: Minute-level customization of all chart elements  
**Scope**: Complete coverage of 50+ Plotly trace types  

## Phase 1 Status ✅

**Foundation Complete:**
- ✅ MCP server with FastMCP framework (SDK 1.2.0+)
- ✅ Project structure for 49 trace types
- ✅ 5 basic trace builders (scatter, bar, line, pie, histogram)
- ✅ Figure assembly system
- ✅ Layout controllers (axes, styling)
- ✅ Sample data generation for testing
- ✅ Cursor integration ready

## Quick Start

### 1. Install Dependencies

**With UV (recommended):**
```bash
# Install UV if you havent already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Setup project
cd /Users/arshad/Desktop/personal/code/plotly-mcp-claude
uv sync
```

**With pip:**
```bash
pip install -r requirements.txt
```

### 2. Run the MCP Server
```bash
cd src
python server.py
```

### 3. Add to Cursor MCP Settings
Add this to your Cursor MCP configuration:
```json
{
  "mcpServers": {
    "plotly-mcp": {
      "command": "python",
      "args": ["/Users/arshad/Desktop/personal/code/plotly-mcp-claude/src/server.py"]
    }
  }
}
```

## Available Tools (Phase 1)

### Basic Trace Builders
1. **create_scatter_plot** - Scatter plots with markers, lines, or both
2. **create_bar_chart** - Vertical/horizontal bar charts with text labels
3. **create_line_chart** - Line charts with styling and fill options
4. **create_pie_chart** - Pie/donut charts with custom colors
5. **create_histogram** - Histograms with binning and normalization

### Utility Tools
6. **create_multi_trace_figure** - Initialize figures for multiple traces
7. **generate_sample_data** - Create test data (linear, sine, random, categories)

## Usage Examples

### Scatter Plot
```python
create_scatter_plot(
    x_data=[1, 2, 3, 4, 5],
    y_data=[2, 4, 1, 5, 3],
    colors="red",
    sizes=15,
    mode="markers+lines",
    name="My Data"
)
```

### Bar Chart
```python
create_bar_chart(
    x_data=["A", "B", "C", "D"],
    y_data=[20, 14, 23, 25],
    colors="blue",
    orientation="v",
    text=["20", "14", "23", "25"],
    name="Sales Data"
)
```

### Pie Chart
```python
create_pie_chart(
    labels=["Apple", "Orange", "Banana"],
    values=[30, 25, 45],
    hole=0.3,  # Donut chart
    textinfo="label+percent"
)
```

### Generate Test Data
```python
generate_sample_data(
    data_type="sine",
    size=100,
    noise=0.1
)
```

## Architecture

```
plotly-mcp-claude/
├── src/
│   ├── server.py              # Main MCP server (FastMCP)
│   ├── traces/                # All trace builders (5/49 complete)
│   │   └── basic/            # Phase 1: scatter, bar, line, pie, histogram
│   ├── layouts/              # Layout controllers
│   │   ├── axes.py           # X/Y/Z axis configuration
│   │   └── styling.py        # Colors, fonts, margins, legends
│   ├── assembly/             # Figure building
│   │   └── builder.py        # Combine traces + layout
│   └── [themes/, nlp/]       # Future phases
├── data/                     # Sample datasets (future)
├── examples/                 # Usage examples (future)
├── tests/                    # Unit tests (future)
├── requirements.txt          # Python dependencies
├── pyproject.toml           # Project configuration
└── README.md                # This file
```

## Complete Plotly Trace Types (Planned)

### Phase 1 ✅ (5/49)
- **Basic Charts**: scatter ✅, bar ✅, line ✅, pie ✅, histogram ✅

### Phase 2 📋 (15 more types)
- **Statistical Charts**: box, violin, heatmap, contour, splom, parcoords, parcats, histogram2d
- **3D Charts**: scatter3d, surface, mesh3d, volume, isosurface, cone, streamtube

### Phase 3 📋 (15 more types)  
- **Geographic Charts**: choropleth, choroplethmap, choroplethmapbox, scattergeo, scattermap, scattermapbox, densitymap, densitymapbox
- **Financial Charts**: candlestick, ohlc, waterfall
- **Hierarchical Charts**: treemap, sunburst, icicle, sankey

### Phase 4 📋 (14 more types)
- **Polar & Coordinates**: scatterpolar, scatterpolargl, scattersmith, scatterternary, carpet, scattercarpet
- **Specialized Charts**: funnel, funnelarea, indicator, image, table
- **Additional**: barpolar, histogram2dcontour, contourcarpet

**Total: 49 trace builders planned**

## Implementation Timeline

- **Phase 1** ✅ Foundation (5 basic traces) - **COMPLETE**
- **Phase 2** 🚧 Statistical & 3D traces (15 more types)
- **Phase 3** 📋 Geographic & Financial traces (15 more types)  
- **Phase 4** 📋 Remaining traces & complete layout (14 more types)
- **Phase 5** 📋 Theming system (sci-fi, corporate, dark themes)
- **Phase 6** 📋 Natural language interface

## Technical Details

### MCP Server Features
- Built with **MCP Python SDK 1.2.0+**
- **FastMCP** framework for easy tool definition
- **Async/await** pattern throughout
- **Type hints** for all parameters
- **Error handling** with detailed messages
- **Logging** for debugging

### Chart Features
- **HTML output** with embedded Plotly.js
- **Interactive** charts (zoom, pan, hover)
- **Responsive design** (800x600 default)
- **Professional styling** (plotly_white theme)
- **Full customization** of all visual elements

### Testing
Each trace type returns complete HTML that can be:
- Viewed directly in browser  
- Embedded in applications
- Displayed in Cursor/Claude interface

## Next Steps for Phase 2

Ready to add Statistical & 3D traces:
- **Box plots** - quartile visualization
- **Violin plots** - distribution shape
- **Heatmaps** - 2D data correlation
- **3D scatter** - three-dimensional points
- **Surface plots** - 3D mathematical functions

## Contributing

The modular architecture makes it easy to add new trace types:

1. Create trace builder in `src/traces/{category}/`
2. Add tool decorator in `src/server.py`
3. Test with sample data
4. Update documentation

## Requirements

- **Python 3.10+**
- **MCP Python SDK 1.2.0+**
- **Plotly 5.0+**
- **Modern browser** for viewing charts

---

*Phase 1 Complete - 5/49 trace types implemented*
*Ready for Phase 2: Statistical & 3D visualization*

**Built with ❤️ for the Claude ecosystem**