Yii2 MCP Server

A Model Context Protocol (MCP) server for Yii2 framework, providing database schema inspection, console command execution, and project management tools for Claude Code.

Features

Database Tools

• db_list_tables: List all database tables with details (rows, size, comments)

• db_describe_table: Get detailed schema information for a specific table

• db_table_relationships: Analyze foreign key relationships

• db_execute_query: Execute SELECT queries safely with results

Database Optimization & Analysis (NEW)

• db_analyze_table: Comprehensive table analysis including fragmentation, index efficiency, and storage engine recommendations

• db_get_index_suggestions: Smart index recommendations based on table structure and query patterns

• db_profile_query: Query performance profiling with execution plans and optimization suggestions

• db_monitor_connections: Real-time database connection monitoring with alerting

Yii2 Console Tools

• yii_list_commands: List all available Yii console commands with descriptions

• yii_command_help: Get detailed help for specific commands

• yii_execute_command: Execute safe console commands (dangerous commands blocked)

• yii_list_migrations: Show migration status (applied and pending)

Model & Project Tools

• yii_list_models: List all ActiveRecord models with relationships

• yii_analyze_model: Analyze specific model classes

• project_structure: Get overview of project directory structure

• module_info: Detailed information about specific modules

• config_inspect: Inspect application configuration files

Advanced Module Analysis

• module_detailed_analysis: Comprehensive module analysis including controllers, models, assets, widgets, jobs, services, and traits

• asset_list_bundles: List all asset bundles with CSS/JS files and dependencies

• asset_analyze_dependencies: Analyze asset dependency chains and registration order

• widget_list: Discover widgets and their associated asset bundles

Migration Management

• migration_create: Create new database migrations

• migration_diff: Generate migrations from model/database differences

• migration_rollback: Rollback migrations safely

• migration_generate_from_model: Generate migrations from ActiveRecord models

Code Generation Tools

• generate_crud: Generate CRUD controllers and views

• generate_model: Generate ActiveRecord models from database tables

• generate_api: Generate REST API controllers

• generate_form: Generate form classes

Cache Management

• cache_clear: Clear application cache with options

• cache_inspect: Inspect cache configuration and status

• cache_performance: Analyze cache performance and hit rates

RBAC (Role-Based Access Control)

• rbac_permission_tree: Visualize permission hierarchy

• rbac_user_access: Check user permissions and access levels

• rbac_role_analysis: Analyze role assignments and permissions

• rbac_access_debug: Debug access control issues

Queue System Management

• queue_job_status: Monitor queue job status and progress

• queue_retry_failed: Retry failed queue jobs

• queue_worker_status: Check queue worker status

• queue_clear_failed: Clear failed jobs from queue

Logging & Debugging

• log_error_analysis: Analyze error logs and patterns

• log_performance_issues: Identify performance bottlenecks in logs

• log_search: Search through application logs

• log_tail: Real-time log monitoring

Advanced Database Analysis

• db_index_suggestions: Advanced index optimization recommendations

• db_query_profiler: Detailed query performance profiling

• db_table_analysis: In-depth table structure analysis

• db_connection_monitor: Real-time database connection monitoring

Testing & Quality Assurance

• test_run: Execute test suites

• test_generate: Generate test cases

• test_coverage_report: Generate code coverage reports

Performance Analysis

• performance_profile: Application performance profiling

• asset_performance_analysis: Frontend asset performance analysis

Installation

Option 1: NPM Install (Recommended)

npm install -g yii2-mcp-server

Then configure Claude Code from your Yii2 project directory:

cd /path/to/your/yii2/project
claude mcp add yii2 yii2-mcp-server

Option 2: Manual Installation

1. Clone and Install

   git clone https://github.com/ArtMin96/yii2-mcp-server.git
   cd yii2-mcp-server
   npm install
   npm run build

2. Configure Claude Code

   Using Claude CLI:

   cd /path/to/your/yii2/project
   claude mcp add yii2 node /path/to/yii2-mcp-server/dist/index.js

   Manual JSON Configuration:

   {
     "mcpServers": {
       "yii2": {
         "command": "node",
         "args": ["/path/to/yii2-mcp-server/dist/index.js"],
         "cwd": "/path/to/your/yii2/project"
       }
     }
   }

Configuration

The MCP server automatically detects your Yii2 project configuration:

