AI Chat for TYPO3 (nr_mcp_agent)

CI

[!NOTE] Proof of concept. This extension explores a concrete question: is agent-like behavior possible within the TYPO3 backend? It is not intended to answer whether this is the right architectural approach — the space is moving fast, and the tradeoffs between MCP, tool-calling, browser-side agents, and custom integrations are far from settled. The goal here is to show that it works, and to invite feedback from anyone thinking about the same problem. If you have thoughts, open an issue.

AI Chat integrates a conversational AI assistant into the TYPO3 backend. Powered by nr-llm and the Model Context Protocol (MCP), it enables backend users to manage content through natural language.

AI agent creating a page, adding content, and rating it in TYPO3

Features

  • Integrated chat module -- A dedicated backend module under Admin Tools with a modern chat interface built as a Lit web component.
  • Content management via MCP -- Connect to hn/typo3-mcp-server to give the AI access to TYPO3 content operations (pages, records, content elements).
  • Conversation history -- Persistent conversations with resume, rename, pin, and auto-archive support.
  • Background processing -- Messages are processed via CLI commands (exec or worker mode), keeping the web server responsive.
  • Floating chat panel -- A toolbar-triggered bottom panel that stays visible across module navigation, allowing users to chat while working in the page tree.
  • Markdown rendering -- LLM responses are rendered as rich Markdown (headings, lists, code blocks, tables) using vendored marked.js v15 and DOMPurify v3. No build step required.
  • Secure by design -- Group-based access control, message length limits, concurrency caps, sanitized error messages, and XSS-safe Markdown rendering.

Supported file formats

The AI chat supports file uploads for use as conversation attachments. Supported formats depend on your configured LLM provider:

Format MIME type Availability
PDF application/pdf Always (text extracted server-side)
DOCX application/vnd.openxmlformats-officedocument.wordprocessingml.document Always (text extracted server-side)
TXT text/plain Always
XLSX application/vnd.openxmlformats-officedocument.spreadsheetml.sheet Requires phpoffice/phpspreadsheet (see below)
Images (JPEG, PNG, WebP) various Requires a vision-capable provider
Native PDF/DOCX various Requires a DocumentCapable provider (e.g. Anthropic Claude)

When a provider natively supports a format (e.g. Claude natively handles PDFs), the file is sent as-is. Otherwise, text is extracted server-side and injected into the prompt.

XLSX support (optional)

XLSX uploads require the optional phpoffice/phpspreadsheet library:

composer require phpoffice/phpspreadsheet:^3.0

If not installed, XLSX files will be rejected at upload time with a 422 response.

Quick Start

  1. Install the extension:

    composer require netresearch/nr-mcp-agent
vendor/bin/typo3 database:updateschema

  2. In nr-llm, create a Task record that configures your LLM provider (e.g. OpenAI, Anthropic). Note the UID.

  3. Go to Admin Tools > Settings > Extension Configuration > nr_mcp_agent and set llmTaskUid to the Task UID from step 2.

The AI Chat module is now available under Admin Tools > AI Chat.

Enable MCP (optional)

  1. Set enableMcp = 1 in the extension configuration.
  2. A default MCP Server record (server_key=typo3, transport=stdio, arguments=mcp:server) is created automatically on the first chat request. To customise or add additional servers, open the List module at pid = 0.

If you use hn/typo3-mcp-server as the stdio backend, install it first:

composer require hn/typo3-mcp-server

Multiple MCP servers can be configured simultaneously. Tool names are prefixed with the server key (e.g. typo3__ReadTable) so the LLM knows which server to call.

DDEV Development

git clone https://github.com/netresearch/t3x-nr-mcp-agent.git
cd t3x-nr-mcp-agent
ddev start
ddev composer install
ddev typo3 database:updateschema

Run quality checks:

ddev composer ci             # All checks (PHPStan + CGL + tests)
ddev composer ci:phpstan     # Static analysis (includes architecture tests)
ddev composer ci:cgl         # Code style check
ddev composer ci:tests:unit  # Unit tests only
ddev composer ci:tests       # Unit + functional tests
ddev composer ci:mutation    # Mutation testing (Infection)
ddev composer fix:cgl        # Fix code style

Run JavaScript unit tests (Jest):

npm install
npm run test:js

For Docker-based testing that mirrors CI exactly (no DDEV required):

./Build/Scripts/runTests.sh -s unit        # Unit tests
./Build/Scripts/runTests.sh -s phpstan     # PHPStan
./Build/Scripts/runTests.sh -s cgl         # Code style check
./Build/Scripts/runTests.sh -s mutation    # Mutation testing
./Build/Scripts/runTests.sh -s unit -p 8.3 # Specific PHP version

Configuration

All settings are in Admin Tools > Settings > Extension Configuration > nr_mcp_agent:

Setting Default Description
llmTaskUid 0 UID of the nr-llm Task record (required)
processingStrategy exec exec (fork per request) or worker (long-running)
allowedGroups (empty) Comma-separated group UIDs (empty = all)
enableMcp false Enable MCP server integration
maxMessageLength 10000 Max characters per message
maxActiveConversationsPerUser 3 Max concurrent processing conversations
maxConversationsPerUser 50 Max conversations kept per user
autoArchiveDays 30 Auto-archive after N days of inactivity

For the full documentation, see the Documentation/ folder or the rendered docs on docs.typo3.org.

Architectural decisions are documented as ADRs in Documentation/Developer/ADR/.

Acknowledgments

License

GPL-2.0-or-later. See LICENSE for details.