[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "ionworks-mcp"
version = "0.1.0"
description = "Read-only MCP server for the Ionworks public API"
authors = []
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "mcp>=1.2.0",
    "ionworks-api",
    "pandas>=2.0,<3",
]

[project.urls]
Homepage = "https://ionworks.com"
Repository = "https://github.com/ionworks/ionworks-app"

[project.scripts]
ionworks-mcp = "ionworks_mcp.__main__:main"

[project.optional-dependencies]
dev = [
    "pytest>=9.0",
    "pytest-cov>=7.0",
]

[tool.uv.sources]
ionworks-api = { workspace = true }

[tool.hatch.build.targets.wheel]
packages = ["ionworks_mcp"]

[tool.hatch.build.targets.sdist]
packages = ["ionworks_mcp"]

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
pythonpath = ["."]

"""Read-only MCP server exposing the Ionworks public API."""

__version__ = "0.1.0"

test-mcp *args:
    just test-package ionworks-mcp {{args}}

uv run --package ionworks-mcp python -c "
from mcp.server.fastmcp import FastMCP
m = FastMCP('probe')
@m.tool()
def sample(x: int) -> dict: return {'x': x}
tools = m._tool_manager.list_tools()
t = tools[0]
print('list_tools ok:', [x.name for x in tools])
print('has .fn:', hasattr(t, 'fn'), 'has .name:', hasattr(t, 'name'))
print('schema:', t.parameters)
"

git add packages/ionworks-mcp/pyproject.toml packages/ionworks-mcp/ionworks_mcp/__init__.py pyproject.toml uv.lock justfile
git commit -m "chore(ionworks-mcp): scaffold package and wire into workspace"

import pytest

import ionworks_mcp.client as client_mod
from ionworks import IonworksError


def test_get_client_forces_pandas_and_caches(monkeypatch):
    calls = {"backend": [], "ctor": 0}

    def fake_set_backend(name):
        calls["backend"].append(name)

    class FakeIonworks:
        def __init__(self, *a, **k):
            calls["ctor"] += 1

    monkeypatch.setattr(client_mod, "set_dataframe_backend", fake_set_backend)
    monkeypatch.setattr(client_mod, "Ionworks", FakeIonworks)
    client_mod._client = None  # reset singleton

    c1 = client_mod.get_client()
    c2 = client_mod.get_client()

    assert c1 is c2                      # cached
    assert calls["ctor"] == 1            # constructed once
    assert calls["backend"] == ["pandas"]  # pandas forced once


def test_get_client_missing_key_raises_clear_ionworks_error(monkeypatch):
    def fake_ctor(*a, **k):
        raise ValueError(
            "API key must be provided either as argument or in IONWORKS_API_KEY "
            "environment variable"
        )

    monkeypatch.setattr(client_mod, "set_dataframe_backend", lambda name: None)
    monkeypatch.setattr(client_mod, "Ionworks", fake_ctor)
    client_mod._client = None

    with pytest.raises(IonworksError) as exc:
        client_mod.get_client()
    assert "IONWORKS_API_KEY" in str(exc.value)

"""Lazy, process-wide Ionworks SDK client for the MCP server."""

from __future__ import annotations

from ionworks import Ionworks, IonworksError, set_dataframe_backend

_client: Ionworks | None = None


def get_client() -> Ionworks:
    """Return a process-wide Ionworks client, constructing it on first use.

    The DataFrame backend is forced to pandas so the serialization layer can
    rely on a single, stable DataFrame API. Credentials are read from the
    environment by the SDK (``IONWORKS_API_KEY`` and optional
    ``IONWORKS_API_URL`` / project id).

    The SDK constructor raises a bare ``ValueError`` immediately when no key is
    present; this is re-raised as an ``IonworksError`` with an actionable
    message so the MCP error boundary reports it as a service error rather than
    a client "bad request".

    Returns
    -------
    Ionworks
        The shared client instance.

    Raises
    ------
    IonworksError
        If ``IONWORKS_API_KEY`` is not configured in the environment.
    """
    global _client
    if _client is None:
        set_dataframe_backend("pandas")
        try:
            _client = Ionworks()
        except ValueError as exc:
            raise IonworksError(
                "IONWORKS_API_KEY not set — configure it in your MCP server "
                f"environment. ({exc})"
            ) from exc
    return _client

