convez.ai
MCP ServerDevOps & InfraestruturaAvançado
Syamsuddin

ODIN — MCP Agent para Gerenciamento de Servidores

Syamsuddin/ODIN

IA para servidor Linux via linguagem natural, sem SSH manual

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent MCP baseado em IA que permite gerenciar servidores Linux através de instruções em linguagem natural via Claude. Transforma comandos de texto em operações automatizadas no servidor, com camadas de segurança, detecção de erros e rollback automático.

Instalação

$npx convez-ai Syamsuddin/ODIN

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Deploy e gerenciamento de aplicações em VPS com linguagem natural
  • Detecção automática e correção de erros em tempo real
  • Automação de workflows consistentes com runbook engine
  • Auditoria e rollback seguro de operações destrutivas

Veredito

ODIN é um servidor MCP robusto para automação de infraestrutura Linux via Claude, com 17 ferramentas, segurança em 5 camadas e análise inteligente de erros. Excelente para times que precisam bridgear entre Claude Code (cliente) e VPS (executor) sem SSH manual ou daemons adicionais.

README

A tradução para o português deste README ainda está na fila.


Mengapa ODIN

Tanpa ODINDengan ODIN
SSH manual, ketik command satu per satuInstruksi natural language, eksekusi otomatis
Lupa urutan deploy, skip langkahWorkflow konsisten via runbook engine
Error tak terdeteksi sampai user komplain22 pola error dianalisis real-time + saran perbaikan
Rollback panik: "commit sebelumnya apa?"State dicatat otomatis sebelum operasi destruktif
Setiap sesi mulai dari nolMemory persisten: ODIN ingat server, preferensi, instruksi
Risk fatigue: approve semua tanpa bacaKartu risiko 5 tier: baca sekilas, putuskan cepat
Server state tak diketahuiAuto-inspect: type, stack, mode terdeteksi otomatis

Arsitektur

