LSP inspection

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Mastra documentation on enabling Language Server Protocol (LSP) inspection for workspace-backed agents to achieve semantic code intelligence through hover information, definition jumping, and implementation lookup.

Insight

LSP inspection is added in @mastra/[email protected] and provides workspace-backed agents with semantic code intelligence capabilities. When enabled, agents can inspect symbols in supported files to retrieve hover information (type information or documentation), jump to definitions, and find implementations. The default exposed tool name is mastra_workspace_lsp_inspect, which takes a JSON object with path (absolute path to file), line (1-based line number), and match (must include exactly one <<< cursor marker identifying the symbol position). The tool returns up to four result groups: hover (type information or documentation), diagnostics (line-scoped LSP diagnostics when present), definition (declaration locations with one-line preview), and implementation (implementation or usage locations). Built-in language servers support TypeScript, JavaScript, Python, Go, and Rust. Custom servers can be registered for PHP, Ruby, Java, Kotlin, Swift, and Elixir. Each custom server definition requires fields: id (unique identifier), name (human-readable name), languageIds (LSP language identifiers), extensions (file extensions including dot), markers (files/directories identifying project root like composer.json or Gemfile), and command (full command string to start server). Optional initializationOptions can be passed for custom LSP handshake settings. Custom servers merge with built-in servers; replace a built-in server using the same id.

Hành động

Enable LSP inspection by setting lsp: true in the Workspace constructor alongside filesystem and sandbox configurations. Use tools config with WORKSPACE_TOOLS.LSP.LSP_INSPECT to rename the exposed tool name. For customization, pass an lsp configuration object with: diagnosticTimeout (default for diagnostics), initTimeout (server startup), disableServers array (e.g. [‘eslint’]), binaryOverrides object (e.g. {typescript: ‘/custom/path/to/typescript-language-server —stdio’}), and searchPaths array for binary lookup. Register custom language servers via the servers field within the lsp configuration object, with each server requiring id, name, languageIds, extensions, markers, and command fields. Call the tool with path, line, and match (including <<< cursor marker) to get hover, diagnostics, definition, and implementation results.

Kết quả

Agents can perform semantic code inspection including retrieving hover information with type documentation, viewing line-scoped diagnostics, jumping to symbol definitions with one-line previews, and finding all implementation or usage locations across the codebase.

Điều kiện áp dụng

Requires @mastra/[email protected] or later. LSP inspection only works for file types with a matching built-in or custom language server. Inspected paths must resolve inside workspace filesystem or allowed paths. External package inspection may resolve to declaration files (.d.ts) instead of runtime source.

Nội dung gốc (Original)

LSP inspection

Added in: @mastra/[email protected]

LSP inspection gives workspace-backed agents semantic code intelligence. When you enable LSP on a workspace, agents can inspect symbols in supported files to retrieve hover information, jump to definitions, and find implementations.

When to use LSP inspection

Use LSP inspection when your agent needs semantic code understanding instead of plain-text search alone:

Inspect symbols and their inferred types in any supported language
Find where a symbol is declared before editing related code
Explore implementations across a codebase without manually tracing every file
Combine semantic inspection with view and search_content for faster navigation
Add LSP support for additional languages by registering custom language servers

Basic usage

Enable LSP on a workspace by setting lsp: true:

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
 
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  lsp: true,
})

With this configuration, the workspace registers the default LSP inspection tool alongside the configured filesystem and sandbox tools.

Agent tool

When LSP is enabled, the workspace exposes mastra_workspace_lsp_inspect by default.

{
  "path": "/absolute/path/to/file.ts",
  "line": 10,
  "match": "const foo = <<<bar()"
}

The match field must include exactly one <<< cursor marker. The marker identifies the symbol position on the specified line.

The tool returns up to three result groups:

Result	Description
`hover`	Type information or documentation for the symbol at the cursor
`diagnostics`	Line-scoped LSP diagnostics for the inspected line, when present
`definition`	Declaration locations with a one-line preview
`implementation`	Implementation or usage locations

Tool name remapping

