LSP 検査

追加バージョン: @mastra/core@1.1.0

LSP 検査は、Workspace を使用する Agent にセマンティックなコードインテリジェンスを提供します。Workspace で LSP を有効にすると、Agent はサポート対象ファイル内のシンボルを検査して、ホバー情報を取得したり、定義へ移動したりできます。実装を検索することもできます。

LSP 検査を使用する場面

プレーンテキスト検索だけではなく、コードをセマンティックに理解する必要がある Agent には LSP 検査を使用します。

• サポート対象の任意の言語でシンボルとその推論された型を検査する
• 関連コードを編集する前に、シンボルが宣言されている場所を特定する
• すべてのファイルを手動で追跡せずに、コードベース全体の実装を調べる
• セマンティック検査を view および search_content と組み合わせて、すばやく移動する
• カスタム Language Server を登録して、追加の言語を LSP でサポートする

基本的な使用方法

lsp: true を設定して、Workspace で LSP を有効にします。

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,
})

この設定では、設定済みの Filesystem Tool および Sandbox Tool とともに、デフォルトの LSP 検査 Tool が Workspace に登録されます。

Agent Tool

LSP を有効にすると、Workspace はデフォルトで mastra_workspace_lsp_inspect を公開します。

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

match フィールドには、<<< カーソルマーカーを正確に 1 つ含める必要があります。このマーカーは、指定した行にあるシンボルの位置を示します。

Tool は最大 3 つの結果グループを返します。

結果	説明
hover	カーソル位置にあるシンボルの型情報またはドキュメント
diagnostics	存在する場合、検査対象行に限定された LSP 診断
definition	1 行のプレビューを含む宣言位置
implementation	実装または使用箇所

Tool 名の再マッピング

Agent がより短い名前を想定している場合は、Tool の名前を変更します。

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',
    },
  },
})

変更されるのは公開される Tool 名だけです。設定キーは引き続き WORKSPACE_TOOLS.LSP.LSP_INSPECT です。

LSP の設定

デフォルトの動作を使用するには lsp を true に設定します。サーバーの起動と診断をカスタマイズするには、オブジェクトを指定します。

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: ['eslint'],
    binaryOverrides: {
      typescript: '/custom/path/to/typescript-language-server --stdio',
    },
    searchPaths: ['/opt/homebrew/bin'],
  },
})

次のことが必要な場合は、カスタム設定を使用します。

• 大規模なリポジトリ向けにタイムアウトを延長する
• 特定の Language Server を無効にする
• Mastra でカスタム Language Server バイナリを使用する
• 制約のある環境でバイナリの検索パスを追加する

カスタム Language Server

Mastra はデフォルトで TypeScript、JavaScript、Python、Go、Rust を組み込みでサポートしています。その他の言語（PHP、Ruby、Java、Kotlin、Swift、Elixir など）で LSP 検査を使用するには、servers フィールドを介してカスタム Language Server を登録します。

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: {
    servers: {
      phpactor: {
        id: 'phpactor',
        name: 'Phpactor Language Server',
        languageIds: ['php'],
        extensions: ['.php'],
        markers: ['composer.json'],
        command: 'phpactor language-server',
      },
    },
  },
})

各カスタムサーバー定義には、次のフィールドが必要です。

フィールド	説明
id	サーバーの一意な識別子
name	ログに表示される、人が読み取れる名前
languageIds	このサーバーが処理する Language Server Protocol（LSP）の言語識別子
extensions	ドットを含むファイル拡張子
markers	プロジェクトルートを特定するファイルまたはディレクトリ（composer.json、Gemfile など）
command	サーバーを起動する完全なコマンド文字列

サーバーに複数の言語 ID がある場合、Mastra は各拡張子を languageIds の最初のエントリにマッピングします。

オプションの initializationOptions を渡して、LSP ハンドシェイク中にカスタム設定を送信することもできます。

カスタムサーバーは組み込みサーバーとマージされます。組み込みサーバーを置き換えるには、同じ id を使用します（たとえば、id: 'go' は組み込みの Go サーバーを置き換えます）。複数の言語を同時にサポートするには、複数のサーバーを登録します。

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: {
    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',
      },
    },
  },
})

要件と制限

• LSP 検査は、一致する組み込みまたはカスタム Language Server があるファイル形式でのみ機能する
• 検査する path は、Workspace の Filesystem 内または許可されたパス内で解決される必要がある
• 外部パッケージの検査では、実行時のソースファイルではなく .d.ts などの宣言ファイルが解決される場合がある
• lsp_inspect は view と search_content を補完するが、完全なコンテキストが必要な場合に実装コードを読む代わりにはならない

関連項目

• Workspace の概要
• Filesystem
• Sandbox
• 検索とインデックス化
• Workspace クラスのリファレンス