Yaniv Golan Release Notes

Behaviour changes to check before upgrading

• server.d/policy.sh is test-loaded once at every server start, so its top-level code runs one extra time: to catch a policy.sh that dies while it is loaded, the server sources it in a separate bash process at each start, before any call. Anything its top level does outside its functions (writing files, network calls, output) now happens twice per start, and a slow top level delays the server's first answer. Keep policy.sh to function definitions and plain assignments.
• Tool calls are refused when policy.sh dies while it is loaded: a top-level command that fails, a syntax error in a file policy.sh sources, or a top-level exit. Before, a syntax error in a sourced file could leave the project's hook undefined on bash 4+, so the tool ran without the project's restrictions; a failing top-level command or an exit ended the call with no response. Now the call gets an error result naming the reason, and the reason is printed on stderr at startup.
• Calls are refused when a file policy.sh sources breaks while the server runs, if the project's hook (mcp_tools_policy_project, or a mcp_tools_policy_check that replaces the built-in check) is then no longer defined. Other mid-run breaks are caught at the next start: restart the server after editing files policy.sh sources.

Changed

• test_exit_stops_tools.sh waits up to 30 s for its tool to start (it timed out under load).

Fixed

• The server stopped at startup in CI mode when TMPDIR was unset: with MCPBASH_CI_MODE=true outside GitHub Actions (no RUNNER_TEMP or GITHUB_WORKSPACE), for example in a Docker container, bash 4 and later stopped with "TMPDIR: unbound variable", because the temp-root default was a malformed expansion. It now uses TMPDIR without its trailing slash, or /tmp. Bash 3.2 was not stopped but got an empty root, which a later fallback replaced.
• mcp-bash run-tool put a log line in the result for a resource outside the roots: the warning that names the skipped path and the allowed roots was written to the same stdout as the resource, and became a {"type":"resource"} block holding the log notification. Only resource objects are embedded now. Over stdio the server was not affected.

Fixed

• Tool log messages never arrived with live progress on: with MCPBASH_ENABLE_LIVE_PROGRESS=true, the server flushed a tool's log stream from the wrong file name (log..ndjson instead of logs..ndjson), so mcp_log notifications from tools never reached the client. Fixing that exposed a race: the background flusher and the worker's final flush could both send the same progress or log line. Each stream's flush now holds a lock, and sends exactly the bytes it measured and only complete lines (a line the tool appended while the flush ran, or a line still being written, waits for the next flush), so every line is sent once.
• mcp_client_supports_ui was always false inside tools: the SDK reads MCPBASH_CLIENT_SUPPORTS_UI or a file in the server's state directory, but the server passed neither to tools. So mcp_result_with_ui always sent its text fallback, even to a client that declared the MCP Apps extension (io.modelcontextprotocol/ui). The server now sets MCPBASH_CLIENT_SUPPORTS_UI (1 or 0) for each tool call.
• A tool's stderr with bytes that aren't valid UTF-8 was cut short on macOS: in a UTF-8 locale, BSD tr stops at the first byte that isn't valid UTF-8, so _meta.stderr, the error message of a failed tool and error.data.stderrTail ended there, and the server logged "tr: Illegal byte sequence". Those tr calls now run in the C locale; the bytes reach the client as U+FFFD.

Behaviour changes to check before upgrading

• Error results from tools with an outputSchema have no structuredContent: when a tool that declares an outputSchema returns an error result carrying structuredContent (the {success: false, error} envelope from mcp_error and mcp_result_error, or JSON output with a non-zero exit), the server now drops structuredContent and moves the envelope's error to _meta["mcpbash/error"] (type, message, hint, and data, or the error's other fields as data). The TypeScript SDK client, which Claude Desktop uses, checks structuredContent against the outputSchema on error results too, so those errors failed in Desktop instead of reaching the model. The text content is unchanged. Tools without an outputSchema are unchanged.

Fixed

• A new server served the registry cache an earlier run left behind: a server that loaded .registry/tools.json (or the prompts, resources or templates cache) at startup treated it as scanned at that moment, so for the first TTL seconds (5 by default) it served the cached definitions, however old. That is when a client lists and makes its first call: after a tool's outputSchema changed, its first call failed with "Tool output does not satisfy outputSchema", and the change only showed up after a later rescan sent list_changed. A loaded cache is now dated by its file's modification time, so one older than the TTL, or dated in the future (a copied or extracted project, clock skew), is rescanned first.

Behaviour changes to check before upgrading

• Tool policy denials: a call refused by MCPBASH_TOOL_ALLOWLIST or server.d/policy.sh now returns a tool result with isError: true and type policy_denied instead of a JSON-RPC error, and a policy's custom error code is no longer sent. mcp-bash run-tool output for a denial no longer contains the _mcpToolError marker: test harnesses that detect a refused call through that marker must check .isError instead (run-tool still exits 1).

• Migrating to the frozen helpers: mcp-bash migrate --write changes your tools, not your tests. Update your own tests that assert the {success, result} envelope or the _mcpToolError marker; migrate can't see them.

