LSPMesh Plugin
Relevant source files
The following files were used as context for generating this wiki page:
LSPMesh is a specialized Language Server Protocol (LSP) aggregator and Model Context Protocol (MCP) server designed to provide a unified intelligence endpoint for the Nordcom Commerce project. It acts as a front-end for multiple language servers—specifically TypeScript, Tailwind CSS, and Biome—routing requests to the appropriate backends based on the file type and merging their results.
The plugin serves two primary roles: it functions as a standard LSP server for code editors and as an MCP server for AI agents like Claude Code. By aggregating these services, it provides precise symbol navigation, reference tracking, and implementation discovery across the monorepo's diverse tech stack.
Sources: packages/ai/lspmesh/package.json:6-6, plugins/lspmesh/README.md:1-12, CLAUDE.md:38-42
Architecture and Core Components
LSPMesh operates using an aggregation engine that manages multiple language server backends. It translates incoming requests into backend-specific calls and synthesizes the responses into a single output.
Aggregator Engine
The AggregatorEngine is the central coordinator of the system. It initializes backends according to a configuration object (LspMeshConfig) and handles the routing of operations. The engine supports "position-based" operations (like finding references at a specific line and character) and "workspace-wide" operations (like searching for symbols by name).
The following diagram illustrates how the AggregatorEngine routes a request from a client (like an IDE or AI agent) to multiple specialized backends:
The engine routes requests to every backend that handles the specific file extension and merges the results.
Sources: packages/ai/lspmesh/README.md:1-6, packages/ai/lspmesh/src/core/engine.test.ts:25-50, plugins/lspmesh/README.md:6-10
Multi-Protocol Support
LSPMesh exposes its functionality through two distinct protocols:
- LSP Server: Launched via
lspmesh lsp, it provides standard editor features liketextDocument/references,textDocument/definition, andworkspace/symbol. - MCP Server: Launched via
lspmesh mcp, it exposes specific tools for AI agents, includingfind_symbol,find_references, andfind_implementations.
Sources: packages/ai/lspmesh/package.json:14-16, packages/ai/lspmesh/README.md:10-13, plugins/lspmesh/README.md:6-12
Technical Implementation
Backend Configuration
Backends are configured with specific commands and language mappings. For example, a backend might be defined to handle .ts files using the TypeScript language server.
| Option | Type | Description |
|---|---|---|
name | string | Unique identifier for the backend (e.g., "echo", "typescript"). |
command | string | The executable command to start the language server. |
args | string[] | Command-line arguments for the server. |
cwd | string | Working directory for the backend process. |
extensionToLanguage | Record | Mapping of file extensions to language IDs (e.g., ".ts": "typescript"). |
Sources: packages/ai/lspmesh/src/core/engine.test.ts:11-18, packages/ai/lspmesh/src/lsp/server.test.ts:12-19
Request Routing Logic
The engine employs different strategies for different types of requests:
- Raw Forwarding: Returns individual replies from every matching backend.
- Position Operations: Merges results from backends that support the specific URI and position.
- Union Finding: For operations like
findReferences, the engine can union references over resolved definitions and tag them with location data.
The diagram shows the parallel execution of requests to multiple backends for a single client query.
Sources: packages/ai/lspmesh/src/core/engine.test.ts:34-70, packages/ai/lspmesh/src/lsp/server.test.ts:31-40
Integration with AI Agents (Claude Code)
LSPMesh is a critical component for code intelligence within the repository's AI workflow. It replaces older, fragmented plugins (like lsp-symbols) with a single, high-performance endpoint. AI agents use the lspmesh MCP tools to navigate the codebase precisely without performing expensive "whole-file" reads.
MCP Tools for Agents
The plugin provides specific tools that allow AI agents to interact with the code intelligence layer:
| Tool Name | Operation | Purpose |
|---|---|---|
find_symbol | workspace/symbol | Search for a symbol across the entire project by name. |
find_references | textDocument/references | Locate all usages of a specific symbol. |
find_implementations | textDocument/implementation | Jump to the actual code implementation of a symbol or interface. |
Sources: CLAUDE.md:38-50, plugins/lspmesh/README.md:10-12, packages/ai/lspmesh/src/core/engine.test.ts:65-80
Version Syncing
Because the plugin is published as a package (lspmesh), the repository includes a synchronization script (scripts/sync-plugin-version.ts) to ensure that the Claude Code plugin manifest and marketplace listings stay in sync with the workspace package version. This script rewrites version pins in .json and README.md files whenever changeset version bumps the package.
Sources: scripts/sync-plugin-version.ts:4-30, package.json:71-72
Conclusion
The LSPMesh plugin serves as the "brain" for code navigation and analysis in the Nordcom Commerce repository. By aggregating TypeScript, Tailwind, and Biome servers into a unified LSP and MCP endpoint, it provides a consistent interface for both human developers and AI agents. This architecture ensures high-precision symbol discovery and reference tracking, which is essential for maintaining a complex multi-tenant TypeScript monorepo.