mcp-yieldshell 1.1.2__tar.gz → 1.1.3__tar.gz

mcp_yieldshell-1.1.2/README.md → mcp_yieldshell-1.1.3/PKG-INFO

@@ -1,3 +1,11 @@
+Metadata-Version: 2.5
+Name: mcp-yieldshell
+Version: 1.1.3
+Summary: A drop-in shell MCP that auto-yields long-running commands into managed background executions.
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.9.0
+Description-Content-Type: text/markdown
+
 # YieldShell MCP
 
 A drop-in shell MCP server that auto-yields long-running commands into managed
@@ -147,8 +155,12 @@ to the background. Addressable responses include an opaque `execution_id`;
 clients must pass it through unchanged to lifecycle tools. `process_id` is the
 numeric OS PID of the initial shell and is not a lifecycle handle.
 
+Every call must now supply `description`. Missing, null, non-string, empty,
+or whitespace-only descriptions fail MCP argument validation before execution.
+
 * **Parameters**:
   * `command` (string, **required**): The command string to execute in the shell.
+  * `description` (string, **required**): A concise, non-blank explanation of what the command does, for example `"Run the project test suite"`. It appears only in the tool call; it is not saved as execution metadata or included in responses or `ps` results. There is no fixed length limit.
   * `side_effects` (array of string, **required**): The side-effect categories this command may plausibly have. Must contain at least one entry drawn from the enum below. Use `["NONE"]` for commands with no meaningful side effects. `NONE` is exclusive and must not be combined with any other category. The server rejects the call with `failed_to_start` if any declared category is configured as blocked.
     * Allowed values: `CHANGES_NETWORK_CONFIGURATION`, `CHANGES_PACKAGES_OR_DEPENDENCIES`, `CONSUMES_SIGNIFICANT_RESOURCES`, `DELETES_FILES`, `EXPOSES_SECRETS`, `KILLS_AGENT_PROCESS`, `MAKES_NETWORK_REQUESTS`, `MODIFIES_OS_SETTINGS`, `MODIFIES_OS_USER_SETTINGS`, `MODIFIES_OUTSIDE_WORKSPACE`, `MODIFIES_PRODUCTION_SERVICES`, `MODIFIES_PROTECTED_FILES`, `MODIFIES_SECURITY_CONTROLS`, `MODIFIES_WORKSPACE_FILES`, `NONE`, `OTHER`, `RUNS_INLINE_CODE`, `RUNS_PRIVILEGED_COMMANDS`, `STOPS_OR_RESTARTS_SERVICES`, `UNKNOWN`, `USES_DESTRUCTIVE_GIT_OPERATION`.
     * `RUNS_INLINE_CODE` is in the default blocklist. It covers commands that execute code supplied inline to an interpreter or shell (e.g. `python -c`, `node -e`, `curl ... | sh`). It does not cover simply creating a script or executable file unless the same command also executes inline code. The safer next action is to write the content to a reviewable workspace file and execute it in a small, inspectable step. Operators can clear the blocklist via `MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS=,`.

mcp_yieldshell-1.1.2/PKG-INFO → mcp_yieldshell-1.1.3/README.md

@@ -1,11 +1,3 @@
-Metadata-Version: 2.4
-Name: mcp-yieldshell
-Version: 1.1.2
-Summary: A drop-in shell MCP that auto-yields long-running commands into managed background executions.
-Requires-Python: >=3.11
-Requires-Dist: mcp<2,>=1.9.0
-Description-Content-Type: text/markdown
-
 # YieldShell MCP
 
 A drop-in shell MCP server that auto-yields long-running commands into managed
@@ -155,8 +147,12 @@ to the background. Addressable responses include an opaque `execution_id`;
 clients must pass it through unchanged to lifecycle tools. `process_id` is the
 numeric OS PID of the initial shell and is not a lifecycle handle.
 
+Every call must now supply `description`. Missing, null, non-string, empty,
+or whitespace-only descriptions fail MCP argument validation before execution.
+
 * **Parameters**:
   * `command` (string, **required**): The command string to execute in the shell.
