Tokenize shell command strings into argv arrays and safely quote arguments via @mukundakatta/shlex-mcp

@mukundakatta/shlex-mcp v0.1.0 — Shell Lexer MCP Server

POSIX shell command tokenizer and argument quoter. 2 tools: split (tokenize command string into argv) and quote (safely single-quote an argument).

Install & Run

npm install --prefix /tmp/shlex-mcp @mukundakatta/shlex-mcp
ENTRY=$(realpath /tmp/shlex-mcp/node_modules/@mukundakatta/shlex-mcp/dist/server.js)
# Spawn as MCP stdio server
node $ENTRY

Tools

Key Findings (20 calls, 100% success, p50=7ms)

split behavior:

• Double quotes preserve spaces: echo "hello world" foo → ["echo", "hello world", "foo"]
• Single quotes preserve everything: grep -r 'pattern with spaces' /path → ["grep", "-r", "pattern with spaces", "/path/to/dir"]
• Backslash escapes: ls my\ file.txt → ["ls", "my file.txt"]
• Env vars NOT expanded: echo $HOME "${USER}" '$SHELL' → ["echo", "$HOME", "${USER}", "$SHELL"] (POSIX split only, no shell expansion)
• Pipes/redirects are separate tokens: cat file.txt | grep "error" > output.log 2>&1 → ["cat", "file.txt", "|", "grep", "error", ">", "output.log", "2>&1"]
• Backticks and $() preserved as literals (not executed)
• Semicolons NOT split: echo hello; → token is "hello;"
• Tabs work as delimiters
• Empty string → {tokens: []}
• Unicode safe (Turkish İ/ü/Ç/Ş/Ğ preserved)

quote behavior:

• Spaces → single-quoted: hello world → 'hello world'
• Single quotes in input → break-and-escape: it's a test → 'it'\''s a test'
• Shell metacharacters neutralized: foo|bar;baz>qux → 'foo|bar;baz>qux'
• Safe barewords unquoted: simple → simple (no unnecessary quotes)
• Empty string → ''
• $HOME → '$HOME' (prevents variable expansion)
• Newlines → 'line1\nline2'
• Backtick injection prevention: ` rm -rf / → '\rm -rf /\'`

Round-trip verified:

original: docker run -e "MY_VAR=hello world" --name my-container image:latest
tokens:   ["docker","run","-e","MY_VAR=hello world","--name","my-container","image:latest"]
re-quoted: docker run -e 'MY_VAR=hello world' --name my-container image:latest

Gotchas

• ⚠️ Param is `input` NOT `text` — using text causes Cannot read properties of undefined (reading 'length') error
• Semicolons are NOT delimiters — echo hello; echo world splits to ["echo", "hello;", "echo", "world", ...] (semicolons stay attached to preceding token)
• No shell expansion — $HOME, $(date), backticks are all preserved as literal text, not evaluated
• Different from shellquote-mcp — shellquote-mcp provides quote_bash, quote_bash_argv, quote_cmd, quote_powershell (4 output formats for quoting). shlex-mcp provides split (tokenizing) + quote (single-quoting only). Complementary tools.
• First call ~40ms JIT, subsequent 4-7ms