"""Plain fake classes shared across tests (imported, not injected as fixtures)."""

from __future__ import annotations


class FakeModel:
    """Stand-in for a Pydantic v2 model exposing model_dump."""

    def __init__(self, data: dict):
        self._data = data

    def model_dump(self, mode: str = "python") -> dict:
        return dict(self._data)


class FakePaginatedList(list):
    """Behaves like PaginatedList: a list plus a .total attribute."""

    def __init__(self, items, total):
        super().__init__(items)
        self.total = total

"""Shared test fixtures: a fake Ionworks client wired into get_client()."""

from __future__ import annotations

from types import SimpleNamespace

import pandas as pd
import pytest

import ionworks_mcp.client as client_mod


@pytest.fixture
def fake_client(monkeypatch):
    """Install a fake Ionworks client and return it for per-test configuration.

    Patches ``ionworks_mcp.client.get_client``; tools call it via
    ``client_mod.get_client()`` so the module-attribute patch is what they see.
    """
    fake = SimpleNamespace(
        cell_spec=SimpleNamespace(),
        cell_instance=SimpleNamespace(),
        cell_measurement=SimpleNamespace(),
        material=SimpleNamespace(),
        material_property_dataset=SimpleNamespace(),
        capabilities=lambda: {"name": "Ionworks", "hierarchy": "..."},
    )
    monkeypatch.setattr(client_mod, "get_client", lambda: fake)
    return fake


@pytest.fixture
def sample_df():
    return pd.DataFrame(
        {
            "Time [s]": [0.0, 1.0, 2.0],
            "Voltage [V]": [3.7, 3.71, 3.72],
            "Current [A]": [0.0, -1.0, -1.0],
        }
    )

git add packages/ionworks-mcp/ionworks_mcp/client.py packages/ionworks-mcp/tests/__init__.py packages/ionworks-mcp/tests/_fakes.py packages/ionworks-mcp/tests/conftest.py packages/ionworks-mcp/tests/test_tools.py
git commit -m "feat(ionworks-mcp): lazy client singleton (pandas backend, clear missing-key error)"

from ionworks import IonworksError

from ionworks_mcp.errors import tool_errors


def test_passes_through_success():
    @tool_errors
    def ok(x):
        return {"value": x}

    assert ok(3) == {"value": 3}


def test_wraps_ionworks_error():
    @tool_errors
    def boom():
        raise IonworksError("nope")

    result = boom()
    assert result["error"]["message"] == "nope"
    assert result["error"]["code"] == "IonworksError"


def test_wraps_value_error_as_bad_request():
    @tool_errors
    def bad():
        raise ValueError("missing material_id")

    result = bad()
    assert result["error"]["code"] == "BadRequest"
    assert "material_id" in result["error"]["message"]

"""Error-boundary decorator translating exceptions into structured payloads."""

from __future__ import annotations

import functools
from collections.abc import Callable
from typing import Any

from ionworks import IonworksError


def tool_errors(func: Callable[..., Any]) -> Callable[..., Any]:
    """Wrap a tool so exceptions become structured error dicts, not crashes.

    ``IonworksError`` (and subclasses) map to their class name as the code.
    ``ValueError`` — raised by argument validation inside tools — maps to
    ``"BadRequest"``. Any other exception maps to ``"InternalError"``.
    """

    @functools.wraps(func)
    def wrapper(*args: Any, **kwargs: Any) -> Any:
        try:
            return func(*args, **kwargs)
        except IonworksError as exc:
            # Use .message (the SDK's raw text attribute), NOT str(exc):
            # IonworksError.__str__ prepends "error code: {status_code}, " which
            # would leak into the MCP payload.
            return {"error": {"code": type(exc).__name__, "message": exc.message}}
        except ValueError as exc:
            return {"error": {"code": "BadRequest", "message": str(exc)}}
        except Exception as exc:  # noqa: BLE001 - MCP boundary must not crash
            return {"error": {"code": "InternalError", "message": str(exc)}}

    return wrapper