Database Configuration

The server looks for database configuration in this order:

1. .env file (for environment variables like DB_HOST, DB_DATABASE, etc.)

2. config/db.php file (falls back to default MySQL settings)

Project Detection

• Must be run from a directory containing a yii console script

• Automatically scans modules/, models/, config/ directories

• Supports standard Yii2 directory structure

Usage Examples

Once configured, you can use these tools through Claude Code:

# Database Analysis
Use db_list_tables tool
Use db_describe_table with table_name: "user"
Use db_table_relationships with table_name: "user"

# Database Optimization (NEW)
Use db_analyze_table with table_name: "user"
Use db_get_index_suggestions with table_name: "user"
Use db_profile_query with query: "SELECT * FROM user WHERE status = 'active'"
Use db_monitor_connections with alert_threshold: 50

# Yii2 Console Commands
Use yii_list_commands
Use yii_list_migrations

# Project Structure
Use project_structure
Use yii_list_models with module: "fastnet"

# Advanced Module Analysis
Use module_detailed_analysis with module_name: "fastnet"
Use module_detailed_analysis with module_name: "billing"

# Asset Bundle Analysis
Use asset_list_bundles
Use asset_list_bundles with module_filter: "rbac"
Use asset_analyze_dependencies
Use asset_analyze_dependencies with asset_name: "AppAsset"

# Widget Discovery
Use widget_list
Use widget_list with module_filter: "fastnet"

# Migration Management
Use migration_create with table_name: "user_profiles"
Use migration_diff to generate from model changes
Use migration_rollback with steps: 1

# Code Generation
Use generate_crud with table_name: "posts"
Use generate_model with table_name: "categories" 
Use generate_api with model_class: "User"

# Cache Operations
Use cache_clear with component: "db"
Use cache_inspect
Use cache_performance

# RBAC Analysis
Use rbac_permission_tree
Use rbac_user_access with user_id: 1
Use rbac_role_analysis with role: "admin"

# Queue Management
Use queue_job_status
Use queue_retry_failed with job_id: 123
Use queue_worker_status

# Logging & Debugging
Use log_error_analysis with hours: 24
Use log_search with pattern: "database error"
Use log_tail with lines: 50

# Testing
Use test_run with suite: "unit"
Use test_coverage_report

# Performance Analysis
Use performance_profile with duration: "5m"
Use asset_performance_analysis

Module Analysis Features

Comprehensive Module Understanding:

• Controllers, models, views structure

• Asset bundles and their dependencies

• Widgets and custom components

• Queue jobs and service classes

• Traits and utility classes

• Bootstrap configuration

Asset Bundle Intelligence:

• CSS and JavaScript file mapping

• Dependency tree analysis

• Circular dependency detection

• Optimal registration order

• Source path resolution

Widget Discovery:

• Widget-to-asset-bundle relationships

• Module-specific widget organization

• Dependency mapping

Safety Features

• Read-Only Database Access: Only SELECT queries allowed

• Command Safety: Dangerous commands (like migrate/fresh) are blocked

• Configuration Security: Sensitive config values are not exposed

• Timeout Protection: Commands have 30-second timeout limits

• Interactive Command Detection: Commands requiring user input are flagged

Requirements

• Node.js 18+

• Yii2 project with console access

• MySQL database

• PHP CLI available in PATH

Troubleshooting

Common Issues

1. "Yii script not found"

   • Ensure you're running from the Yii2 project root directory

   • Check that the yii console script exists and is executable

2. Database connection errors

   • Verify your .env file has correct database credentials

   • Ensure MySQL is running and accessible

   • Check that the database specified in config exists

3. Permission errors

   • Ensure the server has read access to your project files

   • Check that PHP CLI is available and can execute the Yii script

Debug Mode

For development and debugging, you can run the server directly:

npm run dev

This will watch for file changes and rebuild automatically.

Development

The server is built with TypeScript and consists of:

• src/index.ts - Main MCP server setup and tool routing

• src/database.ts - Database connection and schema inspection

• src/yii2.ts - Yii2 console command execution and project analysis

• src/config.ts - Configuration management and project detection

To contribute:

1. Fork the repository

2. Make your changes

3. Run npm run build to compile

4. Test with your Yii2 project

5. Submit a pull request

License

MIT License - feel free to use in your projects!