Craft CMS MCP

Added

• logLevel configuration option to control MCP server log verbosity (storage/logs/mcp-server.log). Set to 'debug' for full tool dispatch logging. Default: 'error' (#10)
• Debug logging in tinker tool for execution tracing, security blocks, and error diagnostics

Fixed

• tinker tool now wraps execution in SafeExecution, ensuring unexpected errors surface with real messages instead of the generic "Tool execution failed" (#10)
• Stray output (echo/print/PHP notices from tinker'd code or Craft) no longer corrupts the stdio JSON-RPC stream; it is rerouted to stderr via a non-removable output buffer in bin/mcp-server
• tinker tool blocks unbounded while (ob_get_level()) teardown loops, which would spin forever against the non-removable stdout shield
• tinker tool now drains only output buffers it opened (baseline-aware): the previous ob_get_level() > 0 guard closed outer buffers such as the stdout shield, clobbering the original error with an ErrorException when user code had closed the capture buffer
• Added explicit psy/psysh requirement: tinker relied on it arriving transitively (e.g. via yiisoft/yii2-shell) and fatally errored on installs without it
• run_query and explain_query no longer reject legitimate SELECTs whose columns contain a blocked keyword as a substring (e.g. dateCreated matched CREATE, dateUpdated matched UPDATE); the read-only guard now matches keywords on word boundaries via the shared SqlReadGuard, and explain_query gained the stronger keyword set
• get_deprecations database lookup selected a nonexistent template column, so the query always failed and was silently swallowed; the column is removed and the query now runs
• get_table_counts and get_deprecations check table existence via schema instead of catching every Throwable, so a genuine database error surfaces instead of being masked as "Table not found" / zero results
• list_asset_folders no longer dereferences a null root folder when a volume has no indexed root folder
• list_backups and create_backup guard against filesize()/filemtime() returning false (file removed mid-listing), preventing a TypeError
• Added explicit symfony/polyfill-php84 requirement: array_any() (PHP 8.4) is used on the supported ^8.3 floor and previously relied on the polyfill arriving transitively
• list_event_handlers reported class-level handlers with the class and event fields swapped; Yii stores them as $_events[eventName][className], so the two nesting levels were mislabeled

Changed

• Extracted read-only SQL validation into a shared SqlReadGuard support class used by run_query and explain_query
• Upgraded mcp/sdk from ^0.4 to ^0.6
• Added explicit symfony/finder requirement: the SDK moved it from require to suggest in 0.5, but file-based discovery (used for tool/prompt/resource registration) still needs it at server boot

Fixed

• tinker tool now releases mutex locks after execution, preventing project config deadlocks in long-running MCP process (#7)

Added

• MutexGuard support class for releasing Yii2 mutex locks and resetting Craft's internal lock state

Changed

• Upgraded mcp/sdk from ^0.3 to ^0.4

Added

• Monorepo-aware project root detection in mcp/install wizard
  • Auto-detects .ddev/.git markers in parent directories
  • Config files (.mcp.json, .cursor/mcp.json) placed at actual project root
  • Binary paths automatically prefixed with Craft subdirectory (e.g., backend/vendor/...)
• ProjectRootResolver class for clean project root resolution (SRP)
• Unit tests for ProjectRootResolver

Changed

• Upgraded mcp/sdk from ^0.2 to ^0.3
• PHPStan ignore patterns updated for Craft CMS generic type annotations

Fixed

• mcp/install now writes config files to the correct location in monorepo setups
• Removed dead code branch in McpServerFactory

Added

• Interactive mcp/install wizard for generating MCP client configuration files
  • Auto-detects DDEV vs native PHP environment
  • Supports Claude Code, Cursor, and Claude Desktop clients
  • Options: --environment (-e), --serverName (-s)
• read_logs tool now supports pattern parameter for case-insensitive content search
• read_logs tool now supports source parameter to target specific log files (web, console, queue, or plugin name)
• read_logs tool now discovers plugin logs recursively in subdirectories
• read_logs tool now parses multi-line stack traces into structured arrays
• read_logs tool now sends progress notifications to clients while parsing multiple files
• read_logs tool now supports output parameter (structured or text) for human-readable colored output
• New ResponseFormat enum for reusable tool output format selection
• New LogParser, LogEntry, StackFrame, and LogFormatter classes for clean log architecture

Changed

• Refactored log parsing into dedicated LogParser class for cleaner architecture
• FileHelper::tail() now uses chunk-based reading for improved performance on large files

Fixed

• Fixed null pointer errors in entry, category, and product serialization when related model (section/type/group) is missing
• list_console_commands now discovers all commands including those from plugins
• tinker tool now properly preserves indentation in multi-line PHP input

Added

• 18 new MCP tools expanding the toolset from 32 to 50 tools:
  • Multi-site tools: list_sites, get_site, list_site_groups
  • GraphQL tools: list_graphql_schemas, get_graphql_schema, execute_graphql, list_graphql_tokens
  • Backup tools: list_backups, create_backup
  • Self-awareness tools: get_mcp_info, list_mcp_tools, reload_mcp
  • Commerce tools (Craft Commerce): list_products, get_product, list_orders, get_order, list_order_statuses, list_product_types
• 9 MCP prompts for guided analysis workflows
  • Content analysis: content_health_analysis, content_audit, debug_content_issue
  • Entry management: create_entry_guide, query_entries_guide, bulk_entry_operations
  • Schema exploration: explore_section_schema, field_usage_analysis, explore_content_model
• 12 MCP resources for read-only URI-based data access
  • Schema resources: craft://schema/sections, craft://schema/fields, craft://schema/sections/{handle}, craft://schema/fields/{handle}
  • Config resources: craft://config/general, craft://config/routes, craft://config/sites, craft://config/volumes, craft://config/plugins
  • Content resources: craft://entries/{section}, craft://entries/{section}/{slug}, craft://entries/{section}/stats
• 7 completion providers for intelligent parameter auto-completion
• Extension system for custom prompts via EVENT_REGISTER_PROMPTS event
• Extension system for custom resources via EVENT_REGISTER_RESOURCES event
• SSH tunnel configuration example for remote server access
• Comprehensive documentation for prompts (docs/prompts.md)
• Comprehensive documentation for resources (docs/resources.md)
• Extended documentation in docs/extending.md covering prompts, resources, and completion providers
• Hot-reload support for newly installed plugins without MCP server restart

Changed

• Tool count updated from 32 to 50 tools
• Documentation updated to reflect all available features
• Refactored error handling to align with MCP SDK conventions
• Applied Rector code quality improvements
• PSR-12 compliance across all files
• Added unit tests for new tool classes (BackupTools, CommerceTools, GraphqlTools, McpTools, SiteTools)

Fixed

• clear_caches tool now uses correct CraftFileHelper::clearDirectory() instead of non-existent Fs::clearDirectory()
• read_logs tool now dynamically finds all log files including date-based logs (e.g., web-2026-01-03.log)
• read_logs tool regex pattern updated to match Craft CMS log format
• get_environment tool removed non-existent getTranslationsPath() call

Added

• Initial release
• 32 MCP tools for Craft CMS
• Schema & Structure tools (list_plugins, list_sections, list_fields, list_volumes, list_routes, list_console_commands)
• Content tools (list_entries, get_entry, create_entry, update_entry, list_globals, list_categories, list_users)
• Asset tools (list_assets, get_asset, list_asset_folders)
• System tools (get_system_info, get_config, read_logs, get_last_error, clear_caches)
• Database tools (get_database_info, get_database_schema, get_table_counts, run_query)
• Tinker tool for PHP execution
• Debugging tools (get_queue_jobs, get_project_config_diff, get_deprecations, explain_query, get_environment, list_event_handlers)
• Extension system via EVENT_REGISTER_TOOLS event
• Production safety defaults (disabled by default in production)
• Dangerous tools protection (tinker, run_query, create_entry, update_entry, clear_caches)