### Install Extension from Source

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/editor-vscode.md

Steps to build and install the Magento 2 LSP extension from its source code repository.

```bash
cd editors/vscode
npm install
npm run build
```

```bash
npm install -g @vscode/vsce
vsce package
code --install-extension magento2-lsp-0.0.1.vsix
```

--------------------------------

### Install from Source

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/README.md

Cloning and building the project locally for development or custom integration.

```bash
git clone https://github.com/mage-os-lab/magento2-lsp.git
cd magento2-lsp
npm install
npm run build
```

--------------------------------

### Install Magento 2 LSP

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/editor-neovim.md

Install the Magento 2 Language Server Protocol globally using npm. This command should be run in your terminal.

```bash
npm install -g @mage-os/magento2-lsp
```

--------------------------------

### VS Code Extension Installation and Configuration

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Install the Magento2 LSP VS Code extension from the marketplace and optionally configure the custom binary path in your `settings.json` file.

```bash
# Install the extension
code --install-extension mage-os.magento2-lsp

# Configure custom binary path (optional) in settings.json
{
  "magento2-lsp.binary.path": "/absolute/path/to/magento2-lsp"
}
```

--------------------------------

### Install Magento 2 LSP Extension

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/editor-vscode.md

Install the Magento 2 LSP extension directly from the VS Code Marketplace.

```bash
code --install-extension mage-os.magento2-lsp
```

--------------------------------

### Configure LSP Completion Matcher

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Set the completion matcher strategy and start the LSP server via standard I/O.

```bash
# Completion matcher: 'fuzzy' (default) or 'segment'
export MAGENTO_LSP_COMPLETION_MATCHER=segment

# Then start the LSP server
magento2-lsp --stdio
```

--------------------------------

### MCP Server Setup for Claude Code

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Set up the MCP server for AI agent integration. This can be done via the CLI, by manually adding to `.mcp.json`, or by using `npx` to run without a global installation.

```bash
# Add via CLI
claude mcp add magento2-lsp-mcp magento2-lsp-mcp

# Or manually add to .mcp.json in project root
{
  "mcpServers": {
    "magento2-lsp-mcp": {
      "command": "magento2-lsp-mcp"
    }
  }
}

# Or run without global install using npx
{
  "mcpServers": {
    "magento2-lsp-mcp": {
      "command": "npx",
      "args": ["-y", "@mage-os/magento2-lsp", "magento2-lsp-mcp"]
    }
  }
}
```

--------------------------------

### Magento Module Overview Response

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Example JSON response for a small Magento module, showing full arrays for all sections.

```json
{
  "fqcn": "Magento\Catalog\Model\Product",
  "file": "vendor/magento/module-catalog/Model/Product.php",
  "module": "Magento_Catalog",
  "preference": { "implementation": "...", "declaredIn": "...", "area": "...", "module": "..." },
  "pluginsByMethod": {
    "save": [
      {
        "prefix": "before",
        "pluginClass": "...",
        "pluginMethod": "beforeSave",
        "pluginFile": "...",
        "declaredIn": "...",
        "area": "...",
        "module": "...",
        "inherited": false
      }
    ]
  },
  "events": [
    { "eventName": "...", "observerName": "...", "declaredIn": "...", "area": "...", "module": "..." }
  ],
  "virtualTypes": [],
  "argumentInjections": [],
  "layoutReferences": [],
  "isPlugin": false,
  "pluginTargets": []
}
```

--------------------------------

### Run Zed from Terminal with Rust Environment

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/editor-zed.md

Source the Rust environment and open Zed from the terminal. This is necessary for installing the extension in development mode if ~/.cargo/bin is not in your PATH.

```bash
source ~/.cargo/env && open -a Zed
```

--------------------------------

### Configure Magento 2 LSP Settings

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/editor-neovim.md

Customize the Magento 2 LSP server behavior by providing `init_options`. This example shows how to set a custom template directory and choose between 'codeLens' or 'inlayHint' modes for displaying indicators.

```lua
['magento2-lsp'] = {
  cmd = { 'magento2-lsp', '--stdio' },
  filetypes = { 'php', 'xml' },
  root_dir = function(bufnr, on_dir) 
    -- ... (same as above)
  end,
  init_options = {
    templateDir = '.magento2-lsp/templates',
    hintMode = 'inlayHint',  -- or 'codeLens' (default)
  },
}
```

--------------------------------

### Magento Class Resolution Response

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Example JSON response for resolving a class name to its file path and vice versa.

```json
{
  "fqcn": "Magento\Catalog\Model\Product",
  "resolvedFile": "vendor/magento/module-catalog/Model/Product.php",
  "phpFile": "vendor/magento/module-catalog/Model/Product.php",
  "resolvedFqcn": "Magento\Catalog\Model\Product",
  "module": "Magento_Catalog"
}
```

--------------------------------

### LSP Diagnostics for XML Configurations

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Examples of XML configuration errors detected by the LSP, such as broken class references, duplicate plugins, and missing observers.

