Architektur

Übersicht

Der satware® AI OnlyOffice MCP-Server ist eine einzelne Express-Anwendung, die das Model Context Protocol, eine Admin-Oberfläche, Artefakt-Downloads und Health-Checks alle auf einem Port bereitstellt.

Single-Port-Modell

Eine Express-Anwendung auf Port :3847 bedient fünf Endpunkte:

Endpunkt	Methode	Zweck
`/mcp`	POST	MCP Streamable HTTP-Transport (Protokoll `2025-11-25`)
`/admin`	GET	Vue 3 + Element Plus Admin-SPA (Session-Cookie-Auth)
`/artifacts`	GET	Dokument-Artefakt-Downloads (automatisch bereinigt)
`/health`	GET	Service-Health-Status (JSON)
`/instances`	GET	OnlyOffice-Instanzliste + Health

Die TLS-Terminierung wird in der Produktion von einem Reverse-Proxy (Caddy oder Nginx) übernommen.

Docker-Stack

+-------------------------------------------------------------+
|                    Docker Compose Stack                      |
+-------------------------------------------------------------+
|  +------------------+  +------------------+  +-------------+ |
|  |   MCP Server     |  |   OnlyOffice     |  |  Artifact   | |
|  |   Port: 3847     |--|   Port: 9980     |  |   Cleanup   | |
|  | /mcp /admin      |  |   (Document      |  |  (Cron)     | |
|  | /artifacts       |  |    Builder)      |  |             | |
|  | /health          |  |                  |  |             | |
|  +--------+---------+  +------------------+  +------+------+
|           |                                     |          |
|           +----------- /var/artifacts ----------+          |
+-------------------------------------------------------------+

Services

Service	Basis-Image	Port	Zweck
`mcp-server`	`node:25-slim` (mehrstufig)	3847	MCP-Server + Admin-Oberfläche + Artefakt-Downloads
`onlyoffice`	`onlyoffice/documentserver`	9980 (intern)	Dokumentgenerierungs-Engine
`artifact-cleanup`	`alpine:3.20` + supercronic	-	Entfernt abgelaufene Artefakte (konfigurierbare TTL)

Optionale Services (aktiviert über Docker Compose-Profile):

Profil	Service	Anwendungsfall
`s3`	`minio`	S3-kompatibler Speicher für die Entwicklung
`smb`	`samba`	SMB/CIFS-Freigabe für die Entwicklung

Tool-Ablauf

Wenn ein KI-Agent onlyoffice_generate_document aufruft:

KI-Agent
  |
  | MCP-Tool-Aufruf (STDIO oder HTTP)
  v
MCP-Server (Express :3847)
  |
  | 1. Daten gegen Vorlagen-Schema validieren (Zod)
  | 2. DocBuilder-Skript aus Vorlage + Daten generieren
  | 3. Skript im OnlyOffice-Container via Docker exec ausführen
  v
OnlyOffice Document Server (:9980)
  |
  | 4. Dokument rendern (DOCX/PPTX/XLSX)
  | 5. Optional: zu PDF konvertieren
  v
MCP-Server
  |
  | 6. Artefakt in /var/artifacts speichern
  | 7. Download-URL oder Base64 an Agent zurückgeben
  v
KI-Agent

Multi-Instanz-Unterstützung

Der Server unterstützt mehrere OnlyOffice Document Server-Instanzen für Lastverteilung oder Tenant-Isolation. Konfigurieren Sie diese über die Umgebungsvariable ONLYOFFICE_INSTANCES (JSON) oder die Admin-Oberfläche unter /admin/instances.

Jedes Tool akzeptiert einen optionalen instanceId-Parameter, um eine bestimmte Instanz anzusprechen. Wird dieser weggelassen, wird die Standardinstanz verwendet.

Admin-Oberfläche

Die Admin-Oberfläche unter /admin bietet:

Vorlagen: Auflisten, Erstellen, Bearbeiten, Löschen. DOCX-Dateien hochladen und automatisch JSON-Schemata aus Platzhaltern extrahieren. Formulare ausfüllen, um Dokumente zu generieren.
Artefakte: Generierte Dokument-Artefakte auflisten und löschen.
Anmeldeinformationen: Verschlüsselte Cloud-Speicher-Anmeldeinformationen erstellen, bearbeiten und löschen (Google Drive, OneDrive, S3, MinIO, WebDAV, SMB).
Instanzen: Vollständiges CRUD für OnlyOffice-Instanzen. Health-Checks, Standardinstanz festlegen, Registry neu laden.

Die Authentifizierung erfolgt über ein Session-Cookie (HMAC-SHA256-signiert, 8h Lebensdauer). Setzen Sie ADMIN_PASSWORD, um sie zu aktivieren. Falls nicht gesetzt, gibt /admin 503 zurück.