# pybme-mcp

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that wraps [pyBME](https://github.com/wiesnerfriedman/pybme) — enabling LLM agents to perform Bayesian Maximum Entropy geostatistical analysis through natural-language intent rather than code.

## What it does

The server exposes **7 tools**, **6 resources**, and **4 prompts** that form an uncertainty-reasoning pipeline:

```
ingest_external_scenario_evidence → inspect_modeling_context
       → fit_uncertainty_model → run_uncertainty_update
       → explain_uncertainty_drivers
       → compare_operator_approaches
       → design_next_observation_or_scenario
```

### Tools

| Tool | Purpose |
|------|---------|
| `ingest_external_scenario_evidence` | Import hard/soft observations and network topology |
| `inspect_modeling_context` | Detect problem type and recommend model families |
| `fit_uncertainty_model` | Fit spatial or network covariance models with cross-validation |
| `run_uncertainty_update` | Run BME prediction at estimation targets |
| `explain_uncertainty_drivers` | Identify what drives uncertainty at specific locations |
| `compare_operator_approaches` | Compare Euclidean vs graph vs physics-informed operators |
| `design_next_observation_or_scenario` | Rank candidate sensor placements by variance reduction |

### Supported model families

- **spatial** — Euclidean covariance (exponential, gaussian, spherical, …)
- **space_time** — Separable space-time covariance
- **graph_laplacian** — Graph-diffusion kernel on network topology
- **physics_informed_network** — Physically consistent network covariance
- **spectral_hodge** — Spectral Hodge decomposition for flow networks

## Install

Install [pyBME](https://github.com/wiesnerfriedman/pybme) first (not yet on PyPI):

```bash
pip install git+https://github.com/wiesnerfriedman/pybme.git
```

Then install the MCP server:

```bash
pip install git+https://github.com/wiesnerfriedman/pybme-mcp.git
```

Or from a local clone:

```bash
git clone https://github.com/wiesnerfriedman/pybme-mcp.git
cd pybme-mcp
pip install -e ".[dev]"
```

## Configuration

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pybme": {
      "command": "pybme-mcp"
    }
  }
}
```

### VS Code (Copilot)

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "pybme": {
      "type": "stdio",
      "command": "pybme-mcp"
    }
  }
}
```

## Usage

Once configured, ask your agent things like:

- *"Fit an uncertainty model to my PM2.5 observations"*
- *"Run a network-aware BME update on this stormwater network"*
- *"Compare Euclidean vs graph Laplacian operators"*
- *"Where should I place the next sensor to reduce uncertainty the most?"*

See [`examples/mcp_agent_demo.ipynb`](examples/mcp_agent_demo.ipynb) for a step-by-step walkthrough of the full tool chain.

## Development

```bash
git clone https://github.com/wiesnerfriedman/pybme-mcp.git
cd pybme-mcp
pip install -e ".[dev]"
pytest
```

## Layout

```text
pybme-mcp/
├── docs/
│   ├── pybme-openswmm-integration.md
│   └── v1-mcp-spec.md
├── examples/
│   └── mcp_agent_demo.ipynb
├── pyproject.toml
├── src/pybme_mcp/
│   ├── __init__.py
│   ├── __main__.py
│   ├── registry.py
│   ├── schemas.py
│   ├── serialisation.py
│   ├── server.py
│   └── services/
│       ├── catalog.py
│       ├── comparison.py
│       ├── context.py
│       ├── explanation.py
│       ├── fitting.py
│       ├── hodge.py
│       ├── ingest.py
│       ├── scenario_design.py
│       └── update.py
└── tests/
    ├── conftest.py
    ├── test_ingest.py
    └── test_integration.py
```

## License

MIT