git add packages/ionworks-mcp/ionworks_mcp/errors.py packages/ionworks-mcp/tests/test_errors.py
git commit -m "feat(ionworks-mcp): tool_errors decorator for structured error payloads"

import pandas as pd

from ionworks_mcp.serialize import (
    DEFAULT_ROW_LIMIT,
    MAX_ROW_LIMIT,
    serialize_dataframe,
    serialize_list,
    serialize_model,
)
from tests._fakes import FakeModel, FakePaginatedList


def test_serialize_model():
    assert serialize_model(FakeModel({"id": "a", "name": "x"})) == {"id": "a", "name": "x"}


def test_serialize_list_shape_and_has_more():
    pl = FakePaginatedList([FakeModel({"id": "1"}), FakeModel({"id": "2"})], total=10)
    out = serialize_list(pl, offset=0)
    assert out["items"] == [{"id": "1"}, {"id": "2"}]
    assert out["count"] == 2
    assert out["total"] == 10
    assert out["offset"] == 0
    assert out["has_more"] is True


def test_serialize_list_has_more_false_at_end():
    pl = FakePaginatedList([FakeModel({"id": "9"})], total=10)
    out = serialize_list(pl, offset=9)
    assert out["has_more"] is False


def test_serialize_dataframe_windows_rows():
    df = pd.DataFrame({"a": range(1000), "b": range(1000)})
    out = serialize_dataframe(df, limit=10, offset=0)
    assert out["row_count"] == 10
    assert out["total_rows"] == 1000
    assert out["truncated"] is True
    assert out["rows"][0] == {"a": 0, "b": 0}
    assert set(out["columns"]) == {"a", "b"}
    assert "a" in out["dtypes"]


def test_serialize_dataframe_offset_paging():
    df = pd.DataFrame({"a": range(100)})
    out = serialize_dataframe(df, limit=5, offset=50)
    assert out["rows"][0]["a"] == 50
    assert out["offset"] == 50


def test_serialize_dataframe_column_projection():
    df = pd.DataFrame({"a": [1, 2], "b": [3, 4], "c": [5, 6]})
    out = serialize_dataframe(df, columns=["a", "c"])
    assert set(out["columns"]) == {"a", "c"}
    assert "b" not in out["rows"][0]


def test_serialize_dataframe_unknown_column_raises():
    df = pd.DataFrame({"a": [1]})
    try:
        serialize_dataframe(df, columns=["a", "nope"])
    except ValueError as exc:
        assert "nope" in str(exc)
    else:
        raise AssertionError("expected ValueError for unknown column")


def test_serialize_dataframe_limit_clamped_to_max():
    df = pd.DataFrame({"a": range(MAX_ROW_LIMIT + 100)})
    out = serialize_dataframe(df, limit=MAX_ROW_LIMIT + 50)
    assert out["row_count"] == MAX_ROW_LIMIT


def test_serialize_dataframe_not_truncated_when_all_returned():
    df = pd.DataFrame({"a": [1, 2, 3]})
    out = serialize_dataframe(df, limit=DEFAULT_ROW_LIMIT, offset=0)
    assert out["truncated"] is False
    assert out["row_count"] == 3

"""Normalize SDK return values to JSON-safe dicts for MCP responses."""

from __future__ import annotations

from typing import Any

import pandas as pd

DEFAULT_ROW_LIMIT = 500
MAX_ROW_LIMIT = 5000


def serialize_model(model: Any) -> dict:
    """Serialize a single Pydantic v2 model to a JSON-safe dict."""
    return model.model_dump(mode="json")


