🌐 English | 中文

shell-as-mcp

TypeScript Shell-as-MCP Server: maps shell commands to standard MCP tools via single-file YAML specs.

1) YAML Spec Design

Each YAML file defines one MCP tool. The root must contain apiVersion, tool, and execution.

apiVersion: v1
tool:
  name: <server>__<action>        # snake_case, e.g. brew__install
  description: |-
    /**
     * One-line description of the tool's purpose (TSDoc format, sole description field).
     * @param param_name Parameter description
     */
  input:
    properties:
      param_name:
        type: string              # string | number | integer | boolean
        description: "..."
    required: [param_name]
  output:
    type: object
    properties:
      status:            { type: string }
      exit_code:         { type: number }
      stdout:            { type: string }
      stderr:            { type: string }
      command:           { type: string }
      execution_time_ms: { type: number }
execution:
  shell:
    mode: direct                  # direct | shell
    name: bash                    # optional: bash | zsh | sh | pwsh | cmd
    path: /usr/bin/bash           # optional, takes precedence over name
    args: ["-lc"]                 # optional, defaults used if omitted
  env:
    static:
      KEY: VALUE
    fromParams:
      TOOL_ENV_KEY: inputParamName  # UPPER_SNAKE_CASE; add TOOL_ prefix if unsure
    fromRuntime:
      TARGET_ENV: SOURCE_ENV        # maps from server runtime env; supports priority lists
      TOOL_OUTPUT_DIR: [YTDLP_OUTPUT_DIR, SHELL_AS_MCP_OUTPUT_DIR]
  compatibility:
    targets:
      - os: macos
        kernel: darwin
        arch: arm64
        support: tested            # optional: tested | declared
        notes: Apple Silicon only validated target
  workingDirectory: /tmp/work
  timeoutMs: 30000
  taskMode: sync                  # sync (default, returns result synchronously) | async (background task, returns taskId immediately)
  maxOutputBytes: 1048576
  # Script mode (recommended: always use this in bundles)
  script:
    path: ./scripts/<tool_name>.sh  # relative to the YAML file's directory
    interpreter: bash
  # Command mode (only for a single executable + static args; forbid && || ; | > < in args)
  # command:
  #   executable: ffmpeg
  #   args: ["-version"]

Key constraints:

• tool.name format is <server>__<action>, all lowercase snake_case

• tool.description must be a TSDoc /** */ block comment

• execution.env.fromParams env var names use UPPER_SNAKE_CASE; add TOOL_ prefix when clashing with reserved names (PATH, HOME, USER, etc.)

• execution.compatibility is optional compatibility metadata; if present, targets must be a non-empty array and each target's os, kernel, arch must be non-empty strings

• targets[].support is optional and only allows tested or declared; targets[].notes is optional and must be a string

• If a target is marked support: tested, a corresponding per-target smoke test must exist under the bundle's scripts/: {prefix}__smoke_test__{kernel}_{arch}.sh (e.g. brew__smoke_test__darwin_arm64.sh)

• execution.command is forbidden when args contain shell operators (&&, ||, ;, |, >, <); multi-step logic must use execution.script

• Each YAML defines exactly one tool

• execution.env.fromRuntime supports a string array, resolved left-to-right with short-circuit; ideal for expressing group-level to global-level fallback chains

• execution.taskMode controls execution mode: sync (default, returns result synchronously) or async (background task, returns taskId immediately; query status via Task management tools)

1.1 Compatibility Metadata

execution.compatibility.targets declares "known runtime targets", not a "hard platform gate".

• Declare each target as a complete tuple to avoid generating incorrect cartesian products by splitting os, kernel, arch into separate lists.

• support: tested means the target has actual validation evidence; omitting it or using declared means the target is claimed to work, but the repository does not use this field as a runtime enforcement condition.

• The evidence for support: tested is a per-target smoke test script: {prefix}__smoke_test__{kernel}_{arch}.sh; lint verifies its existence.

