​

Ionworks MCP Read Layer — Design

​

Summary

​

Goals

• Expose full cell data and metadata (including time-series, steps, cycles) and material data through MCP tools.
• Reuse the existing ionworks-api Python SDK for all HTTP, auth, retries, gzip, caching, pagination, and response modelling — the MCP layer is thin wrappers, no new transport code.
• Keep it lightweight: one small workspace package, 15 tools, unit-tested with no network dependency.

​

Non-goals (v1)

• Any write/mutation operation (create/update/delete/upload).
• Projects, studies, models, parameterized models, simulations (entity browsing) — cut per user direction to focus on data + materials.
• ECM / optimization / protocol / electrolyte reads.
• A remotely-hosted / multi-tenant MCP endpoint (see “Future work”).

​

Decision: build on the SDK, not the backend

• The SDK path requires no new auth or hosting. A hosted endpoint would mean building remote MCP auth (per-request key → org resolution over the MCP transport), SSE/HTTP infra, CORS, and rate limiting — all net-new and the bulk of the work. That is the wrong shape for a “lightweight, read-only start”.
• The SDK already encodes filter/pagination logic and can compose multiple calls into one ergonomic method; wrapping routes directly would re-derive that.
• Tools are thin SDK wrappers, so if a hosted version is built later, most tool code moves over largely unchanged.

​

Architecture

​

Package layout

packages/ionworks-mcp/
├── pyproject.toml            # deps: ionworks-api (workspace), mcp>=1.x
│                             # entry point: ionworks-mcp = ionworks_mcp.__main__:main
├── README.md
├── ionworks_mcp/
│   ├── __init__.py
│   ├── __main__.py           # python -m ionworks_mcp / console entry point
│   ├── server.py             # builds FastMCP instance, registers tools, runs stdio
│   ├── client.py             # lazy singleton: get_client() -> Ionworks() from env
│   ├── serialize.py          # PaginatedList/BaseModel/DataFrame -> JSON-safe dict
│   ├── errors.py             # @tool_errors decorator -> structured error payloads
│   └── tools/                # 15 tools total across the modules below
│       ├── __init__.py       # register_all(mcp)
│       ├── discovery.py      # discover_capabilities
│       ├── cells.py          # cell specs, instances, measurements (list/get)
│       ├── measurement_data.py  # time_series / steps / cycles (windowed)
│       └── materials.py      # materials + material property datasets + data
└── tests/
    ├── conftest.py           # fake Ionworks client fixture
    ├── test_tools.py         # per-tool: delegation, serialization, errors
    └── test_server.py        # all 15 tools register on the FastMCP instance

​

Tool surface (15 tools, read-only)

​

Cell data hierarchy

​

Materials

​

DataFrame → JSON (the key design point)

• Default limit = 500 rows, hard cap max = 5000 rows. A requested limit above the cap is clamped (and the response notes it).
• Optional columns projects to only the requested signals. Projection is done client-side after download — time_series() downloads the full parquet (and the SDK caches it), so repeated row/column slices are cheap; only the response is bounded, not the fetch.
• Response shape:
  {
    "columns": ["Time [s]", "Voltage [V]", ...],
    "dtypes": {"Time [s]": "float64", ...},
    "rows": [{"Time [s]": 0.0, "Voltage [V]": 3.7, ...}, ...],
    "row_count": 500,
    "total_rows": 132004,
    "offset": 0,
    "truncated": true,
    "note": "Returned 500 of 132004 rows. Use offset to page, or columns=[...] to narrow."
  }
  
• Row/column counts and dtypes are always returned even when truncated, so the model knows the full shape.
• For get_material_property_data, units from get_units(dataset_id) are merged into the response (e.g. a units map alongside columns).

​

Serialization (serialize.py)

• PaginatedList / list[BaseModel] → {"items": [...], "count": n, "total": t, "offset": o, "has_more": bool}. PaginatedList exposes only .items, .count, and .total (packages/ionworks-api/ionworks/models.py) — it has no offset. The serializer therefore takes offset as an explicit argument (threaded from the calling tool’s own offset param, defaulting to 0), and computes has_more = offset + count < total. It is serialize_list(paginated, offset=...), not a pure one-arg function.
• Single BaseModel → model.model_dump(mode="json") (UUID→str, datetime→ISO; absolute times, matching the UI convention).
• DataFrame → the windowed shape above. Because get_client() forces the pandas backend, the serializer uses a single stable API (df.dtypes, df.iloc[offset:offset+limit], to_dict(orient="records")) and does not need to branch on polars vs pandas.
• All returns are plain JSON-serializable dicts; FastMCP encodes the wire form.

​

Error handling (errors.py)

• A @tool_errors decorator wraps each tool. It catches IonworksError (and subclasses) and returns a structured {"error": {"code": ..., "message": ...}} payload instead of letting the exception crash the MCP call. Mirrors the backend’s “structured error, actionable message” philosophy.
• Missing credentials: the SDK’s Ionworks() constructor raises a bare ValueError eagerly when no key is set. get_client() catches this and re-raises an IonworksError with a clear message ("IONWORKS_API_KEY not set — configure it in your MCP server environment") so the @tool_errors boundary reports it as an IonworksError (a service error) rather than a generic BadRequest. Surfaced on the first tool call that constructs the client.
• Empty results are normal empty items, not errors.
• Tools do not individually try/except; the decorator is the single boundary.

​

Testing

• just test-mcp recipe, mirroring the other test-* package recipes.
• Unit tests only, no network. conftest.py supplies a fake_client fixture — a stub Ionworks whose sub-clients return canned PaginatedList / BaseModel / DataFrame objects; get_client() is monkeypatched to return it.
• Per-tool coverage: (a) delegates to the right SDK method with the right args, (b) serializes correctly, (c) DataFrame tools window/truncate and set truncated / total_rows, (d) columns projection drops unrequested columns, (e) IonworksError → structured error payload, (f) missing-key path.
• test_server.py asserts all 15 tools register on the FastMCP instance.
• No live-backend test in v1; README documents how to smoke-test with a real key.

​

Future work

• Add the entity-browsing tools (projects, studies, models, parameterized models, simulations) if needed.
• Add heavier reads (simulation.get_result, ECM/optimization/protocol).
• Expose the remaining discovery methods (client.schema(name), client.pybamm_models()) as tools.
• Write tools (guarded, opt-in).
• A remotely-hosted MCP endpoint on the backend for zero-install multi-tenant access — most tool code carries over.