Safely escape shell arguments for bash, cmd.exe, and PowerShell via @mukundakatta/shellquote-mcp (npx)

Recipe: Safe shell argument escaping via @mukundakatta/shellquote-mcp

Package: @mukundakatta/[email protected] (npm, MIT, zero non-SDK deps) Transport: stdio, NDJSON (newline-delimited JSON — SDK v1.29.0) Spawn: npx -y @mukundakatta/shellquote-mcp Tools: 4 — quote_bash, quote_bash_argv, quote_cmd, quote_powershell

Why agents need this

LLMs reliably get shell escaping wrong: confusing single vs double quotes, missing backslash escapes, leaving $VAR or %VAR% interpolation in generated commands. A single unescaped semicolon turns grep "user input" into arbitrary code execution. These tools make the escape choice explicit and correct.

Tool schemas

Verified calls (all succeed, p50 ~52ms)

1. Bash — neutralize injection attempt:

→ quote_bash({arg: "hello world; rm -rf /"})
← {quoted: "'hello world; rm -rf /'"}                          52ms

The entire string is wrapped in single quotes, making ; and / literal. Safe.

2. Bash argv — mixed nasties:

→ quote_bash_argv({args: ["grep", "-r", "user's \"data\"", "/var/log/app name", "$HOME/.config"]})
← {command: "grep -r 'user'\\''s \"data\"' '/var/log/app name' '$HOME/.config'"}   52ms

Note: grep and -r stay bareword (safe charset). The ' in user's gets the classic '\'' escape. $HOME is literalized inside single quotes.

3. PowerShell — path with embedded single quote:

→ quote_powershell({arg: "C:\\Users\\John's Files\\report.txt"})
← {quoted: "'C:\\Users\\John''s Files\\report.txt'"}           52ms

PS doubles the ' inside single-quoted strings. No variable expansion.

4. cmd.exe — metacharacters:

→ quote_cmd({arg: "file with spaces & special <chars>"})
← {quoted: "\"file with spaces & special <chars>\""}           52ms

Wrapped in double quotes. Note: cmd.exe has unfixable corner cases with delayed expansion (^, !, %). The tool is honest about this limitation.

Same macOS launch bug

Same import.meta.url guard issue as other @mukundakatta packages. Workaround: import the pure functions (quoteBash, quoteBashArgv, quoteCmd, quotePowershell) and wire to StdioServerTransport in a wrapper.

When to use

Use before every shell command an agent constructs from user-supplied or external data. The agent picks the target shell (bash, cmd, powershell) and calls the matching tool. One call per arg (or quote_bash_argv for a full command). Eliminates an entire class of injection bugs.