内容
# 系统管理员 MCP
<p align="center">
<a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a>
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.2-7c5cfc?style=flat-square" alt="FastMCP"></a>
</p>
> 📖 **[安装指南](INSTALL.md)** — 快速开始，手动设置，故障排除
**通过 AI 进行 Windows 系统管理。** 文件恢复，安全，磁盘维护，诊断，服务，进程 — 所有这些都可以通过 MCP（Claude Desktop，Cursor 等）和 React 网络仪表盘访问。
> **⚠️ 管理员权限要求。** 磁盘操作，服务管理，文件恢复和权限更改需要提升权限。请在启动服务器之前以管理员身份运行终端。
```json
# Claude Desktop — 右键单击 → 以管理员身份运行，然后：
"mcpServers": { "system-admin-mcp": { "command": "uvx", "args": ["system-admin-mcp"] } }
```
---
## 快速开始
```powershell
git clone https://github.com/sandraschi/system-admin-mcp
cd system-admin-mcp
just
```
这将打开一个交互式仪表盘，显示所有可用的命令。运行 `just bootstrap` 安装依赖项，然后运行 `just serve` 或 `just dev` 启动。
### 手动设置
如果您没有安装 `just`：
# 首先以管理员身份运行终端，然后：
uvx system-admin-mcp
请参阅 [快速入门](docs/quickstart.md) 以完成设置。
## 您能做的事情
| 领域 | 操作 |
|------|-----------|
| **系统健康** | CPU/RAM/磁盘指标，事件日志，硬件库存，已安装软件 |
| **文件恢复** | 扫描 NTFS MFT，恢复已删除的文件，验证完整性 |
| **安全** | 查看/设置/审计 NTFS 权限，获取所有权，网络端口审计 |
| **磁盘** | SMART 健康，碎片整理（HDD），TRIM（SSD），清理，文件夹大小分析 |
| **服务** | 列出/启动/停止，更改启动类型，分页 |
| **进程** | 列出/排序/分析/终止，分页，可按 CPU/内存/名称/PID 排序 |
| **启动和任务栏** | 管理启动程序，切换自动隐藏，查找阻止程序 |
| **代理** | 让 AI 自动诊断和修复问题（SEP-1577 采样） |
所有操作都通过单个 `system_admin` 工具进行 — 一个工具，40 多个操作。
---
## FastMCP 3.2 功能
| 功能 | 提供内容 |
|---------|-----------------|
| **`ctx.sample()`** （SEP-1577） | 用于自主诊断的服务器端 LLM 调用。工具 `agentic_system_workflow` 和 `autonomous_system_troubleshooter` 使用 `ctx.sample()` 来协调多步骤诊断，无需客户端往返 — 服务器借用客户端 LLM 来解释系统数据并建议操作。 |
| **提示** （4 个模板） | 通过 `@mcp.prompt()` 注册：`system_diagnostics_expert`，`security_hardening_expert`，`system_troubleshooter`，`volume_maintenance_expert`。每个都有参数化焦点模式（例如性能与事件，所有权与审计）。客户端将它们作为系统指令注入。 |
| **技能** (`skill://`) | `SkillsDirectoryProvider` 公开 `skill://system-admin-expert/SKILL.md` — 一个便携式专业知识文档，包含安全模式模式，诊断序列和 SEP-1577 工作流程配方。可通过 `resources/list` 发现。 |
| **预制 UI** （4 张卡片） | `@mcp.tool(app=True)` 工具返回具有 `structured_content=PrefabApp(...)` 的 `ToolResult`：`system_health_card` （CPU/RAM/磁盘），`top_processes_card` （按 CPU/内存排序），`list_services_card` （过滤服务），`volume_status_card` （所有卷与条形图）。由具备能力的宿主（Claude Desktop 边栏）原生渲染。 |
| **代码模式** | 用于代理工具选择的 BM25 发现。通过 `--agentic` 标志启用。 |
| **SkillsDirectoryProvider** | 从 `skills/` 目录注册 `skill://` 资源。 |
| **双重传输** | stdio （Claude Desktop 默认）+ 可流式传输的 http (`MCP_TRANSPORT=http`) 。 |
---
## 网络仪表盘
一个 14 页的 React 单页应用，运行在端口 **10860** （前端）/ **10861** （后端）：
```powershell
just web # 后端 API
just web-frontend # 前端开发服务器
```
页面：仪表盘，状态，进程（分页，可排序），服务（分页），卷，文件所有者，文件恢复，日志，工具，应用，提升，聊天，设置，帮助。
---
## Justfile 命令
| 命令 | 执行操作 |
|---------|-------------|
| `just dev` | 启动 MCP 服务器（Claude Desktop） |
| `just serve` | 通过 HTTP 启动 MCP |
| `just test` | 运行测试 |
| `just lint` | 检查代码质量（ruff + biome） |
| `just fix` | 自动修复所有问题 |
| `just mcpb-pack` | 构建 MCPB 包 |
| `just build` | 安装依赖项 |
| `just web` | 在 10861 上启动 FastAPI 后端 |
| `just web-frontend` | 在 10860 上启动 Vite 前端 |
---
## 项目地图
```
├── AGENTS.md # AI 代理说明
├── justfile # 任务运行器（SOTA 工业仪表盘）
├── pyproject.toml # Python 项目配置（FastMCP 3.2）
├── src/system_admin_mcp/
│ ├── app.py # FastMCP 实例 + 生命周期（技能，预制）
│ ├── server.py # FastAPI 后端（20 多个 REST 端点）
│ ├── transport.py # stdio / 可流式传输的 http 双重传输
│ ├── prompts.py # 4 个 `@mcp.prompt()` 模板
│ ├── tools/
│ │ ├── portmanteau.py # system_admin （40 多个操作调度器）
│ │ ├── implementations.py # 文件恢复，ACL，磁盘，WMI
│ │ ├── services_and_tasks.py # 服务，进程，启动，任务栏
│ │ ├── agentic_system_workflow.py # ctx.sample() 工作流程
│ │ ├── monitoring.py # 监视器文件监视器
│ │ ├── system_ops.py # 独立工具
│ │ └── prefab/ # 4 个预制 UI 卡片
│ ├── elevated_service/ # 命名管道提升桥
│ └── user_bridge/ # 服务通信客户端
├── web_sota/ # React 19 + Vite 仪表盘
├── mcpb/ # MCPB 打包（v0.2 清单）
├── skills/ # skill://system-admin-expert/SKILL.md
└── tests/ # Pytest 套件
```
---
## 文档
| 文档 | 适用于 |
|----------|-----|
| [快速入门](docs/quickstart.md) | 最终用户 — 安装，配置，运行 |
| [API 参考](docs/api/README.md) | 开发者 — REST 端点 |
| [开发](docs/development/README.md) | 贡献者 — 服务器开发 |
| [AGENTS.md](AGENTS.md) | AI 代理 — 架构和模式 |
---
由 [Sandra Schipal](https://github.com/sandraschi) 在维也纳构建。MIT。
