konradmichalik / typo3-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.
Maintainers
Package info
github.com/konradmichalik/typo3-ai-mate
Type:typo3-cms-extension
pkg:composer/konradmichalik/typo3-ai-mate
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
- 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.0
- typo3/cms-install: ^13.4 || ^14.0
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
- typo3/cms-base-distribution: ^13.4 || ^14.0
- typo3/testing-framework: ^9.5
This package is auto-updated.
Last update: 2026-06-18 12:03:44 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.
It is both a TYPO3 extension (it ships console commands that boot inside TYPO3) and a symfony/ai-mate extension (it ships #[McpTool]s that run in the Mate server process and wrap those commands / read profile artifacts).
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.
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.
See docs/USE-CASES.md for the full tool-by-tool flows and the request_id correlation anchor.
🔥 Installation
Requirements
- TYPO3 13.4 LTS & 14.0+
- PHP 8.2+
- Composer mode
Supports
| Version | TYPO3 | PHP |
|---|---|---|
| 0.x | 13-14 | 8.2-8.5 |
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.
🔌 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
Tip
Use ddev exec (not the ddev <version> wrapper — its header line would corrupt the stdio MCP stream). Verify with claude mcp list or /mcp. For Claude Desktop or other clients, add the same command to their mcpServers config.
⚙️ 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.
Tools
| MCP tool | Purpose |
|---|---|
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. |
typo3-page |
Show a page's composition: content elements, cache signals and USER_INT plugins. |
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. |
typo3-tca |
Dump the resolved (merged, trimmed) TCA of a table. |
typo3-typoscript |
Dump the resolved frontend TypoScript of a page. |
typo3-middlewares |
List the resolved PSR-15 middleware order. |
typo3-events |
List the resolved PSR-14 event listener registry. |
typo3-upgrade-wizards |
List pending and completed upgrade wizards — outstanding DB/config migrations. |
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. |
typo3-deprecations |
Report runtime deprecation notices, deduplicated and counted. Each one carries origins — the likely caller in own code (a backtrace frame when available, otherwise a static reverse search for the deprecated symbol across own PHP/Fluid files). |
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). |
Note
The profiler tools (typo3-profiler-*) read profiles recorded by the bundled typo3-ai-mate. Trigger a frontend request in the Development context to produce var/log/profiles/*.json — typo3-render-page does this from within the assistant.
💡 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).