MCP-ShellJS

一个为 Claude 等 LLM 提供安全、受控 ShellJS 访问的 MCP 服务器。

概述

MCP-ShellJS 将模型上下文协议 (MCP) 与 ShellJS 连接起来，使 AI 系统能够在安全沙箱中执行 shell 命令。 它提供受控的文件系统访问，并具有多层安全保护。

特性

• 简化安全性:
  • 默认只读模式
  • 可选的读写模式，通过命令行标志启用
  • 可选的 exec 权限，通过命令行标志启用
• 基于 Zod 的模式验证
• 完整的 ShellJS 功能（ls、grep、sed、find 等）
• 使用强类型的 TypeScript 实现
• 简单的 LLM 集成 API

安装

# 克隆仓库
git clone https://github.com/yourusername/mcp-shelljs.git
cd mcp-shelljs

# 安装依赖
npm install

# 构建项目
npm run build

用法

命令行

# 默认模式（只读）
node dist/index.js

# 启用读写操作
node dist/index.js --enable-rw

# 启用 exec 命令（小心！）
node dist/index.js --enable-exec

# 同时启用两者
node dist/index.js --enable-rw --enable-exec

TypeScript 集成

// 导入并初始化 MCP 服务器
import { startMCPServer } from 'mcp-shelljs';

// 使用默认配置启动服务器（只读）
startMCPServer();

// 或使用自定义安全配置
startMCPServer({
  enableRw: true,   // 启用读写操作
  enableExec: false // 保持禁用 exec
});

安全设计

MCP-ShellJS 实现了简单的安全模型：

1. 只读模式（默认）：仅提供不修改文件系统的命令
2. 读写模式 (--enable-rw)：启用可以创建、修改或删除文件的命令
3. Exec 模式 (--enable-exec)：启用可能危险的 exec 命令，用于执行任意 shell 命令

该服务器仅使用 stdio 传输运行，使其适合与桌面 LLM 应用程序集成。

为什么使用 MCP-ShellJS？

对于 AI 开发者，MCP-ShellJS 能够以受控的风险实现强大的文件系统功能：

• 高效探索：使用 grep 和 find 在代码库中快速搜索
• 文本处理：使用 sed 转换文件，而无需完全加载它们
• 安全自动化：让 AI 帮助进行文件组织和管理
• 强大的管道：使用 Unix 风格的管道连接操作

资源

目录资源

directory://{path}?include={glob}&exclude={glob}&honor_gitignore={boolean}

提供目录列表，具有强大的过滤功能：

参数	描述
include	要包含的 Glob 模式（例如，*.js,*.ts）
exclude	要排除的 Glob 模式（例如，node_modules,dist）
honor_gitignore	当为 true 时，过滤掉与 .gitignore 中的模式匹配的文件
recursive	当为 true 时，递归包含子目录

示例：

directory:///project/src?include=*.ts&exclude=*.test.ts&honor_gitignore=true

文件资源

file://{path}?lines={boolean}&start={number}&end={number}

提供文件内容，并提供查看特定部分的选择：

参数	描述
lines	当为 true 时，在输出中包含行号
start	要包含的第一行（从 1 开始的索引）
end	要包含的最后一行
highlight	用于突出显示匹配文本的 Glob 模式

示例：

file:///project/src/index.ts?lines=true&start=10&end=50

工具

MCP-ShellJS 将 ShellJS 命令公开为工具，按安全风险级别分组：

只读工具

工具	描述	参数
cat	输出文件内容	files: 字符串/数组, options: 带有 -n (行号) 的对象
grep	在文件中搜索模式	regex, files, options: 带有 -v (反转), -l (仅文件名), -i (忽略大小写) 的对象
find	递归查找文件	paths: 字符串/数组 (返回包含基本目录的文件路径)
ls	列出目录内容	paths: 字符串/数组, options: 带有 -R (递归), -A (全部), -L (跟随符号链接), -d (仅目录) 的对象
which	查找命令	command: 字符串 (返回命令的路径)
pwd	打印工作目录	(无参数)
test	测试文件条件	expression: 字符串 (例如, -d path 目录存在, -f path 文件存在)
head	显示前几行	files: 字符串/数组, options: 带有 -n <num> (要显示的行数) 的对象
tail	显示最后几行	files: 字符串/数组, options: 带有 -n <num> (要显示的行数) 的对象
sort	排序行	files: 字符串/数组, options: 带有 -r (反向), -n (数字) 的对象
uniq	过滤重复行	input: 字符串, output: 字符串, options: 带有 -i (忽略大小写), -c (计数), -d (仅重复项) 的对象

读写工具

工具	描述	参数
mkdir	创建目录	dir: 字符串/数组, options: 带有 -p (创建中间目录) 的对象
touch	创建/更新文件	files: 字符串/数组, options: 带有 -c (不创建), -a (仅访问时间), -m (仅修改时间) 的对象
cp	复制文件/目录	source: 字符串/数组, dest: 字符串, options: 带有 -R (递归), -n (不覆盖), -f (强制) 的对象
mv	移动文件/目录	source: 字符串/数组, dest: 字符串, options: 带有 -f (强制), -n (不覆盖) 的对象
rm	删除文件/目录	files: 字符串/数组, options: 带有 -r/-R (递归), -f (强制) 的对象
sed	文件的流编辑器	search_regex: RegExp, replacement: 字符串, files: 字符串/数组, options: 带有 -i (就地) 的对象

特殊权限工具

工具	描述	参数
exec	执行命令	command: 字符串, options: 带有 async, silent 的对象, 需要 allowExec: true 配置

许可证

GPL-3.0-or-later