MCP server
zsh-lint includes a local Model Context Protocol (MCP) server that provides
static semantic analysis and native Zsh syntax validation to MCP clients over
standard input and output.
How it worksโ
Start the server with the mcp subcommand from the working directory against
which relative paths should resolve:
zsh-lint mcp
The server communicates using newline-delimited JSON-RPC 2.0 on standard input and standard output. Standard output carries protocol messages only; server logging is written to standard error.
Configure an MCP client to launch the server by specifying the command zsh-lint
with the argument list ["mcp"]. The command does not install an HTTP listener,
write configuration files, or perform automatic client registration.
To select a specific Zsh binary for native syntax checks, pass --zsh PATH:
zsh-lint mcp --zsh /path/to/zsh
To display usage information without starting the server, pass -h or --help:
zsh-lint mcp --help
Like the main CLI, -h and --help print usage to standard output and exit 0.
Startup usage errors exit with status 2, and closing standard input (EOF) shuts
down the server normally.
Available toolsโ
The server registers exactly two tools: zsh_lint and zsh_syntax. Both tools
require explicit file paths resolved against the server working directory. They do
not accept directory paths, inline source text, or recursive globs.
zsh_lintโ
zsh_lint runs static analysis and emits diagnostics in the version 1 JSON
envelope used by zsh-lint --format=json.
Argumentsโ
files(array of strings, required): Non-empty array of file paths to analyze.config(string, optional): Path to an explicitzsh-lint.jsonconfiguration file.no_config(boolean, optional, defaultfalse): Disables automaticzsh-lint.jsondiscovery.
config and no_config: true are mutually exclusive. When neither is provided,
the server walks up the directory hierarchy from each input file to discover the
nearest zsh-lint.json. Files analyzed together in one call share project rule
scope.
Resultsโ
Analyzer findings, including parser errors reported under the reserved rule
parse/error, are returned as successful tool results (isError: false) with
the diagnostic envelope in structuredContent and serialized in the text content
block.
Unreadable inputs, non-regular files, or configuration errors return an error
result (isError: true) with actionable error text. When partial diagnostics
exist alongside a configuration discovery failure, the result includes the
diagnostic envelope followed by the error text. Without diagnostics, the error
text is the only content block.
zsh_syntaxโ
zsh_syntax validates file syntax with native Zsh using two complementary
checks: a syntax pass (zsh -f -n -- FILE) and compilation
(zcompile -U -R).
Argumentsโ
files(array of strings, required): Non-empty array of file paths to check.
This tool does not use zsh-lint.json configuration.
Evaluation and resultsโ
The server locates zsh on PATH by default, or uses the path supplied via
--zsh at startup. If native Zsh is missing from PATH, only zsh_syntax
fails; static analysis with zsh_lint continues to function.
Compilation writes to a disposable temporary directory, which is removed when
the call finishes. No .zwc file is written beside an input.
A file is considered valid (valid: true) only when both checks complete with
empty standard error. Exit status alone does not determine validity because
valid Zsh constructs such as negation (! true) exit with status 1 under
zsh -f -n despite having valid syntax.
The result contains a files array matching the input order:
{
"files": [
{
"file": "script.zsh",
"valid": true,
"syntax": {"stderr": "", "exit_code": 0},
"compile": {"stderr": "", "exit_code": 0}
}
]
}
Files with syntax errors return valid: false within a successful tool call.
Infrastructure errors such as missing input files, execution failures, or
timeouts return isError: true.
Security and execution boundariesโ
Static analysis performed by zsh_lint does not source or execute inspected files.
Native syntax checks executed by zsh_syntax do not run the input program,
but the system zshenv startup file still runs, and native parsing is not a
sandbox for hostile source. Use the native checks only with trusted input files,
a trusted Zsh executable and trusted system startup configuration.
Both tools report read-only and idempotent hints because their intended effect
is analysis.