Skip to content
satware® AI OnlyOffice MCP

Web Platform Integration

Overview

Section titled “Overview”

The MCP server delivers generated documents via three methods:

Method Trigger Response Field Size Limit
Base64 (inline) ARTIFACTS_BASE_URL unset data (base64 string) 10 MB
Local URL ARTIFACTS_BASE_URL set (stdio) downloadUrl + expiresAt None
S3 presigned URL S3 storage enabled (HTTP) downloadUrl + expiresAt Configurable

Response Format

Section titled “Response Format”
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 Types

Section titled “MIME Types”
Document Type MIME Type Extension
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

Section titled “JavaScript Handler”

  1. Handle the MCP tool result

    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');
      }
    }

  2. Download from base64

    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 });
    }

  3. Download from URL

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

React Integration

Section titled “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 };
}

Artifact Lifecycle

Section titled “Artifact Lifecycle”

URL-mode artifacts are temporary:

  1. Server writes document to ARTIFACTS_DIR (or S3 bucket)
  2. Returns downloadUrl with expiresAt timestamp
  3. Artifact cleanup service removes expired files (default TTL: 1 hour)
  4. Download endpoint (/artifacts/<id>) serves files while valid

Configure TTL via ARTIFACTS_TTL_SECONDS (default: 3600 = 1 hour).

Section titled “Related”