Yaniv Golan Release Notes

Fixed

• resources/read of a templated resource with a custom URI scheme now reaches the project provider: Template metadata never enters the static resource registry, so reading a URI expanded from a template such as myapi://items/{id} found no provider and fell back to file, which returned -32002 Resource not found. Provider inference now maps an unrecognised scheme to ${MCPBASH_PROVIDERS_DIR}/<scheme>.sh when that script exists. Statically discovered resources with a custom scheme and no provider field use the same inference. For a client-supplied URI this routing applies only to schemes the project declares, through a resource template or a static resource bound to that provider. A script in providers/ is not reachable by naming its scheme alone. Schemes are matched case-sensitively. The scanner change also means a statically discovered ui:// resource with no provider field now uses the ui provider, not file (which could not serve it).
• File URIs no longer fail intermittently under bash 5.3: mcp_uri_url_encode declared local LC_ALL=C. Under bash 5.3 with LC_CTYPE=UTF-8 (the macOS Terminal default) that made calls in $(...) report failure about 1 time in 16, so resources without an explicit uri could drop out of resources/list. The function now runs in a subshell and sets LC_ALL=C there. …

Fixed

• Bundle prompts now include text field per MCPB v0.3 schema: The bundler reads the template .txt file for each prompt and embeds its content as the required text field in the manifest's prompts array. Prompts without a resolvable template file are excluded from the manifest to maintain schema compliance. Previously, prompts only had name, description, and arguments, which failed strict v0.3 validation.
• Bundle prompt scan now finds scaffolded prompt layouts: The glob pattern now matches prompts/<name>/<name>.meta.json (created by mcp-bash scaffold prompt) in addition to the flat and prompt.meta.json nested layouts.

Added

• Semver validation warning for bundle version: mcp-bash bundle --validate now warns when the resolved version string is not valid semver (MAJOR.MINOR.PATCH). The upstream MCPB CLI is adding strict semver rejection; this warning gives early feedback. Non-semver versions still produce bundles but may be rejected by future MCPB tooling.

Changed

• MCPB documentation updated for upstream spec changes: docs/MCPB.md now documents the text field in prompt manifest entries, manifest v0.4 awareness (UV runtime), clarifies that platform_overrides.env merges with (not replaces) base env, and notes the potential @anthropic-ai/mcpb package rename.

Fixed

• Bundle icon/screenshot path resolution now works on macOS: The v1.2.1 fix for resolving server.d/-relative paths used realpath -m (GNU coreutils), which macOS's BSD realpath doesn't support. Replaced with a portable shell-based resolution using cd + pwd. Also normalizes the destination path in the bundle to avoid ../ escaping the bundle directory.
• Installer warns when another mcp-bash shadows the new install: After installation, the installer checks if a different mcp-bash binary earlier in PATH would take precedence over the one just installed (e.g., a stale manual install shadowing a Homebrew install). Prints version and path of the shadowing binary.

Fixed

• Installer no longer blocks when MCPBASH_HOME points to a different path: Previously, the installer refused to run whenever MCPBASH_HOME was set, even if it pointed to a vendored runtime (.mcp-bash/) rather than the install target. The check now only blocks when MCPBASH_HOME matches the install directory, allowing CI workflows to install the full CLI alongside a vendored runtime.
• Vendored runtime gives a clear error for CLI commands: Running CLI commands (e.g., validate, bundle, doctor) against a vendored or embedded runtime previously failed with a cryptic "No such file or directory". The entrypoint now detects missing CLI modules and prints a helpful message explaining that a full mcp-bash install is required.
• Vendor docs now clarify CLI commands are not included: docs/VENDORING.md explicitly lists which commands require a full install and notes that the installer won't conflict with a vendored copy.
• Bundle resolves icons and screenshots paths from both project root and server.d/: Paths in the server.meta.json icons and screenshots arrays can now be relative to either the project root (assets/icons/foo.png) or to server.d/ (../assets/icons/foo.png). Previously, only project-root-relative paths worked, so ../ paths from server.d/ would fail with a spurious warning.