+  * `description` (string, **required**): A concise, non-blank explanation of what the command does, for example `"Run the project test suite"`. It appears only in the tool call; it is not saved as execution metadata or included in responses or `ps` results. There is no fixed length limit.
   * `side_effects` (array of string, **required**): The side-effect categories this command may plausibly have. Must contain at least one entry drawn from the enum below. Use `["NONE"]` for commands with no meaningful side effects. `NONE` is exclusive and must not be combined with any other category. The server rejects the call with `failed_to_start` if any declared category is configured as blocked.
     * Allowed values: `CHANGES_NETWORK_CONFIGURATION`, `CHANGES_PACKAGES_OR_DEPENDENCIES`, `CONSUMES_SIGNIFICANT_RESOURCES`, `DELETES_FILES`, `EXPOSES_SECRETS`, `KILLS_AGENT_PROCESS`, `MAKES_NETWORK_REQUESTS`, `MODIFIES_OS_SETTINGS`, `MODIFIES_OS_USER_SETTINGS`, `MODIFIES_OUTSIDE_WORKSPACE`, `MODIFIES_PRODUCTION_SERVICES`, `MODIFIES_PROTECTED_FILES`, `MODIFIES_SECURITY_CONTROLS`, `MODIFIES_WORKSPACE_FILES`, `NONE`, `OTHER`, `RUNS_INLINE_CODE`, `RUNS_PRIVILEGED_COMMANDS`, `STOPS_OR_RESTARTS_SERVICES`, `UNKNOWN`, `USES_DESTRUCTIVE_GIT_OPERATION`.
     * `RUNS_INLINE_CODE` is in the default blocklist. It covers commands that execute code supplied inline to an interpreter or shell (e.g. `python -c`, `node -e`, `curl ... | sh`). It does not cover simply creating a script or executable file unless the same command also executes inline code. The safer next action is to write the content to a reviewable workspace file and execute it in a small, inspectable step. Operators can clear the blocklist via `MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS=,`.

