README

Yii2 AI Boost is a Model Context Protocol (MCP) server that provides AI assistants (like Claude Code) with comprehensive tools and guidelines for faster Yii2 application development.

Features

16 MCP Tools - Database inspection and queries, config access, route analysis, component introspection, model and validation inspection, console command discovery, migration inspection, widget inspection, performance profiling, PHP tinker, environment inspection, logging, and FTS5-powered semantic search
Semantic Search - BM25-ranked full-text search over bundled guidelines + Yii2 definitive guide (section-level results, not full files)
Framework Guidelines - Comprehensive Yii2 patterns covering controllers, models, migrations, caching, auth, and more
IDE Integration - Works with Claude Code, Cursor, Zed, and other MCP-compatible editors

Quick Start

For experienced developers:

# 1. Install stable release
composer require codechap/yii2-ai-boost:^1.1 --dev

# Or install beta (includes semantic_search, model_inspector, validation_rules, console_command_inspector, migration_inspector, widget_inspector, performance_profiler, tinker, env_inspector)
composer require codechap/yii2-ai-boost:1.3.0-beta.1 --dev

# 2. Run installation
php yii boost/install

# 3. (Optional) Sync guidelines to your editor (Cursor/Zed)
php yii boost/sync-rules

That's it! Claude Code and other AI tools now have access to your application context.

Installation

Step 1: Require the Package

cd /path/to/yii2/application

# Stable release (8 core tools)
composer require codechap/yii2-ai-boost:^1.1 --dev

# Beta release (16 tools - includes semantic search, model inspector, validation rules, console commands, migration inspector, widget inspector, performance profiler, tinker, env inspector)
composer require codechap/yii2-ai-boost:1.3.0-beta.1 --dev

Step 2: Run Installation Wizard

php yii boost/install

The installation runs automatically and:

Detects your Yii2 environment
Generates configuration files (.mcp.json, boost.json)
Copies framework guidelines to .ai/guidelines/

If installation fails, please open an issue or reach out on X.

Step 3: Connect Claude Code and or your IDE

Claude Code integration

After running php yii boost/install, a .mcp.json file will be generated in your project root. Claude Code will automatically detect and use this configuration to connect to the MCP server.

Codex CLI Configuration @todo

Gemini CLI Configuration @todo

Zed Configuration

For Zed create or open your settings file in .zed/settings.json

{
    "context_servers": {
      "yii2-ai-boost": {
        "enabled": true,
        "command": "php",
        "args" : [
            "yii", "boost/mcp"
        ]
      }
    }
}

Generated Files

After installation, you'll have:

.mcp.json - MCP server configuration for Claude Code
boost.json - Package configuration and tool list
.ai/guidelines/ - Framework and ecosystem guidelines (Markdown)
.cursor/rules/yii2-boost.mdc - (Optional) Generated rules for Cursor
.rules - (Optional) Generated rules for Zed

Usage

View Yii2 information

php yii boost/info

Displays:

Package version and configuration
List of available MCP tools
Status of guidelines and configuration files

Sync Editor Rules

php yii boost/sync-rules

Automatically generates:

Cursor: .cursor/rules/yii2-boost.mdc
Zed: .rules (in project root)

These files contain the core Yii2 guidelines and structural references, giving your AI editor "X-Ray vision" into Yii2 best practices without manual prompting.

Start MCP Server (Manual Testing)

php yii boost/mcp

⚠️ Note: This command is invoked automatically by Cluade Code or your editor. You don't need to run it manually.

The server listens on STDIN for JSON-RPC requests and outputs responses to STDOUT.

Update Guidelines

php yii boost/update

Updates guidelines, downloads Yii2 guide from GitHub, and rebuilds the FTS5 search index.

Guidelines & Editor Integration

Yii2 AI Boost comes with a rich library of "Context Anchors" in .ai/guidelines/. These are Markdown files that define exact structures for Yii2 components (Controllers, Models, Migrations, etc.), preventing AI hallucinations.

