安全指挥官MCP

](https://badge.fury.io/js/safe-commander-mcp) ![License: MIT](https://opensource.org/licenses/MIT) ![TypeScript](https://www.typescriptlang.org/)

一个安全的MCP（模型上下文协议）服务器，用于执行白名单开发命令，具有全面的安全控制和资源限制。特点革命性 智能命令发现 它将人工智能辅助从“试错”转变为主动、分类的命令建议。非常适合需要安全命令执行能力的AI助手。

特性

🧠 智能命令发现

革命的 list_available_commands 主动援助工具
按类型（包管理、版本控制、文件操作等）对命令进行分类
全面的命令描述和实时配置报告
从“试错”到智能指挥工作流程的转变

🔒 安全第一

命令白名单，包含可配置的允许命令
路径遍历预防和目录限制
具有字符净化功能的命令注入保护
资源限制（超时、输出大小、并发命令）
启动验证以尽早发现配置问题

⚡ 性能与监控

执行时间跟踪和详细日志记录
命令冷却时的速率限制（相同命令之间的最小值为1秒）
并发命令管理（可配置限制）
优雅的停机处理和清理

🛠️ 开发者友好

具有完全类型安全的TypeScript实现
全面的错误消息和调试日志
基于环境的配置
生产就绪日志记录到stderr（符合MCP）

快速启动（无需安装！）

🚀 您可以使用Safe Commander MCP，而无需在您的机器上全局安装！

🛡️ 安全第一的方法：默认情况下，只允许使用安全的只读命令来保护您的代码库和数据免受未经授权的访问。

只需将此配置添加到您的MCP客户端，您就可以开始了：

{
  "mcpServers": {
    "safe-commander": {
      "command": "npx",
      "args": ["-y", "safe-commander-mcp"],
      "env": {
        "ALLOWED_PATH": "/path/to/your/project",
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo"
      }
    }
  }
}

⚠️ 严重安全警告:

主要风险是LLM本身 -它可能会尝试访问敏感文件或执行危险的命令
您的代码库和数据保护 是主要的安全问题-命令可以读取私有文件、源代码、环境变量等。
只添加您完全理解的命令 -每个附加命令都会扩展LLM可以访问的内容
你有责任 了解您允许的每个命令的含义

就是这样！这 npx -y 命令将在需要时自动下载并运行最新版本。

配置

所需的环境变量

变量	必填	示例	描述
`ALLOWED_PATH`	✅ 是	`/Users/yourname/projects/my-app`	可以执行命令的目录（使用绝对路径）
`ALLOWED_COMMANDS`	没有	`ls,cat,pwd,echo`	逗号分隔的允许命令列表

Claude桌面设置

第一步： 打开您的Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%/Claude/claude_desktop_config.json

第二步： 添加安全指挥官MCP配置：

{
  "mcpServers": {
    "safe-commander": {
      "command": "npx",
      "args": ["-y", "safe-commander-mcp"],
      "env": {
        "ALLOWED_PATH": "/Users/yourname/projects/my-project",
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo"
      }
    }
  }
}

步骤3： 替换 /Users/yourname/projects/my-project 根据您的实际项目路径。

步骤4： 重新启动克劳德桌面。

步骤5： 通过提问进行测试： *“有哪些命令可用？”*

🔒 重要：默认命令(ls,cat,pwd,echo)是只读和安全的。添加更强大的命令，如 npm, git，或 python，请仔细考虑安全影响——它们可能允许LLM读取敏感数据、修改文件或执行任意代码。

其他MCP客户端

对于其他MCP客户端，使用相同的配置格式。关键点：

命令: npx
参数: ["-y", "safe-commander-mcp"]
环境：设置 ALLOWED_PATH 并且可选 ALLOWED_COMMANDS

真实世界的例子

⚠️ 安全第一：以下所有示例都添加了安全默认值之外的命令。每增加一个命令都会增加LLM功能，但也会增加数据暴露或未经授权操作的风险。

用于Web开发

"ALLOWED_PATH": "/Users/yourname/projects/my-web-app"
"ALLOWED_COMMANDS": "ls,cat,pwd,echo,npm,git"

风险: npm 可以安装软件包并运行脚本。 git 可以访问存储库历史记录，包括提交消息、作者信息、文件更改和分支数据。

Python开发

"ALLOWED_PATH": "/Users/yourname/projects/my-python-app"
"ALLOWED_COMMANDS": "ls,cat,pwd,echo,python,pip,git"

风险: python 可以执行任意代码并访问任何文件。 pip 可以安装软件包。

⚠️ 安全说明: ALLOWED_COMMANDS 可以自定义以包含您需要的任何命令，但是 仔细审查每个命令 在添加之前。更强大的命令可以提供更强大的LLM协助，但也会带来更大的安全风险。 LLM是主要威胁 -它可能会尝试读取敏感文件、访问凭据或执行未经授权的操作。

用于全栈开发

"ALLOWED_PATH": "/Users/yourname/projects"
"ALLOWED_COMMANDS": "ls,cat,pwd,echo,npm,git,python,docker"

风险：此配置允许大量系统访问。 docker 可以访问容器，并可能访问整个系统。

🔒 安全提醒：此示例包括可以访问敏感数据、修改系统或执行任意代码的强大命令。只有在您完全信任LLM并理解其含义的情况下才能使用。

在主MCP配置中使用这些环境变量值，如 Claude桌面设置上面的部分。

替代安装方法

如果您更喜欢全局安装

如果你想先全局安装（可选）：

npm install -g safe-commander-mcp

然后使用 "command": "safe-commander-mcp" 而不是MCP配置中的npx方法。

发展/贡献

如果您想为Safe Commander MCP做出贡献或开发新功能：

# Clone the repository
git clone https://github.com/nonameb3/safe-commander-mcp.git
cd safe-commander-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode (with file watching)
npm run dev

# Run tests
npm test

# Check TypeScript types
npm run lint

此设置允许您在向项目贡献之前修改源代码并在本地测试更改。

使用示例

智能命令发现（新！）

Claude现在可以主动发现和建议命令，而无需猜测：

"What commands are available in this project?"
"Show me the available package management commands"
"List all development tools I can use here"
"What are my options for version control operations?"

这 list_available_commands 该工具提供：

命令类别：按类型组织（包管理、版本控制、文件操作等）
详细说明：解释每个命令的作用
配置信息：当前工作目录、资源限制和超时
使用统计：命令计数和类别摘要

基本命令执行

配置后，您可以要求您的AI助手运行命令：

"Run npm install in the project directory"
"Show me the git status"
"List the files in the current directory"
"Run the build script with npm run build"

安全命令

默认情况下，为了安全起见，包含以下命令：

ls -目录列表（只读）
cat -文件内容读取（只读）
pwd -当前目录（只读）
echo -显示文本（安全输出）

您可能添加的其他命令（首先了解风险）：

git -版本控制操作（可以访问存储库历史记录，包括提交消息、作者信息、文件更改和分支数据）
npm -包管理（可以安装包和运行脚本）
python -脚本执行（可以执行任意代码并访问任何文件）
node -JavaScript执行（可以绕过所有安全保护）

🚨 LLM风险警告：请记住，LLM本身是主要的安全问题。即使有“安全”命令，LLM也可能：

使用 cat 读取敏感文件，如 .env, config.json，私钥
使用 ls 发现私有代码库的结构
组合多个命令以提取敏感信息

始终确保您的 ALLOWED_PATH 指向一个不包含您不希望LLM访问的敏感数据的目录。

自定义命令配置

您可以根据特定需求自定义允许的命令，但请务必仔细查看每个命令：

{
  "env": {
    "ALLOWED_PATH": "/path/to/project",
    "ALLOWED_COMMANDS": "ls,cat,pwd,echo,npm,git"
  }
}

🛡️ 指挥部选择安全指南：

从默认值开始：从安全默认值开始(ls,cat,pwd,echo)
增量添加：仅在特定任务需要时添加新命令
了解LLM风险：LLM是主要威胁-它可能试图访问敏感数据
定期审查：定期审核命令列表并删除未使用的命令
最小权限原则：只授予所需的最低访问权限
数据保护重点：考虑LLM可以通过每个命令访问哪些敏感数据

常见的命令类别及其风险等级：

最小风险: ls, cat, pwd, echo -只读文件操作（但仍可能暴露敏感文件内容）
中等风险: git -版本控制，可访问存储库历史记录，包括提交消息、作者信息、文件更改和分支数据
高风险: npm, pip -可以安装软件和运行脚本的包管理器
重大风险: node, python, bash, sh - 可以绕过所有安全措施 并执行任意系统命令

安全功能

🎯 主要安全目标：保护您的数据免受LLM和第三方的攻击

Safe Commander MCP旨在防止未经授权访问您的敏感代码库、文件和数据。 主要的威胁是LLM本身 -它可能试图：

读取敏感文件（凭据、私钥、源代码）
访问机密业务数据
执行未经授权的操作
将数据泄露给第三方

⚠️ 关键安全考虑因素

重要提示：命令执行绕过漏洞

某些命令可以通过在内部执行其他命令来绕过白名单保护：

node：可以通过执行任何系统命令 child_process 模块

  # This bypasses all protections:
  node -e 'require("child_process").execSync("rm -rf /important/data")'

python：可以通过以下方式执行系统命令 os.system() 或 subprocess
bash/sh：直接外壳访问绕过所有保护
npm：可以运行执行任意命令的脚本

推荐：仅包括 node 或 python 如果你完全信任LLM并了解其中的风险。为了获得最大的安全性，请仅使用只读命令，如 ls, cat, pwd.

命令验证

仅限白名单：只能执行预先批准的命令
字符净化：危险人物(; & | \ $（）{}\[\]\<>\`）被阻止
路径验证：防止目录遍历攻击
长度限制：命令限制为1000个字符

备注：字符净化对具有内置执行功能的命令提供了有限的保护，例如 node 或 python.

资源限制

执行超时：每条命令最多30秒
输出大小限制：最大输出1MB
并发命令：最多同时执行3次
速率限制：相同命令之间的1秒冷却时间

目录限制

所有命令都在配置的 ALLOWED_PATH 目录，防止访问敏感的系统区域。

🔍 快速安全检查

在将任何命令添加到白名单之前，问问自己：

此命令可以读取我不希望LLM看到的文件吗？
此命令可以执行其他命令或脚本吗？
如果LLM运行此命令，可能发生的最糟糕的事情是什么？
我是否信任LLM可以访问我的系统？

记住：法学硕士很好奇，会探索。只授予您对它的发现感到满意的访问权限。

api参考

可用工具

`list_available_commands` 新

通过智能分类和描述发现可用命令。

参数：

无需

答复：

工作目录：当前 ALLOWED_PATH 配置
命令类别：按类型组织的命令（包管理、版本控制、文件操作等）
命令说明：详细解释每个命令的目的
配置：资源限制、超时和系统设置
统计：命令计数和类别摘要

例子：

{
  "name": "list_available_commands",
  "arguments": {}
}

样本响应：

{
  "workingDirectory": "/path/to/project",
  "totalCommands": 6,
  "categories": {
    "packageManagement": ["npm"],
    "versionControl": ["git"],
    "fileOperations": ["ls", "cat", "pwd"],
    "runtime": ["node"]
  },
  "commandDescriptions": {
    "npm": "Node.js package manager - install, update, and manage dependencies",
    "git": "Version control system - track changes and collaborate on code"
  },
  "configuration": {
    "maxCommandLength": 1000,
    "commandTimeout": "30000ms",
    "maxConcurrentCommands": 3
  }
}

`run_command`

执行配置目录中的白名单命令。

参数：

command （string，必填）：要执行的命令

答复：

执行输出（stdout/stderr）
执行时间
错误详细信息（如适用）

例子：

{
  "name": "run_command",
  "arguments": {
    "command": "npm run build"
  }
}

发展

先决条件

Node.js 18+
TypeScript 5.8+
Yarn或npm

设置

git clone https://github.com/nonameb3/safe-commander-mcp.git
cd safe-commander-mcp
yarn install

开发脚本

# Run in development mode
yarn dev

# Build for production
yarn build

# Run built version
yarn start

# Type checking
npx tsc --noEmit

# Run with MCP inspector for debugging
yarn start:mcp

测试配置

为了进行测试，请使用安全目录：

export ALLOWED_PATH="/tmp/safe-test-dir"
export ALLOWED_COMMANDS="ls,cat,pwd,echo"
yarn dev

故障排除

常见问题

错误：“ALLOWED_PATH目录不存在”

确保路径存在且可访问
使用绝对路径保证可靠性

错误：“命令包含潜在危险字符”

为了安全起见，该命令包含被阻止的字符
查看注射尝试命令

错误：“命令不在允许列表中”

将命令添加到 ALLOWED_COMMANDS 环境变量
确保列表中逗号分隔正确
使用 list_available_commands 查看可用内容的工具（v1.1.0+）

MCP客户端中的JSON解析错误

确保没有 console.log() 用法（输出到stdout）
所有日志记录都通过stderr log() 函数

新功能（v1.1.0+）

命令发现：使用 list_available_commands 工具用于：

查看按类别组织的所有可用命令
获取每个命令的详细说明
查看当前配置和资源限制
了解工作目录和安全设置

这消除了猜测，使克劳德能够提供更智能的帮助。

贡献

我们欢迎捐款！请查看我们的贡献指南了解详情。

报告问题

请使用报告错误或请求功能的页面。

拉取请求

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

安全

该项目优先考虑安全性。如果您发现安全漏洞，请发送电子邮件至roonnapai.dev@gmail.com而不是使用问题跟踪器。

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

更新日志

看更改日志.md 查看版本历史和更新。

致谢

内置于模型上下文协议SDK
受安全AI驱动开发工具需求的启发
感谢开源社区的持续反馈和改进

Safe Commander MCP

快速接入

详细介绍