Getting started 

For administrators 

Set up providers, backend modules, and MCP through the AI Foundation module.

For developers 

Build TYPO3 extensions on AI Foundation — shared providers, prompts, features, and MCP tools without handling API keys in every child extension.

Help 

Table of Contents

Overview 

AI Foundation (EXT:ns_t3af) is T3Planet’s shared AI foundation for TYPO3. It is the central engine behind all T3Planet AI extensions.

AI Foundation connects TYPO3 to AI models, manages API keys, exposes an MCP server for AI agents, and logs every request — so your team uses AI in a safe, consistent way. Editors work through connected extensions such as AI Assistant or AI Chatbot. Admins configure everything in the AI Foundation backend module group.

Video Tutorials 

Interactive Supademo walkthroughs help admins and managers learn AI Foundation setup and daily operation. Follow the order below, then practice in your staging TYPO3 instance.

Credits 

This extension is developed and maintained by:

T3Planet project by NITSAN: https://nitsantech.de/typo3-agentur

Developed with modern AI tooling by the NITSAN/T3Planet team — following TYPO3 coding standards, reviewed by certified TYPO3 developers, and tested across TYPO3 v12, v13 and v14.

Quick start 

The recommended way to install this extension is via Composer.

Install the license extension first (if it is not already present), then AI Foundation (EXT:ns_t3af):

composer require nitsan/ns-license
composer require nitsan/ns-t3af
./vendor/bin/typo3 extension:setup
./vendor/bin/typo3 cache:flush

Classic TYPO3 sites can also install from the TYPO3 Extension Repository (TER).

After installation:

1. Activate the extensions in Admin Tools > Extensions.
2. Open AI Foundation > Dashboard and confirm the module group is available.
3. Connect providers and API keys in AI Foundation > AI Providers.
4. Complete guided options with Quick Setup in the AI Foundation module header.
5. Clear caches in Admin Tools > Maintenance.

Continue with Configuration for providers, MCP, and day-to-day module setup.

Composer installation 

composer require nitsan/ns-license

composer require nitsan/ns-t3af

./vendor/bin/typo3 extension:setup
./vendor/bin/typo3 cache:flush

Manual installation 

If you cannot use Composer, install both extensions from the TER in this order:

1. Open Admin Tools > Extensions > Get Extensions.
2. Search for ns_license, install and activate it, then flush caches.
3. Search for ns_t3af (or T3AF), install and activate it.
4. Run Analyze Database Structure.
5. Flush caches again.

Verify the installation 

Confirm that:

• ns_license and ns_t3af are listed as active in Admin Tools > Extensions
• The AI Foundation module group appears in the backend sidebar
• Analyze Database Structure reports no pending changes for ns_t3af

If the module is missing, flush caches and run ./vendor/bin/typo3 extension:setup again.

Next steps 

Open AI Foundation > AI Providers to connect at least one provider, then review Configuration.

Two configuration areas 

AI Providers — Path: AI Foundation > AI Providers. API keys, models, and defaults.

Extension settings — Translation APIs, Basic Auth, notifications, and MCP switches (including enableMcpServer). Prefer AI Foundation > MCP Server > Advanced for MCP options. These keys live in AI Foundation settings, not the classic TYPO3 Admin Tools > Settings > Extension Configuration form.

Minimum working setup 

1. One AI provider with a valid key and model
2. Test connection passes
3. Provider marked Default
4. (Optional) DeepL or Google keys for translation APIs
5. (Optional) MCP enabled if you use AI agents

AI Providers (primary) 

Path: AI Foundation > AI Providers

Connect at least one provider, set a model, run Test connection, and mark exactly one row as Default.

Full field reference: Provider fields. Guide: AI Providers

Extension settings 

AI Foundation stores translation helpers, Basic Auth, notifications, and MCP switches in extension settings (including enableMcpServer). Prefer AI Foundation > MCP Server > Advanced for MCP options.

Where a classic Extension Configuration form is still used for optional keys, open Admin Tools > Settings > Extension Configuration and select ns_t3af.

Per-feature providers 

Path: AI Foundation > AI Features

Override the default provider per task: SEO, Pages, Content, Translation.

See AI Features.

Security checklist 

• Limit backend admin access
• Use HTTPS in production
• Rotate API keys every 90 days
• Enable AI Permissions for large teams
• Never store keys in Git or email

When to reconfigure 

• After key rotation — run Test connection again
• When adding a new child extension — check AI Features
• Before enabling MCP in production — read MCP Server security section
• After license renewal — confirm the extension license is still valid

Purpose 

The Dashboard is your control center for AI health on this TYPO3 instance. Open it daily for a quick status check.

Path: AI Foundation > Dashboard

AI Foundation Dashboard Demo

What the dashboard shows 

• Provider status — Connected, failed, or not tested
• Default provider — Active model name
• Recent usage — Last requests and token count
• Quick actions — Links to AI Providers, MCP Server, and related modules

Daily admin routine (2 minutes) 

1. Open Dashboard
2. Confirm provider status is green
3. Skim AI Logs if usage looks unusual — see AI Usage & Logs

Status meanings 

• Green — Provider OK. No action needed.
• Yellow — Not tested recently. Run a Test connection in AI Providers.
• Red — Connection failed. Check API key, model ID, and outbound HTTPS.

Quick links from the dashboard 

• AI Providers → AI Providers
• MCP Server → MCP Server
• View Logs → AI Usage & Logs

Tips 

• Set one clear default provider — avoids confusion for editors
• Test providers after every key rotation
• Review usage weekly for cost control

When the dashboard shows red 

1. Open AI Providers → run Test connection
2. Check vendor status page (OpenAI, Anthropic, etc.)
3. Verify firewall allows outbound HTTPS
4. Check AI Logs for the exact error message
5. See Known Problems if the issue persists

Adding a provider 

1. Open AI Foundation > AI Providers.
2. Click Add provider.

3. Fill in the required fields:

   • Display name — Friendly label for your team (for example `OpenAI production`).
   • Adapter type — Vendor protocol (OpenAI, Anthropic, Gemini, Azure, Mistral, DeepSeek, xAI, Ollama, or custom OpenAI-compatible).
   • API key — Cloud vendors need a key. Leave empty for local Ollama.
   • Model ID — Completion model (for example gpt-4o-mini).
4. Optionally set the endpoint URL, embedding model, capabilities, temperature, and pricing fields.
5. Click Save.
6. Enable Default on exactly one provider.

Testing a connection 

After saving a provider, click Test connection to verify the setup. The test calls the provider API and reports:

• Connection status (success or failure)
• Error details on failure
• Model / capability hints when the adapter can list them

If your server reaches the internet only through a corporate proxy, configure TYPO3 HTTP settings:

$GLOBALS['TYPO3_CONF_VARS']['HTTP']['proxy'] = 'http://proxy.example.com:8080';

Editing and deleting providers 

• Click a provider row to edit its settings in the drawer.
• Use Test connection after rotating an API key or changing the model.
• Use Delete to remove a provider. Features that pointed at that provider fall back to the global default (or fail until another provider is assigned).

Supported adapters 

Built-in and discovered adapters include:

• symfony.openai — OpenAI
• symfony.anthropic — Anthropic Claude
• symfony.gemini — Google Gemini
• symfony.mistral — Mistral AI
• symfony.ollama — Local Ollama
• symfony.openrouter — OpenRouter
• nst3af.openai_compatible — Custom / OpenAI-compatible endpoints
• Additional Symfony AI bridges when their Composer packages are installed (for example Azure, DeepSeek, xAI)

Custom adapters: Custom AI Providers.

Capabilities 

Pick a model that supports what you need. Test connection helps validate the choice.

• Chat — Text generation
• Streaming — Live response display in the backend
• Embeddings — Search and similarity features
• Vision — Image analysis
• Tool use — MCP agent workflows

Multiple providers — when and why 

Dev and live — Separate rows with different API keys per environment.

Cost saving — Cheap model as global default; premium model assigned in AI Features for important tasks.

EU hosting — Mistral or Azure in an EU region for data residency requirements.

Provider fields 

Fields below map to the AI Providers drawer and the tx_nst3af_provider table.

Troubleshooting 

Test fails — Check the API key, model ID, endpoint URL, and outbound HTTPS/firewall rules.

Rate limit — Wait or upgrade the vendor plan.

Vision returns empty — Use a vision-capable model (for example GPT-4o with vision).

Module works but child extension fails — Check AI Features for per-task overrides.

Security 

• Rotate keys every 90 days
• Use one key per environment (dev, staging, live)
• Restrict access via AI Permissions
• Never commit API keys to Git

Where to get API keys 

More links: Helpful Links

Purpose 

Store your brand profile once. AI Foundation injects it into prompts for consistent, on-brand results across all connected extensions.

Path: AI Foundation > AI Context

AI Foundation AI Context Demo

What to store 

• Company name — For example Finance Company GmbH
• Industry — For example financial services
• Audience — For example SME owners in Germany
• Brand voice — Professional, clear, trustworthy
• Key messages — Digital-first, personal service
• SEO keywords — finance, banking, loans
• Language style — German formal (Sie) or simple English

