使用说明

MCP外壳服务器

概述

MCP外壳服务器(safe_shell_mcp.py)是一个安全可靠的shell服务器，旨在管理具有流式输出、后台任务队列和交互式命令检测等高级功能的shell任务。它在构建时考虑了模块化、安全性和用户体验，使其成为开发人员和系统管理员的理想选择。

主要特点

流输出：执行具有实时流输出和进度更新的命令。
后台任务管理：将任务排队，以便在后台运行，并进行状态跟踪和输出检索。
交互式命令检测：检测需要用户输入的命令并提供警告。
安全执行：限制对指定安全根目录的访问。
跨平台兼容性：支持Linux、macOS和Windows（通过WSL）。

支持的操作系统

Linux：完全支持。
macOS：完全支持。
视窗：通过Windows Linux子系统（WSL）支持。

安装

克隆存储库：

git clone https://github.com/prabeer/shell_mcp_server.git

导航到项目目录：
```
cd shell_mcp_server
```
确保您的系统上安装了Python 3.8+。
安装所需的依赖项：
```
pip install -r requirements.txt
```

用法

启动服务器

使用以下命令运行MCP外壳服务器：

python3 safe_shell_mcp.py --saferoot /path/to/safe/root --debug

--saferoot：指定要限制访问的目录。
--debug：启用调试日志记录。

操作模式

流媒体模式: 通过实时输出流和进度更新执行命令。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_shell","arguments":{"command":"ls -la","stream":true}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

后台任务模式: 在后台运行命令，稍后检索其状态或输出。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_shell","arguments":{"command":"sleep 10","background":true}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

交互式命令检测: 检测需要用户输入的命令并提供警告。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_shell","arguments":{"command":"sudo apt update"}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

其他工具

列表目录:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_dir","arguments":{"path":"."}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

搜索文件:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"file_search","arguments":{"pattern":"*.py","root":"."}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

支持的命令

核心命令

运行Shell命令: 执行带有流式输出或后台执行选项的shell命令。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_shell","arguments":{"command":"ls -la","stream":true}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

运行原始命令: 无需额外处理即可执行shell命令。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_raw","arguments":{"command":"echo Hello World"}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_dir","arguments":{"path":"."}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

搜索文件: 搜索与模式匹配的文件。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"file_search","arguments":{"pattern":"*.py","root":"."}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

打印工作目录: 显示当前工作目录。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"print_workdir"}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

Grep文件: 在文件中搜索模式。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"grep_file","arguments":{"pattern":"def","filepath":"safe_shell_mcp.py"}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

cat文件: 显示文件的内容。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cat_file","arguments":{"filepath":"README.md"}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

Sed搜索: 使用执行搜索 sed.

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sed_search","arguments":{"script":"s/old/new/g","filepath":"README.md"}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

后台任务管理

任务状态: 获取后台任务的状态。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"task_status","arguments":{"task_id":"<task_id>"}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

任务输出: 检索后台任务的输出。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"task_output","arguments":{"task_id":"<task_id>","max_lines":10}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

任务清单: 列出所有后台任务。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"task_list"}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

任务终止: 终止后台任务。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"task_terminate","arguments":{"task_id":"<task_id>"}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

版本信息

版本: 显示服务器版本和构建信息。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version"}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root

后台和流媒体任务

后台任务

后台任务是为不需要立即用户交互的长时间运行操作而设计的。这些任务异步运行，允许用户在监视其进度的同时继续其他操作。

主要特点：

长时间运行的命令的异步执行。
状态跟踪 task_status.
输出检索 task_output.
1小时后自动清理已完成的任务。
优雅的终止与 task_terminate.

推荐使用案例：

训练机器学习模型。
大规模构建或部署。
数据处理任务。

默认超时：

后台任务的超时时间为 3600秒（1小时）.

有关更多详细信息，请参阅流媒体_食品有限公司文件。

流媒体任务

流任务为生成连续输出的命令提供实时反馈。此模式非常适合在执行过程中监控进度和接收更新。

主要特点：

