Skip to main content
Glama
deenesjakoruzh
Ronit-k

MCPilot

by Ronit-k
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

MCPilot

Asistente de diagnóstico Linux agéntico basado en MCP — responde preguntas en lenguaje natural como "¿por qué mi portátil va lento?" haciendo que Gemini seleccione y llame a herramientas tipadas y aisladas expuestas por un servidor MCP personalizado, iterando a través de una máquina de estados LangGraph hasta que tenga suficiente evidencia para un diagnóstico.

Solo local · Ubuntu · CLI · Sin shell arbitrario · Humano en el bucle para mutaciones

Arquitectura

                         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

Regla de capas: los decoradores de MCP llaman a una capa central de abstracción de Linux; nunca contienen lógica de sistema operativo por sí mismos.

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

Catálogo de herramientas (18 herramientas)

Herramienta

Módulo

Devuelve

Riesgo

get_system_info

system

SystemInfo

READ_ONLY

get_cpu_usage

system

CpuUsage

READ_ONLY

get_memory_usage

system

MemoryUsage

READ_ONLY

get_disk_usage

system

list[DiskUsageEntry]

READ_ONLY

list_processes

system

list[ProcessSummary]

READ_ONLY

get_process_info

system

ProcessDetail | ToolError

READ_ONLY

get_service_status

services

ServiceStatus | ToolError

READ_ONLY

get_service_logs

services

ServiceLogs | ToolError

READ_ONLY

get_listening_ports

services

list[ListeningPort]

READ_ONLY

restart_service

services

ServiceStatus | ToolError

APPROVAL_REQUIRED

list_directory

filesystem

list[DirectoryEntry] | ToolError

READ_ONLY

get_file_metadata

filesystem

FileMetadata | ToolError

READ_ONLY

search_files

filesystem

SearchResult | ToolError

READ_ONLY

read_file

filesystem

str | ToolError

READ_ONLY

git_status

git

GitStatus | ToolError

READ_ONLY

git_diff

git

GitDiff | ToolError

READ_ONLY

git_log

git

list[GitLogEntry] | ToolError

READ_ONLY

run_tests

git

TestRunResult | ToolError

READ_ONLY

Intencionadamente no hay delete_file, sudo_command ni herramienta de shell genérica.

Modelo de seguridad

La seguridad de MCPilot se basa en defensa en profundidad en cuatro capas:

  1. Sin herramienta de shell arbitraria — Cada capacidad es una función de Python específica y de alcance limitado con una lista fija de argumentos de subprocess. Nunca shell=True, nunca comandos interpolados en cadenas.

  2. Restricción de rutas — Todas las herramientas de sistema de archivos y Git validan rutas contra una lista de permitidos explícita (~/Projects, ~/Documents). Resuelto por enlaces simbólicos, comprobado con is_relative_to(). Ver server/core/fs.py::validate_path.

  3. Prevención de inyección en nombres de servicio — Una regex estricta (^[a-zA-Z0-9@_.\-]+$) rechaza ;, |, &, $, comillas invertidas, espacios en blanco y separadores de ruta. Ver server/core/systemd.py::validate_service_name.

  4. Clasificación de riesgo + aprobación humana — Cada herramienta tiene un nivel de riesgo (READ_ONLY, APPROVAL_REQUIRED, DENIED). Las herramientas desconocidas por defecto son DENIED (fallo cerrado). La única herramienta mutadora (restart_service) se detiene para confirmación explícita con y.

  5. Registro de auditoría — Cada llamada a herramienta se registra en logs/audit.jsonl con marca de tiempo, herramienta, argumentos, riesgo, estado de aprobación y resultado.

  6. Ejecutor de subprocesos seguro — Todas las llamadas a subprocesos pasan por una única función run_safe(): siempre shell=False, siempre argumentos en lista, siempre con tiempo de espera.

Modelo de amenazas completo: docs/security.md

Inicio rápido

# 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?"

Ejemplos de trazas

Diagnóstico del sistema

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.

Diagnóstico de servicios

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.

Demostración de seguridad

You: Restart PostgreSQL
[Agent] Analyzing request...

┌──────────────────────────────┐
│ MCPilot requests action      │
├──────────────────────────────┤
│ Tool: restart_service        │
│ Service: postgresql          │
│                              │
│ Reason: service action       │
│ requested by diagnostic agent│
│                              │
│ Approve? [y/N]               │
└──────────────────────────────┘

Suite de pruebas

Capa

Pruebas

Qué cubre

Capa 1 — Núcleo Linux

8

/proc, psutil, información de procesos, limitación de salida

Capa 2 — Protocolo MCP

4

18 herramientas registradas, esquemas, descripciones

Capa 3 — Seguridad

24

Recorrido de rutas, inyección de servicios, herramientas desconocidas, límites de salida

Capa 4 — Agente

8

Políticas, límite de iteraciones, rechazo de aprobación, integridad del estado

Total

44

Etiquetas de confianza

La confianza es una etiqueta discreta y explicable, no una puntuación estadística calibrada:

  • ALTA: ≥3 observaciones independientes apuntan a la misma causa

  • MEDIA: Alguna evidencia de apoyo, pero falta una observación confirmatoria

  • BAJA: La evidencia es escasa, se alcanzó el límite de iteraciones o las observaciones entran en conflicto

Estructura del proyecto

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)

Licencia

MIT

Install Server
F
license - not found
A
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • mcp-linux-tools

    gerard-kanters
    A
    license
    A
    quality
    A
    maintenance
    Enables AI assistants to perform controlled Linux system administration tasks like reading logs, managing services, cron jobs, WordPress, and executing sandboxed Python code, with strict security constraints.
    29
    2
    GPL 2.0

  • mcp-linux-ops

    zql78
    F
    license
    B
    quality
    D
    maintenance
    Enables LLMs to execute shell commands and perform file operations on a Linux system, exposing tools like execute_command, read_file, write_file, and more.
    10

  • incident-tool

    KyleCS0
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to diagnose Linux server incidents by collecting and structuring system diagnostics from multiple servers via SSH, with tools for finding incident clusters, gathering context (memory, CPU, swap, etc.), and running arbitrary commands.

View all related MCP servers

Related MCP Connectors

  • SentinelX MCP

    Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.

  • emisar

    Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.

  • Oakallow

    Runtime permission, approval, and audit layer for AI agent tool execution.

View all MCP Connectors

Latest Blog Posts

MCP directory API

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