• The current loader and lint validate the field structure, but the server startup and tool exposure logic do not perform platform filtering based on this field.

1.2 Health Check Contract

The __healthz tool's responsibility is dependency availability probing, not business execution.

• Goal: quickly determine whether the key runtime dependencies of a command bundle are present and callable.

• Output semantics: status=success means dependencies are available; status=error means a dependency is missing or not callable.

• Failure boundary: a healthz failure only indicates that the bundle's runtime requirements are not met in the current environment; it must not masquerade as success.

• Design requirement: healthz must stay lightweight and idempotent, with no side effects.

1.3 Zero-Parameter Tool Rule

For zero-parameter tools (e.g. healthz), the YAML input contract must satisfy:

• tool.input must exist and be a mapping (object).

• tool.input.properties must exist and be a mapping; empty object is allowed.

• tool.input.required should be an empty list for zero-parameter tools.

• Introducing dummy parameters just to "pass validation" is not allowed.

Lint alignment rules:

• Lint validates the existence and type of tool.input.properties, no longer enforcing non-empty.

• This ensures zero-parameter tools are expressed legally and consistently with their runtime behavior.

For the full spec, see shell_as_mcp_defs/runprompt__generate_artifact/prompts/type-specs/shell-as-mcp-yaml.spec.md.

1.4 __mcp_response_mode Parameter

Every tool has an implicitly injected optional parameter __mcp_response_mode:

Typically you do not need to pass this explicitly; the default content mode is sufficient.

Related MCP server: MCP-Ables

2) Developing shell_as_mcp_defs

Each subdirectory under shell_as_mcp_defs/ is a command bundle with the following layout:

shell_as_mcp_defs/<server>/
  spec_yaml/          # one YAML definition file per tool
  scripts/            # one .sh script per tool (referenced by execution.script.path in the YAML)
  prompts/            # optional: runprompt prompt templates

Manual development workflow:

1. Create <server>__<action>.yaml under spec_yaml/, following the §1 spec

2. Create the matching .sh under scripts/, reading params via $TOOL_* env vars

3. Run bash scripts/lint/lint_all.sh to validate

Generating via runprompt__generate_artifact:

⚠️ Work in Progress (WIP): The auto-generation feature of runprompt__generate_artifact is still under development and not yet stable. The spec documents under type-specs/ can be used directly as a reference for manual development, but relying on this tool to auto-generate bundles in production is not recommended.

runprompt__generate_artifact lets an LLM generate a complete bundle (YAML + scripts + optional prompts) in one shot, with the output automatically written to SHELL_AS_MCP_SPEC_DIR/<server_name>/.

Guidance for LLMs developing a new bundle (AI prompt)

When developing a new shell_as_mcp_defs bundle:

1. Full spec is in shell_as_mcp_defs/runprompt__generate_artifact/prompts/type-specs/:

   • shell-as-mcp-yaml.spec.md — YAML structure and forbidden patterns

   • script.spec.md — corresponding shell script spec

   • runprompt-prompt.spec.md — runprompt prompt spec

2. Reference existing bundle examples: brew/, ytdlp/, host_info/, ffmpeg/

3. All tool input params must be mapped to UPPER_SNAKE_CASE env vars via execution.env.fromParams with TOOL_ prefix; scripts only read $TOOL_*, never $1

4. Validate params early in scripts (fail fast); sensitive operations must be re-authorized inside the script and must not rely on the caller for authorization

5. execution.command is only for single-line static commands; multi-step logic must always use execution.script

3) Built-in Tools

All bundles are under shell_as_mcp_defs/ and loaded from SHELL_AS_MCP_SPEC_DIR at startup.

3.1 host_info

Parameters:

3.2 ffmpeg

3.2.1 ffmpeg Output Directory Defaults

Currently applies to ffmpeg__extract_frames_for_vision and ffmpeg__split_video.

Priority order:

1. Explicit parameter output_dir

2. Group-level env var FFMPEG_OUTPUT_DIR

