Skip to main content
Glama
ubbcou

system-command-mcp

by ubbcou
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

system-command-mcp

跨平台系统命令 MCP Server。AI 通过稳定的 program + args[] 接口直接调用已注册程序，无需用 which、where、command -v 或 Get-Command 探测工具；它不是 Shell，自动发现程序集也明确不包括 PowerShell。

工具

system_exec

program 是启动时注册的逻辑程序名；其 Schema 已枚举可用项：

{
  "program": "git",
  "args": ["status", "--short"],
  "cwd": ".",
  "timeoutMs": 30000
}

对原生可执行文件，args 是逐项传递的字面量参数，不经过 Shell 展开或组合；例如 $HOME、*.ts 和 && 都只是参数文本。Windows 的 .cmd / .bat 平台包装程序例外：它们会由 cmd.exe 重新解析，且参数中拒绝 %、!、&、|、<、>、^、CR、LF 和 NUL；即使被接受，参数保真度也比原生程序更窄。用 system_environment 的 argumentSemantics 区分 literal 与 cmd-reparsed。

system_environment

返回平台、架构、根工作目录、模式、Roots，以及逻辑程序名到真实可执行文件的映射（包括 kind 和 argumentSemantics）。通常无需先调用；system_exec.program 的 Schema 已包含可用程序。

system_output

以 Execution Artifact 的不透明 id 分页读取已完成执行的 stdout 或 stderr 原始输出。Artifact 不是主机文件路径，不能用主机文件系统工具读取。

Related MCP server: SSH MCP Server

交给 AI Agent 自动安装

在目标设备上，将对应的一句话复制给 AI coding agent。Agent 会读取仓库中的完整指南，完成版本化 Managed Installation、独立 Manifest、配置备份、Codex/DSH 切换和真实验收：

Windows 一句话：

请读取并严格执行 https://raw.githubusercontent.com/ubbcou/system-command-mcp/main/docs/install/windows-agent.md 。自主完成环境识别、不可变 <version>-<shortSHA> Managed Installation、临时 Manifest 验证及受控提升、Codex/DSH 配置备份与切换，以及真实验收和失败回滚；除非遇到缺少凭据、软件或权限等外部阻塞，否则不要让我手动操作。不要执行 npm publish 或创建 GitHub Release。

macOS 一句话：

请读取并严格执行 https://raw.githubusercontent.com/ubbcou/system-command-mcp/main/docs/install/macos-agent.md 。自主完成环境识别、macOS arm64 本机构建、不可变 <version>-<shortSHA> Managed Installation、临时 Manifest 验证及受控提升、Codex/DSH 配置备份与切换，以及真实验收和失败回滚；除非遇到缺少凭据、软件或权限等外部阻塞，否则不要让我手动操作。不要复制其他系统的 node_modules，不要执行 npm publish 或创建 GitHub Release。

构建和测试

npm install
npm run build
npm test

需要 Node.js 20 或更高版本。

管理 CLI 与 MCP 配置

# 发现固定的默认自动程序集；--yes 将每个已发现程序写为 Optional，且不会修改 Codex 或 DSH 配置
system-command-mcp init --yes --manifest system-command-manifest.json
# 已有 Manifest 默认拒绝覆盖；仅 --force 可以替换
system-command-mcp init --yes --force --manifest system-command-manifest.json
# 配置模式必须显式提供至少一个 Root；旧的 `--root PATH` 调用在 1.0 前仍兼容，但会发出 stderr 弃用提示
system-command-mcp serve --manifest system-command-manifest.json --root /absolute/path/to/workspace
# 默认构造并关闭配置 Runtime 以静态验证候选项、环境引用和限制，不执行程序；--execute 仅执行 Manifest 明确声明的 probes
system-command-mcp doctor --manifest system-command-manifest.json --root /absolute/path/to/workspace
system-command-mcp doctor --execute --manifest system-command-manifest.json --root /absolute/path/to/workspace
# 仅把对应的配置片段写到 stdout，注意审阅后手动添加
system-command-mcp print-config codex --manifest system-command-manifest.json --root /absolute/path/to/workspace
system-command-mcp print-config dsh --manifest system-command-manifest.json --root /absolute/path/to/workspace

