Table of Contents

  1. Ext: sg_ai
  2. SG AI for TYPO3: End-User Documentation
  3. AI Watermark Overlay API
  4. UPGRADE

Ext: sg_ai

sgalinski logo

License: GNU GPL, Version 3

Repository: https://gitlab.sgalinski.de/sg-ai/sg_ai

Please report bugs here: https://gitlab.sgalinski.de/sg-ai/sg_ai/-/work_items

Overview

sg_ai brings AI-assisted editorial workflows directly into TYPO3 backend forms and modules.

The extension covers:

  • Alt text generation for images (sys_file_reference and sys_file_metadata)
  • AI image generation in file fields (including automatic file reference creation)
  • AI text generation in configured text fields
  • SEO title/description generation for pages and social meta fields
  • Technical SEO, content SEO, and accessibility recommendations
  • Queue-based background processing for long-running operations
  • Backend activity history for queued/generated AI results, Chat Agent runs, and artifact generations (including credits, model, tokens, and duration)
  • Prompt persistence for image generation (including image settings block)
  • Automatic SEO-friendly image filename generation based on alt text

For end-user focused documentation, see:

Requirements

  • TYPO3 v13 LTS (13.4) or v14
  • PHP >= 8.3
  • Valid SG AI API key

Composer installs the required TYPO3 backend packages and the compatible sgalinski/sg-apicore release automatically. No sg_ai_core or sg_ai_api extension is required.

Installation

  1. Install extension:
composer require sgalinski/sg-ai
  1. Activate extension in Extension Manager.
  2. Run database schema updates in TYPO3 Install Tool / Admin Tools.
  3. Configure extension settings (see next section).

Configuration

Open:

  • Admin Tools > Settings > Extension Configuration > sg_ai

Available extension settings (ext_conf_template.txt):

  • apiKey
  • useImageAnalysis
  • useBase64Encoding
  • useContextForAltText
  • language
  • browserFetchPolicy
  • browserFetchAllowlist
  • watermarkEnabled
  • watermarkOverlayEnabled
  • watermarkPreserveMetadataOnProcessing
  • watermarkBadgeAssetPath
  • watermarkPosition
  • watermarkMargin
  • watermarkRelativeSize
  • watermarkMaxWidth
  • watermarkMaxHeight
  • watermarkOpacity
  • watermarkMinWidth
  • watermarkMinHeight
  • watermarkScreenReaderLabelEnabled
  • watermarkScreenReaderSuffix
  • watermarkOverlayAccessibilityLabel

Recommended API key setup:

  • Preferred: provide SG_AI_API_KEY as environment variable (for example in .env.local)
  • Alternative: set apiKey directly in extension configuration
  • sg_ai also resolves .env and .env.local lazily for TYPO3 CLI/queue processes if the shell process itself did not inherit the variable directly; this does not require symfony/dotenv to be installed by the host project

Backend advertisements

The backend modules can display a dismissible, localized notice about related sgalinski extensions. The notice follows the selected backend language and falls back to English. No project configuration is required.

AI Image Watermarking

  • Watermark overlays are applied via PSR-14 image-rendering events.

  • sg_ai provides a frontend SASS partial for overlay positioning at Resources/Public/Sass/Bootstrap5/_sg-ai.scss.

  • Theme integrations (for example project-theme) should import this partial.

  • watermarkEnabled=1 means watermark logic is active for images marked as AI-generated (tx_sgai_is_ai_generated in metadata or file references).

  • watermarkOverlayEnabled=1 enables frontend HTML/CSS overlay badge rendering (default: 0, disabled).

  • watermarkPreserveMetadataOnProcessing=1 sets SG AI provenance metadata during TYPO3 processing in the same ImageMagick call.

  • Mode-only override is available via sgAiWatermarkMode (on|off).

  • Structured per-call override is available via sgAiWatermarkOverride and supports: mode|enabled (on|off|true|false|1|0), badgeAssetPath, position, margin, relativeSize, maxWidth, maxHeight, opacity, minWidth, minHeight, overlayAccessibilityLabel, screenReaderSuffix, screenReaderLabelEnabled.

  • Default badge asset is a high-resolution PNG (Resources/Public/Icons/ai-watermark-badge.png).

  • Watermark badge sizing uses watermarkRelativeSize and is capped by default via watermarkMaxWidth / watermarkMaxHeight (80/80); set either to 0 for no cap.

  • Accessibility suffix behavior is configurable through watermarkScreenReaderLabelEnabled and watermarkScreenReaderSuffix and keeps alt and aria-label synchronized for non-decorative images.

  • Watermark badge accessibility text (alt/aria-label) is configurable through watermarkOverlayAccessibilityLabel and supports LLL translation references.

  • watermarkScreenReaderSuffix and watermarkOverlayAccessibilityLabel both support LLL translation references.

  • Optional overlay API integration for custom ViewHelpers is documented in Docs/Developer/WatermarkOverlayApi.md.

What the HTML overlay does:

  • It appends additional markup (<span class="sgai-watermark-overlay">...) to the rendered image/picture HTML.
  • CSS positions this badge absolutely on top of the image.
  • No image pixels are changed in this mode.
  • The required CSS contract and fallback examples are documented in Docs/Developer/WatermarkOverlayApi.md.

Integrator Example (Event-Based Integration)

After generating image markup, dispatch AfterImageRenderingEvent:

$event = new \SGalinski\SgAi\Event\AfterImageRenderingEvent(
	$imageHtml,
	$file,
	[
		'width' => $width,
		'height' => $height,
		'accessibleText' => $alternative,
		'isDecorative' => $alternative === '',
		'sgAiWatermarkOverride' => [
			'mode' => 'on',
			'badgeAssetPath' => 'EXT:site_package/Resources/Public/Icons/custom-ai-badge.svg',
			'maxWidth' => 40,
			'maxHeight' => 40,
		],
	]
);
$event = $eventDispatcher->dispatch($event);
$imageHtml = $event->getImageHtml();

Integrating Into Any Renderer (Recommended)

Use your existing image rendering pipeline and dispatch SGalinski\SgAi\Event\AfterImageRenderingEvent after generating image HTML. SG AI listens to this event and applies overlay/accessibility updates.

This keeps image rendering in one place and avoids duplicate integration paths.

Implementation outline:

  1. Render your image markup (<img> or <picture>) in your own ViewHelper/renderer.
  2. Create and dispatch AfterImageRenderingEvent with:
    • the rendered HTML
    • the resolved FileInterface
    • render context (width, height, accessibleText, isDecorative, optional override keys)
  3. Return getImageHtml() from the dispatched event object.

Integrator Example (Direct Overlay API)

For rendering pipelines without events, use:

$overlayService = GeneralUtility::makeInstance(\SGalinski\SgAi\Service\AiImageWatermarkOverlayService::class);
$overlayResult = $overlayService->buildPictureOverlayResult($file, [
	'width' => $width,
	'height' => $height,
	'accessibleText' => $alternative,
	'isDecorative' => $alternative === '',
	'sgAiWatermarkOverride' => [
		'mode' => 'on',
	],
]);

$overlayMarkup = (string) ($overlayResult['overlayMarkup'] ?? '');
if ($overlayMarkup !== '') {
	$imageHtml .= $overlayMarkup;
}

Why this pattern is recommended:

  • It avoids full-page HTML middleware scanning.
  • It keeps SG AI decision logic centralized and reusable.
  • It supports per-render overrides without custom data attributes.

Required Queue Setup (2.x)

Queue processing must be active for asynchronous tasks.

Required scheduler command:

vendor/bin/typo3 sg_ai:process-queue

Recommended execution interval:

  • every 5 minutes (*/5 * * * *)

Local worker mode for DDEV/manual testing:

vendor/bin/typo3 sg_ai:process-queue --watch --max-jobs=200 --max-seconds=600 --idle-sleep-ms=1000

Setup options:

  1. Backend shortcut:
    • Open module group AI Assistant > Dashboard
    • Click Create scheduler task now if inactive warning is shown for the queue worker
    • Optionally create additional tasks directly there:
      • sg_ai:cleanup-queue (daily)
      • sg_ai:cleanup-chat-attachments --limit=100 (daily; removes expired temporary chat uploads)
      • sg_ai:generate-seo-meta (nightly)
      • sg_ai:generate-alt-texts (early morning)
      • sg_ai:generate-ai-recommendations --limit=25 (weekly, can consume many credits)
  2. Manual scheduler setup:
    • Open TYPO3 Scheduler module and create Execute console commands tasks in group SGAI
    • Use the same command/interval recommendations as shown in the dashboard cards

TYPO3 MCP Chat Agent

sg_ai includes a hosted TYPO3 MCP chat-agent workflow inside the dedicated AI Chat Agent backend module.

Current scope:

  • submit one free-text instruction for one existing page
  • submit the request directly to the hosted SG AI runtime
  • let the hosted SG AI runtime read and update supported TYPO3 fields through MCP
  • choose Brave mode in the chat composer to auto-approve changes
  • disable Brave mode to keep the run in approval-required mode
  • use the default-enabled Self check toggle to run a final LLM verification after writes; Brave mode may repair safe mismatches, while approval mode is strictly review-only
  • disable Self check to skip the optional LLM review; deterministic read-back verification still protects every approved plan
  • poll the hosted runtime until the assistant message is completed
  • persist the final result locally for chat history and AI history views

