VOOZH about

URL: https://deepwiki.com/MahoCommerce/maho/13.6-maho-intelligence-(lsp-and-mcp-servers)

⇱ Maho Intelligence (LSP and MCP Servers) | MahoCommerce/maho | DeepWiki

Loading...
Loading...
Last indexed: 15 May 2026 (ea8ab8)
Menu

Maho Intelligence (LSP and MCP Servers)

The Maho_Intelligence module provides advanced Language Server Protocol (LSP) and Model Context Protocol (MCP) servers to enhance development workflows with IDE integration and AI assistant support. It supports rich IDE features such as code completion, go-to-definition, hover tooltips, and diagnostics for both PHP and XML files that use Maho's dynamic XML and alias-based configuration system. Additionally, it offers AI-friendly interfaces exposing the Maho domain model to intelligent agents.

Architecture Overview

The Maho Intelligence system is architected around core components that bridge the natural language or editor request spaces with the Maho codebase's entity space via a Registry and Provider pattern. This modular design allows context detection, code alias resolution, and dynamic XML structure indexing.

Core Components

  • Registry (Maho_Intelligence_Model_Registry): Central aggregator providing metadata on class aliases, configuration paths, events, and layout handles.
  • Context Detector (Maho_Intelligence_Model_Lsp_ContextDetector): Detects code completion or definition contexts based on PHP call patterns or XML paths.
  • XML Structure Index (Maho_Intelligence_Model_Lsp_XmlStructureIndex): Dynamically indexes valid XML children by merging all relevant module XML and layout files on demand.
  • Document Store (Maho_Intelligence_Model_Lsp_DocumentStore): Holds the current state of all opened documents from the IDE for incremental updates and live diagnostics.
  • LSP Handlers: Responsible for LSP features such as completion, definition, hover info, and diagnostics.
  • Servers:
    • LSP Server (Maho_Intelligence_Model_Lsp_Server): Handles IDE communication using the Language Server Protocol over JSON-RPC.
    • MCP Server (Maho_Intelligence_Model_Mcp_Server): Facilitates AI assistants to interact with and understand the Maho system via a higher-level Model Context Protocol.

System Interaction Diagram



Sources:

app/code/core/Maho/Intelligence/Model/Lsp/Server.php27-46

app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php13-39

app/code/core/Maho/Intelligence/Model/Lsp/Handler/Completion.php13-27

app/code/core/Maho/Intelligence/Model/Lsp/Server.php49-76




Language Server Protocol (LSP)


The LSP server implements a subset of the Language Server Protocol to enhance IDE support. It supports these methods and notifications:


    

  • Initialization and shutdown (initialize, shutdown)
    • 

  • Document synchronization (textDocument/didOpen, didChange, didSave, didClose)
    • 

  • Code completion (textDocument/completion)
    • 

  • Go-to-definition (textDocument/definition)
    • 

  • Hover information (textDocument/hover)
    • 

  • Real-time diagnostics for unresolved class alias references
    • 



It runs on top of ReactPHP for event-driven, non-blocking I/O handling on stdin/stdout streams.


Server Lifecycle & Key Methods


    

  • Run loop and setup: The server bootstraps ReactPHP event loop, initializes Registry, DocumentStore, XML structure index, and context detector, and attaches LSP message handlers.
    • 

  • Message handling: Incoming messages are parsed; notifications are handled asynchronously, and requests return responses or errors.
    • 

  • Diagnostics: Debounced 300ms to avoid excessive CPU usage during active typing. Diagnostics highlight unresolved Maho class alias references.
    • 

  • XML index invalidation: When an XML file is saved, the XML structure index is invalidated to refresh structure info.
    • 

  • Document synchronization: Stores live document contents for completions and diagnostics.
    • 



See app/code/core/Maho/Intelligence/Model/Lsp/Server.php27-207 for implementation details.




Context Detection and Completion


The Maho_Intelligence_Model_Lsp_ContextDetector analyses the developer’s current editing position to identify relevant contexts for completions and definitions. It supports both PHP and XML contexts.


    

  • PHP context detection is based on regex patterns matching Maho factory calls like Mage::getModel('alias'), Mage::helper('alias'), or Mage::getStoreConfig('config/path').
    • 

  • XML context detection parses the XML tag ancestry and attributes to differentiate contexts such as model aliases, block aliases, config paths, event names, or XML element names.
    • 

  • Special XML path-based rules classify how <class> and <model> tags are interpreted—whether as a model alias, FQCN, or cron run model callback.
    • 



The detector caches compiled regexes and integrates the XML structure index to provide dynamic completions for XML tag names.


Sources:

app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php24-188




XML Structure Indexing


