Add-On Authoring Guide

This guide explains how to create, package, and ship a template add-on pack for the satware(r) AI OnlyOffice MCP server.

Quick Start

A customer image extends the base image and merges the add-on at build time:

FROM satware/onlyoffice-mcp:1.3.0-base AS base
COPY ./my-addon/ /tmp/addon/
RUN node dist/scripts/bake-addon.js /tmp/addon

Your add-on directory needs an addon.json manifest and optional templates/, assets/, and fonts/ subdirectories.

Manifest Reference

The addon.json file sits at the root of your add-on directory:

{
  "$schema": "./addon.schema.json",
  "id": "worms",
  "version": "1.0.0",
  "minBaseVersion": "1.3.0",
  "label": "Stadt Worms Template Pack",
  "description": "Corporate templates for Stadt Worms municipal administration",
  "priority": 10,
  "suppressedIds": ["beschlussvorlage"],
  "languages": ["de"]
}

Field	Type	Required	Description
`id`	`string`	Yes	Lowercase ASCII slug. Unique across loaded add-ons.
`version`	`string`	Yes	Semver version of this add-on pack.
`minBaseVersion`	`string`	Yes	Minimum base image version (X.Y.Z).
`label`	`string`	Yes	Human-readable display name.
`description`	`string`	No	Longer description.
`priority`	`number`	No	Merge precedence (default: 10). Higher wins on id collision.
`suppressedIds`	`string[]`	No	Base template IDs to hide.
`languages`	`string[]`	No	BCP-47 language codes (e.g. `["de"]`).

Directory Layout

my-addon/
  addon.json
  templates/
    registry.json
    my_template/
      v1.0/
        template.docbuilder
        schema.json
  assets/
    my_category/
      logo.base64
  fonts/
    montserrat-regular.ttf

Suppression

suppressedIds hides base templates your add-on supersedes:

Soft-disable: files stay on disk, hidden from API only
Absolute: applied after override (even add-on-provided ids are removed)
Idempotent: unknown ids produce a warning, not an error

Override by ID

Same-id add-on template wins over base. Resolution: higher priority wins; on tie, add-on wins over base.

Font Packaging

Formats: TTF, OTF, WOFF
Install path: /usr/share/fonts/truetype/addons/
Licensing: You are responsible for font license compliance

Versioning

minBaseVersion must be plain X.Y.Z (no pre-release suffixes)
Comparison uses semver rules
Mismatch = add-on rejected; server continues with base only
Base image tags are immutable - never retag

Testing

Use the upstream tests/fixtures/synthetic-addon/ as a reference fixture. Test the merge locally:

node dist/scripts/bake-addon.js ./my-addon --templates-dir ./templates --output /tmp/baked
cat /tmp/baked/registry.json | jq '.templates | keys'

Migration from Spec 003

Create addon.json manifest
Set minBaseVersion to your current base version
Move templates into templates/, assets into assets/, fonts into fonts/
Add suppressedIds for replaced base templates
Test with bake-addon locally
Switch Dockerfile to FROM base + COPY + RUN bake-addon