csp-lab 0.1.0__tar.gz

csp_lab-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+.csp-lab/
+.agents/skills/
+skills-lock.json
+/.local/
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/

csp_lab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lackim
+
+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.

csp_lab-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: csp-lab
+Version: 0.1.0
+Summary: A local CubeSat Space Protocol lab powered by libcsp
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.20
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: typer<1,>=0.15
+Description-Content-Type: text/markdown
+
+# csp-lab
+
+A local CubeSat Space Protocol lab powered by [libcsp](https://github.com/libcsp/libcsp). It runs two simulated nodes and a ZMQ hub in Docker. The Python CLI and MCP server provide the same diagnostic operations.
+
+## Requirements
+
+- Python 3.10 or newer and [uv](https://docs.astral.sh/uv/)
+- Docker with Compose
+
+The native code is built against the pinned `libcsp` v2.1 submodule. That library supports CSP protocol v1 and v2 at runtime. The Docker image uses Linux because recent libcsp releases do not provide maintained native macOS support. See [versioning policy](docs/versioning.md) for the supported combinations.
+
+## Local development
+
+```sh
+git submodule update --init --recursive
+uv sync --locked
+uv run --locked csp-lab up --protocol 2 --build
+uv run --locked csp-lab ping 2 --json
+uv run --locked csp-lab doctor --json
+uv run --locked csp-lab down
+```
+
+`--build` compiles the native image from this checkout, so it needs the libcsp submodule. Without `--build`, the CLI uses the image matching its own version from GHCR. That image becomes available after the first release.
+
+Once released, the package can run without a clone or local compilation:
+
+```sh
+uvx csp-lab up --protocol 2
+uvx csp-lab ping 2
+uvx csp-lab down
+```
+
+You can also install it with `uv tool install csp-lab` and then use `csp-lab` directly. Lab state is stored in `~/.local/state/csp-lab` or under `XDG_STATE_HOME` when set, so commands work from any directory.
+
+If a lab was started by the earlier checkout-based CLI, run `csp-lab down` from that checkout once before switching to `uvx` from another directory. The CLI recognizes and removes the earlier path-based Docker project there.
+
+To test CSP v1, start a fresh lab with `up --protocol 1`. `up` refuses to change the protocol of an existing lab; run `down` first. The two versions never share a running network.
+
+The CLI commands are `up`, `down`, `status`, `topology`, `ping <address>`, and `doctor`. `status` checks whether the hub and both nodes are running in Docker. Use `--json` for machine-readable output. `ping` and `doctor` return a nonzero exit code when a node does not respond. Addresses must be 1–31 for CSP v1 or 1–16383 for CSP v2. The demo nodes use addresses 2 and 3; the probe uses address 4.
+
+## MCP
+
+Start the lab first, then configure an MCP client to launch `csp-lab mcp` over stdio. After the package is published, the entry is:
+
+```json
+{
+  "mcpServers": {
+    "csp-lab": {
+      "command": "uvx",
+      "args": ["csp-lab", "mcp"]
+    }
+  }
+}
+```
+
+With `uv tool install`, set the command to `csp-lab` and the argument to `mcp`. GUI clients may not see the shell's `PATH`; use the full path to `uvx` or the installed `csp-lab` executable when needed. For a local clone after `uv sync`, use `/absolute/path/to/csp-lab/.venv/bin/csp-lab` as the command. Keep the lab running in a separate terminal while using the MCP tools.
+
+The stdio server provides `csp_topology`, `csp_ping`, and `csp_diagnose`. It does not expose commands that reboot, shut down, or read or write node memory. The simulated server binds only the CSP ping service port.
+
+## What is tested
+
+`uv run --locked pytest` checks protocol validation, unavailable Docker, cleanup after a failed start, and unresponsive nodes without requiring Docker. Run `uv run --locked ruff check src/csp_lab tests` and `uv run --locked mypy src/csp_lab` for lint and types. The Docker integration flow exercises real libcsp, ZMQ, CLI diagnostics, and MCP for both protocol versions:
+
+```sh
+bash test/integration.sh
+```
+
+The GitHub Actions workflow is configured to run both checks on Ubuntu with Docker Compose. The local integration script stops the lab on exit, including after a failure.
+
+## Scope and license
+
+This lab uses the pinned libcsp release as a build dependency and selects CSP v1 or v2 as a runtime protocol. It does not build against historical libcsp 1.x releases or operate mixed-version networks. ZMQ is the only transport in this lab. The project is licensed under [MIT](LICENSE); the libcsp submodule retains its own license. Image component notices are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

csp_lab-0.1.0/README.md

@@ -0,0 +1,72 @@
+# csp-lab
+
+A local CubeSat Space Protocol lab powered by [libcsp](https://github.com/libcsp/libcsp). It runs two simulated nodes and a ZMQ hub in Docker. The Python CLI and MCP server provide the same diagnostic operations.
+
+## Requirements
+
+- Python 3.10 or newer and [uv](https://docs.astral.sh/uv/)
+- Docker with Compose
+
+The native code is built against the pinned `libcsp` v2.1 submodule. That library supports CSP protocol v1 and v2 at runtime. The Docker image uses Linux because recent libcsp releases do not provide maintained native macOS support. See [versioning policy](docs/versioning.md) for the supported combinations.
+
+## Local development
+
+```sh
+git submodule update --init --recursive
+uv sync --locked
+uv run --locked csp-lab up --protocol 2 --build
+uv run --locked csp-lab ping 2 --json
+uv run --locked csp-lab doctor --json
+uv run --locked csp-lab down
+```
+
+`--build` compiles the native image from this checkout, so it needs the libcsp submodule. Without `--build`, the CLI uses the image matching its own version from GHCR. That image becomes available after the first release.
+
+Once released, the package can run without a clone or local compilation:
+
+```sh
+uvx csp-lab up --protocol 2
+uvx csp-lab ping 2
+uvx csp-lab down
+```
+
+You can also install it with `uv tool install csp-lab` and then use `csp-lab` directly. Lab state is stored in `~/.local/state/csp-lab` or under `XDG_STATE_HOME` when set, so commands work from any directory.
+
+If a lab was started by the earlier checkout-based CLI, run `csp-lab down` from that checkout once before switching to `uvx` from another directory. The CLI recognizes and removes the earlier path-based Docker project there.
+
+To test CSP v1, start a fresh lab with `up --protocol 1`. `up` refuses to change the protocol of an existing lab; run `down` first. The two versions never share a running network.
+
+The CLI commands are `up`, `down`, `status`, `topology`, `ping <address>`, and `doctor`. `status` checks whether the hub and both nodes are running in Docker. Use `--json` for machine-readable output. `ping` and `doctor` return a nonzero exit code when a node does not respond. Addresses must be 1–31 for CSP v1 or 1–16383 for CSP v2. The demo nodes use addresses 2 and 3; the probe uses address 4.
+
+## MCP
+
+Start the lab first, then configure an MCP client to launch `csp-lab mcp` over stdio. After the package is published, the entry is:
+
+```json
+{
+  "mcpServers": {
+    "csp-lab": {
+      "command": "uvx",
+      "args": ["csp-lab", "mcp"]
+    }
+  }
+}
+```
+
+With `uv tool install`, set the command to `csp-lab` and the argument to `mcp`. GUI clients may not see the shell's `PATH`; use the full path to `uvx` or the installed `csp-lab` executable when needed. For a local clone after `uv sync`, use `/absolute/path/to/csp-lab/.venv/bin/csp-lab` as the command. Keep the lab running in a separate terminal while using the MCP tools.
+
+The stdio server provides `csp_topology`, `csp_ping`, and `csp_diagnose`. It does not expose commands that reboot, shut down, or read or write node memory. The simulated server binds only the CSP ping service port.
+
+## What is tested
+
+`uv run --locked pytest` checks protocol validation, unavailable Docker, cleanup after a failed start, and unresponsive nodes without requiring Docker. Run `uv run --locked ruff check src/csp_lab tests` and `uv run --locked mypy src/csp_lab` for lint and types. The Docker integration flow exercises real libcsp, ZMQ, CLI diagnostics, and MCP for both protocol versions:
+
+```sh
+bash test/integration.sh
+```
+
+The GitHub Actions workflow is configured to run both checks on Ubuntu with Docker Compose. The local integration script stops the lab on exit, including after a failure.
+
+## Scope and license
+
+This lab uses the pinned libcsp release as a build dependency and selects CSP v1 or v2 as a runtime protocol. It does not build against historical libcsp 1.x releases or operate mixed-version networks. ZMQ is the only transport in this lab. The project is licensed under [MIT](LICENSE); the libcsp submodule retains its own license. Image component notices are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

csp_lab-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,14 @@
+# Third party notices
+
+The container image includes these components. Their original notices and license
+terms remain in the image.
+
+| Component | Source | License and notice location in the image |
+| --- | --- | --- |
+| libcsp v2.1 | [libcsp](https://github.com/libcsp/libcsp/tree/v2.1) | MIT; `/usr/share/licenses/libcsp/LICENSE` and `AUTHORS` |
+| ZeroMQ (`libzmq5`, Debian bookworm package) | [Debian package](https://packages.debian.org/bookworm/libzmq5) | LGPL-3.0+ with a special exception and package-specific terms; `/usr/share/doc/libzmq5/copyright` |
+| Debian base image and runtime packages | [Debian](https://www.debian.org/) | Individual package notices under `/usr/share/doc/` |
+
+The csp-lab source and its own MIT license are at
+`/usr/share/licenses/csp-lab/LICENSE` in the image. The installed package versions
+can be inspected with `dpkg-query -W` inside a container.

csp_lab-0.1.0/docs/versioning.md

@@ -0,0 +1,28 @@
+# Versioning policy
+
+Three version numbers matter here and they have different meanings:
+
+| Layer | Current support | How it is selected |
+| --- | --- | --- |
+| libcsp library and API | v2.1, pinned as a Git submodule commit | Build time |
+| CSP wire protocol | v1 or v2 | `csp-lab up --protocol 1` or `--protocol 2` |
+| csp-lab CLI and MCP API | 0.1.x prototype | Project release |
+
+The current image always builds against libcsp v2.1. Selecting `--protocol 1` changes the wire format used by that library; it does **not** build libcsp 1.x. The two simulated nodes and the probe always use the same protocol setting. A running lab must be stopped before switching protocols.
+
+## Updating libcsp 2.x
+
+Update the pinned submodule in a dedicated change. Check the C API and ZMQ build, then run `uv run --locked pytest` and `bash test/integration.sh` for both wire protocols. Review the generated Docker image and record the new libcsp commit in the change. Keep the CLI and MCP output compatible within a csp-lab release unless a breaking change is intentional.
+
+## Historical libcsp 1.x
+
+libcsp 1.x has materially different build and API surfaces. If support becomes useful, add a separate legacy native build and adapter, with its own pinned revision and CI job. Do not switch native library generations implicitly based on `--protocol`; that option is reserved for the wire protocol. A mixed v1/v2 network is outside this lab's scope.
+
+## Support matrix
+
+| Native library | Wire protocol | Status |
+| --- | --- | --- |
+| libcsp v2.1 | CSP v1 | Tested locally; covered by the CI workflow |
+| libcsp v2.1 | CSP v2 | Tested locally; covered by the CI workflow |
+| libcsp 1.x | CSP v1 | Unsupported |
+| Any library | Mixed CSP v1/v2 in one lab | Unsupported |

csp_lab-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "csp-lab"
+version = "0.1.0"
+description = "A local CubeSat Space Protocol lab powered by libcsp"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+  "mcp>=1.20,<2",
+  "pydantic>=2.10,<3",
+  "typer>=0.15,<1",
+]
+
+[project.scripts]
+csp-lab = "csp_lab.cli:run_cli"
+
+[dependency-groups]
+dev = [
+  "mypy>=1.15,<2",
+  "pytest>=8,<10",
+  "ruff>=0.11,<1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/csp_lab"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/csp_lab", "THIRD_PARTY_NOTICES.md", "docs/versioning.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "S602", "S605"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/csp_lab"]

csp_lab-0.1.0/src/csp_lab/__init__.py

@@ -0,0 +1,6 @@
+"""Public models and lab operations for the local CSP lab."""
+
+from csp_lab.docker import diagnose, down, ping, status, topology, up
+from csp_lab.models import LabState, PingResult
+
+__all__ = ["LabState", "PingResult", "diagnose", "down", "ping", "status", "topology", "up"]

csp_lab-0.1.0/src/csp_lab/cli.py

@@ -0,0 +1,191 @@
+"""Command-line interface for the local CSP lab."""
+
+import json
+import sys
+from collections.abc import Callable
+from importlib.metadata import version
+from typing import TypeVar
+
+import typer
+from pydantic import BaseModel
+
+from csp_lab import docker
+from csp_lab.models import PingResult
+
+ResultT = TypeVar("ResultT")
+
+app = typer.Typer(
+    name="csp-lab",
+    help="Local CubeSat Space Protocol lab",
+    add_completion=False,
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _show_version(value: bool) -> bool:
+    if value:
+        print(version("csp-lab"))
+        raise typer.Exit()
+    return value
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+    show_version: bool = typer.Option(
+        False, "-V", "--version", callback=_show_version, is_eager=True
+    ),
+) -> None:
+    """Global output options."""
+    ctx.obj = json_output
+
+
+def _json(ctx: typer.Context, local: bool) -> bool:
+    return bool(ctx.obj) or local
+
+
+def _emit(value: BaseModel | dict[str, object], json_output: bool) -> None:
+    data = value.model_dump(by_alias=True) if isinstance(value, BaseModel) else value
+    print(
+        json.dumps(
+            data,
+            indent=None if json_output else 2,
+            separators=(",", ":") if json_output else None,
+            ensure_ascii=False,
+        )
+    )
+
+
+def _action(operation: Callable[[], ResultT], json_output: bool) -> ResultT:
+    try:
+        return operation()
+    except Exception as exc:
+        message = str(exc)
+        if json_output:
+            print(json.dumps({"error": message}, separators=(",", ":"), ensure_ascii=False))
+        else:
+            print(f"csp-lab: {message}", file=sys.stderr)
+        raise typer.Exit(code=1) from exc
+
+
+@app.command()
+def up(
+    ctx: typer.Context,
+    protocol: str = typer.Option("2", "--protocol", help="CSP protocol version (1 or 2)"),
+    build: bool = typer.Option(False, "--build", help="Build the native image from this checkout"),
+    json_output: bool = typer.Option(False, "--json", help="Print JSON output"),
+    show_version: bool = typer.Option(
+        False, "-V", "--version", callback=_show_version, is_eager=True, hidden=True
+    ),
+) -> None:
+    """Start two libcsp nodes and a ZMQ hub."""
+    json_output = _json(ctx, json_output)
+    state = _action(lambda: docker.up(docker.parse_protocol(protocol), build), json_output)
+    data: dict[str, object] = {"started": True}
+    data.update(state.as_json())
+    _emit(data, json_output)
+
+
+@app.command()
+def down(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="Print JSON output"),
+    show_version: bool = typer.Option(
+        False, "-V", "--version", callback=_show_version, is_eager=True, hidden=True
+    ),
+) -> None:
+    """Stop the lab."""
+    json_output = _json(ctx, json_output)
+    _action(docker.down, json_output)
+    _emit({"stopped": True}, json_output)
+
+
+@app.command()
+def ping(
+    ctx: typer.Context,
+    address: str = typer.Argument(..., help="CSP address to ping"),
+    json_output: bool = typer.Option(False, "--json", help="Print JSON output"),
+    show_version: bool = typer.Option(
+        False, "-V", "--version", callback=_show_version, is_eager=True, hidden=True
+    ),
+) -> None:
+    """Ping a node using libcsp."""
+    json_output = _json(ctx, json_output)
+
+    def probe() -> PingResult:
+        state = docker.require_state()
+        return docker.ping(docker.parse_address(address, state.protocol))
+
+    result = _action(probe, json_output)
+    _emit(result, json_output)
+    if not result.reachable:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def topology(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="Print JSON output"),
+    show_version: bool = typer.Option(
+        False, "-V", "--version", callback=_show_version, is_eager=True, hidden=True
+    ),
+) -> None:
+    """Show the configured network."""
+    json_output = _json(ctx, json_output)
+    _emit(_action(docker.topology, json_output), json_output)
+
+
+@app.command()
+def doctor(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="Print JSON output"),
+    show_version: bool = typer.Option(
+        False, "-V", "--version", callback=_show_version, is_eager=True, hidden=True
+    ),
+) -> None:
+    """Test both nodes."""
+    json_output = _json(ctx, json_output)
+    result = _action(docker.diagnose, json_output)
+    _emit(result, json_output)
+    if not result.healthy:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def status(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="Print JSON output"),
+    show_version: bool = typer.Option(
+        False, "-V", "--version", callback=_show_version, is_eager=True, hidden=True
+    ),
+) -> None:
+    """Show local lab state."""
+    json_output = _json(ctx, json_output)
+    _emit(_action(docker.status, json_output), json_output)
+
+
+@app.command()
+def mcp() -> None:
+    """Serve read-only CSP diagnostics over MCP stdio."""
+    from csp_lab.mcp_server import server
+
+    server.run(transport="stdio")
+
+
+def run_cli() -> None:
+    """Map legacy help syntax and parser exit codes to the original CLI."""
+    args = sys.argv[1:]
+    if args and args[0] == "help":
+        args = [*args[1:], "--help"]
+    try:
+        app(args=args)
+    except SystemExit as exc:
+        if exc.code == 2:
+            raise SystemExit(1) from exc
+        raise
+
+
+if __name__ == "__main__":
+    run_cli()

csp_lab-0.1.0/src/csp_lab/data/compose.build.yaml

@@ -0,0 +1,11 @@
+services:
+  hub:
+    build:
+      context: ${CSP_LAB_BUILD_CONTEXT:?}
+    pull_policy: build
+  node2:
+    pull_policy: never
+  node3:
+    pull_policy: never
+  probe:
+    pull_policy: never

csp_lab-0.1.0/src/csp_lab/data/compose.yaml

@@ -0,0 +1,16 @@
+services:
+  hub:
+    image: ${CSP_LAB_IMAGE:?}
+    entrypoint: ["/usr/local/bin/zmqproxy"]
+    command: ["-v", "${CSP_VERSION:-2}"]
+  node2:
+    image: ${CSP_LAB_IMAGE:?}
+    depends_on: [hub]
+    command: ["server", "${CSP_VERSION:-2}", "2", "hub"]
+  node3:
+    image: ${CSP_LAB_IMAGE:?}
+    depends_on: [hub]
+    command: ["server", "${CSP_VERSION:-2}", "3", "hub"]
+  probe:
+    image: ${CSP_LAB_IMAGE:?}
+    profiles: ["tools"]

csp_lab-0.1.0/src/csp_lab/docker.py

@@ -0,0 +1,270 @@
+"""Docker Compose orchestration and CSP probe operations."""
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+from contextlib import ExitStack
+from importlib.metadata import version
+from importlib.resources import as_file, files
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from csp_lab.models import (
+    DiagnoseResult,
+    LabState,
+    PingResult,
+    Protocol,
+    StatusResult,
+    TopologyResult,
+)
+
+ROOT = Path(__file__).resolve().parents[2]
+STATE_HOME = Path(os.environ.get("XDG_STATE_HOME", Path.home() / ".local" / "state"))
+STATE_DIR = STATE_HOME / "csp-lab"
+STATE_FILE = STATE_DIR / "state.json"
+PROJECT = "csp-lab"
+IMAGE = "ghcr.io/lackim/csp-lab"
+
+
+def selected_image(build: bool) -> str:
+    return "csp-lab-native:local" if build else f"{IMAGE}:v{version('csp-lab')}"
+
+
+def state_image(state: LabState) -> str:
+    return state.image or selected_image(state.build)
+
+
+def state_project(state: LabState) -> str:
+    return state.project or PROJECT
+
+
+def parse_protocol(value: str) -> Protocol:
+    if value == "1":
+        return 1
+    if value == "2":
+        return 2
+    raise ValueError("Protocol must be 1 or 2.")
+
+
+def parse_address(value: str, protocol: Protocol) -> int:
+    if re.fullmatch(r"[0-9]+", value) is None:
+        raise ValueError("Address must be a decimal integer.")
+    address = int(value)
+    maximum = 31 if protocol == 1 else 16383
+    if address < 1 or address > maximum:
+        raise ValueError(f"CSP v{protocol} address must be between 1 and {maximum}.")
+    return address
+
+
+def _read_state(path: Path) -> LabState | None:
+    try:
+        content = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    try:
+        return LabState.model_validate_json(content)
+    except ValidationError as exc:
+        raise ValueError("Unsupported lab state. Run 'csp-lab down' and start again.") from exc
+
+
+def get_state() -> LabState | None:
+    state = _read_state(STATE_FILE)
+    if state is not None:
+        return state
+    for root in dict.fromkeys((ROOT, Path.cwd().resolve())):
+        legacy = _read_state(root / ".csp-lab" / "state.json")
+        if legacy is not None:
+            project = "csp-lab-" + hashlib.sha256(str(root).encode()).hexdigest()[:8]
+            return legacy.model_copy(
+                update={
+                    "build": True,
+                    "image": "csp-lab-native:local",
+                    "project": project,
+                    "legacy_root": root,
+                }
+            )
+    return None
+
+
+def require_state() -> LabState:
+    state = get_state()
+    if state is None:
+        raise RuntimeError("Lab is not started. Run 'csp-lab up --protocol 2' first.")
+    return state
+
+
+def run(
+    command: str, args: list[str], env: dict[str, str] | None = None, timeout: int = 120
+) -> str:
+    try:
+        result = subprocess.run(
+            [command, *args],
+            env={**os.environ, **(env or {})},
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise RuntimeError(f"{command} ENOENT: {exc}") from exc
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout).strip()
+        raise RuntimeError(f"{command} exited {result.returncode}: {detail}")
+    return result.stdout
+
+
+def compose(
+    args: list[str],
+    protocol: Protocol,
+    image: str | None = None,
+    timeout: int = 120,
+    build_overlay: bool = False,
+    project: str = PROJECT,
+) -> str:
+    env = {"CSP_VERSION": str(protocol), "CSP_LAB_IMAGE": image or selected_image(False)}
+    with ExitStack() as stack:
+        compose_file = stack.enter_context(as_file(files("csp_lab") / "data" / "compose.yaml"))
+        file_args = ["-f", str(compose_file)]
+        if build_overlay:
+            if not (ROOT / "Dockerfile").is_file() or not (ROOT / "vendor" / "libcsp").is_dir():
+                raise RuntimeError(
+                    "Local build requires a source checkout with the libcsp submodule."
+                )
+            build_file = stack.enter_context(
+                as_file(files("csp_lab") / "data" / "compose.build.yaml")
+            )
+            file_args.extend(["-f", str(build_file)])
+            env["CSP_LAB_BUILD_CONTEXT"] = str(ROOT)
+        return run("docker", ["compose", "-p", project, *file_args, *args], env, timeout)
+
+
+def up(protocol: Protocol, build: bool = False) -> LabState:
+    if get_state() is not None:
+        raise RuntimeError("Lab is already started. Run 'csp-lab down' before changing protocol.")
+    if build and (
+        not (ROOT / "Dockerfile").is_file() or not (ROOT / "vendor" / "libcsp").is_dir()
+    ):
+        raise RuntimeError("Local build requires a source checkout with the libcsp submodule.")
+    image = selected_image(build)
+    try:
+        pull = ["--build"] if build else ["--pull", "always"]
+        compose(
+            ["up", "-d", *pull, "hub", "node2", "node3"],
+            protocol,
+            image,
+            600,
+            build_overlay=build,
+        )
+        for target in (2, 3):
+            if not ping_with_protocol(target, protocol, image).reachable:
+                raise RuntimeError(f"Node {target} did not answer a CSP v{protocol} ping.")
+        state = LabState(
+            protocol=protocol,
+            libcspVersion="2.1",
+            build=build,
+            image=image,
+            project=PROJECT,
+        )
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        STATE_FILE.write_text(
+            json.dumps(
+                {**state.as_json(), "build": build, "image": image, "project": PROJECT},
+                indent=2,
+            )
+            + "\n",
+            encoding="utf-8",
+        )
+        return state
+    except Exception:
+        try:
+            compose(["down", "--remove-orphans"], protocol, image)
+        except Exception:
+            pass
+        shutil.rmtree(STATE_DIR, ignore_errors=True)
+        raise
+
+
+def down() -> None:
+    state = get_state()
+    compose(
+        ["down", "--remove-orphans"],
+        state.protocol if state else 2,
+        state_image(state) if state else None,
+        project=state_project(state) if state else PROJECT,
+    )
+    state_dir = state.legacy_root / ".csp-lab" if state and state.legacy_root else STATE_DIR
+    shutil.rmtree(state_dir, ignore_errors=True)
+
+
+def ping_with_protocol(
+    target: int, protocol: Protocol, image: str | None = None, project: str = PROJECT
+) -> PingResult:
+    parse_address(str(target), protocol)
+    output = compose(
+        ["run", "--rm", "--no-deps", "probe", "probe", str(protocol), "4", str(target)],
+        protocol,
+        image,
+        30,
+        project=project,
+    )
+    line = next(
+        (part for part in reversed(output.splitlines()) if part.startswith('{"target":')),
+        None,
+    )
+    if line is None:
+        raise ValueError(f"Probe returned no JSON result: {output.strip()}")
+    try:
+        result = PingResult.model_validate_json(line)
+    except ValidationError as exc:
+        raise ValueError("Probe returned an invalid result.") from exc
+    if result.target != target:
+        raise ValueError("Probe returned an invalid result.")
+    return result
+
+
+def ping(target: int) -> PingResult:
+    state = require_state()
+    return ping_with_protocol(target, state.protocol, state_image(state), state_project(state))
+
+
+def topology() -> TopologyResult:
+    state = require_state()
+    return TopologyResult(
+        protocol=state.protocol,
+        libcspVersion=state.libcsp_version,
+        nodes=[2, 3],
+        probeAddress=4,
+        transport="ZMQ",
+    )
+
+
+def diagnose() -> DiagnoseResult:
+    state = require_state()
+    nodes = [
+        ping_with_protocol(target, state.protocol, state_image(state), state_project(state))
+        for target in (2, 3)
+    ]
+    return DiagnoseResult(
+        protocol=state.protocol,
+        libcspVersion=state.libcsp_version,
+        healthy=all(node.reachable for node in nodes),
+        nodes=nodes,
+    )
+
+
+def status() -> StatusResult:
+    state = get_state()
+    if state is None:
+        return StatusResult(running=False, state=None)
+    services = compose(
+        ["ps", "--services", "--status", "running"],
+        state.protocol,
+        state_image(state),
+        project=state_project(state),
+    ).splitlines()
+    running = all(name in services for name in ("hub", "node2", "node3"))
+    return StatusResult(running=running, state=state)

csp_lab-0.1.0/src/csp_lab/mcp_server.py

@@ -0,0 +1,42 @@
+"""Read-only MCP tools for inspecting a running CSP lab."""
+
+import json
+from typing import Annotated
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from csp_lab import docker
+
+server = FastMCP("csp-lab")
+READ_ONLY = ToolAnnotations(readOnlyHint=True, openWorldHint=False)
+
+
+@server.tool(
+    name="csp_topology",
+    description="Read the configured CSP protocol version and simulated nodes",
+    annotations=READ_ONLY,
+)
+def csp_topology() -> str:
+    return json.dumps(docker.topology().as_json())
+
+
+@server.tool(
+    name="csp_ping",
+    description="Ping a simulated node through libcsp",
+    annotations=READ_ONLY,
+)
+def csp_ping(address: Annotated[int, Field(strict=True, gt=0)]) -> str:
+    state = docker.require_state()
+    target = docker.parse_address(str(address), state.protocol)
+    return json.dumps(docker.ping(target).as_json())
+
+
+@server.tool(
+    name="csp_diagnose",
+    description="Ping both nodes and summarize lab health",
+    annotations=READ_ONLY,
+)
+def csp_diagnose() -> str:
+    return json.dumps(docker.diagnose().as_json())

csp_lab-0.1.0/src/csp_lab/models.py

@@ -0,0 +1,50 @@
+"""Validated data returned by the CLI and MCP server."""
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, StrictBool
+
+Protocol = Literal[1, 2]
+
+
+class LabModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, populate_by_name=True)
+
+    def as_json(self) -> dict[str, object]:
+        return self.model_dump(by_alias=True)
+
+
+class LabState(LabModel):
+    protocol: Protocol
+    libcsp_version: Literal["2.1"] = Field(alias="libcspVersion")
+    build: bool = Field(default=False, exclude=True)
+    image: str | None = Field(default=None, exclude=True)
+    project: str | None = Field(default=None, exclude=True)
+    legacy_root: Path | None = Field(default=None, exclude=True)
+
+
+class PingResult(LabModel):
+    target: int
+    reachable: StrictBool
+    rtt_ms: int = Field(alias="rttMs")
+
+
+class StatusResult(LabModel):
+    running: bool
+    state: LabState | None
+
+
+class TopologyResult(LabModel):
+    protocol: Protocol
+    libcsp_version: Literal["2.1"] = Field(alias="libcspVersion")
+    nodes: list[int]
+    probe_address: int = Field(alias="probeAddress")
+    transport: Literal["ZMQ"]
+
+
+class DiagnoseResult(LabModel):
+    protocol: Protocol
+    libcsp_version: Literal["2.1"] = Field(alias="libcspVersion")
+    healthy: bool
+    nodes: list[PingResult]