MCP 服务器

MCP Command Server

MCP 命令服务器提供了一个安全的、容器化的接口，用于远程命令执行，它具有内置的基于模式的安全验证、全面的 API 文档以及企业级的部署配置。

copyleftdev

开发者工具

访问服务器

README

MCP 命令服务器

用于远程命令执行的安全 JSON-RPC API

<p align="center"> MCP 命令服务器提供了一个安全的、容器化的接口，用于远程命令执行，具有内置的基于模式的安全验证、全面的 API 文档和企业级部署配置。 </p>

</div>

📋 目录

🔍 概述
✨ 功能特性
🏗️ 架构
🚀 安装
🧰 使用
📚 API 文档
🔒 安全性
💻 开发
🧪 测试
👥 贡献
📄 许可证

🔍 概述

MCP 命令服务器提供了一个符合 JSON-RPC 2.0 标准的 API，用于在服务器上执行 shell 命令。它的设计考虑了安全性，具有命令模式排除功能，以防止潜在的有害操作。该服务器完全容器化，使用 Docker，并包含可通过 API 直接访问的全面 API 文档。

✨ 功能特性

JSON-RPC 2.0 API: 用于命令执行的标准化接口
命令安全性: 基于模式的命令过滤，以阻止潜在的有害操作
自文档化: 内置的 /context 端点，提供 markdown 文档
容器化: 即用型 Docker 配置
生产就绪: 以安全为中心的设计，采用非 root 用户执行
开发者友好: 完整的 Postman 集合，用于测试

🏗️ 架构

flowchart TB
    Client[客户端] -->|HTTP POST JSON-RPC| Server[MCP 命令服务器]
    Client -->|HTTP GET| Context["/context 文档"]
    
    subgraph Server["MCP 命令服务器 (端口 3030)"]
        API[JSON-RPC API] --> Validator[命令验证器]
        Validator -->|如果安全| Executor[命令执行器]
        Validator -->|如果不安全| Reject[拒绝命令]
        Context
    end
    
    Validator --> ExcludeYAML[exclude.yaml]
    Context --> ContextMD[.context]
    
    Executor -->|执行| Shell[Shell]
    Shell --> Results[命令结果]
    Results --> API
    
    classDef container fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
    classDef component fill:#fff,stroke:#000,stroke-width:1px,color:#000;
    classDef config fill:#f9f,stroke:#333,stroke-width:1px,color:#333;
    
    class Server,Shell container;
    class API,Validator,Executor,Context,Reject,Results component;
    class ExcludeYAML,ContextMD config;

组件流程

sequenceDiagram
    participant Client as 客户端
    participant Server as MCP 命令服务器
    participant Validator as 验证器
    participant Executor as 执行器
    participant Shell as Shell
    
    Client->>Server: POST / {JSON-RPC 请求}
    Server->>Validator: 验证命令
    
    alt 命令匹配排除模式
        Validator->>Server: 拒绝 (安全违规)
        Server->>Client: 错误响应
    else 命令安全
        Validator->>Executor: 执行命令
        Executor->>Shell: 运行 shell 命令
        Shell->>Executor: 命令输出
        Executor->>Server: 处理结果
        Server->>Client: JSON-RPC 响应
    end
    
    Client->>Server: GET /context
    Server->>Client: Markdown 文档

🚀 安装

前提条件

Docker 和 Docker Compose
Git (用于克隆存储库)

使用 Docker (推荐)

克隆存储库:

git clone https://github.com/yourusername/mcp_command_server.git
cd mcp_command_server

使用 Docker Compose 启动服务器:
```
docker-compose up -d
```
服务器将在 http://localhost:3030 上可用

从源代码构建

确保已安装 Rust (建议 1.74+):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

克隆并构建项目:

git clone https://github.com/yourusername/mcp_command_server.git
cd mcp_command_server
cargo build --release

运行服务器:
```
./target/release/mcp_command_server
```

🧰 使用

基本命令

执行一个简单的命令:

curl -X POST -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "command/get",
  "params": {
    "command": "echo \"Hello World\""
  }
}' http://localhost:3030/

响应:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "stdout": "Hello World\n"
  }
}

访问 API 文档

获取 markdown 格式的 API 文档:

curl http://localhost:3030/context

📚 API 文档