Automatic connection setup:

  • no extra chat-agent token field must be configured manually in TYPO3 extension settings
  • when SGAI TYPO3 MCP is enabled, sg_ai now creates:
    • the user-facing TYPO3 MCP token for external MCP clients
    • a separate internal chat-agent token for the hosted SG AI runtime
  • the internal token and canonical MCP endpoint are registered automatically in the SG AI SaaS and reused per tenant/site
  • CLI and queue dispatches refresh a stale local MCP entitlement snapshot from /v1/credits automatically before sync/registration
  • chat-agent dispatches re-synchronize the MCP setup and re-register the SaaS-side connection automatically when needed
  • the outbound MCP host is still protected on the SaaS side by Typo3McpEndpointGuardService
  • chat-agent dispatch keeps the safer remote background transport by default
  • model selection for chat-agent rewrites is configured server-side in the SG AI SaaS runtime, not in TYPO3
  • the interactive chat module no longer depends on sg_ai:process-queue; only the SaaS queue worker must be active for live chat runs

Supported field scope:

  • page fields: title, subtitle, nav_title, abstract, description, seo_title, keywords
  • content types: text, textmedia
  • content fields: header, subheader, bodytext
  • unsupported content element types are skipped and shown in the final summary

How to use the chat agent:

  1. Open the standalone AI Chat Agent backend module from the Web menu. Its native TYPO3 page tree selects the context for the next message; it does not select a chat.
  2. Continue the active chat or open Chat history to select another conversation. Starting a new chat keeps the current page-tree selection as its initial context.
  3. Enter one concrete instruction for the context shown above the composer.
  4. Start the run and keep the SaaS queue worker active:
    • SaaS queue worker: vendor/bin/typo3 sg_ai_api:queue:work
  5. Follow the smooth chat transcript in the dedicated thread view and use the inline Reload backend or Open page actions to verify saved changes quickly.

Chat UI capabilities:

  • dedicated backend module with a ChatGPT-like thread/composer layout
  • fixed quick-start prompts for page review, SEO improvement, and English localization
  • sticky bottom composer with compact attachment, model, Brave-mode, usage, and send controls for fast iterative editing
  • next-message selection of site-visible skills and templates from the composer attachment menu; editor-selected artifacts are mandatory for that run while the automatic selector may still add other relevant guidance
  • click-accessible conversation-usage panel with message count, context-window consumption, and credit usage
  • closed-by-default history drawer with reusable recent sessions, last context, and affected scope
  • session actions to rename chats inline and pin important work; pinned chats stay above the recent chats in the order in which they were pinned, and the settings belong to the backend user across reloads
  • active chat, next-message page context, and affected operation scope tracked as separate state
  • contextless requests carry the configured site's default content language to the hosted runtime while replies follow the user's language
  • runs without a resolved or affected page use an empty scope and are never displayed as page UID 0
  • strict recent-activity ordering for history; selecting a page never changes the active chat
  • direct hosted-runtime polling from the chat module until the assistant message completes
  • chat-side MCP tool discovery uses the endpoint's stateless tools/list contract and caches the resulting schemas; it does not add a redundant initialize request per chat process
  • automatic restoration of the latest active thread after a backend reload
  • compact assistant details that can be expanded per message instead of consuming full-card space
  • individual chat instructions support up to 16,000 characters; a clear composer error is shown when the limit is exceeded
  • runtime details per assistant message including workflow, provider/model, token usage, remaining context-window budget, verification summary, debug IDs, and the artifacts loaded and sent to the run
  • explicit context-mode feedback for long chats, including checkpoint-resume status when a run continues from checkpoint memory
  • approval-gated proposals for edits and newly created tt_content elements when brave mode is disabled
    • each proposal carries a queue-safe, 24-hour signed receipt bound to its account, page, site, chat session, and exact MCP operations; approving it cannot start a new planning pass or apply a changed/cross-session proposal
  • hosted MCP tool calls require the signed initiating Backend User identity. The same active caller is used for TYPO3 history, durable audit data, and DataHandler writes with admin = false; there is no service-account or administrator fallback. Effective MCP access is the intersection of the managed SGAI MCP policy, token scopes, and the caller's actual TYPO3 table, field, page, and record rights.
  • attachment ingestion for images, PDFs, and text-like files with temporary storage by default and optional TYPO3 file promotion
  • one-shot composer attachments: a successfully submitted file remains visible on the originating user message but is removed from the composer before the next turn, preventing accidental repeated multimodal input and cost
  • PDF and image attachment extraction delegated to the SG AI SaaS through a dedicated extraction endpoint with checksum-based caching, so TYPO3 does not require local PDF binaries or local OCR tooling on shared-hosting setups

Debugging and tracing:

  • each assistant message exposes local TYPO3 IDs (messageUid, sessionUid, queueUid, resultUid) in Show details
  • the same details also expose the hosted SaaS remoteMessageId
  • new runs expose the loaded and injected artifacts by display name, type, and origin (Built-in or Tenant) without exposing their instruction bodies
  • use the local IDs to inspect tx_sgai_chat_message / tx_sgai_chat_session / persisted result history in TYPO3
  • use the remoteMessageId to inspect the hosted /v1/messages/{id} runtime state and profiler payloads
  • live progress labels are now intentionally descriptive (Reading TYPO3 context, Running MCP tools, Verifying TYPO3 result) instead of generic one-word placeholders
  • technical Show details rows after Operation summary are hidden by default; set SGAI_TYPO3_CHAT_AGENT_DEBUG_UI_ENABLED=1 in .env to expose verification, execution, context, runtime, routing, profiler, and debug identifiers
  • LLM verification is bounded by SGAI_TYPO3_CHAT_AGENT_MAX_VERIFICATION_ITERATIONS (default 3, absolute maximum 5). Individual skills may request fewer iterations; this setting is only the global safety ceiling.

Agent guidance

Completed assistant responses show a compact tooltip indicator when tenant-owned skills, templates, context packs, or workflows were selected for the turn. The tooltip lists the injected tenant guidance and the selector reason without exposing built-in system guidance or instruction bodies.

Use the standalone Agent guidance module to create reusable, tenant-owned guidance for the chat agent. Built-in guidance is intentionally not exposed for copying; tenant artifacts are editable, publishable, and assignable to one or more registered sites.

The visible Summary is the semantic description used by the AI selector. It must describe the outcome, applicable requests, and scope. Relevant tenant guidance has priority over system guidance for site-specific conventions, while compatible system guidance may be selected alongside it for general TYPO3 mechanics.

  • Skill: operational guidance for a tenant-specific content element, plugin, or TYPO3 capability.
  • Template: an ordered content blueprint. It defines the required content elements, columns (colPos), heading levels, content intent, and quality checks.
  • Context pack: reusable factual context such as a brand voice, terminology, or local editorial conventions.
  • Workflow: a reusable multi-step process with prerequisites, approval boundaries, and completion criteria.

Both creation actions first show a type chooser with a concise explanation and example for each artifact type. The help icon next to the creation actions provides the same guidance without exposing built-in artifact instructions.

The guidance library can be narrowed by type and status. Its default Active status view keeps archived guidance out of the way; select Draft, Published, Archived, or All when reviewing a specific lifecycle state. Sort guidance by most recently updated or by title.

The Dashboard’s Recent activity panel links to the detailed activity history. Its default All view collects supported request activity across the extension; use the SEO / Accessibility or Chat Agent filter to focus on that activity.

Create a draft manually or generate one from a page, content element, or current chat. The page and content-element context menus provide a separate AI group with direct Create skill and Create template actions. Both open Generate with AI with the selected record and artifact type prefilled. The active-chat action opens the same form with the current conversation prefilled and limits the choice to a skill. When chat is selected manually, the form searches the current backend user's locally loaded active conversations by title and shows each conversation's last-active date; it does not issue a search request or read diagnostic traces. The page source uses the same local search pattern for readable pages, displaying title and page ID while also accepting a page ID typed directly into the field. Hidden pages remain available when the backend user has page-show permission. When a skill or template is generated from a content element, its source context includes the selected record type's visible TCA fields and parsed FlexForm values. For visible TCA inline relations, it also includes the readable child hierarchy up to three levels deep. Only relations whose table-select permission and page mount are available to the current backend user are included, and TCA fields marked as exclude require their explicit field permission. This lets generated guidance preserve nested placement and ordering instead of treating a child record as an independent bodytext element. Review the generated Markdown, save it as a draft, assign the artifact to the intended sites, and publish it. The chat agent sees compact catalog metadata first and hydrates the full artifact only when its LLM selector chooses it for the task. Opening a published artifact without a newer working draft exposes Unpublish; this returns it to draft status and removes it from the active catalog while preserving its published version history.

Artifact keys are created server-side as stable, account-unique slugs. Editors do not enter or change them; an existing artifact shows its generated key as read-only context.

Website context scan