1. Active Search (MCP Tool)

The MCP server includes a semantic_search tool powered by SQLite FTS5. AI agents (like Claude or Gemini) can use this to "look up" how to do things in Yii2.

User: "How do I create a migration?"
AI: Calls semantic_search(query="migration") -> Gets BM25-ranked sections -> Writes perfect code.

2. Passive Context (Editor Rules)

Run php yii boost/sync-rules to bake these guidelines directly into your editor's context.

Cursor: Creates a .mdc rule file.
Zed: Creates a .rules file.

This means when you open a file in Zed or Cursor, the AI already knows it should use yii\web\Controller and not Illuminate\Routing\Controller.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to interact with tools and data sources. MCP allows Claude Code and other AI tools to securely access your application's context—database schemas, configuration, routes, and logs—without exposing sensitive data.

Yii2 AI Boost implements MCP v2025-11-25 using JSON-RPC 2.0 over STDIO transport. This means Claude Code communicates with your application through standard input/output, with no need for network configuration.

Learn more about MCP

Available Tools

1. `application_info` - Application Info

Get comprehensive information about your Yii2 application:

Yii2 and PHP versions
Application environment and debug status
Installed modules and extensions

2. `database_schema` - Database Schema

Inspect your database structure:

List all tables with row counts
View detailed table schemas (columns, types, constraints)
Discover Active Record models
View indexes and foreign keys

3. `database_query` - Database Query

Execute SQL queries against your database:

Run SELECT queries with automatic row limiting
Support for bound parameters
Returns execution time and row count
Works with any configured database connection

4. `config_access` - Config Access

Access application configuration safely:

Component configurations
Module configurations
Application parameters (with sensitive data redaction)

5. `route_inspector` - Route Inspector

Analyze your application routes:

URL rules and patterns
Module routes with prefixes
Controller and action mappings
RESTful API endpoints

6. `component_inspector` - Component Inspector

Introspect application components:

List all registered components
View component classes and configurations
Check singleton vs new instance behavior
Inspect component properties

7. `log_inspector` - Log Inspector

Inspect application logs from all configured sources:

Read logs from FileTarget (text files)
Read logs from DbTarget (database table)
Access in-memory logs (current request)
Filter by log level (error, warning, info, trace, profile)
Filter by category with wildcard patterns
Search logs by keywords
Filter by time range
View stack traces (for in-memory logs)

8. `semantic_search` - Semantic Search (FTS5)

Search Yii2 guidelines and documentation with full-text search:

BM25-ranked results using SQLite FTS5 (replaces grep-based search)
Section-level results (relevant sections, not full files)
Supports phrases ("active record"), boolean (migration AND database), prefix (migrat*)
Indexes bundled guidelines + Yii2 definitive guide from GitHub
Porter stemming ("migrating" matches "migration")
Grep fallback if FTS5 index not built yet

9. `model_inspector` - Model Inspector (beta release)

Inspect Active Record models at runtime:

Attributes with database types, labels, and hints
Relations (hasOne/hasMany) with link details and junction tables
Attached behaviors with class names and properties
Scenarios with active and safe attributes
Fields and extra fields for API serialization
Automatic model discovery from @app/models

10. `validation_rules` - Validation Rules (beta release)

Inspect model validation rules and constraints:

All validation rules with parameters and scenario filters
Built-in vs custom validator classification
Error messages per validator grouped by attribute
Constraint summary (required, unique, string length, number range, email, etc.)
Safe attributes per scenario
Supports filtering by specific scenario

11. `console_command_inspector` - Console Command Inspector (beta release)

Discover and inspect Yii2 console commands (./yii commands):

List all discoverable console controllers with class and description
Inspect individual commands with actions, options, and help text
Drill into specific actions for arguments, types, and defaults
Discovers from controllerMap, namespace directory, and modules
Option aliases and PHPDoc-based help extraction

12. `migration_inspector` - Migration Inspector (beta release)

Inspect database migrations and their status:

