Skip to main content
Glama
deenesjakoruzh
20000419

fauxnix

by 20000419
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

fauxnix

CI npm version npm downloads license 20000419/fauxnix MCP server

Run Linux-style commands on Windows — natively, deterministically, no VM, no WSL.

fauxnix is a bash→PowerShell translation layer built for AI agents. Your agent keeps writing the bash it already knows (ls -la | grep foo, find . -name '*.ts' | wc -l, kill -9 1234), and fauxnix deterministically translates each command into PowerShell, executes it natively, and hands back output that looks like GNU/Linux: ls -l columns, bash-style error messages, coreutils exit codes, UTF-8/GBK handled automatically.

One-command install for Claude Code · Codex · OpenCode · Kimi Code · Qwen Code, plus any MCP client. 109 translated commands · 400+ automated tests · 253-case differential corpus verified against real GNU coreutils · zero LLM calls at runtime.

Try it now — no install

npx fauxnix-cli@latest "ls -la src | head -3"
npx fauxnix-cli@latest translate "find . -name '*.log' -mtime +7 -delete"

fauxnix demo

$ fauxnix "ls -la src | head -2"
-rw-r--r-- 1 me me 1204 Aug 16 09:12 ast.ts
-rw-r--r-- 1 me me 8192 Aug 16 09:12 cli.ts

$ fauxnix "cat nope.txt"
cat: nope.txt: No such file or directory        # not a PowerShell stack trace

Related MCP server: wmux

Connect your agent — one command

npm install -g fauxnix-cli
fauxnix install --claude     # or --codex / --opencode / --kimi / --qwen
fauxnix doctor               # verifies encoding, harness config, and MCP round-trip

Idempotent; prints exactly what changed. Manual configurations below if you prefer to edit config files yourself.

npm package name is fauxnix-cli (the fauxnix name on npm belongs to an unrelated 2015 websocket library); the installed command is fauxnix. Requires Windows with PowerShell 5.1+ (built-in) and Node.js ≥ 18.

Claude Code

claude mcp add fauxnix -- fauxnix mcp

Codex (~/.codex/config.toml or codex mcp add fauxnix -- fauxnix mcp)

[mcp_servers.fauxnix]
command = "fauxnix"
args = ["mcp"]

Note: in non-interactive codex exec mode, MCP tool calls are auto-denied by the approval layer; pass --dangerously-bypass-approvals-and-sandbox (or run interactively and approve once).

OpenCode (opencode.json)

{
  "mcp": {
    "fauxnix": { "type": "local", "command": ["fauxnix", "mcp"] }
  }
}

Kimi Code — MCP servers live in a JSON file, not the TOML config: ~/.kimi-code/mcp.json

{
  "mcpServers": {
    "fauxnix": { "command": "fauxnix", "args": ["mcp"] }
  }
}

Qwen Code (~/.qwen/settings.json)

fauxnix install --qwen

The installer preserves the rest of settings.json and writes an absolute Node + package-entry launcher so Qwen startup does not depend on its working directory or PATH order. See the Qwen example for the generated JSON shape.

Any MCP client — stdio server: fauxnix mcp. The tool name is bash (override with FAUXNIX_TOOL_NAME). The tool description already teaches the model the supported subset, so no system-prompt changes are required.

Copy-paste quickstarts with a 10-command smoke test per harness: docs/examples/

The MCP session persists cwd, environment variables, export/unset, cd -/OLDPWD, and positional parameters (set -- / $1 / "$@") across tool calls — it behaves like a logged-in shell, not a stateless exec. $0 is the MCP tool name, not a Windows path.

For workflows whose commands are already known, the MCP server also exposes bash_batch: it compiles every step before execution, runs the plan atomically in one session, and returns one structured result per step in a single MCP round trip (stops on first nonzero exit by default).

{
  "steps": [
    { "id": "write", "command": "printf 'a\\r\\nb' > data.txt" },
    { "id": "measure", "command": "wc -c data.txt" }
  ]
}

See compiled MCP batch plans for timeout, budget, cancellation, and preflight semantics.

Measured: your model is probably worse at PowerShell than you think