Added

• mcp-bash vendor command: Embeds the mcp-bash runtime into a project's .mcp-bash/ directory for committing to git, eliminating the need for a system-wide install at runtime. Useful for dev teams, CI pipelines, and MCP clients that do not support MCPB bundles. Includes --verify for SHA-256 integrity checking, --upgrade to update in place, and --dry-run to preview. Writes a vendor.json lockfile recording version, digest, source, and timestamp. See docs/VENDORING.md.
• Homebrew tap: mcp-bash is now installable via brew install yaniv-golan/mcp-bash/mcp-bash. Homebrew handles upgrades (brew upgrade mcp-bash) and is the recommended install method on macOS and Linux. The formula is auto-bumped on each release.
• Renovate preset for vendored copies: A renovate-preset.json in this repo configures Renovate to track vendor.json against GitHub Releases and open automatic upgrade PRs. Users opt in with {"extends": ["github>yaniv-golan/mcp-bash-framework//renovate-preset"]} in their renovate.json.

Fixed …

Added

• Static tools array in MCPB manifest: The bundler now scans tools/*/tool.meta.json at bundle time and emits a tools array of {name, description} objects in manifest.json. This enables pre-install discovery in extension stores — clients can show what an extension offers before downloading. Emitted alongside the existing tools_generated flag.
• Static prompts array in MCPB manifest: Same pattern for prompts — scans prompts/*.meta.json and prompts/*/prompt.meta.json, extracts name, description, and arguments (property names from the JSON schema). Emitted alongside prompts_generated.
• icons array passthrough in MCPB manifest: When server.meta.json defines an icons array (with {src, size, theme} objects for light/dark and multi-size variants), the bundler passes it through to manifest.json and copies referenced local files into the bundle. Supports the MCPB spec's themed icon feature for proper dark mode rendering in extension stores.
• screenshots passthrough in MCPB manifest: When server.meta.json defines a screenshots array, the bundler passes it through and copies referenced local files into the bundle for extension store listings. …

Fixed

• mcp-bash config now includes MCPBASH_TOOL_ALLOWLIST in all output modes: All six output modes (--json, --client claude-desktop, --client cursor, --client claude-cli, --client windsurf, --client librechat, --wrapper/--wrapper-env, --inspector) now emit MCPBASH_TOOL_ALLOWLIST="*" in the generated env block. Previously, the allowlist was omitted, causing all tools to be silently blocked by the default-deny policy when users copied config output verbatim.

Added

• Per-Client Snippets in README include MCPBASH_TOOL_ALLOWLIST: All six client setup snippets (Claude Desktop, Claude CLI, LibreChat, OpenAI Agents SDK, Clawdbot, Highlight AI) now show MCPBASH_TOOL_ALLOWLIST="*" with a security note directing users to narrow it for production.
• Agent Quick Start section in llms.txt and llms-full.txt: A new "Quick Start for AI Agents Building MCP Servers" section provides step-by-step build instructions, highlights the critical allowlist requirement, and documents CLI wrapper patterns (PATH resolution via mcp_detect_cli, set -uo pipefail error handling).
• New example examples/15-cli-wrapper: Demonstrates the most common real-world MCP server pattern — wrapping an external CLI with mcp_detect_cli for PATH resolution, set -uo pipefail for error capture, and SDK helpers for MCP-compliant output. …

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 <name> — creates standalone UI in ui/<name>/
  • mcp-bash scaffold ui --tool <name> — 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. …

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. …

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 …

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. …

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.

Added

• --stderr-file option for mcp_run_with_progress: New option to capture non-progress stderr lines to a file while still forwarding progress notifications to MCP. Enables MCP tools to report detailed CLI error messages when using progress forwarding. See BEST-PRACTICES.md §4.9 "Capturing non-progress stderr".

Documentation

• SECURITY.md: Added production deployment checklist, critical policy.sh security warning, known security limitations section (rate limiting, TOCTOU, input validation, debug logging, env inheritance), and gateway requirements for remote access.