MCP Bash Framework Release Notes

Changed

• MCPBASH_LOG_LEVEL boolean normalization: Boolean-like values are now normalized to RFC-5424 levels: true / 1 → debug, false / 0 → info. This supports UI toggles (like Claude Desktop Extensions settings) that map boolean debug settings to MCPBASH_LOG_LEVEL. The normalized value is re-exported so tool subprocesses inherit canonical level names.
  Breaking: Existing deployments setting MCPBASH_LOG_LEVEL=true (intending "enable logging") will now get debug-level verbosity instead of info-level.

Added

• MCP Apps extension support (SEP-1865): Full implementation of the MCP Apps specification for serving interactive HTML UIs. Tools can now provide rich visual interfaces via ui:// resources. Includes auto-discovery of UI resources, CSP header generation, and template-based UI generation.
• Auto-inference of _meta.ui.resourceUri: When a tool has a ui/ subdirectory containing index.html or ui.meta.json, the framework automatically links the tool to its UI resource. No manual _meta.ui configuration needed—the URI is generated as ui://{server-name}/{tool-name}.
• mcp-bash scaffold ui command: New scaffold command for creating UI resources:
  • mcp-bash scaffold ui — creates standalone UI in ui//
  • mcp-bash scaffold ui --tool — creates UI for existing tool (auto-linked)
  • Generates index.html with MCP Apps SDK integration, ui.meta.json with CSP configuration
• --ui flag for mcp-bash scaffold tool: Create a tool with UI in one command: mcp-bash scaffold tool weather --ui. Generates both the tool files and the ui/ subdirectory with working templates.
• UI Resources Guide: New documentation at docs/guides/ui-resources.md covering static HTML UIs, template-based UIs, auto-linking, CSP configuration, and the MCP Apps SDK.
• Pre-push hook: New .githooks/pre-push runs unit tests and bundle validation before pushing, catching issues locally before CI.
• Bash 3.2 lint check: test/lint.sh now sources core libs with /bin/bash to catch bash 4+ features (like declare -gA) before CI fails on macOS.

Fixed

• MCPBASH_HOME override support: The bin/mcp-bash script now respects the MCPBASH_HOME environment variable, allowing the installed binary to use development code during testing.

Documentation

• Added MCP Apps concepts documentation (docs/concepts/mcp-apps.md)
• Added UI SDK reference (docs/reference/ui-sdk.md)
• Added UI templates reference (docs/reference/ui-templates.md)
• Added known limitations section for Claude Desktop MCP Apps support
• Updated docs/PROJECT-STRUCTURE.md to document the ui/ directory
• Updated scaffold READMEs with UI documentation links
• Added MCP Apps to README feature list and spec compliance table

mcp-bash reaches 1.0.0

mcp-bash reaches 1.0.0 — the framework is now considered stable for production use. The protocol implementation is complete, the SDK API is mature, and the project has been validated across multiple MCP servers and clients.

Added

• Clawdbot client documentation: Added configuration instructions for Clawdbot, which uses mcporter for MCP integration. Config goes in ~/.mcporter/mcporter.json.
• Highlight AI client documentation: Added configuration instructions for Highlight AI. Tested end-to-end. Uses UI-based config: Settings → Connections → Add → Custom command.

Changed

• Version bump to 1.0.0: Signals API stability. The MCP protocol implementation covers the full 2025-11-25 spec (tools, resources, prompts, elicitation, roots, progress, cancellation). No breaking changes are expected in the 1.x series.

Added

• Zombie process mitigation: MCP servers now include automatic defenses against zombie/orphan process accumulation.
• Idle timeout (default: 1 hour) exits the server when no client activity is received.
• Orphan detection (Unix only) exits the server when the parent process dies. Both features are enabled by default and can be configured via environment variables (MCPBASH_IDLE_TIMEOUT, MCPBASH_IDLE_TIMEOUT_ENABLED, MCPBASH_ORPHAN_CHECK_ENABLED, MCPBASH_ORPHAN_CHECK_INTERVAL). See DEBUGGING.md for details.

Fixed