def serialize_list(paginated: Any, offset: int = 0) -> dict:
    """Serialize a PaginatedList (list + ``.total``) to a paged response.

    ``PaginatedList`` has no offset of its own, so ``offset`` is threaded in
    from the calling tool. ``has_more`` is ``offset + count < total``.
    """
    items = [serialize_model(item) for item in paginated]
    count = len(items)
    total = int(getattr(paginated, "total", count) or 0)
    return {
        "items": items,
        "count": count,
        "total": total,
        "offset": offset,
        "has_more": offset + count < total,
    }


def serialize_dataframe(
    df: pd.DataFrame,
    columns: list[str] | None = None,
    limit: int = DEFAULT_ROW_LIMIT,
    offset: int = 0,
    units: dict[str, str] | None = None,
) -> dict:
    """Serialize a (pandas) DataFrame to a windowed, JSON-safe response.

    Row count is bounded by ``limit`` (clamped to ``MAX_ROW_LIMIT``); ``offset``
    pages through rows; ``columns`` projects a subset (unknown names raise
    ``ValueError``). ``total_rows`` and ``dtypes`` always reflect the full frame
    so the caller knows the shape even when ``truncated`` is True.
    """
    if columns is not None:
        missing = [c for c in columns if c not in df.columns]
        if missing:
            raise ValueError(
                f"Unknown column(s): {', '.join(missing)}. "
                f"Available: {', '.join(map(str, df.columns))}"
            )
        df = df[columns]

    total_rows = int(len(df))
    effective_limit = min(max(int(limit), 0), MAX_ROW_LIMIT)
    window = df.iloc[offset : offset + effective_limit]
    rows = window.to_dict(orient="records")
    row_count = len(rows)

    response: dict = {
        "columns": [str(c) for c in df.columns],
        "dtypes": {str(c): str(dt) for c, dt in df.dtypes.items()},
        "rows": rows,
        "row_count": row_count,
        "total_rows": total_rows,
        "offset": offset,
        "truncated": offset + row_count < total_rows,
        "note": (
            f"Returned {row_count} of {total_rows} rows"
            f" (limit {effective_limit}, offset {offset})."
            " Use offset to page, or columns=[...] to narrow."
        ),
    }
    if units is not None:
        response["units"] = units
    return response

git add packages/ionworks-mcp/ionworks_mcp/serialize.py packages/ionworks-mcp/tests/test_serialize.py
git commit -m "feat(ionworks-mcp): JSON serialization with DataFrame row-windowing"

from mcp.server.fastmcp import FastMCP

from ionworks_mcp.serialize import serialize_list, serialize_model
from ionworks_mcp.tools import cells, discovery
from tests._fakes import FakeModel, FakePaginatedList


def _tool_fns(register, fake, monkeypatch):
    """Register a module's tools on a throwaway FastMCP and return {name: fn}.

    Uses the tool-enumeration accessor confirmed in Task 1 Step 6
    (``mcp._tool_manager.list_tools()`` with ``.name``/``.fn``); if Task 1
    recorded a different accessor for the resolved ``mcp`` version, use that
    form here instead.
    """
    import ionworks_mcp.client as client_mod

    monkeypatch.setattr(client_mod, "get_client", lambda: fake)
    mcp = FastMCP("test")
    register(mcp)
    return {t.name: t.fn for t in mcp._tool_manager.list_tools()}


def test_discover_capabilities(fake_client, monkeypatch):
    fns = _tool_fns(discovery.register, fake_client, monkeypatch)
    out = fns["discover_capabilities"]()
    assert out["name"] == "Ionworks"