• SDK argument helpers: mcp_args_require, mcp_args_int, mcp_args_bool, mcp_require_path and mcp_download_safe_or_fail now report a missing or invalid argument as a tool error result (isError: true, _meta["mcpbash/error"].type = invalid_args) instead of a JSON-RPC -32602 error. Tests or clients that expect -32602 from these helpers must check .result.isError instead. mcp_fail_invalid_args itself still sends -32602.

• Tools now receive SIGTERM on timeout and cancel: tools used to run with SIGTERM ignored, so only SIGKILL stopped them. A tool's own trap … TERM now runs when its call times out or is cancelled, and gets about a second before SIGKILL.

Changed

• Argument helpers report errors the model can read: a missing or invalid argument rejected by the SDK helpers was a JSON-RPC error, which Claude Desktop shows only as a generic connector error. It is now an invalid_args error result, so the model can read it and retry. Called inside $(...), the helpers still deliver that result: it goes through the tool-error side channel, and the framework returns it as the tool's result. The script itself stops there only under set -e; without it, write x="$(mcp_args_require '.x')" || exit 1.

• New projects use the frozen helpers: mcp-bash new, init, and scaffold tool generate tools that return mcp_result_json with an outputSchema describing the data itself, show mcp_fail --type for errors, and record "mcpBash": {"apiVersion": 2} in server.meta.json.

• Examples and docs teach the frozen helpers: BEST-PRACTICES adds "Migrating to the 2.0 helpers".

