README

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:

Docs/End-User/README.md

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

Install extension:

composer require sgalinski/sg-ai

Activate extension in Extension Manager.
Run database schema updates in TYPO3 Install Tool / Admin Tools.
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:

Render your image markup (<img> or <picture>) in your own ViewHelper/renderer.
Create and dispatch AfterImageRenderingEvent with:
- the rendered HTML
- the resolved FileInterface
- render context (width, height, accessibleText, isDecorative, optional override keys)
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:

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)
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:

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.
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.
Enter one concrete instruction for the context shown above the composer.
Start the run and keep the SaaS queue worker active:
- SaaS queue worker: vendor/bin/typo3 sg_ai_api:queue:work
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:

Open AI Assistant > Dashboard
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
If the card shows Upgrade required and the account is eligible, click Start 14-day TYPO3 MCP trial.
Once the card shows Included or Trial, choose the target site and click Enable SGAI TYPO3 MCP
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:

Resolves the selected site (or auto-selects when exactly one site exists).
Creates or updates backend group SGAI MCP with default table/field permissions and DB mount.
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
Creates or reuses one token for API sgai_mcp and synchronizes its scopes.
Persists setup state (site/group/token/resource/signature/timestamp) in TYPO3 registry.
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:

Create the target content element.
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:

localize_page with:

{
  "pageUid": 123,
  "languageUid": 1
}

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.

sgalinski / sg-ai

Maintainers

Package info

Statistics

Security