def test_list_cell_specs_delegates_and_serializes(fake_client, monkeypatch):
    captured = {}

    def fake_list(include_components=False, limit=None, offset=None, **kw):
        captured.update(dict(include_components=include_components, limit=limit, offset=offset, **kw))
        return FakePaginatedList([FakeModel({"id": "spec-1"})], total=1)

    fake_client.cell_spec.list = fake_list
    fns = _tool_fns(cells.register, fake_client, monkeypatch)

    out = fns["list_cell_specs"](name="foo", limit=10, offset=0)
    assert out["items"] == [{"id": "spec-1"}]
    assert out["total"] == 1
    assert captured["name"] == "foo"
    assert captured["limit"] == 10


def test_get_cell_spec_delegates(fake_client, monkeypatch):
    # No **kw: asserts the tool calls get() with exactly the SDK signature
    # (cell_spec_id only). If the tool passed include_components, this raises.
    fake_client.cell_spec.get = lambda cell_spec_id: FakeModel({"id": cell_spec_id})
    fns = _tool_fns(cells.register, fake_client, monkeypatch)
    out = fns["get_cell_spec"](cell_spec_id="spec-9")
    assert out == {"id": "spec-9"}


def test_list_cell_instances_passes_required_id(fake_client, monkeypatch):
    captured = {}

    def fake_list(cell_spec_id, limit=None, offset=None, **kw):
        captured["cell_spec_id"] = cell_spec_id
        return FakePaginatedList([], total=0)

    fake_client.cell_instance.list = fake_list
    fns = _tool_fns(cells.register, fake_client, monkeypatch)
    fns["list_cell_instances"](cell_spec_id="spec-1")
    assert captured["cell_spec_id"] == "spec-1"


def test_list_measurements_error_wrapped(fake_client, monkeypatch):
    from ionworks import IonworksError

    def boom(cell_instance_id, **kw):
        raise IonworksError("boom")

    fake_client.cell_measurement.list = boom
    fns = _tool_fns(cells.register, fake_client, monkeypatch)
    out = fns["list_measurements"](cell_instance_id="ci-1")
    assert out["error"]["code"] == "IonworksError"

"""Discovery tool: platform capabilities and domain context."""

from __future__ import annotations

from ionworks_mcp import client as client_mod
from ionworks_mcp.errors import tool_errors


def register(mcp) -> None:
    @mcp.tool()
    @tool_errors
    def discover_capabilities() -> dict:
        """Return Ionworks platform capabilities, data hierarchy, and key concepts.

        Call this first to understand the entity hierarchy (cell specification →
        instance → measurement → time-series/steps/cycles) and available schemas.
        """
        return client_mod.get_client().capabilities()

"""Cell-data hierarchy tools: specifications, instances, measurements."""

from __future__ import annotations

from ionworks_mcp import client as client_mod
from ionworks_mcp.errors import tool_errors
from ionworks_mcp.serialize import serialize_list, serialize_model


def register(mcp) -> None:
    @mcp.tool()
    @tool_errors
    def list_cell_specs(
        name: str | None = None,
        form_factor: str | None = None,
        include_components: bool = False,
        limit: int = 25,
        offset: int = 0,
    ) -> dict:
        """List cell specifications (blueprints: chemistry, form factor, ratings)."""
        result = client_mod.get_client().cell_spec.list(
            include_components=include_components,
            limit=limit,
            offset=offset,
            name=name,
            form_factor=form_factor,
        )
        return serialize_list(result, offset=offset)

    @mcp.tool()
    @tool_errors
    def get_cell_spec(cell_spec_id: str) -> dict:
        """Get one cell specification by id.

        (The SDK's ``cell_spec.get`` returns the full spec; there is no
        ``include_components`` toggle at the get level — use ``list_cell_specs``
        with ``include_components=True`` for nested component/material data.)
        """
        return serialize_model(client_mod.get_client().cell_spec.get(cell_spec_id))

    @mcp.tool()
    @tool_errors
    def list_cell_instances(
        cell_spec_id: str,
        name: str | None = None,
        limit: int = 25,
        offset: int = 0,
    ) -> dict:
        """List physical cell instances built from a given specification."""
        result = client_mod.get_client().cell_instance.list(
            cell_spec_id, limit=limit, offset=offset, name=name
        )
        return serialize_list(result, offset=offset)

    @mcp.tool()
    @tool_errors
    def get_cell_instance(cell_instance_id: str) -> dict:
        """Get one physical cell instance by id."""
        return serialize_model(
            client_mod.get_client().cell_instance.get(cell_instance_id)
        )

    @mcp.tool()
    @tool_errors
    def list_measurements(
        cell_instance_id: str,
        name: str | None = None,
        measurement_type: str | None = None,
        limit: int = 25,
        offset: int = 0,
    ) -> dict:
        """List measurements (tests/experiments) for a cell instance."""
        result = client_mod.get_client().cell_measurement.list(
            cell_instance_id,
            limit=limit,
            offset=offset,
            measurement_type=measurement_type,
            name=name,
        )
        return serialize_list(result, offset=offset)

    @mcp.tool()
    @tool_errors
    def get_measurement(measurement_id: str) -> dict:
        """Get one measurement's metadata by id."""
        return serialize_model(
            client_mod.get_client().cell_measurement.get(measurement_id)
        )

