win-shell-mcp

AI 네이티브 크로스 플랫폼 명령어 추상화 계층 — MCP Server 형태로 40개의 결정적 도구를 제공하여 원시 셸 호출을 대체하고, 통일된 최소 JSON 출력을 제공하며, Windows 경로/인코딩/따옴표 차이를 처리합니다.

왜 필요한가

AI가 셸 명령어를 호출하는 것은 위험하고 신뢰할 수 없습니다:

• 크로스 플랫폼 불일치: Windows의 경로 구분자, 인코딩(GBK), 따옴표, 명령어 이름(del vs rm)이 유닉스와 크게 다릅니다.

• 출력 분석 어려움: 셸 명령어 출력 형식이 일정하지 않아 AI가 정보를 안정적으로 추출하기 어렵습니다.

• 보안 위험: 원시 셸은 파이프, 리다이렉션, 명령어 주입을 허용합니다.

win-shell-mcp는 40개의 결정적 도구로 일반적인 셸 명령어를 대체합니다. 각 도구는:

• 구조화된 JSON 매개변수를 받아들이고, 통일된 { ok: true, ...data } 또는 { ok: false, error: { code, message } }를 반환합니다.

• 크로스 플랫폼에서 일관된 동작(Windows/macOS/Linux 동일한 설정).

• 최소 출력(기본적으로 AI 의사 결정에 필요한 최소 필드만 포함), verbose 스위치로 전체 데이터 획득.

• 표준 오류 코드(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

설치

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

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

Node.js ≥ 18이 필요합니다.

클라이언트 설정

Claude Desktop

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

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

전역 설치가 아닌 경우 npx 사용:

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

일반 MCP 클라이언트

Model Context Protocol과 호환되는 모든 클라이언트는 stdio를 통해 연결할 수 있습니다:

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

시작 후 클라이언트는 stdio를 통해 서버와 통신하며, 전체 40개의 도구를 자동으로 발견합니다.

도구 목록 (40개)

도메인별로 그룹화됨. 각 도구는 통일된 출력 계약을 반환: 성공 { ok: true, ...data }, 실패 { 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)

⚠️ 보안 설명

샌드박스 없음, 모든 권한.

이 서버는 실행 중인 사용자의 전체 권한으로 모든 작업을 수행하며, 원시 셸과 동등합니다. fs_rm은 접근 가능한 모든 파일을 삭제할 수 있고, shell_exec는 모든 명령어를 실행할 수 있으며, process_kill은 접근 가능한 모든 프로세스를 종료할 수 있고, fs_write는 접근 가능한 모든 파일을 덮어쓸 수 있습니다.

신뢰할 수 있는 환경에서만 사용하세요:

• 신뢰하는 AI 클라이언트에만 연결하세요.

• 공유/멀티테넌트 환경에 노출하지 마세요.

• 민감한 디렉터리(시스템 디렉터리, 사용자 홈 디렉터리) 작업 전에 수동으로 확인하세요.

• 프로덕션 환경에서는 운영 체제 수준의 권한 격리(전용 낮은 권한 계정, 컨테이너, chroot 등)를 함께 사용하는 것이 좋습니다.

이 프로젝트는 샌드박스, 권한 격리, 명령어 블랙리스트 또는 경로 제한을 제공하지 않습니다. 모든 접근 제어는 운영 체제 권한에 의존합니다.

개발

# 安装依赖
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

빌드 결과물은 dist/index.js (tsup 번들, ESM).

프로젝트 구조

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/         # 编码测试

License

MIT