mittwald/smart-extension-builder

MCP server for TYPO3 extension development

v0.1.0 2026-05-08 11:20 UTC

Requires

• php: ^8.4
• friendsoftypo3/kickstarter: ^0.4.0
• mcp/sdk: ^0.5.0

Requires (Dev)

• ergebnis/composer-normalize: ^2.44
• mikey179/vfsstream: ^1.6
• phpstan/phpstan: ^2.1.25
• phpunit/phpunit: ^11.2.5
• typo3/coding-standards: ^0.8
• typo3/testing-framework: ^9.0.1

MIT

• Martin Helmich

README

The Smart Extension Builder is a TYPO3 extension that accelerates TYPO3 extension development through AI-powered code generation. Its main component is a Model Context Protocol (MCP) server. Built on top of the friendsoftypo3/kickstarter package, this MCP server exposes powerful scaffolding tools to AI assistants like Claude Code, Cursor, or OpenCode.

License

This project is licensed under the MIT License; see the LICENSE file for details.

Quickstart

This tool is meant to be used as part of your local development environment. It requires a local TYPO3 Composer project, and an AI assistant that supports MCP.

To get started:

1. Install the Smart Extension Builder
2. Configure your AI assistant
3. Learn about use cases and use the tools

Features

This MCP server provides specialized tools for TYPO3 extension development, plus contextual resources for better code generation:

Extension Management

• Extension Creation - Scaffold new TYPO3 extensions with proper structure
• Site Package Creation - Generate complete site packages with templates and configuration
• Dependency Injection - Create and update Services.yaml configuration

Domain Layer

• Domain Models - Generate Extbase domain models with properties and annotations
• Repositories - Create Extbase repository classes
• Validators - Build custom Extbase validators (Model and Property types)

Controllers & Actions

• Controllers - Scaffold Extbase controllers with action methods and Fluid templates
• Plugins - Create frontend plugins with controller-action mappings
• Backend Modules - Generate backend modules with Extbase integration

Data Persistence

• Database Tables - Define database tables with TCA configuration
• Upgrade Wizards - Create upgrade wizards for data migrations

Extension Points

• PSR-14 Events - Define custom PSR-14 event classes
• Event Listeners - Implement PSR-14 event listener classes
• Middleware - Create HTTP middleware for request/response processing
• Type Converters - Build Extbase type converters for custom data types
• Console Commands - Generate Symfony Console commands

Site Configuration

• Site Sets - Create TYPO3 site set configurations
• Site Settings - Define site settings with categories and validation

Localization & Testing

• Language Files - Create/extend XLF translation files
• Test Environment - Set up PHPUnit testing infrastructure

Contextual Resources

• TCA Reference - Access complete Table Configuration Array for all database tables available in your TYPO3 installation
• ViewHelper Documentation - Reference all available Fluid ViewHelpers with documentation

Use Cases

AI-Powered Extension Development

Use AI assistants to rapidly prototype and build TYPO3 extensions:

• "Create a blog extension with Post and Comment models"
• "Add a backend module to manage blog posts"
• "Create an event for post publication with email notification listener"

Learning TYPO3 Development

AI assistants can explain TYPO3 concepts while generating proper code:

• "Explain Extbase repositories and create one for managing products"
• "Show me how middleware works and create one for API authentication"

Migration & Refactoring

Accelerate migration projects:

• "Create upgrade wizards to migrate from old to new data structure"
• "Generate database tables for these legacy entities"

Rapid Prototyping

Quickly scaffold extension components to validate ideas:

• "Create a plugin that displays recent articles"
• "Add a command to import data from CSV"

Prerequisites

• A local (!) TYPO3 v12 or v13 installation (in Composer mode). Using DDEV is recommended.
• An agentic coding assistant with MCP support (like Claude Code or Cursor).

Installation

1. Install via Composer

If your TYPO3 installation uses Composer mode (recommended):

# Install the extension
composer require mittwald/smart-extension-builder

# Or, in DDEV:
ddev composer require mittwald/smart-extension-builder

2. Activate the Extension

# Via CLI
vendor/bin/typo3 extension:setup

# Or, in DDEV:
ddev typo3 extension:setup

3. Start the MCP Server

The extension includes an MCP server command:

vendor/bin/typo3 extension:dev-mcp-server

# Or, in DDEV:
ddev typo3 extension:dev-mcp-server

The server will start and listen for MCP client connections on stdin/stdout.

Setup with AI Tools

Claude Code

Claude Code has native MCP support. Add the server to your Claude Code configuration using the claude mcp add command (run the command from within your project directory):

