MCP Bash Framework Updates & Release Notes

Changed

• CI/CD improvements: Bundle validation is now part of release gates via new bundle-sanity job that validates mcp-bash bundle --help and mcp-bash bundle --validate on every push. Prevents broken bundle functionality from reaching releases when non-bundle-path changes break bundle code. Full bundle creation tests remain in separate bundle.yml workflow for thorough path-triggered testing.
• Consistent Windows CI policy: bundle.yml now uses continue-on-error for Windows matrix jobs, matching the main CI workflow policy. Windows failures are reported but don't block the workflow.
• CI workflow cleanup: Removed unreachable Windows-specific code from Ubuntu-only jobs (lint, unit, stress). These jobs never run on Windows, so the conditional Windows path setup was dead code.

Fixed

• Bundle corrupted resources.json for parameterized resources: mcp_resources_scan() now correctly skips resources with uriTemplate field. Previously, resources defining a uriTemplate (for parameterized access like file:///{path}) would get incorrectly added to resources.json with a fabricated file:// URI based on the meta.json path, corrupting the registry. These resources now only appear in resource-templates.json as intended per MCP spec.

Added

• mcp_require helper: New function for conditional library sourcing with duplicate-load prevention. Simplifies optional dependency loading in tools and SDK code. See lib/require.sh.

Changed

• Release workflow: Release job now runs as part of CI workflow with needs: dependency on core test jobs. Releases are created after lint, unit, integration (Ubuntu + macOS), and compatibility tests pass. Windows integration tests run in parallel but do not block releases (failures are reported as warnings with artifacts). Previously, all three OS integration tests were required, causing Windows slowness to delay releases.
• Internal refactoring: Consolidated error response formatting in handlers and standardized error variable naming to _ERROR_CODE/_ERROR_MESSAGE for consistency across the codebase.

Fixed

• Malformed JSON in notifications/message: Fixed edge case where mcp_logging_emit() could emit malformed JSON ("logger":,"data":}) when the internal quote function failed silently. Added defensive validation to ensure quoted strings are never empty.
• Validator missing uriTemplate support: mcp-bash validate now accepts uriTemplate as a valid alternative to uri for resource templates, per MCP spec. Previously, resources with only uriTemplate (no uri) failed validation with "missing required uri". The validator now:
  • Accepts either uri OR uriTemplate (not both required) …

Added

