# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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:

```json
{
  "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
```bash
# 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
```bash
# 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
```python
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

- **[MCP_WALKTHROUGH.md](MCP_WALKTHROUGH.md)** - Complete step-by-step walkthrough
- **[examples/walkthrough/](examples/walkthrough/)** - Hands-on examples and demos
- **[USAGE_GUIDE.md](USAGE_GUIDE.md)** - 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.