Status summary with applied/pending counts and last applied migration
Applied migration history with timestamps (sorted most recent first)
Pending migration discovery from configured migration paths
View individual migration source code and apply status
Supports @app/migrations and additional configured paths

13. `widget_inspector` - Widget Inspector (beta release)

Discover and inspect Yii2 widgets:

List available widgets grouped by source (framework core, grid, application)
Inspect widget properties with types, defaults, and PHPDoc descriptions
Public methods with parameter signatures and return types
Event constants (EVENT_*) with declaring class
Class hierarchy chain up to yii\base\Widget
Short name resolution (e.g., "ActiveForm" resolves to yii\widgets\ActiveForm)
Discovers widgets from @app/widgets/, @app/components/, and modules//widgets/ + modules//components/
Note: Yii2 allows widgets anywhere in the codebase. Auto-discovery scans the directories above; widgets in other locations can still be inspected by passing the full class name (e.g., widget: "app\\custom\\MyWidget")

14. `performance_profiler` - Performance Profiler (beta release)

Analyze query performance and index coverage:

EXPLAIN query plans with driver-specific formatting (MySQL, PostgreSQL, SQLite)
Automatic detection of full table scans, missing index usage, filesort, and temporary tables
Per-table index analysis with foreign key column coverage
Missing index detection for FK-like columns (*_id naming convention)
Table statistics (row counts, data/index sizes for MySQL, scan counts for PostgreSQL)
Overview mode with per-table summary and missing-index report across all tables
Supports bound parameters for parameterized query analysis

15. `tinker` - Tinker (beta release)

Execute arbitrary PHP code in the Yii2 application context:

Run any PHP expression or statement with full access to \Yii::$app
Automatic return value capture (tries expression first, falls back to statement)
Output capture for echo/print statements
Configurable timeout (default 5s, max 30s)
Dangerous function blocking (exit, die, shell_exec, system, exec, etc.)
Return values formatted with VarDumper for objects
Output truncated at 100KB, sensitive data automatically redacted

16. `env_inspector` - Environment Inspector (beta release)

Inspect environment variables, PHP extensions, and system configuration:

Environment variables with automatic sensitive value redaction
Prefix filter for environment variables (e.g., "DB", "APP")
Loaded PHP extensions sorted alphabetically with count
Key PHP configuration values (memory_limit, max_execution_time, upload sizes, etc.)
System info: OS, architecture (32/64-bit), working directory
Configurable sections via include parameter

Core Tools Architecture

All 16 tools provide deep introspection into your Yii2 application. They follow a consistent architecture based on the BaseTool abstract class, which provides:

Automatic Sanitization: Sensitive data (passwords, tokens, keys) is automatically redacted from all tool outputs
Database Discovery: Tools automatically detect and access configured database connections
JSON Schema Validation: Input parameters are validated against defined schemas
Error Handling: Graceful error responses without exposing sensitive details

How the Log Inspector Works

The Log Inspector features a multi-reader architecture supporting three log storage methods:

Reader	Source	Best For	Features
InMemoryLogReader	Current request logs (`Yii::getLogger()->messages`)	Real-time debugging during development	Full stack traces, microsecond timestamps
FileLogReader	FileTarget text logs (`@runtime/logs/app.log`)	Reviewing logs from previous requests/sessions	Efficient file handling (5MB+ files), auto-detects rotation
DbLogReader	DbTarget database table (`{{%log}}`)	Production logging & log aggregation	Fast indexed queries, precise time-range filtering

Tools Roadmap