LAPTOP (Claude Code CLI)                    SERVER (Ubuntu VPS, user: odin)
┌─────────────────────────┐  SSH stdio MCP  ┌────────────────────────────────┐
│                         │ ──────────────▶ │                                │
│  odin_guard.py  │  spawn fresh    │  odin_agent.py (ODIN server) │
│  ├─ READ/WRITE classify │  per sesi       │  ├─ 17 MCP tools               │
│  ├─ Risk engine (5 tier)│                 │  ├─ Output intelligence (23)   │
│  ├─ Mode-aware tier     │                 │  ├─ Rollback tracking          │
│  ├─ Undo hints (12 pat) │                 │  ├─ Runbook engine + templates │
│  └─ Kartu risiko UI     │                 │  ├─ Server profiler + modes    │
│                         │                 │  ├─ Memory persisten (JSONL)   │
│  651 baris Python       │                 │  ├─ Audit log + audit_tail     │
│                         │                 │  ├─ Deploy fingerprint & drift │
│                         │                 │  └─ Watchdog (health://live)   │
│                         │                 │  2046 baris Python             │
└─────────────────────────┘                 └────────────────────────────────┘

Koneksi: SSH stdio — tidak perlu port tambahan, tidak perlu daemon, tidak perlu API key di server. MCP server di-spawn fresh tiap sesi Claude Code, lalu mati otomatis saat sesi berakhir.


Struktur Proyek

ODIN/
├── server/
│   ├── odin_agent.py    # MCP server ODIN (2046 baris) — jalan di VPS
│   └── run.sh             # Launcher: set env + exec venv python
├── client/
│   ├── odin_guard.py  # Risk engine + gerbang read/write (651 baris) — jalan di laptop
│   └── update_checker.py      # Cek versi terbaru dari GitHub (155 baris)
├── tests/                     # 485 tests across 10 files
│   ├── test_core.py           # Core functions (44 tests)
│   ├── test_guard.py          # Guard classifier & risk engine (160 tests)
│   ├── test_memory.py         # Memory system (58 tests)
│   ├── test_output_intelligence.py  # Error patterns (48 tests)
│   ├── test_fase2_intelligence.py   # Suggestions, tracking, trends (25 tests)
│   ├── test_fase3.py          # Runbook & rollback (36 tests)
│   ├── test_fase3_ux.py       # Audit tail, undo hints, templates (32 tests)
│   ├── test_fase4_proactive.py # Fingerprint, drift, budget, watchdog (38 tests)
│   └── test_profile_mode.py   # Server profiler & mode (44 tests)
├── docs/
│   └── MEMORY_NOTES.md        # Dokumentasi sistem memory
├── install.sh                 # Installer + server setup wizard (macOS & Linux, 857 baris)
├── install.ps1                # Installer Windows (PowerShell)
├── uninstall.sh               # Uninstaller + auto-clean config (macOS & Linux)
├── uninstall.ps1              # Uninstaller Windows (PowerShell)
├── requirements.txt           # Dependensi: mcp[cli]
├── CLAUDE.md                  # Instruksi untuk Claude Code
├── CHANGELOG.md               # Riwayat perubahan
├── EXECUTIVE_SUMMARY.md       # Rangkuman eksekutif
└── REVIEW_EMPAT_FAKTOR.md     # Review teknis 4 dimensi

Total: 2852 baris source + 3545 baris test = 6397 baris


17 Tools MCP + 2 Resources

Eksekusi & Inspeksi

ToolFungsiApproval
run_commandJalankan command shell apa pun di serverREAD: otomatis, WRITE: kartu risiko
tail_logBaca N baris terakhir file log (Laravel, Nginx, system)Otomatis
service_actionKelola systemd: status, restart, reload, start, stopREAD: otomatis, WRITE: kartu risiko
server_infoRingkasan server: OS, disk, memory, PHP, uptimeOtomatis
inspect_serverFull inspection: type detection, stack scan, mode derivationOtomatis

Deploy & Testing

ToolFungsiApproval
laravel_deployDeploy Laravel satu tombol: git reset, composer, migrate, cache, FPM reloadKartu risiko TINGGI
run_testsJalankan PHPUnit/Pest test suiteOtomatis
http_health_checkVerifikasi HTTP status (response code + body)Otomatis

Workflow Intelligence

ToolFungsiApproval
runbookEksekusi workflow multi-langkah (maks 20 step) dengan error analysis & rollback per stepKartu risiko (tier tertinggi)
runbook_templatesList/ambil template runbook builtin & customOtomatis
rollback_planTampilkan saran undo untuk operasi destruktif terakhirOtomatis
session_historyRiwayat semua operasi di sesi ini (in-memory, hilang saat respawn)Otomatis
audit_tailBaca audit log dengan filter (last, tool, success, since)Otomatis

Memory Persisten

ToolFungsiApproval
memory_writeSimpan fakta/instruksi yang bertahan lintas sesiKartu risiko RENDAH
memory_recallCari memory berdasarkan namespace/tag/keywordOtomatis
memory_forgetHapus memory entry (tombstone)Kartu risiko RENDAH
memory_digestTampilkan seluruh memory aktif (sama dengan yang di-inject saat startup)Otomatis

MCP Resources

ResourceFungsi
memory://{ns}Baca memory per namespace (read-only, tanpa tool call)
health://liveWatchdog: cek disk, memory, load, service status — untuk polling via /loop

Model Keamanan — 4 Lapis Defense-in-Depth

Lapis 1: READ/WRITE Classifier (client — odin_guard.py)
         23 sub-command classifier (git, docker, mysql, npm, curl, ufw, nginx, ...)
         READ → auto-approve    WRITE → lanjut ke lapis 2
              ↓
Lapis 2: Risk Engine + Kartu Risiko (client)
         5 tier: AMAN → RENDAH → SEDANG → TINGGI → KRITIS
         26 aturan shell + DB risk assessor
         User membaca kartu, memutuskan approve/reject
              ↓
Lapis 3: Hard-block Katastrofik (server — _DANGER_RE)
         rm -rf /, mkfs, dd of=/dev, fork bomb, shutdown, DROP DATABASE
         Ditolak kecuali allow_dangerous=True (double brake)
              ↓
Lapis 4: OS-level (server)
         User odin dengan sudoers terbatas
         Batas keamanan sesungguhnya

Contoh Kartu Risiko

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🟠 RISIKO: TINGGI
Cmd   : git reset --hard origin/main
Dir   : /var/www/simuru
Aksi  : Buang semua perubahan lokal
Efek  : Perubahan belum commit hilang permanen
Saran : Stash dulu jika ada kerja penting
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Perlindungan Tambahan

  • Command substitution ($() dan backtick) di-detect dan di-force ke "ask" — mencegah bypass via subshell
  • Secret detection di memory: password, token, private key, JWT, AWS key ditolak masuk JSONL
  • Memory di luar webroot: tidak bisa diakses via web, tidak ikut git reset --hard saat deploy
  • Audit trail: setiap eksekusi tercatat append-only — untuk forensik pasca-insiden
  • Production mode: tier risiko naik 1 level + warning MODE PRODUCTION di kartu risiko

Kecerdasan Bawaan

Output Intelligence (22 Pola Error)

Setiap output command dianalisis terhadap 22 pola error — dari spesifik ke generik:

KategoriPola yang Dideteksi
DatabaseSQLSTATE (auth, connection, constraint, general), deadlock, max connections
PHP/LaravelFatal error, OOM, timeout, class not found, composer lock
SystemDisk full, OOM kill, permission denied, command not found
ToolsNginx config error, SSL expired, npm build failure

Hasil analisis dilampirkan otomatis:

{"error_type": "db_conn", "hints": ["Cek service MySQL, pastikan berjalan..."]}

Rollback Tracking

Sebelum command destruktif (git reset, artisan migrate, service restart):

  1. _capture_pre_state() — tangkap git HEAD, migration status, service status
  2. Eksekusi command
  3. _suggest_rollback() — sarankan undo command spesifik berdasarkan state yang ditangkap

Runbook Engine

Claude menyusun langkah berdasarkan konteks — ODIN mengeksekusi berurutan (maks 20 step):

  • Error analysis per langkah
  • Rollback tracking per langkah
  • Berhenti otomatis pada kegagalan (kecuali continue_on_fail=True)
  • Laporan terstruktur: executed/total/skipped/failed

Pre-flight Checks

Sebelum laravel_deploy, otomatis cek: disk (blokir jika >= 95%), git dirty files, commit saat ini, versi PHP. Blocker = deploy dibatalkan dengan laporan.

Server Profiler & Mode Operasi

Pada startup, ODIN menjalankan inspeksi penuh:

  1. Base inspection — OS, kernel, uptime, disk, memory, firewall, fail2ban, SSH, cron, users
  2. Type detection — klasifikasi: web-app, database, container, general
  3. Stack inspection — per-type: web (nginx/PHP/FPM/composer/DB/Redis/SSL), database (MySQL/PG/Mongo), container (Docker/compose)
  4. App inspection — .env, vendor, framework detection, git state
  5. Mode derivation — otomatis: setup / deploy / production

Mode enforcement (dual layer):

  • Server (_mode_gate): production mode memblokir laravel_deploy dan package-install commands
  • Guard (_shift_tier): production mode menaikkan tier risiko +1 level

Memory Persisten

3 namespace: server (fakta infrastruktur), instruction (arahan user), profile (identitas).

  • Append-only JSONL + fold (last-write-wins, tombstone, TTL)
  • Auto-inject ke konteks saat spawn — setiap sesi baru langsung "ingat"
  • Compaction otomatis saat melebihi MEMORY_MAX_ENTRIES
  • Storage di luar webroot dan PROJECT_ROOT — aman dari deploy & run_command

Audit Log

Setiap eksekusi tool dicatat ke audit.jsonl: timestamp, tool, summary, success, exit_code, durasi, mode. Append-only, tidak pernah dihapus.


Instalasi

Installer Otomatis (Rekomendasi)

curl -fsSL https://raw.githubusercontent.com/Syamsuddin/ODIN/main/install.sh | bash

Installer terintegrasi menangani laptop + server dalam satu langkah:

Tahap 1 — Laptop (otomatis)

  • Clone repo, buat venv, install mcp[cli], setup guard hook, buat perintah odin-update
  • Wizard interaktif: 3 pertanyaan (SSH host, path run.sh, scope guard) → config ditulis otomatis ke ~/.claude.json dan settings.json
  • Tes koneksi SSH ke server

Tahap 2 — Server via SSH (opsional, ditawarkan setelah laptop selesai)

  • Cek Python 3 dan python3-venv di server
  • Buat user odin jika belum ada
  • Buat venv + install mcp[cli]
  • Upload odin_agent.py dan generate run.sh dengan config yang benar
  • Set password user odin
  • Verifikasi semua file terpasang

SSH ControlMaster digunakan agar hanya satu kali autentikasi selama setup.

Windows: irm https://raw.githubusercontent.com/Syamsuddin/ODIN/main/install.ps1 | iex (laptop only, server setup manual)

Manual

Jika lebih memilih setup manual (atau installer gagal):

1. Di Laptop (client)

git clone https://github.com/Syamsuddin/ODIN.git ~/.odin
cd ~/.odin
python3 -m venv .venv && .venv/bin/pip install "mcp[cli]"

2. Di Server (VPS)

# Buat user odin (sebagai root)
useradd -m -s /bin/bash odin
passwd odin

# Setup venv + install dependensi
python3 -m venv /home/odin/.venv
/home/odin/.venv/bin/pip install "mcp[cli]"

# Salin file dari laptop
scp ~/.odin/server/odin_agent.py  <host>:/home/odin/
scp ~/.odin/server/run.sh           <host>:/home/odin/

# Set permissions
chmod 600 /home/odin/odin_agent.py
chmod 755 /home/odin/run.sh
chown -R odin:odin /home/odin/

3. Konfigurasi Claude Code

MCP server (~/.claude.json):

{
  "mcpServers": {
    "odin": {
      "type": "stdio",
      "command": "ssh",
      "args": ["your-server-alias", "/home/odin/run.sh"]
    }
  }
}

Guard hook (.claude/settings.json):

{
  "permissions": {
    "allow": [
      "mcp__odin__server_info",
      "mcp__odin__tail_log",
      "mcp__odin__http_health_check",
      "mcp__odin__memory_recall",
      "mcp__odin__memory_digest",
      "mcp__odin__session_history",
      "mcp__odin__rollback_plan",
      "mcp__odin__inspect_server"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__odin__(run_command|service_action|laravel_deploy|run_tests|runbook|inspect_server|memory_write|memory_forget)",
        "hooks": [
          {
            "type": "command",
            "command": "python3 '<path-to>/odin_guard.py'",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Update

odin-update

Uninstall

curl -fsSL https://raw.githubusercontent.com/Syamsuddin/ODIN/main/uninstall.sh | bash

Uninstaller menghapus direktori ODIN, membersihkan config mcpServers.odin dan hook mcp__odin__ dari ~/.claude.json dan semua settings.json secara otomatis, serta menawarkan cleanup server via SSH.

Windows: irm https://raw.githubusercontent.com/Syamsuddin/ODIN/main/uninstall.ps1 | iex


Cara Kerja End-to-End

User: "Cek kenapa website error 500, perbaiki kalau bisa"

Claude Code (otak):
  1. server_info          → "Ubuntu 24.04, disk 42%, PHP 8.3"
  2. http_health_check    → "HTTP 500"
  3. tail_log laravel.log → "SQLSTATE[HY000] [2002] Connection refused"
  4. ODIN analisis        → {error_type: "db_conn", hints: ["Cek service MySQL..."]}
  5. service_action mysql  → "inactive (dead)" ← DITEMUKAN
  6. service_action restart mysql → [KARTU RISIKO SEDANG → user approve] → "active"
  7. http_health_check    → "HTTP 200" ← SELESAI

User membaca laporan: "MySQL mati, sudah di-restart, website kembali normal."
Total waktu: < 2 menit. Intervensi user: 1x approve restart MySQL.

Environment Variables

VariableDefaultKeterangan
DEPLOY_MODElocallocal atau ssh
SSH_TARGET—user@host (wajib jika mode ssh)
SSH_PORT22Port SSH
SSH_KEY—Path private key (opsional)
PROJECT_ROOTcwdRoot aplikasi di server
LOCK_CWD_TO_PROJECT01 = kunci cwd ke PROJECT_ROOT
ALLOWED_LOG_DIRS/var/log,/var/www,...Folder yang boleh dibaca tail_log
DEFAULT_TIMEOUT180Timeout default (detik)
MAX_TIMEOUT900Timeout maksimum (detik)
OUTPUT_LIMIT20000Potong output panjang (karakter)
AGENT_LOG_LEVELINFOLevel log
MEMORY_DIR/home/odin/memoryFolder simpanan memory
MEMORY_MAX_TEXT4000Panjang maks teks satu entry
MEMORY_MAX_ENTRIES2000Ambang compaction
AUDIT_ENABLED10 = matikan audit log
ODIN_SKIP_INSPECT01 = skip startup inspection (untuk testing)

Testing

python3 -m pytest tests/ -v          # full test suite (80 tests)
python3 -m py_compile server/odin_agent.py
python3 -m py_compile client/odin_guard.py

Stack yang Didukung

Dirancang untuk dan diuji dengan:

  • OS: Ubuntu Linux (VPS)
  • Web: Laravel / PHP 8.x
  • Database: MySQL / MariaDB
  • Web server: Nginx
  • Process: systemd, PHP-FPM
  • Build: Composer, NPM
  • VCS: Git

Auto-detect juga mendukung: PostgreSQL, MongoDB, Docker, Apache, Redis, Supervisor, Let's Encrypt SSL.

run_command adalah primitif serbaguna — ODIN bisa mengeksekusi command apa pun yang tersedia di server, tidak terbatas stack di atas.


Angka-Angka Kunci

MetrikNilai
Total kode2852 baris Python (server 2046 + guard 651 + updater 155)
Total test3545 baris (485 automated tests, 10 files)
Dependensi runtime1 (mcp[cli])
MCP tools17
MCP resources2 (memory://{ns}, health://live)
Error patterns23 (18 with suggested_commands)
Risk rules26 shell + DB assessor
Undo hint patterns12
Runbook templates4 builtin + custom
READ sub-classifiers23 (git, docker, mysql, npm, curl, ufw, nginx, ...)
Risk tiers5 (AMAN / RENDAH / SEDANG / TINGGI / KRITIS)
Operation modes3 (setup / deploy / production)
Security layers4 (classifier → risk engine → hard-block → OS)
Memory namespaces3 (server / instruction / profile)
FrameworkTidak ada — pure Python + FastMCP
Overhead server0 (spawn-per-session, tidak ada daemon)

Keamanan

Batas sebenarnya = hak OS user odin + sudoers. Hook + _DANGER_RE = jaring pengaman, bukan sandbox. Keputusan akhir selalu di operator (konfirmasi WRITE).

Filosofi: READ auto-approve, WRITE wajib konfirmasi, katastrofik double-brake. Guard lebih ketat dari server (by design).


Lisensi & Versi

Versi aktif: 1.3.0 — tersimpan di __version__ pada kedua file Python. Lihat CHANGELOG.md untuk riwayat perubahan lengkap.

ODIN v1.3 — ringan, cerdas, aman. Satu file di server, satu file di laptop, otak Claude.

Ver o original no GitHub

Bom para

Relacionados