patrickoleary/data-mcp

Data MCP Server

A Model Context Protocol (MCP) server for scientific data introspection and visualization. Provides comprehensive analysis of VTK datasets with format-specific metadata extraction and interactive 3D visualization.

✨ Features

• 10 MCP Tools for complete dataset analysis
• Format-Adaptive Metadata - Specialized handlers for VTI, VTU, VTP formats
• Interactive 3D Visualization using Trame/VTK
• Memory-Efficient Architecture with automatic cleanup
• Comprehensive Component Analysis with detailed statistics

🚀 Quick Start

1. Setup Environment

# Clone or navigate to the project directory
cd data-mcp

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On macOS/Linux
# .venv\Scripts\activate   # On Windows

# Install dependencies
pip install -r requirements.txt
pip install -e .

2. Run Basic Demo

# Test MCP server functionality
python examples/walkthrough/demo_mcp_usage.py

3. Sample Data

Pre-generated VTK files in examples/sample_data/:

• gaussian_simple.vti - 3D structured grid (20×15×12)
• wave_pattern.vti - Wave pattern data

4. Interactive Visualization

# Launch 3D viewer (opens at localhost:8080)
python -c "
from src.data_mcp.viewers.vtk_viewer import VTKViewer
VTKViewer.show_file('examples/sample_data/gaussian_simple.vti')
"

5. Start MCP Server

# Start the MCP server (requires MCP client to connect)
python -m data_mcp.server

🔌 MCP Client Configuration

Connecting MCP Clients

Use the provided mcp_client_config.json to connect MCP-compatible clients:

{
  "mcpServers": {
    "data-mcp": {
      "command": "python",
      "args": ["-m", "data_mcp.server"],
      "cwd": "/Users/patrick.oleary/code/AI Experiments/data-mcp",
      "env": {}
    }
  }
}

Supported MCP Clients

• Claude Desktop - Anthropic's desktop application
• Custom MCP applications - Built with MCP client libraries
• Development tools - IDEs and testing frameworks with MCP support

Integration Steps

1. Copy the config to your MCP client's configuration directory
2. Update the cwd path to match your project location
3. Restart your MCP client to register the server
4. Access via client - The server will appear as "data-mcp" with 10 available tools

🧪 Testing & Examples

Comprehensive Walkthrough

# Test all 10 MCP tools with detailed output
python examples/walkthrough/manual_tool_test.py

# Test format-specific metadata adaptation
python examples/walkthrough/test_format_adaptation.py

Integration Tests

# Full MCP workflow testing
python tests/integration/test_full_mcp_workflow.py

# Real MCP client connection test
python tests/integration/test_real_mcp_client.py

🎯 Available MCP Tools

• upload_dataset - Load and register dataset files
• list_datasets - Show all loaded datasets
• query_dataset - Get comprehensive dataset information
• get_schema - Extract detailed schema information
• list_components - Show available data arrays/components
• get_component_info - Get detailed component information
• get_statistics - Calculate statistics for components
• visualize_dataset - Launch interactive 3D viewer
• suggest_visualizations - Get visualization recommendations
• remove_dataset - Remove dataset from memory

📋 Usage Examples

Programmatic Usage

from data_mcp.formats.vtk_factory import VTKHandlerFactory
from data_mcp.core.dataset import Dataset
from data_mcp.viewers.vtk_viewer import VTKViewer

# Load dataset with format-specific handler
handler = VTKHandlerFactory.create_handler("path/to/file.vti")
dataset = Dataset("path/to/file.vti", handler)
dataset.introspect()

# Get comprehensive information
info = dataset.get_info()
components = dataset.list_components()
stats = dataset.get_statistics("temperature")

# Launch interactive viewer (convenience method)
VTKViewer.show_file("path/to/file.vti")  # Opens at localhost:8080

# Or create viewer with dataset
viewer = VTKViewer(dataset=dataset)
viewer.show()

MCP Client Usage

Connect via MCP client and use these tools:

• Upload datasets, query metadata, analyze components
• Get format-specific information (VTI/VTU/VTP)
• Launch interactive 3D visualizations
• Calculate detailed statistics

🏗️ Architecture

Format Handler Inheritance System

• BaseVTKHandler - Common VTK functionality
• VTKImageDataHandler (.vti) - Structured grids with spacing/dimensions
• VTKUnstructuredGridHandler (.vtu) - Irregular meshes with cell analysis
• VTKPolyDataHandler (.vtp) - Surface meshes with topology analysis
• VTKHandlerFactory - Automatic handler selection by file extension

Supported Formats

Currently supports VTK formats with format-specific metadata:

• .vti - ImageData (regular grids, voxel data)
• .vtu - UnstructuredGrid (irregular meshes, FEM data)
• .vtp - PolyData (surface meshes, CAD data)

Memory Management

• Automatic cleanup after dataset introspection
• Stored component data for efficient access
• Handler recycling to prevent memory bloat

📁 Project Structure

data-mcp/
├── README.md                    # Project documentation
├── MCP_WALKTHROUGH.md          # Comprehensive walkthrough guide
├── pyproject.toml              # Python packaging configuration
├── requirements.txt            # Dependencies
├── src/data_mcp/              # Main package
│   ├── server.py              # MCP server implementation
│   ├── core/                  # Core functionality
│   │   ├── dataset.py         # Dataset abstraction with cleanup
│   │   ├── introspector.py    # Dataset analysis engine
│   │   ├── schema.py          # Schema representation
│   │   └── visualizer.py      # Visualization engine
│   ├── formats/               # Format handlers (inheritance system)
│   │   ├── base.py           # Base format handler interface
│   │   ├── vtk_base.py       # Base VTK handler
│   │   ├── vtk_imagedata.py  # VTI handler (structured grids)
│   │   ├── vtk_unstructured.py # VTU handler (irregular meshes)
│   │   ├── vtk_polydata.py   # VTP handler (surface meshes)
│   │   └── vtk_factory.py    # Handler factory
│   ├── viewers/               # Trame-based visualization
│   │   └── vtk_viewer.py     # VTK 3D viewer
│   └── utils/                 # Utilities
│       └── file_utils.py     # File handling
├── examples/                  # Usage examples
│   ├── basic_usage.py        # Basic programmatic usage
│   ├── walkthrough/          # Walkthrough examples
│   │   ├── demo_mcp_usage.py # Basic MCP demo
│   │   ├── manual_tool_test.py # All 10 tools test
│   │   └── test_format_adaptation.py # Format adaptation demo
│   └── sample_data/          # Sample VTK files
│       ├── gaussian_simple.vti # 3D structured grid
│       └── wave_pattern.vti   # Wave pattern data
└── tests/                     # Test suite
    ├── integration/           # Integration tests
    └── test_formats/         # Format handler tests

🔧 Current Status

• ✅ 10/10 MCP Tools Working (100% success rate)
• ✅ Format-Adaptive Metadata for VTI/VTU/VTP files
• ✅ Memory-Efficient Architecture with automatic cleanup
• ✅ Interactive 3D Visualization via Trame/VTK
• ✅ Production-Ready for scientific data workflows

📚 Documentation

• - Complete step-by-step walkthrough
• - Hands-on examples and demos
• - Basic usage guide

🤝 Contributing

This project demonstrates a production-ready MCP server with:

• Format-adaptive metadata extraction
• Memory-efficient architecture
• Comprehensive testing suite
• Interactive visualization capabilities

For extending to new formats, follow the inheritance pattern established in the VTK handlers.

📄 License

MIT License - see LICENSE file for details.