konradmichalik/typo3-ai-mate

AI Mate - Dev-only TYPO3 extension and symfony/ai-mate bridge that exposes the resolved runtime state of a TYPO3 installation (TCA, pages, TypoScript, middlewares, logs, request profiles) to AI coding assistants via MCP tools.

0.1.0 2026-06-19 09:35 UTC

Requires

• php: ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0
• ext-mbstring: *
• helgesverre/toon: ^3.1
• konradmichalik/typo3-request-profiler: ^0.2
• mcp/sdk: ^0.5
• nikic/php-parser: ^5.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0
• psr/log: ^3.0
• symfony/ai-mate: ^0.9
• symfony/console: ^6.4 || ^7.0
• symfony/dependency-injection: ^6.4 || ^7.0
• symfony/finder: ^6.4 || ^7.0
• symfony/process: ^6.4 || ^7.0
• typo3/cms-core: ^13.4 || ^14.3
• typo3/cms-install: ^13.4 || ^14.3

Requires (Dev)

• composer/class-map-generator: ^1.0
• phpunit/phpcov: ^9.0 || ^10.0 || ^11.0 || ^13.0
• phpunit/phpunit: ^10.5 || ^11.0 || ^12.0
• psr/http-message: ^1.0 || ^2.0
• typo3/cms-base-distribution: ^13.4 || ^14.3
• typo3/testing-framework: ^9.5

GPL-2.0-or-later

• Konrad Michalik

Published on Packagist.org on 2026-06-19 09:37 UTC

README

TYPO3 extension typo3_ai_mate

A dev-only TYPO3 introspection bridge for AI coding assistants. It exposes the resolved runtime state of an installation — TCA, page composition, resolved TypoScript, the PSR-15 middleware order, logs and per-request profiles — to assistants like Claude Code, Cursor or Copilot over MCP, so they reason from facts instead of guessing from source files.

Warning

This package is in early development stage and may change significantly in the future. I am working steadily to release a stable version as soon as possible.

Important

This package is active only in a Development context (Environment::getContext()->isDevelopment()).

🤔 Why

AI assistants normally read your raw source and config files and guess at the result. But the state that actually matters — the merged TCA, the resolved TypoScript of a page, the real PSR-15 middleware order, whether a request was cached — is computed at runtime and can't be reliably inferred from files alone.

typo3-ai-mate hands the assistant that already-resolved state instead — see Tools below for the full list of what it exposes. This is often more token-efficient too: a compact resolved summary costs far fewer tokens than having the assistant read and reason over the raw source and config files.

Use cases

• Slow page — "This page is slow — find the performance problem." The assistant reads the profile, spots N+1 queries / cache state / timing, and diagnoses instead of guessing.
• Error page — locate an exception in the logs and tie it back to the page that produced it.
• Major upgrade — surface breaking code, outstanding migrations and runtime deprecations before a major jump.

🔥 Installation

Requirements

• TYPO3 13.4 LTS & 14.3 LTS
• PHP 8.2+
• Composer mode

Composer

composer require --dev konradmichalik/typo3-ai-mate

Note

Requiring typo3-ai-mate automatically pulls in symfony/ai-mate (the MCP server and mate binary) and konradmichalik/typo3-ai-mate (the profile source for the typo3-profiler-* tools) — no separate installs needed.

TER

Download the zip file from TYPO3 extension repository (TER).

🔌 Connect your assistant

Scaffold the Mate workspace and register the tools once:

vendor/bin/mate init       # scaffold mate/ + mcp.json (skip if already present)
vendor/bin/mate discover   # register the typo3-* tools

mate serve is a single MCP server exposing all typo3-* tools — your assistant (Claude Code, Cursor, Copilot, …) starts it for you once it is registered:

claude mcp add typo3-ai-mate --scope project -- ddev exec vendor/bin/mate serve   # DDEV project
claude mcp add typo3-ai-mate --scope project -- ./vendor/bin/mate serve           # host PHP project

Note

After updating the package (composer update), reconnect the MCP server so the assistant picks up new or changed tool schemas — in Claude Code run /mcp and reconnect typo3-ai-mate. Freshly installed vendor code alone is not enough; without a reconnect the assistant keeps using the previously registered tool definitions.

⚙️ How it works