Manifest Schema 和示例分别为 system-command-manifest.schema.json、system-command-manifest.example.json。Schema 用严格 oneOf 区分版本：v1 是兼容过渡格式，只接受 nodeResolution；v2 只接受可选 projectNode，并允许平台对它做完整替换。示例展示 v2。probes 仅供 doctor --execute 使用，启动 MCP 不会执行它们。Codex 输出说明 $CODEX_HOME/config.toml 和实际有效的 CODEX_HOME（默认 ~/.codex）；v0.1.0 有意设置启动超时 30 秒、工具超时 300 秒，并给出 codex mcp list --json / codex mcp get system-command --json 验证命令。DSH 输出是 rc.6 的 Cordis @deepseek-ai/dsh-mcp-client 插件列表行，包含 serverName、transport、command、args、cwd、30,000 ms toolCallTimeoutMs、启动失败致命和有界 reconnect（500/30000/10）。

Host Guidance

  • 一个直接的已注册 Program 调用使用 system_exec；

  • 管道、重定向、展开及其他 Shell 组合使用宿主 Shell；

  • 读写和枚举文件使用宿主文件系统工具；

  • Root 只验证执行进程的 cwd，不是文件系统沙箱，也不会限制已启动程序能访问的文件。

自动发现的逻辑程序

未提供 Manifest 时，自动发现模式仅尝试注册以下逻辑程序，并且只暴露启动环境中实际可解析的程序：

  • git、node、npm、pnpm、yarn、bun

  • python：依次尝试 python3、python

  • ripgrep：尝试 rg

不自动发现或暴露 PowerShell（pwsh / powershell）。 自动发现是向后兼容的零配置模式；它使用继承环境，不能承诺不同宿主间的一致程序身份。init 生成的 Manifest 会将上述已发现程序固定为绝对候选路径；配置模式则只注册 Manifest 声明的程序，且默认不继承 PATH，除非设置 allowInheritedPath: true。

