Skip to content
satware® AI OnlyOffice MCP

Template Contract Spec v1

Purpose

Section titled “Purpose”

This spec defines a stable, agent-readable contract for discovering, describing, validating, and creating Office documents from templates. It enables AI agents to answer user requests like “Welche Vorlagen gibt es?” or “Erstelle ein Schreiben auf Behoerdenbriefbogen” without hardcoding template knowledge.

Terminology

Section titled “Terminology”
Term Definition
Template Agent-facing document type that can be listed, described, validated, and created
Manifest Declarative JSON metadata and fill contract for one template version
Renderer Internal implementation that turns validated data into a document
Artifact Generated document returned as URL, base64, or MCP resource
Field A user-fillable value described in the manifest
Required field Document creation must not proceed without it (unless a default exists)
Optional field May be omitted; manifest may define default behavior

Tool Contract

Section titled “Tool Contract”

1. List Templates

Section titled “1. List Templates”

Returns available templates with enough detail for initial user choice.

Input:

Parameter Type Description
formats string[] Optional format filter (docx, xlsx, pptx, pdf)
category string Optional category filter
query string Optional natural-language search
language enum "de" or "en" (default: "de")
includeFields boolean Include field summaries (default: true)

Output: Array of template list items, each with id, name, description, category, primaryFormat, supportedFormats, requiredFields, optionalFields.

2. Describe Template

Section titled “2. Describe Template”

Returns the complete fill contract for one template.

Input:

Parameter Type Description
templateId string Template identifier
version string Template version (optional)
language enum "de" or "en" (default: "de")

Output: Full template manifest including JSON Schema, examples, field descriptions, validation rules, and suggested follow-up questions.

3. Validate Template Data

Section titled “3. Validate Template Data”

Validates user-supplied data before rendering.

Input:

Parameter Type Description
templateId string Template identifier
data object Data to validate
version string Template version (optional)

Output:

{
  "valid": true,
  "errors": [],
  "missingRequiredFields": [],
  "suggestedQuestions": []
}

4. Create Document

Section titled “4. Create Document”

Creates the Office artifact after validation.

Input:

Parameter Type Description
templateId string Template identifier
data object Validated template data
outputFormat enum docx, xlsx, pptx, or pdf
outputFilename string Custom filename (optional)
deliveryMethod enum url, base64, or resource (default: url)

Output: success, jobId, templateId, format, filename, artifact (or downloadUrl).

Template Manifest v1

Section titled “Template Manifest v1”

The planned manifest location is templates/<id>/<version>/manifest.json.

Required Fields

Section titled “Required Fields”
Field Type Description
manifestVersion const Must be "1.0"
id string Template identifier
version string Template version
names object Display names (de required, en optional)
descriptions object Descriptions (de required, en optional)
category string Template category
primaryFormat enum docx, xlsx, or pptx
supportedFormats string[] Array including pdf if export supported
fields Field[] Field definitions (see below)
validation object JSON Schema file reference
examples Example[] Sample data
renderer object Renderer type + template file

Field Types

Section titled “Field Types”
Type Description
string Plain text
date Date string (DD.MM.YYYY)
email Email address
phone Phone number
address Address object
person Person object (name, position, etc.)
object Nested object
array Array of values
enum Enumerated values
richText Multi-paragraph text

Field Definition

Section titled “Field Definition”
{
  "key": "Positionstitel",
  "label": "Positionstitel",
  "type": "string",
  "required": true,
  "description": "Job title",
  "askIfMissing": "Welche Position soll besetzt werden?",
  "group": "position"
}

Example

Section titled “Example”
{
  "name": "Minimal Example",
  "description": "Minimal valid data",
  "data": {
    "Positionstitel": "Software Engineer",
    "Fachbereich": "IT"
  }
}

Suggested Questions

Section titled “Suggested Questions”

The manifest can declare follow-up questions for missing required fields:

{
  "field": "Standort",
  "question": "An welchem Standort wird die Position angesiedelt?",
  "priority": "required"
}

User Workflow Example

Section titled “User Workflow Example”
User: "Erstelle eine Stellenbeschreibung fuer einen Software Engineer"
  |
  v
Agent calls: onlyoffice_list_templates({ query: "stellenbeschreibung" })
  |
  v
Agent calls: onlyoffice_describe_template({ templateId: "stellenbeschreibung" })
  -> Returns required fields + suggested questions
  |
  v
Agent asks user for missing required fields
  -> User provides: Fachbereich, Abteilung, Standort, etc.
  |
  v
Agent calls: onlyoffice_validate_template_data({ templateId, data })
  -> Returns: valid=true
  |
  v
Agent calls: onlyoffice_create_document({ templateId, data, outputFormat: "docx" })
  -> Returns: downloadUrl
Section titled “Related”