win-shell-mcp

KI-native, plattformübergreifende Befehlsabstraktionsebene – bietet 40 deterministische Tools als MCP-Server, ersetzt direkte Shell-Aufrufe, vereinheitlicht minimale JSON-Ausgabe und behandelt Windows-Pfad-/Kodierungs-/Anführungszeichenunterschiede.

Warum

KI den Aufruf von Shell-Befehlen zu überlassen, ist gefährlich und unzuverlässig:

• Plattforminkonsistenzen: Windows-Pfadtrennzeichen, Kodierung (GBK), Anführungszeichen, Befehlsnamen (del vs rm) unterscheiden sich stark von Unix

• Schwer zu parsende Ausgabe: Die Ausgabe von Shell-Befehlen ist formlos, sodass KI schwer zuverlässig Informationen extrahieren kann

• Sicherheitsrisiken: Die reine Shell erlaubt Pipes, Umleitungen und Befehlsinjektion

win-shell-mcp ersetzt gängige Shell-Befehle durch 40 deterministische Tools. Jedes Tool:

• Akzeptiert strukturierte JSON-Parameter und gibt einheitliches { ok: true, ...data } oder { ok: false, error: { code, message } } zurück

• Verhält sich plattformübergreifend konsistent (gleiche Konfiguration für Windows/macOS/Linux)

• Minimale Ausgabe (standardmäßig nur die für KI-Entscheidungen notwendigen Felder), verbose-Schalter für vollständige Daten

• Standardisierte Fehlercodes (ENOENT/EISDIR/ENOTDIR/EACCES/EINVAL/ETIMEOUT/EEXEC/EUNKNOWN/INVALID_URL/NET_TIMEOUT/NET_FAIL/PROC_NOT_FOUND/PROC_KILL_FAIL/EXEC_FAIL/EXEC_TIMEOUT/GIT_FAIL)

Related MCP server: Pare

Installation

# 全局安装
npm install -g win-shell-mcp

# 或一次性运行
npx win-shell-mcp

Erfordert Node.js ≥ 18.

Client-Konfiguration

Claude Desktop

Bearbeiten Sie claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "win-shell-mcp": {
      "command": "win-shell-mcp"
    }
  }
}

Wenn nicht global installiert, verwenden Sie npx:

{
  "mcpServers": {
    "win-shell-mcp": {
      "command": "npx",
      "args": ["win-shell-mcp"]
    }
  }
}

Allgemeiner MCP-Client

Jeder Client, der mit dem Model Context Protocol kompatibel ist, kann über stdio verbunden werden:

{
  "mcpServers": {
    "win-shell-mcp": {
      "command": "win-shell-mcp",
      "transport": "stdio"
    }
  }
}

Nach dem Start kommuniziert der Client über stdio mit dem Server und entdeckt automatisch alle 40 Tools.

Tool-Liste (40)

Gruppiert nach Domäne. Jedes Tool gibt einen einheitlichen Ausgabevertrag zurück: Erfolg { ok: true, ...data }, Fehler { ok: false, error: { code, message } }.

system (4)

fs_read (3)

fs_write (6)

text (6)

search (3)

process (2)

shell_exec (1)

env (3)

net (4)

pkg (2)

git (6)

⚠️ Sicherheitshinweis

Keine Sandbox, volle Berechtigungen.

Dieser Server führt alle Operationen mit den vollen Berechtigungen des ausführenden Benutzers aus, gleichwertig zur reinen Shell. fs_rm kann jede zugängliche Datei löschen, shell_exec kann jeden beliebigen Befehl ausführen, process_kill kann jeden zugänglichen Prozess beenden, fs_write kann jede zugängliche Datei überschreiben.

Verwenden Sie dies nur in vertrauenswürdigen Umgebungen:

• Verbinden Sie sich nur mit KI-Clients, denen Sie vertrauen

• Setzen Sie dies nicht in gemeinsam genutzten/Mandantenfähigen Umgebungen ein

• Bestätigen Sie Operationen an sensiblen Verzeichnissen (Systemverzeichnisse, Benutzerhome) manuell

• In Produktionsumgebungen wird die Kombination mit Betriebssystem-Berechtigungsisolierung empfohlen (dediziertes Konto mit niedrigen Rechten, Container, chroot usw.)

Dieses Projekt bietet keine Sandbox, Berechtigungsisolierung, Befehlsblacklist oder Pfadbeschränkungen. Die gesamte Zugriffskontrolle basiert auf den Betriebssystemberechtigungen.

Entwicklung

# 安装依赖
npm install

# 类型检查
npm run typecheck

# 测试
npm test

# 测试（watch 模式）
npm run test:watch

# 覆盖率（阈值：lines/functions/statements ≥ 85%，branches ≥ 70%）
npm run coverage

# 构建
npm run build

# 开发模式（watch 构建）
npm run dev

Das Build-Artefakt ist dist/index.js (tsup-Bundle, ESM).

Projektstruktur

src/
  index.ts          # 入口：启动 stdio server
  server.ts         # MCP Server 创建与工具分发
  registry.ts       # 工具注册表（注册全部 40 个工具）
  contract/         # 输出契约与错误码
  encoding/         # 编码检测（GBK/UTF-8）
  tools/            # 40 个工具实现，按域分文件
tests/
  server.test.ts    # server 单元测试
  integration/      # 集成测试（Client + InMemoryTransport）
  tools/            # 各工具单元测试
  contract/         # 契约测试
  encoding/         # 编码测试

Lizenz

MIT