README

MCP server for AI-powered Yii2 code generation and scaffolding

yii2-gii-mcp is a PHP-based Model Context Protocol (MCP) server that enables AI assistants (Firebender, Claude Desktop, Cline, etc.) to interact with Yii2's Gii code generator. This allows AI agents to inspect your database, generate ActiveRecord models, create CRUD interfaces, and scaffold complete application components—all through natural language conversations.

Note: This MCP server works exclusively with Yii2 framework projects. Yii1 and Yii3 are not supported.

Key Features

• Database Inspection - List tables, columns, relationships, indexes, and constraints
• Model Generation - Create ActiveRecord models from database tables with relations
• CRUD Scaffolding - Generate complete CRUD operations (controllers, views, search models)
• Controller Generation - Create custom controllers with specific actions
• Form Generation - Generate form models for data collection and validation
• Module Scaffolding - Create complete Yii2 modules with directory structure
• Extension Scaffolding - Generate extension boilerplate with Composer packaging
• Preview-First Workflow - Review all code before writing to disk (safety built-in)
• Full MCP Support - JSON-RPC 2.0 over stdio, works with any MCP client

Requirements

• PHP 8.2 or higher
• Composer
• Yii2 framework (provided by your project)
• Yii2 Gii module (provided by your project)

Important: This MCP server is designed exclusively for Yii2 framework projects. Yii1 and Yii3 are not supported. If you're using Yii1, please migrate to Yii2 first using the official Yii2 upgrade guide.

Quick Start

1. Installation

Install into your existing Yii2 project via Composer:

cd /path/to/your/yii2/project
composer require took/yii2-gii-mcp

2. Setup (Interactive)

Run the interactive setup wizard to configure everything automatically:

php vendor/took/yii2-gii-mcp/bin/interactive-setup

This wizard will:

• Detect your Yii2 project structure (Basic/Advanced Template)
• Create config-mcp.php configuration file
• Test your database connection
• Configure Firebender or Claude Desktop
• Verify the setup

That's it! Restart your IDE/client and you're ready to use it.

3. Manual Setup (Alternative)

If you prefer manual configuration:

Create config-mcp.php

cp vendor/took/yii2-gii-mcp/examples/config-advanced-template.php config-mcp.php

This smart config template automatically detects your Yii2 structure (Basic/Advanced/Advanced+API).

Important: Add to .gitignore:

echo "config-mcp.php" >> .gitignore

Configure Your MCP Client

For Firebender (Global - recommended):

Edit ~/.firebender/firebender.json:

{
  "mcpServers": {
    "yii2-gii": {
      "command": "php",
      "args": [
        "${workspaceFolder}/vendor/took/yii2-gii-mcp/bin/yii2-gii-mcp"
      ],
      "env": {
        "YII2_CONFIG_PATH": "${workspaceFolder}/config-mcp.php",
        "YII2_APP_PATH": "${workspaceFolder}"
      }
    }
  }
}

For Claude Desktop:

Edit your Claude config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "yii2-gii": {
      "command": "php",
      "args": [
        "/absolute/path/to/your/project/vendor/took/yii2-gii-mcp/bin/yii2-gii-mcp"
      ],
      "env": {
        "YII2_CONFIG_PATH": "/absolute/path/to/your/project/config-mcp.php",
        "YII2_APP_PATH": "/absolute/path/to/your/project"
      }
    }
  }
}

Note: Use absolute paths for Claude Desktop!

4. Docker Setup

If your Yii2 project runs in Docker Desktop, see the Docker-specific guide:

→ docs/DOCKER.md

This covers:

• Two setup options: MCP on host (recommended) or inside container
• Database connection configuration for Docker
• Firebender and Claude Desktop configs for Docker
• Troubleshooting Docker-specific issues
• Example configurations and wrapper scripts

Quick Docker Start (Host-Based - Recommended):

# 1. Install on host (faster, simpler)
composer require took/yii2-gii-mcp

# 2. Run interactive setup
php vendor/took/yii2-gii-mcp/bin/interactive-setup
# Configure database as 127.0.0.1:3306 (Docker exposes ports to host)