Why it matters 

Without context, AI output sounds generic. With context, text matches your brand and market. Every editor benefits without retyping instructions.

Setup (3 steps) 

1. Open AI Foundation > AI Context
2. Fill business identity fields
3. Save — extensions use it automatically on the next AI request

When to update AI Context 

• Rebrand or new product line
• New target market (for example expand from DE to EN)
• Compliance change (formal Sie required everywhere)
• After AI Prompts changes still produce off-brand text

Scenario: multi-language site 

Set language style to “German formal (Sie) for DE; simple English for EN”. Add brand terms that must stay untranslated. Connected translation features will respect this context.

See also AI Prompts for task-specific instructions.

Purpose 

Central prompt templates for AI Foundation and connected extensions. Same prompt quality for every user and every extension.

Path: AI Foundation > AI Prompts

What is a prompt? 

The instruction sent to the AI. Examples:

• “Write a meta description, max 155 characters”
• “Translate to German, formal Sie”

Central prompts mean consistent quality across your team.

Manage prompts 

1. Open AI Prompts
2. Select feature category
3. Edit template text
4. Save and test with one real request

Extensions can sync default prompts from AI Foundation.

Writing good prompts 

1. Be specific — length, format, language
2. Set tone — formal, friendly, technical
3. Say what to avoid — no emojis, no hype, no legal claims
4. Include the page goal — SEO, translation, rewriting, or summary

Example prompt 

Write a friendly greeting for [audience] mentioning [topic].

Pair prompts with AI Context for brand voice. Context handles who you are; prompts handle what to do.

Reset to default 

If results worsen after edits, use Reset to default in the UI. Then change one variable at a time and test again.

When to customize prompts 

• SEO team has strict meta description rules
• Legal requires disclaimers in generated text
• German formal (Sie) must appear in every output
• Extension default is too generic for your industry

When to leave defaults 

• Small team still learning AI features
• You have not yet filled AI Context
• Results are already good — do not over-edit

Governance note 

Prompt changes affect all users. Coordinate with AI Permissions before large template changes on production.

Purpose 

Assign different AI providers per task type. Use a fast cheap model for bulk SEO work and a premium model for important pages.

Path: AI Foundation > AI Features

Feature types 

• SEO — Meta data, keywords, schema-related tasks
• Pages — Page creation and structure
• Content — Text generation and rewriting
• Translation — Language conversion

Resolution order 

When an AI request runs, AI Foundation picks the provider in this order:

1. Provider chosen in the UI modal (if the editor selected one)
2. Feature default from this page
3. Global default provider from AI Providers

When to use per-feature providers 

Small team — Leave feature defaults empty. Use the global default only.

Large team — Cheap model for bulk tasks; premium model for key landing pages.

Multilingual site — Strong German model for Translation; fast model for SEO meta fields.

Example setup 

• SEO — Fast, cost-effective model (for example Gemini Flash or GPT-4o-mini)
• Pages — Premium model (for example Claude Sonnet or GPT-4o)
• Content — Balanced model for everyday editing
• Translation — Model strong in German and English

Why this matters for cost 

Without per-feature settings, every task uses the most expensive default. Routing SEO meta generation to a smaller model can cut monthly spend significantly while keeping premium quality where it counts.

How to configure 

1. Open AI Foundation > AI Features
2. For each feature row, select a provider (or leave empty for global default)
3. Save
4. Test one request per feature type from a connected extension
5. Review token usage in AI Usage & Logs

Scenario: agency with dev and live keys 

Use global default for staging. On production, set SEO to a fast model and Pages to premium. Dev team keeps separate provider rows in AI Providers with dev API keys.

Purpose 

Transparency for every AI request on your TYPO3 instance. Use these screens for budget control, debugging, and compliance.

AI Usage 

Path: AI Foundation > AI Usage

AI Foundation AI Usage Demo

Shows:

• Request count — Total AI calls in the selected period
• Tokens — Input and output volume
• By extension — Which extension called AI (AI Assistant, AI Chatbot, and others)
• By feature — For example seo.meta_description
• Time range — Day, week, or month

Use for: budget control, team planning, anomaly detection.

Compare usage trends on the Dashboard.

AI Logs 

Path: AI Foundation > AI Logs

AI Foundation AI Logs Demo

Per-request detail includes:

• Timestamp, user, extension, feature
• Provider, model, tokens
• Success or failure

Use for: debugging failed requests and compliance audits.

Scheduler & CLI 

Path: AI Foundation > Scheduler & CLI

AI Foundation Scheduler and CLI Demo

Background jobs and CLI commands. Example:

vendor/bin/typo3 ns_t3af:cache:flush

Ensure scheduler cron runs every minute on production.

OpenAI org statistics (optional) 

Set openai_admin_api_key in Extension Configuration for organization-level usage charts. This is not the chat API key. See Configuration.

Privacy 

Log detail depends on provider privacy settings and group audit limits from AI Permissions. Configure carefully before enabling full prompt/response storage.

Weekly admin habit 

1. Open AI Foundation > AI Usage and compare the trend with last week
2. Scan AI Foundation > AI Logs for repeated failures (same user, same feature)
3. Escalate persistent errors to Support with log details

When logs show high usage 

• Check AI Features — bulk tasks may need a cheaper model
• Review group limits in AI Permissions
• Ask editors if a script or loop triggered many requests

When logs show failures 

• Run Test connection in AI Providers
• Check vendor status and rate limits
• See Known Problems and FAQ

Purpose 

Role-based access and permissions for AI on TYPO3: a guided wizard over backend usergroups so junior staff, clients, and freelancers get safe AI access without seeing admin-only tools.

Configure per group:

• Module access — Which AI Foundation tabs and child modules appear
• Fine-grained feature permissions — Which features inside those modules are allowed
• Record-level restrictions — Read vs read/write on providers, prompts, context profiles, logs, and other catalog records
• Page-scope and batch limits — Bulk page limits, scheduler batch limits, and workspace enforcement where enabled
• Per-group credit limits — Monthly credit caps and daily request caps

The module writes into normal TYPO3 backend user group ACL fields (groupMods, custom_options, tables_select, tables_modify) and merges only AI-managed keys. Unrelated modules and tables already granted to the group stay intact.

TYPO3 Backend Usergroups 

The left sidebar lists backend user groups (same shell pattern as MCP Tools).

• Search with Find group…
• Each row shows the group name, member count, and how many AI modules are configured
• Select a group to open the guided wizard for that group

Example: a group such as ns_t3af_extended may show 0 members and a configured module count after you apply permissions.

Guided wizard 

After you select a group, the wizard walks through five steps:

1. Modules — Toggle AI Foundation admin modules and installed child extensions (for example AI Assistant, AI Search Hub, and other registered suite modules).
2. Features — Grant fine-grained feature permissions for the modules you enabled.
3. Records — Set record-level read or read/write access for catalog records those modules manage.
4. Limits — Set per-group credit limits, daily request caps, bulk/page batch limits, workspace enforcement, and audit/logging options (shown in the matrix under Credits, Workspace, and Audit).
5. Review — Preview the merged be_groups values, then apply.

Use Back / Next in the wizard footer. On Review, confirm the preview, then apply and flush caches before testing with an editor account.

Permission Matrix 

Open the Permission Matrix tab for a cross-group overview. The subtitle shows how many groups exist and how many are configured (for example 1 groups, 1 configured).

What enforcement does 

After you apply permissions:

• Restricted editors only see AI Foundation tabs they are allowed to use
• Dashboard may show an allowed-tabs overview instead of full analytics when usage/context/MCP tabs are closed
• AI Providers create/edit/delete needs write access on the provider table; otherwise the list stays read-only (Test connection can still work)
• Child extension tabs, cards, and mutating routes follow the same grants (403 when write is denied)

Administrators always keep full access to configure AI Permissions.

Recommended workflow 

1. Create or choose a backend user group for editors.
2. Open AI Foundation > AI Permissions.
3. Select the group and complete Modules → Features → Records → Limits → Review.
4. Check the Permission Matrix for that group.
5. Flush caches.
6. Log in as a user in that group and confirm hidden tabs and read-only screens match the matrix.

When to use this module 

• Safe AI access for junior staff, clients, and freelancers
• Editors share one instance across departments
• MCP or provider management must stay admin-only
• Per-group credit or request caps are required
• Child extensions must show only allowed tabs, features, and write actions

Developer extensions can register additional modules, features, and records through Custom Access Catalogs.

Product overview: AI Foundation on GitHub.

Purpose 

Connect external AI agents to TYPO3 through the Model Context Protocol (MCP). Tools like Cursor, Claude Desktop, and n8n can read pages, inspect schema, and update records (with permissions).

Path: AI Foundation > MCP Server

AI Foundation MCP Server Demo

What MCP does 

• Read TYPO3 pages and content
• Inspect database schema
• Create or update records (with permissions)
• Call extension-registered tools (see MCP Tools)