• Policy denials are tool results, not JSON-RPC errors: A tools/call refused by the tool allowlist or a server.d/policy.sh rule returned a JSON-RPC error, which Claude Desktop shows only as "The connector returned an error or an invalid response", so neither the model nor the user saw why. It is now a tool result with isError: true, the denial message as text and _meta["mcpbash/error"] = {"type":"policy_denied","message":…} (plus the policy's data, if any). A policy's custom error code (for example -32600) is no longer sent. A rejected tool path, a missing executable and inherit mode without the allow flag stay JSON-RPC errors. mcp-bash run-tool prints the result and still exits 1.

Added

• Startup notice for APIs that change in 2.0: When a project uses APIs that change in mcp-bash 2.0, the server prints one line to stderr at startup, at most once a day per project, with the number of uses and a pointer to mcp-bash validate. The scan runs in the background and never writes to stdout. It is skipped for bundles (static registry), vendored runtimes, minimal mode and a read-only registry dir; MCPBASH_DEPRECATION_NOTICE=false turns it off.

• mcp-bash migrate: lists every use of an API that changes in 2.0 (check mode by default). --write applies the unambiguous rewrites into the frozen forms (mcp_fail_invalid_args / mcp_fail -32602|-32603 → mcp_fail --type; mcp_error followed by exit → mcp_fail --type; mcp_result_success → mcp_result_json) together with the tool's envelope-shaped outputSchema; a policy.sh hook that starts with the default check → mcp_tools_policy_project, then records "mcpBash": {"apiVersion": 2} once nothing else is pending. Anything ambiguous is listed as manual: captured $(…) output, "$@" forwarding, extra arguments, UI code reading .result, mcp_result_error. --write refuses a dirty git tree (unless --force) and a vendored .mcp-bash runtime older than these helpers (run mcp-bash vendor --upgrade first), and keeps .bak copies outside git. Exit status: 0 nothing pending, 1 automatic fixes pending, 2 manual work pending, 3 error. Also --list, --explain ID, --only, --skip, --json.

• mcp-bash doctor shows the tool and provider env policy: For tools and providers it shows the effective mode and where it came from (launch env, server.meta.json, or default), and whether each allowlisted variable is set, empty, an unexpanded placeholder or not set in the current shell. It also flags refused or invalid server.meta.json env keys, invalid allowlist names, and inherit without the operator opt-in. Values are never printed. doctor --json adds an envPolicy object and matching findings.

• Per-resource completion scripts work for resource templates: A completion/complete with ref/resource was matched only against static resources by exact URI, so a template's completion script was never run and the server returned values built from the URI string. Claude Desktop sends ref/resource only for template arguments, so per-resource completions did nothing there. The URI is now also matched against the templates (exactly by uriTemplate, or as a concrete URI), and the script is found by template name: resources/.completion.sh or resources//.completion.sh. MCP_RESOURCE_URI is the uriTemplate, and MCP_COMPLETION_ARGS_JSON .argument.name names the variable being completed.

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

Fixed

• Timed-out and cancelled tools left processes running: the tool wrapper ignored SIGTERM, and every process it started inherited that. A cancelled tool could keep running, and on timeout only the tool's own process was killed, so anything it started (for example a sleep or a git command) was left orphaned. Timeout now stops the tool and everything it started (TERM, then KILL after a second), and cancel stops the request's whole process group even when the worker exits first. A tool call with a timeout also no longer waits for the watchdog's next one-second tick after the tool finishes. Not on Git Bash, which has no process groups.

• No file error on stderr after a cancel: the delayed cancel cleanup no longer writes into the state directory of a server that has already exited.

• Two examples kept going after rejecting their input: examples/04-roots-basics read a file after rejecting its path as outside the allowed roots, and examples/12-config-and-downloads downloaded an http:// URL after rejecting it. Both used mcp_error, which reports an error but doesn't end the tool; they now use mcp_fail --type.

• A request split across the read timeout is answered: With the timed read loop (the default outside CI mode), a request whose bytes arrived on both sides of the read timeout was lost. On bash 4+ each part was answered as a separate, unparseable message; on bash 3.2 the first part was discarded. The request itself was never answered, and the client waited indefinitely. The server now keeps the partial input and joins it with the rest (bash 4+), or reads the rest of a started line without a timeout (bash 3.2). A final request without a trailing newline is still answered when input ends.

Added

• mcp-bash doctor warns when the git provider is enabled but git is missing: With MCPBASH_ENABLE_GIT_PROVIDER=true and no git on PATH, every git resource read fails at fetch time. Doctor now warns (git.missing in --json).
• Claude Code plugin with an mcp-bash skill: The repository is now a plugin marketplace. /plugin install mcp-bash --marketplace yaniv-golan/mcp-bash-framework installs a skill that walks an agent through creating, testing, wiring and bundling an mcp-bash server, and lists the traps that fail silently (deny-by-default tools, policy.sh, the tool environment, bash 3.2 under Claude Desktop, completion script names).

Security

• Resources embedded in tool results can no longer be redirected by a symlink swap: A tool's embedded resources (MCP_TOOL_RESOURCES_FILE, mcp_result_text_with_resource) were checked against the roots by path and then opened by name up to three times, for mime detection, the binary check and the content. Someone able to write inside a root could swap the file for a symlink after the check, and the tool result then carried the content of a file outside the roots. The file is now read once through the same verified read as file:// resources, with the matched root, and detection and encoding use the bytes of that read. A file that isn't a regular file inside the roots when it is opened is skipped with a warning.

Changed

• Unknown methods before initialize get -32601 Method not found: Newer clients, including Claude Code and Claude Desktop, probe with server/discover before initialize and fall back to initialize when it fails. The server answered every pre-initialize request it doesn't allow with -32000 Server not initialized, which some client versions handled badly. A method the server doesn't implement now gets -32601, and the server stays ready for initialize. Methods it does implement (for example tools/list) still get -32000 before initialize.

Fixed

• Vendored runtimes and MCPB bundles include the whole SDK: mcp-bash vendor and mcp-bash bundle copied only sdk/tool-sdk.sh, so ui-sdk.sh was missing and UI helpers such as mcp_result_with_ui did not exist in vendored and bundled projects. Every sdk/*.sh file is now embedded.
• Cancellations no longer stall request handling: Each notifications/cancelled sent TERM, then waited 1 second in the main loop before escalating to KILL. Cancels are handled one at a time, so N cancels delayed every other request, including ping, by N seconds. The escalation now runs in a background helper after the same grace period, and the server keeps answering at once.
• Workers no longer spin when the server exits while they wait for a lock: The lock root is inside the server's state directory, which cleanup removes on exit. A worker still waiting for a lock could then never create its lock directory and polled forever, starting a sleep every 20 ms. Lock waits now give up once the lock root is gone.
• Error results are no longer checked against outputSchema: A tool that declares an outputSchema and returns an error result (mcp_result_error, or any result with isError: true) got -32603 Tool output does not satisfy outputSchema instead of its own error, so the model never saw the reason. The schema describes successful structured results, and the MCP SDKs skip it for errors; error results are now returned as they are.
• A fatal shell error in the server exits non-zero on bash 3.2: Bash 3.2 reports status 0 to the EXIT trap after a fatal error such as an unbound variable, so the server exited 0 and hosts and CI saw success. Only the intended exits (end of input, shutdown/exit, idle timeout, orphan detection) now exit 0; any other zero status becomes 1.
• SIGHUP stops the server, and INT/TERM stop it at any point: The server's HUP trap, and its INT/TERM traps outside the read loop, ran cleanup without exiting, so the server kept running without its state directory. HUP, INT and TERM now exit with 129, 130 and 143 at any point after startup, and cleanup runs once. A signal while the server waits for running tools after stdin closes also cleans up.
• The elicitation and ffmpeg-studio examples stop where they should: The elicitation example (08) died under set -e when the client could not elicit; it now returns its own "Stopped" result. The ffmpeg-studio tools did not exit after an early error result, so transcode could continue to ffprobe and ffmpeg -y after an invalid preset or a declined overwrite, overwriting the file the user had refused to overwrite.
• Built-in UI templates unwrap the {success, result} envelope: The data-table, progress, diff-viewer, tree-view and kanban templates read the raw structured content, so a table fed by mcp_result_success rendered nothing. They now unwrap the envelope and still accept the old shape.
• mcp_result_with_ui and mcp_result_with_ui_data work for clients without MCP Apps support: They returned isError: "Invalid JSON passed to mcp_result_success" to every client without MCP Apps support; they now return the text fallback as a normal result. A UI result without data no longer sends structuredContent: null.
• mcp-bash run-tool finds tools added or changed since the last scan: A registry cache loaded from disk counted as fresh for the registry TTL from the moment it was loaded, so a one-shot run-tool never rescanned, and a tool added after the cache was written was reported as "tool not found" until mcp-bash registry refresh was run. run-tool now rescans when anything under the tools directory is newer than the cache, and reuses the cache otherwise. --no-refresh still uses the cache as written.
• Clawdbot recipe renamed to OpenClaw: Clawdbot is now OpenClaw and mcporter has moved to the openclaw organisation. The README recipe links to the new repositories and uses mcporter's current config shape (mcpServers, no type field); the config path ~/.mcporter/mcporter.json is unchanged.
• MCP Apps specification links work again: The links to the MCP Apps extension spec in docs/concepts/mcp-apps.md and docs/guides/ui-resources.md returned 404; they now point at https://modelcontextprotocol.io/extensions/apps/overview.
• mcp_args_get --default works: The tool scaffold writes mcp_args_get '.name' --default 'World', but mcp_args_get ignored the option, so every scaffolded tool returned the string null for a missing argument. --default VALUE is now used when the value is missing, null or an empty string (as mcp_args_int and mcp_args_bool do); false, 0, and the string "null" are kept. With --default, the helper also works in minimal mode. Tools copied from the scaffold are fixed without changes.
• The installer test no longer changes the developer's mcp-bash command: test/integration/test_installer.sh ran the installer with the real HOME, so each run pointed ~/.local/bin/mcp-bash at a test directory that was deleted afterwards. It now uses a temporary HOME.

Behaviour changes to check before upgrading

Details are in the entries below.

• Git provider (opt-in, MCPBASH_ENABLE_GIT_PROVIDER=true): hostnames need git 2.37 or later; older git refuses them, since it can't be pinned to the checked address (mcp-bash doctor warns). It no longer follows HTTP redirects. LFS-tracked files are returned as pointer files.
• URL ports: the HTTPS and git providers refuse ports with leading zeros (:080) or out of range.
• HTTPS and git providers: a host that doesn't resolve is no longer fetched, and both providers refuse every request if lib/policy.sh can't be loaded.
• Tool and provider environment: only framework-owned MCP_* variables are passed by default, and MCPBASH_REMOTE_TOKEN* is never passed to tools or providers outside inherit mode (and is removed from tools' _meta in every mode). Add other names to the allowlist if a tool or provider needs them.
• Resources: a declared mimeType is reported as declared again, so resources scaffolded with "mimeType": "text/plain" report text/plain.
• Completions: registered completions without timeoutSecs time out after 30 seconds (0 disables).
• initialize: a client asking for an unsupported protocol version now gets the latest supported version instead of an error; a non-string protocolVersion (e.g. false) now fails with -32602.
• Runtime directories: state and lock directories get random names; ${TMPDIR}/mcpbash.locks is no longer used. A symlinked MCPBASH_STATE_DIR, MCPBASH_LOCK_ROOT, or MCPBASH_LOG_DIR now stops startup.
• resources/unsubscribe: a request with neither uri nor subscriptionId now fails with "Resource uri required".

Changed

• initialize negotiates unsupported protocol versions instead of rejecting them: Per MCP 2025-11-25 (Lifecycle, Version Negotiation: "Otherwise, the server MUST respond with another protocol version it supports"), a request for an unsupported version, older or newer, now succeeds with the latest supported version (2025-11-25), and the server logs a note to stderr. Previously it returned -32602 Unsupported protocol version. A missing or null protocolVersion still negotiates the default. A non-string value (for example false or 42) returns -32602 with data: {supported, requested}; used to count as missing.

• Runtime state directories have random names: Per-process state directories, and the CI-mode default log directory, are created with mktemp -d (mode 0700), for example mcpbash.state...XXXXXX. The lock root is now inside the state directory, and the shared CLI lock directory ${TMPDIR}/mcpbash.locks is gone.

• A declared resource mimeType is the reported label again: resources/read reports a static resource's mimeType (from .meta.json, register.sh, or register.json) as written. Since 0.x's binary detection, file --mime overrode it, so a .md declared text/markdown was reported as text/plain. This restores the pre-detection labels.

  • Detection still decides whether content is sent as text or a base64 blob: a text/plain label on a PDF is still a blob, and a declared application/toml stays text.
  • Resources without mimeType are labelled by detection, as before.
  • Projects created with mcp-bash scaffold resource have "mimeType": "text/plain" in their .meta.json and will now report text/plain even if the file holds JSON, Markdown, HTML or binary content. Remove the field or set the right type; mcp-bash validate warns when a declared type clearly disagrees with the file. New scaffolds no longer write mimeType.
  • mcp_result_text_with_resource without --mime no longer guesses a type (it fell back to application/octet-stream); the server detects it. With --mime, the value is reported as given.
  • After upgrading, registry hashes change for resources that declare mimeType: clients see one notifications/resources/list_changed, and earlier resources/list cursors become invalid.

• Registered completions now time out by default: Completions registered in server.d/register.json or register.sh that don't set timeoutSecs had no limit, so a hung script held a worker. They now time out after MCPBASH_COMPLETION_REGISTERED_TIMEOUT_SECS (default 30; 0 restores no limit). An explicit timeoutSecs: 0 now means no timeout; it used to trip the watchdog after about a second. A negative or non-numeric timeoutSecs is rejected at registration with a warning and treated as unset; it used to fail the completion at run time.

Security

• HTTPS and git providers refuse non-canonical URL ports: A port like :000080 or :0 made the providers pin port 443 while curl or git connected to the real port, unpinned. A port must now be plain decimal 1-65535 without leading zeros (exit 4, host_blocked in mcp_download_safe). Spellings such as :080, which worked before, are now refused too.

• The git provider disables git-lfs downloads: A cloned repository's .lfsconfig could send git-lfs, which makes its own HTTP requests outside the provider's pinning, protocol and redirect controls, to any URL. LFS-tracked files are now returned as pointer files.

• file:// and ui:// reads can no longer be redirected by a symlink swap: The providers checked the path for symlinks before and after reading, but never checked the file they actually opened. Someone able to write inside an allowed resource root could swap the file, or a directory above it, for a symlink mid-read and read files outside the roots. Reads now go through lib/file_read.sh. It pins the checked directory, confirms by inode that the directory is inside the matched root, and opens the file once. No bytes are returned unless the open descriptor is the regular, non-symlink file that was checked. If the platform can't identify the descriptor (no usable stat or /dev/fd), the read is refused. Known limits: a hard link inside a root to an outside file is still served; on macOS the file is identified by inode and birth time, which the file's owner can set; and a file swapped for a FIFO can block a read. See docs/SECURITY.md.

• Static UI HTML is no longer served through a symlink pointing anywhere: The UI registry read static HTML with no symlink check, so an index.html symlink to any file was served. It now uses the same verified read, and MCPBASH_MAX_UI_RESOURCE_BYTES now applies to it.

• HTTPS and git providers check addresses more strictly and always pin the resolved address: These checks matter when an operator has widened the host allowlist (MCPBASH_HTTPS_ALLOW_ALL, MCPBASH_GIT_ALLOW_ALL, or broad allow lists).

  • IPv4 literals must be canonical dotted quads. Octal, hex, short and integer forms such as 0177.0.0.1, 0x7f.0.0.1, 127.1, 2130706433 previously reached loopback; they are now refused.
  • IPv6 literals are normalised before checking, so [0:0:0:0:0:0:0:1], [::], and full-form or hex v4-mapped loopback are blocked. NAT64, 6to4 and v4-compatible addresses are judged by their embedded IPv4 address. Teredo, documentation and other non-global IPv6 addresses are blocked.
  • More blocked IPv4 ranges: 0.0.0.0/8, 100.64.0.0/10 (includes the 100.100.100.200 metadata endpoint), 192.0.0.0/24, 198.18.0.0/15, 224.0.0.0/4, and 240.0.0.0/4 (includes 255.255.255.255). *.localhost names are blocked.
  • Resolution fails closed. A host that does not resolve is never fetched (exit 5), and every fetch is pinned to the checked addresses. On macOS the resolver now sees /etc/hosts and mDNS names (via dscacheutil); before, those names skipped both the private-range check and the pin.
  • The git provider pins too, via http.curloptResolve, and no longer follows redirects. This needs git 2.37 or later; older git is refused for hostnames.
  • One private-range list in lib/policy.sh, shared by both providers. If it can't be loaded, the providers refuse every request instead of falling back to their own, weaker copies.

• Runtime directories can no longer be pre-planted by another local user: State and lock directories used predictable names in the shared temp directory and were created with mkdir -p, which accepts a directory or symlink that already exists. They are now created with mktemp -d. Startup fails if MCPBASH_STATE_DIR, MCPBASH_LOCK_ROOT or MCPBASH_LOG_DIR is a symlink, and a MCPBASH_STATE_DIR that cannot be created is an error instead of being silently replaced. Cleanup never removes a symlink.

• Tools and providers no longer receive the remote-access secret: Outside inherit mode, MCPBASH_REMOTE_TOKEN* is removed from tool and provider environments, even when an allowlist names it. (A tool running as the same user can still read the server's own process environment; see docs/SECURITY.md.) The token's request _meta keys (MCPBASH_REMOTE_TOKEN_KEY, default mcpbash/remoteToken, and the fallback key) are deleted from the _meta passed to tools (MCP_TOOL_META_JSON / MCP_TOOL_META_FILE) in every mode. A _meta that is not a JSON object becomes {}. Behaviour change: a tool that read the token must get it another way.

• Only framework-owned MCP_* variables reach tools and providers by default: Previously every MCP_* variable passed, including user secrets such as MCP_REGISTRY_TOKEN (docs/MCPB.md tells users to export). Now only MCP_SDK, MCP_TOOL_*, MCP_ELICIT_*, MCP_PROGRESS_*, MCP_LOG_STREAM, MCP_CANCEL_FILE, MCP_ROOTS_*, MCP_RESOURCES_ROOTS, MCP_COMPLETION_*, MCP_PROMPT_*, MCP_RESOURCE_*, MCP_CONFIG_JSON, MCP_TRANSPORT and MCP_PATH_DEBUG pass. Behaviour change: a tool or provider that reads its own MCP_* variable must name it in MCPBASH_TOOL_ENV_ALLOWLIST / MCPBASH_PROVIDER_ENV_ALLOWLIST (allowlist mode); server.meta.json allowlists may now name such variables, while the framework families stay reserved.

Added

• Per-resource completion scripts work for resource templates: A completion/complete with ref/resource was matched only against static resources by exact URI, so a template's completion script was never run and the server returned values built from the URI string. Claude Desktop sends ref/resource only for template arguments, so per-resource completions did nothing there. The URI is now also matched against the templates (exactly by uriTemplate, or as a concrete URI), and the script is found by template name: resources/.completion.sh or resources//.completion.sh. MCP_RESOURCE_URI is the uriTemplate, and MCP_COMPLETION_ARGS_JSON .argument.name names the variable being completed.

• mcp-bash doctor warns when the git provider can't pin: With MCPBASH_ENABLE_GIT_PROVIDER=true and git older than 2.37, doctor warns (git.version_unpinnable in --json) that fetches by hostname will be refused.

• resources/read matches resource templates: When no resource has the requested name or exact URI, the URI is matched against the registered resource templates.

  • Syntax: a subset of RFC 6570: {v} (stops at /, ?, #), {+v} and {#v}. Templates using other operators, comma lists, modifiers, adjacent or repeated expressions keep their previous read behaviour.
  • Ties: the template with the most literal characters wins, then the fewest expressions, then the template name.
  • What a match supplies: the template's mimeType is reported as a declared label, and the provider receives MCP_RESOURCE_TEMPLATE_NAME and MCP_RESOURCE_TEMPLATE_VARS (compact JSON of the raw, not percent-decoded, values). Both variables are cleared at startup, so a host-set value never reaches other reads, tools or completion providers.
  • Unchanged: matching never changes which provider runs, and the resources/templates/list shape is unchanged.

• mcp-bash run-tool --print-env shows the env policy: It now prints the effective tool and provider env policy (mode and source per scope, allowlisted names and whether each is set) and never values. It covers the launch environment plus server.meta.json only, not --with-server-env / --source files or server.d/policy.sh, and says so.

• Bundles log cleared placeholders at debug level: With MCPBASH_LOG_LEVEL=debug, a bundle's run-server.sh writes the names (never values) of variables it unset because they still held an unexpanded ${user_config.*} placeholder. Logs at warn level when hint provided.

Fixed

• On bash 3.2, a disconnected client no longer leaves the server spinning: When the host ignores SIGPIPE (as GUI hosts do) and the client goes away, the failed response write left its bytes in bash 3.2's output buffer. They leaked into later command output, and the server looped at full CPU instead of exiting.
• mcp-bash run-tool --source FILE fails when FILE has a syntax error: On bash 3.2 it reported success. Files are now syntax-checked before they are sourced.
• Scaffolded completions, the scaffolded test/run.sh and the example completions no longer use the "${x:-{}}" default: It appends a stray }, so scaffolded run_test name '{...}' calls were rejected by run-tool.
• The policy.sh default-check warning isn't fooled by comments: validate and doctor counted a mention of mcp_tools_policy_check_default in a comment as a call.
• A malformed notifications/cancelled no longer ends the server: A cancel with a missing, null or false requestId, or with non-object params, made the server exit; in minimal mode every cancel did. It is now ignored, like any notification the server can't use.
• Closing stdin after a cancellation no longer cuts the shutdown short on bash 4+: The server exited with status 143, dropped results still in flight and left workers running. It now delivers them and exits 0.
• mcp_json_quote_text "" works on bash 3.2 under set -u: It aborted with "unbound variable", so mcp-bash doctor --json printed invalid JSON on macOS /bin/bash.
• An unsubscribe sent right after a subscribe for the same URI ends the subscription: Requests run in parallel, so the unsubscribe could finish first, find nothing, and leave the subscription live.
• notifications/cancelled cancels requests with string ids: Only numeric ids were matched, so a cancelled call with a string id still returned its result.
• resources/unsubscribe accepts the spec's uri param: It removes every subscription to that URI. subscriptionId is still accepted. Unsubscribing something that isn't subscribed returns {} ; a request with neither field returns -32602 ("Resource uri required"; previously "subscriptionId required").
• Subscription polling starts with the first resources/subscribe: It used to start only with the next client message, so a client that subscribed and then waited got no updates.
• A newline in a subscribe name or uri can no longer redirect the subscription to another resource: Subscription records are stored as JSON.
• The subscription poller survives an unsubscribe that arrives mid-poll: Bash 5 stopped polling; bash 3.2 recreated the removed subscription and sent an update with an empty URI.
• Interactive UI templates call tools correctly: The form, tree-view, kanban, and progress-cancel templates called app.callTool(), which the MCP Apps SDK does not have. They now use app.callServerTool({ name, arguments }) and treat isError results as failures, and the SDK is pinned to @modelcontextprotocol/[email protected] instead of a floating version. Whether a host lets a UI call tools is still up to the host; the docs no longer blame a host bug for this.
• ping is answered before initialize: The MCP lifecycle allows ping before initialization completes; it was rejected with -32000 and now returns {}.
• Docs: the README security table no longer says every server.d/*.sh file is disabled by default (only register.sh is; policy.sh is always sourced); run-tool examples include --allow-self, and the flag list is complete; mcp-bash --help lists run-tool --with-server-env/--source, validate --inspector, config --wrapper-env and the main doctor flags; docs/ENV_REFERENCE.md documents MCPBASH_HOME, MCPBASH_ROOTS, the registry TTLs, the trace variables, MCPBASH_LOG_DIR, MCPBASH_KEEP_LOGS, MCPBASH_CI_VERBOSE, and MCPBASH_MAX_UI_RESOURCE_BYTES; the vendoring guide links to the README's verified-install steps instead of a stale example.

Added

• Declarative env policy in server.d/server.meta.json: An optional "env" object can set MCPBASH_TOOL_ENV_MODE, MCPBASH_TOOL_ENV_ALLOWLIST, MCPBASH_PROVIDER_ENV_MODE, and MCPBASH_PROVIDER_ENV_ALLOWLIST, so a project (including an installed MCPB bundle) can pass host-injected secrets such as an API key on to its tools and providers. The server applies it at startup, and mcp-bash run-tool applies it too, after any --with-server-env / --source files, which count as launch env.

  • Only those four keys are accepted. Operator opt-ins (*_INHERIT_ALLOW, MCPBASH_ALLOW_PROJECT_HOOKS, ...) and any other variable are refused with a warning that names the key, never the value.
  • Values are validated before use: modes must be valid for their key, allowlists may only name plain variables (no shell-control or reserved names such as LD_PRELOAD, BASH_ENV, or MCPBASH_*), and values with control characters are refused. A server.meta.json holding more than one JSON document applies nothing. Warnings go to stderr.
  • The launch environment wins. If it sets either the mode or the allowlist for tools (or for providers), both meta values for that scope are ignored. An empty value, or an unexpanded ${user_config.*} placeholder, counts as unset.
  • MCPBASH_IGNORE_META_ENV=true ignores the section entirely.
  • inherit still requires the operator's *_INHERIT_ALLOW.
  • mcp-bash validate reports problems in the section, and mcp-bash bundle refuses a bundle whose section contains a disallowed key, because its value would ship.

• mcp-bash doctor shows the tool and provider env policy: For tools and providers it shows the effective mode and where it came from (launch env, server.meta.json or default), and whether each allowlisted variable is set, empty, an unexpanded placeholder or not set in the current shell. It also flags refused or invalid server.meta.json env keys, invalid allowlist names, and inherit without the operator opt-in. Values are never printed. doctor --json adds an envPolicy object and matching findings.

Fixed

• Refused register.json / register.sh now say why and how to fix it: When the file, server.d/ or the project root is group- or world-writable, a symlink, or owned by another user, the registry is refused and every tools/resources/prompts list fails. The error said only "permissions/ownership invalid". It now names the path (relative to the project, since the message can reach clients) and the fix, for example server.d is group- or world-writable (fix: chmod g-w,o-w server.d).

• Non-ASCII file URIs are encoded correctly on bash 3.2: mcp_uri_url_encode printed bytes >= 0x80 as sign-extended values under bash 3.2 (the macOS /bin/bash), so é became %FFFFFFFFFFFFFFC3%FFFFFFFFFFFFFFA9 instead of %C3%A9. Resources without an explicit uri whose path contains non-ASCII characters got broken file:// URIs.

• Per-prompt and per-resource completion scripts now time out: Scripts found next to a prompt or resource (for example prompts//.completion.sh) had no timeout, so a hung script held a worker on every keystroke. They now time out after MCPBASH_COMPLETION_TIMEOUT_SECS (default 5 seconds). These scripts are now covered by an integration test, and their file lookup and environment are documented in docs/COMPLETION.md.

• Tools on Windows keep the system variables they need: In minimal and allowlist tool env modes, tools received only PATH, HOME, TMPDIR, and LANG (plus MCP_*/MCPBASH_*), while providers also kept the Windows system variables. Without SYSTEMROOT, Python on Windows cannot open sockets (WinError 10106). Tools now also keep SYSTEMROOT, SYSTEMDRIVE, WINDIR, COMSPEC, PATHEXT, USERPROFILE, APPDATA, LOCALAPPDATA, TEMP, TMP, MSYSTEM and MSYS2_ARG_CONV_EXCL.

