# PyBaMM MCP Server

This project exposes PyBaMM documentation and source code through a local MCP
server so an LLM-enabled IDE can search docs and open files directly from
tools.

## What This Server Does

At startup, the project prepares three things:

1. A local clone of the PyBaMM repository (`./PyBaMM`)
2. Built plain-text docs (`PyBaMM/docs/_build/text`)
3. A full-text SQLite index (`pybamm_docs.db`)

Then `server.py` starts an MCP stdio server that provides these tools:

- `search_pybamm_docs(query)`: full-text search across PyBaMM docs
- `read_doc_page(filepath)`: read one docs text page from search results
- `read_pybamm_source_code(module_path)`: open source files from the cloned repo

## Prerequisites

### Docker workflow

- Docker
- Docker Compose v2 (`docker compose`)

### Local (non-Docker) workflow

- Python 3.11+
- Git
- `make`
- `pandoc`

## Install And Run With Docker

From this repository root:

```bash
docker compose build
docker compose run --rm --no-deps -T pybamm-mcp
```

Notes:

- The first build can take a while because it builds PyBaMM docs.
- Transport is stdio (no HTTP/TCP port).
- Rebuild after changing `Dockerfile`, `requirements.txt`, `build_index.py`, or
  `server.py`:

```bash
docker compose build --no-cache
```

## Install And Run Locally

From this repository root:

```bash
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
git clone --depth 1 --branch main https://github.com/pybamm-team/PyBaMM.git PyBaMM
pip install -e ./PyBaMM
make -C PyBaMM/docs text
python build_index.py
python server.py
```

Notes:

- `server.py` expects paths relative to this repo root. Run it from here.
- If `PyBaMM/` already exists, skip the clone command.
- Rebuild docs/index after updating the PyBaMM checkout:

```bash
make -C PyBaMM/docs text
python build_index.py
```

## Configure Your IDE MCP Client

Most MCP-enabled IDEs use a JSON server entry with:

- a command to run
- args
- optional `cwd`

Add one of the following entries in your IDE MCP settings.

### Option A: Docker-backed server (recommended for consistency)

```json
{
  "mcpServers": {
    "pybamm-docs": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/absolute/path/to/pybamm_mcp_server/docker-compose.yml",
        "run",
        "--rm",
        "--no-deps",
        "-T",
        "pybamm-mcp"
      ]
    }
  }
}
```

### Option B: Local virtualenv server (fastest startup after setup)

```json
{
  "mcpServers": {
    "pybamm-docs": {
      "command": "/absolute/path/to/pybamm_mcp_server/.venv/bin/python",
      "args": ["/absolute/path/to/pybamm_mcp_server/server.py"],
      "cwd": "/absolute/path/to/pybamm_mcp_server"
    }
  }
}
```

### Option C: IDE running on Windows, server in WSL

If your IDE launches commands in Windows but your project is in WSL:

```json
{
  "mcpServers": {
    "pybamm-docs": {
      "command": "wsl",
      "args": [
        "-e",
        "bash",
        "-lc",
        "cd /absolute/path/to/pybamm_mcp_server && .venv/bin/python server.py"
      ]
    }
  }
}
```

## Verify IDE Connection

After adding the server config:

1. Restart your IDE MCP service (or the IDE itself).
2. Confirm `pybamm-docs` shows as connected.
3. Run a quick tool call, for example:
   `search_pybamm_docs("single particle model")`.

If the server fails to start, most issues are one of:

- wrong absolute path in MCP config
- missing docs/index (`make text` and `python build_index.py` not run)
- wrong working directory (must be this repo root for local mode)