MCP 命令服务器通过 /context 端点提供全面的文档。此文档以 markdown 格式提供，包括:

API 概述
可用方法
请求/响应格式
错误代码
使用示例
安全注意事项

JSON-RPC 规范

该 API 遵循 JSON-RPC 2.0 规范:

端点: http://localhost:3030/
方法: POST
Content-Type: application/json
Body 格式:

{
  "jsonrpc": "2.0",
  "id": "<unique_id>",
  "method": "command/get",
  "params": {
    "command": "<shell_command>"
  }
}

可用方法

方法	描述	参数
`command/get`	执行 shell 命令	`command`: string

响应格式

成功响应:

{
  "jsonrpc": "2.0",
  "id": "<request_id>",
  "result": {
    "stdout": "<command_output>"
  }
}

错误响应:

{
  "jsonrpc": "2.0",
  "id": "<request_id>",
  "error": {
    "code": "<error_code>",
    "message": "<error_message>"
  }
}

错误代码

代码	消息	描述
-32602	缺少 'command' 参数	未提供必需的 'command' 参数
-32000	命令执行错误	无法执行命令或命令被拒绝
-32601	方法未找到	指定的方法不存在

🔒 安全性

MCP 命令服务器实现了多种安全措施:

命令排除系统

服务器使用基于模式的排除系统来防止执行潜在的有害命令。这通过 exclude.yaml 文件进行配置，该文件包含:

纯文本模式 (例如, rm -rf, sudo, apt)
正则表达式模式 (例如, regex:.*\.\.\/.*)
用于区分大小写和匹配行为的选项

flowchart LR
    Command[命令输入] --> Validator[命令验证器]
    ExcludeYAML[exclude.yaml] --> Validator
    
    Validator --> Check{安全?}
    Check -->|是| Execute[执行命令]
    Check -->|否| Reject[拒绝并报错]
    
    subgraph Patterns[模式]
        Plain[纯文本模式]
        Regex[正则表达式模式]
    end
    
    ExcludeYAML --> Patterns

阻止的命令类别

命令排除系统阻止了几类潜在的有害命令:

系统修改 (apt, yum 等)
文件删除/修改 (rm -rf 等)
系统控制 (shutdown, reboot 等)
用户/权限更改 (chmod, sudo 等)
网络操作 (wget, curl 等)
命令链接以绕过过滤器 (&&, | 等)
脚本执行 (bash, python 等)
文件系统遍历 (../ 等)

Docker 安全性

服务器在 Docker 容器中以非 root 用户身份运行，以限制安全漏洞可能造成的潜在损害。

💻 开发

项目结构

mcp_command_server/
├── .context                 # API 文档 markdown
├── Cargo.toml               # Rust 依赖项
├── Dockerfile               # 多阶段 Docker 构建
├── exclude.yaml             # 命令排除模式
├── docker-compose.yml       # Docker Compose 配置
├── src/
│   ├── main.rs              # 主服务器代码
│   ├── command.rs           # 命令执行逻辑
│   ├── rpc.rs               # JSON-RPC 处理
│   └── validator.rs         # 命令验证逻辑
└── docs/
    ├── README.md            # Postman 集合的文档
    └── mcp_command_server.postman_collection.json  # Postman 集合

依赖项

Rust: 主要编程语言
tokio: Rust 的异步运行时
warp: Web 服务器框架
serde & serde_json: 序列化/反序列化
serde_yaml: 用于排除模式的 YAML 解析
regex: 用于命令验证的正则表达式支持

🧪 测试

使用 Postman 集合

docs/ 目录中包含一个全面的 Postman 集合，用于测试 API:

将 docs/mcp_command_server.postman_collection.json 导入到 Postman
运行单个请求或整个集合
该集合包括以下测试:
- 基本命令
- 错误处理
- 命令执行
- 文件操作
- 安全验证

手动测试

使用 curl 测试基本功能:

# 测试 context 端点
curl http://localhost:3030/context

# 执行一个简单的命令
curl -X POST -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "command/get",
  "params": {
    "command": "echo \"Hello World\""
  }
}' http://localhost:3030/

👥 贡献

欢迎贡献! 请随时提交 Pull Request。

Fork 存储库
创建您的功能分支 (git checkout -b feature/amazing-feature)
提交您的更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开一个 Pull Request

📄 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

使用 Rust 和 Docker 构建 ❤️。