实时输出流。
进度每10行或重要事件更新一次。
超时保护，防止挂起命令。
开始和完成状态消息。
经过的时间跟踪。

推荐使用案例：

构建流程。
包装安装。
持续监控任务。

默认超时：

流任务超时为 300秒（5分钟）.

有关更多详细信息，请参阅流媒体_食品有限公司文件。

兼容性

专为VS Code和GitHub Copilot设计：优化了与现代代码编辑器的无缝集成，实现了智能代码建议和简化的工作流程。
支持RFC JSON格式：确保工具和命令的结构化和标准化数据处理，使其与现代API和自动化系统兼容。
跨编辑器兼容性：与PyCharm、Sublime Text和Atom等其他流行编辑器无缝协作，确保开发人员的灵活性。

贡献

欢迎投稿！请分叉存储库，并提交一个包含您的更改的拉取请求。

许可证

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

联系

如有疑问或需要支持，请联系普拉比尔.

与VS Code和GitHub Copilot集成

向VS代码添加任务

要将MCP Shell Server与VS Code集成，您可以将任务添加到 tasks.json 您工作区中的文件。以下是一个示例配置：

在VS代码中打开命令面板(Ctrl+Shift+P 或 Cmd+Shift+P 在macOS上），然后选择 Tasks: Configure Task.
选择 Create tasks.json file from template 如果提示。
将以下任务添加到 tasks.json 文件：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "MCP Shell: List Directory",
      "type": "shell",
      "command": "echo",
      "args": [
        "'{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"list_dir\",\"arguments\":{\"path\":\".\"}}}}' | python3 safe_shell_mcp.py --saferoot /path/to/safe/root"
      ],
      "group": "build"
    },
    {
      "label": "MCP Shell: Run Command",
      "type": "shell",
      "command": "bash",
      "args": [
        "-c",
        "read -p 'Enter command: ' cmd && echo \"{\\\"jsonrpc\\\":\\\"2.0\\\",\\\"id\\\":1,\\\"method\\\":\\\"tools/call\\\",\\\"params\\\":{\\\"name\\\":\\\"run_shell\\\",\\\"arguments\\\":{\\\"command\\\":\\\"$cmd\\\"}}}}\" | python3 safe_shell_mcp.py --saferoot /path/to/safe/root"
      ],
      "group": "build"
    }
  ]
}

将MCP外壳服务器添加到VS代码设置

要在VS代码设置中配置MCP外壳服务器，您可以将以下代码段添加到您的 settings.json 文件：

"mcp": {
  "servers": {
    "shell_server": {
      "type": "stdio",
      "command": "python3",
      "args": [
        "<path_to_safe_shell_mcp.py>",
        "--saferoot",
        "<path_to_safe_root>",
        "--debug"
      ]
    }
  }
}

替换 <path_to_safe_shell_mcp.py> 通过绝对路径 safe_shell_mcp.py 文件和 <path_to_safe_root> 使用您要限制访问的目录。

将MCP Shell服务器添加到VS代码工作区

要为您的VS代码工作区配置MCP外壳服务器，您可以将以下代码段添加到 .vscode/settings.json 文件：

{
  "mcp": {
    "servers": {
      "shell_server": {
        "type": "stdio",
        "command": "python3",
        "args": [
          "<path_to_safe_shell_mcp.py>",
          "--saferoot",
          "<path_to_safe_root>",
          "--debug"
        ]
      }
    }
  }
}

替换 <path_to_safe_shell_mcp.py> 通过绝对路径 safe_shell_mcp.py 文件和 <path_to_safe_root> 使用您要限制访问的目录。

使用GitHub Copilot

GitHub Copilot可以帮助编写和编辑MCP Shell Server的代码。要启用Copilot，请执行以下操作：

从VS代码市场安装GitHub Copilot扩展。
在VS Code中打开MCP Shell Server项目。
开始键入命令或代码片段，Copilot将提供智能建议。
使用Copilot生成JSON-RPC命令、调试脚本或编写文档。

有关更多详细信息，请参阅 GitHub副驾驶文档.