typo3-dev-mcp — AI development helper for TYPO3

typo3-dev-mcp gives Claude Code (and any MCP client) live insight into your TYPO3
v13/v14 installation: instead of guessing versions, TCA columns, CTypes or config keys
from files, the AI reads them from the running application. Inspired by
laravel/boost.

Development-only tooling. Do not install or enable in production.

Status: alpha — verified live against TYPO3 13.4 and 14.3, but APIs and
tool output formats may still change between releases.

Installation

composer require --dev "balatd/typo3-dev-mcp:^0.1@alpha"
vendor/bin/typo3 devmcp:install        # or: ddev exec vendor/bin/typo3 devmcp:install

devmcp:install

• registers the MCP server in the project's .mcp.json — when DDEV is detected the
  server is started via ddev exec vendor/bin/typo3 devmcp:serve, otherwise via local PHP;
• composes version-specific AI guidelines into .ai/guidelines/typo3.md and links them
  from CLAUDE.md / AGENTS.md (between idempotent markers, existing content is kept).

Then restart your AI assistant (or run /mcp in Claude Code).

Claude Code is supported out of the box via the project-scoped .mcp.json.
Support for other AI CLIs (Codex, Gemini CLI, …) is coming. Meanwhile any MCP
client can be pointed at vendor/bin/typo3 devmcp:serve manually — and the
composed guidelines already land in AGENTS.md, which most agents read.

Tools

Application and data

Resolved configuration

The backend-module-only corners of TYPO3 — core ships no CLI for any of these.

API discovery

Documentation and diagnostics

content_blocks is only announced when friendsoftypo3/content-blocks is installed.
Because the DI container is cached, installing that package later needs a
vendor/bin/typo3 cache:flush before the tool appears.

Safety model

• Everything is read-only by default; results carry MCP readOnlyHint annotations.
  flush_cache is the only tool that changes state.
• Secret-looking configuration values (password, encryptionKey, tokens, …) are masked
  before they leave the server.
• database_query accepts only SELECT/SHOW/EXPLAIN/DESCRIBE/WITH unless the
  developer sets DEV_MCP_ALLOW_WRITE=1.
• search_docs and extension_info are the only tools that reach the network
  (docs.typo3.org, extensions.typo3.org, Packagist). They use TYPO3's own HTTP client, so
  proxy and TLS settings apply. Set DEV_MCP_NO_NETWORK=1 to keep the server fully offline
  — those two tools then fail with an explanatory message and everything else is unaffected.
• There is deliberately no code-execution tool: nothing this server exposes can run
  arbitrary PHP.

Extending

Custom tools from your extension or sitepackage

Implement BalatD\DevMcp\Mcp\ToolInterface — that's it. With standard
autoconfiguration (autoconfigure: true in your Services.yaml, the default in
every modern extension) the service is tagged and announced automatically:

final class ProjectInfoTool implements ToolInterface
{
    public function getName(): string
    {
        return 'project_info';
    }

    public function getDescription(): string
    {
        return 'Project-specific conventions the AI should know.';
    }

    public function getInputSchema(): array
    {
        return ['type' => 'object', 'properties' => new \stdClass()];
    }

    public function isReadOnly(): bool
    {
        return true;
    }

    public function execute(array $arguments): mixed
    {
        return ['deployTarget' => 'staging.example.com'];
    }
}

Constructor injection works as in any TYPO3 service. Throw a
\RuntimeException with an actionable message on failure — it reaches the AI
as a readable error. After adding a tool, flush the DI cache
(vendor/bin/typo3 cache:flush) and restart the MCP server.

PSR-14 events

#[AsEventListener]
public function __invoke(BeforeToolExecutionEvent $event): void
{
    if ($event->getTool()->getName() === 'flush_cache') {
        throw new \RuntimeException('Cache flushing is disabled in this project.');
    }
}

Requirements

• TYPO3 13.4 LTS or 14, Composer mode
• PHP 8.2, 8.3 or 8.4 — every PHP/TYPO3 combination is tested in CI

Development

The repository ships a DDEV harness with TYPO3 v13 and v14 side by side:

ddev start
ddev install-v13      # TYPO3 13.4 + this extension at /var/www/html/v13
ddev install-v14      # TYPO3 14 + this extension at /var/www/html/v14

Backends: https://v13.typo3-dev-mcp.ddev.site/typo3/ /
https://v14.typo3-dev-mcp.ddev.site/typo3/ (admin / Joh316!!).
Protocol smoke test without an MCP client:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | ddev exec -d /var/www/html/v13 vendor/bin/typo3 devmcp:serve

License

MIT