$ claude mcp add --transport stdio typo3_ext_dev vendor/bin/typo3 extension:dev-mcp-server

If you're running your project in DDEV, use the following version instead:

$ claude mcp add --transport stdio typo3_ext_dev ddev typo3 extension:dev-mcp-server

After configuration:

1. Restart Claude Code
2. The TYPO3 development tools will be automatically available
3. Verify by asking: "What TYPO3 development tools do you have available?"

Read more about adding MCP servers to Claude Code.

Claude Code / OpenCode Skills

This package includes skills that guide you through common TYPO3 development workflows. These skills are compatible with both Claude Code and OpenCode.

Available skills:

• /typo3-extension - Step-by-step guide for creating complete TYPO3 extensions with domain models, controllers, plugins, and Fluid templates
• /typo3-sitepackage - Workflow for kickstarting TYPO3 site packages with templates, site sets, and configuration

Installation:

Install the skills to your project's .claude/skills/ directory using the CLI command:

vendor/bin/typo3 extension:install-skills

# Or, in DDEV:
ddev typo3 extension:install-skills

After installation, type the skill name (e.g., /typo3-extension) in Claude Code or OpenCode and follow the guided workflow.

Cursor

Cursor supports MCP through a mcp.json file, either in your home directory (~/.cursor/mcp.json), or in your project directory (also .cursor/mcp.json).

Since the TYPO3 development MCP server is best configured on a per-project basis, create a .cursor/mcp.json file within your current project directory:

{
  "mcpServers": {
    "typo3-dev": {
      "command": "vendor/bin/typo3",
      "args": ["extension:dev-mcp-server"]
    }
  }
}

Alternatively, if you're using DDEV:

{
  "mcpServers": {
    "typo3-dev": {
      "command": "ddev",
      "args": ["typo3", "extension:dev-mcp-server"]
    }
  }
}

After configuration, Cursor should automatically detect the new configuration and suggest enabling the MCP server.

Read more about adding MCP servers to Cursor via the configuration file.

OpenCode

OpenCode supports MCP servers in its main configuration file. The relevant section of an opencode.jsonc file might look like this:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "typo3-dev": {
      "type": "local",
      "command": ["vendor/bin/typo3", "extension:dev-mcp-server"],
      "enabled": true
    }
  }
}

Alternatively, if you're using DDEV:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "typo3-dev": {
      "type": "local",
      "command": ["ddev", "typo3", "extension:dev-mcp-server"],
      "enabled": true
    }
  }
}

Read more about configuring MCP servers in OpenCode.

Usage Examples

Once configured, you can use natural language with your AI assistant to scaffold TYPO3 code:

Creating an Extension

Create a new TYPO3 blog extension called "my_blog"

Building a Domain Model

Create a Post model for my_blog extension with these properties:
- title (string, required)
- content (text)
- publishDate (DateTime)
- author (string)
- tags (ObjectStorage<Tag>)

Adding a Plugin

Create an Extbase plugin named "BlogList" for the my_blog extension
that displays recent blog posts using the PostController's listAction

Creating a Backend Module

Add a backend module to my_blog extension for managing posts.
Use the PostController with list, show, new, create, edit, and update actions.
Place it in the "web" section.

Setting Up Localization

Create language file locallang.xlf for my_blog with these labels:
- blog.title: "Blog Posts"
- blog.readMore: "Read more"
- blog.author: "Author"

Adding Middleware

Create a frontend middleware called "BlogStatisticsMiddleware" for my_blog that tracks post views. It should run after typo3/cms-frontend/authentication.

Generating Tests

Set up PHPUnit testing environment for my_blog extension

MCP Resources

In addition to tools (which perform actions), this MCP server provides resources - read-only information that you can add to your AI assistant's context for better code generation.

What are Resources?

Resources provide reference information about your TYPO3 system:

• Tools = Actions (create, generate, scaffold)
• Resources = Information (read, query, reference)

You can manually add resources to your conversation context when you need the AI to understand specific aspects of your TYPO3 installation.

Available Resources

1. TCA (Table Configuration Array)

Provides database table structure and configuration information.

Overview Resource: typo3-mcp://tca

• Lists all available database tables
• Shows table titles and label fields
• Provides quick reference for what tables exist

Detailed Resource: typo3-mcp://tca/{tableName}

• Complete TCA configuration for a specific table
• Field definitions with types, validation, and constraints
• Relationship information (foreign keys, MM relations)
• Record types and palettes
• Enable columns (hidden, starttime, endtime, etc.)

2. ViewHelper Reference

