The Adaptive Developer

Overview

EdenVanguard turns Minecraft server support from a manual slog into an auditable pipeline. Players paste crash logs into Discord; Vanguard's detection layer recognizes crash signatures and paste-service links, retrieves the full log, and hands the case to Aegis — an autonomous agent that diagnoses with an LLM, proposes a fix, requests admin approval for destructive actions, and executes remediation against a Pterodactyl-managed server through a dedicated MCP safety layer. Every step is recorded in PostgreSQL, and every privileged operation crosses the same audited tool boundary.

The system is organized as an npm-workspaces monorepo with four TypeScript packages — vanguard (Discord gateway), aegis (intelligence core), pterodactyl-mcp (MCP server wrapping the Pterodactyl Application/Client APIs), and shared (contracts) — plus infra (PostgreSQL + NATS JetStream Compose stack and Drizzle migration).

🛡️

Core design rule: Aegis never calls the Pterodactyl REST API directly. Power commands, file operations, backups, schedules, and console actions all go through MCP tools with scoped ptla_/ptlc_ credentials, rate limiting, and confirmation gates.

Highlights

27 MCP tools wrapping Pterodactyl — server power, console, files, backups, schedules, and build configuration. Seven destructive operations are guarded by Zod confirm: true gates, with double confirmation for the two highest-risk operations.
LLM diagnosis with operational discipline — Groq inference with round-robin API keys from an encrypted vault, AES-256-GCM token decryption at rest, 429-aware retry with Retry-After parsing, and per-event rate-limit telemetry.
Crash detection — recognizes mclo.gs, mclogs.io, Pastebin, pastes.io, gnome.dev, and bytebin links, alongside inline JVM and crash-report signatures.
Cron deployment pipeline — backup → verify → file swap → health check → rollback semantics, a maintenance queue, and a zero-player gate.
Skill engine — deduplication using Jaccard similarity and an admin review flow, turning recurring fixes into reusable, reviewed automation.
Console safety — WebSocket console with JWT auto-refresh (8-minute refresh against a 10-minute expiry) and a command blocker that rejects destructive console input.

Technology stack

Layer	Technology
Language	TypeScript (strict, ES2024, project references)
Gateway	Node.js ≥ 22, discord.js 14
Agent core	orchestrator → planner → executor → resultHandler → reporter loop
Tool protocol	Model Context Protocol (@modelcontextprotocol/sdk 1.29) over stdio JSON-RPC 2.0
IPC	NATS JetStream; subjects defined in shared
Database	PostgreSQL + Drizzle ORM; 9 tables, one versioned migration
LLM	Groq (llama-3.3-70b-versatile) with rotating encrypted keys
Infrastructure	Docker Compose (postgres:17-alpine, nats:2-alpine), GitHub Actions CI
Testing	node:test; 116/116 unit tests across four workspaces

Key features

End-to-end crash workflow — detection, paste extraction, diagnosis, admin approval buttons/modals, execution, and a written evaluation back into the Discord thread.
Credential vault — Pterodactyl tokens are AES-256-GCM encrypted and indexed with SHA-256 lookup hashes, scoped by credential type, and rotatable without a restart. LLM keys use the same pattern in the api_keys table.
Approval-first autonomy — safe operations run automatically; stop/kill/restore/delete-class operations require admin confirmation enforced at the tool-schema level, not merely by convention.
Auditability — audit_log, deployment_audit, and rate_limit_events record what changed, which step ran, and which key was throttled.
Sandboxed skill execution — scripts run through a child_process executor with ulimit resource wrappers, timeouts, output caps, and a dangerous-command blocklist. Full container isolation is a documented roadmap item, not claimed as complete.
Repeatable verification — typecheck-clean across all four workspaces, 116/116 unit tests without live-service dependencies, and CI on every push.

Architecture

Discord events enter Vanguard's gateway, where crash signatures are detected and logs are enriched. Jobs flow through NATS JetStream to Aegis. Aegis plans and executes through an MCP client; the pterodactyl-mcp server translates approved tool calls into scoped Pterodactyl API traffic, including a pooled WebSocket console with JWT refresh. PostgreSQL underpins queues, audits, credentials, and the skill registry.

The repository's docs/ directory contains the 10-part design corpus covering architecture, database schema, state machines, API contracts, phases, Pterodactyl research, and risks. STATUS.md records what is and is not implemented; README.md contains the quickstart and environment-variable reference.

Status and verification

Implemented and verified at compile/test level: all four workspaces typecheck cleanly, all 116 unit tests pass, GitHub Actions CI is wired, secrets have been scrubbed, and repository history is consolidated into seven logical commits.

Not production-deployed. Container-isolated sandboxing, patch export/rollback tooling, and integration/end-to-end test suites remain documented next steps. Unit tests do not imply production readiness.

Repository and quickstart

Code: github.com/x-TheFox/Vanguard
Quickstart: npm ci → configure .env → docker compose up → npm run build → run the three services. Follow the repository README for complete setup instructions.