Enable MCP 

1. Open AI Foundation > MCP Server > Advanced.
2. Enable the MCP server checkbox (enableMcpServer).
3. Flush caches → status should show Online.

The setting is also available in AI Foundation extension settings under the MCP Server group. It is not part of the classic TYPO3 Admin Tools > Settings > Extension Configuration form.

Health check 

curl -sS -o /dev/null -w "%{http_code}" https://your-site.com/mcp
# Expect: 401 (auth required = good)

curl -sS https://your-site.com/.well-known/oauth-authorization-server/mcp
# Expect: JSON 200

Connection methods 

• Remote OAuth — Production and Cursor. Uses OAuth 2.1 with PKCE.
• mcp-remote — Simple HTTP clients. Uses URL token.
• Local CLI — DDEV and local development. Uses backend user and workspace.

MCP modes 

Set the mode in the MCP Server top bar (stored as mcpMode in the AI Foundation MCP settings).

Context (AI Generate via AI Agent) — Default for Cursor, Claude Desktop, and similar clients.

• The external AI agent generates content outside TYPO3.
• MCP tools apply and save that content into TYPO3 (pages, records, files).
• Use this when the model and reasoning run in the client, and TYPO3 is the CMS tool layer.

Native (AI Generate via TYPO3) — Server-side generation.

• TYPO3 runs AI generation on the server through your configured AI Providers.
• MCP tools receive instructions and generate or process content inside TYPO3.
• Use this when generation must stay on your instance (provider keys, brand context, and governance already configured in AI Foundation).

Some dual-mode content tools change their argument requirements and descriptions based on the active mode. After switching mode, reconnect or refresh your MCP client so the tool list updates.

Core tools 

AI Foundation ships a large TYPO3 Core tool catalog (pages, content, records, files, workspaces, scheduler, permissions, redirects, cache, and more). Browse the full list in AI Foundation > MCP Tools.

Starter examples for first checks:

• table_schema — Field metadata for any table
• pages_get — Read one page
• content_list — List content on a page
• write_table — Create, update, or delete records

Child extensions can register additional tools — also visible in the MCP Tools tab.

Workspaces 

• 0 — Live workspace
• 1+ — Draft workspace

MCP edits respect the active workspace. Test writes in workspace 1 before live.

Cursor example (stdio / DDEV) 

{
  "mcpServers": {
    "typo3": {
      "command": "bash",
      "args": ["-lc", "cd /path/to/project && ddev exec php vendor/bin/typo3 ns_t3af:mcp:serve --no-startup-message -u admin -w 0"]
    }
  }
}

Security 

• Use HTTPS in production
• Treat URL tokens like passwords
• Limit which backend users can authorize OAuth
• Test in draft workspace before live writes
• Enable AI Permissions for multi-user sites

When to enable MCP 

• Developers use Cursor or Claude Desktop with TYPO3 daily
• Automation workflows via n8n need CMS access
• Staging environment for safe agent testing

When not to enable yet 

• Production site without HTTPS
• No clear policy for which admins may authorize agents
• Team has not completed AI Providers setup

Purpose 

The MCP Tools screen lists every tool an AI agent can call against your TYPO3 instance. Core tools ship with AI Foundation. Child extensions can register additional tools.

Path: AI Foundation > MCP Tools

AI Foundation MCP Tools Demo

What you see 

• Tool catalog — All registered MCP tools with descriptions
• Playground — Test a tool call without leaving the backend
• Extension cards — Tools contributed by installed T3Planet AI extensions

Core tools 

These tools ship with AI Foundation and appear under the TYPO3 Core tab in AI Foundation > MCP Tools when the MCP Server is enabled.

The Core catalog covers many tools across categories such as Content, Records, Schema, Files, Workspaces, Search, Cache, and related TYPO3 operations. Open the MCP Tools module to see the complete, up-to-date list.

Starter examples for first checks:

• table_schema — Field metadata for any database table
• pages_get — Read a single page record
• content_list — List content elements on a page
• write_table — Create, update, or delete records (permission-controlled)

Warning: Test write operations in a draft workspace before using live workspace 0.

Extension-registered tools 

When AI Assistant, AI Chatbot, AI Search, or other connected extensions are installed, their MCP tools appear automatically in the catalog. Each card shows:

• Tool name and description
• Required permissions
• Link to the extension documentation

Playground workflow 

1. Open AI Foundation > MCP Tools in the TYPO3 backend.
2. Select a tool from the catalog (start with read-only tools like pages_get).
3. Fill in required fields (page UID, table name, and so on).
4. Run the tool and inspect the JSON response before connecting external agents.

Why use the playground 

• Verify MCP is online before configuring Cursor
• Debug permission errors with a known backend user
• Show stakeholders what agents can access without installing client software

Security 

• Tools respect backend user permissions and workspace context
• OAuth and URL tokens are configured on the MCP Server screen
• Limit which admin users may authorize external agents
• Use draft workspaces for write_table tests

When to use MCP Tools vs MCP Server 

• MCP Server — Enable connectivity, OAuth, and client configuration
• MCP Tools — Browse tools, test calls, see extension contributions

See MCP Server for connection setup.

Prerequisites 

Environment

TYPO3 ^13.4 || ^14.3, PHP >= 8.2, typo3/cms-workspaces installed, ns_t3af enabled.

Local stack (example)

ddev start
ddev composer install
ddev exec typo3 cache:flush

Copied!

Backend access

Log in as an admin backend user (for example admin).

Site URL

https://<project>.ddev.site/mcp

Copied!

The MCP module derives URLs from your first site configuration. On DDEV this is typically: Replace <project> with your DDEV project name throughout this guide.

Optional tools

Node.js 18+ — MCP Inspector and mcp-remote Claude Desktop — OAuth remote setup n8n — MCP Client node (self-hosted or cloud) Cursor / VS Code MCP — for CLI or mcp-remote configs

Step 0 — Pre-flight checks (backend module) 

Open AI Foundation > MCP Server.

1. Workspace - Use the WORKSPACE dropdown (top right). - If you see a yellow “create workspace” notice, click Create MCP workspace (requires permission) or pick Live for read-only smoke tests.

2. Status bar (top card) Verify:

   • Server Status → Online
   • OAuth Endpoints → both oauth-authorization-server and oauth-protected-resource show green checks
   • Server URL → copy your https://…/mcp URL

3. Endpoint health (Remote MCP Setup tab) Under MCP endpoint status, all three rows should be green:

   • MCP endpoint (/mcp returns 401 without auth — that is expected and counts as online)
   • /.well-known/oauth-authorization-server/mcp
   • /.well-known/oauth-protected-resource/mcp

4. Quick curl smoke test

   # Replace with your site URL
   BASE=https://t3af.ddev.site
   
   curl -sS -o /dev/null -w "%{http_code}\n" "$BASE/mcp"
   # Expected: 401
   
   curl -sS "$BASE/.well-known/oauth-authorization-server/mcp" | head -c 200
   curl -sS "$BASE/.well-known/oauth-protected-resource/mcp" | head -c 200
   # Expected: JSON metadata (HTTP 200)

   Copied!
5. Enable MCP (if offline) Expand Show advanced → ensure Enable MCP Server is checked → Save.

Cursor IDE — two connection methods 

Cursor can connect to the TYPO3 MCP server in two ways. Use one method per server entry — do not mix stdio and URL for the same logical connection.

Project stdio (DDEV)

• Config file: .cursor/mcp.json in the project root
• Transport: stdio via DDEV
• Auth: backend user and workspace
• Best for: local development in this repository

Global remote URL (HTTP)

• Config file: ~/.cursor/mcp.json in the user home directory
• Transport: HTTP Streamable at /mcp
• Auth: OAuth 2.1 with PKCE (browser)
• Best for: any Cursor workspace, including production

Method A — Project stdio via DDEV 

Create or edit ``.cursor/mcp.json`` in the project root (same directory as .ddev/). Cursor spawns ddev exec … nst3af:mcp:serve when you open this project.

Important:

• `cwd` must be the absolute path to the DDEV project root. Without it, ddev may fail with could not find a project.
• Use the full command name `nst3af:mcp:serve` (alias mcp:server works only after TYPO3 caches are warm).
• `–no-startup-message` keeps diagnostics off stdout (stdio MCP reserves stdout for JSON-RPC).
• Adjust `–user` and `–workspace`` to match your backend user and workspace UID from the MCP module dropdown.

{
  "mcpServers": {
    "TYPO3 DDEV": {
      "command": "ddev",
      "args": [
        "exec",
        "php",
        "vendor/bin/typo3",
        "nst3af:mcp:serve",
        "--no-startup-message",
        "--user=admin",
        "--workspace=3"
      ],
      "cwd": "/absolute/path/to/aiuniverse"
    }
  }
}

Replace /absolute/path/to/aiuniverse with your checkout path (for example /Users/you/projects/aiuniverse).

Verify in Cursor: Settings → MCP → TYPO3 DDEV shows Connected and lists Core tools from AI Foundation (for example table_schema, pages_get, content_list, write_table, plus many others in the Core catalog).

Method B — Global remote URL (OAuth) 

For HTTP + OAuth without DDEV stdio, add the server URL to your user-level Cursor config: ~/.cursor/mcp.json. This works from any project; Cursor opens the OAuth flow in the browser on first connect.

{
  "mcpServers": {
    "typo3": {
      "url": "https://t3af.ddev.site/mcp"
    }
  }
}

Replace the host with your site URL from the MCP module Server URL field. Complete OAuth when Cursor prompts. The backend Active OAuth Tokens table should show a new token with an updated Last Used timestamp after tool calls.

Terminal verification (stdio / DDEV) 

Use these checks before relying on Cursor, or when debugging a broken stdio connection.

1. DDEV and TYPO3 CLI

cd /absolute/path/to/aiuniverse
ddev describe   # site should be running
ddev exec php vendor/bin/typo3 list nst3af

Expect nst3af:mcp:cleanup and nst3af:mcp:serve (alias mcp:server). If list nst3af fails, verify with:

ddev exec php vendor/bin/typo3 help nst3af:mcp:serve

2. One-shot initialize (pipe test — recommended)

Sends a single JSON-RPC initialize request on stdin and prints the JSON response on stdout. This confirms the server speaks MCP without leaving a process running:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n' \
  | ddev exec typo3 nst3af:mcp:serve --no-startup-message -u admin -w 3

Expected output (one line of JSON on stdout):

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"logging":{},"completions":{},"tools":{}},"serverInfo":{"name":"AI Foundation MCP Server","version":"1.0.0"}}}

Adjust -u / -w (short for --user / --workspace) to match your config. If you see this JSON, the stdio transport is working; any Cursor issue is likely cwd, command name, or MCP panel cache (restart Cursor).

3. Interactive run (optional)

ddev exec php vendor/bin/typo3 nst3af:mcp:serve --no-startup-message --user=admin --workspace=3

The process waits on stdin after startup — that is normal. It is not “stuck”; it expects JSON-RPC from an MCP client. Diagnostics go to stderr (use -v or -vv for more detail). Stop with Ctrl+C.

Method 1 — Remote MCP Setup (HTTP + OAuth / Bearer) 

Recommended for production-like clients. Transport: HTTP Streamable at {site}/mcp.

Authentication options:

• OAuth 2.1 + PKCE — Claude Desktop, MCP Inspector, generic OAuth clients
• Bearer token — n8n, Manus (create token in the module UI)

Default scopes (advanced settings): mcp:read mcp:write mcp:tools

Claude Desktop (OAuth) 

In the module: Remote MCP Setup → Claude Desktop tab.

Steps:

1. Open Claude Desktop → Settings → Integrations.
2. Click Add Integration.
3. Name it (for example TYPO3 DDEV).

4. Paste Server URL from the module, e.g.:

   https://t3af.ddev.site/mcp

   Copied!
5. Save. Claude starts OAuth automatically (browser window / system prompt).
6. Approve access as your TYPO3 backend user.

Verify:

• Ask Claude to list MCP tools or call table_schema with tableName: pages.
• In the module, Active OAuth Tokens shows a new row; Last Used updates.

Example prompt:

Use the TYPO3 MCP tool table_schema for table "pages" and summarize the fields.

n8n (Bearer token) 

In the module: Remote MCP Setup → n8n tab.

Steps:

1. Click Create n8n token (if no active token is shown).
2. Copy the Bearer token immediately (full value is only shown once; the UI stores it in the browser session for copy).
3. In n8n, add an MCP Client node to a workflow.

4. Configure the MCP Client node:

   • Endpoint — https://t3af.ddev.site/mcp
   • Server Transport — HTTP Streamable
   • Authentication — Bearer Auth
   • Bearer Token — paste the token from step 2
5. Save and Execute workflow.

Verify:

• Node connects without 401 errors.
• Tool list includes Core tools such as table_schema, pages_get, content_list, and write_table (the Core catalog contains many more).
• Active OAuth Tokens table shows client n8n token.

Manus (Bearer token) 

In the module: Remote MCP Setup → Manus tab.

Steps:

1. Click Create manus token and copy the Bearer token.
2. In Manus, add a new MCP server connection.

3. Configure the connection:

   • Server Name — your TYPO3 site name
   • Transport — HTTP
   • Server URL — https://t3af.ddev.site/mcp
   • Authorization — header Authorization: Bearer <token>
4. Save the connection.

Verify: Same as n8n — tool calls succeed and token appears in Active OAuth Tokens.

MCP Inspector (OAuth) 

In the module: Remote MCP Setup → MCP Inspector tab.

Steps:

1. Copy the pre-filled command (requires Node.js):

   npx @modelcontextprotocol/inspector --transport http --server-url https://t3af.ddev.site/mcp

   Copied!
2. Run it in your terminal.
3. Open the Inspector UI in the browser (URL printed in the terminal).
4. Complete OAuth when prompted.

5. Use the Tools panel to invoke table_schema:

   {
     "tableName": "pages"
   }

   Copied!

Verify:

• tools/list returns the Core tool catalog (many tools, not a short fixed set).
• table_schema returns JSON with pages field metadata.

Other OAuth-capable clients 

In the module: Remote MCP Setup → Other tab.

Generic checklist:

1. Add a remote MCP server in your client.
2. Server URL: https://t3af.ddev.site/mcp
3. Transport: HTTP Streamable (when available).
4. Auth: OAuth 2.1 + PKCE if supported; otherwise create a Bearer token under the n8n or Manus tabs.

Cursor: see Cursor IDE — two connection methods for project stdio (DDEV) and global URL (OAuth) setup, plus terminal verification.

Method 2 — Local Setup (mcp-remote) 

For MCP clients that only speak stdio (no native HTTP). The mcp-remote npm package bridges stdio ↔ your TYPO3 HTTP endpoint.

Token in URL

After creating a token, the server accepts: https://<host>/mcp?token=<64-char-hex> (recommended in UI) https://<host>/mcp/r/<64-char-hex> (legacy path form)

In the module: click Local Setup (mcp-remote).

Step-by-step 

1. Click Create mcp-remote Token (if none exists).
2. Copy Token URL (includes ?token=…).

3. Copy Example mcp-remote configuration or build manually:

   {
     "mcpServers": {
       "New TYPO3 site": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://t3af.ddev.site/mcp?token=YOUR_64_CHAR_TOKEN"
         ]
       }
     }
   }

   Copied!

4. Paste into your client’s MCP config:

   • Claude Desktop: claude_desktop_config.json → mcpServers
   • Cursor: .cursor/mcp.json
   • VS Code: MCP extension settings
5. Restart the client so it spawns npx mcp-remote ….

Verify:

# Optional: run bridge manually to see logs
npx mcp-remote "https://t3af.ddev.site/mcp?token=YOUR_TOKEN"

• Client lists TYPO3 tools.
• Active OAuth Tokens shows mcp-remote token with updated Last Used.

Method 3 — Local Setup (TYPO3 CLI) 

Direct stdio transport — no HTTP, no OAuth. The MCP client must run on the same machine as TYPO3 (or inside the DDEV web container).

In the module: click Local Setup (TYPO3 CLI).

Example configuration 

Copy from the module or use:

{
  "mcpServers": {
    "New TYPO3 site": {
      "command": "php",
      "args": [
        "vendor/bin/typo3",
        "nst3af:mcp:serve",
        "--no-startup-message"
      ]
    }
  }
}

The short alias mcp:server also maps to nst3af:mcp:serve when TYPO3 command caches are up to date.

Step-by-step (DDEV) 

1. For Cursor, prefer the full walkthrough in Cursor IDE — two connection methods.

2. For other MCP clients, use DDEV from the host with an absolute cwd:

   {
     "mcpServers": {
       "TYPO3 DDEV": {
         "command": "ddev",
         "args": [
           "exec",
           "php",
           "vendor/bin/typo3",
           "nst3af:mcp:serve",
           "--no-startup-message",
           "--user=admin",
           "--workspace=3"
         ],
         "cwd": "/absolute/path/to/aiuniverse"
       }
     }
   }

   Copied!
3. Terminal verification: see Cursor IDE — two connection methods (pipe test and expected initialize JSON).

4. CLI options:

   • ``–user`` / ``-u`` — Backend username (default admin).
   • ``–workspace`` / ``-w`` — Workspace UID (0 = live).
   • ``–no-startup-message`` — Suppress stderr banner (recommended for MCP).
   • ``-v`` / ``-vv`` — Verbose stderr diagnostics.

Verify:

• MCP client connects without HTTP/OAuth.
• Invoke pages_get with uid: 1 (adjust to a page that exists).

Step 4 — Test Core tools 

Use MCP Inspector, Claude, or any connected client. The TYPO3 Core tab contains many tools — do not assume only four exist. Browse the full catalog in AI Foundation > MCP Tools, then smoke-test a few representative calls.

Starter checks:

table_schema

Input: { "tableName": "pages" } Expect: JSON with field definitions.

pages_get

Input: { "uid": 1 } Expect: Page record (or error if uid missing).

content_list

Input: { "pid": 1, "limit": 5 } Expect: Array of tt_content rows for that page.

write_table (workspace recommended)

{
  "action": "create",
  "tableName": "tt_content",
  "data": "{\"pid\": 1, \"CType\": \"text\", \"header\": \"MCP test\"}"
}

Copied!

Create (use a test page pid and workspace): Expect: JSON with uid, fields, and ignoredFields. Verify with content_list on the same pid. Use action: delete with the new uid to clean up.

Workspace testing

Select a non-live workspace in the module dropdown before issuing tokens. Repeat content_list / pages_get — draft overlays should differ from live.

See MCP Tools for the full Core catalog and MCP Server for connection details.

Step 5 — Active OAuth Tokens table 

After each test, confirm in Active OAuth Tokens:

• Client Name — n8n token, OAuth client name, and similar labels.
• Created / Last Used — Updates on successful calls.
• Expires — Reasonable future date.
• Workspace — Matches dropdown selection.
• Token — Preview plus Copy Token.
• Action — Revoke removes access.

Header actions:

• Refresh — reload table via AJAX
• Revoke All — invalidates every token for your backend user (confirm dialog)

Quick test matrix 

Use this checklist when regression-testing a release:

Remote HTTP clients (Claude, n8n, Manus, MCP Inspector, other OAuth clients)

• Endpoint health is green.
• tools/list works.
• table_schema works.
• Token appears in the connections table.

mcp-remote bridge

• Create token URL.
• npx mcp-remote bridge connects.
• Client stdio config lists tools.

TYPO3 CLI / Cursor stdio

• nst3af:mcp:serve starts.
• Pipe initialize test returns JSON.
• Cursor project cwd is set.
• --user and --workspace match your backend user.
• Tool invocation succeeds.

Cursor URL (``~/.cursor/mcp.json``)

• OAuth at /mcp completes.
• Token appears in the connections table.

Troubleshooting 

Server Status Offline

Enable MCP in Show advanced. Run ddev exec typo3 cache:flush.

/mcp returns 503

enableMcpServer is off (MCP Server → Advanced, or AI Foundation MCP settings).

/mcp returns 401 without token

Expected — proves middleware is reachable. Authenticate with OAuth or Bearer.

OAuth metadata checks red

Verify site base URL, HTTPS, and that config/sites/*/config.yaml routes exist. Flush caches.

Bearer / URL token Authentication failed

Token revoked, expired, or wrong workspace. Create a new token in the module.

mcp-remote client shows no tools

Confirm Node.js is installed, URL includes valid ?token=, restart client.

CLI Backend user not found

Pass --user= <../existing-be-username>.

Tool returns empty / wrong data

Check WORKSPACE dropdown and token workspace pin.

Full token not copyable later

Plaintext is only shown at issuance. Revoke and re-create, or use OAuth flow.

Cleanup after testing 

1. Revoke test tokens in Active OAuth Tokens (or Revoke All).
2. Remove MCP entries from claude_desktop_config.json / .cursor/mcp.json.

3. Optional maintenance:

   ddev exec vendor/bin/typo3 nst3af:mcp:cleanup

   Copied!

See also Configuration and MCP Server.

For administrators 

Daily responsibilities:

• Keep provider API keys valid in AI Foundation > AI Providers.
• Maintain the default provider and model selections.
• Monitor usage statistics across all configured AI providers in AI Foundation > AI Usage and the Dashboard.
• Keep credentials and access permissions under control.

For editors 

Editors usually do not configure providers directly. They interact with features built by other extensions that depend on AI Foundation.

When AI features fail in a backend module:

• Retry once.
• Capture exact error text.
• Inform the administrator with module and page context.

For non-technical stakeholders 

AI Foundation helps organizations by:

• Reducing duplicated AI integration work across extensions.
• Centralizing provider and model governance.
• Improving consistency of AI capabilities across teams.

What to expect operationally 

• Some providers have rate limits and temporary outages.
• Model behavior can differ between providers and versions.
• Usage statistics cover configured AI providers from a centralized view and may be cached (not always real-time).

Known boundaries 

• No standalone frontend plugin is provided by this extension.
• This package is a service layer; UI features come from dependent extensions.

Prerequisites 

• AI Foundation is installed and configured — Installation
• At least one AI provider is connected when your feature needs AI requests — AI Providers
• You understand TYPO3 extension development, Composer, and Symfony dependency injection

Reference extension 

• nitsan-technologies/ns_t3af_extended

Overview 

AI Foundation is a shared foundation layer:

Consuming Extension Code
        |
        v
AiServiceInterface
        |
        v
AdapterRegistry -> Provider adapters
        |
        v
   Provider APIs

Parallel support:

AiStatisticsService -> OpenAiOrganizationUsageService -> OpenAI Usage API
HttpAuthUtility    -> Protected URL fetching with optional Basic Auth

Main components 

• Request orchestration: AiServiceInterface and AiService
• Provider adapters: AdapterRegistry and AdapterInterface implementations
• Statistics processing: AiStatisticsService and OpenAiOrganizationUsageService
• Engine configuration filtering: AiEngineConfiguration
• Utility and environment helpers: AiUniverseUtilityHelper
• HTTP auth helper: HttpAuthUtility

Configuration model 

Runtime AI requests resolve through provider rows in AI Providers. Optional extension settings cover translation helpers, Basic Auth, notifications, and MCP switches. See Configuration.

This includes:

• provider adapters, encrypted API keys, and model IDs
• default provider selection
• optional temperature and capability flags on provider rows
• optional Basic Auth settings for protected URL fetching

Caching 

The extension registers cache nst3af_statistics in ext_localconf.php.

Statistics service stores processed data in this cache to reduce repeated usage API calls.

Constraints 

• No native frontend plugin and no Fluid frontend output in this package.
• Primary role is reusable service infrastructure.

Purpose 

AI Foundation acts as the shared AI gateway for child extensions such as AI Assistant, AI Search, AI Chatbot, AI Accessibility, and custom agency extensions. The child extension prepares the prompt, context, and feature metadata. AI Foundation resolves the provider, executes the request, and records usage attribution.

Request lifecycle 

1. Your extension builds the prompt and context.
2. Your service calls AiServiceInterface.
3. AI Foundation resolves the requested provider or the default provider.
4. The matching adapter performs the completion, stream, or embedding request.
5. Request metadata is logged for usage, analytics, and troubleshooting.

Dependency injection 

Inject the interface into your own service.

use NITSAN\NsT3AF\Api\AiServiceInterface;

final class MyAiService
{
    public function __construct(
        private readonly AiServiceInterface $aiService,
    ) {}
}

Minimal working example 

Pass AiOptions with stable feature metadata. This makes logs and usage analytics useful.

use NITSAN\NsT3AF\Api\AiOptions;
use NITSAN\NsT3AF\Api\AiServiceInterface;

final class SeoDescriptionGenerator
{
    public function __construct(
        private readonly AiServiceInterface $aiService,
    ) {}

    public function generate(string $prompt, int $pageUid): string
    {
        $response = $this->aiService->complete(
            $prompt,
            new AiOptions(
                extensionKey: 'my_extension',
                featureKey: 'seo.meta_description',
                featureLabel: 'SEO meta description',
                requestSource: 'backend_module',
                contentEntityType: 'pages',
                contentEntityUid: $pageUid,
            ),
        );

        return $response->content;
    }
}

What to put in AiOptions 

extensionKey

TYPO3 extension key that initiated the request.

featureKey

Stable machine key for the feature. Keep it unchanged across releases.

featureLabel

Human-readable label for logs and dashboards.

requestSource

Source of the request, such as backend_module, scheduler, or cli.

contentEntityType and contentEntityUid

Optional record context used for drilldown and troubleshooting.

Best practices 

• Use AiServiceInterface as the only runtime AI integration surface.
• Keep featureKey stable so analytics history remains meaningful.
• Treat AI output as untrusted content before rendering or saving it.
• Do not log API keys, provider secrets, or sensitive prompt payloads.
• Handle provider failures and empty responses in your feature code.
• For CLI or Scheduler usage, configure an absolute TYPO3 site base URL when required by your environment.

Troubleshooting 

No provider is resolved

• Confirm a provider is connected in AI Foundation > AI Providers.
• Confirm your feature-level provider override, if used, points to an enabled provider.

Request is missing in logs

• Confirm extensionKey and featureKey are set in AiOptions.
• Check AI Usage & Logs.

Related documentation 

• Feature Provider Overrides
• Custom AI Providers
• AI Providers
• AI Usage & Logs

Provider architecture 

AI Foundation discovers provider adapters from the Symfony service container. Each adapter describes its type, display name, default endpoint, supported capabilities, connection test, and runtime platform object.

Built-in bridge packages are auto-registered when available. AI Foundation also provides the built-in Custom / Other OpenAI-compatible adapter under nst3af.openai_compatible. Use a custom adapter only when the provider is not OpenAI-compatible or needs a custom SDK/protocol.

When to create a provider 

• You use a private or on-premise LLM.
• Your vendor has a custom API that is not OpenAI-compatible.
• Your company routes AI requests through an internal gateway.
• You need capabilities or connection behavior that the built-in adapters do not provide.

Implementation steps 

1. Add a Composer dependency or suggestion on nitsan/ns-t3af.
2. Create an adapter class in your extension.
3. Implement NITSAN\NsT3AF\Provider\Contract\AdapterInterface.
4. Tag the service with nst3af.adapter in your extension.
5. Flush TYPO3 caches.
6. Create a provider row in AI Foundation > AI Providers and select your adapter.
7. Run the connection test.

Minimal adapter shape 

use NITSAN\NsT3AF\Domain\Model\Provider;
use NITSAN\NsT3AF\Provider\Capability;
use NITSAN\NsT3AF\Provider\Contract\AdapterInterface;
use NITSAN\NsT3AF\Provider\Contract\VerifyResult;

final class AcmeAdapter implements AdapterInterface
{
    public function getType(): string
    {
        return 'custom.acme';
    }

    public function getDisplayName(): string
    {
        return 'ACME AI Gateway';
    }

    public function getDefaultEndpoint(): string
    {
        return 'https://llm.example.internal/v1';
    }

    public function getDefaultCapabilities(): array
    {
        return [Capability::CHAT, Capability::STREAMING];
    }

    public function testConnection(Provider $provider): VerifyResult
    {
        // Return VerifyResult::ok() or VerifyResult::failure().
    }

    public function platform(Provider $provider): object
    {
        // Return the SDK/platform object used by the runtime adapter layer.
    }
}

Service registration 

The _instanceof rules inside EXT:ns_t3af do not tag services from your extension. Register the adapter in your own Configuration/Services.yaml.

services:
  _defaults:
    autowire: true
    public: false

  _instanceof:
    NITSAN\NsT3AF\Provider\Contract\AdapterInterface:
      tags: ['nst3af.adapter']

  MyVendor\MyExt\Provider\:
    resource: '../Classes/Provider/*'
    autoconfigure: true

Credentials 

Provider API keys are stored encrypted on provider records. If your SDK needs the plaintext key, decrypt it through AI Foundation’s credential service and never write the value to logs, exceptions, or frontend output.

Best practices 

• Use the custom.<vendor> prefix for custom adapter types.
• Keep adapter type values stable after release.
• Return connection failures through VerifyResult::failure() instead of throwing from testConnection().
• Advertise only the capabilities your adapter really supports.
• Reuse AI Foundation provider rows instead of adding your own provider configuration table.

Verification 

1. Flush caches.
2. Open AI Foundation > AI Providers.
3. Create or edit a provider row and select your adapter.
4. Save the row.
5. Run the connection test and confirm the status updates.
6. Trigger a feature that uses AiServiceInterface with that provider.

Related documentation 

• Extension Integration
• AI Providers
• Configuration

Purpose 

AI prompts are feature prompts, not MCP workflow templates. Use them for extension features such as SEO generation, content generation, chat answers, product summaries, or support replies.

AI Foundation provides the backend module and shared storage. Your extension provides the prompt contracts, category metadata, and runtime resolver.

Architecture 

PromptContractRegistry

Your extension’s PHP source of truth for built-in prompt types, labels, default text, scopes, and required variables.

PromptCatalogProviderInterface

Connects your prompt contracts to AI Foundation > AI Prompts.

tx_nst3af_ai_prompt

Shared table owned by AI Foundation for editor-created custom prompts.

Runtime resolver

Your feature code decides which text to use: explicit request text, saved custom prompt, or built-in default.

Implementation steps 

1. Define prompt contracts in your extension.
2. Implement NITSAN\NsT3AF\Contract\PromptCatalogProviderInterface.
3. Tag the provider with t3af.prompt_catalog_provider.
4. Add a runtime resolver that reads custom prompt rows through AI Foundation services.
5. Use the resolved prompt when calling AiServiceInterface.
6. Flush caches and verify the category in AI Foundation > AI Prompts.

Prompt contract rules 

• Use stable prompt_type values, for example product_summary.
• Use a unique category_id prefixed with your extension key.
• Use [variable] placeholders for required values.
• Do not seed built-in prompts into the database. Keep built-ins in PHP.

Minimal contract idea 

private const CONTRACTS = [
    'product_summary' => [
        'scope' => 'catalog',
        'label' => 'Product summary',
        'defaultText' => 'Write a concise product summary for a TYPO3 catalog page. Focus on key benefits, keep it under 80 words, and use clear retail language.',
        'requiredVariables' => [],
    ],
];

Service registration 

Register prompt providers in your extension.

services:
  _defaults:
    autowire: true
    autoconfigure: true

  _instanceof:
    NITSAN\NsT3AF\Contract\PromptCatalogProviderInterface:
      tags: ['t3af.prompt_catalog_provider']

  MyVendor\MyExt\Prompt\:
    resource: '../Classes/Prompt/'

Runtime usage 

At runtime, resolve prompt text before making the AI request. A common resolution order is:

1. Explicit prompt text passed by the current request.
2. Custom prompt selected by title/type from tx_nst3af_ai_prompt.
3. Built-in default from your contract registry.

Then pass the resolved text to AiServiceInterface with a stable featureKey.

Best practices 

• Keep category IDs unique across the TYPO3 instance.
• Keep prompt types stable after release.
• Validate that custom prompt text still contains required variables.
• Do not create extension-specific prompt tables unless the implementation requires separate domain data.
• Keep prompts focused on one feature workflow.

Verification 

1. Flush TYPO3 caches.
2. Open AI Foundation > AI Prompts.
3. Confirm your category card appears.
4. Open the category and verify built-in prompt rows.
5. Add a custom prompt and save it.
6. Trigger your feature and confirm the resolver can use the custom prompt.

Troubleshooting 

Category is missing

• Confirm the provider is tagged with t3af.prompt_catalog_provider.
• Confirm isAvailable() returns true.
• Flush caches.

Custom prompt is not used

• Confirm extension_key, category_id, scope, and prompt_type match your resolver query.
• Confirm the selected prompt title is passed to the feature runtime.

Related documentation 

• Extension Integration
• Custom AI Features
• AI Prompts

Purpose 

AI Features are not prompt templates and not MCP tools. They are configuration surfaces for extensions that use AI Foundation.

AI Foundation renders the card, drawer, AJAX save/load flow, and per-site storage. Your extension provides the card metadata, allowed settings scope, and field schema.

Architecture 

Settings schema

Configuration/ExtensionSettings/schema.php points to the field definition file.

Field definitions

Configuration/ExtensionSettings/fields.typoscript defines the fields shown in the drawer.

Card provider

AiFeatureCardProviderInterface returns one or more cards for the AI Features overview.

Scope provider

ExtensionSettingsScopeProviderInterface declares which settings scopes your extension accepts.

Storage

Values are stored by AI Foundation in tx_nst3af_extension_setting for the selected site context.

Implementation steps 

1. Add schema.php and fields.typoscript to your extension.
2. Implement AiFeatureCardProviderInterface.
3. Implement ExtensionSettingsScopeProviderInterface.
4. Tag both services in your extension.
5. Read saved values at runtime through the AI Foundation settings service.
6. Flush caches and verify the card in AI Foundation > AI Features.

Schema example 

<?php

declare(strict_types=1);

return [
    'fieldsTemplate' => __DIR__ . '/fields.typoscript',
];

Field example 

The category in # cat= must match the card’s settingsScope.

# cat=my ext settings//01; type=boolean; label=Enable AI-assisted generation
enableAiFeature = 0

# cat=my ext settings//02; type=int+; label=Default number of suggestions
defaultSuggestionCount = 3

Service registration 

services:
  _defaults:
    autowire: true
    autoconfigure: true

  _instanceof:
    NITSAN\NsT3AF\Contract\AiFeatureCardProviderInterface:
      tags: ['t3af.ai_feature_card_provider']
    NITSAN\NsT3AF\Contract\ExtensionSettingsScopeProviderInterface:
      tags: ['t3af.extension_settings_scope']

  MyVendor\MyExt\Feature\:
    resource: '../Classes/Feature/'

Runtime usage 

Read settings through the AI Foundation settings API instead of parsing extension configuration manually. The saved values are merged with schema defaults.

$settings = $this->extensionSettingsService->getAll('my_ext', $storagePid);
$enabled = ($settings['enableAiFeature'] ?? '0') === '1';

Best practices 

• Keep settingsScope stable.
• Use clear labels because editors see them in the backend drawer.
• Do not overload one card with unrelated feature groups.
• Use Feature Provider Overrides when a feature needs its own provider dropdown.
• Flush caches after changing schema or DI definitions.

Verification 

1. Select a site in AI Foundation.
2. Open AI Foundation > AI Features.
3. Confirm your card appears.
4. Open the drawer and verify fields from fields.typoscript.
5. Save settings and reopen the drawer.
6. Confirm your runtime service reads the saved value.

Troubleshooting 

Card is missing

• Confirm the card provider is tagged with t3af.ai_feature_card_provider.
• Confirm isAvailable() returns true.
• Flush TYPO3 caches.

Drawer says the scope is invalid

• Confirm the card settingsScope is listed by your scope provider.
• Confirm the # cat= category matches the same scope.

Related documentation 

• Feature Provider Overrides
• Custom AI Prompts
• AI Features

How it works 

AI Foundation owns the provider rows. The child extension exposes feature-specific provider fields in AI Foundation > AI Features. At runtime, the feature resolves the provider in this order:

1. Provider selected in the runtime modal, if the request includes one.
2. Feature default saved in AI Features.
3. Global default provider fallback.

Supported implementation hook 

Child extensions register provider dropdowns by implementing:

NITSAN\NsT3AF\Contract\FeatureProviderFormOptionsInterface

Register the service with:

t3af.feature_provider_form_options

AI Foundation uses the registered service to render provider options in the feature settings drawer.

Known feature fields 

AI Assistant uses feature-specific default provider fields such as:

• defaultProviderForSeo
• defaultProviderForPages
• defaultProviderForContent
• defaultProviderForTranslation
• defaultModel
• defaultEmbeddingsModel

Each dropdown lists enabled providers from AI Providers. The Default (inherit global provider) option keeps the feature on the global provider path.

Translation note 

defaultModelForTranslation still selects the translation backend, such as DeepL, Google, or an AI-based path. defaultProviderForTranslation applies only to LLM completion paths that use the AI Foundation completion gateway.

Configuration workflow 

1. Register a feature card with Custom AI Features.
2. Add the provider field to that feature’s settings schema.
3. Implement FeatureProviderFormOptionsInterface.
4. Tag the service with t3af.feature_provider_form_options.
5. Flush caches.
6. Open AI Foundation > AI Features and verify the provider dropdown.
7. Save a default provider and test the runtime feature.

Best practices 

• Keep provider field names stable.
• Always include an inherit/default option.
• Use the same label, AI Provider, when the same choice appears in runtime modals.
• Resolve providers through the feature runtime path instead of reading provider rows directly.
• Do not hardcode provider IDs in feature logic.

Verification 

1. Open AI Foundation > AI Providers and confirm at least one provider is enabled.
2. Open AI Foundation > AI Features.
3. Open the feature settings drawer.
4. Confirm the provider dropdown contains enabled providers.
5. Save a feature default.
6. Open the feature runtime modal and confirm the saved provider is preselected.

Troubleshooting 

Dropdown is missing

• Confirm the form-options service implements the correct interface.
• Confirm the service is tagged with t3af.feature_provider_form_options.
• Confirm the related feature card and scope provider are active.

Runtime uses the wrong provider

• Confirm the request field name matches the saved setting.
• Confirm the feature handles default or empty values as fallback.
• Confirm the saved provider row still exists and is enabled.

Related documentation 

• Custom AI Features
• Extension Integration
• AI Providers
• AI Features

Architecture 

Tool handler

A PHP service with an execute() method annotated with #[McpTool].

Tool schema

AI Foundation introspects the handler signature and PHPDoc to publish parameters.

Dependency injection

Tool services must be public and tagged with mcp.tool in your extension.

Invocation context

AI Foundation applies MCP context such as workspace and provider selection before the handler runs.

Backend MCP Tools area

Editors can browse tools, inspect parameters, and test calls through the MCP Tools screen and playground workflow.

Implementation steps 

1. Create a handler class under Classes/Mcp/Tool/.
2. Implement McpToolHandlerInterface or use the #[AsMcpTool] class attribute.
3. Add #[McpTool(name: '...', description: '...')] to execute().
4. Return a JSON string from execute().
5. Register the class as a public service tagged with mcp.tool.
6. Flush caches.
7. Verify the tool with tools/list and tools/call.

Minimal handler 

use const JSON_THROW_ON_ERROR;
use Mcp\Capability\Attribute\McpTool;
use NITSAN\NsT3AF\Mcp\Contract\McpToolHandlerInterface;

final readonly class HelloTool implements McpToolHandlerInterface
{
    #[McpTool(
        name: 'myext_hello',
        description: 'Returns a greeting for the given name.',
    )]
    public function execute(string $name = 'world'): string
    {
        return json_encode(['message' => 'Hello ' . $name], JSON_THROW_ON_ERROR);
    }
}

Service registration 

services:
  _defaults:
    autowire: true
    autoconfigure: true

  _instanceof:
    NITSAN\NsT3AF\Mcp\Contract\McpToolHandlerInterface:
      tags: ['mcp.tool']
      public: true

  MyVendor\MyExt\Mcp\Tool\:
    resource: '../Classes/Mcp/Tool/*'

Parameters 

Map MCP input arguments to typed execute() parameters. Optional parameters need default values. Use PHPDoc @param descriptions so the backend MCP Tools screen can show useful parameter help.

AI Foundation can augment published schemas with global MCP context such as workspace or AI provider selection, depending on the tool type. Your handler should only declare the parameters it actually uses.

Response lifecycle 

Return a JSON string. For expected validation problems, return a structured JSON error. For unexpected failures, throw a clear exception and let the MCP layer map the failure for the client.

Client usage 

Cursor, Claude Desktop, MCP Inspector, and other MCP clients connect through the MCP Server configuration. After connection, the client discovers your tool through tools/list and calls it with tools/call.

Use:

• MCP Server for transport and client connection setup.
• MCP Server — Testing guide for Cursor and Claude Desktop validation.
• MCP Tools for backend tool browsing and playground testing.

Backend MCP Tools card 

If your extension should appear as its own group in AI Foundation > MCP Tools, provide extension card metadata through the supported MCP tools card provider path. Tools are grouped by ownership, namespace inference, or configured tool prefix.

Use stable tool names such as myext_action_name. This keeps tools predictable for external clients and easier to find in the backend.

Best practices 

• Keep tool names stable after release.
• Use a unique prefix that matches your extension.
• Keep handlers thin and delegate business logic to services.
• Avoid calling backend controllers from MCP tools.
• Validate parameters before writing data.
• Respect TYPO3 workspace and backend-user context.
• Return JSON only.
• Do not expose secrets in responses or errors.

Debugging 

Tool does not appear in ``tools/list``

• Confirm the service is registered in the container.
• Confirm it is tagged with mcp.tool.
• Confirm the service is public.
• Confirm execute() has #[McpTool].
• Flush TYPO3 caches.

Tool appears under the wrong backend card

• Confirm the tool name prefix matches the extension metadata.
• Add explicit ownership metadata if namespace inference cannot detect the extension.

Client cannot call the tool

• Verify the MCP Server connection first.
• Test the same tool in AI Foundation > MCP Tools.
• Check the input schema and required parameters.
• Review TYPO3 logs for handler exceptions.

Related documentation 

• MCP Server
• MCP Tools
• MCP Server — Testing guide
• Extension Integration

When to use this 

Implement a provider when your extension:

• exposes a backend module that should be controlled per backend user group
• defines AI feature areas checked with FeaturePermissionGate
• stores records that need tables_select or tables_modify enforcement

Administrators assign the resulting permissions through Backend Users > Backend usergroups > Access Lists. The optional AI Foundation > AI Permissions wizard reads the same merged catalogs.

Step 1 — Implement the provider 

Implement NITSAN\NsT3AF\Contract\AiAccessCatalogProviderInterface in your extension.

namespace MyVendor\MyExt\Access;

use NITSAN\NsT3AF\Access\Dto\FeatureAccessBindingsDescriptor;
use NITSAN\NsT3AF\Access\Dto\FeaturePermissionDescriptor;
use NITSAN\NsT3AF\Access\Dto\ModuleAccessDescriptor;
use NITSAN\NsT3AF\Access\Dto\RecordPermissionDescriptor;
use NITSAN\NsT3AF\Contract\AiAccessCatalogProviderInterface;
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

final class MyExtAccessCatalogProvider implements AiAccessCatalogProviderInterface
{
    public function isAvailable(): bool
    {
        return ExtensionManagementUtility::isLoaded('my_ext');
    }

    public function getExtensionKey(): string
    {
        return 'my_ext';
    }

    public function getCatalogModuleKey(): string
    {
        return 'my_ext';
    }

    public function getModuleAccess(): ?ModuleAccessDescriptor
    {
        return new ModuleAccessDescriptor(
            label: 'My Extension',
            sublabel: 'AI Assistant',
            description: 'Short description for the wizard module card.',
            color: '#2563eb',
            groupMod: 'myvendor_myext_dashboard',
            extension: 'my_ext',
        );
    }

    public function getFeaturePermissions(): array
    {
        return [
            new FeaturePermissionDescriptor(
                id: 'myFeature',
                label: 'My AI Feature',
                description: 'Generate content with AI.',
                permBase: 'MyExt.Feature',
                relevantModules: ['my_ext'],
                group: 'my_ext',
                extension: 'my_ext',
            ),
        ];
    }

    public function getRecordPermissions(): array
    {
        return [
            new RecordPermissionDescriptor(
                id: 'myExtRecords',
                label: 'My Records',
                tables: ['tx_myext_domain_model_item'],
                relevantModules: ['my_ext'],
                relevantFeatures: ['myFeature'],
                readHelp: 'View records',
                writeHelp: 'Create and edit records',
                extension: 'my_ext',
            ),
        ];
    }

    public function getFeatureAccessBindings(): FeatureAccessBindingsDescriptor
    {
        return new FeatureAccessBindingsDescriptor(
            moduleKey: 'my_ext',
            legacyCardPermPrefix: 'tx_myext_dashboard_',
            moduleGroupMod: 'myvendor_myext_',
            tabFeatureMap: ['dashboard' => 'MyExt.Feature'],
        );
    }
}

Step 2 — Register the provider 

Tag the provider in your extension’s Configuration/Services.yaml.

_instanceof:
  NITSAN\NsT3AF\Contract\AiAccessCatalogProviderInterface:
    tags: ['t3af.ai_access_catalog_provider']

MyVendor\MyExt\Access\:
  resource: '../Classes/Access/'

Step 3 — Gate backend UI and routes 

Use FeaturePermissionGate for tabs, cards, and feature areas.

use NITSAN\NsT3AF\Access\FeaturePermissionGate;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$gate = GeneralUtility::makeInstance(FeaturePermissionGate::class);
if (!$gate->grantsModuleTab($GLOBALS['BE_USER'], 'my_ext', 'content')) {
    // return 403
}

You can take the reference below for the function definition:

NITSAN\NsT3AF\Access\FeaturePermissionGate::grantsModuleTab

<?php
public function grantsModuleTab(BackendUserAuthentication $user, string $moduleKey, string $tabIdentifier): bool { }
@param \TYPO3\CMS\Core\Authentication\BackendUserAuthentication $user
@param string $moduleKey
@param string $tabIdentifier
@return bool

For suite child extensions, use the gate method that matches the module family, such as grantsT3AiTab, grantsT3AaTab, grantsT3CsTab, or grantsT3AaCard.

Use RecordAccessEnforcer before mutating records.

use NITSAN\NsT3AF\Access\RecordAccessEnforcer;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$enforcer = GeneralUtility::makeInstance(RecordAccessEnforcer::class);
if ($denied = $enforcer->denyUnlessCanModifyCatalogId($GLOBALS['BE_USER'], 'myExtRecords')) {
    return $denied;
}

Step 4 — Assign permissions 

Administrators can assign permissions in two ways.

Option A — AI Permissions wizard

Open AI Foundation > AI Permissions, select a backend group, and configure the wizard steps or permission matrix tabs.

Option B — Native backend groups

1. Grant the custom feature bit under Custom module options (T3Ai section).
2. Grant the backend module under Modules.
3. Grant tables_select and tables_modify for the relevant tables.

Step 5 — Verify 

• The merged catalog contains your feature and record rows when your extension is loaded.
• A restricted editor without the feature bit cannot open gated tabs or submit protected actions.
• A direct POST without tables_modify returns a 403 JSON response from RecordAccessEnforcer.

Reference implementations 

• EXT:ns_t3af_extended/Classes/Access/T3afExtendedAccessCatalogProvider.php
• EXT:ns_t3ai/Classes/Access/T3AiAccessCatalogProvider.php
• EXT:ns_t3aa/Classes/Access/T3AaAccessCatalogProvider.php
• EXT:ns_t3cs/Classes/Access/T3CsAccessCatalogProvider.php
• EXT:ns_t3as/Classes/Access/T3AsAccessCatalogProvider.php
• EXT:ns_t3ac/Classes/Access/T3AcAccessCatalogProvider.php

Troubleshooting 

Permissions do not appear in the wizard

• Confirm the provider is tagged with t3af.ai_access_catalog_provider.
• Confirm isAvailable() returns true.
• Flush TYPO3 caches so the DI container is rebuilt.

Backend action is still allowed

• Confirm the route calls FeaturePermissionGate or RecordAccessEnforcer before performing the action.
• Confirm the catalog id used in the enforcer matches the id returned by the provider.

Related documentation 

• Extension Integration
• AI Permissions

Installation 

Composer conflicts with another MCP package

AI Foundation includes an MCP server and conflicts with other MCP server packages such as marekskopal/typo3-mcp-server and hn/typo3-mcp-server. Remove those packages before installing nitsan/ns-t3af.

Backend module is missing

1. Confirm ns_t3af is active.
2. Flush all caches.

3. Run:

   ./vendor/bin/typo3 extension:setup
   ./vendor/bin/typo3 cache:flush

   Copied!

Also confirm scheduler and workspaces are available. See Installation.

Providers 

Provider request or Test connection fails

• Confirm the provider row exists and is enabled in AI Foundation > AI Providers.
• Run Test connection from the provider drawer.
• Check the API key, model ID, and endpoint URL (for custom/OpenAI-compatible rows).
• Confirm outbound HTTPS to the provider API works from the server.
• Review backend logs for entries from AI Foundation request logging.

Unexpected model or provider behavior

• Confirm the default provider matches the feature you expect.
• Confirm the model ID on the provider row.
• Check feature-level provider overrides in AI Foundation > AI Features.

No usage statistics shown

• Confirm an OpenAI admin/organization key is set where org usage charts are required.
• Clear caches and open AI Foundation > AI Usage / AI Foundation > AI Logs again.
• Confirm the dashboard analytics cache is available after extension:setup.

Configuration 

HTTP 401 / 403 when fetching a protected URL

If you use the Basic Auth helper in Extension Configuration (ns_t3af):

• Enable basicAuthEnabled.
• Set basicAuthUsername and basicAuthPassword.
• Retry the protected URL fetch.

MCP 

MCP client cannot connect

• Confirm the MCP server is enabled in Extension Configuration.
• Prefer HTTPS on the site base URL.
• For Cursor and similar clients, follow MCP Testing.
• For stdio setups, keep the working directory and user/workspace flags correct.

MCP writes fail after a successful connect

Confirm the backend user has the required module, table, and workspace rights. See AI Permissions.

Report an issue 

Include TYPO3 version, PHP version, ns_t3af version, exact error text, and whether MCP is enabled. Submit via Support.

General 

What is AI Foundation?

The shared AI foundation for T3Planet TYPO3 extensions. It manages providers, MCP, brand context, prompts, access roles, and usage in one backend module. See Overview.

Does it include a frontend plugin?

No. AI Foundation is a backend foundation layer. Visitors see AI through child extensions such as AI Assistant or AI Chatbot.

Which TYPO3 and PHP versions are supported?

TYPO3 12.4–14.x with PHP 8.2 or higher. See System Requirements.

Installation 

How do I install it?

With Composer (composer require nitsan/ns-t3af) or from the TYPO3 Extension Repository. See Installation.

Composer reports a conflict with another MCP package.

Remove conflicting MCP server packages first, then install AI Foundation. See Known Problems.

Providers and MCP 

Can I use local models such as Ollama?

Yes. Use the Ollama provider type or a custom OpenAI-compatible endpoint. See AI Providers.

Test connection fails even with a valid key.

Check the model ID, outbound HTTPS, and provider status. See the provider checklist in Known Problems.

What is MCP?

Model Context Protocol connects AI clients such as Cursor to your TYPO3 instance. See MCP Server.

Privacy 

Where does request data go?

AI Foundation is self-hosted. Prompts and responses go from your server to the AI provider you configure, using your API keys. T3Planet is not in the AI data path. License validation only sends the license key and domain.

Still stuck? 

Open Support with your TYPO3, PHP, and ns_t3af versions and the exact error text.

List of versions 

Product and documentation 

API key portals 

Store keys only in AI Foundation > AI Providers. Never commit keys to Git.

• OpenAI — https://platform.openai.com/api-keys
• Anthropic (Claude) — https://console.anthropic.com/
• Google Gemini — https://aistudio.google.com/apikey
• Mistral — https://console.mistral.ai/
• Azure OpenAI — https://portal.azure.com/
• DeepL (translation setting) — https://www.deepl.com/pro-api

Model references 

• OpenAI models — https://platform.openai.com/docs/models
• Anthropic models — https://docs.anthropic.com/en/docs/about-claude/models
• Gemini models — https://ai.google.dev/gemini-api/docs/models

This documentation 

• Introduction — Start here
• FAQ — Common questions
• Known Problems — Workarounds
• Support — Contact T3Planet

Community 

When to use which link 

• Installing premium — License activation URL above
• Getting API keys — Provider portals above, then AI Providers
• Developer integration — Developer Guide for AiServiceInterface
• MCP client setup — Model Context Protocol site plus MCP Server

Need Help? 

• T3Planet Support — technical support and customer assistance
• GitHub Issues — report bugs or request features