Rename the tool if your agent expects a shorter name:

import { Workspace, LocalFilesystem, WORKSPACE_TOOLS } from '@mastra/core/workspace'
 
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  lsp: true,
  tools: {
    [WORKSPACE_TOOLS.LSP.LSP_INSPECT]: {
      name: 'lsp_inspect',
    },
  },
})

This changes the exposed tool name only. The configuration key stays WORKSPACE_TOOLS.LSP.LSP_INSPECT.

LSP configuration

Set lsp to true for default behavior, or provide an object to customize server startup and diagnostics:

import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
 
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  lsp: {
    diagnosticTimeout: 4000,
    initTimeout: 8000,
    disableServers: ['eslint'],
    binaryOverrides: {
      typescript: '/custom/path/to/typescript-language-server --stdio',
    },
    searchPaths: ['/opt/homebrew/bin'],
  },
})

Use custom configuration when you need to:

Increase timeouts for large repositories
Disable specific language servers
Point Mastra at custom language server binaries
Add extra binary search paths in constrained environments

Custom language servers

By default, Mastra includes built-in support for TypeScript, JavaScript, Python, Go, and Rust. To use LSP inspection with other languages (e.g. PHP, Ruby, Java, Kotlin, Swift, Elixir), register a custom language server via the servers field:

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
 
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  lsp: {
    servers: {
      phpactor: {
        id: 'phpactor',
        name: 'Phpactor Language Server',
        languageIds: ['php'],
        extensions: ['.php'],
        markers: ['composer.json'],
        command: 'phpactor language-server',
      },
    },
  },
})

Each custom server definition requires these fields:

Field	Description
`id`	Unique identifier for the server
`name`	Human-readable name shown in logs
`languageIds`	Language Server Protocol (LSP) language identifiers this server handles
`extensions`	File extensions, including the dot
`markers`	Files or directories that identify the project root (e.g. `composer.json`, `Gemfile`)
`command`	Full command string to start the server

When a server has multiple language IDs, Mastra maps each extension to the first entry in languageIds.

You can also pass optional initializationOptions to send custom settings during the LSP handshake.

Custom servers are merged with built-in servers. To replace a built-in server, use the same id (e.g. id: 'go' replaces the built-in Go server). Register multiple servers to support several languages at once:

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
 
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  lsp: {
    servers: {
      phpactor: {
        id: 'phpactor',
        name: 'Phpactor Language Server',
        languageIds: ['php'],
        extensions: ['.php'],
        markers: ['composer.json'],
        command: 'phpactor language-server',
      },
      solargraph: {
        id: 'solargraph',
        name: 'Solargraph',
        languageIds: ['ruby'],
        extensions: ['.rb', '.erb'],
        markers: ['Gemfile'],
        command: 'solargraph stdio',
      },
    },
  },
})

Requirements and limitations

LSP inspection only works for file types with a matching built-in or custom language server
The path you inspect must resolve inside the workspace filesystem or allowed paths
External package inspection may resolve to declaration files such as .d.ts instead of runtime source files
lsp_inspect complements view and search_content, but does not replace reading implementation code when you need full context

Liên kết

Nền tảng: Dev Framework · Mastra
Nguồn: https://mastra.ai/docs/workspace/lsp

KakaFlow KB

Nội dung

LSP inspection

LSP inspection

Tình huống

Insight

Hành động

Kết quả

Điều kiện áp dụng

Nội dung gốc (Original)

LSP inspection

When to use LSP inspection

Basic usage

Agent tool

Tool name remapping

LSP configuration

Custom language servers

Requirements and limitations

Liên kết

Sơ đồ

Mục lục

Liên kết ngược

KakaFlow KB

Nội dung

LSP inspection

LSP inspection

Tình huống

Insight

Hành động

Kết quả

Điều kiện áp dụng

Nội dung gốc (Original)

LSP inspection

When to use LSP inspection

Basic usage

Agent tool

Tool name remapping

LSP configuration

Custom language servers

Requirements and limitations

Related

Liên kết

Sơ đồ

Mục lục

Liên kết ngược