After MCP setup, Create website context is available in Agent guidance. Choose a TYPO3 site when more than one is configured. The scan always uses the public homepage and at most three public first-level navigation pages in the site default language. It makes one model request with the fixed SGAI_TYPO3_CHAT_AGENT_MODEL, creates an assigned unpublished Context Pack draft, and never publishes it to the agent runtime automatically.

The scan is capped at 20 credits. It uses an eight-second selected-site-only fetch with three redirects and 12,000 clean characters per page. Raw HTML and full page text are not retained; the draft provenance shows source URLs, resolved URLs, content hashes, and unreadable-page warnings for review.

Current limitations:

  • no undo workflow
  • a started hosted request cannot be stopped until the runtime moves from polling to a streaming transport

SGAI MCP Auto-API Setup

sg_ai can automatically expose a site-scoped MCP API (sgai_mcp) via sg_apicore.

Important: there are two different MCP servers

To avoid confusion, treat these as separate integrations:

  • SGAI Cloud MCP: your existing MCP for SG AI platform functions (external to TYPO3).
  • SGAI TYPO3 MCP: the MCP auto-generated by this extension for TYPO3 content/data access.

They use different endpoints and usually different tokens. Tokens are not interchangeable.

Recommended client naming:

  • sgai for SG AI platform MCP (existing/released name)
  • sgai_typo3 for TYPO3 MCP (sgai_mcp)

Setup flow:

  1. Open AI Assistant > Dashboard
  2. In SGAI TYPO3 MCP, review the entitlement state shown in the card:
    • Included: TYPO3 MCP is available on the current SG AI subscription
    • Trial: a 14-day TYPO3 MCP trial is active
  • Upgrade required: TYPO3 MCP is not available until the SG AI account uses Silver or above
    • Expired: previously active TYPO3 MCP access is no longer active
  1. If the card shows Upgrade required and the account is eligible, click Start 14-day TYPO3 MCP trial.
  2. Once the card shows Included or Trial, choose the target site and click Enable SGAI TYPO3 MCP
  3. Copy the one-time token shown in the modal (it is not shown again on reruns)

Canonical MCP endpoint:

  • /api/sgai_mcp/v1/mcp

Compatibility alias endpoint:

  • /sgai_mcp/mcp

Behavior:

  • v1 supports one active target site per TYPO3 instance.
  • TYPO3 MCP access is driven by the locally stored package and trial state in TYPO3.
  • TYPO3 MCP setup and runtime usage are available only when the locally stored state allows it:
  • paid access through Silver or above, or
    • an active 14-day TYPO3 MCP trial
  • Permissions are compiled from backend group SGAI MCP (tables_select, tables_modify, non_exclude_fields).
  • Permission changes on that group trigger immediate sync; fallback sync is available via scheduler/CLI:
    • vendor/bin/typo3 sg_ai:mcp:sync
  • Fail-closed: if the managed SGAI MCP backend group is missing, compiled MCP resources are cleared until setup/sync is run again.
  • Opening the SG AI dashboard refreshes the local package snapshot from /v1/credits.
  • MCP runtime uses only the local snapshot and never performs a remote entitlement request in the request path.
  • If the local trial is expired or the last known package state is stale or not eligible, setup and runtime usage stay blocked until the dashboard refreshes the package snapshot again.

How MCP setup works internally

When you click Enable SGAI TYPO3 MCP, sg_ai performs a deterministic sync, not a one-time wizard:

  1. Resolves the selected site (or auto-selects when exactly one site exists).
  2. Creates or updates backend group SGAI MCP with default table/field permissions and DB mount.
  3. Compiles MCP resources and scopes from that group:
    • tables_select -> list,get
    • tables_modify -> create,update,delete
    • special case: sys_file stays a read-only MCP resource, but tables_modify=sys_file still compiles the write scope sgai_mcp:sys_file:write for upload tools
  4. Creates or reuses one token for API sgai_mcp and synchronizes its scopes.
  5. Persists setup state (site/group/token/resource/signature/timestamp) in TYPO3 registry.
  6. Invalidates API/discovery caches.

Repeated clicks are safe and expected:

  • If configuration changed, they resynchronize state/resources/scopes.
  • If token already exists and is reusable, it is reused (no historical plaintext token is shown again).
  • A new plaintext token is returned only when a new token record had to be created.

Automatic synchronization, including the backend-group DataHandler hook and chat connection refresh, compiles the current SGAI MCP group exactly as an administrator saved it. It never regenerates default table or field permissions, so removing a permission cannot be undone by a background sync. Explicitly running Enable SGAI TYPO3 MCP again is the administrator-controlled action that regenerates the managed group defaults.

Dashboard behavior:

  • Before setup, the dashboard card shows one of four entitlement states:
    • Included
    • Trial
    • Upgrade required
    • Expired
  • Depending on that entitlement state, the primary action becomes:
    • Enable SGAI TYPO3 MCP
    • Start 14-day TYPO3 MCP trial
    • or a disabled setup button plus Manage plan
  • After setup, the card switches to Disable SGAI TYPO3 MCP and exposes compact TYPO3 MCP client configuration examples inline.
  • Disabling MCP hides the managed backend group, revokes the active token, clears compiled MCP state, and removes the MCP surface until setup is run again.
  • The card also shows the current plan, optional trial end timestamp, and the last successful entitlement check.

When a new token is created

A new MCP token is created only if no reusable token can be found:

  • The stored preferred token UID is missing/invalid/revoked/deleted, and
  • No active reusable token exists for api_id=sgai_mcp + selected tenant/site.

Otherwise the existing token is reused and updated (scopes, tenant, pid, label).

MCP client configuration (Codex, Cursor, Junie, ...)

sg_ai exposes a standard HTTP MCP endpoint. For Codex-style clients, configure:

  • URL: canonical /api/sgai_mcp/v1/mcp (or alias /sgai_mcp/mcp)
  • Auth: use bearer_token_env_var

Recommended: use the canonical endpoint in clients and keep alias only for backward compatibility.

Use separate environment variables for the two MCP tokens:

  • SGAI_API_TOKEN for SG AI platform MCP (existing)
  • SGAI_TYPO3_API_TOKEN for TYPO3 MCP

Example shell exports:

export SGAI_API_TOKEN="..."
export SGAI_TYPO3_API_TOKEN="..."

Example (Codex-style TOML, TYPO3 MCP only):

[mcp_servers.sgai_typo3]
bearer_token_env_var = "SGAI_TYPO3_API_TOKEN"
transport = "http"
url = "https://your-site.example/api/sgai_mcp/v1/mcp"

Example (Codex-style TOML, both MCP servers):

[mcp_servers.sgai]
bearer_token_env_var = "SGAI_API_TOKEN"
transport = "http"
url = "https://sgai.mateevsolutions.com/api/sgai/v1/mcp"

[mcp_servers.sgai_typo3]
bearer_token_env_var = "SGAI_TYPO3_API_TOKEN"
transport = "http"
url = "https://your-site.example/api/sgai_mcp/v1/mcp"

Example (JSON-style clients such as Cursor/Junie variants, TYPO3 MCP only):

{
  "mcpServers": {
    "sgai_typo3": {
      "transport": "http",
      "url": "https://your-site.example/api/sgai_mcp/v1/mcp",
      "bearer_token_env_var": "SGAI_TYPO3_API_TOKEN"
    }
  }
}

tt_content positioning for MCP clients

When creating TYPO3 content elements through sgai_typo3, the default TYPO3 behavior is position=top.

For tt_content create endpoints, the generated MCP/OpenAPI description now exposes two optional request fields:

  • position: top, bottom, or after
  • afterUid: required when position=after

Behavior:

  • top: insert at the top of the target placement context
  • bottom: insert after the last sibling in the same pid, colPos, and sys_language_uid context
  • after: insert directly after an existing tt_content record

Notes for MCP clients:

  • position defaults to top if omitted.
  • afterUid must reference an existing tt_content record.
  • If position=after and pid, colPos, or sys_language_uid are omitted, they are inherited from the referenced record.
  • For column-aware placement, pass colPos when that field is available in the resource schema.
  • To reorder already existing content elements, use the dedicated MCP tool move_content_after instead of tt_content.update.

AI image generation flow for MCP clients

sgai_typo3 exposes dedicated MCP tools for TYPO3 images:

  • generate_and_attach_image_to_content
  • generate_and_attach_image_to_page
  • generate_and_attach_image_to_resource

This is the preferred image workflow for MCP clients. The TYPO3 backend uses its configured SG AI API key, generates the image server-side, stores it in TYPO3 FAL, creates the sys_file_reference, and attaches it to the correct TYPO3 media field for the target record.

Recommended flow for adding an image to tt_content.image:

  1. Create the target content element.
  2. Call generate_and_attach_image_to_content in sgai_typo3.

Example tool arguments:

{
  "contentUid": 456,
  "prompt": "Editorial hero image about TYPO3 AI workflows, modern office scene, realistic, clean composition",
  "imageSize": "landscape_16_9",
  "outputFormat": "png"
}

Expected result:

{
  "contentUid": 456,
  "fileUid": 123,
  "fileReferenceUid": 987,
  "publicUrl": "/fileadmin/user_upload/ai_generated/editorial-hero-image.png",
  "altText": "Editorial hero image about TYPO3 AI workflows",
  "usage": {
    "credits": 10.0
  }
}