The MCP tools run in the Mate process (its own Symfony DI container, Configuration/Mate.php). They boot no TYPO3; they reach it by shelling out to vendor/bin/typo3 <command> (TYPO3_CONTEXT=Development, stdout→JSON) via the Typo3CliRunner service, or by reading profile artifacts directly. The console commands run in the TYPO3 process (TYPO3 DI, Configuration/Services.yaml) and emit raw JSON.

flowchart LR
    A["AI agent (e.g. Claude)"] -->|MCP| B["Mate process (typo3-* tools)"]
    B -->|shell out| C["TYPO3 process (vendor/bin/typo3)"]
    C -->|JSON| B

Loading

Tools

Area	MCP tool	Purpose
Profiling	typo3-profiler-latest / -list / -search / -get	Inspect recorded per-request profiles as compact summaries (timing, N+1, cache, page.id), each linking a typo3-profiler://profile/{token} resource for the full SQL/section detail.
Page	typo3-page	Show a page's composition: content elements, cache signals and USER_INT plugins.
Records	typo3-records	Read-only record query for any table (structured, parameterised — equality filters via uid/pid/where, never raw SQL). Returns compact rows (uid, pid, label/type, enable columns, timestamps; long text truncated) each with a _flags list (hidden/deleted/timed/fe_group). No restrictions by default so hidden/deleted rows are visible — the answer to "why is this record not showing?". Pass fields for specific columns, mode=full for all columns, respectEnableFields=true for the frontend view. Sensitive columns (passwords and password-type TCA fields) are always redacted, and any embedded emails, IPv4 addresses or secrets in text values are redacted too.
Logs	typo3-logs-search / -tail / -by-level	Search, tail or filter the TYPO3 logs. Returns a compact summary (distinct messages with occurrence counts and lastSeen, no stack traces) by default; pass mode=full for individual entries with truncated traces, and since (e.g. 1h, 2d) to scope to recent entries. Emails, IPv4 addresses and secrets embedded in messages/traces are redacted before output.
TCA	typo3-tca	Dump the resolved (merged, trimmed) TCA of a table.
TypoScript	typo3-typoscript	Dump the resolved frontend TypoScript of a page.
TSconfig	typo3-tsconfig	Dump the resolved Page TSconfig (rootline-merged: mod.*, TCEFORM, TCEMAIN, RTE) or User TSconfig — the backend configuration layer that no single file reveals. Scope large output with a dotted path, e.g. mod.web_layout.
Fluid	typo3-fluid-resolve	Resolve the templateRootPaths/partialRootPaths/layoutRootPaths override chain for a plugin/view (e.g. plugin.tx_news_pi1) and report which physical template/partial/layout file wins — ordered candidate directories with exists flags plus the resolved file.
Middlewares	typo3-middlewares	List the resolved PSR-15 middleware order.
Events	typo3-events	List the resolved PSR-14 event listener registry.
Upgrade	typo3-upgrade-wizards	List pending and completed upgrade wizards — outstanding DB/config migrations.
Extension scanner	typo3-extension-scanner	Statically scan an extension — or all non-core extensions — against the core breaking/deprecation matchers. Returns a compact summary by default (matches grouped by message with strong/weak counts and the affected files, plus a per-origin rollup when scanning all); pass mode=full for individual matches with line content, and ownCode=true to skip third-party (vendor) packages.
Deprecations	typo3-deprecations	Report runtime deprecation notices, deduplicated and counted. Each one carries origins — the likely caller in own code. With deprecation logging enabled, a dev-only log processor records the caller's backtrace at log time for a high-confidence file:line; otherwise it falls back to a class-aware static reverse search across own PHP/Fluid files.
Rendering	typo3-render-page	Render a frontend page via an internal HTTP request (no external curl/Playwright) so runtime notices fire, and report the HTTP status plus the log entries written during that request. Requires a running webserver (e.g. DDEV). An explicit --url is only allowed for the installation's configured site hosts (SSRF guard) and the request is capped at 60s.

💡 Development

Custom typo3-* tools, the Typo3CliRunner recipe and security notes live in DEVELOPMENT.md.

🔗 Related

hauptsacheNet/typo3-mcp-server is a complementary project with a different goal: it gives assistants a native MCP server to create, edit and translate TYPO3 content, safely gated behind workspaces. typo3-ai-mate deliberately does not write anything — it is a dev-only, read-only diagnostics bridge for the resolved runtime state (performance, TypoScript, middlewares, logs). Use the former to edit content, the latter to debug it; they sit happily side by side.

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

⭐ License

This project is licensed under GNU General Public License 2.0 (or later).