ML Research MCP

# ML Research MCP A comprehensive Model Context Protocol (MCP) server providing research productivity tools for machine learning researchers and developers. ## Overview ML Research MCP is an extensible platform that provides AI assistants with powerful tools for scientific research workflows. Built on the Model Context Protocol, it enables seamless integration with AI applications like Claude Desktop to automate and enhance various research tasks. **Current Status**: Phase 1 - Data Visualization **Roadmap**: Image generation, presentation tools, literature management, and more ## Vision & Roadmap This project aims to be a comprehensive research assistant covering the entire ML research lifecycle: ### ✅ Phase 1: Data Visualization (Current) - **Scientific plotting** with publication-quality output - **Statistical analysis** visualizations - **2D data representations** (heatmaps, contours) - Multiple export formats (PNG, PDF, SVG) ### 🚧 Phase 2: Image & Figure Generation (Planned) - **AI-powered figure generation** using diffusion models - **Diagram creation** for architecture illustrations - **Chart enhancement** with intelligent styling - **Multi-panel figure composition** ### 🚧 Phase 3: Presentation Tools (Planned) - **Slide generation** from research content - **Poster creation** for conferences - **Automated layout** optimization - **Template management** for institutional branding ### 🚧 Phase 4: Research Management (Future) - **Literature search** and summarization - **Citation management** and formatting - **Experiment tracking** and versioning - **Collaboration tools** for team projects ## Current Features (Phase 1) ### Data Visualization Tools #### Basic Plots - `plot_line` - Time series and continuous data visualization - `plot_scatter` - Multi-dimensional scatter plots with size/color mapping - `plot_bar` - Categorical comparisons (vertical/horizontal) #### Statistical Visualizations - `plot_histogram` - Distribution analysis with density estimation - `plot_box` - Statistical summaries and outlier detection - `plot_violin` - Detailed distribution shapes with KDE #### 2D Representations - `plot_heatmap` - Matrix visualization with annotations - `plot_contour` - 3D data in 2D with contour lines - `plot_pcolormesh` - Fast pseudocolor plots for large datasets ### Technical Highlights - **Publication-quality output** via [UltraPlot](https://ultraplot.readthedocs.io/) - **High-performance data handling** with [Polars](https://pola.rs/) - **Flexible input** from CSV, JSON files or direct data - **Vector & raster formats** (PDF, SVG, PNG) - **Type-safe** with comprehensive validation - **Well-tested** with 48 passing tests ## Requirements - Python 3.12+ - [uv](https://docs.astral.sh/uv/) package manager - MCP-compatible client (Claude Desktop, VSCode, etc.) ## Installation ### Quick Start with Claude Code Add the server to Claude Code with a single command: ```bash claude mcp add-json "ml-research" \ '{"command":"uvx","args":["--from","git+https://github.com/nishide-dev/ml-research-mcp","ml-research-mcp"]}' ``` Verify installation: ```bash claude mcp list ``` ### Manual Installation for MCP Clients Add to your MCP client configuration (e.g., `~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "ml-research": { "command": "uvx", "args": [ "--from", "git+https://github.com/nishide-dev/ml-research-mcp", "ml-research-mcp" ] } } } ``` ### Direct Execution with uvx Run the server directly without installation: ```bash # From GitHub (recommended) uvx --from "git+https://github.com/nishide-dev/ml-research-mcp" ml-research-mcp # From local directory (for development) cd /path/to/ml-research-mcp uvx --from . ml-research-mcp ``` ### For Developers Clone and set up development environment: ```bash git clone https://github.com/nishide-dev/ml-research-mcp.git cd ml-research-mcp uv sync # Run in development mode uv run ml-research-mcp ``` ## Quick Start ### Using with Claude Desktop After installation, you can ask Claude: > "Create a line plot showing temperature over time from experiment.csv" > "Generate a heatmap of the correlation matrix and save as PDF" > "Plot a scatter chart with x=[1,2,3,4], y=[2,4,6,8], sized by [10,20,30,40]" ### Using as a Library ```python from ml_research_mcp.tools.plot_basic import plot_line # Generate publication-quality plot image = plot_line( x=[1, 2, 3, 4, 5], y=[1, 4, 9, 16, 25], style={"title": "Quadratic Function", "xlabel": "X", "ylabel": "Y²"}, output={"format": "pdf", "width": 20, "height": 15, "dpi": 300} ) # Save to file with open("plot.pdf", "wb") as f: f.write(image) ``` ## Example Gallery Real examples generated with ML Research MCP: | Query | Result | |-------|--------| | **Line Plot**<br>"Create a line plot showing temperature over time with x=[1,2,3,4,5,6] and y=[2,4,3,5,6,7]" | <img src="assets/example_line.png" width="400" alt="Line Plot"> | | **Scatter Plot**<br>"Make a scatter plot with color and size mapping using plasma colormap" | <img src="assets/example_scatter.png" width="400" alt="Scatter Plot"> | | **Bar Chart**<br>"Generate a bar chart comparing performance across categories A through E" | <img src="assets/example_bar.png" width="400" alt="Bar Chart"> | | **Histogram**<br>"Create a histogram with density normalization for distribution analysis" | <img src="assets/example_histogram.png" width="400" alt="Histogram"> | | **Violin Plot**<br>"Make a violin plot comparing Control vs Treatment groups" | <img src="assets/example_violin.png" width="400" alt="Violin Plot"> | | **Heatmap**<br>"Generate an annotated correlation matrix heatmap using RdBu colormap" | <img src="assets/example_heatmap.png" width="400" alt="Heatmap"> | All plots generated with publication-quality settings (150 DPI, customizable dimensions). ## Documentation ### Visualization Tools (Phase 1) <details> <summary><b>Basic Plotting Tools</b></summary> #### plot_line ```python plot_line( x: str | list[float], y: str | list[float], data_input: dict | None = None, style: dict | None = None, output: dict | None = None ) -> Image | bytes ``` **Parameters:** - `x`, `y`: Column names (if using file) or data arrays - `data_input`: `{"file_path": "data.csv"}` or `{"data": {...}}` - `style`: `{"title": "...", "xlabel": "...", "ylabel": "...", "grid": true}` - `output`: `{"format": "png/pdf/svg", "width": 15, "height": 10, "dpi": 300}` #### plot_scatter Additional parameters: - `size`: Point sizes (column name, array, or constant) - `color`: Point colors (column name or array) #### plot_bar Additional parameters: - `orientation`: `"vertical"` or `"horizontal"` </details> <details> <summary><b>Statistical Tools</b></summary> #### plot_histogram ```python plot_histogram( data: str | list[float], bins: int = 30, density: bool = False, ... ) ``` #### plot_box ```python plot_box( data: str | list[list[float]], labels: list[str] | None = None, ... ) ``` #### plot_violin Similar to `plot_box` with kernel density estimation. </details> <details> <summary><b>2D Visualization Tools</b></summary> #### plot_heatmap ```python plot_heatmap( data: str | list[list[float]], x_labels: list[str] | None = None, y_labels: list[str] | None = None, annotate: bool = False, ... ) ``` #### plot_contour ```python plot_contour( x: str | list[float], y: str | list[float], z: str | list[list[float]], levels: int = 10, filled: bool = True, ... ) ``` #### plot_pcolormesh Fast alternative to contour plots with shading options. </details> ### Future Tools (Planned) Documentation will be added as features are implemented. ## Development ### Project Structure ``` ml-research-mcp/ ├── src/ml_research_mcp/ │ ├── server.py # MCP server entry point │ ├── data/ # Data I/O modules │ ├── plotting/ # Phase 1: Visualization │ ├── tools/ # MCP tool definitions │ │ ├── plot_basic.py │ │ ├── plot_statistical.py │ │ └── plot_2d.py │ ├── generation/ # Phase 2: Image generation (planned) │ ├── presentation/ # Phase 3: Slides/posters (planned) │ └── research/ # Phase 4: Research tools (planned) ├── tests/ # Comprehensive test suite └── docs/ # Extended documentation (planned) ``` ### Running the Server ```bash # Development mode uv run ml-research-mcp # Or as module uv run python -m ml_research_mcp.server ``` ### Testing ```bash # All tests (48 tests, 100% pass rate) uv run pytest # With coverage report uv run pytest --cov=src --cov-report=html # Specific test suite uv run pytest tests/test_plot_basic.py -v ``` ### Code Quality ```bash # Format code uv run ruff format . # Lint and type check uv run ruff check . uv run ty check ``` ### Adding Dependencies ```bash uv add <package> # Runtime dependency uv add --dev <package> # Development dependency uv lock --upgrade # Update lockfile ``` ## Architecture ### Current Design (Phase 1) ``` Input Data (CSV/JSON/Array) ↓ Polars DataFrame Processing ↓ UltraPlot Rendering ↓ Output (PIL Image / bytes) ``` ### Future Architecture The platform is designed to be modular, with each research tool category as a separate module: - **Data Module**: Unified data loading (Polars-based) - **Visualization Module**: Current plotting tools - **Generation Module**: AI-powered content creation - **Presentation Module**: Slide and poster generation - **Research Module**: Literature and experiment management Each module exposes MCP tools that can be independently used or composed together. ## Technology Stack **Current (Phase 1)** - [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework - [UltraPlot](https://ultraplot.readthedocs.io/) - Publication-quality plotting - [Polars](https://pola.rs/) - High-performance dataframes - [Pillow](https://python-pillow.org/) - Image processing - [Pydantic](https://docs.pydantic.dev/) - Data validation **Planned** - Diffusion models (Stable Diffusion, DALL-E) for image generation - LaTeX/Typst for presentation rendering - Vector database for literature search - More to be determined based on research needs ## Contributing We welcome contributions across all phases of the project! ### Current Priorities 1. ✅ Phase 1 visualization tools (complete) 2. 🔨 Additional plot types (3D, network graphs, etc.) 3. 🚧 Phase 2 planning and design ### How to Contribute 1. Fork the repository 2. Create a feature branch 3. Implement with tests (maintain 100% pass rate) 4. Ensure quality checks pass: ```bash uv run ruff format . uv run ruff check . uv run ty check uv run pytest ``` 5. Submit a pull request See [CONTRIBUTING.md](CONTRIBUTING.md) (coming soon) for detailed guidelines. ## Project Goals 1. **Comprehensive**: Cover the full research lifecycle from data analysis to publication 2. **High-quality**: Publication-ready outputs with professional standards 3. **Efficient**: Fast execution leveraging modern Python tools 4. **Extensible**: Easy to add new tools and integrations 5. **AI-friendly**: Designed for seamless AI assistant integration via MCP ## Testing & Quality - **48 tests** covering all Phase 1 functionality - **100% pass rate** with comprehensive coverage - **Type-safe** with full type annotations - **Linted** with Ruff (zero errors) - **Documented** with detailed docstrings ## License MIT License - see [LICENSE](LICENSE) file for details. ## Acknowledgments **Current Phase** - [FastMCP](https://github.com/jlowin/fastmcp) by Jeff Lowin - [UltraPlot](https://ultraplot.readthedocs.io/) - ProPlot successor - [Polars](https://pola.rs/) - Rust-powered dataframes - [uv](https://docs.astral.sh/uv/) - Fast Python packaging **Inspiration** - Model Context Protocol by Anthropic - Modern scientific Python ecosystem ## Resources - [Model Context Protocol Documentation](https://modelcontextprotocol.io/) - [FastMCP Documentation](https://github.com/jlowin/fastmcp) - [UltraPlot Documentation](https://ultraplot.readthedocs.io/) - [Project Issues & Discussions](https://github.com/nishide-dev/ml-research-mcp/issues) --- **Status**: Phase 1 (Visualization) complete ✅ | Phase 2 (Image Generation) in planning 🚧 For feature requests or questions, please open an issue on GitHub.