```xml
<!-- di.xml: Broken class reference -->
<preference for="Vendor\Module\Api\NonExistentInterface" type="..."/>
<!-- Error: Class 'Vendor\Module\Api\NonExistentInterface' not found -->

<!-- di.xml: Duplicate plugin name -->
<type name="Magento\Catalog\Model\Product">
    <plugin name="product_save_plugin" type="Vendor\Module\Plugin\First"/>
</type>
<type name="Magento\Catalog\Model\Product">
    <plugin name="product_save_plugin" type="Vendor\Module\Plugin\Second"/>
    <!-- Warning: Duplicate plugin name 'product_save_plugin' for type -->
</type>

<!-- events.xml: Missing ObserverInterface -->
<observer instance="Vendor\Module\Observer\BrokenObserver"/>
<!-- Warning: Class does not implement Magento\Framework\Event\ObserverInterface -->

<!-- Layout XML: Broken template reference -->
<block template="Vendor_Module::nonexistent/template.phtml"/>
<!-- Warning: Template 'Vendor_Module::nonexistent/template.phtml' not found -->

<!-- webapi.xml: Missing service method -->
<service class="Vendor\Module\Api\ExampleInterface" method="nonExistentMethod"/>
<!-- Warning: Method 'nonExistentMethod' not found on service class -->

<!-- ACL reference: Undefined resource -->
<resource ref="Vendor_Module::undefined_resource"/>
<!-- Warning: ACL resource 'Vendor_Module::undefined_resource' not defined in any acl.xml -->

<!-- db_schema.xml: Broken foreign key -->
<constraint xsi:type="foreign" referenceTable="nonexistent_table" referenceColumn="id"/>
<!-- Warning: Foreign key referenceTable 'nonexistent_table' not found -->
```

--------------------------------

### Retrieve Database Schema Response

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Example response for magento_get_db_schema, detailing table columns, foreign keys, and the source module file.

```json
{
  "tableName": "catalog_product_entity",
  "comment": "Catalog Product Table",
  "resource": "default",
  "engine": "innodb",
  "columns": [
    {
      "name": "entity_id",
      "type": "int",
      "nullable": false,
      "identity": true,
      "unsigned": true,
      "comment": "Entity ID",
      "module": "Magento_Catalog"
    },
    {
      "name": "sku",
      "type": "varchar",
      "length": "64",
      "nullable": false,
      "identity": false,
      "comment": "SKU",
      "module": "Magento_Catalog"
    }
  ],
  "foreignKeys": [
    {
      "referenceId": "CAT_PRD_ENTT_ATTR_SET_ID_EAV_ATTR_SET_ATTR_SET_ID",
      "column": "attribute_set_id",
      "referenceTable": "eav_attribute_set",
      "referenceColumn": "attribute_set_id",
      "onDelete": "CASCADE"
    }
  ],
  "declaredIn": [
    { "module": "Magento_Catalog", "file": "vendor/magento/module-catalog/etc/db_schema.xml" }
  ]
}
```

--------------------------------

### Magento Module Overview Response (Large Module)

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Example JSON response for a large Magento module, where certain sections are summarized with a 'count' field.

```json
{
  "moduleName": "Magento_Catalog",
  "modulePath": "vendor/magento/module-catalog",
  "loadOrder": 34,
  "preferences": { "count": 102 },
  "plugins": { "count": 48 },
  "virtualTypes": { "count": 37 },
  "observers": { "count": 27 },
  "routes": [
    { "routeId": "catalog", "frontName": "catalog", "routerType": "standard", "area": "frontend" }
  ],
  "webapiEndpoints": { "count": 81 },
  "dbTables": ["catalog_product_entity", "catalog_category_entity"],
  "aclResources": [
    { "id": "Magento_Catalog::catalog", "title": "Catalog" }
  ]
}
```

--------------------------------

### Rescan Project Response

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Example response for magento_rescan_project, indicating the scope of the re-indexed Magento project files.

```json
{
  "projectRoot": "/path/to/magento",
  "moduleCount": 417,
  "diXmlFiles": 1200,
  "eventsXmlFiles": 150,
  "layoutXmlFiles": 800,
  "routesXmlFiles": 45,
  "themes": 3
}
```

--------------------------------

### Get Magento Module Overview

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Retrieves a summary of a Magento module's declared components. Use 'detail: true' for full arrays of preferences, plugins, etc.

```json
{
  "tool": "magento_get_module_overview",
  "arguments": {
    "filePath": "/path/to/magento/vendor/magento/module-catalog/Model/Product.php",
    "moduleName": "Magento_Catalog",
    "detail": false
  }
}
```

```json
{
  "moduleName": "Magento_Catalog",
  "modulePath": "vendor/magento/module-catalog",
  "loadOrder": 34,
  "preferences": { "count": 102 },
  "plugins": { "count": 48 },
  "virtualTypes": { "count": 37 },
  "observers": { "count": 27 },
  "routes": [
    { "routeId": "catalog", "frontName": "catalog", "routerType": "standard", "area": "frontend" }
  ],
  "webapiEndpoints": { "count": 81 },
  "dbTables": ["catalog_product_entity", "catalog_category_entity", "catalog_product_website"],
  "aclResources": [
    { "id": "Magento_Catalog::catalog", "title": "Catalog" },
    { "id": "Magento_Catalog::products", "title": "Products" }
  ]
}
```

```json
{
  "tool": "magento_get_module_overview",
  "arguments": {
    "filePath": "/path/to/magento/app/code/Vendor/Module/registration.php",
    "detail": true
  }
}
```

