mcp-yieldshell 0.1.7__tar.gz

mcp_yieldshell-0.1.7/.gitignore

@@ -0,0 +1,166 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+bin/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nosenv/
+.pytest_cache/
+.tox/
+.grudge/
+.htmlcov/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to share your .python-version.
+#   For an app, this is usually fine to prevent.
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if Pipfile.lock is not desired, it can be added here.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, poetry.lock is generally recommended to be committed.
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, pdm.lock is generally recommended to be committed.
+#pdm.lock
+
+# PEP 582; project local packages directory (PDM, Poetry)
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# OS-specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDEs
+.vscode/
+.idea/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Project specific
+.cybervisor/
+.prompts/
+.antigravitycli/
+
+

mcp_yieldshell-0.1.7/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: mcp-yieldshell
+Version: 0.1.7
+Summary: A drop-in shell MCP that auto-yields long-running commands into managed background processes.
+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 background processes.
+
+## Why Auto-Yielding?
+
+Most shell tools present a frustrating choice: either block the LLM agent until the command finishes, or force the agent to decide upfront that a command should run in the background.
+
+**YieldShell MCP** solves this by keeping normal foreground semantics for fast commands, then automatically promoting long-running commands into managed background processes after a brief delay (`yield_ms`, default: 1 second).
+
+```mermaid
+graph TD
+    A[exec_command] --> B["Wait for yield_ms (default: 1s)"]
+    B --> C{Is process still running?}
+    C -->|Yes| D["backgrounded<br>Returns process_id"]
+    C -->|No| E["completed<br>Returns full output"]
+```
+
+- **Fast Commands** (e.g., `echo hello`, `ls`): Complete instantly, returning the output immediately.
+- **Long-Running Commands** (e.g., `npm run dev`, `docker build`, `sleep 60`): Automatically yield control back to the agent with a `process_id` and a snapshot of initial output, letting the agent decide when to `read`, `wait`, or `stop` the process.
+
+---
+
+## Installation
+
+### From Registry (Recommended)
+
+To run the published package via `uv`:
+
+```bash
+uv tool install mcp-yieldshell
+```
+
+### Local Development
+
+To clone and run locally:
+
+```bash
+git clone <repo-url> && cd mcp-yieldshell
+uv sync
+uv run mcp-yieldshell
+```
+
+---
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+To configure the server in Claude Desktop, add the configuration below to your Claude Desktop config file:
+
+*   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+*   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+#### Production (via uvx)
+
+```json
+{
+  "mcpServers": {
+    "yieldshell": {
+      "command": "uvx",
+      "args": ["mcp-yieldshell"]
+    }
+  }
+}
+```
+
+#### Production with Security Restrictions
+
+```json
+{
+  "mcpServers": {
+    "yieldshell": {
+      "command": "uvx",
+      "args": ["mcp-yieldshell"],
+      "env": {
+        "YIELDSHELL_ALLOWED_CWDS": "/home/user/projects:/tmp/build",
+        "YIELDSHELL_DEFAULT_TIMEOUT_MS": "300000"
+      }
+    }
+  }
+}
+```
+
+#### Local Development Setup
+
+Replace `/path/to/mcp-yieldshell` with the absolute path to your cloned repository:
+
+```json
+{
+  "mcpServers": {
+    "yieldshell": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/mcp-yieldshell",
+        "run",
+        "mcp-yieldshell"
+      ]
+    }
+  }
+}
+```
+
+### Cursor
+
+To configure the server in Cursor:
+1. Open **Cursor Settings** -> **Features** -> **MCP**.
+2. Click **+ Add New MCP Server**.
+3. Fill out the form:
+   - **Name**: `yieldshell`
+   - **Type**: `stdio`
+   - **Command**: `uvx mcp-yieldshell` (or `uv --directory /path/to/mcp-yieldshell run mcp-yieldshell` for local development)
+
+### OpenCode
+
+Add to your OpenCode MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "yieldshell": {
+      "command": "uvx",
+      "args": ["mcp-yieldshell"]
+    }
+  }
+}
+```
+
+---
+
+## Tool Reference
+
+### `exec`
+Execute a shell command. If the command runs longer than `yield_ms`, it yields a `process_id` and runs in the background.
+
+*   **Parameters**:
+    *   `command` (string, **required**): The command string to execute in the shell.
+    *   `cwd` (string, optional): Working directory for the command. Must be under allowed roots if `YIELDSHELL_ALLOWED_CWDS` is set. Defaults to `YIELDSHELL_DEFAULT_CWD`.
+    *   `env` (object of string to string, optional): Additive environment variable overlay. Merged into the parent environment.
+    *   `shell` (string, optional): A custom shell path to execute commands (e.g. `/bin/zsh`). Internally executed using the platform's default shell handler if omitted.
+    *   `stdin` (string, optional): Initial text input written to standard input immediately after spawning.
+    *   `name` (string, optional): A human-readable label/name to identify this process.
+    *   `yield_ms` (integer, optional): Milliseconds to wait before yielding execution to background. Clamped by `YIELDSHELL_MAX_YIELD_MS`. Defaults to `YIELDSHELL_DEFAULT_YIELD_MS` (5000ms).
+    *   `timeout_ms` (integer, optional): Total execution runtime limit in milliseconds. Process is killed if it runs longer than this. Defaults to `YIELDSHELL_DEFAULT_TIMEOUT_MS` (0 = no limit).
+    *   `max_output_bytes` (integer, optional): Maximum output bytes to capture in stdout/stderr ring buffers. Subject to `YIELDSHELL_MAX_OUTPUT_BYTES` cap.
+
+*   **Output Statuses**:
+    *   `completed`: Process finished within `yield_ms`. Returns exit code, stdout, and stderr.
+    *   `backgrounded`: Process auto-yielded. Returns `process_id` and `pid` for tracking.
+    *   `timed_out`: Process exceeded `timeout_ms` and was terminated.
+    *   `stopped`: Process was explicitly terminated.
+    *   `failed_to_start`: Command could not be spawned (e.g., bad directory or policy violation).
+    *   `failed`: An internal execution error occurred.
+
+### `read`
+Read stdout and/or stderr output from a running or completed background process.
+
+*   **Parameters**:
+    *   `process_id` (string, **required**): Unique identifier of the process.
+    *   `since_seq` (integer, optional): Return only output appended after this sequence number. Enables efficient incremental log polling.
+    *   `max_output_bytes` (integer, optional): Clamps the response size. Defaults to the server cap.
+    *   `streams` (string, default: `"both"`): The streams to read. Options: `"both"`, `"stdout"`, or `"stderr"`.
+
+*   **Returns**:
+    *   `process_id`, `status`, `exit_code`, `signal`, `next_seq` (sequence index to use in subsequent `since_seq` reads), `stdout`/`stderr` text, and a `truncated` flag.
+
+### `write`
+Write text input to the standard input (`stdin`) of a running process.
+
+*   **Parameters**:
+    *   `process_id` (string, **required**): Unique identifier of the process.
+    *   `input` (string, **required**): Text input to write.
+    *   `newline` (boolean, default: `false`): If `true`, appends `\n` to the input.
+
+### `wait`
+Block execution until the process exits or the wait timeout expires. This allows the LLM to pause and await completion without spawning a new execution loop.
+
+*   **Parameters**:
+    *   `process_id` (string, **required**): Unique identifier of the process.
+    *   `timeout_ms` (integer, default: `30000`): Maximum time to wait.
+    *   `max_output_bytes` (integer, optional): Maximum output bytes to return in the response.
+
+*   **Important**: If the wait timeout expires, `wait` returns the current status but **does not kill** the process. It continues running in the background.
+
+### `stop`
+Gracefully terminate or force kill a running process.
+
+*   **Parameters**:
+    *   `process_id` (string, **required**): Unique identifier of the process.
+    *   `signal` (string, default: `"SIGTERM"`): OS signal to send (e.g. `SIGTERM`, `SIGKILL`, `SIGINT`). Ignored on Windows.
+    *   `force_after_ms` (integer, default: `3000`): Grace period before escalating to force kill (`SIGKILL`).
+
+### `ps`
+List all managed processes.
+
+*   **Parameters**:
+    *   `include_completed` (boolean, default: `true`): If `false`, finished/stopped processes are excluded from the output.
+    *   `limit` (integer, default: `50`): Maximum number of entries.
+
+### `cleanup`
+Prune completed or stopped process records to free memory.
+
+*   **Parameters**:
+    *   `completed_older_than_ms` (integer, default: `3600000`): Prunes completed processes older than this threshold (1 hour default).
+    *   `stopped_older_than_ms` (integer, default: `3600000`): Prunes stopped, timed-out, or failed processes older than this threshold (1 hour default).
+
+---
+
+## Sequence Number & Incremental Reads
+
+To avoid sending duplicate data over the MCP protocol (which can consume context window space), the server implements a sequence-based polling protocol:
+
+1. Every output chunk appended to a process's ring buffer receives a unique, incremental sequence number (`seq`).
+2. When calling `exec`, `read`, or `wait`, the response includes a `next_seq` value representing the index of the next chunk to be written.
+3. To retrieve only *new* output, call `read` with `since_seq` set to the previously received `next_seq`.
+4. Omitting `since_seq` returns the entire contents currently stored in the buffer (clamped by `max_output_bytes`).
+
+---
+
+## Configuration Variables
+
+Configure the server by setting these environment variables prior to launch:
+
+| Environment Variable | Default Value | Description |
+|---|---|---|
+| `YIELDSHELL_DEFAULT_CWD` | Current directory | The fallback working directory for commands. |
+| `YIELDSHELL_ALLOWED_CWDS` | *(none)* | A list of allowed directory paths separated by `os.pathsep` (e.g., `:` on UNIX, `;` on Windows). If set, all command execution paths must resolve inside one of these roots. |
+| `YIELDSHELL_MAX_OUTPUT_BYTES` | `20000` | The default and maximum capacity of the ring buffers for stdout/stderr. |
+| `YIELDSHELL_MAX_PROCESSES` | `50` | Maximum concurrent managed processes. Spawning a new command when this limit is reached will return `failed_to_start`. |
+| `YIELDSHELL_DEFAULT_YIELD_MS` | `5000` | Fallback delay before auto-yielding. |
+| `YIELDSHELL_MAX_YIELD_MS` | `300000` | The maximum allowed value for the `yield_ms` parameter. |
+| `YIELDSHELL_DEFAULT_TIMEOUT_MS` | `0` | Default hard runtime limit (0 means no limit). |
+| `YIELDSHELL_DENY_COMMAND_REGEX` | *(none)* | A regular expression pattern. Commands matching this pattern are blocked before starting. |
+| `YIELDSHELL_ALLOW_COMMAND_REGEX` | *(none)* | A regular expression pattern. If set, only commands matching this pattern are permitted. |
+| `YIELDSHELL_REDACT_ENV_REGEX` | `TOKEN\|KEY\|SECRET\|PASSWORD` | Regex to identify sensitive environment variable keys. Their values are redacted in stdout/stderr outputs. |
+
+---
+
+## Security Notes
+
+*   **Arbitrary Code Execution**: This server executes shell commands on the host system. Always run the server inside a container, sandbox, or isolated development VM.
+*   **Path Validation**: CWD path verification uses absolute paths (`resolve()`), preventing path-traversal attacks (`../`) outside the allowed roots.
+*   **Additive Environments**: The `env` argument overlays existing env parameters. It merges with the parent process environment instead of completely replacing it, protecting critical OS vars.
+*   **Best-effort Redaction**: While values of variables matching `YIELDSHELL_REDACT_ENV_REGEX` are scrubbed from outputs, this is a best-effort system. Sensitive data printed through complex formats or argument lists might not be caught.
+
+---
+
+## Platform Support
+
+*   **POSIX (Linux & macOS)**: Fully supported. Spawns processes in distinct sessions (`start_new_session=True`), allowing signals (`SIGTERM`/`SIGKILL`) to target the entire process group. This ensures child processes started by commands (such as npm dev tasks) are completely cleaned up.
+*   **Windows**: Supported with best-effort process group controls. Windows lacks native POSIX signals, meaning `stop` and `timeout_ms` act on the primary process, and child subprocesses might persist if they do not exit cleanly.
+
+---
+
+## License
+
+MIT

mcp_yieldshell-0.1.7/README.md

@@ -0,0 +1,258 @@
+# YieldShell MCP
+
+A drop-in shell MCP server that auto-yields long-running commands into managed background processes.
+
+## Why Auto-Yielding?
+
+Most shell tools present a frustrating choice: either block the LLM agent until the command finishes, or force the agent to decide upfront that a command should run in the background.
+
+**YieldShell MCP** solves this by keeping normal foreground semantics for fast commands, then automatically promoting long-running commands into managed background processes after a brief delay (`yield_ms`, default: 1 second).
+
+```mermaid
+graph TD
+    A[exec_command] --> B["Wait for yield_ms (default: 1s)"]
+    B --> C{Is process still running?}
+    C -->|Yes| D["backgrounded<br>Returns process_id"]
+    C -->|No| E["completed<br>Returns full output"]
+```
+
+- **Fast Commands** (e.g., `echo hello`, `ls`): Complete instantly, returning the output immediately.
+- **Long-Running Commands** (e.g., `npm run dev`, `docker build`, `sleep 60`): Automatically yield control back to the agent with a `process_id` and a snapshot of initial output, letting the agent decide when to `read`, `wait`, or `stop` the process.
+
+---
+
+## Installation
+
+### From Registry (Recommended)
+
+To run the published package via `uv`:
+
+```bash
+uv tool install mcp-yieldshell
+```
+
+### Local Development
+
+To clone and run locally:
+
+```bash
+git clone <repo-url> && cd mcp-yieldshell
+uv sync
+uv run mcp-yieldshell
+```
+
+---
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+To configure the server in Claude Desktop, add the configuration below to your Claude Desktop config file:
+
+*   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+*   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+#### Production (via uvx)
+
+```json
+{
+  "mcpServers": {
+    "yieldshell": {
+      "command": "uvx",
+      "args": ["mcp-yieldshell"]
+    }
+  }
+}
+```
+
+#### Production with Security Restrictions
+
+```json
+{
+  "mcpServers": {
+    "yieldshell": {
+      "command": "uvx",
+      "args": ["mcp-yieldshell"],
+      "env": {
+        "YIELDSHELL_ALLOWED_CWDS": "/home/user/projects:/tmp/build",
+        "YIELDSHELL_DEFAULT_TIMEOUT_MS": "300000"
+      }
+    }
+  }
+}
+```
+
+#### Local Development Setup
+
+Replace `/path/to/mcp-yieldshell` with the absolute path to your cloned repository:
+
+```json
+{
+  "mcpServers": {
+    "yieldshell": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/mcp-yieldshell",
+        "run",
+        "mcp-yieldshell"
+      ]
+    }
+  }
+}
+```
+
+### Cursor
+
+To configure the server in Cursor:
+1. Open **Cursor Settings** -> **Features** -> **MCP**.
+2. Click **+ Add New MCP Server**.
+3. Fill out the form:
+   - **Name**: `yieldshell`
+   - **Type**: `stdio`
+   - **Command**: `uvx mcp-yieldshell` (or `uv --directory /path/to/mcp-yieldshell run mcp-yieldshell` for local development)
+
+### OpenCode
+
+Add to your OpenCode MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "yieldshell": {
+      "command": "uvx",
+      "args": ["mcp-yieldshell"]
+    }
+  }
+}
+```
+
+---
+
+## Tool Reference
+
+### `exec`
+Execute a shell command. If the command runs longer than `yield_ms`, it yields a `process_id` and runs in the background.
+
+*   **Parameters**:
+    *   `command` (string, **required**): The command string to execute in the shell.
+    *   `cwd` (string, optional): Working directory for the command. Must be under allowed roots if `YIELDSHELL_ALLOWED_CWDS` is set. Defaults to `YIELDSHELL_DEFAULT_CWD`.
+    *   `env` (object of string to string, optional): Additive environment variable overlay. Merged into the parent environment.
+    *   `shell` (string, optional): A custom shell path to execute commands (e.g. `/bin/zsh`). Internally executed using the platform's default shell handler if omitted.
+    *   `stdin` (string, optional): Initial text input written to standard input immediately after spawning.
+    *   `name` (string, optional): A human-readable label/name to identify this process.
+    *   `yield_ms` (integer, optional): Milliseconds to wait before yielding execution to background. Clamped by `YIELDSHELL_MAX_YIELD_MS`. Defaults to `YIELDSHELL_DEFAULT_YIELD_MS` (5000ms).
+    *   `timeout_ms` (integer, optional): Total execution runtime limit in milliseconds. Process is killed if it runs longer than this. Defaults to `YIELDSHELL_DEFAULT_TIMEOUT_MS` (0 = no limit).
+    *   `max_output_bytes` (integer, optional): Maximum output bytes to capture in stdout/stderr ring buffers. Subject to `YIELDSHELL_MAX_OUTPUT_BYTES` cap.
+
+*   **Output Statuses**:
+    *   `completed`: Process finished within `yield_ms`. Returns exit code, stdout, and stderr.
+    *   `backgrounded`: Process auto-yielded. Returns `process_id` and `pid` for tracking.
+    *   `timed_out`: Process exceeded `timeout_ms` and was terminated.
+    *   `stopped`: Process was explicitly terminated.
+    *   `failed_to_start`: Command could not be spawned (e.g., bad directory or policy violation).
+    *   `failed`: An internal execution error occurred.
+
+### `read`
+Read stdout and/or stderr output from a running or completed background process.
+
+*   **Parameters**:
+    *   `process_id` (string, **required**): Unique identifier of the process.
+    *   `since_seq` (integer, optional): Return only output appended after this sequence number. Enables efficient incremental log polling.
+    *   `max_output_bytes` (integer, optional): Clamps the response size. Defaults to the server cap.
+    *   `streams` (string, default: `"both"`): The streams to read. Options: `"both"`, `"stdout"`, or `"stderr"`.
+
+*   **Returns**:
+    *   `process_id`, `status`, `exit_code`, `signal`, `next_seq` (sequence index to use in subsequent `since_seq` reads), `stdout`/`stderr` text, and a `truncated` flag.
+
+### `write`
+Write text input to the standard input (`stdin`) of a running process.
+
+*   **Parameters**:
+    *   `process_id` (string, **required**): Unique identifier of the process.
+    *   `input` (string, **required**): Text input to write.
+    *   `newline` (boolean, default: `false`): If `true`, appends `\n` to the input.
+
+### `wait`
+Block execution until the process exits or the wait timeout expires. This allows the LLM to pause and await completion without spawning a new execution loop.
+
+*   **Parameters**:
+    *   `process_id` (string, **required**): Unique identifier of the process.
+    *   `timeout_ms` (integer, default: `30000`): Maximum time to wait.
+    *   `max_output_bytes` (integer, optional): Maximum output bytes to return in the response.
+
+*   **Important**: If the wait timeout expires, `wait` returns the current status but **does not kill** the process. It continues running in the background.
+
+### `stop`
+Gracefully terminate or force kill a running process.
+
+*   **Parameters**:
+    *   `process_id` (string, **required**): Unique identifier of the process.
+    *   `signal` (string, default: `"SIGTERM"`): OS signal to send (e.g. `SIGTERM`, `SIGKILL`, `SIGINT`). Ignored on Windows.
+    *   `force_after_ms` (integer, default: `3000`): Grace period before escalating to force kill (`SIGKILL`).
+
+### `ps`
+List all managed processes.
+
+*   **Parameters**:
+    *   `include_completed` (boolean, default: `true`): If `false`, finished/stopped processes are excluded from the output.
+    *   `limit` (integer, default: `50`): Maximum number of entries.
+
+### `cleanup`
+Prune completed or stopped process records to free memory.
+
+*   **Parameters**:
+    *   `completed_older_than_ms` (integer, default: `3600000`): Prunes completed processes older than this threshold (1 hour default).
+    *   `stopped_older_than_ms` (integer, default: `3600000`): Prunes stopped, timed-out, or failed processes older than this threshold (1 hour default).
+
+---
+
+## Sequence Number & Incremental Reads
+
+To avoid sending duplicate data over the MCP protocol (which can consume context window space), the server implements a sequence-based polling protocol:
+
+1. Every output chunk appended to a process's ring buffer receives a unique, incremental sequence number (`seq`).
+2. When calling `exec`, `read`, or `wait`, the response includes a `next_seq` value representing the index of the next chunk to be written.
+3. To retrieve only *new* output, call `read` with `since_seq` set to the previously received `next_seq`.
+4. Omitting `since_seq` returns the entire contents currently stored in the buffer (clamped by `max_output_bytes`).
+
+---
+
+## Configuration Variables
+
+Configure the server by setting these environment variables prior to launch:
+
+| Environment Variable | Default Value | Description |
+|---|---|---|
+| `YIELDSHELL_DEFAULT_CWD` | Current directory | The fallback working directory for commands. |
+| `YIELDSHELL_ALLOWED_CWDS` | *(none)* | A list of allowed directory paths separated by `os.pathsep` (e.g., `:` on UNIX, `;` on Windows). If set, all command execution paths must resolve inside one of these roots. |
+| `YIELDSHELL_MAX_OUTPUT_BYTES` | `20000` | The default and maximum capacity of the ring buffers for stdout/stderr. |
+| `YIELDSHELL_MAX_PROCESSES` | `50` | Maximum concurrent managed processes. Spawning a new command when this limit is reached will return `failed_to_start`. |
+| `YIELDSHELL_DEFAULT_YIELD_MS` | `5000` | Fallback delay before auto-yielding. |
+| `YIELDSHELL_MAX_YIELD_MS` | `300000` | The maximum allowed value for the `yield_ms` parameter. |
+| `YIELDSHELL_DEFAULT_TIMEOUT_MS` | `0` | Default hard runtime limit (0 means no limit). |
+| `YIELDSHELL_DENY_COMMAND_REGEX` | *(none)* | A regular expression pattern. Commands matching this pattern are blocked before starting. |
+| `YIELDSHELL_ALLOW_COMMAND_REGEX` | *(none)* | A regular expression pattern. If set, only commands matching this pattern are permitted. |
+| `YIELDSHELL_REDACT_ENV_REGEX` | `TOKEN\|KEY\|SECRET\|PASSWORD` | Regex to identify sensitive environment variable keys. Their values are redacted in stdout/stderr outputs. |
+
+---
+
+## Security Notes
+
+*   **Arbitrary Code Execution**: This server executes shell commands on the host system. Always run the server inside a container, sandbox, or isolated development VM.
+*   **Path Validation**: CWD path verification uses absolute paths (`resolve()`), preventing path-traversal attacks (`../`) outside the allowed roots.
+*   **Additive Environments**: The `env` argument overlays existing env parameters. It merges with the parent process environment instead of completely replacing it, protecting critical OS vars.
+*   **Best-effort Redaction**: While values of variables matching `YIELDSHELL_REDACT_ENV_REGEX` are scrubbed from outputs, this is a best-effort system. Sensitive data printed through complex formats or argument lists might not be caught.
+
+---
+
+## Platform Support
+
+*   **POSIX (Linux & macOS)**: Fully supported. Spawns processes in distinct sessions (`start_new_session=True`), allowing signals (`SIGTERM`/`SIGKILL`) to target the entire process group. This ensures child processes started by commands (such as npm dev tasks) are completely cleaned up.
+*   **Windows**: Supported with best-effort process group controls. Windows lacks native POSIX signals, meaning `stop` and `timeout_ms` act on the primary process, and child subprocesses might persist if they do not exit cleanly.
+
+---
+
+## License
+
+MIT