Skip to main content

LSP inspection

Added in: @mastra/core@1.1.0

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
Direct link to When to use LSP inspection

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

  • Inspect TypeScript or JavaScript symbols and their inferred types
  • 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

Basic usage
Direct link to Basic usage

Enable LSP on a workspace by setting lsp: true:

src/mastra/workspaces.ts
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
Direct link to 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:

ResultDescription
hoverType information or documentation for the symbol at the cursor
diagnosticsLine-scoped LSP diagnostics for the inspected line, when present
definitionDeclaration locations with a one-line preview
implementationImplementation or usage locations

Tool name remapping
Direct link to Tool name remapping

Rename the tool if your agent expects a shorter name:

src/mastra/workspaces.ts
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
Direct link to LSP configuration

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

src/mastra/workspaces.ts
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  lsp: {
    diagnosticTimeout: 4000,
    initTimeout: 8000,
    disableServers: ['pyright'],
    binaryOverrides: {
      typescript: '/custom/path/to/typescript-language-server',
    },
    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

Requirements and limitations
Direct link to Requirements and limitations

  • LSP inspection only works for file types with a matching 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
On this page