• Registry generation missing progressExtendsTimeout and maxTimeoutSecs fields: Tools with progress-aware timeout configuration in tool.meta.json would silently fall back to fixed countdown mode because the registry generator did not copy progressExtendsTimeout or maxTimeoutSecs fields to .registry/tools.json. The timeout watchdog reads these values from the registry at runtime, but they were always null, causing MCPBASH_PROGRESS_EXTENDS_TIMEOUT to never be set. Fix: added both fields to auto-discovery and manual registration registry generation paths. Added unit tests to prevent regression.
• .debug file detection not enabling MCP debug logs: The server.d/.debug marker file correctly set MCPBASH_LOG_LEVEL=debug, but debug-level MCP log notifications were still filtered out. Root cause: MCP_LOG_LEVEL_CURRENT was initialized when logging.sh was sourced (before .debug file detection runs). Fix: sync MCP logging level after mcp_runtime_init_paths() in mcp_core_bootstrap_state().
• Zombie mitigations causing CI test failures: The zombie process mitigation feature's timeout-based read loop caused widespread test failures in CI. The new read loop with read -t behaves differently than the simple blocking read when processing piped input. Fix: disable both idle timeout and orphan detection when MCPBASH_CI_MODE=true to restore simple blocking read loop behavior.
• Log notification corruption in handler responses: Log notifications emitted inside command substitutions (e.g., during registry building) could intermittently corrupt JSON-RPC responses due to unreliable fd inheritance in nested bash subshells. Fix: defer log notifications to a queue file during handler execution and flush after the handler completes. This ensures notifications are emitted outside any command substitution context. Trade-off: log notifications are now batched per-request rather than streaming in real-time. Progress notifications (used for timeout extension) are unaffected as they use a separate file-based mechanism.

Added

• timeoutHint field in tool.meta.json: New optional field that provides actionable guidance appended to timeout error messages. When a tool times out, the hint text is displayed as a "Suggestion:" in the error message and is also available programmatically via structuredContent.error.hint. This helps LLMs adjust their approach (e.g., use smaller batches, enable dry-run mode). Example: "timeoutHint": "Use dryRun=true first. For large datasets, try limit <= 100.". See Timeout Strategy Guide for details.

Documentation

• Runtime CLI detection pattern: New section in BEST-PRACTICES.md documenting how to detect external CLIs when MCP hosts spawn servers with restricted PATH (missing version manager shims). Includes mcp_detect_cli() helper covering pyenv, asdf, mise, nvm, fnm, volta, rbenv, goenv, cargo, and Homebrew paths. Clarifies that server.d/env.sh is not auto-sourced at server startup.

Changed

• Progress-aware timeout now extends on any pattern match: When using mcp_run_with_progress, the timeout watchdog now extends on any pattern match, not just lines with a .progress field. This decouples activity detection ("I'm alive") from progress reporting ("I'm X% done"). Tools emitting structured events like {"type":"step_start"} that match the progress pattern will now survive past their nominal timeout even without a .progress field. Debug logging added when activity is detected without progress extraction. See BEST-PRACTICES.md §4.9 for details.

Added

• --array-path parameter for mcp_json_truncate: New optional parameter to specify which array to truncate in JSON responses. Allows tool authors to declare their data structure (e.g., --array-path ".data", --array-path ".hits.items") instead of relying on hardcoded heuristics. Returns structured errors (path_not_found, invalid_array_path, invalid_path_syntax) for invalid paths. Path syntax is validated before jq interpolation for security. Backward compatible: without --array-path, falls back to top-level arrays and .results heuristic. See BEST-PRACTICES.md "Truncating large results" section.

Added

• mcp_config_load / mcp_config_get SDK helpers: Unified configuration loading with standard precedence (env var → file → example → defaults). mcp_config_load accepts --env, --file, --example, and --defaults flags; performs shallow merge with jq (last-source-wins without jq). mcp_config_get extracts values by jq path with optional --default. Supports minimal mode (top-level keys only without jq). See BEST-PRACTICES.md "Configuration loading" section.

• user_config bundle support: Bundles can now declare user-configurable options via MCPB_USER_CONFIG_FILE, MCPB_USER_CONFIG_ENV_MAP, and MCPB_USER_CONFIG_ARGS_MAP in mcpb.conf, or via user_config, user_config_env_map, and user_config_args_map in server.d/server.meta.json. User config fields are validated for schema correctness (type, title required; type-specific properties like sensitive, min/max, multiple). Env and args mappings are validated to reference existing config keys. Generated manifests include user_config section and proper ${user_config.KEY} variable substitution in mcp_config.env and mcp_config.args. See docs/MCPB.md "User Configuration" section.