{mcp_yieldshell-1.1.2 → mcp_yieldshell-1.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-yieldshell"
-version = "1.1.2"
+version = "1.1.3"
 description = "A drop-in shell MCP that auto-yields long-running commands into managed background executions."
 readme = "README.md"
 requires-python = ">=3.11"

{mcp_yieldshell-1.1.2 → mcp_yieldshell-1.1.3}/src/mcp_yieldshell/server.py

@@ -4,8 +4,10 @@ from __future__ import annotations
 
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
+from typing import Annotated
 
 from mcp.server.fastmcp import FastMCP
+from pydantic import Field
 
 from .config import Config
 from .execution.manager import ExecutionManager
@@ -39,6 +41,18 @@ def _get_manager() -> ExecutionManager:
 async def execute(
     command: str,
     side_effects: list[SideEffect],
+    description: Annotated[
+        str,
+        Field(
+            strict=True,
+            min_length=1,
+            pattern=r"\S",
+            description=(
+                "A concise explanation of what the command does, "
+                "for example: Run the project test suite. Must not be blank."
+            ),
+        ),
+    ],
     cwd: str | None = None,
     env: dict[str, str] | None = None,
     shell: str | None = None,
@@ -55,6 +69,12 @@ async def execute(
     through unchanged to ``read``, ``write``, ``wait``, or ``stop``; never
     parse it or substitute the numeric OS ``process_id``.
 
+    ``description`` is required and must be a non-blank string explaining
+    what the command does, for example ``"Run the project test suite"``.
+    It appears only in the tool call and is not retained as execution
+    metadata or included in responses. Invalid descriptions are rejected
+    by MCP argument validation before the execution manager is invoked.
+
     ``side_effects`` is required and must be a non-empty list. Declare every
     plausible side-effect category before running the command. ``NONE`` is
     exclusive and must not be combined with any other category; pass

mcp_yieldshell-1.1.3/tests/test_execute_description.py

@@ -0,0 +1,89 @@
+"""MCP schema and validation checks for the required execution description."""
+
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from mcp.server.fastmcp.exceptions import ToolError
+from mcp.server.fastmcp.tools.base import Tool
+
+from mcp_yieldshell import server
+
+
+@pytest.fixture
+def execute_tool():
+    return Tool.from_function(server.execute)
+
+
+def test_description_schema_is_required_and_explains_its_purpose(execute_tool):
+    schema = execute_tool.parameters
+    assert "description" in schema["required"]
+    description = schema["properties"]["description"]
+    assert description["type"] == "string"
+    assert description["minLength"] == 1
+    assert description["pattern"] == r"\S"
+    assert "what the command does" in description["description"]
+    assert "default" not in description
+    assert "maxLength" not in description
+
+
+@pytest.mark.parametrize(
+    "description_args",
+    [
+        pytest.param({}, id="missing"),
+        pytest.param({"description": None}, id="null"),
+        pytest.param({"description": 123}, id="integer"),
+        pytest.param({"description": 1.5}, id="float"),
+        pytest.param({"description": True}, id="boolean"),
+        pytest.param({"description": []}, id="array"),
+        pytest.param({"description": {}}, id="object"),
+        pytest.param({"description": ""}, id="empty"),
+        pytest.param({"description": " \t\r\n"}, id="whitespace"),
+        pytest.param({"description": "\u2003\u00a0"}, id="unicode-whitespace"),
+    ],
+)
+async def test_invalid_description_never_reaches_manager(
+    execute_tool, monkeypatch, description_args
+):
+    get_manager = Mock()
+    monkeypatch.setattr(server, "_get_manager", get_manager)
+
+    with pytest.raises(ToolError, match="description"):
+        await execute_tool.run(
+            {"command": "echo hello", "side_effects": ["NONE"], **description_args}
+        )
+
+    get_manager.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    "description",
+    [
+        "Print a greeting",
+        " \n输出问候语\t ",
+        "Explain the command. " * 1_000,
+    ],
+    ids=["concise", "unicode-with-whitespace", "long"],
+)
+async def test_valid_description_is_not_forwarded_to_manager(
+    execute_tool, monkeypatch, description
+):
+    manager = Mock()
+    response = {"status": "completed", "stdout": "hello\n"}
+    manager.execute_command = AsyncMock(return_value=response)
+    monkeypatch.setattr(server, "_get_manager", lambda: manager)
+
+    result = await execute_tool.run(
+        {
+            "command": "echo hello",
+            "side_effects": ["NONE"],
+            "description": description,
+            "name": "greeting",
+        }
+    )
+
+    assert result == response
+    manager.execute_command.assert_awaited_once()
+    arguments = manager.execute_command.await_args.kwargs
+    assert arguments["command"] == "echo hello"
+    assert arguments["name"] == "greeting"
+    assert "description" not in arguments

{mcp_yieldshell-1.1.2 → mcp_yieldshell-1.1.3}/tests/test_protocol.py

@@ -49,6 +49,9 @@ async def test_stdio_server_lists_and_executes_tools():
                 "write",
             }
             assert "exec" not in tool_names
+            execute_schema = tools_by_name["execute"].inputSchema
+            assert "description" in execute_schema["required"]
+            assert execute_schema["properties"]["description"]["type"] == "string"
             for tool_name in ("read", "write", "wait", "stop"):
                 tool = tools_by_name[tool_name]
                 properties = tool.inputSchema["properties"]
@@ -59,11 +62,21 @@ async def test_stdio_server_lists_and_executes_tools():
                 assert "opaque" in (tool.description or "")
                 assert "passed through unchanged" in (tool.description or "")
 
+            missing_description = await session.call_tool(
+                "execute",
+                {"command": "printf should-not-run", "side_effects": ["NONE"]},
+            )
+            assert missing_description.isError is True
+            assert isinstance(missing_description.content[0], TextContent)
+            assert "description" in missing_description.content[0].text
+            assert _payload(await session.call_tool("ps", {}))["executions"] == []
+
             result = await session.call_tool(
                 "execute",
                 {
                     "command": "printf protocol-ok",
                     "side_effects": ["NONE"],
+                    "description": "Print a marker to verify command execution",
                 },
             )
 
@@ -73,6 +86,11 @@ async def test_stdio_server_lists_and_executes_tools():
             assert isinstance(payload["execution_id"], str)
             assert isinstance(payload["process_id"], int)
             assert "pid" not in payload
+            assert "description" not in payload
+            listing = _payload(await session.call_tool("ps", {}))
+            entry = listing["executions"][0]
+            assert entry["execution_id"] == payload["execution_id"]
+            assert "description" not in entry
 
             rejected = await session.call_tool(
                 "read",
@@ -102,6 +120,7 @@ async def test_stdio_server_incremental_polling_does_not_replay_output():
                             "sleep 0.2; done"
                         ),
                         "side_effects": ["NONE"],
+                        "description": "Emit numbered chunks to verify incremental polling",
                         "yield_ms": 0,
                     },
                 )
@@ -172,6 +191,7 @@ async def test_stdio_server_background_input_wait_stop_and_cleanup_workflow():
                     {
                         "command": "cat",
                         "side_effects": ["NONE"],
+                        "description": "Echo input to verify interactive execution",
                         "close_stdin": False,
                         "yield_ms": 0,
                     },
@@ -213,6 +233,7 @@ async def test_stdio_server_background_input_wait_stop_and_cleanup_workflow():
                     {
                         "command": "sleep 30",
                         "side_effects": ["NONE"],
+                        "description": "Start a background process to verify stopping it",
                         "yield_ms": 0,
                     },
                 )