pybme-mcp

A Model Context Protocol (MCP) server that wraps 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 first (not yet on PyPI):

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

Then install the MCP server:

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

Or from a local clone:

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:

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

VS Code (Copilot)

Add to .vscode/mcp.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 for a step-by-step walkthrough of the full tool chain.

Development

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

Layout

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