• Additional MCPB manifest fields: Bundle manifests now support optional metadata fields for registry/marketplace listing: MCPB_LICENSE (SPDX identifier), MCPB_KEYWORDS (space-separated), MCPB_HOMEPAGE, MCPB_DOCUMENTATION, MCPB_SUPPORT, MCPB_PRIVACY_POLICIES (space-separated URLs). Also added compatibility constraints: MCPB_COMPAT_CLAUDE_DESKTOP (semver), MCPB_RUNTIME_PYTHON, MCPB_RUNTIME_NODE. All fields are optional and omitted from manifest when not set.

• mcp_error SDK helper: Convenience wrapper for tool execution errors with consistent schema. Takes with optional --hint and --data flags. Builds normalized error JSON and delegates to mcp_result_error. Logs at debug level for all errors; logs at warn level when hint provided. See BEST-PRACTICES.md "Convenience error helper" section and ERRORS.md "SDK Support" section.

• mcp_download_safe SDK helper: New function for SSRF-safe HTTPS downloads in tools. Wraps the HTTPS provider with ergonomic API: named flags (--url, --out, --allow), automatic retries with exponential backoff, structured JSON responses ({"success":true,"bytes":N,"path":"..."} or {"success":false,"error":{...}}), and set -e safe (always returns 0). See BEST-PRACTICES.md "Secure downloads" section.

• mcp_download_safe_or_fail SDK helper: Fail-fast wrapper for mcp_download_safe that returns the output path on success or fails the tool with -32602 on error. Simplifies common "download or die" pattern: path=$(mcp_download_safe_or_fail --url "$url" --out "$tmp" --allow "example.com").

• mcp_result_text_with_resource SDK helper: Convenience wrapper for tool responses with embedded resources. Combines mcp_result_success with resource embedding via --path, --mime, --uri flags. Supports multiple resources. MIME type auto-detected if omitted (requires file command). See BEST-PRACTICES.md "Embedding resources in tool responses" section.

• Redirect detection in HTTPS provider: URLs that return 3xx redirects now produce a redirect error type with the target location in .error.location. This helps users identify canonical URLs without silently failing. Redirects are not retried (deterministic behavior).

• MCPBASH_HTTPS_USER_AGENT env var: Custom User-Agent for HTTPS provider requests. The mcp_download_safe SDK helper sets mcpbash/ (tool-sdk) by default; override via --user-agent flag or this env var.

Added

• Bundle libs sync test: New CI test (test/unit/bundle_libs_sync.bats) that verifies BUNDLE_REQUIRED_LIBS includes all libraries sourced by bin/mcp-bash. Prevents broken releases with missing bundled libraries (e.g., 0.9.9, 0.9.10).

Fixed

• errexit (set -e) state leak in functions: Fixed a bug where mcp_with_retry and several internal functions would modify the caller's errexit shell state. Functions using set +e; cmd; rc=$?; set -e patterns would leave errexit enabled even if the caller had it disabled, causing unexpected script termination. Replaced with errexit-safe cmd && rc=0 || rc=$? pattern. Affected functions: mcp_with_retry (SDK), mcp_tools_validate_output_schema, mcp_tools_call, mcp_registry_register_execute, mcp_cli_health.

Added

• mcp_extract_cli_error SDK helper: New function to extract error messages from CLI tools that output structured JSON errors to stdout (common with --json flags) instead of stderr. Checks common patterns (.error.message, .error string, .message with status flags, .errors[0].message) before falling back to stderr. Improves LLM self-correction by providing meaningful error messages instead of empty strings. See BEST-PRACTICES.md §4.4 "Handling CLIs with structured JSON errors".

Fixed

• Incorrect JSON-RPC error code for tool errors: Changed "Tool path unavailable" and "Tool executable missing" errors from -32601 (Method not found) to -32602 (Invalid params) per JSON-RPC 2.0 and MCP specifications. The -32601 code is reserved for when the RPC method itself doesn't exist; tool-related errors are parameter validation failures and should use -32602. This aligns with the existing "Tool not found" error which correctly uses -32602.