shell-ops-mcp 0.1.0
Shell Operations MCP Server - 系统运维操作工具集，提供系统监控、进程管理、网络诊断、日志分析等能力
Requires Python: >=3.10
Keywords: devops, diagnostics, fastmcp, mcp, monitoring, network, shell, system

# Shell Operations MCP Server

一个功能完整的 Shell 运维操作 MCP 服务器，基于 **FastMCP** + **uv** 构建，提供系统监控、进程管理、网络诊断、日志分析等能力。

> 📖 **[5 分钟快速开始](QUICKSTART.md)** | **[使用指南](USAGE.md)** | **[项目总结](PROJECT_SUMMARY.md)**

## 特性

- 🚀 **FastMCP 框架** - 简洁高效的 MCP 实现
- 📦 **uv 包管理** - 快速依赖管理和虚拟环境
- 🔒 **安全模式** - 内置安全机制，防止危险操作
- 📊 **跨平台监控** - 基于 psutil，支持 macOS/Linux/Windows
- 🛠️ **40+ 工具** - 涵盖系统监控、进程管理、网络诊断、日志分析等
- 🎯 **零配置** - 使用 uvx 无需安装即可运行
- 📝 **结构化输出** - 所有工具返回 JSON 格式，易于解析

## 功能模块

### 1. 系统资源监控
- `get_memory_info` - 内存使用情况（总量/已用/可用/缓存）
- `get_cpu_load` - CPU 负载（1/5/15分钟平均值）
- `get_disk_usage` - 磁盘使用率（所有挂载点）
- `get_io_stats` - I/O 统计信息
- `get_system_uptime` - 系统运行时间

### 2. 进程管理
- `list_processes` - 列出进程（支持过滤）
- `get_process_info` - 获取进程详细信息
- `get_process_files` - 查看进程打开的文件
- `kill_process` - 终止进程（需确认）
- `get_top_processes` - 获取资源占用 TOP N 进程

### 3. 网络诊断
- `check_port_listening` - 检查端口监听状态
- `test_connectivity` - 测试网络连通性（ping/curl）
- `dns_lookup` - DNS 解析查询
- `get_network_stats` - 网络流量统计
- `test_tls_connection` - TLS/SSL 握手测试

### 4. 文件与目录操作
- `get_file_info` - 文件详细信息（大小/权限/时间）
- `get_directory_size` - 目录大小统计
- `calculate_file_hash` - 文件哈希校验（md5/sha256）
- `search_files` - 文件搜索（支持正则）
- `get_file_permissions` - 查看文件权限和 ACL

### 5. 环境变量管理
- `get_env_var` - 读取环境变量
- `set_env_var` - 设置环境变量（会话级）
- `list_env_vars` - 列出所有环境变量
- `export_env_to_file` - 导出环境变量到文件

### 6. 日志与文本处理
- `tail_log` - 实时查看日志尾部
- `grep_log` - 日志关键字搜索
- `count_pattern` - 统计模式匹配次数
- `extract_log_slice` - 提取日志片段（按行号/时间）
- `parse_json_log` - 解析 JSON 格式日志

### 7. 服务与包管理
- `check_service_status` - 检查服务状态（systemd/launchd）
- `list_installed_packages` - 列出已安装包
- `check_docker_status` - Docker 容器状态
- `get_package_version` - 查询包版本

### 8. 健康检查与探针
- `http_health_check` - HTTP 健康检查
- `database_health_check` - 数据库连接测试
- `system_health_report` - 系统综合健康报告
- `custom_health_script` - 执行自定义健康检查脚本

### 9. 配置与部署
- `generate_config_file` - 生成配置文件模板
- `compress_directory` - 压缩目录
- `extract_archive` - 解压文件
- `cleanup_temp_files` - 清理临时文件

### 10. 安全与审计
- `check_open_ports` - 扫描开放端口
- `get_failed_login_attempts` - 获取失败登录记录
- `check_file_integrity` - 文件完整性检查
- `audit_user_permissions` - 审计用户权限

## 快速开始

### 1. 安装 uv（如果还没有）

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 Homebrew
brew install uv
```

### 2. 安装依赖

```bash
cd python/shell_ops_mcp
uv sync
```

### 3. 本地测试

```bash
# 直接运行测试
uv run python test_local.py

# 或进入虚拟环境
uv run shell-ops-mcp
```

## MCP 配置

在 Kiro 的 `.kiro/settings/mcp.json` 中添加：

### 方式 1: 使用 uvx（推荐，无需安装）

```json
{
  "mcpServers": {
    "shell-ops": {
      "command": "uvx",
      "args": [
        "--from",
        "/Users/你的用户名/项目路径/python/shell_ops_mcp",
        "shell-ops-mcp"
      ],
      "env": {
        "SHELL_OPS_SAFE_MODE": "true",
        "SHELL_OPS_TIMEOUT": "30",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": [
        "get_memory_info",
        "get_cpu_load",
        "get_system_info",
        "get_disk_usage",
        "list_env_vars"
      ]
    }
  }
}
```

### 方式 2: 使用 uv run

```json
{
  "mcpServers": {
    "shell-ops": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/你的用户名/项目路径/python/shell_ops_mcp",
        "shell-ops-mcp"
      ],
      "env": {
        "SHELL_OPS_SAFE_MODE": "true"
      }
    }
  }
}
```

## 安全特性

- 命令白名单机制
- 危险操作需要确认
- 资源使用限制（超时/内存）
- 审计日志记录
- 沙箱模式支持

## 使用示例

```python
# 获取系统健康报告
result = await mcp.call_tool("system_health_report")

# 检查端口
result = await mcp.call_tool("check_port_listening", {"port": 8080})

# 搜索日志
result = await mcp.call_tool("grep_log", {
    "file": "/var/log/app.log",
    "pattern": "ERROR",
    "lines": 50
})
```