# openEuler MCP Toolkit

面向 openEuler/Linux 的只读系统观测与操作系统算法实验 MCP Server。它把内存、文件系统、进程与 CPU 信息封装为类型化工具，让支持 MCP 的大模型客户端能够调用可靠、可测试、结果规模受控的系统能力。

> 这个仓库是 MCP Server，不内置大模型。工具选择和自然语言解释由连接它的 MCP 客户端完成。

## 项目特点

- 12 个正式工具，覆盖内存、文件系统、进程和 CPU 调度。
- 实时系统观测与算法仿真采用独立模块和输出类型。
- Pydantic 输入输出模型，由 MCP 自动生成并校验 Schema。
- 文件工具受允许目录限制；不提供删除文件、结束进程等写操作。
- 长时间采样支持取消和进度通知。
- 纯算法测试、系统服务测试和真实 stdio MCP 协议测试。
- 20 条自然语言评测任务，不绑定模型厂商或 API Key。

## 工具列表

| 模块 | 工具 | 类型 | 说明 |
|---|---|---|---|
| 内存 | `get_memory_info` | 实时观测 | RAM、Swap 和 `/proc/meminfo` |
| 内存 | `get_process_memory` | 实时观测 | 进程 RSS、VMS 和前 N 项内存映射 |
| 内存 | `sample_memory_trend` | 实时观测 | 有界时间窗口内的内存趋势 |
| 内存 | `simulate_page_replacement` | 算法仿真 | FIFO、LRU、CLOCK、OPT |
| 文件系统 | `get_filesystem_info` | 实时观测 | 分区、容量和 inode |
| 文件系统 | `analyze_file_distribution` | 实时观测 | 受控目录内的文件分布 |
| 文件系统 | `monitor_file_metadata` | 实时观测 | 轮询文件大小和时间戳变化 |
| 文件系统 | `simulate_disk_allocation` | 算法仿真 | 连续、链式、索引分配 |
| 调度 | `get_process_tree` | 实时观测 | 有深度和节点上限的进程树 |
| 调度 | `monitor_context_switches` | 实时观测 | 系统或单进程上下文切换增量 |
| 调度 | `simulate_cpu_scheduling` | 算法仿真 | FCFS、SJF、RR、Priority |
| 调度 | `sample_cpu_time_ratios` | 实时观测 | CPU 各状态时间占比 |

## 快速开始

需要 Python 3.11 或 3.12。推荐在 openEuler/Linux 上运行；macOS 可运行算法和多数 psutil 工具，但没有 `/proc` 数据。

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

启动 stdio Server：

```bash
openeuler-mcp
```

stdio 是协议通道，直接运行后没有交互式提示属于正常现象。可以运行协议示例：

```bash
python examples/smoke_client.py
```

使用 MCP Inspector：

```bash
mcp dev src/openeuler_mcp/server.py
```

通用客户端配置见 [`examples/mcp-config.json`](examples/mcp-config.json)。请把命令改为虚拟环境中 `openeuler-mcp` 的绝对路径，并替换允许访问的目录。

## 文件访问安全

文件分析默认只能访问 Server 的启动目录。通过系统路径分隔符配置多个允许目录：

```bash
export OPENEULER_MCP_ALLOWED_ROOTS="/var/log:/home/user/safe-data"
```

- 工具拒绝允许目录以外的路径。
- 扫描时跳过符号链接。
- 不要授权包含私钥、浏览器配置、Cookie 或其他敏感数据的目录。
- MCP 客户端可能将工具结果发送给所配置的模型服务，请同时检查客户端的数据策略。

## 三条演示链路

### 1. 系统内存检查

> 查看当前内存和交换区使用情况，并说明数据来源。

客户端应调用 `get_memory_info`，然后区分 psutil 数据与 Linux `/proc/meminfo` 数据。

### 2. 进程内存分析

> 分析 PID 1234 的内存占用，只列出 RSS 最大的 10 项映射。

客户端应调用 `get_process_memory(pid=1234, mapping_limit=10)`。进程不存在或无权限时，调用应明确失败而不是返回伪造结果。

### 3. 调度算法对比

> 对任务 A(到达0、运行4) 和 B(到达0、运行2) 使用时间片1的 RR 调度，解释等待时间。

客户端应调用 `simulate_cpu_scheduling`。正确结果中 A、B 的累计等待时间都为 2。

更多示例见 [`docs/demo.md`](docs/demo.md)。

## 测试

```bash
ruff check .
pytest --cov=openeuler_mcp --cov-report=term-missing
```

测试覆盖页面置换、RR 累计等待时间、磁盘分配回滚、路径边界、当前系统服务，以及 MCP Server 的 12 个工具注册、Schema 和结构化调用。

## 评测

[`evaluation/cases.jsonl`](evaluation/cases.jsonl) 包含 20 条任务，其中两条用于验证模型不会选择不存在的危险写工具。把客户端调用轨迹整理为 `result.example.jsonl` 的格式后运行：

```bash
python evaluation/evaluate_results.py evaluation/result.example.jsonl
```

输出工具选择正确率、参数有效率、调用成功率和任务完成率；各项指标根据输入的客户端调用轨迹计算。

## 文档

- [架构与数据流](docs/architecture.md)
- [工具接口与边界](docs/tools.md)
- [演示问题](docs/demo.md)
- [平台支持](docs/platform-support.md)
- [安全策略](SECURITY.md)

## 已知限制

- 仅提供本地 stdio transport，不包含远程 HTTP 和认证。
- 文件变化通过元数据轮询观察，快速发生并恢复的变化可能被漏掉。
- 进程和系统状态具有瞬时性，采集期间进程可能退出或权限可能变化。
- 磁盘分配和 CPU/页面调度仅计算模拟结果，不会修改真实操作系统状态。

## License

[MIT](LICENSE)