nextmv 1.4.0.dev0__tar.gz → 1.4.1.dev0__tar.gz

{nextmv-1.4.0.dev0 → nextmv-1.4.1.dev0}/.gitignore

@@ -161,5 +161,10 @@ cython_debug/
 # VSCode
 .vscode/
 
+# Agents
+.claude
+
 # Documentation stuff
 site/
+
+scratch

{nextmv-1.4.0.dev0 → nextmv-1.4.1.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 1.4.0.dev0
+Version: 1.4.1.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,8 @@ 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: 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.4.1.dev0/nextmv/__about__.py

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

{nextmv-1.4.0.dev0 → nextmv-1.4.1.dev0}/nextmv/__init__.py

@@ -1,6 +1,7 @@
 """Nextmv Python SDK."""
 
 from .__about__ import __version__
+from .account import AccountMemberRole as AccountMemberRole
 from .base_model import BaseModel as BaseModel
 from .base_model import from_dict as from_dict
 from .content_format import ContentFormat as ContentFormat

nextmv-1.4.1.dev0/nextmv/account.py

@@ -0,0 +1,51 @@
+"""
+Provides role enum for Nextmv accounts.
+
+This module defines enumerations for representing member roles within
+a Nextmv account.
+
+Classes
+-------
+AccountMemberRole
+    Represents the role of a member in a Nextmv account.
+"""
+
+from enum import Enum
+
+
+class AccountMemberRole(str, Enum):
+    """
+    The role type of an `AccountMember` represented as a string.
+
+    You can import the `AccountMemberRole` class directly from `nextmv`:
+
+    ```python
+    from nextmv import AccountMemberRole
+    ```
+
+    This enum specifies the supported roles for users in Nextmv accounts.
+
+    Attributes
+    ----------
+    ROOT : str
+        The role of the owner of the account
+    ADMIN : str
+        The role of administrators of the account
+    DEVELOPER: str
+        The role of developers of the account
+    OPERATOR: str
+        The role of operators of the account
+    VIEWER: str
+        The role of viewers of the account
+    """
+
+    ROOT = "root"
+    """The role of the owner of the account"""
+    ADMIN = "admin"
+    """The role of administrators of the account"""
+    DEVELOPER = "developer"
+    """The role of developers of the account"""
+    OPERATOR = "operator"
+    """The role of operators of the account"""
+    VIEWER = "viewer"
+    """The role of viewers of the account"""

{nextmv-1.4.0.dev0 → nextmv-1.4.1.dev0}/nextmv/cli/init.py

@@ -170,11 +170,7 @@ def _manifest_type_question() -> ManifestType:
         default=ManifestType.PYTHON.value,
     )
 
-    manifest_type = ManifestType(manifest_type)
-    if manifest_type == ManifestType.BINARY:
-        manifest_type = ManifestType.GO
-
-    return manifest_type
+    return ManifestType(manifest_type)
 
 
 def _template_question(manifest_type: ManifestType) -> str:
@@ -339,12 +335,12 @@ def _handle_files_initialization(
         )
 
     else:
-        dst = initialize_manifest(manifest_type=manifest_type, content_format=content_format, dirpath=dirpath)
+        manifest_path = initialize_manifest(manifest_type=manifest_type, content_format=content_format, dirpath=dirpath)
         success(
             f"[magenta]{manifest_type.value}[/magenta], [magenta]{content_format.value}[/magenta] manifest "
-            f"initialized at [magenta]{dst}[/magenta]."
+            f"initialized at [magenta]{manifest_path}[/magenta]."
         )
-        local_app = local.Application(src=dst)
+        local_app = local.Application(src=os.path.dirname(manifest_path))
 
     return local_app
 

{nextmv-1.4.0.dev0 → nextmv-1.4.1.dev0}/nextmv/cli/main.py

@@ -55,6 +55,14 @@ app.add_typer(local_app, name="local")
 app.add_typer(manifest_app, name="manifest")
 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")
+except ImportError:
+    pass
+
 
 @app.callback()
 def callback(
@@ -79,7 +87,7 @@ def callback(
         return
 
     # Skip checks for certain commands.
-    ignored_commands = {"configuration", "local", "init", "manifest", "version"}
+    ignored_commands = {"configuration", "mcp", "local", "init", "manifest", "version"}
     if ctx.invoked_subcommand in ignored_commands:
         return
 

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

@@ -0,0 +1,38 @@
+"""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
+
+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.4.1.dev0/nextmv/cli/mcp/serve.py

@@ -0,0 +1,65 @@
+"""MCP server command for the Nextmv CLI."""
+
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.mcp.server import create_server
+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.
+
+    [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]
+    """
+
+    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.4.1.dev0/nextmv/cli/mcp/server.py

@@ -0,0 +1,115 @@
+"""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,
+    guide,
+    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
+    _get_app,
+    _get_client,
+    _get_local_app,
+    _mask_key,
+    _save_to_file,
+    _save_to_json_file,
+    session,
+)
+
+# 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\").\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."
+        ),
+    )
+
+    # 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)
+
+    # Workflow guide
+    guide.register(mcp)
+
+    return mcp