Notes:

  • sgai_typo3 still exposes sys_file as a read-only resource so stored files can be listed and found later.
  • The tool requires a configured SG AI API key in the TYPO3 backend.
  • Successful responses include nested SG AI usage metadata when the backend image generation API returns it.
  • It requires sgai_mcp:tt_content:write, sgai_mcp:sys_file:write, sgai_mcp:sys_file_reference:write, and sgai_mcp:sys_file_metadata:write.
  • For CType=textmedia, generate_and_attach_image_to_content writes to tt_content.assets. For standard image-based content elements, it usually writes to tt_content.image.
  • tt_content.image is a built-in non-exclude field in TYPO3, so no separate non_exclude_fields entry is required for it.
  • generate_and_attach_image_to_page works for pages.media and pages.og_image, defaults to media, and requires sgai_mcp:pages:write plus the same file-related write scopes. Because both page fields are exclude fields, the managed backend group must allow pages:media and/or pages:og_image for the targets you want to use.
  • generate_and_attach_image_to_resource targets an existing custom or inline Resource record and an exact writable TCA file field from the live managed-group catalog. It resolves the owning page through the Resource ownership chain before generating the file and creating the FAL reference.

For a newly generated image on a custom or Mask child record, use generate_and_attach_image_to_resource directly:

{
  "recordType": "tx_mask_sg_slide_items",
  "recordUid": 408,
  "fieldName": "tx_mask_sg_slide_image",
  "prompt": "Wide editorial photograph of a kitten",
  "imageSize": "landscape_16_9",
  "outputFormat": "png"
}

In approval mode, use the semantic resource.image.generate operation. Its resource may be an existing UID or the handle of a matching resource.create operation in the same plan. This keeps record creation, UID resolution, image generation, and FAL attachment deterministic without requiring the model to construct sys_file_reference fields.

To reuse an already existing fileUid on another custom or Mask child record, use the generated sys_file_reference.create Resource tool. The destination is available only when all of these conditions are true:

  • the destination table is writable for the MCP Backend User group;
  • the exact destination field is writable and is a live TCA file field (legacy FAL inline fields are also supported);
  • sg_apicore can resolve the destination record through pid or a deterministic inline-parent chain;
  • the calling Backend User can modify both sys_file_reference and the destination table and has edit rights on the owning page.

Approval-mode plans can connect earlier operation results without model-invented UIDs. For example, after generating an image and creating a Mask slider item, the attachment operation can use:

{
  "kind": "resource.create",
  "recordType": "sys_file_reference",
  "toolName": "sgai_mcp_post_sys_file_reference",
  "arguments": {
    "pid": 905,
    "uid_local": { "$ref": { "handle": "kittenImage", "output": "fileUid" } },
    "uid_foreign": { "$ref": { "handle": "slideItem", "output": "uid" } },
    "tablenames": "tx_mask_sg_slide_items",
    "fieldname": "tx_mask_sg_slide_image"
  }
}

pid is the UID of the page resolved through the destination ownership chain, not the destination record UID. The server-declared contract binds the exact table and field and rejects forged selectors, cross-page ownership, stale non-FAL fields, and missing destination-table permissions before DataHandler runs.

Localize a page before editing translated fields

Use localize_page to create or reuse the translated page record first. Then call pages.update on the returned localizedPageUid.

Example flow:

  1. localize_page with: 
    {
  "pageUid": 123,
  "languageUid": 1
}
  2. pages.update on the returned localized page UID with translated fields such as title, slug, description, or seo_title.

Generic page and content updates cannot change TYPO3 placement or localization fields (pid, language IDs, localization parents/sources, content column, or sorting). Dedicated localization and move operations own those invariants. When an existing native localization has a missing l10n_source, the dedicated localization service repairs the source pointer before returning the existing record. MCP resource maps also exclude TYPO3's internal l18n_diffsource payload, which is not useful to the agent and can otherwise make content-list responses unnecessarily large.

Approval is recorded as an action on the staged assistant proposal. It does not create a synthetic user chat message. The follow-up execution inherits the proposal's reply language independently of the TYPO3 Backend interface locale.

Browser-style page read-back for MCP clients

sgai_typo3 now also exposes:

  • fetch_site_page

Use this tool when the LLM needs rendered frontend read-back after page or content changes. The tool fetches a real frontend URL through TYPO3's HTTP client and returns compact page content plus metadata such as title, language, statusCode, and the resolved finalUrl.

Security and runtime behavior:

  • allowed URLs are controlled by browserFetchPolicy in extension configuration (open, same_site_only, allowlist)
  • browserFetchAllowlist accepts one URL prefix per line and is used only when the policy is allowlist
  • default output is cleaned text (stripTags=true) so the response stays useful for LLM context windows
  • set stripTags=false only when rendered HTML structure matters
  • redirects are re-checked against the active policy
  • non-HTML/text payloads such as PDFs are rejected

Example tool arguments:

{
  "url": "https://example.test/news/my-article",
  "maxLength": 12000
}

Filtering examples for MCP clients

List endpoints use the filter shape filter[field]=value.

Typical pages examples:

{
  "filter": {
    "title": "News"
  }
}

{
  "filter": {
    "slug": "/news"
  }
}

Do not send title or slug as top-level arguments for list tools. They must be nested inside filter.

Client notes:

  • Keep tokens in environment variables or client secret storage. Do not hardcode credentials in VCS.
  • If you rotate/revoke token records in TYPO3, update client configs with the new token.
  • Effective tool/resource exposure is driven by the SGAI MCP backend group's permissions and token scopes.

Backend Usage

Modules

  • AI Assistant (/module/web/ai-assistant)
    • Backend module group for SG AI workflows
  • Dashboard (/module/web/sg-ai-dashboard)
    • Overview for all SG AI modules, onboarding checklist, scheduler status/setup
    • Shows real queue health (pending, processing and failed jobs) plus the latest completed activity
  • AI Page Insights (/module/web/sg-ai)
    • Unified workspace for analysis and history (tabs in one module)
    • Run URL checks, trigger recommendation tasks, monitor active queue work, and inspect/reuse past results
    • The credits badge is resolved from the live /v1/credits response on each backend render; API failures show 0 instead of a cached snapshot
  • Legacy AI History URL (/module/web/sg-ai-history)
    • Redirects to the unified AI Page Insights history tab for backward compatibility

Field Controls

Depending on TCA configuration and field type, backend forms can show:

  • Generate alt text button
  • Generate image button
  • Generate text button
  • Generate SEO title/description buttons
  • Generate technical/content/a11y recommendation buttons

Generated images are marked as AI-generated in TYPO3 metadata/reference flags (tx_sgai_is_ai_generated) and receive automatic alt text handling. If the SG AI image response provides provenance/generation metadata, sg_ai preserves it for generated originals by mapping values into sys_file_metadata (for example creator, creator_tool, source, copyright, description, title). Additionally, sg_ai writes AI provenance markers for generated originals:

  • IPTC/XMP Digital Source Type (trainedAlgorithmicMedia URI)
  • AI system fields (system name/version and model name) when provided by the API response
  • A normalized provenance summary in TYPO3 sys_file_metadata.note

For processed image variants, SG AI can add this provenance metadata within TYPO3's processing command (watermarkPreserveMetadataOnProcessing, default 1). Metadata persistence in image binaries depends on file format and ImageMagick/GraphicsMagick capabilities. In practice, PNG/JPEG usually keep more metadata than WEBP in many environments. SG AI still attempts metadata embedding for all processed target formats as best effort.

EU AI Act transparency support is declared at extension metadata level (ext_emconf.php and composer.json), not as an image-embedded compliance statement.

EU AI Act (Pragmatic Note)

This extension provides technical support for transparency workflows:

  • AI-generated image marking (tx_sgai_is_ai_generated)
  • Optional visual watermark overlays in frontend output
  • Accessible label suffixes for non-decorative AI images
  • Provenance metadata best effort during image processing
  • Prompt/result traces in TYPO3 data structures for editorial review
  • AI-generated text/recommendation outputs are persisted in TYPO3 records and queue/history tables for review before publication

Integrators are responsible for deciding where and when labels/disclosures are shown, based on their legal and organizational requirements. This extension does not provide legal advice.

Not Yet Added: C2PA Manifest Signing

sg_ai does not yet add a C2PA manifest to generated images.

What this would provide:

  • A cryptographically signed provenance manifest embedded in or bound to the image
  • Verifiable claim of origin and transformation chain (tamper-evident)
  • Stronger interoperability with Content Credentials / C2PA-aware verification tools

Why this is separate from ordinary metadata:

  • XMP/IPTC fields are editable metadata and are not cryptographically protected by default
  • C2PA requires a signing pipeline (private key management, certificates, manifest generation, and signature validation strategy)
  • Operationally this introduces trust infrastructure and key-rotation requirements that must be configured per environment

Planned scope for a future implementation:

  • Optional C2PA signer integration (disabled by default)
  • Configurable key/certificate handling and signer identity
  • Fail-safe behavior (image generation still succeeds if signing is unavailable, with explicit logging)

