基于 MCP 的智能 Linux 诊断助手 — 通过让 Gemini 选择并调用由自定义 MCP 服务器暴露的类型化、沙箱化工具，回答诸如 "为什么我的笔记本电脑很慢" 之类的自然语言问题，并通过 LangGraph 状态机迭代，直到收集到足够的证据进行诊断。
仅限本地 · Ubuntu · 命令行 · 无任意 shell · 变更需人工介入
USER
│
▼
CLI Interface (rich)
│
▼
┌─────────────────┐
│ LangGraph │
│ Diagnostic Agent│◄──── Gemini (function calling)
└────────┬────────┘
│
MCP Client (stdio)
│
MCP Protocol
│
▼
┌─────────────────┐
│ MCPilot Server │ (MCPServer, subprocess-launched)
└────────┬────────┘
│
┌───────────────┼────────────────┐
│ │ │
▼ ▼ ▼
System Filesystem Git
/proc, psutil POSIX APIs, Git CLI via
systemd, path allow-list controlled
journalctl subprocess分层规则：MCP 装饰器调用核心 Linux 抽象层；它们本身绝不包含操作系统逻辑。
server/tools/system.py → server/core/linux.py → /proc, psutil, uname
server/tools/services.py → server/core/systemd.py → systemctl, journalctl
server/tools/filesystem.py → server/core/fs.py → pathlib / POSIX APIs
server/tools/git.py → server/core/git.py → git CLI (controlled subprocess)Related MCP server: mcp-linux-ops
工具 | 模块 | 返回类型 | 风险 |
| system |
| READ_ONLY |
| system |
| READ_ONLY |
| system |
| READ_ONLY |
| system |
| READ_ONLY |
| system |
| READ_ONLY |
| system |
| READ_ONLY |
| services |
| READ_ONLY |
| services |
| READ_ONLY |
| services |
| READ_ONLY |
| services |
| APPROVAL_REQUIRED |
| filesystem |
| READ_ONLY |
| filesystem |
| READ_ONLY |
| filesystem |
| READ_ONLY |
| filesystem |
| READ_ONLY |
| git |
| READ_ONLY |
| git |
| READ_ONLY |
| git |
| READ_ONLY |
| git |
| READ_ONLY |
有意不提供 delete_file、sudo_command 或通用 shell 工具。
MCPilot 的安全策略是跨四个层次的纵深防御：
无任意 shell 工具 — 每个能力都是一个特定的、范围狭窄的 Python 函数，具有固定的子进程参数列表。绝不使用 shell=True，绝不使用字符串插值命令。
路径限制 — 所有文件系统和 Git 工具都根据显式允许列表（~/Projects、~/Documents）验证路径。通过符号链接解析，并使用 is_relative_to() 检查。参见 server/core/fs.py::validate_path。
服务名称注入防护 — 严格的正则表达式（^[a-zA-Z0-9@_.\-]+$）拒绝 ;、|、&、$、反引号、空白字符和路径分隔符。参见 server/core/systemd.py::validate_service_name。
风险分类 + 人工审批 — 每个工具都有风险级别（READ_ONLY、APPROVAL_REQUIRED、DENIED）。未知工具默认为 DENIED（失败关闭）。唯一的变更工具（restart_service）会暂停等待明确的 y 确认。
审计日志 — 每次工具调用都会记录到 logs/audit.jsonl，包含时间戳、工具、参数、风险、审批状态和结果。
安全的子进程运行器 — 所有子进程调用都通过单一的 run_safe() 函数：始终使用 shell=False，始终使用列表参数，始终设置超时。
完整威胁模型：docs/security.md
# Prerequisites: Ubuntu, Python 3.12+, uv
git clone <repo-url> && cd mcpilot
# Install dependencies
uv sync
# Set Gemini API key
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
# Run tests (44 tests, all layers)
PYTHONPATH="" uv run python -m pytest tests/ -v --override-ini="asyncio_mode=auto"
# Interactive mode
uv run python -m cli.main
# One-shot mode
uv run python -m cli.main "Why is my system slow?"You: Why is my system slow?
[Agent] Analyzing request...
[MCP] get_cpu_usage()
[MCP] get_memory_usage()
[MCP] list_processes(limit=20)
[MCP] get_disk_usage()
[Agent] Evaluating evidence...
[Agent] Generating diagnosis...
Diagnosis: Memory pressure (92% used, 70% swap) driven by firefox.
Confidence: HIGH.You: Why isn't PostgreSQL working?
[Agent] Analyzing request...
[MCP] get_service_status(service='postgresql')
[MCP] get_service_logs(service='postgresql')
[MCP] get_listening_ports()
[MCP] list_processes(limit=20)
[Agent] Evaluating evidence...
[Agent] Generating diagnosis...
Diagnosis: systemd shows failed; journal shows "address already in use";
port 5432 is held by PID <n> (<process>). Confidence: HIGH.You: Restart PostgreSQL
[Agent] Analyzing request...
┌──────────────────────────────┐
│ MCPilot requests action │
├──────────────────────────────┤
│ Tool: restart_service │
│ Service: postgresql │
│ │
│ Reason: service action │
│ requested by diagnostic agent│
│ │
│ Approve? [y/N] │
└──────────────────────────────┘层 | 测试数 | 覆盖内容 |
第 1 层 — 核心 Linux | 8 |
|
第 2 层 — MCP 协议 | 4 | 注册了 18 个工具、模式、描述 |
第 3 层 — 安全 | 24 | 路径遍历、服务注入、未知工具、输出限制 |
第 4 层 — 智能体 | 8 | 策略、迭代上限、审批拒绝、状态完整性 |
总计 | 44 |
置信度是一个离散的、可解释的标签 — 不是校准的统计分数：
高：≥3 个独立观察指向同一原因
中：有一些支持性证据，但缺少确认性观察
低：证据薄弱，达到迭代上限，或观察结果冲突
mcpilot/
├── server/
│ ├── main.py # MCPServer app, registers all 18 tools
│ ├── tools/ # MCP tool wrappers (thin, no OS logic)
│ │ ├── system.py # 6 system tools
│ │ ├── services.py # 4 service tools (incl. restart_service)
│ │ ├── filesystem.py # 4 filesystem tools
│ │ └── git.py # 4 git tools
│ ├── core/ # Linux abstraction layer
│ │ ├── linux.py # /proc + psutil parsing
│ │ ├── systemd.py # systemctl/journalctl wrappers
│ │ ├── fs.py # path validation + file ops
│ │ ├── git.py # git subprocess wrappers
│ │ └── command.py # shared safe-subprocess runner
│ ├── policies.py # risk classification map
│ ├── schemas.py # all Pydantic models
│ └── audit.py # JSONL audit logger
├── client/
│ └── mcp_client.py # MCP stdio client
├── agent/
│ ├── state.py # DiagnosticState TypedDict
│ ├── graph.py # LangGraph wiring
│ ├── nodes.py # 4 LangGraph nodes
│ ├── prompts.py # LLM prompt templates
│ └── tool_adapter.py # MCP → Gemini function declarations
├── cli/
│ └── main.py # CLI entrypoint, rich output, approval UI
├── tests/ # 44 tests across 4 layers
│ ├── server/ # Layer 1+2 tests
│ ├── agent/ # Layer 4 tests
│ └── security/ # Layer 3 tests (interview demo suite)
├── docs/ # Architecture, security, MCP docs
├── examples/ # Captured diagnostic transcripts
└── logs/ # audit.jsonl (gitignored)MIT
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Runtime permission, approval, and audit layer for AI agent tool execution.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Ronit-k/MCPilot'
If you have feedback or need assistance with the MCP directory API, please join our Discord server