• Static registry mode (MCPBASH_STATIC_REGISTRY=1): Opt-in mode for bundle deployments that skips runtime discovery and uses pre-generated .registry/*.json cache files directly. Reduces cold start time by skipping TTL checks, fastpath detection, and directory scanning. When enabled:
  • Loads pre-generated cache immediately without freshness checks
  • Skips register.sh execution (shell code) but still honors register.json (data-only declarative overrides)
  • Falls back to normal discovery if cache is missing/invalid
  • Respects CLI forced refresh (mcp-bash registry refresh still works)
  • Logs info message on first request to alert developers if static mode is accidentally left enabled
  • Cache format versioning (format_version: 1) for future compatibility
• MCPB_STATIC bundle config: Bundles now use static registry mode by default for zero-config fast cold start. The bundler automatically:
  • Runs registry refresh to pre-generate .registry/*.json files
  • Adds .registry to MCPB_INCLUDE if not present
  • Sets MCPBASH_STATIC_REGISTRY=1 in bundle manifest environment
  • To opt out, set MCPB_STATIC=false in mcpb.conf (accepts false, 0, no, off) …

Added

• CallToolResult response helpers: New SDK functions for building MCP CallToolResult responses with consistent {success, result} envelope patterns:
  • mcp_result_success - Emit success CallToolResult with structuredContent.success=true and isError=false
  • mcp_result_error - Emit error CallToolResult with structuredContent.success=false and isError=true
  • mcp_json_truncate - Binary-search truncation for large JSON arrays with metadata (truncated, kept, total)
  • mcp_is_valid_json - Validate single JSON value (handles false/null correctly via slurp mode)
  • mcp_byte_length - UTF-8 safe byte length measurement
• Documentation: Added BEST-PRACTICES.md §4.7 "Building CallToolResult responses" with examples and comparison table. Added "Capturing stdout and stderr separately" pattern to §4.3 for CLI wrapper tools.
• Tests: Unit tests (test/unit/sdk_result_helpers.bats) and integration tests (test/integration/test_result_helpers.sh) for all new helpers.

Changed

• Test framework modernization: Unit tests now use proper bats-core syntax with @test functions (219 tests across 40 files). Migrated from custom test runner to direct bats invocation with parallel execution support (--jobs N when GNU parallel available). Bats helper libraries (bats-support, bats-assert, bats-file) installed via npm instead of vendored. CI now outputs JUnit XML for test result visualization. …

Added

• Installer now uses exit code 3 for policy refusal (user declined prompt or MCPBASH_HOME is set), allowing CI/CD scripts to distinguish "user/policy declined" from actual failures (exit 1).
• Installer help text now documents exit codes (0=success, 1=error, 2=invalid args, 3=policy refusal).
• README now includes installer exit codes table and CI/CD installation patterns (tarball+SHA256 and git+SHA verification).

Fixed

• Installer color escape codes now render correctly (use $'\033[...]' syntax instead of single-quoted literals).
• Installer now prompts interactively via /dev/tty when run via curl | bash, instead of auto-confirming overwrites.
• Installer messaging clarifies when auto-confirm is due to --yes flag vs no TTY available.
• Installer verification error messages now include filename, expected/actual SHA values, and guidance on possible causes (corrupted download, MITM attack, version mismatch).

Added

• MCPB bundle support: mcp-bash bundle creates distributable .mcpb packages for one-click installation in MCPB-compatible clients (e.g., Claude Desktop). Bundles include the embedded framework, tools, resources, prompts, and a generated manifest following MCPB specification v0.3.
• mcp_with_retry SDK helper: Retry commands with exponential backoff + jitter for transient failures. Exit codes 0-2 are not retried (permanent); 3+ trigger retry. Example: mcp_with_retry 3 1.0 -- curl -sf "$url".
• Health checks hook: Optional server.d/health-checks.sh verifies external dependencies (CLIs, env vars) before serving. Helpers mcp_health_check_command and mcp_health_check_env report results to mcp-bash health output as projectChecks: ok|failed.
• Optional mcpb.conf configuration file for customizing bundle metadata (name, version, author, repository). Values fall back to server.d/server.meta.json, VERSION file, and git config.
• Automatic icon inclusion: icon.png or icon.svg in project root is bundled for client UI display.
• Platform-specific builds: mcp-bash bundle --platform darwin|linux|win32|all creates bundles targeting specific platforms.
• gojq bundling: mcp-bash bundle --include-gojq embeds gojq binary for systems without jq installed.
• Registry publishing: mcp-bash publish command submits bundles to the MCP Registry with validation, dry-run support, and API token authentication. …

Added

• Project-level resource providers: Projects can now define custom resource providers in ${MCPBASH_PROJECT_ROOT}/providers/. Project providers are checked before framework providers, enabling custom URI schemes (e.g., xaffinity://, myapi://) without modifying the framework installation. See docs/REGISTRY.md for details.
• New environment variable MCPBASH_PROVIDERS_DIR for overriding the providers directory location.

Fixed

• Shell profile sourcing now loads all relevant profiles (.zprofile, .zshrc, .bash_profile, .profile, .bashrc) instead of only the first one found. Ensures version managers like pyenv, nvm, and rbenv are properly available when MCP servers are launched from GUI applications like Claude Desktop.
• config --wrapper and --wrapper-env now work on macOS system bash (3.2) by avoiding heredocs inside command substitutions.

Added

• mcp-bash validate now validates icons format per MCP spec: icons must be objects with src property, not plain strings. Catches the common "expected object, received string" error that causes strict MCP clients (Cursor, Claude Desktop, MCP Inspector) to reject servers.
• mcp-bash validate --inspector flag prints the command to run MCP Inspector CLI for strict schema validation.

Documentation

• Added "Common Schema Errors" section to DEBUGGING.md documenting icons format errors and strict client validation failures.
• Added troubleshooting flowchart to DEBUGGING.md for diagnosing "works from CLI but fails in clients" issues.

Added

• mcp-bash doctor: added --dry-run (propose actions) and --fix (managed-install-only repairs), plus --min-version/--archive/--verify/--ref upgrade inputs, a concurrency lock, and JSON contract fields schemaVersion, exitCode, findings, proposedActions, and actionsTaken.
• Installer now writes INSTALLER.json into managed installs so doctor --fix can reliably distinguish managed vs user-managed installs.

Fixed

• Windows/Git Bash: registry builds no longer pass large item payloads via --argjson, avoiding E2BIG/Argument list too long failures when icons are inlined.

Documentation

• Clarified resource template discoverability: templates are listed via resources/templates/list and are not advertised via a dedicated capabilities flag; clients should probe the method (treat -32601 as unsupported).

Added

Changed

• Tool environment isolation no longer spawns external env; uses bash built-ins (compgen -e, unset) to avoid E2BIG/Argument list too long failures on Windows/Git Bash with large environments.
• BREAKING: Completion/resource providers now run under a curated environment by default (MCPBASH_PROVIDER_ENV_MODE=isolate) to reduce E2BIG risk; opt into inheritance with MCPBASH_PROVIDER_ENV_MODE=inherit + MCPBASH_PROVIDER_ENV_INHERIT_ALLOW=true or selectively pass variables via MCPBASH_PROVIDER_ENV_MODE=allowlist.
• BREAKING: completion/complete requests are now spec-shape only (MCP 2025-11-25: params.ref + params.argument). The legacy params.name/params.arguments shape is no longer accepted.
• BREAKING: Prompt templating only substitutes {{var}} placeholders from prompts/get arguments; other placeholder syntaxes are treated as literal text.
• CI: Windows integration runs default to non-verbose output and use a PR allowlist to reduce runtime; scheduled runs keep the full suite with per-test timeouts and better log preservation on cancellation.
• When MCPBASH_PRESERVE_STATE=true, per-request worker stderr logs (stderr.*.log) are preserved for debugging.
• Dev: Unit test runner supports filtering and enforces per-test timeouts (MCPBASH_UNIT_TEST_TIMEOUT_SECONDS) to avoid hangs and orphaned subprocesses.

Fixed …

Documentation

• Clarified Windows support: Git Bash is CI-tested; WSL works like Linux but is not separately validated in CI.
• README MCP spec coverage table now marks Resources as fully supported (templates/binary included).
• Fixed docs/ERRORS.md examples to reflect that result.isError=true is derived from a non-zero tool exit.
• Added docs/INSPECTOR.md with MCP Inspector recipes and strict-client schema/shape pitfalls.
• Clarified completion script argument parsing: MCP_COMPLETION_ARGS_JSON is params.arguments (use .query / .prefix).

Added

• Declarative project registration via server.d/register.json (data-only alternative to server.d/register.sh) with strict validation, safe-permissions checks, and per-kind override semantics.
• mcp-bash run-tool now supports per-invocation allowlisting via --allow-self, --allow <tool>, and --allow-all.
• Installer verification flag --verify to validate downloaded archives against published SHA256 checksums; pairs with release-published tarball and SHA256SUMS.
• Installer --archive flag to install from a local tar.gz (or URL) after verifying it externally (or via --verify).
• GitHub Actions release workflow (tag-triggered) builds a tarball and publishes SHA256SUMS for installer verification.
• Release prep automation: scripts/bump-version.sh, scripts/render-readme.sh, and a Prepare Release workflow to open a PR that bumps VERSION and re-renders README.md. …

Added

• Documentation discoverability improvements: README now links feature guides (elicitation, roots, registry, limits, errors, best practices, completions) and a new docs/COMPLETION.md covers completion providers, pagination, and script contracts.
• New example examples/10-completions demonstrating manual completion registration, query filtering, and hasMore/cursor pagination; included in the examples ladder.
• Comprehensive MCP Feature Support Matrix in SPEC-COMPLIANCE.md tracking all MCP features across protocol versions (2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25) with mcpbash version support status. Table includes 60+ features with implementation status, notes, and version history.
• Request metadata (_meta) support for tools/call: clients can now pass arbitrary metadata via params._meta which is exposed to tools as MCP_TOOL_META_JSON (or MCP_TOOL_META_FILE for large payloads). SDK helpers mcp_meta_raw and mcp_meta_get provide easy access. Use cases: pass auth context, rate limiting IDs, or behavior flags not generated by the LLM.
• Tools can now return embedded resources in results: write paths (optional mime/uri) to MCP_TOOL_RESOURCES_FILE and the framework will emit type:"resource" entries, including binary-safe handling.
• Resource reads detect binary MIME and emit base64 blob payloads instead of raw text to prevent malformed JSON on binary files. …

Added

• Protocol version 2025-11-25 support for compatibility with MCP Inspector v0.17+ and latest MCP SDK.
• Icons support for tools, resources, and prompts (SEP-973): add an icons array to any .meta.json file to provide visual identifiers in compatible clients. Icons are passed through in tools/list, resources/list, and prompts/list responses. Local file paths (e.g., "./icon.svg") are automatically converted to data URIs for stdio transport compatibility.
• Documentation on Protocol Errors vs Tool Execution Errors (SEP-1303): ERRORS.md and BEST-PRACTICES.md now explain when to use each error type to enable LLM self-correction. Examples updated to demonstrate best practices.
• Elicitation SDK helpers for SEP-1330 enum improvements: mcp_elicit_titled_choice (choices with display labels) and mcp_elicit_multi_choice / mcp_elicit_titled_multi_choice (multi-select checkboxes). The 08-elicitation example demonstrates all patterns.
• SEP-1036 URL mode elicitation support: mcp_elicit_url helper for secure out-of-band interactions (OAuth, payments, sensitive data). The framework now detects client form/url mode capabilities and includes mode in elicitation requests.
• mcp-bash config --inspector prints a ready-to-run MCP Inspector command (stdio transport) with MCPBASH_PROJECT_ROOT pre-populated for the current project. …

Added

• SDK helper mcp_require_path for consistent path normalization, optional single-root defaulting, and roots enforcement in tools.
• SDK type coercion helpers (mcp_args_bool, mcp_args_int, mcp_args_require) for common argument parsing patterns.
• Shared path normalization helpers (lib/path.sh) with consistent fallback chain (realpath -m → realpath → readlink -f → manual collapse) used by SDK/runtime/installer; added unit coverage.
• CLI run-tool command for direct tool invocation with optional roots, dry-run, timeout override, and verbose stderr streaming.
• Installer supports --version/--ref aliases for tagged installs and auto-prefixes bare semver tags with v.
• CLI run-tool --print-env to inspect wiring without executing tools; help/examples updated.
• mcp-bash validate now supports --json, --explain-defaults, and --strict; tool naming validation warns on missing namespace/format/length; outputs include defaults in JSON.
• mcp-bash config gains richer --json output, pasteable JSON for --client, and --wrapper generator for auto-install scripts.
• mcp-bash registry status subcommand to inspect registry cache (hash/mtime/counts) without refresh.
• mcp-bash doctor --json for machine-readable environment/project readiness (absorbs readiness summary). …

Added

• CLI project tooling for standalone servers:
  • mcp-bash init [--name NAME] [--no-hello] initializes a project in the current directory with server.d/server.meta.json, a tools/ directory, a .gitignore, and a working hello tool by default.
  • mcp-bash scaffold server <name> creates a new project directory with the same structure and example tool, wired to the existing scaffold templates.
  • mcp-bash validate [--project-root DIR] [--fix] validates server metadata and all tools/prompts/resources (JSON shape, required fields, script presence, executability, basic schema checks) and can auto-fix missing executable bits.
  • mcp-bash config [--project-root DIR] [--show|--json|--client NAME] emits ready-to-paste MCP client configuration snippets (Claude Desktop/CLI, Cursor, Windsurf, LibreChat) and a machine-readable JSON descriptor including MCPBASH_PROJECT_ROOT.
  • mcp-bash doctor performs environment diagnostics (framework location/version, PATH wiring, jq/gojq availability, basic project metadata, shellcheck/npx presence).
• One-line installer script install.sh:
  • Clones the framework into a safe, dedicated install directory, configures shell PATH for common shells, verifies mcp-bash --version, and warns when jq/gojq is missing.
  • Supports --dir, --branch, and --yes flags for CI and advanced setups.
• New SDK JSON helpers in sdk/tool-sdk.sh:
  • mcp_json_escape for quoting strings as JSON string literals. …

Changed

• Hardened HTTPS provider: blocks private/loopback hosts, optional host allow/deny via MCPBASH_HTTPS_ALLOW_HOSTS / MCPBASH_HTTPS_DENY_HOSTS, disables redirects/protocol downgrades, and caps timeouts/size (timeout ≤60s, max bytes ≤20MB).
• Hardened git provider: disabled by default (MCPBASH_ENABLE_GIT_PROVIDER=true to enable), host allow/deny lists added, private/loopback blocked, shallow clones enforced, timeout bounded (default 30s, max 60s), and repository size capped via MCPBASH_GIT_MAX_KB (default 50MB, max 1GB).
• Introduced shared host policy helper (lib/policy.sh) for consistent allow/deny handling across providers.
• Tightened state/lock/registry permissions with umask 077; debug mode now uses a randomized 0700 directory.
• File provider now rejects symlinks and rechecks before read to reduce TOCTOU/symlink escape risk.
• Scaffold commands validate names to prevent path traversal.
• Added llms.txt and llms-full.txt for LLM-specific repository guidance and compressed, agent-optimized reference content.