```json
{
  "moduleName": "Vendor_Module",
  "modulePath": "app/code/Vendor/Module",
  "loadOrder": 450,
  "preferences": [
    { "interface": "Vendor\\Module\\Api\\ExampleInterface", "implementation": "Vendor\\Module\\Model\\Example", "area": "global", "file": "app/code/Vendor/Module/etc/di.xml" }
  ],
  "plugins": [
    { "targetClass": "Magento\\Catalog\\Model\\Product", "pluginClass": "Vendor\\Module\\Plugin\\ProductPlugin", "area": "global", "file": "app/code/Vendor/Module/etc/di.xml" }
  ],
  "virtualTypes": [],
  "observers": [
    { "eventName": "catalog_product_save_after", "observerName": "vendor_module_observer", "observerClass": "Vendor\\Module\\Observer\\ProductObserver", "area": "global", "file": "app/code/Vendor/Module/etc/events.xml" }
  ],
  "routes": [],
  "webapiEndpoints": [
    { "url": "/V1/vendor/example/:id", "httpMethod": "GET", "serviceClass": "Vendor\\Module\\Api\\ExampleInterface", "serviceMethod": "getById" }
  ],
  "dbTables": ["vendor_example"],
  "aclResources": [
    { "id": "Vendor_Module::example", "title": "Manage Examples" }
  ]
}
```

--------------------------------

### Configure MCP Server with npx

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp.md

Configure the MCP server to be run using `npx` directly from the `.mcp.json` file. This avoids a global installation and ensures the latest version is used.

```json
{
  "mcpServers": {
    "magento2-lsp-mcp": {
      "command": "npx",
      "args": ["-y", "@mage-os/magento2-lsp", "magento2-lsp-mcp"]
    }
  }
}
```

--------------------------------

### Retrieve Class Metadata Response

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Example response structure for class inspection, providing FQCN, file path, module, parent class, interfaces, and ancestors.

```json
{
  "fqcn": "Magento\\Catalog\\Model\\Product",
  "classFile": "vendor/magento/module-catalog/Model/Product.php",
  "module": "Magento_Catalog",
  "parentClass": "Magento\\Catalog\\Model\\AbstractModel",
  "interfaces": ["Magento\\Catalog\\Api\\Data\\ProductInterface"],
  "ancestors": [
    "Magento\\Catalog\\Model\\AbstractModel",
    "Magento\\Framework\\Model\\AbstractExtensibleModel",
    "Magento\\Catalog\\Api\\Data\\ProductInterface"
  ]
}
```

--------------------------------

### GET magento_resolve_class

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Performs lightweight PSR-4 resolution between a Fully Qualified Class Name (FQCN) and a file path.

```APIDOC
## GET magento_resolve_class

### Description
Lightweight PSR-4 resolution between FQCN and file path.

### Method
GET

### Endpoint
/magento_resolve_class

### Parameters
#### Query Parameters
- **filePath** (string) - Required - Path inside the Magento project
- **fqcn** (string) - Optional - FQCN to resolve to a file path
- **phpFile** (string) - Optional - PHP file path to resolve to a FQCN

### Response
#### Success Response (200)
- **fqcn** (string) - Resolved FQCN
- **resolvedFile** (string) - Resolved file path
- **phpFile** (string) - Input PHP file
- **resolvedFqcn** (string) - Resolved FQCN
- **module** (string) - Associated module

#### Response Example
{
  "fqcn": "Magento\\Catalog\\Model\\Product",
  "resolvedFile": "vendor/magento/module-catalog/Model/Product.php",
  "phpFile": "vendor/magento/module-catalog/Model/Product.php",
  "resolvedFqcn": "Magento\\Catalog\\Model\\Product",
  "module": "Magento_Catalog"
}
```

--------------------------------

### GET magento_get_module_overview

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Retrieves an overview of what a module declares, including preferences, plugins, and routes. Automatically summarizes large modules unless detail is requested.

```APIDOC
## GET magento_get_module_overview

### Description
Get an overview of what a module declares. Automatically summarizes large modules.

### Method
GET

### Endpoint
/magento_get_module_overview

### Parameters
#### Query Parameters
- **filePath** (string) - Required - Path inside the Magento project
- **moduleName** (string) - Optional - Module in Vendor_Module format. Auto-detected from filePath if omitted
- **detail** (boolean) - Optional - When true, always return full arrays even for large modules. Default: false

### Response
#### Success Response (200)
- **moduleName** (string) - Name of the module
- **modulePath** (string) - Path to the module
- **loadOrder** (integer) - Module load order
- **preferences** (object) - Preferences count or array
- **plugins** (object) - Plugins count or array
- **virtualTypes** (object) - Virtual types count or array
- **observers** (object) - Observers count or array
- **routes** (array) - List of routes
- **webapiEndpoints** (object) - WebAPI endpoints count or array
- **dbTables** (array) - List of database tables
- **aclResources** (array) - List of ACL resources

#### Response Example
{
  "moduleName": "Magento_Catalog",
  "modulePath": "vendor/magento/module-catalog",
  "loadOrder": 34,
  "preferences": { "count": 102 },
  "plugins": { "count": 48 },
  "virtualTypes": { "count": 37 },
  "observers": { "count": 27 },
  "routes": [
    { "routeId": "catalog", "frontName": "catalog", "routerType": "standard", "area": "frontend" }
  ],
  "webapiEndpoints": { "count": 81 },
  "dbTables": ["catalog_product_entity", "catalog_category_entity"],
  "aclResources": [
    { "id": "Magento_Catalog::catalog", "title": "Catalog" }
  ]
}
```