"""Tool registration: wire every tool module onto the FastMCP instance."""

from __future__ import annotations

from ionworks_mcp.tools import cells, discovery, materials, measurement_data


def register_all(mcp) -> None:
    discovery.register(mcp)
    cells.register(mcp)
    measurement_data.register(mcp)
    materials.register(mcp)

"""Stub — filled in a later task."""

def register(mcp) -> None:  # noqa: D401
    pass

git add packages/ionworks-mcp/ionworks_mcp/tools/ packages/ionworks-mcp/tests/test_tools.py
git commit -m "feat(ionworks-mcp): discovery + cell hierarchy tools"

from ionworks_mcp.tools import measurement_data


def test_time_series_windows_and_projects(fake_client, monkeypatch, sample_df):
    fake_client.cell_measurement.time_series = lambda mid, **kw: sample_df
    fns = _tool_fns(measurement_data.register, fake_client, monkeypatch)
    out = fns["get_measurement_time_series"](
        measurement_id="m-1", columns=["Time [s]", "Voltage [V]"], limit=2, offset=0
    )
    assert out["total_rows"] == 3
    assert out["row_count"] == 2
    assert out["truncated"] is True
    assert set(out["columns"]) == {"Time [s]", "Voltage [V]"}


def test_steps_delegates(fake_client, monkeypatch, sample_df):
    fake_client.cell_measurement.steps = lambda mid, **kw: sample_df
    fns = _tool_fns(measurement_data.register, fake_client, monkeypatch)
    out = fns["get_measurement_steps"](measurement_id="m-1")
    assert out["total_rows"] == 3


def test_cycles_delegates(fake_client, monkeypatch, sample_df):
    fake_client.cell_measurement.cycles = lambda mid, **kw: sample_df
    fns = _tool_fns(measurement_data.register, fake_client, monkeypatch)
    out = fns["get_measurement_cycles"](measurement_id="m-1")
    assert out["total_rows"] == 3


def test_time_series_unknown_column_is_bad_request(fake_client, monkeypatch, sample_df):
    fake_client.cell_measurement.time_series = lambda mid, **kw: sample_df
    fns = _tool_fns(measurement_data.register, fake_client, monkeypatch)
    out = fns["get_measurement_time_series"](measurement_id="m-1", columns=["nope"])
    assert out["error"]["code"] == "BadRequest"

"""Measurement time-series / steps / cycles tools (row-windowed)."""

from __future__ import annotations

from ionworks_mcp import client as client_mod
from ionworks_mcp.errors import tool_errors
from ionworks_mcp.serialize import DEFAULT_ROW_LIMIT, serialize_dataframe


