nextmv 1.2.2.dev0__tar.gz → 1.2.3.dev0__tar.gz

{nextmv-1.2.2.dev0 → nextmv-1.2.3.dev0}/.gitignore

@@ -163,3 +163,6 @@ cython_debug/
 
 # Documentation stuff
 site/
+
+scratch
+.claude

{nextmv-1.2.2.dev0 → nextmv-1.2.3.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 1.2.2.dev0
+Version: 1.2.3.dev0
 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,6 +227,12 @@ 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
 Requires-Dist: mlflow>=3.9.0; extra == 'notebook'
 Description-Content-Type: text/markdown

nextmv-1.2.3.dev0/nextmv/__about__.py

@@ -0,0 +1 @@
+__version__ = "v1.2.3.dev0"

{nextmv-1.2.2.dev0 → nextmv-1.2.3.dev0}/nextmv/cli/main.py

@@ -26,6 +26,7 @@ from nextmv.cli.configuration import app as configuration_app
 from nextmv.cli.configuration.config import CONFIG_DIR, GO_CLI_PATH, load_config
 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
@@ -51,6 +52,7 @@ app.add_typer(community_app, name="community")
 app.add_typer(configuration_app, name="configuration")
 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)
 
 
@@ -77,7 +79,7 @@ def callback(
         return
 
     # Skip checks for certain commands.
-    ignored_commands = {"configuration", "version"}
+    ignored_commands = {"configuration", "mcp", "version"}
     if ctx.invoked_subcommand in ignored_commands:
         return
 

nextmv-1.2.3.dev0/nextmv/cli/mcp/__init__.py

@@ -0,0 +1,26 @@
+"""MCP (Model Context Protocol) server for the Nextmv CLI."""
+
+import typer
+
+from nextmv.cli.mcp.serve import app as serve_app
+
+# Set up subcommand application.
+app = typer.Typer()
+app.add_typer(serve_app)
+
+
+@app.callback()
+def callback() -> None:
+    """
+    Model Context Protocol (MCP) server for LLM integrations.
+
+    Start an MCP server so that any MCP-compatible client (Claude Code,
+    Cursor, VS Code, etc.) can interact with Nextmv Cloud through natural
+    language.
+
+    [bold][underline]Quick start[/underline][/bold]
+
+    - Register with Claude Code.
+        $ [dim]claude mcp add nextmv -- nextmv mcp serve[/dim]
+    """
+    pass

nextmv-1.2.3.dev0/nextmv/cli/mcp/serve.py

@@ -0,0 +1,76 @@
+"""MCP server command for the Nextmv CLI."""
+
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.message import error
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def serve(
+    port: Annotated[
+        int,
+        typer.Option(
+            "--port",
+            help="Port for the HTTP transport.",
+            metavar="PORT",
+        ),
+    ] = 8080,
+    transport: Annotated[
+        str,
+        typer.Option(
+            "--transport",
+            "-t",
+            help="Transport protocol. "
+            "Allowed values: [magenta]stdio[/magenta], [magenta]streamable-http[/magenta].",
+            metavar="TRANSPORT",
+        ),
+    ] = "stdio",
+) -> None:
+    """
+    Start the Nextmv MCP server.
+
+    The MCP server exposes Nextmv Cloud functionality as tools that any
+    MCP-compatible client can use. The default transport is
+    [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).
+        $ [dim]nextmv mcp serve[/dim]
+
+    - Start the MCP server with HTTP transport on port 9090.
+        $ [dim]nextmv mcp serve --transport streamable-http --port 9090[/dim]
+
+    - Register with Claude Code.
+        $ [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
+
+    server = create_server()
+
+    if transport == "stdio":
+        server.run(transport="stdio")
+    elif transport in ("http", "streamable-http"):
+        server.run(transport="streamable-http", port=port)
+    else:
+        error(
+            f"Unknown transport [magenta]{transport}[/magenta]. "
+            "Allowed values are: [magenta]stdio[/magenta], [magenta]streamable-http[/magenta]."
+        )

nextmv-1.2.3.dev0/nextmv/cli/mcp/server.py

@@ -0,0 +1,100 @@
+"""Nextmv MCP server definition.
+
+This module is the public entry point for the MCP server. It delegates
+tool registration to domain-specific submodules under ``tools/`` and
+re-exports shared helpers so that existing imports continue to work.
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+# Import tool registration submodules.
+from nextmv.cli.mcp.tools import (
+    acceptance,
+    account,
+    app,
+    batch,
+    community,
+    ensemble,
+    input_set,
+    instance,
+    local,
+    managed_input,
+    profile,
+    run,
+    scenario,
+    secrets,
+    shadow,
+    sso,
+    switchback,
+    version,
+)
+
+# 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,
+)
+
+# Re-export SDK names that tests patch on this module.
+from nextmv.cloud import list_applications  # noqa: F401
+
+
+def create_server() -> FastMCP:
+    """Create and return the Nextmv MCP server."""
+
+    mcp = FastMCP(
+        "nextmv",
+        json_response=True,
+        instructions=(
+            "Nextmv is a platform for deploying and managing decision "
+            "models (optimization, routing, scheduling, etc.). Use these "
+            "tools to interact with Nextmv Cloud apps: list apps, submit "
+            "runs, check results, manage versions/instances, run experiments, "
+            "and work with local applications.\n\n"
+            "IMPORTANT: Always use these MCP tools instead of shelling out "
+            "to the `nextmv` CLI binary. Large responses (run results, "
+            "inputs, logs) are automatically saved to local temp files to "
+            "keep the context window small — the tool will return the file "
+            "path so you can selectively read what you need. Large inputs "
+            "can be passed directly as tool parameters without concern.\n\n"
+            "PROFILES: The server supports multiple profiles from "
+            "~/.nextmv/config.yaml. Use cloud_list_profiles to see "
+            "available profiles and cloud_set_profile to switch. The "
+            "default profile is used unless changed. When the user asks "
+            "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\")."
+        ),
+    )
+
+    # Cloud tools
+    profile.register(mcp)
+    app.register(mcp)
+    run.register(mcp)
+    version.register(mcp)
+    instance.register(mcp)
+    batch.register(mcp)
+    input_set.register(mcp)
+    acceptance.register(mcp)
+    scenario.register(mcp)
+    ensemble.register(mcp)
+    shadow.register(mcp)
+    switchback.register(mcp)
+    secrets.register(mcp)
+    sso.register(mcp)
+    account.register(mcp)
+    managed_input.register(mcp)
+
+    # Community tools
+    community.register(mcp)
+
+    # Local tools
+    local.register(mcp)
+
+    return mcp