--------------------------------

### Get Plugins for a Specific Method

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Retrieve all plugins (before/after/around interceptors) for a given method, including inherited ones. Specify the target class FQCN and the method name.

```json
{
  "targetClass": "Magento\Catalog\Model\Product",
  "targetMethod": "save",
  "plugins": [
    {
      "prefix": "before",
      "pluginClass": "Vendor\Module\Plugin\ProductPlugin",
      "pluginMethod": "beforeSave",
      "pluginFile": "app/code/Vendor/Module/Plugin/ProductPlugin.php",
      "declaredIn": "app/code/Vendor/Module/etc/di.xml",
      "area": "global",
      "module": "Vendor_Module",
      "inherited": false
    }
  ]
}
```

--------------------------------

### XML Auto-Completion for events.xml

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Offers auto-completion for event names and observer class names in `events.xml`. Type partial event names or class names to get relevant suggestions.

```xml
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <event name="█">
        <!-- Type "catalog_product" → shows catalog_product_save_after, catalog_product_load_after, etc. -->
        <observer name="my_observer" instance="█"/>
        <!-- Type "VenModObs" → completes to Vendor\Module\Observer\ProductObserver -->
    </event>
</config>
```

--------------------------------

### Get DI Configuration for a PHP Class

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Use this to retrieve the complete DI configuration for a PHP class or interface after Magento's configuration merging. Requires the file path and the fully-qualified class name (FQCN).

```json
{
  "fqcn": "Magento\Catalog\Api\ProductRepositoryInterface",
  "area": "global",
  "classFile": "vendor/magento/module-catalog/Api/ProductRepositoryInterface.php",
  "preference": {
    "implementation": "Magento\Catalog\Model\ProductRepository",
    "declaredIn": "vendor/magento/module-catalog/etc/di.xml",
    "area": "global",
    "module": "Magento_Catalog"
  },
  "plugins": [
    {
      "pluginClass": "Magento\Catalog\Plugin\...",
      "methods": ["beforeSave", "afterGet"],
      "declaredIn": "vendor/magento/.../etc/di.xml",
      "area": "global",
      "module": "Magento_..."
    }
  ],
  "virtualTypes": [
    {
      "name": "VirtualTypeName",
      "declaredIn": "...",
      "area": "global",
      "module": "...",
      "effectiveParentType": "..."
    }
  ],
  "argumentInjections": [
    { "declaredIn": "...", "area": "global", "module": "..." }
  ],
  "layoutReferences": [
    { "kind": "block-class", "file": "..." }
  ]
}
```

--------------------------------

### Get Full Magento Class Context

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Retrieve the complete Magento context for a given PHP class file. This tool requires the absolute path to the PHP class file.

```json
{
  "filePath": "app/code/Vendor/Module/Model/MyClass.php"
}
```

--------------------------------

### Get Magento Class Context

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

This tool returns all Magento configurations related to a PHP class, including DI preferences, plugin interceptions, event observers, and layout references. It requires the file path to the PHP class.

```json
{
  "tool": "magento_get_class_context",
  "arguments": {
    "filePath": "/path/to/magento/vendor/magento/module-catalog/Model/Product.php"
  }
}
```

```json
{
  "fqcn": "Magento\Catalog\Model\Product",
  "file": "vendor/magento/module-catalog/Model/Product.php",
  "module": "Magento_Catalog",
  "preference": {
    "implementation": "Magento\Catalog\Model\Product",
    "declaredIn": "vendor/magento/module-catalog/etc/di.xml",
    "area": "global",
    "module": "Magento_Catalog"
  },
  "pluginsByMethod": {
    "save": [
      {
        "prefix": "before",
        "pluginClass": "Vendor\Module\Plugin\ProductSavePlugin",
        "pluginMethod": "beforeSave",
        "pluginFile": "app/code/Vendor/Module/Plugin/ProductSavePlugin.php",
        "declaredIn": "app/code/Vendor/Module/etc/di.xml",
        "area": "global",
        "module": "Vendor_Module",
        "inherited": false
      }
    ],
    "getName": []
  },
  "events": [
    { "eventName": "catalog_product_save_after", "observerName": "clean_cache", "declaredIn": "vendor/magento/module-catalog/etc/events.xml", "area": "global", "module": "Magento_Catalog" }
  ],
  "virtualTypes": [],
  "argumentInjections": [],
  "layoutReferences": [
    { "kind": "block-class", "file": "vendor/magento/module-catalog/view/frontend/layout/catalog_product_view.xml" }
  ],
  "isPlugin": false,
  "pluginTargets": []
}
```

--------------------------------

### Go-to-Definition in di.xml

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Allows navigation from class names in `di.xml` to their corresponding PHP files. Supports jumping to the effective implementation after configuration merging.

