mcp-bash

# mcp-bash > mcp-bash is a pure Bash implementation of the Model Context Protocol (MCP) that lets you expose shell scripts and binaries directly to AI systems with zero ceremony. No runtimes, no dependency chains—just Bash ≥3.2 and a JSON processor (jq/gojq). Key points: - **Framework/project separation**: Install the framework once (e.g., via `install.sh`), create unlimited MCP server projects. Your tools stay yours; upgrades are clean. - **Stdio transport only**: Standard input/output communication. No daemons, no HTTP servers, no hidden state. - **Auto-discovery & auto-detection**: Tools/resources/prompts are discovered from project directories; project root is auto-detected when you run `mcp-bash` inside a project (for MCP clients, set `MCPBASH_PROJECT_ROOT` explicitly). Manual registry hooks run only when `MCPBASH_ALLOW_PROJECT_HOOKS=true` and have safe ownership/permissions. - **Built-in DX commands**: `mcp-bash new`, `mcp-bash init`, `mcp-bash scaffold tool|prompt|resource`, `mcp-bash validate [--json|--strict|--explain-defaults]`, `mcp-bash config [--json|--client|--wrapper]` (`--show` prints labeled snippets per client; use `--client` to filter), `mcp-bash doctor [--json]`, `mcp-bash registry status`, `mcp-bash run-tool [--print-env]`. - **Tool policy**: Default deny unless `MCPBASH_TOOL_ALLOWLIST` is set (use `*` only in trusted projects). Optional `server.d/policy.sh` defines `mcp_tools_policy_check()` for centralized allow/deny. - **Tool annotations**: Declare behavior hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) in `.meta.json` to help clients present appropriate UI cues. - **Protocol version**: Targets MCP `2025-11-25` with negotiated downgrades to `2025-06-18`, `2025-03-26`, and `2024-11-05`. - **Cross-platform**: macOS, Linux, and Windows (Git Bash CI-tested; WSL works like Linux). - **CLI `run-tool`**: Direct tool invocation with roots, dry-run, timeout override, verbose stderr, `--print-env`; covered by unit and example smoke tests. - **Scaffolded smoke scripts**: Each scaffolded tool ships with `tools/<name>/smoke.sh` to validate stdout JSON quickly; update the sample args in the script if you change `tool.meta.json`. - **Test harnesses**: `test_run_mcp` (NDJSON batch, preferred) and `test/common/session.sh` (interactive sequential calls; skips notifications, overwrites EXIT traps, no timeout). - **Embedded resources**: Use `mcp_result_text_with_resource '{"msg":"done"}' --path /tmp/file.txt --mime text/plain` to add `type:"resource"` content; binary files auto-encode to `blob`, text uses `text`. ## Docs - [README](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/README.md): Quick start (verified-download install path), client recipes (Claude Desktop, Cursor, Windsurf, etc.), configuration reference, and feature overview. - [Architecture Guide](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/ARCHITECTURE.md): Internal architecture, lifecycle loop, worker model, and handler implementation details. - [Project Structure Guide](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/PROJECT-STRUCTURE.md): Layouts, Docker deployment, multi-environment setups, and path resolution. - [Protocol Compliance](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/SPEC-COMPLIANCE.md): Detailed MCP protocol support breakdown and capability coverage matrix. - [Best Practices Guide](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/BEST-PRACTICES.md): Development, testing, operations, and contribution guidance. - [Testing Guide](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/TESTING.md): Lint, unit, integration, and stress test commands. ## Examples - [00-hello-tool](https://github.com/yaniv-golan/mcp-bash-framework/tree/main/examples/00-hello-tool): Basic "Hello World" tool structure and metadata. - [01-args-and-validation](https://github.com/yaniv-golan/mcp-bash-framework/tree/main/examples/01-args-and-validation): Handling JSON arguments and input validation. - [02-logging-and-levels](https://github.com/yaniv-golan/mcp-bash-framework/tree/main/examples/02-logging-and-levels): Sending logs to the client and managing verbosity. - [03-progress-and-cancellation](https://github.com/yaniv-golan/mcp-bash-framework/tree/main/examples/03-progress-and-cancellation): Long-running tasks, reporting progress, and handling user cancellation. - [04-roots-basics](https://github.com/yaniv-golan/mcp-bash-framework/tree/main/examples/04-roots-basics): MCP roots scoping for tools; allows/denies file reads based on configured roots. - [05-resources-basics](https://github.com/yaniv-golan/mcp-bash-framework/tree/main/examples/05-resources-basics): Listing and reading resources via the built-in file provider. - [06-embedded-resources](https://github.com/yaniv-golan/mcp-bash-framework/tree/main/examples/06-embedded-resources): Tool output that embeds files (`type:"resource"`). - [07-prompts-basics](https://github.com/yaniv-golan/mcp-bash-framework/tree/main/examples/07-prompts-basics): Discovering and rendering prompt templates. - [08-elicitation](https://github.com/yaniv-golan/mcp-bash-framework/tree/main/examples/08-elicitation): Client-driven elicitation prompts that gate tool execution. - [09-registry-overrides](https://github.com/yaniv-golan/mcp-bash-framework/tree/main/examples/09-registry-overrides): Declarative registry overrides, live progress streaming, and custom resource providers. ## SDK & Scaffolding - [Tool SDK](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/sdk/tool-sdk.sh): Shared helpers for argument parsing (`mcp_args_get`), output (`mcp_emit_json`, `mcp_emit_text`), JSON construction (`mcp_json_escape`, `mcp_json_obj`, `mcp_json_arr`), progress (`mcp_progress`, `mcp_run_with_progress`), cancellation (`mcp_is_cancelled`), logging (`mcp_log_info`, `mcp_log_warn`), configuration loading (`mcp_config_load`, `mcp_config_get`), error handling (`mcp_error` with `--hint` and `--data` flags for LLM-friendly errors), secure downloads (`mcp_download_safe`, `mcp_download_safe_or_fail` for SSRF-safe HTTPS fetching with retries), and embedded resources (`mcp_result_text_with_resource`). - [Scaffold Templates](https://github.com/yaniv-golan/mcp-bash-framework/tree/main/scaffold): Templates for generating compliant tools, resources, and prompts via `mcp-bash scaffold <type> <name>`; create a full server skeleton via `mcp-bash new <name>`. ## Configuration & Operations - [Registry Contracts](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/REGISTRY.md): Registry JSON schemas, TTL, regeneration, and manual overrides. - [Limits & Performance](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/LIMITS.md): Tunable limits for concurrency, payloads, progress throttling. - [Logging](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/LOGGING.md): Log levels, verbose mode, and structured logging. - [Roots](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/ROOTS.md): MCP roots scoping for filesystem access control. - [Minimal Mode](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/MINIMAL-MODE.md): Behavior when jq/gojq is missing or minimal mode is forced. - [Security](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/SECURITY.md): Threat model, provider hardening, and guidance around local diagnostics (`mcp-bash doctor`, debug mode). ## Optional - [MCPB Bundles](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/MCPB.md): Create distributable `.mcpb` packages for one-click installation. Supports user configuration (`MCPB_USER_CONFIG_FILE`, env/args mapping), metadata fields (`MCPB_LICENSE`, `MCPB_KEYWORDS`, `MCPB_HOMEPAGE`, etc.), and compatibility constraints (`MCPB_COMPAT_CLAUDE_DESKTOP`, runtime requirements). - [Security Policy](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/SECURITY.md): Input validation, execution safety, and threat model. - [Windows Support](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/WINDOWS.md): Running on Git Bash/WSL, path normalization, and known limitations. - [Remote Connectivity](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/REMOTE.md): Exposing mcp-bash over HTTP/SSE via external gateways. - [Debugging Guide](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/docs/DEBUGGING.md): Debug mode, payload tracing, and log analysis. - [Changelog](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/CHANGELOG.md): Notable changes between releases. - [Contributing](https://github.com/yaniv-golan/mcp-bash-framework/blob/main/CONTRIBUTING.md): Development setup, coding conventions, and PR workflow.