当前限制与生命周期

  • 仅支持 stdio transport；不支持 Shell 命令字符串、管道、重定向、展开、命令替换或其他 Shell 组合。需要这些语义时，使用宿主 Shell；读写和枚举文件时，使用宿主文件系统工具。

  • 执行是有限且非交互式的：不支持 TTY、后台任务或常驻进程。进程成功启动后的非零退出、超时和取消均返回结构化 Execution Result，而不是 MCP 工具错误。

  • 默认超时为 30 秒，最多 600 秒；默认最多四个并发执行（可用 --max-concurrent-executions 设置）。stdout 和 stderr 分别保留最多 1 MiB 的 UTF-8 诊断投影，总量硬上限为 8 MiB，--inline-head-bytes 必须为正且不超过 --max-output-bytes：未截断时保留完整内容；截断时保留头部和尾部，并报告省略的字节数。完整流可按 Program Policy 作为 Execution Artifact 保存：never 不请求、on-truncation（默认）仅在任一流截断时发布、always 每次发布。Artifact 可能因存储不可用、配额或流大小上限（每流最多 100 MiB）而不可用，并受保留期和配额清理；只能在执行完成后通过 system_output 和不透明 id 读取。

  • cwd 必须在授权的 --root 内；多个 Root 时 cwd 必须为授权树内的绝对路径。Root 只验证进程从哪里启动，不是文件系统沙箱，也不限制已启动程序可访问的文件。

  • 程序、PATH、Manifest 和可用 Node 安装在启动时生成快照，变化都需要重启 Server。Manifest v1 的 nodeResolution 仅为兼容过渡；新配置使用 v2 的 projectNode，明确给出 enabledRoots、installationRoots 和精确 defaultVersion。每个 enabled Root 必须位于 Host Authorization 内，也是项目声明向上查找的唯一边界；不会读取 .git、VCS、package workspace 或 monorepo 逻辑，边界外请求只使用静态 Program。每个符合条件的 node / npm / npx 请求会重新读取 devEngines.runtime(node)、volta.node、.nvmrc、.node-version 和祖先 engines.node；这是请求输入，不是 Manifest/PATH/安装目录 watching。前四种声明必须是精确 pin，最近目录中的多个 pin 必须一致；engines.node 只做兼容性约束，不负责从安装集合挑最高版本。没有 pin 时默认使用 Manifest 的精确 defaultVersion；也可显式设置 whenNoSelector: "active-manager" 和只含一个条目的 activeManagerLinks；数组仅用于平台配置替换。每次请求观察这个唯一且权威的 manager-owned symlink/junction（Windows nvm 常用 C:\\Program Files\\nodejs）并选择启动快照中对应版本。权威链接缺失、非链接、损坏或不匹配时立即返回 PROJECT_NODE_ACTIVE_VERSION_UNAVAILABLE，不尝试其他链接，也不回退默认版本。冲突、无匹配或 engines 不兼容都静态失败；default、node、stable、lts/* 等 manager 默认/别名无效。启动和执行都不会运行版本管理器、安装缺失版本、联网或修改全局状态。选中 Variant 时，逻辑 npm / npx 必须与同一 Variant 的 canonical npm-cli.js / npx-cli.js 配对并由该 Variant 的 Node 启动；缺失即失败，不与静态 wrapper 混用。pnpm/yarn 不重定向。

  • 超时、取消和 Server 关闭会尝试终止整个 Process Tree，并在结构化 termination 字段中报告结果。Unix 使用进程组，后代若另建 session 或进程组会逃逸；Windows 使用每请求 Job Object（禁止 breakaway），但进程创建到加入 Job Object 之间存在无法验证的竞态，早期后代可能逃逸。Windows 无通用的优雅树终止，因此会立即强制终止；任务管理器回退路径也无法确认完整清理。始终检查 termination.treeCleaned 和诊断信息，不要把终止请求当作完整树清理的保证。

Available Tools

2 tools
system_environmentA

Return the authoritative system execution environment and registered logical program names. Program availability is already reflected in system_exec; do not probe with which, where, command -v, or Get-Command.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior3/5

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

With no annotations, the description must carry behavioral transparency. It conveys the tool is authoritative and not a probing tool, but it does not explicitly state whether it has side effects, what exactly 'registered logical program names' means, or potential output format limitations, leaving some ambiguity.

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 with no redundancy. The first sentence states purpose, the second provides usage guidance—concise and well-structured.

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?

For a simple tool with no parameters and no output schema, the description covers purpose, usage, and gives a warning about probing. It's fairly complete, though 'authoritative system execution environment' could be more precisely defined.

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?

The tool has zero parameters, and the schema is empty. The description doesn't need to explain parameters, and the baseline for 0 params is 4. It adds context about the tool's output scope but not parameter details.

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 returns the 'authoritative system execution environment and registered logical program names', which is specific and differentiated from the sibling tool system_exec by explicitly noting program availability is covered there.

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?

It explicitly tells when not to use this tool: 'do not probe with which, where, command -v, or Get-Command', and directs users to system_exec for program availability, providing clear alternatives and context.

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

system_execA

Execute one registered system program directly through a cross-platform program-and-arguments interface. Use only program names in the enum. Pass arguments separately without shell quoting. Shell operators, pipelines, redirects, command substitution, and environment expansion are not supported. Do not probe or guess alternative executable names.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNoWorking directory relative to the configured root, or an absolute path inside it.
argsNoArguments passed individually and literally; do not add shell escaping.
programYesRegistered logical program name mapped to the platform-specific executable.
timeoutMsNoPositive timeout in milliseconds, at most 600000; defaults to 30000.

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: no shell support, no quoting, strict program name whitelist, and cross-platform abstraction. However, it does not mention return value/exit code handling or error behavior, which would be valuable for an execution tool.

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 three sentences, front-loaded with the core purpose, followed by necessary constraints. Every sentence earns its place, with no redundancy or filler.

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

Completeness3/5

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

The tool has no output schema, so the description should clarify what happens after execution (stdout/stderr, exit code, or side effects). It does not, which leaves a notable gap. Otherwise, it covers the main execution constraints and usage context well.

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. The description adds meaningful context: program names must come from the enum, args are passed literally without shell escaping, and cwd is relative to the configured root. This supplements the schema descriptions with practical usage constraints.

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's purpose: 'Execute one registered system program directly through a cross-platform program-and-arguments interface.' It identifies the specific verb (execute), resource (registered system program), and interface style, distinguishing it from the sibling system_environment which concerns environment information.

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 provides explicit usage rules: 'Use only program names in the enum,' 'Pass arguments separately without shell quoting,' and lists unsupported constructs (shell operators, pipelines, redirects, command substitution, environment expansion). It also warns against probing or guessing alternative executable names, giving clear boundaries for when and how to use the tool.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

system_environment provides information about the execution environment and registered program names, while system_exec actually executes a program. Their purposes are completely distinct with no overlap, making selection unambiguous.

Naming Consistency5/5

Both tools follow a consistent 'system_' prefix pattern in snake_case. Although 'environment' is a noun and 'exec' is a verb, the uniform prefix and clear naming make the pattern predictable.

Tool Count3/5

With only two tools, the server feels minimal and borderline thin for even a focused command-execution utility. The count is not egregiously low, but it leaves little room for additional useful operations.

Completeness4/5

The two tools cover the core needs of querying the environment and executing registered programs. Minor gaps exist, such as no capability to manage program registrations or handle interactive sessions, but these are likely beyond the server's intended scope.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ubbcou/system-command-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server