MCPShell

<p align="center"> <img src="docs/logo.png" alt="横幅" width="300"/> </p>

MCPShell 是一个工具，允许大型语言模型（LLMs）通过模型上下文协议（MCP）安全地执行命令行工具。它在LLMs和操作系统命令之间提供了一个安全的桥梁。

特性

• 灵活的命令执行：运行任何shell命令作为MCP工具，并通过模板进行参数替换。
• 基于配置的工具定义：使用YAML定义工具及其参数、约束和输出格式。
• 通过约束确保安全性：在执行前使用CEL表达式验证工具参数，以及可选的沙箱环境来运行命令。
• 快速原型化MCP工具：只需添加一些shell代码并将其用作您的LLM中的MCP工具。
• 简单集成：与支持MCP协议的任何LLM客户端兼容（例如，Cursor、VSCode、Witsy等）。

快速开始

假设您希望Cursor（或其他MCP客户端）帮助您解决硬盘空间问题。

1. 创建一个配置文件 /my/example.yaml 来定义您的工具：

   mcp:
     description: |
       分析磁盘使用情况以帮助识别占用空间的内容的工具。
     run:
       shell: bash
     tools:
       - name: "disk_usage"
         description: "检查目录的磁盘使用情况"
         params:
           directory:
             type: string
             description: "要分析的目录"
             required: true
           max_depth:
             type: number
             description: "分析的最大深度（1-3）"
             default: 2
         constraints:
           - "directory.startsWith('/')"  # 必须是绝对路径
           - "!directory.contains('..')"  # 防止目录遍历
           - "max_depth >= 1 && max_depth <= 3"  # 限制递归深度
           - "directory.matches('^[\\w\\s./\\-_]+$')"  # 只允许安全路径字符，防止命令注入
         run:
           command: |
             du -h --max-depth={{ .max_depth }} {{ .directory }} | sort -hr | head -20
         output:
           prefix: |
             磁盘使用分析（最大的20个目录）：
   

   查看示例目录以获取更多复杂且有用的示例。也许您更喜欢让LLM了解您的Kubernetes集群，使用kubectl？或者让它运行一些AWS CLI命令？

2. 在Cursor（或任何其他支持MCP的LLM客户端）中配置MCP服务器

   例如，对于Cursor，创建 .cursor/mcp.json 文件：

   {
       // 您需要有可用的"go"命令
       "mcpServers": {
           "mcp-cli-examples": {
               "command": "go",
               "args": [
                  "run", "github.com/inercia/MCPShell@v0.1.8",
                  "mcp", "--tools", "/my/example.yaml",
                  "--logfile", "/some/path/mcpshell/example.log"
               ]
           }
       }
   }
   

   您也可以使用相对路径并省略.yaml扩展名：

   {
       "mcpServers": {
           "mcp-cli-examples": {
               "command": "go",
               "args": [
                  "run", "github.com/inercia/MCPShell@v0.1.8",
                  "mcp", "--tools", "example",
                  "--logfile", "/some/path/mcpshell/example.log"
               ]
           }
       }
   }
   

   这将在工具目录（默认为~/.mcpshell/tools/）中查找example.yaml。

   查看如何配置Cursor或Visual Studio Code的详细信息。支持MCP的其他LLMs应以类似方式配置。

3. 确保您的MCP客户端已刷新（Cursor应在第一次自动识别，但配置文件中的任何更改都需要刷新）。

4. 向您的LLM询问一些它应该能够使用新工具回答的问题。例如：“我的硬盘空间不足了，你能帮我找到问题吗？”

使用和配置

查看此文档中的所有命令。

配置文件使用在此处定义的YAML格式：此处。查看此目录以获取一些示例。

有关容器部署指南，请参阅容器部署指南。

代理模式

MCPShell还可以在代理模式下运行，提供大型语言模型（LLMs）和您的命令行工具之间的直接连接，而无需单独的MCP客户端。在这种模式下，MCPShell连接到兼容OpenAI的API（包括本地LLMs如Ollama），使您的工具对模型可用，执行请求的工具操作，并管理对话流程。这使得可以创建专门的AI助手，能够自主执行您在配置中定义的系统任务。代理模式支持交互式对话和一次性执行，并允许您直接在配置文件中定义系统和用户提示。

有关使用代理模式的详细信息，请参阅代理模式文档。

安全注意事项

您可能会想：“这个AI已经帮助我找到了所有这些大文件。如果我再创建一个删除文件的工具呢？”不要这样做！

• 将这些工具的作用范围限制为只读操作，不要给LLM改变事物的能力。
• 使用约束来限制命令执行的安全参数。
• 考虑使用沙箱环境来运行命令。
• 审查所有命令模板以发现潜在的注入漏洞。
• 只公开适合外部使用的工具。
• 所有上述！

在使用本软件之前，请务必阅读安全注意事项文档。

贡献

欢迎贡献！请查看开发指南。请在GitHub上打开一个问题或提交一个拉取请求。

许可证

本项目根据MIT许可证发布 - 详情请参见LICENSE文件。