```xml
<preference for="Magento\Catalog\Api\ProductRepositoryInterface"
            type="Magento\Catalog\Model\ProductRepository"/>
<!-- Go-to-definition on 'for' jumps to effective implementation after config merging -->
<!-- Find-references on class shows all di.xml usages across modules -->
```

--------------------------------

### GET magento_search_symbols

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Searches for Magento symbols by name substring across all indexed data.

```APIDOC
## GET magento_search_symbols

### Description
Search for Magento symbols by name substring across all indexed data.

### Method
GET

### Endpoint
/magento_search_symbols

### Parameters
#### Query Parameters
- **filePath** (string) - Required - Path inside the Magento project
- **query** (string) - Required - Search string (minimum 2 characters, case-insensitive)

### Response
#### Success Response (200)
- **query** (string) - The search query
- **resultCount** (integer) - Total results found
- **results** (array) - List of symbol objects

#### Response Example
{
  "query": "customer",
  "resultCount": 100,
  "results": [
    { "name": "Magento\\Customer\\Api\\CustomerRepositoryInterface", "kind": "class", "file": "...", "classFile": "..." },
    { "name": "CustomerAddressSnapshot", "kind": "virtualType", "file": "..." },
    { "name": "customer_login", "kind": "event", "file": "..." },
    { "name": "customer_entity", "kind": "table", "file": "..." },
    { "name": "customer/account_share/scope", "kind": "configPath", "file": "..." },
    { "name": "Magento_Customer::manage", "kind": "aclResource", "file": "..." },
    { "name": "customer", "kind": "route", "file": "..." }
  ]
}
```

--------------------------------

### Development Commands

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/README.md

Standard commands for managing the development lifecycle of the project.

```bash
npm install
npm test           # run tests once
npm run test:watch # run tests in watch mode
npm run build      # compile TypeScript
```

--------------------------------

### Configure custom binary path

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/editor-cursor.md

Sets a custom path for the language server binary in Cursor settings.

```json
{
  "magento2-lsp.binary.path": "/absolute/path/to/magento2-lsp"
}
```

--------------------------------

### Environment Variables Configuration

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Configure LSP behavior using environment variables for template directories and hint modes.

```bash
# Custom code action templates directory
export MAGENTO_LSP_TEMPLATES_DIR="/path/to/custom/templates"

# Hint mode: 'codeLens' (default) or 'inlayHint'
export MAGENTO_LSP_HINT_MODE=inlayHint
```

--------------------------------

### Configure Magento 2 LSP Initialization Options

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/editor-zed.md

Set custom initialization options for the magento2-lsp server, such as template directory and hint mode. This allows for advanced configuration like custom code action templates.

```json
{
  "lsp": {
    "magento2-lsp": {
      "binary": {
        "path": "/absolute/path/to/magento2-lsp",
        "arguments": ["--stdio"]
      },
      "initialization_options": {
        "templateDir": ".magento2-lsp/templates",
        "hintMode": "inlayHint"
      }
    }
  }
}
```

--------------------------------

### Magento Get DB Schema API

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Retrieves the merged database table schema from all db_schema.xml files across modules for a specified table.

```APIDOC
## POST /api/magento/get_db_schema

### Description
Get the merged database table schema from all db_schema.xml files across modules.

### Method
POST

### Endpoint
/api/magento/get_db_schema

### Parameters
#### Request Body
- **filePath** (string) - yes - Path inside the Magento project
- **tableName** (string) - yes - Database table name (e.g., `catalog_product_entity`)

### Response
#### Success Response (200)
- **tableName** (string) - The name of the database table.
- **comment** (string) - A comment describing the table.
- **resource** (string) - The resource type for the table.
- **engine** (string) - The storage engine used for the table.
- **columns** (array) - An array of column definitions for the table.
  - **name** (string) - The name of the column.
  - **type** (string) - The data type of the column.
  - **nullable** (boolean) - Indicates if the column can be null.
  - **identity** (boolean) - Indicates if the column is an identity column.
  - **unsigned** (boolean) - Indicates if the column is unsigned.
  - **comment** (string) - A comment describing the column.
  - **module** (string) - The Magento module that declared the column.
  - **length** (string) - The length of the column (for string/binary types).
  - **default** (string) - The default value for the column.
  - **precision** (integer) - The precision for numeric types.
  - **scale** (integer) - The scale for numeric types.
- **foreignKeys** (array) - An array of foreign key definitions for the table.
  - **referenceId** (string) - The ID of the foreign key constraint.
  - **column** (string) - The column in the current table that is part of the foreign key.
  - **referenceTable** (string) - The table referenced by the foreign key.
  - **referenceColumn** (string) - The column in the referenced table.
  - **onDelete** (string) - The action to take on delete.
- **declaredIn** (array) - An array of objects indicating where the schema was declared.
  - **module** (string) - The module name.
  - **file** (string) - The path to the declaration file.

#### Response Example
```json
{
  "tableName": "catalog_product_entity",
  "comment": "Catalog Product Table",
  "resource": "default",
  "engine": "innodb",
  "columns": [
    {
      "name": "entity_id",
      "type": "int",
      "nullable": false,
      "identity": true,
      "unsigned": true,
      "comment": "Entity ID",
      "module": "Magento_Catalog"
    },
    {
      "name": "sku",
      "type": "varchar",
      "length": "64",
      "nullable": false,
      "identity": false,
      "comment": "SKU",
      "module": "Magento_Catalog"
    }
  ],
  "foreignKeys": [
    {
      "referenceId": "CAT_PRD_ENTT_ATTR_SET_ID_EAV_ATTR_SET_ATTR_SET_ID",
      "column": "attribute_set_id",
      "referenceTable": "eav_attribute_set",
      "referenceColumn": "attribute_set_id",
      "onDelete": "CASCADE"
    }
  ],
  "declaredIn": [
    { "module": "Magento_Catalog", "file": "vendor/magento/module-catalog/etc/db_schema.xml" }
  ]
}
```
```