Same model (DeepSeek-V4-Pro), same 5 tasks, three execution modes on one Windows machine — full data in docs/benchmark-deepseek-v4-pro.md and docs/benchmark-ark-models.md:

PowerShell

fauxnix

Git Bash

tool calls / unexpected errors

14 / 9

7 / 0

4 / 0

time (T1–T4)

163s

66s

57s

Across 7 models on the Volcano Ark Coding Plan, the PowerShell-vs-fauxnix gap held for every model tested — worst case (kimi-k2-thinking): 3.1× slower with 24 error events writing PowerShell vs zero errors through fauxnix. fauxnix lands within ~15% of the real-bash ceiling with no bash toolchain installed.

Why

LLM agents are dramatically better at bash than at PowerShell — bash dominates training data, so models on Windows often produce "looks right, doesn't run" commands (wrong quoting, curl that isn't curl, mojibake from codepage mismatches, inscrutable CategoryInfo error dumps).

fauxnix

Git Bash

WSL

Raw PowerShell

agent writes plain bash

✓

✓

✓

✗

only needs Node (no bash toolchain / VM)

✓

✗

✗ (VM, GBs)

✓

native Windows filesystem & environment

✓

mostly

✗ (9P bridge)

✓

GNU-exact output, verified

✓ 253-case differential

✓ (is GNU)

✓

✗

CRLF / UTF-8 / GBK traps handled

✓

locale-dependent

✓

✗

If Git Bash already works for you, keep it — we literally use it as our differential-testing oracle. fauxnix is for when you can't or don't want to ship one: agent fleets where the bash toolchain drifts or isn't detected (the Windows ARM64 Git-Bash detection failure is a live example), CI runners, locked-down machines, or anywhere a single npm install -g is easier than a toolchain.

fauxnix takes the third road: translate, don't emulate. A large, high-value subset of the Linux command line — file ops, text processing, process management, archives, networking basics — maps cleanly onto PowerShell + .NET. fauxnix implements that subset faithfully and fails loudly and helpfully on what it can't translate, so the agent never gets silently-wrong results. That matters as labs train computer-use agents on Mac fleets — the agent keeps writing bash; fauxnix makes the Windows box answer like the box the agent was trained on (RFC: computer-use parity).

What's translated

109 commands, output-matched against real GNU coreutils on Windows (Git Bash) during development:

  • files: ls cp mv rm mkdir rmdir touch mktemp ln readlink realpath basename dirname stat file du df find chmod chown diff

  • text filters: grep egrep sed awk sort uniq cut tr — sed/awk scripts are parsed while preparing an executable plan (unsupported constructs throw named errors, never silently misbehave)

  • text I/O: echo printf cat head tail wc tee nl tac md5sum sha1sum sha256sum base64 seq yes xargs

  • shell/system: cd pwd export unset env printenv ps kill pkill pgrep sleep which type whoami id groups date uname hostname uptime free nproc clear true false test [ [[ : pushd popd dirs sudo timeout man history less more source . eval exit alias set shift

  • network: curl wget ping netstat ss ip ifconfig nslookup dig host

  • archives: tar gzip gunzip zcat zip unzip

The curated agent-daily 60 carry a CommandSpec: unknown options fail with a GNU-style usage error instead of being ignored. The generated docs/command-specs.md is the exact list, coverage count, option table, and exclusion rationale; fauxnix list --json exposes the same per-command metadata. find stays unspec'd so predicates like -name still compile; sed/awk/egrep keep their command-specific parsers; tar remains native to tar.exe so supported bsdtar options reach the executable. Implemented GNU holes include cp -n / mv -n / touch -c / tee --append / grep -m / head --lines / du --max-depth / env -u / ps -f / command -V / date --date=@SECONDS.

Plus shell syntax: pipes, && / || / ;, redirections (> >> 2> 2>&1 < &>, /dev/null), quoting, $VAR $1 $# "$@" set -- shift, ${name:-word} ${name//pat/str} ${name:off:len} ${name[n]} ${#name[@]}, A=(x y z) array assignment, $(...) command substitution, VAR=x cmd prefixes, ~ expansion, and POSIX-style path normalization (/tmp, /d/foo → D:\foo). Exit codes follow bash conventions: 0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout.

Unknown commands (git, node, npm, python, cargo, gh, docker, ...) are passed through natively with argv-style quoting. Windows .cmd/.bat shims necessarily pass through cmd.exe; fauxnix preserves its supported punctuation and fails loudly for %, embedded double quotes, NUL, and line breaks rather than passing a different argument.

How it works

bash command ──parser──▶ AST ──translator──▶ PowerShell script ──executor──▶ selected PowerShell
                                                                              │
agent ◀── GNU-style output, bash-style errors ◀── UTF-8 framed host protocol ◀┘

  • Deterministic translation, zero LLM calls at runtime.

  • Each command maps to a generator that emits a self-contained PowerShell block honoring the "Fauxnix contract": string-per-line stdout, [Console]::Error.WriteLine for bash-style stderr, $script:fx_exit for exit codes, $input for stdin.

  • The executor wraps every script with UTF-8 enforcement, decodes native output at the process boundary (UTF-8 by default or GBK(936) in ansi mode), strips CLIXML serialization and PowerShell noise from stderr, and rewrites common PowerShell errors (including zh-CN locale messages) into bash phrasing. File reads are always sniffed per file (UTF-8 strict → GBK fallback), so grep/sed/awk over GBK files works in either mode.

  • Scripts run via -EncodedCommand (UTF-16LE) and transparently fall back to a temp .ps1 file when the 32 KB command-line limit would be exceeded.

PowerShell 7 is an opt-in, CI-tested tier: set FAUXNIX_PS=pwsh before starting fauxnix or its MCP harness. The default is Windows PowerShell 5.1; invalid values fail loudly rather than falling back. See PowerShell 7 support.

Known deviations (honest list)

fauxnix optimizes for the commands agents actually run. Documented deviations:

  • X=1 standalone assignments follow export semantics (one session-wide environment; bash's shell-var vs exported-var distinction does not exist), and a same-segment prefix is visible to $VAR inside the command's own words (Z=in [[ $Z == in ]] is true here, false in bash where word expansion precedes the temporary environment).

  • yes is capped at 65,536 lines — PS 5.1 pipelines cannot signal upstream producers to stop, so an unbounded yes | head would hang.

  • tail -f, eval, alias, heredocs, env -i/--ignore-environment, background &, and output/fd redirects on a non-last pipeline stage are rejected with operation-specific, actionable error messages instead of misbehaving. Per-stage < remains supported. (if/then/elif/else/fi, for x in ..., while/until, case ... esac (;; only), backtick substitution, command -v, pipeline read, dotenv-style source, word-level $((...)) arithmetic expansion, A=(x y z) arrays, and ${name//pat/str} / ${name:off:len} are supported.)

  • command -v <builtin> prints /usr/bin/<name> where bash prints the bare builtin name; exit codes and empty-result semantics match.

  • chmod maps only the read-only bit; exec bits are no-ops on Windows. chown is a silent no-op (as in Git Bash).

  • ps aux columns are approximations (no per-process CPU% accounting, USER shows ?).

  • gzip -c/pipeline stdin is text-faithful, not byte-faithful; file-mode gzip f is byte-exact.

  • A pipeline producing exactly one line, piped into wc -l, counts that line (bash would count 0 if the producer omitted the trailing newline). printf 'x' | md5sum stays byte-exact.

  • sed/awk support the common subset; hold-space, labels, arrays, loops throw named "not supported" errors at translate time.

  • curl/wget refuse loopback/private/reserved addresses (localhost, 127.x, ::1, 10.x, 172.16–31.x, 192.168.x, 169.254.x) as a safety default for agent-driven HTTP.

  • Native-tool pipelines vs encoding: PS 5.1 has a single console-encoding knob, so piping localized admin tools (ipconfig, tasklist — GBK on zh-CN) and UTF-8-native dev tools (node, curl) cannot both decode cleanly mid-pipeline. Default favors UTF-8 dev tools; set FAUXNIX_NATIVE_ENCODING=ansi when your agents grep Chinese output of native Windows admin tools.

Development

npm install
npm test          # unit + real-PowerShell integration suite (Windows only, auto-skipped elsewhere)
$env:FAUXNIX_PS = 'pwsh'; npm test   # same suite through PowerShell 7
npm run build
npx tsx scratch/run.mjs "any bash command"   # quick live check

Differential vs Git Bash is opt-in (FAUXNIX_DIFF_ORACLE=1; skips if unset or bash.exe is missing — Git Bash is not required). See test/differential/README.md. The 253-case corpus enforces the RFC C-7 minimum of 200 cases and a 95% identity gate; the weekly oracle runs from .github/workflows/differential.yml.

Architecture map: src/parser.ts (bash subset → AST) · src/translator.ts (AST → PowerShell + executor wrapper) · src/executor.ts (spawn, redirects, session persistence) · src/commands/*.ts (per-command generators) · src/mcp.ts (MCP server) · src/cli.ts.

Roadmap: docs/rfc-roadmap-to-1.0.md — tracks, milestones, and the RFC process for proposing waves.

Security

Trust model, host protocol, kill semantics, network guard, and reporting: SECURITY.md.

License

MIT © 20000419

Available Tools

4 tools
bashA
Destructive

Execute a Linux/bash-style command on this Windows machine.

Commands are deterministically translated to PowerShell and executed natively — no WSL or VM. Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), errors look like bash errors, and text encoding (UTF-8/GBK) is handled automatically.

Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), variables ($VAR $HOME $1 $# "$@" ~), set -- / shift, array assignment A=(x y z), ${name[n]} ${#name[@]} ${name//pat/str} ${name:off:len}, command substitution $(...), and 109+ coreutils-style commands (., :, [, [[, alias, awk, base64, basename, cat, cd, chmod, chown, clear, command, cp, curl, cut, date...). Unknown commands (git, node, npm, python, cargo...) are passed through and executed natively with argv-style quoting. Not supported: heredocs, env -i/--ignore-environment, background jobs. if/then/elif/else/fi, for-in loops, while/until, case ... esac, and word-level $((...)) arithmetic expansion are supported. CWD, environment variables, export/unset, cd, and positional parameters (set -- / $1 / "$@") persist across calls within this session — a resident PowerShell 5.1 host is started when the MCP session begins (and after reset), so the first bash tool call is already warm. Efficiency: when two or more commands or verification steps are already known, prefer bash_batch once instead of making several bash calls. Keep separate calls only when the next command requires model interpretation of the previous output. For byte-exact work, measure with wc -c or stat -c %s instead of inferring CRLF byte counts from displayed text. Exit codes follow bash conventions (0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout, 130 cancelled). The tool also returns structuredContent (schemaVersion 1) with stdout/stderr/exitCode/timedOut/cancelled/truncated/sessionId.

Platform requirement: the execution backend is native Windows PowerShell 5.1+. On hosts without PowerShell on PATH (e.g. Linux containers/sandboxes), the bash tool returns exit code 127 with an actionable error instead of running the command.

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesThe bash-style command line to run
timeout_msNoTimeout in milliseconds (default 120000)

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations only say readOnly=false, destructive=true, idempotent=false. The description goes far beyond with high-value behavioral disclosure: exact exit-code mapping (0/1/2/127/124/130), persistence of CWD/environment/positional params across calls via a resident PowerShell 5.1 host, platform fallback behavior (127 on non-PowerShell hosts), translation fidelity ('deterministically translated'), and return of structuredContent fields. No contradiction with annotations; the destructiveHint is consistent with running arbitrary shell commands.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long (roughly 400 words) but nearly every sentence carries load-bearing information: purpose first, then translation mechanism, supported syntax, unsupported cases, passthrough, persistence, exit codes, and platform requirement. The length is justified by the tool's high complexity. It is well-structured and front-loaded with the core purpose; only the 109+ coreutils-name enumeration is slightly bulky, but even it is useful for the agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description explicitly documents return semantics (GNU-formatted output, bash-style errors, structuredContent with stdout/stderr/exitCode/timedOut/cancelled/truncated/sessionId) and exit-code conventions, plus failure-mode behavior on hosts without PowerShell. Given the tool's complexity (2 required-ish params, persistent side effects, and universal command input), the description is sufficient for an agent to call it correctly in nearly all contexts.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3 even without additional info. The description nonetheless adds substantial meaning beyond the schema for both parameters: it documents what command syntax is supported (pipes, redirections, arrays, substitution), what is not (heredocs, background jobs), the timeout-related exit code 124, the timeout bounds/default (120000ms), and the platform conditions under which commands fail. Only timeout_ms could have been elaborated further, but the description clearly covers the important semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource: 'Execute a Linux/bash-style command on this Windows machine.' It further distinguishes the mechanism (deterministically translated to PowerShell, no WSL/VM) and the advertised behavior (GNU-like output/errors, automatic encoding), immediately differentiating it from siblings like bash_batch and fauxnix_translate. The passthrough clause for unknown commands (git, node, python...) also clarifies scope — it is a general command runner, not only a fixed command set.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance routes to the main alternative: 'prefer bash_batch once instead of making several bash calls' and 'keep separate calls only when the next command requires model interpretation of the previous output.' The unsupported-features list (heredocs, background jobs) also functions as a when-not. However, the description does not address when to use the sibling tools fauxnix_session or fauxnix_translate instead, leaving part of the alternative universe unguided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bash_batchA
Destructive

Compile and execute a preplanned multi-step bash workflow in one MCP round trip.

Use this instead of repeated bash calls when the complete sequence is already known. Steps run serially and atomically in the same persistent session: later steps see cwd, environment, and files from earlier steps, while run/reset requests cannot interleave. Every command is parsed and translated before step 1 runs, and the result reports each step separately.

By default the batch stops after the first nonzero exit. Set stop_on_error=false only when later steps should still run. timeout_ms and both output limits apply to the whole batch, not once per step. Output defaults to 256 KiB stdout and 64 KiB stderr; redirect larger artifacts to files. Preflight performs no operand-file reads: use sed -e with inline script text instead of sed -f. If a later command depends on model interpretation of an earlier result, use separate bash calls instead. For byte counts, include wc -c or stat -c %s as a verification step rather than calculating CRLF bytes mentally.

ParametersJSON Schema
NameRequiredDescriptionDefault
stepsYesOrdered workflow steps; all are compiled before execution begins
timeout_msNoTotal timeout for the complete batch (default 120000)
stop_on_errorNoStop after the first nonzero exit (default true)
stderr_limit_bytesNoTotal stderr budget shared by every step (default 65536)
stdout_limit_bytesNoTotal stdout budget shared by every step (default 262144)

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description richly discloses behavioral traits beyond the annotations: steps run serially and atomically in one persistent session, commands are pre-parsed before execution, output limits apply per-batch not per-step, preflight does no operand-file reads, and redirects are recommended for large artifacts. This complements the destructive/open-world hints with actionable detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized for a complex batch tool. It front-loads the core purpose and usage, then covers behavioral constraints, defaults, and caveats in a logical order. Every sentence conveys useful guidance without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description compensates by explaining step result reporting, failure behavior, session persistence, output limits, and preflight limitations. An agent has enough context to correctly select and invoke the tool, including how to handle large outputs and byte-count verification.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful semantics beyond the schema: timeout_ms and output limits apply to the whole batch rather than per step, and stop_on_error=false is recommended only when later steps should still run. This exceeds the baseline for fully-covered schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Compile and execute a preplanned multi-step bash workflow in one MCP round trip') and explicitly contrasts it with repeated bash calls. It clearly distinguishes this tool from the single-command sibling bash by focusing on preplanned multi-step workflows.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: use instead of repeated bash calls when the complete sequence is already known. It also provides exclusions: use separate bash calls when later steps depend on model interpretation of earlier results, and explains when stop_on_error=false is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fauxnix_sessionA
Idempotent

Inspect or reset the persistent fauxnix shell session (current directory, environment, positional count, session id). Actions: "status" (default) or "reset".

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNo"status" shows the session state (cwd, tracked env keys, positional count); "reset" clears it back to a fresh shellstatus

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark idempotentHint=true and destructiveHint=false; the description adds that reset 'clears it back to a fresh shell' and enumerates what status exposes. This contextualizes the mutation behavior beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence states the operation, resource, and fields, then a compact action list. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a single optional enum parameter, no output schema, and detailed action semantics in the schema, the description covers the essentials including reset side effects. It could specify the shape of a status response, but that is a minor gap for such a low-complexity tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the action property already explains both enum values. The tool description adds only 'session id' to the status contents, so it slightly extends but does not need to compensate for the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb pair (inspect/reset), a precise resource (persistent fauxnix shell session), and the exact state fields. This separates it clearly from sibling tools like bash and fauxnix_translate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The action enum and sentence imply when to use it (inspect or reset session state), but there is no explicit guidance about when not to use it or which sibling would be preferred. Usage context is clear enough by implication, but no exclusion or alternative is stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fauxnix_translateA
Read-onlyIdempotent

Translate a bash-style command into the equivalent PowerShell script WITHOUT executing it. Useful for learning/debugging what fauxnix does under the hood.

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesThe bash-style command line to translate (never executed)

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-destructive operation. The description adds behavioral context by emphasizing 'WITHOUT executing it' and that the command is 'never executed', reinforcing safety beyond the annotations. This matches the bar for adding value beyond structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the core action and immediate caveat (no execution) in the first sentence, then stating the use case. Every sentence earns its place without any wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has a single parameter, no output schema, and rich annotations (readOnly, idempotent, non-destructive), the description is complete enough. It explains the translation function, non-execution guarantee, and appropriate use case. The absence of return value detail is acceptable since there is no output schema to contradict, and the use case is clear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (1 parameter fully described in schema), so the baseline is 3. The description adds minimal parameter information beyond the schema (just reiterates 'bash-style command line'), but it does clarify that the command is never executed, which complements the schema description. No enum parameters exist to add further context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool translates a bash-style command into PowerShell without executing it, specifying the verb 'Translate' and the resource 'bash-style command'. It distinguishes itself from siblings like 'bash' or 'fauxnix_session' by highlighting its non-execution and translation-only purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states this is for learning or debugging what fauxnix does under the hood, providing clear context for when to use it. However, it does not specify when not to use it or mention alternatives, though the sibling 'bash' implies execution which contrasts with this tool's non-execution nature.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.13.0
    • Addedbash_batch
    • Changedfauxnix_session1 field changed
      • changedInput schema / properties / action / description
        Previous value: -"\"status\" shows the session state (cwd, tracked env keys); \"reset\" clears it back to a fresh shell"New value: +"\"status\" shows the session state (cwd, tracked env keys, positional count); \"reset\" clears it back to a fresh shell"
  2. 3 tool updates
    • First observedbash
    • First observedfauxnix_session
    • First observedfauxnix_translate
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: bash executes a single command, bash_batch runs a preplanned multi-step workflow, fauxnix_translate shows the PowerShell translation, and fauxnix_session inspects/resets session state. The one potential overlap between bash and bash_batch is explicitly resolved by their descriptions.

Naming Consistency3/5

The names are all lowercase and grouped by prefix (bash vs fauxnix), but they do not follow a consistent verb_noun convention. One bare noun tool, one noun_noun tool, and one noun_verb tool makes the pattern only partially predictable.

Tool Count5/5

Four tools is well-scoped for this server's purpose: single execution, batch execution, translation/debugging, and session management. Each tool earns its place without redundancy.

Completeness5/5

The tool surface fully covers the stated domain: execute commands, run batches, translate for debugging, and manage session state. There are no obvious gaps for a bash-compatibility focused server.

Maintenance

ActivityMaintained
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • COP Plug

    beepoo304
    F
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants to execute PowerShell commands, manage files, inspect projects, run Git operations, and monitor system information on Windows through a local MCP server.
    -

  • relaybridge

    maximyz3d
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides a local Windows control plane for PowerShell and AI CLIs, exposing MCP tools for safe terminal sessions, bounded provider calls, routing, committees, and run receipts.
    2
    MIT