Provides complete documentation of all available Fluid ViewHelpers.

Resource: typo3-mcp://view-helper-reference

• Lists all registered ViewHelpers
• Includes documentation and usage examples
• Shows XML namespaces for each ViewHelper

How to Use Resources

In Claude Code

Use the "Add Context" feature to add resources:

1. Click the "+" button or use the attachment icon
2. Select "MCP Resource"
3. Choose the resource you want to add:
   • typo3-mcp://tca - Overview of all tables
   • typo3-mcp://tca/pages - TCA for pages table
   • typo3-mcp://tca/tt_content - TCA for content elements
   • typo3-mcp://view-helper-reference - ViewHelper documentation

The resource content will be added to the conversation context.

In Cursor

Resources can be referenced in your prompts by mentioning them explicitly. The exact method depends on Cursor's MCP implementation.

Usage Examples

Example 1: Creating a Model from TCA

Steps:

1. Add resource: typo3-mcp://tca/tx_news_domain_model_news
2. Ask: "Create an Extbase model that matches this TCA structure"

Result: The AI generates a model with properties matching the actual database fields.

Example 2: Understanding Table Relations

Steps:

1. Add resource: typo3-mcp://tca/pages
2. Add resource: typo3-mcp://tca/tt_content
3. Ask: "Explain how pages and content elements are related"

Result: The AI analyzes the TCA foreign keys and explains the relationship.

Example 3: Writing Fluid Templates

Steps:

1. Add resource: typo3-mcp://view-helper-reference
2. Ask: "Create a template for displaying news with images"

Result: The AI uses actual available ViewHelpers with correct namespaces.

Example 4: Repository Methods from TCA

Steps:

1. Add resource: typo3-mcp://tca/fe_users
2. Ask: "Create a repository with find methods for searchable fields"

Result: The AI generates repository methods based on actual TCA field configuration.

Benefits of Using Resources

• Accurate field names - Uses actual database columns from your TCA
• Correct data types - Matches your existing table structure
• Valid ViewHelpers - Only suggests ViewHelpers that are actually available
• Proper relationships - Understands foreign keys and MM relations
• Context-aware code - Generates code that fits your specific TYPO3 setup

Available Tools Reference

Extension Tools

• typo3_create_extension - Create new TYPO3 extension
• typo3_create_sitepackage - Create site package
• typo3_configure_dependency_injection - Create/update Services.yaml

Domain Layer Tools

• typo3_create_model - Create Extbase domain model
• typo3_create_repository - Create Extbase repository
• typo3_create_validator - Create Extbase validator

Controller Tools

• typo3_create_controller - Create controller with actions
• typo3_create_plugin - Create frontend plugin
• typo3_create_backend_module - Create backend module

Database Tools

• typo3_create_table - Create database table with TCA
• typo3_create_upgrade_wizard - Create upgrade wizard

Event System Tools

• typo3_create_event - Create PSR-14 event
• typo3_create_event_listener - Create event listener

Infrastructure Tools

• typo3_create_middleware - Create HTTP middleware
• typo3_create_type_converter - Create type converter
• typo3_create_command - Create console command

Site Configuration Tools

• typo3_create_site_set - Create site set
• typo3_create_site_settings_definition - Create site settings

Localization & Testing Tools

• typo3_create_locallang - Create/extend XLF files
• typo3_setup_test_environment - Set up testing infrastructure

Reference Tools

• typo3_list_viewhelpers - List available Fluid ViewHelpers by tag name
• typo3_get_viewhelper_documentation - Get complete documentation for a specific ViewHelper

Troubleshooting

MCP Server Won't Start

Check TYPO3 installation:

vendor/bin/typo3 mcp:server --help

Verify extension is active:

vendor/bin/typo3 extension:list

Tools Not Appearing in AI Assistant

1. Verify MCP configuration file path is correct
2. Ensure cwd points to your TYPO3 installation root
3. Restart your AI assistant completely
4. Check server logs for errors

Permission Issues

The MCP server runs with the same permissions as your TYPO3 installation. Ensure the web server user has write access to:

• packages/ directory (for new extensions)
• Extension directories (for modifications)

Debugging

Enable debug mode in TYPO3 to see detailed error messages:

# In your TYPO3 installation
export TYPO3_CONTEXT=Development
vendor/bin/typo3 mcp:server

Contributing

Contributions are welcome! This project follows standard open-source contribution practices.

For detailed information about:

• Development setup
• Project architecture
• Adding new tools and resources
• Coding standards
• Testing guidelines
• Pull request process

Please see CONTRIBUTING.md.