nextmv-1.2.3.dev0/nextmv/cli/mcp/tools/__init__.py

@@ -0,0 +1 @@
+"""MCP tool registration submodules, organized by domain."""

nextmv-1.2.3.dev0/nextmv/cli/mcp/tools/_helpers.py

@@ -0,0 +1,87 @@
+"""Shared helpers for MCP tool modules."""
+
+import json
+import os
+import tempfile
+from typing import Any
+
+from nextmv import local
+from nextmv.cloud import Application, Client
+
+# Session-level profile. None means "default" (top-level config keys).
+_current_profile: str | None = None
+
+
+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:]
+
+
+def _get_client(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 ``_current_profile``.
+    """
+
+    resolved = profile or _current_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(
+            "No Nextmv API key found. Either set the NEXTMV_API_KEY "
+            "environment variable or configure the CLI with: "
+            "nextmv configuration create"
+        ) from e
+
+
+def _get_app(app_id: str, profile: str | None = None) -> Application:
+    """Build a cloud Application handle for the given ID."""
+
+    client = _get_client(profile=profile)
+    return Application(client=client, id=app_id)
+
+
+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 _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."

nextmv-1.2.3.dev0/nextmv/cli/mcp/tools/acceptance.py

@@ -0,0 +1,107 @@
+"""MCP tools for cloud acceptance tests."""
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from nextmv.cli.mcp.tools import _helpers
+
+
+def register(mcp: FastMCP) -> None:
+    """Register cloud acceptance test tools."""
+
+    @mcp.tool()
+    def cloud_list_acceptance_tests(app_id: str) -> list[dict[str, Any]]:
+        """List acceptance tests for a Nextmv Cloud application.
+
+        Acceptance tests compare a candidate instance against a
+        baseline using defined metrics. Returns a list of test
+        summaries.
+
+        Args:
+            app_id: The application ID.
+        """
+
+        app = _helpers._get_app(app_id)
+        tests = app.list_acceptance_tests()
+        return [t.to_dict() for t in tests]
+
+    @mcp.tool()
+    def cloud_get_acceptance_test(
+        app_id: str,
+        acceptance_test_id: str,
+    ) -> str:
+        """Get details and results of an acceptance test.
+
+        Saves the full test data (including metric comparisons and
+        pass/fail results) to a local temp file. Use file-reading
+        tools to inspect the contents.
+
+        Args:
+            app_id: The application ID.
+            acceptance_test_id: The acceptance test ID.
+        """
+
+        app = _helpers._get_app(app_id)
+        test = app.acceptance_test(acceptance_test_id=acceptance_test_id)
+        return _helpers._save_to_file(test.to_dict(), prefix=f"acceptance_test_{acceptance_test_id}")
+
+    @mcp.tool()
+    def cloud_create_acceptance_test(
+        app_id: str,
+        candidate_instance_id: str,
+        baseline_instance_id: str,
+        metrics: list[dict[str, Any]],
+        acceptance_test_id: str | None = None,
+        name: str | None = None,
+        input_set_id: str | None = None,
+        description: str | None = None,
+    ) -> dict[str, Any]:
+        """Create an acceptance test comparing two instances.
+
+        An acceptance test runs both instances against the same input
+        set and compares results using the specified metrics to
+        determine whether the candidate meets acceptance criteria.
+
+        Args:
+            app_id: The application ID.
+            candidate_instance_id: The candidate instance to evaluate.
+            baseline_instance_id: The baseline instance to compare
+                the candidate against.
+            metrics: List of metric definitions. Each metric is a dict
+                with keys: ``field``, ``metric_type``, ``params``,
+                ``statistic``.
+            acceptance_test_id: Optional test ID. Auto-generated if
+                omitted.
+            name: Optional human-readable name.
+            input_set_id: Optional input set ID to run the test against.
+            description: Optional description.
+        """
+
+        app = _helpers._get_app(app_id)
+        test = app.new_acceptance_test(
+            candidate_instance_id=candidate_instance_id,
+            baseline_instance_id=baseline_instance_id,
+            metrics=metrics,
+            id=acceptance_test_id,
+            name=name,
+            input_set_id=input_set_id,
+            description=description,
+        )
+        return test.to_dict()
+
+    @mcp.tool()
+    def cloud_delete_acceptance_test(
+        app_id: str,
+        acceptance_test_id: str,
+    ) -> str:
+        """Delete an acceptance test permanently.
+
+        Args:
+            app_id: The application ID.
+            acceptance_test_id: The acceptance test ID to delete.
+        """
+
+        app = _helpers._get_app(app_id)
+        app.delete_acceptance_test(acceptance_test_id=acceptance_test_id)
+        return f"Deleted acceptance test {acceptance_test_id}"

nextmv-1.2.3.dev0/nextmv/cli/mcp/tools/account.py

@@ -0,0 +1,47 @@
+"""MCP tools for cloud account management."""
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from nextmv.cli.mcp.tools import _helpers
+
+
+def register(mcp: FastMCP) -> None:
+    """Register cloud account tools."""
+
+    @mcp.tool()
+    def cloud_get_account(account_id: str) -> dict[str, Any]:
+        """Get details of a Nextmv Cloud account.
+
+        Returns account information including organization name,
+        plan details, and usage limits.
+
+        Args:
+            account_id: The account ID to retrieve.
+        """
+
+        from nextmv.cloud.account import Account
+
+        client = _helpers._get_client()
+        account = Account.get(client=client, account_id=account_id)
+        return account.to_dict()
+
+    @mcp.tool()
+    def cloud_get_queue(account_id: str) -> dict[str, Any]:
+        """Get the run queue for a Nextmv Cloud account.
+
+        Returns information about currently queued and running runs
+        across all applications in the account, including queue
+        depth and concurrency usage.
+
+        Args:
+            account_id: The account ID.
+        """
+
+        from nextmv.cloud.account import Account
+
+        client = _helpers._get_client()
+        account = Account.get(client=client, account_id=account_id)
+        queue = account.queue()
+        return queue.to_dict()

nextmv-1.2.3.dev0/nextmv/cli/mcp/tools/app.py

@@ -0,0 +1,141 @@
+"""MCP tools for cloud application management."""
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from nextmv.cli.mcp.tools import _helpers
+from nextmv.cloud import Application, list_applications
+
+
+def register(mcp: FastMCP) -> None:
+    """Register cloud application management tools."""
+
+    @mcp.tool()
+    def cloud_list_apps() -> list[dict[str, Any]]:
+        """List all Nextmv Cloud applications in the current account.
+
+        Returns a list of application dictionaries containing each
+        application's ID, name, description, and default instance.
+        """
+
+        client = _helpers._get_client()
+        apps = list_applications(client)
+        return [a.to_dict() for a in apps]
+
+    @mcp.tool()
+    def cloud_get_app(app_id: str) -> dict[str, Any]:
+        """Get details of a specific Nextmv Cloud application.
+
+        Returns the full application object including its name,
+        description, default instance, and creation timestamp.
+
+        Args:
+            app_id: The application ID (e.g., ``"my-routing-app"``).
+        """
+
+        client = _helpers._get_client()
+        app = Application.get(client=client, id=app_id)
+        return app.to_dict()
+
+    @mcp.tool()
+    def cloud_create_app(
+        name: str,
+        app_id: str | None = None,
+        description: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new Nextmv Cloud application.
+
+        Returns the created application object. A version and default
+        instance are automatically provisioned.
+
+        Args:
+            name: A human-readable name for the application.
+            app_id: Optional URL-friendly ID. Auto-generated from
+                the name if omitted.
+            description: Optional description of what the application does.
+        """
+
+        client = _helpers._get_client()
+        app = Application.new(
+            client=client,
+            name=name,
+            id=app_id,
+            description=description,
+        )
+        return app.to_dict()
+
+    @mcp.tool()
+    def cloud_delete_app(app_id: str) -> str:
+        """Delete a Nextmv Cloud application permanently.
+
+        This action cannot be undone. All versions, instances, and
+        run history associated with the application will be removed.
+
+        Args:
+            app_id: The application ID to delete.
+        """
+
+        app = _helpers._get_app(app_id)
+        app.delete()
+        return f"Deleted application {app_id}"
+
+    @mcp.tool()
+    def cloud_app_exists(app_id: str) -> bool:
+        """Check whether a Nextmv Cloud application exists.
+
+        Returns True if an application with the given ID exists in
+        the current account, False otherwise.
+
+        Args:
+            app_id: The application ID to check.
+        """
+
+        client = _helpers._get_client()
+        return Application.exists(client=client, id=app_id)
+
+    @mcp.tool()
+    def cloud_update_app(
+        app_id: str,
+        name: str | None = None,
+        description: str | None = None,
+        default_instance_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Update attributes of a Nextmv Cloud application.
+
+        Only the provided fields are updated; omitted fields remain
+        unchanged. Returns the updated application object.
+
+        Args:
+            app_id: The application ID to update.
+            name: New human-readable name for the application.
+            description: New description.
+            default_instance_id: New default instance ID used when no
+                instance is specified at run time.
+        """
+
+        app = _helpers._get_app(app_id)
+        updated = app.update(
+            name=name,
+            description=description,
+            default_instance_id=default_instance_id,
+        )
+        return updated.to_dict()
+
+    @mcp.tool()
+    def cloud_push_app(app_id: str, app_dir: str) -> str:
+        """Push local application code to a Nextmv Cloud application.
+
+        Uploads the contents of a local directory as a new version of
+        the application. The directory must contain an ``app.yaml``
+        manifest.
+
+        Args:
+            app_id: The application ID to push to.
+            app_dir: Absolute path to the local directory containing the
+                application code and ``app.yaml`` manifest.
+        """
+
+        app = _helpers._get_app(app_id)
+        app.push(app_dir=app_dir)
+        return f"Pushed {app_dir} to application {app_id}"