--------------------------------

### Go-to-Definition in events.xml

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Enables navigation from observer instances in `events.xml` to the observer's PHP class. Also supports finding all observers for a given event name.

```xml
<event name="catalog_product_save_after">
    <observer name="clean_cache" instance="Magento\Catalog\Observer\FlushCacheByTags"/>
    <!-- Go-to-definition on instance → jumps to PHP observer class -->
    <!-- Find-references on event name → shows all observers for this event -->
</event>
```

--------------------------------

### XML Auto-Completion for di.xml

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Provides context-aware auto-completion for Fully Qualified Class Names (FQCNs) in `di.xml` for preferences, types, and plugins. Type partial class names to see suggestions.

```xml
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <preference for="Magento\Catalog\Api\ProductRepositoryInterface" type="█"/>
    <!-- Type "CatModProd" → completes to Magento\Catalog\Model\ProductRepository -->

    <type name="Magento\Catalog\Model\Product">
        <plugin name="my_plugin" type="█"/>
        <!-- Type "VenModPlug" → completes to Vendor\Module\Plugin\ProductPlugin -->
    </type>
</config>
```

--------------------------------

### Configure Magento 2 LSP in Neovim

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/editor-neovim.md

Add the Magento 2 LSP configuration to your Neovim's LSP client settings. This includes the command to run the server, supported filetypes, and a custom root directory detection function that looks for `app/etc/di.xml`.

```lua
['magento2-lsp'] = {
  cmd = { 'magento2-lsp', '--stdio' },
  filetypes = { 'php', 'xml' },
  root_dir = function(bufnr, on_dir) 
    local path = vim.fn.fnamemodify(vim.api.nvim_buf_get_name(bufnr), ':p:h')
    while path and path ~= '/' do
      if vim.uv.fs_stat(path .. '/app/etc/di.xml') then
        on_dir(path)
        return
      end
      path = vim.fn.fnamemodify(path, ':h')
    end
  end,
}
```

--------------------------------

### Get Magento Template Overrides

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Use this tool to find theme overrides and layout XML usages for a given template identifier. It resolves the full theme fallback hierarchy.

```json
{
  "tool": "magento_get_template_overrides",
  "arguments": {
    "filePath": "/path/to/magento/app/design/frontend/Vendor/theme/Magento_Catalog/templates/product/view.phtml",
    "templateId": "Magento_Catalog::product/view.phtml",
    "area": "frontend"
  }
}
```

```json
{
  "templateId": "Magento_Catalog::product/view.phtml",
  "area": "frontend",
  "moduleTemplate": "vendor/magento/module-catalog/view/frontend/templates/product/view.phtml",
  "themeOverrides": [
    { "theme": "Vendor/theme", "file": "app/design/frontend/Vendor/theme/Magento_Catalog/templates/product/view.phtml" },
    { "theme": "Vendor/parent-theme", "file": "app/design/frontend/Vendor/parent-theme/Magento_Catalog/templates/product/view.phtml" }
  ],
  "layoutUsages": [
    { "kind": "block-template", "file": "vendor/magento/module-catalog/view/frontend/layout/catalog_product_view.xml" },
    { "kind": "block-template", "file": "app/design/frontend/Vendor/theme/Magento_Catalog/layout/catalog_product_view.xml" }
  ]
}
```

--------------------------------

### Get Magento Database Schema

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

This tool returns the merged database table schema from all db_schema.xml files across modules. Specify the file path and table name in the request.

```json
{
  "tool": "magento_get_db_schema",
  "arguments": {
    "filePath": "/path/to/magento/vendor/magento/module-catalog/Model/Product.php",
    "tableName": "catalog_product_entity"
  }
}
```

```json
{
  "tableName": "catalog_product_entity",
  "comment": "Catalog Product Table",
  "resource": "default",
  "engine": "innodb",
  "columns": [
    {
      "name": "entity_id",
      "type": "int",
      "nullable": false,
      "identity": true,
      "unsigned": true,
      "comment": "Entity ID",
      "module": "Magento_Catalog"
    },
    {
      "name": "sku",
      "type": "varchar",
      "length": "64",
      "nullable": false,
      "identity": false,
      "comment": "SKU",
      "module": "Magento_Catalog"
    },
    {
      "name": "attribute_set_id",
      "type": "smallint",
      "nullable": false,
      "identity": false,
      "unsigned": true,
      "default": "0",
      "comment": "Attribute Set ID",
      "module": "Magento_Catalog"
    },
    {
      "name": "qty",
      "type": "decimal",
      "precision": "12",
      "scale": "4",
      "nullable": true,
      "comment": "Qty",
      "module": "Magento_CatalogInventory"
    }
  ],
  "foreignKeys": [
    {
      "referenceId": "CAT_PRD_ENTT_ATTR_SET_ID_EAV_ATTR_SET_ATTR_SET_ID",
      "column": "attribute_set_id",
      "referenceTable": "eav_attribute_set",
      "referenceColumn": "attribute_set_id",
      "onDelete": "CASCADE"
    }
  ],
  "declaredIn": [
    { "module": "Magento_Catalog", "file": "vendor/magento/module-catalog/etc/db_schema.xml" },
    { "module": "Magento_CatalogInventory", "file": "vendor/magento/module-catalog-inventory/etc/db_schema.xml" }
  ]
}
```