• Bundles keep their base env on platforms with an override: Claude Desktop replaces mcp_config.env with a platform_overrides..env rather than merging, so an override dropped MCPBASH_PROJECT_ROOT, MCPBASH_TOOL_ALLOWLIST, and every user_config variable on that platform. The bundler now copies the base env into each override env, and docs/MCPB.md no longer says the env is merged.

• mcp-bash bundle also warns when override env turns on an operator opt-in such as MCPBASH_TOOL_ENV_INHERIT_ALLOW.

• Bundles no longer pass unexpanded ${user_config.*} placeholders to tools: Claude Desktop leaves the literal placeholder text when an optional setting has no value and no default. run-server.sh now unsets such variables. On Windows, where the host passes TEMP but not TMP, it also sets TMP from TEMP.

• The tool inherit-mode gate now also applies to a mode set by server.d/policy.sh: MCPBASH_TOOL_ENV_MODE=inherit requires MCPBASH_TOOL_ENV_INHERIT_ALLOW=true, but the check ran before policy.sh was sourced, so a mode exported there skipped it. The check now runs after the policy hook. policy.sh is project code and can still set anything, so this guards against accidental configuration, not a hostile project.

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}/.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.
• Resource providers now receive MCPBASH_JSON_TOOL_BIN and MCPBASH_JSON_TOOL: Previously only the ui provider got them, so provider scripts using ${MCPBASH_JSON_TOOL_BIN:-jq} ran with them unset. Completion providers already received both.

