MCP命令服务器

Name: MCP命令服务器
Author: copyleftdev

作者：copyleftdev2 星标更新：2025-09-24

项目介绍

 <div align="center">

MCP 命令服务器

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

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT 许可证"></a> <a href="https://www.rust-lang.org/"><img src="https://img.shields.io/badge/使用-Rust-orange" alt="使用 Rust"></a> <a href="docker-compose.yml"><img src="https://img.shields.io/badge/Docker-准备就绪-blue" alt="Docker"></a> <a href="https://www.jsonrpc.org/specification"><img src="https://img.shields.io/badge/API-JSON--RPC%202.0-lightgrey" alt="JSON-RPC"></a> </p> <p align="center"> MCP 命令服务器提供了一个安全、容器化的接口用于远程命令执行，内置模式匹配的安全验证机制，全面的API文档以及企业级部署配置。 </p> </div>

🔍 概览

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

✨ 特性

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

🏗️ 架构

flowchart TB
    客户端[客户端] -->|HTTP POST JSON-RPC| 服务器[MCP 命令服务器]
    客户端 -->|HTTP GET| 上下文["/context" 文档]
    
    subgraph 服务器["MCP 命令服务器 (端口 3030)"]
        API[JSON-RPC API] --> 验证器[命令验证器]
        验证器 -->|如果安全| 执行器[命令执行器]
        验证器 -->|如果不安全| 拒绝[拒绝命令]
        上下文
    end
    
    验证器 --> 排除YAML[exclude.yaml]
    上下文 --> 上下文MD[.context]
    
    执行器 -->|执行| Shell[Shell]
    Shell --> 结果[命令结果]
    结果 --> 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 服务器,Shell container;
    class API,验证器,执行器,上下文,拒绝,结果 component;
    class 排除YAML,上下文MD config;

组件流程

sequenceDiagram
    参与者 客户端
    参与者 服务器 as MCP 命令服务器
    参与者 验证器
    参与者 执行器
    参与者 Shell
    
    客户端->>服务器: POST / {JSON-RPC 请求}
    服务器->>验证器: 验证命令
    
    alt 命令匹配排除模式
        验证器->>服务器: 拒绝 (安全违规)
        服务器->>客户端: 错误响应
    else 命令是安全的
        验证器->>执行器: 执行命令
        执行器->>Shell: 运行 shell 命令
        Shell->>执行器: 命令输出
        执行器->>服务器: 处理结果
        服务器->>客户端: JSON-RPC 响应
    end
    
    客户端->>服务器: GET /context
    服务器->>客户端: 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 文档

获取 API 文档的 Markdown 格式：

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
请求体格式:

{
  "jsonrpc": "2.0",
  "id": "<唯一ID>",
  "method": "command/get",
  "params": {
    "command": "<shell命令>"
  }
}

可用方法

方法	描述	参数
`command/get`	执行一个 shell 命令	`command`: 字符串

响应格式

成功响应:

{
  "jsonrpc": "2.0",
  "id": "<请求ID>",
  "result": {
    "stdout": "<命令输出>"
  }
}

错误响应:

{
  "jsonrpc": "2.0",
  "id": "<请求ID>",
  "error": {
    "code": "<错误码>",
    "message": "<错误消息>"
  }
}

错误码

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

🔒 安全

🚨 安全更新: 版本 0.1.1 修复了一个关键的空格注入漏洞 (CVE-2024-XXXX)，该漏洞允许绕过命令过滤器。所有用户应立即更新。

MCP 命令服务器实现了多个安全措施：

命令排除系统

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

纯文本模式（例如：rm -rf，sudo，apt）
正则表达式模式（例如：regex:.*\.\.\/.*）
对大小写敏感性和匹配行为的选项

flowchart LR
    命令[命令输入] --> 验证器[命令验证器]
    排除YAML[exclude.yaml] --> 验证器
    
    验证器 --> 检查{安全？}
    检查 -->|是| 执行[执行命令]
    检查 -->|否| 拒绝[拒绝并报错]
    
    subgraph 模式
        纯文本[纯文本模式]
        正则[正则表达式模式]
    end
    
    排除YAML --> 模式

阻止的命令类别

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

系统修改 (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。

分叉仓库
创建你的功能分支 (git checkout -b feature/amazing-feature)
提交你的更改 (git commit -m '添加一些精彩的功能')
推送到分支 (git push origin feature/amazing-feature)
打开 Pull Request

📄 许可证

此项目根据 MIT 许可证发布 - 查看 LICENSE 文件了解详情。

使用 Rust 和 Docker 制作 ❤️