mission-control-v2/docs/memory/project-mc2-architecture.md

⚠️ TEILS VERALTET (Juni 2026, Archiv). Aktuelle Dienste/Ports/Modelle: docs/wissen/STACK.md · Fallen: docs/wissen/FALLEN.md. Die Schichten-/Key-File-Übersicht hier stimmt im Kern noch.

---

name: project-mc2-architecture description: "MC2 Architektur — Schichten, Key-Files, API-Endpunkte, wichtige Eigenheiten" metadata: node_type: memory type: project originSessionId: e6bf38ac-b5dc-4aaa-80c3-ad8dd078a1fe

Stack-Schichten

Windows PC (192.168.178.98)
  └─ executor.py :7777  ← PC-Steuerung (FastAPI, manuell via start.bat)

AI Box (192.168.178.151) — Ryzen AI MAX+ 395, 122GB unified RAM
  ├─ llama-swap :8080       ← Engine (ROCm/HIP, lemonade-sdk/llamacpp-rocm)
  ├─ mission-control-2 :9001 ← MC2 (FastAPI + React, user-service)
  │    └─ /v1              ← Builtin Gateway (model:auto, OpenAI-kompatibel)
  ├─ hermes-gateway :8642   ← Hermes Agent (NousResearch, user-service)
  │    ├─ mcp_pc.py        ← MCP → executor.py auf Windows PC
  │    ├─ mcp_web.py       ← MCP → trafilatura Web-Fetch
  │    ├─ mcp_memory.py    ← MCP → SQLite Gedächtnis
  │    └─ mcp_mc.py        ← MCP → MC2 Stack-Management
  └─ hermes-webui :8787     ← nesquena hermes-webui (user-service)

Proxmox (192.168.178.108)  ← LXCs: adguard(100) npmplus(101) netbird(102) gitea(104)

---

MC2 Key-Files

Datei	Zweck
backend/app.py	FastAPI Einstieg, Router-Mounting
backend/config.py	Alle Env-Vars (LLAMA_SWAP_URL, HERMES_*, PC_EXECUTOR_URL, etc.)
backend/services/agent.py	/api/agent/status (gateway/webui/telegram/mcp/pc)
backend/services/llamaswap.py	llama-swap API, ROLE_IDS, Modell-CRUD
backend/services/maintenance.py	Updates, Logs, Restart, ROLE_MAP
backend/services/sources.py	CATEGORIES für Discover (roles: vision/coder/agent/scout)
backend/gateway/gateway_proxy.py	Builtin OpenAI-Gateway, model:auto Routing
frontend/src/lib/api.ts	TypeScript-Interfaces für alle API-Responses
frontend/src/lib/queries.ts	React-Query Hooks (useModels, useAgentStatus, etc.)
mcp/mcp_pc.py	PC-Control MCP-Server
mcp/mcp_web.py	Web-Fetch MCP-Server (trafilatura)
mcp/mcp_memory.py	Shared Memory MCP-Server

---

Wichtige Eigenheiten / Gotchas

• Python 3.14 auf Box → LiteLLM unmöglich (uvloop scheitert). MC2 hat eigenen Gateway.
• mcp_pc.py / mcp_web.py müssen Hermes-Venv nutzen (nicht MC2-Venv). Python 3.11 vs 3.14 TaskGroup-Kompatibilität.
• Builtin-Gateway Port: MC2 läuft auf :9001, der /v1-Endpunkt ist Teil von MC2 (nicht separater Dienst).
• MC_PORT vs tatsächlicher Port: In Env ist MC_PORT=9000, aber der User-Service hört auf :9001 (Port in Unit-Definition). Beim SSH-Deploy immer :9001 verwenden.
• llama-swap Config braucht sudo zum Schreiben (/etc/llama-swap/config.yaml), aber hitonabi ist in adm-Gruppe → journalctl ohne sudo lesbar.
• ROLE_IDS in llamaswap.py = {"vision", "coder", "agent", "scout"} (reasoning entfernt 2026-06-27).
• Discover-CATEGORIES in sources.py: vision / coder / agent / scout (kein reasoning mehr).
• API_SERVER_KEY: in ~/.hermes/.env auf der Box

---

/api/agent/status Felder (Stand 2026-06-27)

{
  "gateway_reachable": bool,    # Hermes :8642
  "webui_reachable": bool,      # hermes-webui :8787
  "brain_model": str,           # aus ~/.hermes/config.yaml
  "has_config": bool,
  "has_skills": bool,
  "has_memories": bool,
  "telegram_enabled": bool,     # TELEGRAM_BOT_TOKEN gesetzt?
  "mcp_server_count": int,      # enabled MCP-Server in config.yaml
  "pc_executor_reachable": bool # 192.168.178.98:7777/health
}