Changed

• Docs no longer claim server.d/env.sh runs at server startup: docs/PROJECT-STRUCTURE.md, docs/ARCHITECTURE.md, and the configuration hierarchy in docs/BEST-PRACTICES.md described it as applied at startup. The server has never sourced it, and neither does an MCPB bundle's run-server.sh; only mcp-bash run-tool --with-server-env does. The docs now say so and point to where a running server's environment should be set.

Security

• resources/read and resources/subscribe reject a name and uri that refer to different resources: The name parameter (an mcp-bash extension; MCP addresses reads by uri) selected the provider, while the client's uri was passed to it unchecked. Any client could therefore send an arbitrary URI to any registered resource's provider. Such requests now fail with -32602. Requests with only name, only uri, or a matching pair are unaffected.
• Provider scripts must validate their URI argument: A provider receives any URI in its declared scheme, not only the URIs the project lists. Check $1 and exit 3 or 4 for URIs the provider does not serve. See docs/SECURITY.md.

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//.meta.json (created by mcp-bash scaffold prompt) in addition to the flat and prompt.meta.json nested layouts.

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

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

• 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

• Built-in resource providers now embedded in bundles and vendor trees: Both lib/resources.sh and sdk/tool-sdk.sh resolve built-in providers (file://, https://, git://, echo://, ui://) via ${MCPBASH_HOME}/providers/. Previously, mcp-bash bundle did not copy the framework's providers/ directory into .mcp-bash/, so any server using built-in resource providers would silently fail in bundled deployments unless the project overrode every provider. The providers/*.sh files are now always included in the embedded framework tree.

Changed

• Shared embed logic extracted to lib/cli/embed.sh: The framework embedding logic previously duplicated between bundle and the new vendor command is now in a single shared module (EMBED_REQUIRED_LIBS, mcp_embed_framework(), mcp_embed_compute_hash()). bundle.sh delegates to it unchanged.

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.

• platform_overrides passthrough in MCPB manifest: When server.meta.json defines platform_overrides, the bundler merges it into server.mcp_config.platform_overrides in the manifest. Enables per-platform command, args, and env overrides for cross-platform bundles (e.g., .exe suffix on Windows, DYLD_LIBRARY_PATH on macOS).

• _meta passthrough in MCPB manifest: When server.meta.json defines _meta, the bundler passes it through as a top-level manifest field. Supports platform-specific client integration metadata (e.g., Windows Store package_family_name, static initialize/tools/list responses).

• localization passthrough in MCPB manifest: When server.meta.json defines localization (with resources path template and default_locale), the bundler passes it through for i18n of user-facing fields.

Fixed

• Registry cache epoch-boundary race: load_cache_if_empty in tools, resources, resource templates, and prompts called date +%s independently of the caller's now timestamp. When the epoch second rolled over between the two calls, LAST_SCAN could exceed now, producing a negative cache age that satisfied any TTL check — skipping the disk scan entirely. Each function now accepts the caller's now to ensure LAST_SCAN <= now.

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.

• set -e + CLI wrapper pitfall documented in docs/BEST-PRACTICES.md §4.5: Documents that set -euo pipefail makes error branches unreachable when wrapping CLIs that return non-zero for business errors, with a fix example.