--------------------------------

### Configure MCP Server Manually in .mcp.json

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp.md

Manually configure the MCP server by adding an entry to your project's `.mcp.json` file. This specifies the command to run the server.

```json
{
  "mcpServers": {
    "magento2-lsp-mcp": {
      "command": "magento2-lsp-mcp"
    }
  }
}
```

--------------------------------

### Go-to-Definition in Layout XML

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Facilitates navigation from block classes and template paths in layout XML to their respective PHP and `.phtml` files. Supports theme fallback for templates and finding references for templates.

```xml
<block class="Magento\Catalog\Block\Product\View" template="Magento_Catalog::product/view.phtml"/>
<!-- Go-to-definition on class → PHP file -->
<!-- Go-to-definition on template → .phtml file (respects theme fallback) -->
<!-- Find-references on template → all layout files using it -->
```

```xml
<referenceBlock name="product.info">
    <!-- Go-to-definition → original <block name="product.info"> declaration -->
</referenceBlock>
```

--------------------------------

### Magento Get Class Info API

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Retrieves detailed information about a specific PHP class within a Magento project, including its file path, module, parent class, interfaces, and ancestors.

```APIDOC
## POST /api/magento/get_class_info

### Description
Retrieves detailed information about a specific PHP class within a Magento project.

### Method
POST

### Endpoint
/api/magento/get_class_info

### Parameters
#### Request Body
- **filePath** (string) - yes - Path inside the Magento project
- **fqcn** (string) - yes - Fully-qualified PHP class name

### Request Example
```json
{
  "filePath": "vendor/magento/module-catalog/Model/Product.php",
  "fqcn": "Magento\Catalog\Model\Product"
}
```

### Response
#### Success Response (200)
- **fqcn** (string) - The fully-qualified class name.
- **classFile** (string) - The path to the class file within the project.
- **module** (string) - The Magento module the class belongs to.
- **parentClass** (string) - The parent class of the current class.
- **interfaces** (array) - An array of interfaces implemented by the class.
- **ancestors** (array) - An array of all ancestor classes and interfaces.

#### Response Example
```json
{
  "fqcn": "Magento\Catalog\Model\Product",
  "classFile": "vendor/magento/module-catalog/Model/Product.php",
  "module": "Magento_Catalog",
  "parentClass": "Magento\Catalog\Model\AbstractModel",
  "interfaces": ["Magento\Catalog\Api\Data\ProductInterface"],
  "ancestors": [
    "Magento\Catalog\Model\AbstractModel",
    "Magento\Framework\Model\AbstractExtensibleModel",
    "Magento\Catalog\Api\Data\ProductInterface"
  ]
}
```
```

--------------------------------

### Retrieve DI Configuration

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Fetches the effective dependency injection configuration for a class or interface, including preferences, plugins, and virtual types.

```json
// Request
{
  "tool": "magento_get_di_config",
  "arguments": {
    "filePath": "/path/to/magento/app/code/Vendor/Module/Model/Example.php",
    "fqcn": "Magento\\Catalog\\Api\\ProductRepositoryInterface",
    "area": "global"
  }
}

// Response
{
  "fqcn": "Magento\\Catalog\\Api\\ProductRepositoryInterface",
  "area": "global",
  "classFile": "vendor/magento/module-catalog/Api/ProductRepositoryInterface.php",
  "preference": {
    "implementation": "Magento\\Catalog\\Model\\ProductRepository",
    "declaredIn": "vendor/magento/module-catalog/etc/di.xml",
    "area": "global",
    "module": "Magento_Catalog"
  },
  "plugins": [
    {
      "pluginClass": "Magento\\Catalog\\Plugin\\ProductPlugin",
      "methods": ["beforeSave", "afterGet"],
      "declaredIn": "vendor/magento/module-catalog/etc/di.xml",
      "area": "global",
      "module": "Magento_Catalog"
    }
  ],
  "virtualTypes": [
    {
      "name": "VirtualProductRepository",
      "declaredIn": "vendor/magento/module-catalog/etc/di.xml",
      "area": "global",
      "module": "Magento_Catalog",
      "effectiveParentType": "Magento\\Catalog\\Model\\ProductRepository"
    }
  ],
  "argumentInjections": [
    { "declaredIn": "vendor/magento/module-catalog/etc/di.xml", "area": "global", "module": "Magento_Catalog" }
  ],
  "layoutReferences": [
    { "kind": "block-class", "file": "vendor/magento/module-catalog/view/frontend/layout/catalog_product_view.xml" }
  ]
}
```