# 3. Configure Firebender with examples/docker/firebender-host.json
# 4. Restart PhpStorm - Done!

For container-based setup or troubleshooting, see the full Docker guide.

5. Verify Installation

Test your setup with the diagnostic tool:

php vendor/took/yii2-gii-mcp/bin/diagnose

Or test manually:

YII2_CONFIG_PATH=config-mcp.php php vendor/took/yii2-gii-mcp/examples/test-list-tables.php

6. First Use

Ask your AI assistant (Firebender, Claude, etc.):

"List all database tables"
"Show me the structure of the user table"
"Generate an ActiveRecord model for the party table"
"Create CRUD operations for the venue table"

The AI will use the MCP tools to inspect your database and generate code!

Usage Examples

Database Inspection

You: "What tables are in my database?"
AI: [Uses list-tables tool] "Found 15 tables: users, posts, comments, ..."

You: "Show me the schema for the users table"
AI: [Uses inspect-database] "The users table has columns: id (int), username (varchar), ..."

Model Generation

You: "Generate a User model from the users table"
AI: [Uses generate-model with preview] "Here's a preview of the User model..."

You: "Looks good, generate it"
AI: [Writes file] "Created User model at app/models/User.php"

CRUD Scaffolding

You: "I need CRUD operations for the Post model"
AI: [Uses generate-crud] "Generated:
  - PostController.php
  - PostSearch.php
  - views/post/index.php
  - views/post/view.php
  - views/post/create.php
  - views/post/update.php"

Available Tools

All generation tools default to preview mode for safety.

Troubleshooting

"Tools not available" in AI assistant

1. Run diagnostics: php vendor/took/yii2-gii-mcp/bin/diagnose
2. Check config-mcp.php exists
3. Verify database connection in config
4. Restart your IDE/client completely

Database connection errors

1. Check database credentials in config-mcp.php
2. Ensure database is running
3. Run: php vendor/took/yii2-gii-mcp/bin/diagnose

Firebender doesn't see MCP server

1. Verify ~/.firebender/firebender.json exists and has correct JSON syntax
2. Completely restart PhpStorm (not just close window)
3. Check logs: Help → Show Log in Files

Files not generated

1. Check write permissions on target directory
2. Ask AI to show preview first
3. Verify Gii module is enabled in config

For more troubleshooting, see the comprehensive documentation.

Documentation

• For AI Agents: docs/AI-MEMORY-BANK.md - Complete technical reference
• Interactive Setup: Run php vendor/took/yii2-gii-mcp/bin/interactive-setup
• Diagnostics: Run php vendor/took/yii2-gii-mcp/bin/diagnose
• Examples: See examples/ directory for config templates and test scripts
• Implementation Roadmap: See TODO.md for development plans

Development

Running Tests

# Run all tests
make test

# Run specific test suite
make test-unit             # Unit tests
make test-functional       # Functional tests

# Generate coverage report
make coverage

Or with Composer:

composer test
composer test-unit
composer test-functional

Adding New Tools

See docs/AI-MEMORY-BANK.md for detailed development guidelines.

Support and Contributing

• Issues: Use GitHub Issues to report bugs or request features
• Pull Requests: Fork the repo and follow PSR-12 coding standards
• Tests: Include tests for new tools (we use Codeception)
• Documentation: Update the AI memory bank for significant changes

Authors

• Author: Guido Pannenbecker info@sd-gp.de
• AI Implementation: Significant portions implemented with AI coding agents (Firebender, Claude)

License

MIT - See LICENSE file for details.

Project Status

Phase 1-4 Complete 🎉

• ✅ Full MCP protocol implementation (JSON-RPC 2.0 over stdio)
• ✅ 8 production-ready Gii generator tools
• ✅ Comprehensive test suite (50+ tests)
• ✅ Interactive setup wizard and diagnostic tools
• ✅ Complete documentation for humans and AI agents

Next Phase: Custom Gii templates, code inspection tools, advanced features

See TODO.md for detailed roadmap.