3. Global env var SHELL_AS_MCP_OUTPUT_DIR

The tool's "directory output" contract remains unchanged; this only allows the default directory to be sourced from the runtime environment when no explicit parameter is passed.

3.3 brew

⚠️ brew__install / brew__uninstall / brew__upgrade require confirm_action=true to authorize execution; the script will also prompt a native macOS authorization dialog.

3.4 ytdlp

The cookies parameter accepts a path to a Netscape-format cookies file. You can also run ytdlp__setup_cookies first to encrypt and store cookies; subsequent tools will automatically fall back to these stored cookies when cookies is not specified.

3.4.1 Output Directory Priority

Applies only to ytdlp download tools: ytdlp__download_video, ytdlp__download_audio, ytdlp__download_video_subtitles.

Priority order:

1. Explicit parameter output_dir

2. Group-level env var YTDLP_OUTPUT_DIR

3. Global env var SHELL_AS_MCP_OUTPUT_DIR

4. Historical default ~/Downloads

Scripts uniformly read TOOL_OUTPUT_DIR; the bundle handles the mapping via execution.env.fromRuntime and execution.env.fromParams. This does not change the existing semantics of output_path / output_dir; it merely adds default value sources for download tools.

3.5 shell

3.6 advanced_substation_alpha_ass

Advanced SubStation Alpha (ASS) subtitle format toolkit.

3.6.1 ASS Output Directory Defaults

Applies to ass__create_template and ass__smoke_test when output_path is a relative path.

Priority order:

1. Explicit parameter output_dir

2. Group-level env var ASS_OUTPUT_DIR

3. Global env var SHELL_AS_MCP_OUTPUT_DIR

3.7 runprompt__generate_artifact

⚠️ Work in Progress (WIP): The auto-generation feature is still under development and not yet stable.

3.8 run_safe_command

⚠️ run_safe_command__execute and run_safe_command__pipeline both run without shell eval. execute accepts a single command + args in a validated working directory; pipeline accepts a JSON-structured sequence of pipe-connected stages, each validated against a safe command allowlist. On darwin/arm64, both use native Swift+WKWebView for pre-execution authorization and automatically fall back to OSA. All executions are written to a structured audit log.

3.9 iwencai

iwencai__query2data_basic and iwencai__search_basic are bounded, read-only wrappers around the local iwencai CLI. They require IWENCAI_API_KEY in the runtime environment and never write output files.

4) Running

npm install
npm run build
npm start

4.1 Launch via GitHub npx -y (stdio)

npx -y github:meomeo-dev/shell-as-mcp --transport stdio

If you use the runprompt__generate_artifact tool, install runprompt separately:

# Using uv (recommended)
uv pip install git+https://github.com/chr15m/runprompt
# Using pip
pip install "git+https://github.com/chr15m/runprompt.git"

4.2 Startup Options & Environment Variables

4.3 Built-in Spec vs. Overlay Directory

The tools in the built-in shell_as_mcp_defs/ are always loaded directly from the package. SHELL_AS_MCP_SPEC_DIR is an overlay directory that additionally loads tools from it; tools with the same name as built-in ones are overridden by the user directory.

• The default value is ./shell_as_mcp_defs (loaded only once when it matches the built-in path).

5) mcpServers Configuration

5.1 stdio (recommended for local use)

{
  "mcpServers": {
    "shell-as-mcp": {
      "command": "npx",
      "args": ["-y", "github:meomeo-dev/shell-as-mcp", "--transport", "stdio"],
      "env": {
        "SHELL_AS_MCP_SPEC_DIR": "/absolute/path/to/specs",
        "RUNPROMPT_MODEL": "openrouter/deepseek/deepseek-v3.2",
        "RUNPROMPT_BASE_URL": "https://openrouter.ai/api/v1",
        "RUNPROMPT_OPENROUTER_API_KEY": "sk-or-v1-xxxx",
        "https_proxy": "http://127.0.0.1:8890",
        "HTTPS_PROXY": "http://127.0.0.1:8890"
      }
    }
  }
}