Queue and History Behavior

  • Long-running tasks are enqueued and processed asynchronously.
  • Queue records are persisted in tx_sgai_queue.
  • Results/history are persisted in tx_sgai_url_check.
  • Remote background processing (HTTP 202/message ID) is supported and finalized via queue polling.
  • Queue entries store cloud tracking metadata (remote_message_id, remote_status) for remote runs.
  • History views support search, sorting, pagination, and result preview via View action.
  • If the cloud API rate limits (HTTP 429), processing is deferred and retried safely.

Image Generation Behavior

  • The last image prompt is persisted and reused per record/field (tx_sgai_last_image_prompt).
  • Prompt persistence keeps the image settings comment block, including image_size and output_format.
  • Generated images are automatically marked as AI-generated (tx_sgai_is_ai_generated).
  • AI-generated images can be watermarked automatically during rendering based on extension configuration.
  • Generated images can be renamed from alt text to SEO-friendly slugs.
  • Renamed files are capped at 60 characters total (including hash suffix and extension).

TCA Configuration Example (AI Image Generation)

'images' => [
	'config' => [
		'sg_ai' => [
			'promptProvider' => 'Vendor\\Extension\\PromptProvider\\CustomPromptProvider',
			'promptTemplate' => 'Generate an image for ###title### with ###category### theme',
			'disabled' => true,
			'image_size' => 'landscape_16_9',
			'output_format' => 'png',
		],
		'type' => 'file',
	],
],

Supported image size presets:

  • square_hd
  • square
  • portrait_4_3
  • portrait_16_9
  • landscape_4_3
  • landscape_16_9

You can also pass custom dimensions:

  • ['width' => 1280, 'height' => 720]

CLI Commands

Alt text generation

vendor/bin/typo3 sg_ai:generate-alt-texts

Options:

  • --limit
  • --dry-run

SEO meta generation

vendor/bin/typo3 sg_ai:generate-seo-meta [page-uid]

Options include:

  • --force
  • --title-only
  • --description-only
  • --limit
  • --exclude-hidden
  • --exclude-deleted

AI recommendations generation

vendor/bin/typo3 sg_ai:generate-ai-recommendations [page-uid]

Options include:

  • --force
  • --accessibility-only
  • --content-seo-only
  • --technical-seo-only
  • --limit
  • --exclude-hidden
  • --exclude-deleted

Queue operations

Process queue:

vendor/bin/typo3 sg_ai:process-queue

Run the local queue as a temporary daemon:

vendor/bin/typo3 sg_ai:process-queue --watch --max-jobs=200 --max-seconds=600 --idle-sleep-ms=1000

List queue:

vendor/bin/typo3 sg_ai:list-queue

Cleanup queue/results:

vendor/bin/typo3 sg_ai:cleanup-queue

Preview a cleanup before it changes data:

vendor/bin/typo3 sg_ai:cleanup-queue --days=30 --dry-run

Cleanup expired temporary chat attachments in a bounded batch:

vendor/bin/typo3 sg_ai:cleanup-chat-attachments --limit=100

MCP and chat-agent operations

Synchronize the managed MCP group, token, resources, and scopes for a site:

vendor/bin/typo3 sg_ai:mcp:sync --site=website

Dispatch one chat-agent instruction through the local queue. Add --wait to poll for the remote result:

vendor/bin/typo3 sg_ai:chat-agent 42 "Create an introductory paragraph" --wait

Run a multi-turn chat-agent scenario against one page and print diagnostic JSON:

vendor/bin/typo3 sg_ai:chat-agent:session-harness 42 --instruction="Summarize this page" --instruction="Expand the summary" --json

Preview the migration of legacy chat approval payloads before changing stored messages:

vendor/bin/typo3 sg_ai:migrate:chat-approval-payloads --dry-run

The migration processes records in batches; use --batch-size to adjust the batch size up to 1000 rows.

Troubleshooting

  • Tasks stay pending:
    • verify scheduler task exists and is enabled
    • run one manual queue cycle: vendor/bin/typo3 sg_ai:process-queue --limit=5
    • for local chat-agent testing keep a watch worker running: vendor/bin/typo3 sg_ai:process-queue --watch --max-jobs=200 --max-seconds=600 --idle-sleep-ms=1000
    • for multi-turn context stress tests use vendor/bin/typo3 sg_ai:chat-agent:session-harness 685 --instruction="Translate the page to English." --instruction="Make the content much longer." --instruction="Add another summary paragraph." --model="deepseek/deepseek-v4-flash" --json
    • the harness keeps one TYPO3-side chat session, polls the hosted remoteMessageId directly, and reports checkpoint/resume/rollover diagnostics turn by turn
    • if --model is omitted, the harness uses the regular chat-agent default model from .env (SGAI_TYPO3_CHAT_AGENT_MODEL)
  • API key error:
    • check SG_AI_API_KEY / extension configuration
  • URL/page checks fail:
    • ensure target pages are publicly reachable for checks that require rendered output

Testing

Run extension checks from the project root:

composer phpunit vendor/sgalinski/sg-ai
composer phpstan vendor/sgalinski/sg-ai
composer ecs vendor/sgalinski/sg-ai

If you update to the chat-agent session UI, run the database schema migration first as documented in UPGRADE.md.

SG AI for TYPO3: End-User Documentation

This guide explains how to use the sg_ai TYPO3 extension in daily editorial work.

It is focused on:

  • real backend workflows for editors and SEO managers
  • all user-facing buttons introduced by the extension
  • setup and configuration that affects behavior
  • practical benefits, limits, and troubleshooting

For extension-level setup and upgrade notes, also see:

1. Purpose of the Extension

sg_ai adds AI-assisted content and quality workflows directly into TYPO3 backend forms.

Main goals:

  • speed up content production
  • improve SEO and accessibility quality
  • reduce repetitive manual work for editors
  • standardize outputs across large teams

The extension currently covers:

  1. Alt text generation for images
  2. AI image generation for file fields
  3. AI text generation for RTE content
  4. SEO title and description generation for pages
  5. AI-powered technical/content SEO recommendations
  6. AI-powered accessibility recommendations
  7. URL checks in the backend module
  8. bulk processing through CLI commands

2. Target Users and Responsibilities

Editors

  • generate text, images, and alt text
  • refine generated output before publishing
  • trigger page-level recommendation generation

SEO / Accessibility Managers

  • review scores and recommendation tables
  • prioritize fixes by impact
  • re-run checks after content updates

TYPO3 Administrators / Integrators

  • configure API access and defaults
  • control field-level behavior in TCA
  • automate bulk generation via commands

3. Prerequisites

Before users can work with the buttons:

  1. The extension sg_ai must be installed and active.
  2. Queue processing must be active by creating the TYPO3 scheduler task sg_ai:process-queue.
  3. SG AI API credentials must be configured.
  4. Editors need backend access to the affected records/tables.
  5. For URL/page-based checks, the checked page must be reachable as rendered HTML.

3.1 Required queue activation (TYPO3 2.x)

Queue processing is mandatory in 2.x for asynchronous workflows (recommendations, history updates, remote background results).

Recommended setup path:

  1. Open Web > AI Assistant > Dashboard.
  2. If the warning Scheduler task inactive is shown, click Create scheduler task now for sg_ai:process-queue.
  3. Add the additional recommended scheduler tasks from the dashboard:
    • sg_ai:cleanup-queue (daily)
    • sg_ai:generate-seo-meta (nightly)
    • sg_ai:generate-alt-texts (early morning)
    • sg_ai:generate-ai-recommendations --limit=25 (weekly; may consume many credits)

Recommended execution interval for sg_ai:process-queue: every 5 minutes (*/5 * * * *).

3.2 Optional MCP auto-API setup (sgai_mcp)

If you want to connect MCP clients directly to TYPO3 content data:

Important distinction:

  • SGAI Cloud MCP = your existing SG AI platform MCP server.
  • SGAI TYPO3 MCP = this extension's TYPO3 MCP server (sgai_mcp).

Use separate client names and tokens for these two servers.

  1. Open Web > AI Assistant > Dashboard.
  2. In SGAI TYPO3 MCP, first check the access state shown in the card:
    • Included: TYPO3 MCP is available on the current SG AI subscription
    • Trial: a 14-day TYPO3 MCP trial is active
    • Upgrade required: TYPO3 MCP is not yet available; switch to Silver or above
    • Expired: previous TYPO3 MCP access is no longer active
  3. If Upgrade required is shown and the account is eligible, start the 14-day TYPO3 MCP trial.
  4. Once the state is Included or Trial, select one target site and run Enable SGAI TYPO3 MCP.
  5. Save the shown token immediately (it is shown once only).

Endpoints:

  • Canonical: /api/sgai_mcp/v1/mcp
  • Compatibility alias: /sgai_mcp/mcp

Notes:

  • v1 supports one active target site per TYPO3 instance.
  • TYPO3 MCP access is controlled by the locally stored package and trial state in TYPO3.
  • TYPO3 MCP is available only for:
    • SG AI subscriptions from Silver upwards
    • or an active 14-day TYPO3 MCP trial
  • The setup manages backend group SGAI MCP and compiles resources/scopes from that group's table/field permissions.
  • Permission changes are synced immediately; fallback command: sg_ai:mcp:sync.
  • Opening the SG AI dashboard refreshes the local package snapshot from /v1/credits.
  • MCP runtime uses only the local snapshot and never performs a remote entitlement request in the request path.
  • If the local trial is expired or the last known package state is stale or not eligible, setup and runtime usage stay blocked until the dashboard refreshes the package snapshot again.

