cellpy-mcp 0.1.0__tar.gz

cellpy_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+uv.lock

cellpy_mcp-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright (c) 2026, Jan Petter Maehlen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

cellpy_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: cellpy-mcp
+Version: 0.1.0
+Summary: MCP server for cellpy — battery cell data, plots and the cellpy API, for agents and chat clients.
+Project-URL: Homepage, https://github.com/cellpy/cellpy-mcp
+Project-URL: Repository, https://github.com/cellpy/cellpy-mcp
+Project-URL: Issues, https://github.com/cellpy/cellpy-mcp/issues
+Project-URL: cellpy, https://github.com/jepegit/cellpy
+Author: cellpy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,battery,cellpy,electrochemistry,llm,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.13
+Requires-Dist: cellpy>=2.1.3
+Requires-Dist: mcp>=2.0
+Requires-Dist: plotly>=5.22
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: tables; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cellpy-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for
+[cellpy](https://github.com/jepegit/cellpy). It lets an agent — or a chat
+window — load battery cells, collect them into frames, render figures, export
+data, look up how any cellpy call works, and set up a batch project. Without
+writing any Python.
+
+```bash
+pip install cellpy-mcp
+cellpy mcp install        # register it with your chat client
+```
+
+Then restart the client and ask it to plot something.
+
+## Who it is for
+
+- **People building on cellpy** — a GUI, a script that automates cell handling.
+  The tools are the useful API, and `describe_api` gives real signatures from
+  the version you have installed.
+- **People who just want to ask.** Open a chat window, point it at a file, ask
+  for capacity versus cycle. The prompts below are pickable starting points, so
+  you do not have to know what to ask for.
+- **People who would rather not use a terminal.** `new_project` is `cellpy new`
+  without the command line.
+
+Nothing is hosted. Under stdio your chat client starts the server itself, on
+your machine, reading your files — there is no service to sign up for and
+nothing leaves the machine except what you paste into the chat.
+
+## What it can do
+
+Cells and figures:
+
+| Tool | What it gives you |
+|---|---|
+| `list_instruments` | loaders, and whether each can actually run on this machine |
+| `load_cell` | a handle, cycle count, mass, summary column names |
+| `list_cells` | what is loaded |
+| `describe_plot_families` | the 20 summary families, marked available or missing-columns |
+| `collect` | a handle, row count, columns, `is_grouped`, direction counts |
+| `preview_collection` | a few rows, capped at 20 |
+| `render` | writes a figure; returns trace types and points plotted |
+| `export_collection` | writes csv/parquet/json; returns rows and bytes |
+
+The cellpy API — "how does this call work, and what are its arguments":
+
+| Tool | What it gives you |
+|---|---|
+| `search_api` | calls matching a name or a docstring line |
+| `describe_api` | signature, argument types and defaults, docstring, `undocumented_parameters`, optionally source |
+
+Batch templating:
+
+| Tool | What it gives you |
+|---|---|
+| `list_templates` | registered and local templates, and which is the default |
+| `new_project` | a project from a template; returns the notebooks it made |
+
+Prompts: `analyse_cell`, `start_batch_project`, `explain_call`.
+
+## Where it may read and write
+
+Everything is confined to a set of roots, and both reads and writes are checked
+— an unchecked write would make the read check decoration.
+
+By default the roots are the directories cellpy already knows about
+(`rawdatadir`, `cellpydatadir`, `outdatadir`, `notebookdir`), because you told
+cellpy where your data is when you set it up. Override with `CELLPY_MCP_ROOT`,
+which takes several directories separated the way `PATH` separates them:
+
+```bash
+CELLPY_MCP_ROOT=/data/cells:/data/out cellpy mcp serve
+```
+
+Roots that are not plain local directories are dropped: `rawdatadir` is often
+`scp://host/…`, and containment here is `pathlib`-based and cannot express
+"inside that remote share". If cellpy has no configured paths at all, the
+single root is `~/cellpy_mcp` — never your whole filesystem.
+
+## Four things it does on purpose
+
+**Handles, not data.** Only `preview_collection` returns rows. A tool result
+goes into a model's context window, and one collected summary is ~29 kB of CSV
+while a raw figure can be several MB.
+
+**Results carry the traps.** `render` returns `trace_types` alongside
+`points_plotted` and `rows_collected`, so an agent that asked for a density film
+can see it got `histogram2d` rather than lines, and one that forgot
+`direction="both"` can see it plotted 891 of 2328 rows. `describe_api` returns
+`undocumented_parameters` for the same reason: cellpy documents about half its
+arguments, and a model should know when the package never said.
+
+**It follows the docstring's own cross-references.** `CellpyCell.get_cap` takes
+23 arguments, documents none, and points at
+`cellpy.readers.capacity_curves.get_cap` — which documents 22 of 24. Following
+that takes argument coverage across the documented API from 51% to 72%. Only a
+docs site resolves those markers; nobody reading a docstring does.
+
+**One client per process.** State is process-wide, deliberately: the MCP SDK
+does not give a tool a stable session identity, and under stdio each client
+spawns its own process anyway. Do not put this behind a shared HTTP endpoint as
+written.
+
+## Limits worth knowing
+
+- `load_cell` blocks, with no progress and no cancellation, so a slow load can
+  look like a hang to a client. This is the gap most worth closing.
+- No quota and no eviction: an agent can fill the sandbox with figures, and
+  cells stay in memory until the process exits.
+- `new_project` has to create the project directory itself, because `cellpy new`
+  prompts even with `no_input=True`
+  ([cellpy#990](https://github.com/jepegit/cellpy/issues/990)). It also
+  downloads a cookiecutter from GitHub on first use.
+
+## Running it without cellpy's shim
+
+`cellpy mcp serve` needs cellpy 2.2 or newer. Otherwise:
+
+```bash
+python -m cellpy_mcp serve
+python -m cellpy_mcp install --dry-run
+python -m cellpy_mcp status
+```
+
+## Background
+
+The design, the measurements behind it, and a two-round prototype log are in
+[cellpy#840](https://github.com/jepegit/cellpy/issues/840).
+
+MIT licensed.

cellpy_mcp-0.1.0/README.md

@@ -0,0 +1,131 @@
+# cellpy-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for
+[cellpy](https://github.com/jepegit/cellpy). It lets an agent — or a chat
+window — load battery cells, collect them into frames, render figures, export
+data, look up how any cellpy call works, and set up a batch project. Without
+writing any Python.
+
+```bash
+pip install cellpy-mcp
+cellpy mcp install        # register it with your chat client
+```
+
+Then restart the client and ask it to plot something.
+
+## Who it is for
+
+- **People building on cellpy** — a GUI, a script that automates cell handling.
+  The tools are the useful API, and `describe_api` gives real signatures from
+  the version you have installed.
+- **People who just want to ask.** Open a chat window, point it at a file, ask
+  for capacity versus cycle. The prompts below are pickable starting points, so
+  you do not have to know what to ask for.
+- **People who would rather not use a terminal.** `new_project` is `cellpy new`
+  without the command line.
+
+Nothing is hosted. Under stdio your chat client starts the server itself, on
+your machine, reading your files — there is no service to sign up for and
+nothing leaves the machine except what you paste into the chat.
+
+## What it can do
+
+Cells and figures:
+
+| Tool | What it gives you |
+|---|---|
+| `list_instruments` | loaders, and whether each can actually run on this machine |
+| `load_cell` | a handle, cycle count, mass, summary column names |
+| `list_cells` | what is loaded |
+| `describe_plot_families` | the 20 summary families, marked available or missing-columns |
+| `collect` | a handle, row count, columns, `is_grouped`, direction counts |
+| `preview_collection` | a few rows, capped at 20 |
+| `render` | writes a figure; returns trace types and points plotted |
+| `export_collection` | writes csv/parquet/json; returns rows and bytes |
+
+The cellpy API — "how does this call work, and what are its arguments":
+
+| Tool | What it gives you |
+|---|---|
+| `search_api` | calls matching a name or a docstring line |
+| `describe_api` | signature, argument types and defaults, docstring, `undocumented_parameters`, optionally source |
+
+Batch templating:
+
+| Tool | What it gives you |
+|---|---|
+| `list_templates` | registered and local templates, and which is the default |
+| `new_project` | a project from a template; returns the notebooks it made |
+
+Prompts: `analyse_cell`, `start_batch_project`, `explain_call`.
+
+## Where it may read and write
+
+Everything is confined to a set of roots, and both reads and writes are checked
+— an unchecked write would make the read check decoration.
+
+By default the roots are the directories cellpy already knows about
+(`rawdatadir`, `cellpydatadir`, `outdatadir`, `notebookdir`), because you told
+cellpy where your data is when you set it up. Override with `CELLPY_MCP_ROOT`,
+which takes several directories separated the way `PATH` separates them:
+
+```bash
+CELLPY_MCP_ROOT=/data/cells:/data/out cellpy mcp serve
+```
+
+Roots that are not plain local directories are dropped: `rawdatadir` is often
+`scp://host/…`, and containment here is `pathlib`-based and cannot express
+"inside that remote share". If cellpy has no configured paths at all, the
+single root is `~/cellpy_mcp` — never your whole filesystem.
+
+## Four things it does on purpose
+
+**Handles, not data.** Only `preview_collection` returns rows. A tool result
+goes into a model's context window, and one collected summary is ~29 kB of CSV
+while a raw figure can be several MB.
+
+**Results carry the traps.** `render` returns `trace_types` alongside
+`points_plotted` and `rows_collected`, so an agent that asked for a density film
+can see it got `histogram2d` rather than lines, and one that forgot
+`direction="both"` can see it plotted 891 of 2328 rows. `describe_api` returns
+`undocumented_parameters` for the same reason: cellpy documents about half its
+arguments, and a model should know when the package never said.
+
+**It follows the docstring's own cross-references.** `CellpyCell.get_cap` takes
+23 arguments, documents none, and points at
+`cellpy.readers.capacity_curves.get_cap` — which documents 22 of 24. Following
+that takes argument coverage across the documented API from 51% to 72%. Only a
+docs site resolves those markers; nobody reading a docstring does.
+
+**One client per process.** State is process-wide, deliberately: the MCP SDK
+does not give a tool a stable session identity, and under stdio each client
+spawns its own process anyway. Do not put this behind a shared HTTP endpoint as
+written.
+
+## Limits worth knowing
+
+- `load_cell` blocks, with no progress and no cancellation, so a slow load can
+  look like a hang to a client. This is the gap most worth closing.
+- No quota and no eviction: an agent can fill the sandbox with figures, and
+  cells stay in memory until the process exits.
+- `new_project` has to create the project directory itself, because `cellpy new`
+  prompts even with `no_input=True`
+  ([cellpy#990](https://github.com/jepegit/cellpy/issues/990)). It also
+  downloads a cookiecutter from GitHub on first use.
+
+## Running it without cellpy's shim
+
+`cellpy mcp serve` needs cellpy 2.2 or newer. Otherwise:
+
+```bash
+python -m cellpy_mcp serve
+python -m cellpy_mcp install --dry-run
+python -m cellpy_mcp status
+```
+
+## Background
+
+The design, the measurements behind it, and a two-round prototype log are in
+[cellpy#840](https://github.com/jepegit/cellpy/issues/840).
+
+MIT licensed.

cellpy_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "cellpy-mcp"
+# Single-sourced from the package, so a release cannot ship a wheel whose
+# metadata and __version__ disagree — see [tool.hatch.version] below.
+dynamic = ["version"]
+description = "MCP server for cellpy — battery cell data, plots and the cellpy API, for agents and chat clients."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+# cellpy itself requires >= 3.13, so this cannot be lower however much the MCP
+# SDK would allow (it takes 3.10).
+requires-python = ">=3.13"
+authors = [{ name = "cellpy" }]
+keywords = ["battery", "electrochemistry", "cellpy", "mcp", "agents", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Chemistry",
+]
+
+dependencies = [
+    "cellpy>=2.1.3",
+    "mcp>=2.0",
+    "plotly>=5.22",
+]
+
+[project.urls]
+Homepage = "https://github.com/cellpy/cellpy-mcp"
+Repository = "https://github.com/cellpy/cellpy-mcp"
+Issues = "https://github.com/cellpy/cellpy-mcp/issues"
+cellpy = "https://github.com/jepegit/cellpy"
+
+[project.scripts]
+# `cellpy mcp serve` is the discoverable spelling and goes through cellpy's
+# shim. This is the same thing without it — useful in a client config, where
+# naming the executable directly is one less layer to get wrong.
+cellpy-mcp = "cellpy_mcp.__main__:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "tables"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/cellpy_mcp/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cellpy_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+markers = [
+    "essential: critical-path tests run in GitHub Actions CI",
+    "network: needs the network (a cookiecutter clone); deselected in CI",
+]

cellpy_mcp-0.1.0/src/cellpy_mcp/__init__.py

@@ -0,0 +1,83 @@
+"""An MCP server for cellpy — battery cell data, plots, and the cellpy API.
+
+Four things a caller can do without writing Python: load cells and collect them
+into frames; render figures and export data; ask what any cellpy call takes and
+what its arguments mean; and set up a batch project from a template.
+
+**This module is the contract `cellpy mcp` depends on.** cellpy ships a thin
+command group (`cellpy mcp serve | install | status`) that imports this package
+and, when it is absent, says how to install it. cellpy deliberately does not
+depend on the MCP SDK — it is young and moving, and a long-lived network-facing
+process is a security surface a data library should not carry — so the four
+names below are load-bearing across a repository boundary. Changing them
+without changing cellpy breaks the command:
+
+    __version__
+    serve(root=None)
+    install(root=None, client=None, dry_run=False) -> str
+    describe() -> dict
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__", "serve", "install", "describe", "build_server", "Sandbox"]
+
+
+def build_server(sandbox=None, state=None):
+    """An `MCPServer` with every tool and prompt registered."""
+    from .server import build_server as _build
+
+    return _build(sandbox=sandbox, state=state)
+
+
+def serve(root: str | Path | None = None) -> None:
+    """Run the server over stdio. Blocks until the client disconnects.
+
+    Prints nothing: stdout *is* the protocol channel, and a friendly banner on
+    it is a parse error at the other end.
+    """
+    from .sandbox import Sandbox
+
+    build_server(Sandbox.from_environment(root)).run(transport="stdio")
+
+
+def install(
+    root: str | Path | None = None,
+    client: str | None = None,
+    dry_run: bool = False,
+) -> str:
+    """Register this server with a chat client; return the path written."""
+    from .clients import install as _install
+    from .sandbox import Sandbox
+
+    return _install(Sandbox.from_environment(root).roots, client=client, dry_run=dry_run)
+
+
+def describe() -> dict:
+    """What `cellpy mcp status` reports beyond the two version numbers."""
+    from .clients import config_path
+    from .sandbox import Sandbox
+
+    sandbox = Sandbox.from_environment()
+    described = {"roots": ", ".join(str(root) for root in sandbox.roots)}
+    try:
+        target = config_path()
+    except ValueError:  # pragma: no cover - only if CLIENTS shrinks
+        return described
+    described["client config"] = f"{target}{'' if target.exists() else ' (not present)'}"
+    return described
+
+
+def __getattr__(name: str):
+    # `Sandbox` is re-exported for callers who want to build a server with an
+    # explicit set of roots, but importing it eagerly would drag cellpy's
+    # config in just because someone imported the package.
+    if name == "Sandbox":
+        from .sandbox import Sandbox
+
+        return Sandbox
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

cellpy_mcp-0.1.0/src/cellpy_mcp/__main__.py

@@ -0,0 +1,61 @@
+"""`python -m cellpy_mcp` — what a chat client spawns.
+
+`cellpy mcp serve` is the discoverable spelling and goes through cellpy's shim.
+This is the same thing without it, and it is what `install` writes into a client
+config: naming the interpreter and the module directly is one fewer layer to be
+wrong about when a GUI launches it from nowhere in particular.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="cellpy-mcp", description="MCP server for cellpy."
+    )
+    subcommands = parser.add_subparsers(dest="command")
+
+    serve = subcommands.add_parser("serve", help="run over stdio (the default)")
+    serve.add_argument("--root", help="a directory the server may read and write")
+
+    install = subcommands.add_parser("install", help="register with a chat client")
+    install.add_argument("--root", help="a directory the server may read and write")
+    install.add_argument("--client", help="which chat client to register with")
+    install.add_argument(
+        "--dry-run", action="store_true", help="print the target instead of writing"
+    )
+
+    subcommands.add_parser("status", help="report the roots and the client config")
+
+    args = parser.parse_args(argv)
+
+    from . import describe, install as do_install, serve as do_serve
+
+    # No subcommand means serve: a client config that says `-m cellpy_mcp` and
+    # nothing else must start a server, not print usage to the protocol channel.
+    if args.command in (None, "serve"):
+        do_serve(root=getattr(args, "root", None))
+        return 0
+
+    if args.command == "install":
+        try:
+            target = do_install(root=args.root, client=args.client, dry_run=args.dry_run)
+        except ValueError as exc:
+            print(exc, file=sys.stderr)
+            return 1
+        verb = "would register" if args.dry_run else "registered"
+        print(f"{verb} 'cellpy' in {target}")
+        if not args.dry_run:
+            print("restart the client to pick it up.")
+        return 0
+
+    for key, value in describe().items():
+        print(f"{key}: {value}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())