Web-Plattform-Integration

Übersicht

Der MCP-Server liefert generierte Dokumente über drei Methoden:

Methode	Auslöser	Antwortfeld	Größenlimit
Base64 (inline)	`ARTIFACTS_BASE_URL` nicht gesetzt	`data` (base64-String)	10 MB
Local URL	`ARTIFACTS_BASE_URL` gesetzt (stdio)	`downloadUrl` + `expiresAt`	Keins
S3 presigned URL	S3-Speicher aktiviert (HTTP)	`downloadUrl` + `expiresAt`	Konfigurierbar

Antwortformat

interface DocumentArtifact {
  // Base64 mode (when ARTIFACTS_BASE_URL is unset)
  data?: string;

  // URL mode (Local URL or S3/MinIO)
  downloadUrl?: string;
  expiresAt?: string;  // ISO 8601 timestamp

  // Common fields
  size: number;
  mimeType: string;
  filename: string;
  deliveryMethod: 'url' | 'base64';
  truncated?: boolean;
  truncationReason?: string;
}

MIME-Typen

Dokumenttyp	MIME-Typ	Erweiterung
Word	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	`.docx`
PowerPoint	`application/vnd.openxmlformats-officedocument.presentationml.presentation`	`.pptx`
Excel	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	`.xlsx`
PDF	`application/pdf`	`.pdf`

JavaScript-Handler

MCP-Tool-Ergebnis behandeln

async function handleDocumentGeneration(toolResult) {
  const content = toolResult.structuredContent || toolResult.content;

  if (!content.success) {
    throw new Error(content.error || 'Generation failed');
  }

  if (content.data) {
    // Inline base64
    return downloadFromBase64(content.data, content.filename, content.mimeType);
  } else if (content.downloadUrl) {
    // Presigned URL
    return downloadFromUrl(content.downloadUrl, content.filename);
  } else {
    throw new Error('No document data in response');
  }
}

Von base64 herunterladen

function downloadFromBase64(base64Data, filename, mimeType) {
  const blob = base64ToBlob(base64Data, mimeType);
  const url = URL.createObjectURL(blob);

  const link = document.createElement('a');
  link.href = url;
  link.download = filename;
  document.body.appendChild(link);
  link.click();
  document.body.removeChild(link);

  setTimeout(() => URL.revokeObjectURL(url), 100);
  return { success: true, filename, size: blob.size };
}

function base64ToBlob(base64, mimeType) {
  const bytes = atob(base64);
  const array = new Uint8Array(bytes.length);
  for (let i = 0; i < bytes.length; i++) {
    array[i] = bytes.charCodeAt(i);
  }
  return new Blob([array], { type: mimeType });
}

Von URL herunterladen

async function downloadFromUrl(downloadUrl, filename) {
  // Direct navigation (opens in new tab)
  window.open(downloadUrl, '_blank');
  return { success: true, filename, url: downloadUrl };
}

React-Integration

import { useState } from 'react';

function useDocumentGeneration() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const generate = async (template, data, format) => {
    setLoading(true);
    setError(null);
    try {
      const result = await callMcpTool('onlyoffice_generate_document', {
        template, data, format
      });
      return await handleDocumentGeneration(result);
    } catch (err) {
      setError(err.message);
      throw err;
    } finally {
      setLoading(false);
    }
  };

  return { generate, loading, error };
}

Artefakt-Lebenszyklus

URL-Modus-Artefakte sind temporär:

Server schreibt Dokument nach ARTIFACTS_DIR (oder S3-Bucket)
Gibt downloadUrl mit expiresAt-Zeitstempel zurück
Artefakt-Aufräumdienst entfernt abgelaufene Dateien (Standard-TTL: 1 Stunde)
Download-Endpunkt (/artifacts/<id>) bedient Dateien, solange gültig

Konfigurieren Sie die TTL über ARTIFACTS_TTL_SECONDS (Standard: 3600 = 1 Stunde).