nextmv 1.3.1.dev0__tar.gz → 1.3.1.dev2__tar.gz

{nextmv-1.3.1.dev0 → nextmv-1.3.1.dev2}/.gitignore

@@ -168,4 +168,3 @@ cython_debug/
 site/
 
 scratch
-.claude

{nextmv-1.3.1.dev0 → nextmv-1.3.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 1.3.1.dev0
+Version: 1.3.1.dev2
 Summary: The all-purpose Python SDK for Nextmv
 Project-URL: Homepage, https://www.nextmv.io
 Project-URL: Documentation, https://nextmv-py.docs.nextmv.io/en/latest/nextmv/
@@ -227,10 +227,6 @@ Requires-Dist: questionary>=2.1.1
 Requires-Dist: requests>=2.31.0
 Requires-Dist: typer>=0.20.1
 Requires-Dist: urllib3>=2.1.0
-Provides-Extra: all
-Requires-Dist: folium>=0.20.0; extra == 'all'
-Requires-Dist: mcp[cli]>=1.0; extra == 'all'
-Requires-Dist: plotly>=6.0.1; extra == 'all'
 Provides-Extra: mcp
 Requires-Dist: mcp[cli]>=1.0; extra == 'mcp'
 Provides-Extra: notebook

nextmv-1.3.1.dev2/nextmv/__about__.py

@@ -0,0 +1 @@
+__version__ = "v1.3.1.dev2"

{nextmv-1.3.1.dev0 → nextmv-1.3.1.dev2}/nextmv/cli/main.py

@@ -27,7 +27,6 @@ from nextmv.cli.configuration.config import CONFIG_DIR, GO_CLI_PATH, load_config
 from nextmv.cli.init import app as init_app
 from nextmv.cli.local import app as local_app
 from nextmv.cli.manifest import app as manifest_app
-from nextmv.cli.mcp import app as mcp_app
 from nextmv.cli.message import confirmation, error, info, success, warning
 from nextmv.cli.version import app as version_app
 from nextmv.cli.version import version_callback
@@ -54,9 +53,16 @@ app.add_typer(configuration_app, name="configuration")
 app.add_typer(init_app)
 app.add_typer(local_app, name="local")
 app.add_typer(manifest_app, name="manifest")
-app.add_typer(mcp_app, name="mcp")
 app.add_typer(version_app)
 
+# Register the MCP subcommand only if the mcp extra is installed.
+try:
+    from nextmv.cli.mcp import app as mcp_app
+
+    app.add_typer(mcp_app, name="mcp", rich_help_panel="Preview")
+except ImportError:
+    pass
+
 
 @app.callback()
 def callback(

{nextmv-1.3.1.dev0 → nextmv-1.3.1.dev2}/nextmv/cli/mcp/__init__.py

@@ -1,4 +1,16 @@
-"""MCP (Model Context Protocol) server for the Nextmv CLI."""
+"""MCP (Model Context Protocol) server for the Nextmv CLI.
+
+Requires the ``mcp`` optional extra: ``pip install nextmv[mcp]``.
+"""
+
+# Fail fast at import time so that main.py's try/except can gate the
+# subcommand registration.
+import importlib.util
+
+if importlib.util.find_spec("mcp") is None:
+    raise ImportError(
+        "The mcp extra is not installed. Install it with: pip install nextmv[mcp]"
+    )
 
 import typer
 

{nextmv-1.3.1.dev0 → nextmv-1.3.1.dev2}/nextmv/cli/mcp/serve.py

@@ -39,9 +39,6 @@ def serve(
     [magenta]stdio[/magenta], which is what Claude Code, Cursor, and most
     local clients expect.
 
-    Requires the [magenta]mcp[/magenta] optional dependency. Install with:
-    [code]pip install 'nextmv[mcp]'[/code]
-
     [bold][underline]Examples[/underline][/bold]
 
     - Start the MCP server with stdio transport (default).
@@ -54,14 +51,7 @@ def serve(
         $ [dim]claude mcp add nextmv -- nextmv mcp serve[/dim]
     """
 
-    try:
-        from nextmv.cli.mcp.server import create_server
-    except ImportError:
-        error(
-            "MCP support requires the [magenta]mcp[/magenta] package. "
-            "Install with: [code]pip install 'nextmv[mcp]'[/code]"
-        )
-        return  # unreachable, error() raises
+    from nextmv.cli.mcp.server import create_server
 
     server = create_server()
 

{nextmv-1.3.1.dev0 → nextmv-1.3.1.dev2}/nextmv/cli/mcp/server.py

@@ -15,6 +15,7 @@ from nextmv.cli.mcp.tools import (
     batch,
     community,
     ensemble,
+    guide,
     input_set,
     instance,
     local,
@@ -32,12 +33,12 @@ from nextmv.cli.mcp.tools import (
 # Re-export helpers for backward compatibility — tests and external code
 # may import these directly from ``nextmv.cli.mcp.server``.
 from nextmv.cli.mcp.tools._helpers import (  # noqa: F401
-    _current_profile,
     _get_app,
     _get_client,
     _get_local_app,
     _mask_key,
     _save_to_file,
+    session,
 )
 
 # Re-export SDK names that tests patch on this module.
@@ -69,7 +70,17 @@ def create_server() -> FastMCP:
             "to use a specific profile (e.g. \"list apps in my dev "
             "profile\"), call cloud_set_profile first. Always state which "
             "profile you are using when calling cloud tools, e.g. "
-            "(profile: \"default\")."
+            "(profile: \"default\").\n\n"
+            "CLOUD RUN CACHE: Cloud run data (results, inputs, logs) is "
+            "cached locally at ~/.nextmv/runs/{endpoint}/{run_id}/ using "
+            "the same directory layout as local runs. The {endpoint} is the "
+            "API endpoint (e.g. api.cloud.nextmv.io). If a file already "
+            "exists there, it will not be re-downloaded. You can read "
+            "cached cloud run data directly from these paths without "
+            "calling the cloud tools again.\n\n"
+            "WORKFLOW GUIDE: When creating a new app, deploying to Cloud, "
+            "or running experiments, call the nextmv_workflow_guide tool "
+            "first to get the step-by-step workflow and coding patterns."
         ),
     )
 
@@ -97,4 +108,7 @@ def create_server() -> FastMCP:
     # Local tools
     local.register(mcp)
 
+    # Workflow guide
+    guide.register(mcp)
+
     return mcp

nextmv-1.3.1.dev2/nextmv/cli/mcp/tools/_helpers.py

@@ -0,0 +1,316 @@
+"""Shared helpers for MCP tool modules."""
+
+import contextvars
+import json
+import logging
+import os
+import tempfile
+from typing import Any
+
+from nextmv import local
+from nextmv.cloud import Application, Client
+from nextmv.local.local import LOGS_FILE, LOGS_KEY
+from nextmv.output import ASSETS_KEY, METRICS_KEY, OUTPUTS_KEY, SOLUTIONS_KEY, STATISTICS_KEY
+
+logger = logging.getLogger(__name__)
+
+
+class ProfileSession:
+    """Manages the active Nextmv Cloud profile for the current async context.
+
+    Uses ``contextvars.ContextVar`` internally so that each async task
+    (and therefore each concurrent HTTP request in streamable-http
+    transport) gets its own isolated profile state.
+    """
+
+    def __init__(self) -> None:
+        self._profile: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+            "nextmv_profile", default=None,
+        )
+
+    @property
+    def profile(self) -> str | None:
+        """Return the current profile name, or ``None`` for the default."""
+
+        return self._profile.get()
+
+    @profile.setter
+    def profile(self, value: str | None) -> None:
+        self._profile.set(value)
+
+    def get_client(self, profile: str | None = None) -> Client:
+        """Build a Nextmv Cloud client from env var or CLI config.
+
+        Checks for credentials in the following order:
+
+        1. ``NEXTMV_API_KEY`` environment variable (unless a profile is active).
+        2. CLI configuration file at ``~/.nextmv/config.yaml``.
+
+        Args:
+            profile: Optional profile name override. If not provided, uses
+                the session-level profile.
+        """
+
+        resolved = profile or self.profile
+
+        api_key = os.getenv("NEXTMV_API_KEY")
+        if api_key and not resolved:
+            endpoint = os.getenv("NEXTMV_ENDPOINT", "https://api.cloud.nextmv.io")
+            if not endpoint.startswith("http"):
+                endpoint = f"https://{endpoint}"
+            return Client(api_key=api_key, url=endpoint)
+
+        # Fall back to the CLI configuration file (~/.nextmv/config.yaml).
+        try:
+            from nextmv.cli.configuration.config import build_client
+
+            # "default" means use top-level keys (profile=None in build_client).
+            p = None if resolved is None or resolved == "default" else resolved
+            return build_client(profile=p)
+        except Exception as e:
+            raise ValueError(
+                f"Could not build a Nextmv client: {e}. Either set the "
+                "NEXTMV_API_KEY environment variable or configure the "
+                "CLI with: nextmv configuration create"
+            ) from e
+
+    def get_app(self, app_id: str, profile: str | None = None) -> Application:
+        """Build a cloud Application handle for the given ID."""
+
+        client = self.get_client(profile=profile)
+        return Application(client=client, id=app_id)
+
+
+# Singleton session used by all MCP tool modules.
+session = ProfileSession()
+
+
+def _mask_key(key: str | None) -> str | None:
+    """Mask an API key, keeping only the last 4 characters visible."""
+
+    if not key:
+        return None
+    if len(key) <= 4:
+        return key
+    return "X" * (len(key) - 4) + key[-4:]
+
+
+# ---------------------------------------------------------------------------
+# Convenience aliases so tool modules can call ``_helpers._get_client()``
+# without reaching into ``session`` directly.
+# ---------------------------------------------------------------------------
+
+
+def _get_client(profile: str | None = None) -> Client:
+    return session.get_client(profile=profile)
+
+
+def _get_app(app_id: str, profile: str | None = None) -> Application:
+    return session.get_app(app_id=app_id, profile=profile)
+
+
+def _get_local_app(app_dir: str, app_id: str | None = None) -> local.Application:
+    """Build a local Application, registering it if needed."""
+
+    app, _ = local.Application.get_or_register(app_src=app_dir, app_id=app_id)
+    return app
+
+
+def _build_run_configuration(content_format: str | None):
+    """Build a RunConfiguration for the given content format string, or None."""
+
+    if content_format is None:
+        return None
+
+    from nextmv.input import InputFormat
+    from nextmv.run import Format, FormatInput, RunConfiguration
+
+    config = RunConfiguration()
+    config.format = Format(
+        format_input=FormatInput(
+            input_type=InputFormat(content_format),
+        ),
+    )
+    return config
+
+
+def _none_if_empty(value: str | None) -> str | None:
+    """Convert empty or whitespace-only strings to None.
+
+    LLMs sometimes pass ``""`` instead of omitting optional parameters.
+    This normalises empty strings so downstream code sees ``None``.
+    Whitespace-only strings (e.g. ``"  "``) are also treated as empty.
+    """
+
+    if value is None or not value.strip():
+        return None
+    return value.strip()
+
+
+def _require_non_empty(value: str, name: str) -> str:
+    """Raise a clear error when a required string parameter is empty."""
+
+    if not value or not value.strip():
+        raise ValueError(f"'{name}' is required and must not be empty.")
+    return value.strip()
+
+
+def _save_to_file(data: Any, prefix: str) -> str:
+    """Serialize data to a temp JSON file and return a message with the path.
+
+    This keeps large payloads out of the MCP response (and thus out of
+    the LLM context window). The caller can selectively read the file
+    using standard file-reading tools.
+    """
+
+    fd, path = tempfile.mkstemp(suffix=".json", prefix=f"{prefix}_")
+    with os.fdopen(fd, "w") as fh:
+        json.dump(data, fh, indent=2)
+    return f"Data saved to {path} — use file-reading tools to inspect the contents."
+
+
+def _cloud_run_dir(endpoint: str, run_id: str) -> str:
+    """Build the local cache directory for a cloud run.
+
+    Returns ``~/.nextmv/runs/{endpoint}/{run_id}``. The *endpoint*
+    parameter should already have the URL scheme (``https://`` /
+    ``http://``) stripped.
+    """
+
+    return os.path.join(os.path.expanduser("~"), ".nextmv", "runs", endpoint, run_id)
+
+
+def _cloud_run_file_exists(endpoint: str, run_id: str, *path_parts: str) -> str | None:
+    """Return the file path if a cached cloud run file exists, else None.
+
+    Args:
+        endpoint: API endpoint with scheme stripped.
+        run_id: The run ID.
+        *path_parts: Path components relative to the run directory
+            (e.g. ``"inputs", "input.json"``).
+    """
+
+    path = os.path.join(_cloud_run_dir(endpoint, run_id), *path_parts)
+    return path if os.path.exists(path) else None
+
+
+def _endpoint_from_app(app: Application) -> str:
+    """Return the API endpoint from an Application with scheme stripped."""
+
+    url: str = app.client.url
+    for scheme in ("https://", "http://"):
+        if url.startswith(scheme):
+            url = url[len(scheme):]
+            break
+    return url
+
+
+def _save_cloud_run_file(data: Any, endpoint: str, run_id: str, *path_parts: str) -> str:
+    """Serialize *data* as JSON into the cloud run cache and return the path.
+
+    Creates intermediate directories as needed. The *endpoint* parameter
+    should already have the URL scheme stripped.
+    """
+
+    path = os.path.join(_cloud_run_dir(endpoint, run_id), *path_parts)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w") as fh:
+        json.dump(data, fh, indent=2)
+    return path
+
+
+def _extract_cloud_run_outputs(result_dict: dict[str, Any], endpoint: str, run_id: str) -> None:
+    """Extract output components from a cloud result into separate files.
+
+    Mirrors the local run ``outputs/`` directory structure:
+
+    * ``outputs/solutions/solution.json`` — the full output dict (matches local)
+    * ``outputs/metrics/metrics.json`` — raw metrics value
+    * ``outputs/statistics/statistics.json`` — wrapped as ``{"statistics": ...}``
+    * ``outputs/assets/assets.json`` — wrapped as ``{"assets": ...}``
+
+    Skipped when *output* is not a dict with inline data (e.g. csv-archive
+    results where the SDK already extracted files via ``output_dir_path``).
+    """
+
+    output = result_dict.get("output")
+    if not isinstance(output, dict) or "solution" not in output:
+        return
+
+    run_dir = _cloud_run_dir(endpoint, run_id)
+    outputs_dir = os.path.join(run_dir, OUTPUTS_KEY)
+
+    # solution → outputs/solutions/solution.json
+    # Local writes the entire stdout output dict here, so we do the same.
+    path = os.path.join(outputs_dir, SOLUTIONS_KEY, "solution.json")
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w") as fh:
+        json.dump(output, fh, indent=2)
+
+    # metrics → outputs/metrics/metrics.json (raw, matching local)
+    metrics = output.get(METRICS_KEY)
+    if metrics:
+        path = os.path.join(outputs_dir, METRICS_KEY, f"{METRICS_KEY}.json")
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w") as fh:
+            json.dump(metrics, fh, indent=2)
+
+    # statistics → outputs/statistics/statistics.json (wrapped, matching local)
+    statistics = output.get(STATISTICS_KEY)
+    if statistics:
+        path = os.path.join(outputs_dir, STATISTICS_KEY, f"{STATISTICS_KEY}.json")
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w") as fh:
+            json.dump({STATISTICS_KEY: statistics}, fh, indent=2)
+
+    # assets → outputs/assets/assets.json (wrapped, matching local)
+    assets = output.get(ASSETS_KEY)
+    if assets:
+        path = os.path.join(outputs_dir, ASSETS_KEY, f"{ASSETS_KEY}.json")
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w") as fh:
+            json.dump({ASSETS_KEY: assets}, fh, indent=2)
+
+    # Generate visuals from assets (Plotly/GeoJSON → HTML), matching local.
+    try:
+        from nextmv.local.executor import process_run_visuals
+
+        process_run_visuals(run_dir=run_dir, outputs_dir=outputs_dir)
+    except Exception as exc:
+        logger.warning("Visual generation failed for run %s: %s", run_id, exc)
+
+
+def _save_cloud_run_logs(data: Any, endpoint: str, run_id: str) -> str:
+    """Write cloud run logs as plain text to match local run format.
+
+    Accepts either a ``RunLog.to_dict()`` (``{"log": "..."}`` with an
+    optional ``"stderr"`` key) or a list of poll entries
+    (``[{"timestamp": ..., "log": ...}, ...]``).
+    """
+
+    path = os.path.join(_cloud_run_dir(endpoint, run_id), LOGS_KEY, LOGS_FILE)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+
+    with open(path, "w") as fh:
+        if isinstance(data, list):
+            # Poll entries: write each as "timestamp log\n".
+            for entry in data:
+                ts = entry.get("timestamp") or ""
+                log = entry.get("log") or ""
+                fh.write(f"{ts} {log}\n")
+        elif isinstance(data, dict):
+            # RunLog.to_dict(): write the log string directly.
+            log = data.get("log", "")
+            if log:
+                fh.write(log)
+                if not log.endswith("\n"):
+                    fh.write("\n")
+            stderr = data.get("stderr", "")
+            if stderr:
+                fh.write(stderr)
+                if not stderr.endswith("\n"):
+                    fh.write("\n")
+        else:
+            fh.write(str(data))
+
+    return path