Phase	Tool	Status	Description
1	application_info	✓ Complete	Yii2 version, environment, modules, extensions
1	database_schema	✓ Complete	Tables, columns, indexes, models, foreign keys
1	config_access	✓ Complete	Component, module, and parameter configurations
1	route_inspector	✓ Complete	URL rules, routes, REST endpoints
1	component_inspector	✓ Complete	Component listing, classes, configurations
1	log_inspector	✓ Complete	File, database, and in-memory logs with filtering
1	semantic_search	✓ Complete	FTS5-powered search over guidelines + Yii2 guide
1	database_query	✓ Complete	Execute database queries (limited rows)
2	model_inspector	✓ Complete	Active Record model analysis, properties, relations
2	validation_rules	✓ Complete	Model validation rules, error messages, constraints
2	console_command_inspector	✓ Complete	Console command discovery, actions, options, arguments
3	migration_inspector	✓ Complete	Migration status, history, pending, source viewing
3	widget_inspector	✓ Complete	Available widgets, properties, methods, events, hierarchy
3	performance_profiler	✓ Complete	EXPLAIN plans, index analysis, missing index detection
4	tinker	✓ Complete	Execute arbitrary PHP code in Yii2 application context
4	env_inspector	✓ Complete	Environment variables, PHP extensions, system configuration
5	semantic_search	✓ Complete	SQLite FTS5 search over Yii2 guide + guidelines sourced from GitHub

MCP Protocol

Yii2 AI Boost implements the Model Context Protocol (MCP) v2025-11-25:

Transport: STDIO (local) - reads from stdin, writes to stdout
Format: JSON-RPC 2.0
Tools: Expose functionality to AI assistants
Resources: Provide static content (guidelines, configuration)

Example JSON-RPC Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "application_info",
    "arguments": {
      "include": ["version", "environment", "modules"]
    }
  }
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "version": {
      "yii2_version": "2.0.45",
      "php_version": "8.1.2",
      "php_sapi": "cli"
    },
    "environment": {
      "yii_env": "dev",
      "yii_debug": true,
      "base_path": "/path/to/app",
      "runtime_path": "/path/to/app/runtime"
    },
    "modules": {
      "site": {
        "class": "app\\modules\\site\\Module",
        "basePath": "/path/to/app/modules/site"
      }
    }
  }
}

Response Structure:

jsonrpc: Always "2.0" per JSON-RPC spec
id: Echoes the request ID for request/response matching
result: The actual tool output (sensitive data automatically redacted)

Error Responses use error instead of result:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": "Error details here"
  }
}

Guidelines

The package downloads comprehensive Yii2 development guidelines to .ai/guidelines/core/yii2-2.0.45.md. These cover application structure, controllers, models, views, components, security, performance, and console commands.

Including Guidelines in Your AI Workflow

To use these guidelines with Claude Code or other AI tools, add the following lines to your project's CLAUDE.md file:

@include .ai/guidelines/core/yii2-2.0.45.md

Your AI assistant can also search additional guidelines on-demand via the semantic_search MCP tool (database, cache, auth, validation, etc.).

This ensures AI assistants have access to framework best practices and patterns when working in your project.

Troubleshooting

Getting Help

If you encounter issues:

Check the log files listed below for error details
Open an issue: https://github.com/codechap/yii2-ai-boost/issues
Reach out on X: https://x.com/codechap

Log Files

When debugging, check these log files:

Startup Log: @runtime/logs/mcp-startup.log — Server initialization and tool registration
Error Log: @runtime/logs/mcp-errors.log — PHP errors and exceptions
Request Log: @runtime/logs/mcp-requests.log — JSON-RPC requests and responses
Transport Log: /tmp/mcp-server/mcp-transport.log — Low-level STDIO communication

FAQ

This section will be expanded as common questions arise. For now, please reach out with issues or questions.

Requirements

Component	Version	Status
PHP	7.4, 8.0, 8.1, 8.2, 8.3	✓ Tested
Yii2	2.0.45+	✓ Compatible

Why PHP 7.4? While PHP 7.4 is EOL, Yii2 itself still supports it. As a Yii2 extension, we maintain the same baseline to ensure developers on older Yii2 installations aren't locked out. If your Yii2 app runs, this tool should too.

Why no caching? All introspection data is fetched fresh on every request. This is intentional - as a development tool, you need to see the current state of your application, not stale cached data. When you change a route, schema, or component, the tools should reflect that immediately.