How setup behaves:

  1. Setup is idempotent and can be executed multiple times.
  2. Re-running setup resynchronizes group permissions, resources, scopes, and cache state.
  3. The token is only shown in plaintext when a new token was created.
  4. If a reusable token already exists, it is reused and not shown again.
  5. After setup, the dashboard card switches from Enable SGAI TYPO3 MCP to Disable SGAI TYPO3 MCP and shows compact TYPO3 MCP client configuration examples inline.
  6. Disabling MCP revokes the active token, hides the managed backend group, and removes the MCP surface until setup is run again.
  7. The card shows the current plan, trial end date if applicable, and the last local package refresh timestamp.

When a new token is created:

  • No valid preferred token exists from previous setup state, and
  • No reusable token is found for API sgai_mcp + selected site/tenant.

3.3 MCP client configuration (Codex/Cursor/Junie)

Use the token from setup and configure your MCP client (Codex) with HTTP transport:

  • URL: https://your-site.example/api/sgai_mcp/v1/mcp
  • Auth: use bearer_token_env_var (Codex-style)

Recommended naming:

  • sgai for SG AI platform MCP (existing/released name)
  • sgai_typo3 for TYPO3 MCP

Recommended environment variables:

  • SGAI_API_TOKEN
  • SGAI_TYPO3_API_TOKEN

Codex-style TOML (TYPO3 MCP):

[mcp_servers.sgai_typo3]
bearer_token_env_var = "SGAI_TYPO3_API_TOKEN"
transport = "http"
url = "https://your-site.example/api/sgai_mcp/v1/mcp"

Codex-style TOML (both MCP servers):

[mcp_servers.sgai]
bearer_token_env_var = "SGAI_API_TOKEN"
transport = "http"
url = "https://sgai.mateevsolutions.com/api/sgai/v1/mcp"

[mcp_servers.sgai_typo3]
bearer_token_env_var = "SGAI_TYPO3_API_TOKEN"
transport = "http"
url = "https://your-site.example/api/sgai_mcp/v1/mcp"

JSON-style client example (Cursor/Junie variants, TYPO3 MCP):

{
  "mcpServers": {
    "sgai_typo3": {
      "transport": "http",
      "url": "https://your-site.example/api/sgai_mcp/v1/mcp",
      "bearer_token_env_var": "SGAI_TYPO3_API_TOKEN"
    }
  }
}

3.4 tt_content positioning for MCP clients

By default, TYPO3 inserts newly created tt_content records at the top.

For tt_content create endpoints, the generated MCP/OpenAPI schema exposes these optional request fields:

  • position: top, bottom, or after
  • afterUid: required when position=after

How they work:

  • top: insert at the top of the target context
  • bottom: insert after the last sibling in the same pid, colPos, and sys_language_uid context
  • after: insert directly after an existing tt_content element

Important:

  • If position is omitted, top is used.
  • afterUid must point to an existing tt_content record.
  • If position=after and you do not send pid, colPos, or sys_language_uid, TYPO3 inherits them from the referenced record.
  • If you want deterministic placement within a column, send colPos when it is available in the endpoint schema.
  • To reorder already existing content elements, use the dedicated MCP tool move_content_after instead of tt_content.update.

3.5 AI image generation flow for MCP clients

sgai_typo3 provides one dedicated MCP tool for TYPO3 content images:

  • generate_and_attach_image_to_content
  • generate_and_attach_image_to_page

This is the preferred image workflow for MCP clients. The TYPO3 backend uses its configured SG AI API key, generates the image server-side, stores it in TYPO3 FAL, creates the sys_file_reference, and attaches it to the correct TYPO3 media field for the target record.

Recommended flow for tt_content.image:

  1. Create the target content element.
  2. Call generate_and_attach_image_to_content in sgai_typo3.

Example call:

{
  "contentUid": 456,
  "prompt": "Editorial hero image about TYPO3 AI workflows, modern office scene, realistic, clean composition",
  "imageSize": "landscape_16_9",
  "outputFormat": "png"
}

Expected result:

{
  "contentUid": 456,
  "fileUid": 123,
  "fileReferenceUid": 987,
  "publicUrl": "/fileadmin/user_upload/ai_generated/editorial-hero-image.png",
  "altText": "Editorial hero image about TYPO3 AI workflows"
}

Notes:

  • sys_file remains exposed as a read-only MCP resource so stored files can still be listed and found later.
  • The tool requires a configured SG AI API key in the TYPO3 backend.
  • It requires sgai_mcp:tt_content:write, sgai_mcp:sys_file:write, sgai_mcp:sys_file_reference:write, and sgai_mcp:sys_file_metadata:write.
  • For CType=textmedia, generate_and_attach_image_to_content writes to tt_content.assets. For standard image-based content elements, it usually writes to tt_content.image.
  • tt_content.image is a built-in non-exclude field in TYPO3, so no separate non_exclude_fields entry is required for it.
  • generate_and_attach_image_to_page works for pages.media and pages.og_image, defaults to media, and requires sgai_mcp:pages:write plus the same file-related write scopes. Because both page fields are exclude fields, the managed backend group must allow pages:media and/or pages:og_image for the targets you want to use.

3.6 Browser-style page read-back for MCP clients

sgai_typo3 also provides:

  • fetch_site_page

Use it when an MCP client needs rendered frontend read-back after changing TYPO3 content or page fields. The tool fetches the frontend URL through TYPO3's HTTP client and returns compact page content plus metadata like title, language, statusCode, and finalUrl.

Important behavior:

  • allowed URLs are controlled by browserFetchPolicy in extension configuration (open, same_site_only, allowlist)
  • browserFetchAllowlist accepts one URL prefix per line and is used only when the policy is allowlist
  • default output is cleaned text with HTML tags removed
  • set stripTags=false only if rendered HTML structure matters
  • redirects are re-checked against the active policy
  • non-text payloads such as PDFs are rejected

Example call:

{
  "url": "https://example.test/news/my-article",
  "maxLength": 12000
}

3.7 Localize a page before editing translated fields

Use localize_page to create or reuse the translated page record first. Then call pages.update on the returned localizedPageUid.

Example flow:

  1. localize_page with: 
    {
  "pageUid": 123,
  "languageUid": 1
}
  2. pages.update on the returned localized page UID with translated fields such as title, slug, description, or seo_title.

Do not send localization or placement fields through a generic update. The dedicated localization and move tools own pid, language, localization-parent, localization-source, content-column, and sorting fields. In the Backend Page module, open the source page with the target language selected; the localized page UID is an overlay record, while localized content remains stored on the source page PID.

3.8 Filtering examples for MCP clients

List endpoints expect filters in the shape filter[field]=value.

Examples for pages:

{
  "filter": {
    "title": "News"
  }
}

{
  "filter": {
    "slug": "/news"
  }
}

Do not send title or slug as top-level list arguments. They must be nested inside filter.

Operational recommendations:

  • Prefer canonical endpoint /api/sgai_mcp/v1/mcp.
  • Treat tokens as secrets and keep them in environment variables/secure client settings.
  • After token revocation/rotation in TYPO3, update the MCP client token.

4. Global Configuration (Extension Configuration)

Open:

  • Admin Tools > Settings > Extension Configuration > sg_ai

4.1 Required

  • apiKey
    • SG AI API key.
    • Recommended: do not store in TYPO3 DB; use environment variable SG_AI_API_KEY.

4.2 Optional but Important

  • useImageAnalysis (0/1)

    • 1: analyzes actual image content for alt text generation.
    • 0: metadata-only alt text generation.
    • Impact: quality vs. processing complexity.

  • useBase64Encoding (0/1)

    • 1: sends image data as base64 to SG AI.
    • 0: sends image URL.
    • Recommended: keep 1 for private/staging/non-public environments.

  • useContextForAltText (0/1)

    • 1: includes surrounding TYPO3 context when generating alt text.
    • 0: no contextual page data.
    • Impact: often better relevance, potentially higher token usage.

  • language (e.g. en, de)

    • default language for recommendation output (SEO/a11y checks and module usage).

  • watermarkEnabled (0/1)

    • global on/off switch for SG AI watermark logic on AI-flagged images (overlay decision + processing metadata hooks).

  • watermarkOverlayEnabled (0/1)

    • enables/disables frontend HTML/CSS watermark overlay rendering.
    • default is 0 (disabled).

  • watermarkPreserveMetadataOnProcessing (0/1)

    • adds SG AI provenance metadata in TYPO3's processing command when processed variants are created.
    • default is 1 (enabled).

  • watermarkBadgeAssetPath

    • EXT: path or absolute path to the badge graphic (default circled AI icon).

  • watermarkPosition, watermarkMargin, watermarkRelativeSize, watermarkOpacity

    • visual styling and placement controls.

  • watermarkMaxWidth, watermarkMaxHeight

    • badge size caps in pixels (default 80/80, 0 = unlimited).

  • watermarkMinWidth, watermarkMinHeight

    • minimum output dimensions for watermarking.

  • watermarkScreenReaderLabelEnabled, watermarkScreenReaderSuffix

    • controls whether non-decorative AI images receive an accessibility suffix in alt and aria-label.

  • watermarkOverlayAccessibilityLabel

    • localized label text used for the watermark badge image (alt / aria-label).

  • per-call overrides

    • mode-only: sgAiWatermarkMode (on|off)
    • structured: sgAiWatermarkOverride supports mode / enabled and visual/accessibility settings.