Maho’s XML is dynamic and not constrained by static schemas. To provide accurate XML completion and validation, the Maho_Intelligence_Model_Lsp_XmlStructureIndex merges all module XML files (config.xml, system.xml, adminhtml.xml) and theme layout XML files.


    

  • It recursively builds parent-to-children mappings of element names for each XML file type.
    • 

  • For module XML, merges files from app/code/*/*/*/etc/.
    • 

  • Layout XML files are merged separately from theme directories under app/design.
    • 

  • The index is lazily rebuilt on demand or when invalidated after file save events.
    • 

  • The data structure maps paths like config/global → [models, helpers, ...] for completion suggestions.
    • 



See app/code/core/Maho/Intelligence/Model/Lsp/XmlStructureIndex.php23-176 for full logic.




LSP Handlers Overview
































HandlerResponsibilityNotes
CompletionProvides completion items in contextSupports model/helper/block/resource_model aliases, config paths, event names, XML element names, FQCN autocomplete, etc. Completion.php13-179
DefinitionResolves go-to-definition requestsReturns file URIs and optional line numbers for aliases, class names, methods, templates. Uses Maho::findClassFile() where appropriate. Definition.php13-172
HoverShows hover info including class, file, rewrite infoFormats markdown summaries with class hierarchy and rewrite data from the Registry. Hover.php13-180
DiagnosticReports unresolved class alias referencesRuns regex scans on documents for known alias patterns and flags unresolved aliases. Diagnostic.php19-164


Sources:

app/code/core/Maho/Intelligence/Model/Lsp/Handler/Completion.php13-179

app/code/core/Maho/Intelligence/Model/Lsp/Handler/Definition.php13-172

app/code/core/Maho/Intelligence/Model/Lsp/Handler/Hover.php13-180

app/code/core/Maho/Intelligence/Model/Lsp/Handler/Diagnostic.php19-164




Example: Resolving a Model Alias to File Location


Consider a config.xml defining bundle product type with alias bundle/product_type. The LSP resolves this alias to its physical PHP class file:




This resolution allows the IDE to jump directly to the relevant PHP file.


Sources:

app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php127-130

app/code/core/Mage/Bundle/etc/config.xml19-66

app/code/core/Maho/Intelligence/Model/Lsp/Handler/Definition.php63-84

app/code/core/Maho/Intelligence/Model/Lsp/Handler/Definition.php86-91




Model Context Protocol (MCP)


The MCP server exposes Maho's domain model for AI assistants, enabling them to query the system structure intelligently:


    

  • Tools include:

      

    • get_class_info: Resolve an alias to FQCN and physical file.
      • 

    • search_config: Locate configuration path nodes.
      • 

    • get_event_observers: Retrieve event names and their observers.
      • 

    • get_layout_info: Query layout handles and associated blocks.
      • 

    

    • 



This enables advanced AI-assisted code generation, comprehension, and system navigation.




CLI Commands for Servers


The Intelligence module provides CLI commands to launch these servers:



















CommandDescription
dev:lsp:startStarts the Language Server Protocol (LSP) server on stdin/stdout. Enables IDE integration.
dev:mcp:startStarts the Model Context Protocol (MCP) server for AI assistant integration.


These commands are typically run in a development environment to connect editors or AI agents to Maho’s intelligent services.


Sources:

app/code/core/Maho/Intelligence/Model/Lsp/Server.php27-84

app/code/core/Maho/Intelligence/Model/Lsp/Server.php78-81




Internal Data Flow Summary




In this flow:


    

  • The LSP server receives JSON-RPC messages from the client.
    • 

  • It updates or queries the Document Store for current file contents.
    • 

  • The Context Detector analyzes the cursor location and file content.
    • 

  • Handlers use the Registry for alias and configuration info and consult the XML index when needed.
    • 

  • Results or diagnostics are passed back via JSON-RPC responses or notifications.
    • 



Sources:

app/code/core/Maho/Intelligence/Model/Lsp/Server.php47-110

app/code/core/Maho/Intelligence/Model/Lsp/DocumentStore.php16-45

app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php23-39

app/code/core/Maho/Intelligence/Model/Lsp/XmlStructureIndex.php23-88




Summary


The Maho_Intelligence module enriches the Maho development experience by providing a robust and context-aware Language Server Protocol implementation for IDEs, alongside a Model Context Protocol server designed for AI assistant integration. Through Registry-driven alias resolution, dynamic XML structure indexing, and context detection, it unlocks powerful features like completion, navigation, and diagnostics in complex PHP/XML projects.


Developers running VS Code, Cursor, or AI models like Claude or ChatGPT can leverage these services by starting the respective servers via CLI commands and connecting their tools accordingly.


This leaf page documents the system's architecture, main classes, data flow, and integration points critical to understanding Maho Intelligence’s capabilities.




End of 13.6 - Maho Intelligence (LSP and MCP Servers)