# MDF MCP Server

A Model Context Protocol (MCP) server for analyzing ASAM MDF (Measurement Data Format) files. Enables AI assistants to access and analyze automotive and industrial measurement data.

## 🚀 Quick Start

### Using uvx (Recommended)

```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run the server directly
uvx mcp-server-mdf
```

### Local Development

```bash
# Clone and setup
git clone https://github.com/Shanko-26/mdfmcp
cd mdfmcp

# Install in virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

# Run the server
mcp-server-mdf
```

## 📋 Features

- **MDF File Support**: Versions 2.x, 3.x, and 4.x
- **AI-Native Interface**: Designed for LLM integration
- **Data Analysis**: Statistics, plotting, signal processing
- **Format Export**: CSV, HDF5, Parquet, MATLAB
- **Session Management**: Multi-file support
- **High Performance**: Efficient large file handling

## 🔧 Configuration

**Important**: This MCP server requires direct file system access to read MDF files. It works best with IDEs that support local file operations.

### Compatible IDEs

#### For VS Code with Continue.dev

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "mdf": {
      "command": "uvx",
      "args": ["mcp-server-mdf@latest"]
    }
  }
}
```

#### For Cursor IDE

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "mdf": {
      "command": "uvx",
      "args": ["mcp-server-mdf@latest"]
    }
  }
}
```

#### For Windsurf/Codeium

Follow your IDE's MCP configuration guide with the same uvx command.

#### Troubleshooting uvx Path Issues

If you get "command not found" errors, find your uvx path:
```bash
which uvx  # On macOS/Linux  
where uvx  # On Windows
```
Then use the full path in your configuration:
```json
{
  "mcpServers": {
    "mdf": {
      "command": "/Users/username/.local/bin/uvx",
      "args": ["mcp-server-mdf"]
    }
  }
}
```

## 📁 File Organization

**Smart Workspace Search**: The server automatically finds MDF files in your project:

```
your-project/
├── data.mf4              # ✅ Found by filename
├── data/
│   └── test.mf4          # ✅ Found in data/ folder
├── measurements/
│   └── run1.mf4          # ✅ Found in measurements/ folder
├── test_data/
├── examples/
└── samples/
```

**Usage Examples**:
- `"data.mf4"` → Searches workspace automatically
- `"./data/test.mf4"` → Relative path from current directory  
- `"/absolute/path/file.mf4"` → Full absolute path
- Case insensitive: `"DATA.MF4"` finds `"data.mf4"`

## 🔄 Staying Current

**Always use latest version** by adding `@latest` to your IDE configuration:

```json
{
  "mcpServers": {
    "mdf": {
      "command": "uvx",
      "args": ["mcp-server-mdf@latest"]
    }
  }
}
```

**Check version**: `uvx mcp-server-mdf@latest --version`

## 📊 Usage Examples

### Open and Analyze MDF Files

```
User: Open the measurement file at /data/test_drive.mf4
Assistant: I'll open that MDF file for you.

[Opens file]
Successfully opened test_drive.mf4:
- Session ID: mdf_a3b2c1d4
- Version: 4.10
- Channels: 847
- Duration: 1823.4 seconds
```

### List and Search Channels

```
User: What temperature channels are available?
Assistant: Let me search for temperature-related channels.

Found 23 temperature channels:
- Engine_Temp (°C) - Engine coolant temperature
- Oil_Temp (°C) - Engine oil temperature
- Ambient_Temp (°C) - Outside air temperature
```

### Analyze and Plot Signals

```
User: Show me the engine speed statistics and plot it
Assistant: I'll analyze the engine speed signal.

Engine Speed Analysis:
- Mean: 2,847 RPM
- Max: 6,234 RPM
- Std Dev: 1,123 RPM

[Shows time-series plot of engine speed]
```

## 🛠️ Available Tools

### Session Management
- `open_mdf` - Open an MDF file
- `close_mdf` - Close a session
- `list_sessions` - Show active sessions
- `get_file_info` - Get file metadata

### Data Access
- `list_channels` - List available channels
- `mdf_get` - Extract single channel data
- `mdf_select` - Extract multiple channels
- `mdf_get_master` - Get time channel data

### Analysis
- `calculate_statistics` - Compute signal statistics
- `plot_signals` - Create visualizations
- `mdf_to_dataframe` - Convert to pandas DataFrame

### Data Manipulation
- `mdf_cut` - Extract time slice
- `mdf_filter` - Filter specific channels
- `mdf_resample` - Change sampling rate

### Export
- `mdf_export` - Export to various formats
- `mdf_convert` - Convert between MDF versions
- `mdf_save` - Save modified file

## 🐳 Docker Deployment (Alternative)

### Build Image

```bash
docker build -t mcp-server-mdf .
```

### Run Container

```bash
# Basic run
docker run -it --rm mcp-server-mdf

# With volume mount for data
docker run -it --rm -v /path/to/mdf/files:/data mcp-server-mdf

# With custom environment
docker run -it --rm -e MAX_SESSIONS=20 mcp-server-mdf
```

### MCP Configuration for Docker

```json
{
  "mcpServers": {
    "mdf": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/data:/data", "mcp-server-mdf"]
    }
  }
}
```

## 🧪 Testing

```bash
# Run tests
pytest tests/

# Test server manually
python tests/manual_test.py
```

## 📁 Project Structure

```
mdfmcp/
├── src/mdfmcp/
│   ├── __init__.py
│   └── server.py          # Main MCP server
├── tests/
│   ├── conftest.py
│   ├── manual_test.py
│   └── test_server.py
├── examples/
│   ├── basic_usage.py
│   └── test_data_generator.py
├── Dockerfile
├── requirements.txt
├── pyproject.toml
└── README.md
```

## 🔧 Development

### Setup Development Environment

```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .
```

### Code Quality

```bash
# Format code
black src/

# Lint
ruff src/

# Type checking
mypy src/
```

## 🚨 Troubleshooting

### Common Issues

1. **Memory errors with large files**
   - Use `memory="low"` when opening files
   - Reduce concurrent sessions

2. **Cannot find channels**
   - Channel names are case-sensitive
   - Use regex patterns for flexible searching

3. **Docker build fails**
   - Ensure Docker is running
   - Check Dockerfile syntax

## 🙏 Acknowledgments

- Built on [asammdf](https://github.com/danielhrisca/asammdf) by Daniel Hrisca (LGPL v3+)
- Uses the [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic
- Matplotlib for plotting capabilities
- Pandas and NumPy for data processing

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

**Dependencies**: This project uses asammdf which is licensed under LGPL v3+. The asammdf library remains a separate component and is not modified by this project.