def register(mcp) -> None:
    @mcp.tool()
    @tool_errors
    def get_measurement_time_series(
        measurement_id: str,
        columns: list[str] | None = None,
        limit: int = DEFAULT_ROW_LIMIT,
        offset: int = 0,
    ) -> dict:
        """Get measurement time-series data (row-windowed; use columns/offset to narrow)."""
        df = client_mod.get_client().cell_measurement.time_series(measurement_id)
        return serialize_dataframe(df, columns=columns, limit=limit, offset=offset)

    @mcp.tool()
    @tool_errors
    def get_measurement_steps(
        measurement_id: str,
        columns: list[str] | None = None,
        limit: int = DEFAULT_ROW_LIMIT,
        offset: int = 0,
    ) -> dict:
        """Get per-step summary data for a measurement (row-windowed)."""
        df = client_mod.get_client().cell_measurement.steps(measurement_id)
        return serialize_dataframe(df, columns=columns, limit=limit, offset=offset)

    @mcp.tool()
    @tool_errors
    def get_measurement_cycles(
        measurement_id: str,
        columns: list[str] | None = None,
        limit: int = DEFAULT_ROW_LIMIT,
        offset: int = 0,
    ) -> dict:
        """Get per-cycle metrics for a measurement (row-windowed)."""
        df = client_mod.get_client().cell_measurement.cycles(measurement_id)
        return serialize_dataframe(df, columns=columns, limit=limit, offset=offset)

git add packages/ionworks-mcp/ionworks_mcp/tools/measurement_data.py packages/ionworks-mcp/tests/test_tools.py
git commit -m "feat(ionworks-mcp): measurement time-series/steps/cycles tools"

from ionworks_mcp.tools import materials


def test_list_materials_delegates(fake_client, monkeypatch):
    fake_client.material.list = lambda limit=None, offset=None, project_id=None: FakePaginatedList(
        [FakeModel({"id": "mat-1"})], total=1
    )
    fns = _tool_fns(materials.register, fake_client, monkeypatch)
    out = fns["list_materials"]()
    assert out["items"] == [{"id": "mat-1"}]


def test_get_material_delegates(fake_client, monkeypatch):
    fake_client.material.get = lambda material_id: FakeModel({"id": material_id})
    fns = _tool_fns(materials.register, fake_client, monkeypatch)
    assert fns["get_material"](material_id="mat-9") == {"id": "mat-9"}


def test_list_property_datasets_requires_material_id(fake_client, monkeypatch):
    captured = {}
    fake_client.material_property_dataset.list = (
        lambda material_id, project_id=None, limit=None, offset=None: captured.update(
            material_id=material_id
        )
        or FakePaginatedList([], total=0)
    )
    fns = _tool_fns(materials.register, fake_client, monkeypatch)
    fns["list_material_property_datasets"](material_id="mat-1")
    assert captured["material_id"] == "mat-1"


def test_get_property_data_merges_units(fake_client, monkeypatch, sample_df):
    fake_client.material_property_dataset.get_data = lambda dataset_id: sample_df
    fake_client.material_property_dataset.get_units = lambda dataset_id: {"Voltage [V]": "V"}
    fns = _tool_fns(materials.register, fake_client, monkeypatch)
    out = fns["get_material_property_data"](dataset_id="d-1")
    assert out["units"] == {"Voltage [V]": "V"}
    assert out["total_rows"] == 3

"""Materials and material-property-dataset tools."""

from __future__ import annotations

from ionworks_mcp import client as client_mod
from ionworks_mcp.errors import tool_errors
from ionworks_mcp.serialize import (
    DEFAULT_ROW_LIMIT,
    serialize_dataframe,
    serialize_list,
    serialize_model,
)