HTML overlay behavior:

  • the extension appends additional badge markup to rendered image HTML
  • the badge is positioned with CSS on top of the image
  • this does not alter image pixels or binary image data

4.3 Fixed Queue/Polling Defaults

Queue and remote background polling behavior uses fixed defaults in code and is not configurable via Extension Configuration:

  • immediate local processing priorities: 20,30
  • remote synchronous priorities: 20,30
  • polling max retries: 120
  • polling sleep seconds: 2

4.4 EU AI Act (Pragmatic Note)

sg_ai supports practical transparency measures for AI-assisted content:

  • AI-image markers in TYPO3 metadata/reference records
  • optional visual frontend overlay labeling
  • optional accessibility suffixes for non-decorative AI images
  • provenance metadata best effort during processing
  • persisted AI text/recommendation outputs in TYPO3 records/history for editorial approval workflows

What must be shown to end users, in which channel, and at what workflow stage remains an integrator/editorial decision. This documentation does not provide legal advice.

5. Field-Level Configuration in TCA

Several features can be tuned per field using config.sg_ai.

5.1 Common controls

  • disabled
    • hides SG AI controls for that field.
  • promptProvider
    • custom provider class to generate prompts.
  • promptTemplate
    • template with placeholders such as ###title###.

5.2 Image-field specific

  • image_size
    • default generated image size preset or custom dimensions.
  • output_format
    • png or jpeg.

6. Button-by-Button End-User Guide

This section lists all user-facing buttons introduced by sg_ai.

6.1 Generate Alt Text with AI

Where it appears

  • On sys_file_reference.alternative
  • On sys_file_metadata.alternative

Label / title behavior

  • The control uses context-aware titles:
    • context active
    • context ignored

Workflow

  1. Open a record that contains an image reference.
  2. Locate the Alternative (alt text) field.
  3. Click Generate Alt Text with AI.
  4. Wait for the request to finish.
  5. Review the generated text and adjust if needed.
  6. Save the record.

Important notes

  • If image is marked decorative, generation is skipped.
  • If record/file is missing or inaccessible, generation fails with an error message.
  • If API key is missing, users receive an explicit configuration error.

Benefits

  • very fast accessibility baseline
  • improved consistency in alt text style and length
  • lower manual effort for media-heavy pages

6.2 Is Decorative (Toggle)

Where it appears

  • Image overlay palette in sys_file_reference

Purpose

  • Marks an image as decorative.
  • Decorative images are intentionally excluded from alt text generation.

Workflow

  1. Open image reference in backend form.
  2. Enable Is decorative if image has no informative value.
  3. Save.

Benefit

  • prevents misleading or unnecessary alt text
  • improves accessibility quality by using proper decorative-image handling

6.3 Generate Image with AI

Where it appears

  • In inline file controls for image-capable fields (for matching image file types)
  • Can be disabled per field via config.sg_ai.disabled

Modal actions

  • Generate
  • Reset to Default
  • Cancel

Workflow

  1. Open a saved record with an eligible image field.
  2. Click Generate Image with AI.
  3. In modal, edit or keep the prompt.
  4. Optional: click Reset to Default to regenerate default prompt.
  5. Click Generate.
  6. Wait for processing notification.
  7. Page reloads and new image reference is attached.

What happens technically (user-visible outcome)

  • New file is generated and attached to record.
  • MCP image-tool responses include SG AI usage metadata when available, so hosted runtimes can show the real generated-image credits.
  • Generated file is marked as AI-generated in file metadata.
  • SG AI stores provenance metadata for generated images.
  • Alt text generation is triggered for the new image.
  • Last prompt is persisted per record/field, including the image settings comment block.
  • File may be renamed to an SEO-friendly name derived from alt text.
  • Generated filename length is capped to 60 characters (including suffix and extension).

EU AI Act transparency support is documented in extension metadata (ext_emconf.php and composer.json).

Benefits

  • fast visual content creation without leaving TYPO3
  • consistent style via prompt templates
  • immediate integration into existing media fields

6.4 Generate Text with AI

Where it appears

  • On eligible RTE text fields.
  • The extension auto-injects this button for supported text fields.

Modal actions

  • Generate Text
  • Reset to Default
  • Cancel
  • Checkbox: Include page context

Workflow

  1. Open a saved record with an RTE field.
  2. Click Generate Text with AI.
  3. Review/edit the generated prompt.
  4. Choose whether to include page context.
  5. Click Generate Text.
  6. Generated content is inserted into CKEditor/textarea.
  7. Review, edit, and save.

Page-context option

When enabled, context may include:

  • TYPO3 version metadata
  • page information
  • nearby content data for richer relevance

Restrictions

  • Unsaved records cannot generate text.
  • Non-RTE fields are filtered/removed from this workflow.

Benefits

  • faster drafting, rewriting, and expansion
  • better context-aware results with one click
  • reduced editor switching between tools

6.5 Generate SEO-Friendly Title

Where it appears

  • pages.seo_title field control

Workflow

  1. Open page properties.
  2. Click Generate SEO-friendly title.
  3. Wait for generation.
  4. Value is written to seo_title.
  5. Review and save.

Benefits

  • faster meta optimization
  • consistent and language-aware SEO title generation

6.6 Generate SEO-Friendly Description

Where it appears

  • pages.description field control

Workflow

  1. Open page properties.
  2. Click Generate SEO-friendly description.
  3. Wait for generation.
  4. Value is written to description.
  5. Review and save.

Benefits

  • faster and more complete meta coverage
  • reduced chance of missing or weak descriptions

6.7 Generate Technical SEO Recommendations

Where it appears

  • In page-level SG AI recommendation area

Workflow

  1. Open saved page record.
  2. Click Generate Technical SEO Recommendations.
  3. Wait for background processing notice.
  4. Page reloads.
  5. Review updated score and recommendation table.

Output shown to users

  • score indicator (0-100)
  • recommendation table with:
    • Priority, Where, What, How, Why
  • generation timestamp

Benefit

  • quick technical SEO issue discovery directly in page editing

6.8 Generate Content SEO Recommendations

Workflow

  1. Open saved page record.
  2. Click Generate Content SEO Recommendations.
  3. Page reloads with updated score and recommendations.

Benefit

  • content-quality and relevance guidance for editors and SEO teams

6.9 Generate Accessibility Recommendations

Workflow

  1. Open saved page record.
  2. Click Generate Accessibility Recommendations.
  3. Page reloads with updated score and recommendation table.

Benefit

  • faster identification of accessibility barriers and fixes

6.10 Backend Module Button: Get Recommendations

Use the dashboard first when setting up a fresh instance:

  • Web > AI Assistant > Dashboard for onboarding and scheduler setup
    • The dashboard shows the current queue health and recent completed activity. Configure the queue scheduler before submitting work that should run in the background.
  • then switch to Web > AI Assistant > AI Page Insights for URL checks

Location

  • Web > AI Assistant > AI Page Insights

Inputs

  • URL (required)
  • Type:
    • Technical SEO
    • Content SEO
    • Accessibility

Main action

  • Get recommendations

Workflow

  1. Open module.
  2. Enter public URL.
  3. Select analysis type.
  4. Click Get recommendations.
  5. Review score and structured recommendations in “Last result”.

Benefits

  • quick quality check for arbitrary URLs
  • usable for checks outside the currently edited page

6.11 AI History and Queue Status

Where it appears

  • Web > AI Assistant > AI Page Insights (integrated Analysis + History tabs)
  • Web > AI Assistant > Dashboard (scheduler overview and setup actions)

What users can do

  1. Track queued and completed AI tasks.
  2. Open View to inspect full generated result payloads.
  3. Search, sort, and paginate through past results.
  4. Reuse generated output where action buttons are available.
  5. Identify remote queue runs by message state information in status/details.

Why this matters

  • improves traceability of AI-generated changes
  • supports editorial review before applying outputs
  • helps teams verify that queue processing is healthy

7. Typical End-User Scenarios

7.1 New page creation

  1. Create and save page/content.
  2. Generate draft text in RTE fields.
  3. Generate images where needed.
  4. Generate image alt texts.
  5. Generate SEO title and description.
  6. Run content/technical/a11y recommendations.
  7. Apply improvements and publish.

7.2 Existing page optimization

  1. Run recommendation buttons.
  2. Prioritize high-impact items from table.
  3. Update content, structure, or media.
  4. Re-run recommendation generation.
  5. Track improved score and publish updates.

8. CLI Workflows for Large Sites

