MCP 기반 에이전트형 Linux 진단 도우미 — "노트북이 왜 느린가요" 같은 자연어 질문에 대해 Gemini가 커스텀 MCP 서버가 노출하는 타입화되고 샌드박스된 도구를 선택하고 호출하며, 진단에 충분한 증거를 모을 때까지 LangGraph 상태 머신을 반복하는 방식으로 답변합니다.
로컬 전용 · Ubuntu · CLI · 임의 셸 없음 · 변경 작업은 인간 개입 필요
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 추상화 계층을 호출하며, OS 로직을 직접 포함하지 않습니다.
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, 일반 셸 도구는 없습니다.
MCPilot의 보안은 4개 계층에 걸친 심층 방어입니다:
임의 셸 도구 없음 — 모든 기능은 고정된 서브프로세스 인자 목록을 가진 특정하고 좁은 범위의 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