5.2 streamable-http

{
  "mcpServers": {
    "shell-as-mcp-http": {
      "command": "npx",
      "args": [
        "-y", "github:meomeo-dev/shell-as-mcp",
        "--transport", "streamable-http",
        "--host", "127.0.0.1",
        "--port", "3001",
        "--http-path", "/mcp"
      ],
      "env": {
        "SHELL_AS_MCP_SPEC_DIR": "/absolute/path/to/specs",
        "SHELL_AS_MCP_SERVER_NAME": "shell-as-mcp-http"
      }
    }
  }
}

5.3 Available Environment Variables

All of the following env vars can be placed directly in mcpServers.<name>.env.

Server Startup

Output Directory Defaults

runprompt Generation

iwencai Query

Network Proxy

In short: if you just run the server normally, you typically only need SHELL_AS_MCP_SPEC_DIR; if you need file output, also add SHELL_AS_MCP_OUTPUT_DIR or the group-level directory vars; if you use runprompt__generate_artifact, also supply the RUNPROMPT_* vars.

runprompt__generate_artifact environment variables (⚠️ auto-generation is WIP):

Debug tip: set RUNPROMPT_DEBUG_PROMPT=1 to print the full rendered prompt before the request and enable runprompt -v.

6) Testing & Lint

# All TypeScript tests (unit + contract + e2e)
npm test

# Run smoke tests (generic + current-target)
bash scripts/run_smoke_tests.sh

# Build + pack + strict protocol handshake smoke in one command
make regress-pack-smoke

# Lint (YAML spec + shellcheck + prompt format; full scan of shell_as_mcp_defs/)
bash scripts/lint/lint_all.sh

lint_all.sh auto-discovers and validates five categories:

• spec_yaml/*.yaml → validate_shell_as_mcp_yaml.sh (structure/fields/forbidden patterns)

• scripts/*.sh → validate_script.sh (shellcheck)

• prompts/*.prompt (not starting with _) → validate_runprompt_prompt.sh (frontmatter/schema)

• spec_yaml/*.yaml (containing support: tested) → validate_tested_has_smoke_test.sh (verifies the corresponding per-target smoke test exists)

• SKILL.md → validate_skill_md.sh (frontmatter and structure)

run_smoke_tests.sh first runs each bundle's generic smoke test (*__smoke_test.sh), then auto-discovers and runs the per-target smoke test matching the current platform (e.g. *__smoke_test__darwin_arm64.sh).

make regress-pack-smoke runs build, npm pack, starts the server in streamable-http mode from the tarball, and validates the strict handshake sequence: initialize, notifications/initialized, tools/list.

Single-file validation:

bash scripts/lint/validate_shell_as_mcp_yaml.sh shell_as_mcp_defs/brew/spec_yaml/brew__info.yaml
bash scripts/lint/validate_script.sh shell_as_mcp_defs/brew/scripts/brew__info.sh
bash scripts/lint/validate_tested_has_smoke_test.sh shell_as_mcp_defs/brew/spec_yaml/brew__info.yaml

6.1 Make Shortcuts

make build    # clean + compile TypeScript + copy runtime assets
make test     # equivalent to npm test (unit + e2e)
make lint     # equivalent to bash scripts/lint/lint_all.sh
make deps     # npm ci to install dependencies
make help     # show all available make targets

6.2 Docker

# Build image
make docker-build

# Run container (stdio mode)
make docker-run

# Enter container shell for debugging
make docker-shell

Acknowledgements

This project builds on top of the following excellent open-source projects:

• @modelcontextprotocol/sdk — TypeScript MCP SDK providing standardized MCP server protocol implementation

• runprompt — CLI LLM prompt runner powering the runprompt__generate_artifact bundle

• dotprompt — Google's structured prompt format specification, influencing this project's prompt template design

License

MIT — see LICENSE for details.