For admins/integrators:

  • vendor/bin/typo3 sg_ai:generate-alt-texts
  • vendor/bin/typo3 sg_ai:generate-seo-meta
  • vendor/bin/typo3 sg_ai:generate-ai-recommendations
  • vendor/bin/typo3 sg_ai:process-queue
  • vendor/bin/typo3 sg_ai:list-queue
  • vendor/bin/typo3 sg_ai:cleanup-queue

When to use:

  • initial rollout on existing content
  • scheduled quality maintenance jobs
  • large-batch updates after migrations

9. Best Practices for Content Teams

  1. Always review AI output before publishing.
  2. Use “Is decorative” correctly for non-informative images.
  3. Keep prompts concise and task-specific.
  4. Use TCA templates for consistent tone across fields.
  5. Re-run recommendations after meaningful content changes.
  6. Keep API credentials in environment variables, not in VCS.

10. Troubleshooting Guide

“API key is not configured”

  • Check SG_AI_API_KEY or sg_ai extension configuration.

Buttons are missing

  • Check user permissions.
  • Verify field-level config.sg_ai.disabled.
  • Confirm field type supports that button workflow.

Unsaved record warning

  • Save record first, then run generation.

Recommendation generation fails

  • Ensure target page/URL is reachable and rendered.
  • Check TYPO3/system logs for request details.

Queue tasks stay pending for too long

  • Verify the scheduler task sg_ai:process-queue exists and is enabled.
  • Execute a manual run: vendor/bin/typo3 sg_ai:process-queue --limit=5.
  • If the backend shows Scheduler task inactive, create it in Web > AI Assistant > Dashboard.

Image generation works but no visible result

  • Record reload may be required.
  • Verify file field configuration and storage permissions.

History is empty even after generation

  • Confirm queue processing is active and tasks reach status finished.
  • Verify there are no API/permission errors in TYPO3 logs.

11. Governance and Quality Control

For team leads:

  • define editorial rules for AI output acceptance
  • set periodic accessibility/SEO review cadences
  • document approved prompt patterns for each content type
  • monitor changes in recommendations over time

12. Summary

sg_ai turns TYPO3 backend forms into AI-assisted workflows:

  • generate faster
  • improve quality continuously
  • keep content, SEO, and accessibility work inside TYPO3

For extension-level setup and upgrade information, see:

AI Watermark Overlay API

sg_ai provides a reusable overlay API so extension-level ViewHelpers can render AI watermarks in a generic way.

SG AI watermark overlays are injected through PSR-14 image-rendering events:

  • SGalinski\SgAi\Event\AfterImageRenderingEvent

Recommended integration for all setups: dispatch AfterImageRenderingEvent from your existing renderer right after building the final image HTML (<img>/<picture>). This avoids custom SG AI wrapper ViewHelpers and keeps one rendering path.

Implementation outline:

  1. Render image HTML in your own renderer.
  2. Resolve the corresponding TYPO3 FileInterface.
  3. Dispatch SGalinski\SgAi\Event\AfterImageRenderingEvent with HTML, file, and render context.
  4. Use the returned event HTML (getImageHtml()) as final output.

Services

SGalinski\SgAi\Service\AiImageWatermarkOverlayService

Main methods:

  • buildPictureOverlayResult(FileInterface $file, array $renderContext = []): array

buildPictureOverlayResult() returns a consumer-ready payload for thin integrations:

  • overlayMarkup (ready-to-append badge overlay markup)
  • isWatermarkActive (final decision after global settings, AI flag, dimension limits, and optional per-call override)
  • accessibleText (input accessible text with optional AI suffix applied for non-decorative images)
  • shouldSyncAccessibleText (whether alt/aria-label should be rewritten from accessibleText)

The badge image accessibility label (alt/aria-label inside overlayMarkup) is configured through watermarkOverlayAccessibilityLabel and supports LLL references.

SGalinski\SgAi\Service\AiImageWatermarkService

Relevant integration method:

  • resolvePerCallWatermarkContext(array $context, ?array $watermarkConfiguration = null): array

This method normalizes mode-only and structured overrides and is used by both processing and overlay integrations. Use it if your extension needs to apply SG AI-compatible watermark overrides in custom pipelines.

Render Context

Supported render-context keys:

  • width, height (optional target dimensions used for threshold checks)
  • accessibleText (optional source text for alt and aria-label synchronization)
  • isDecorative (optional boolean to suppress suffixing for decorative images)
  • sgAiWatermarkMode (optional on|off)
  • sgAiWatermarkOverride (optional structured override array)

sgAiWatermarkOverride supports:

  • mode (on|off) or enabled (true|false)
  • badgeAssetPath
  • position
  • margin
  • relativeSize
  • maxWidth, maxHeight
  • opacity
  • minWidth, minHeight
  • overlayAccessibilityLabel
  • screenReaderSuffix
  • screenReaderLabelEnabled

Global extension settings relevant to overlay behavior:

  • watermarkEnabled (global watermark decision base)
  • watermarkOverlayEnabled (frontend overlay rendering switch)

If watermarkOverlayEnabled is disabled, no overlay markup is injected even if image-level watermark conditions are met.

Overlay Markup and CSS Requirements

The overlay is rendered as additional HTML appended to the image/picture output:

<span class="sgai-watermark-overlay" style="--sgai-watermark-margin: ...; --sgai-watermark-size: ...; ...">
	<img class="sgai-watermark-overlay-badge sgai-watermark-overlay-badge--southeast" ... />
</span>

This markup requires CSS to be visually positioned as an overlay. Without CSS, the badge will be rendered as normal inline content.

Required CSS Integration

Import the SG AI stylesheet partial in your frontend build:

EXT:sg_ai/Resources/Public/Sass/Bootstrap5/_sg-ai.scss

If you do not use SASS imports, add equivalent CSS rules manually. The minimum required behavior is:

  1. The image container must be position: relative.
  2. .sgai-watermark-overlay must be position: absolute; inset: 0;.
  3. .sgai-watermark-overlay-badge must be absolutely positioned via the --north/.../--southeast classes.

Plain CSS Fallback Example

.my-image-wrapper {
	position: relative;
}

.my-image-wrapper .sgai-watermark-overlay {
	position: absolute;
	inset: 0;
	pointer-events: none;
}

.my-image-wrapper .sgai-watermark-overlay-badge {
	position: absolute;
	width: var(--sgai-watermark-size, 12%);
	opacity: var(--sgai-watermark-opacity, 0.85);
}

.my-image-wrapper .sgai-watermark-overlay-badge--southeast {
	right: var(--sgai-watermark-margin, 24px);
	bottom: var(--sgai-watermark-margin, 24px);
}

Runtime CSS Variables

The overlay service writes these CSS variables inline:

  • --sgai-watermark-margin
  • --sgai-watermark-size
  • --sgai-watermark-opacity
  • --sgai-watermark-max-width
  • --sgai-watermark-max-height

This allows integrators to keep global CSS generic while sizing and placement are still controlled by SG AI settings and per-call overrides.

UPGRADE

Generic MCP Resource mutations

The generated SGAI MCP permission map now exposes Backend User-authorized custom-table writes when sg_apicore can prove their Site ownership through pid or deterministically selected reverse TCA inline relations. PATCH schemas exclude identity, placement, sorting, localization linkage, and inline owner fields. Ensure the MCP Backend User group grants both the target table permission and every required inline ownership/match field; otherwise the write remains unavailable. Page-stored inline children are additionally checked against ownership-contract schema version 2: an omitted pid and fixed single-relation selectors are derived from the persisted parent chain and server metadata. Explicit conflicting selectors, requested PIDs, and persisted cross-page child PIDs are rejected before DataHandler executes.

The generated sys_file_reference.create Resource contract now includes writable TCA file fields on supported custom and inline tables. This allows an earlier generated fileUid to be attached to a Mask child record through typed semantic plan dependencies. Run the normal MCP synchronization after updating so the persisted permission map contains the new destination contracts. Destinations remain unavailable when the table or field is not writable, ownership is ambiguous, or the calling Backend User lacks destination-table or owning-page permissions.

Generic page and content PATCH schemas are now operation-specific. Real changes to pid, colPos, sorting, or localization linkage still require the dedicated TYPO3 move/localization operations. A stale client may repeat an unchanged structural value; the guard compares it with the persisted record and accepts only an exact normalized no-op.

Chat Agent Backend Module

The dedicated AI Chat Agent backend module introduces persistent TYPO3-side chat sessions and chat messages.

Required manual step after updating:

vendor/bin/typo3 extension:setup

This applies the new database tables:

  • tx_sgai_chat_session
  • tx_sgai_chat_message
  • tx_sgai_chat_attachment

Without the schema update the backend module cannot store or reload chat conversations, and attachment-enabled chat requests will fail at runtime.

Attachment Extraction Backend Requirement

Attachment-enabled chat now expects SG AI SaaS-side attachment extraction for PDFs, images, and similar file-based fallbacks.

Required backend capability after updating:

  • the SG AI API must expose POST /v1/attachments/extract
  • the SaaS endpoint must perform attachment extraction with a file-capable model
  • the SaaS endpoint should cache normalized extraction results by checksum and extractor version/model

TYPO3 no longer relies on local PDF extraction binaries for this path. If the SaaS endpoint is missing, PDF and image attachment processing will fail even when TYPO3 itself is updated correctly.