Note: PHP 8.4 support pending. Report any compatibility issues on GitHub.

Development Timeline

Phase	Goal	Status	Tools
1	Core MVP	✓ Complete	8 tools + guidelines + installer
2	Model & Command Introspection	✓ Complete	+3 tools (model inspector, validation rules, console commands)
3	Extended Tools	✓ Complete	+3 tools (migration inspector, widget inspector, performance profiler)
4	Advanced Tools	✓ Complete	+2 tools (tinker, env inspector)
5	Semantic Search	✓ Complete	SQLite FTS5 index, GitHub content pipeline, BM25-ranked search

Track progress and contribute at GitHub.

License

BSD 3-Clause License. See LICENSE file for details.

Contributing

Contributions are welcome! Here's how to get started:

Fork the repository
Clone your fork and create a branch (git checkout -b feature/my-feature)
Install dependencies (composer install)
Make your changes
Test your changes (composer test)
Check code style (composer cs-check) and fix if needed (composer cs-fix)
Run static analysis (composer analyze)
Commit with a clear message and push to your fork
Open a Pull Request against master

Guidelines

Follow PSR-12 code style
Add tests for new functionality where practical
Keep changes focused - one feature/fix per PR
Update documentation if adding new tools or changing behavior

Areas Where Help is Appreciated

Additional test coverage (especially integration tests)
New tools from the roadmap
Documentation improvements
Bug reports with reproduction steps

Support & Feedback

Bug Reports & Feature Requests: GitHub Issues
Direct Contact: @codechap on X

Yii2 AI Boost - Making Yii2 development smarter and faster with AI assistants.

codechap / yii2-ai-boost

Maintainers

Details

README

Features

Quick Start

Installation

Step 1: Require the Package

Step 2: Run Installation Wizard

Step 3: Connect Claude Code and or your IDE

Generated Files

Usage

View Yii2 information

Sync Editor Rules

Start MCP Server (Manual Testing)

Update Guidelines

Guidelines & Editor Integration

1. Active Search (MCP Tool)

2. Passive Context (Editor Rules)

What is MCP?

Available Tools

1. application_info - Application Info

2. database_schema - Database Schema

3. database_query - Database Query

4. config_access - Config Access

5. route_inspector - Route Inspector

6. component_inspector - Component Inspector

7. log_inspector - Log Inspector

8. semantic_search - Semantic Search (FTS5)

9. model_inspector - Model Inspector (beta release)

10. validation_rules - Validation Rules (beta release)

11. console_command_inspector - Console Command Inspector (beta release)

12. migration_inspector - Migration Inspector (beta release)

13. widget_inspector - Widget Inspector (beta release)

14. performance_profiler - Performance Profiler (beta release)

15. tinker - Tinker (beta release)

16. env_inspector - Environment Inspector (beta release)

Core Tools Architecture

How the Log Inspector Works

Tools Roadmap

MCP Protocol

Example JSON-RPC Request

Example Response

Guidelines

Including Guidelines in Your AI Workflow

Troubleshooting

Getting Help

Log Files

FAQ

Requirements

Development Timeline

License

Contributing

Guidelines

Areas Where Help is Appreciated

Support & Feedback

1. `application_info` - Application Info

2. `database_schema` - Database Schema

3. `database_query` - Database Query

4. `config_access` - Config Access

5. `route_inspector` - Route Inspector

6. `component_inspector` - Component Inspector

7. `log_inspector` - Log Inspector

8. `semantic_search` - Semantic Search (FTS5)

9. `model_inspector` - Model Inspector (beta release)

10. `validation_rules` - Validation Rules (beta release)

11. `console_command_inspector` - Console Command Inspector (beta release)

12. `migration_inspector` - Migration Inspector (beta release)

13. `widget_inspector` - Widget Inspector (beta release)

14. `performance_profiler` - Performance Profiler (beta release)

15. `tinker` - Tinker (beta release)

16. `env_inspector` - Environment Inspector (beta release)