def register(mcp) -> None:
    @mcp.tool()
    @tool_errors
    def list_materials(
        project_id: str | None = None, limit: int = 25, offset: int = 0
    ) -> dict:
        """List materials for the organization (optionally scope counts to a project)."""
        result = client_mod.get_client().material.list(
            limit=limit, offset=offset, project_id=project_id
        )
        return serialize_list(result, offset=offset)

    @mcp.tool()
    @tool_errors
    def get_material(material_id: str) -> dict:
        """Get one material by id."""
        return serialize_model(client_mod.get_client().material.get(material_id))

    @mcp.tool()
    @tool_errors
    def list_material_property_datasets(
        material_id: str,
        project_id: str | None = None,
        limit: int = 25,
        offset: int = 0,
    ) -> dict:
        """List property datasets for a given material."""
        result = client_mod.get_client().material_property_dataset.list(
            material_id, project_id=project_id, limit=limit, offset=offset
        )
        return serialize_list(result, offset=offset)

    @mcp.tool()
    @tool_errors
    def get_material_property_dataset(dataset_id: str) -> dict:
        """Get one material property dataset's metadata by id."""
        return serialize_model(
            client_mod.get_client().material_property_dataset.get(dataset_id)
        )

    @mcp.tool()
    @tool_errors
    def get_material_property_data(
        dataset_id: str,
        columns: list[str] | None = None,
        limit: int = DEFAULT_ROW_LIMIT,
        offset: int = 0,
    ) -> dict:
        """Get a property dataset's tabular data (row-windowed) with column units."""
        client = client_mod.get_client()
        df = client.material_property_dataset.get_data(dataset_id)
        units = client.material_property_dataset.get_units(dataset_id)
        return serialize_dataframe(
            df, columns=columns, limit=limit, offset=offset, units=units
        )

git add packages/ionworks-mcp/ionworks_mcp/tools/materials.py packages/ionworks-mcp/tests/test_tools.py
git commit -m "feat(ionworks-mcp): materials + property-dataset tools"

from ionworks_mcp.server import build_server

EXPECTED_TOOLS = {
    "discover_capabilities",
    "list_cell_specs",
    "get_cell_spec",
    "list_cell_instances",
    "get_cell_instance",
    "list_measurements",
    "get_measurement",
    "get_measurement_time_series",
    "get_measurement_steps",
    "get_measurement_cycles",
    "list_materials",
    "get_material",
    "list_material_property_datasets",
    "get_material_property_dataset",
    "get_material_property_data",
}


def test_all_fifteen_tools_registered():
    mcp = build_server()
    names = {t.name for t in mcp._tool_manager.list_tools()}
    assert names == EXPECTED_TOOLS
    assert len(names) == 15


def test_tool_schema_exposes_real_params():
    # Guards against @tool_errors erasing annotations, which would make every
    # tool advertise (*args, **kwargs) and silently break MCP schema discovery.
    mcp = build_server()
    tools = {t.name: t for t in mcp._tool_manager.list_tools()}
    schema = tools["list_cell_specs"].parameters  # JSON Schema dict
    props = set(schema.get("properties", {}))
    assert {"name", "form_factor", "include_components", "limit", "offset"} <= props

"""FastMCP server assembly and stdio entry point."""

from __future__ import annotations

from mcp.server.fastmcp import FastMCP

from ionworks_mcp.tools import register_all


def build_server() -> FastMCP:
    """Construct the FastMCP server with all read-only Ionworks tools registered."""
    mcp = FastMCP("ionworks")
    register_all(mcp)
    return mcp


def run() -> None:
    """Run the server over stdio (blocking)."""
    build_server().run()

"""Console entry point: ``ionworks-mcp`` / ``python -m ionworks_mcp``."""

from __future__ import annotations

from ionworks_mcp.server import run


def main() -> None:
    run()


if __name__ == "__main__":
    main()

git add packages/ionworks-mcp/ionworks_mcp/server.py packages/ionworks-mcp/ionworks_mcp/__main__.py packages/ionworks-mcp/tests/test_server.py
git commit -m "feat(ionworks-mcp): FastMCP server assembly + stdio entry point"

IONWORKS_API_KEY=... uv run --package ionworks-mcp python -c "from ionworks_mcp.server import build_server; m=build_server(); print(sorted(t.name for t in m._tool_manager.list_tools()))"

git add packages/ionworks-mcp/README.md
git commit -m "docs(ionworks-mcp): usage, MCP client config, and tool reference"