--------------------------------

### Magento Symbol Search Response

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/mcp-tools-reference.md

Example JSON response for searching Magento symbols, showing various symbol kinds like class, virtualType, event, table, configPath, aclResource, and route.

```json
{
  "query": "customer",
  "resultCount": 100,
  "results": [
    { "name": "Magento\Customer\Api\CustomerRepositoryInterface", "kind": "class", "file": "...", "classFile": "..." },
    { "name": "CustomerAddressSnapshot", "kind": "virtualType", "file": "..." },
    { "name": "customer_login", "kind": "event", "file": "..." },
    { "name": "customer_entity", "kind": "table", "file": "..." },
    { "name": "customer/account_share/scope", "kind": "configPath", "file": "..." },
    { "name": "Magento_Customer::manage", "kind": "aclResource", "file": "..." },
    { "name": "customer", "kind": "route", "file": "..." }
  ]
}
```

--------------------------------

### PHP Auto-Completion for Events, Config, and ACL

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Provides context-aware auto-completion for event names, configuration paths, and ACL resource IDs in PHP code. Type partial strings to see relevant suggestions.

```php
<?php
// PHP - Complete event names, config paths, ACL resource IDs

// Event dispatch completion
$this->eventManager->dispatch('█');
// Type "catalog" → shows catalog_product_save_after, catalog_category_save_after, etc.

// Config path completion
$this->scopeConfig->getValue('█');
$this->scopeConfig->isSetFlag('█');
// Type "payment/" → shows payment/account/active, payment/paypal/settings, etc.

// ACL check completion
$this->authorization->isAllowed('█');
const ADMIN_RESOURCE = '█';
// Type "Magento_Catalog" → shows Magento_Catalog::catalog, Magento_Catalog::products, etc.
```

--------------------------------

### Enable Inlay Hints for PHP in Zed

Source: https://github.com/mage-os-lab/magento2-lsp/blob/main/docs/editor-zed.md

Configure Zed to enable inlay hints for PHP files. This setting should be added to the language-specific configuration in your Zed settings.

```json
"languages": {
  "PHP": {
    "inlay_hints": {
      "enabled": true
    }
  }
}
```

--------------------------------

### PHP Navigation to XML Config

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Enables navigation from PHP code to corresponding XML configuration files. Supports jumping from config paths to `system.xml` and from ACL checks to `acl.xml`.

```php
<?php
// PHP: Navigate from code to XML config

// Config path navigation
$value = $this->scopeConfig->getValue('payment/account/active');
// Go-to-definition → jumps to <field> declaration in system.xml

// ACL navigation
if ($this->authorization->isAllowed('Magento_Catalog::products')) {
// Go-to-definition → jumps to <resource> in acl.xml
// Find-references → shows all usages in webapi.xml, menu.xml, system.xml, PHP

// Find-references from PHP class declaration shows:
// - All di.xml references (preferences, plugins, type declarations)
// - Layout XML block classes
// - system.xml model references
// - webapi.xml service classes

```

--------------------------------

### Get Magento Class Hierarchy

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Use this tool to retrieve the parent class, implemented interfaces, and the full ancestor chain for a given Magento class. Provide the file path and fully qualified class name (FQCN) in the request.

```json
{
  "tool": "magento_get_class_hierarchy",
  "arguments": {
    "filePath": "/path/to/magento/vendor/magento/module-catalog/Model/Product.php",
    "fqcn": "Magento\Catalog\Model\Product"
  }
}
```

```json
{
  "fqcn": "Magento\Catalog\Model\Product",
  "classFile": "vendor/magento/module-catalog/Model/Product.php",
  "module": "Magento_Catalog",
  "parentClass": "Magento\Catalog\Model\AbstractModel",
  "interfaces": [
    "Magento\Catalog\Api\Data\ProductInterface",
    "Magento\Framework\DataObject\IdentityInterface"
  ],
  "ancestors": [
    "Magento\Catalog\Model\AbstractModel",
    "Magento\Framework\Model\AbstractExtensibleModel",
    "Magento\Framework\Model\AbstractModel",
    "Magento\Framework\DataObject",
    "Magento\Catalog\Api\Data\ProductInterface",
    "Magento\Framework\Api\ExtensibleDataInterface",
    "Magento\Framework\DataObject\IdentityInterface"
  ]
}
```

--------------------------------

### magento_get_module_overview

Source: https://context7.com/mage-os-lab/magento2-lsp/llms.txt

Retrieves a comprehensive overview of a Magento module, including preferences, plugins, virtual types, observers, routes, REST API endpoints, database tables, and ACL resources.

```APIDOC
## POST magento_get_module_overview

### Description
Returns an overview of what a module declares: preferences, plugins, virtual types, observers, routes, REST API endpoints, database tables, and ACL resources.

### Request Body
- **filePath** (string) - Optional - Path to a file within the module context.
- **moduleName** (string) - Optional - The name of the Magento module.
- **detail** (boolean) - Optional - If true, returns full arrays of declarations instead of summaries.

### Request Example
{
  "tool": "magento_get_module_overview",
  "arguments": {
    "filePath": "/path/to/magento/vendor/magento/module-catalog/Model/Product.php",
    "moduleName": "Magento_Catalog",
    "detail": false
  }
}
```