Deixis

Deixis

Deixis は、コーディングエージェントに Language Server Protocol（LSP）操作への型付きアクセスを提供する Model Context Protocol（MCP）サーバーです。1 つのプロジェクトに対して明示的に設定された言語サーバーを管理し、ファイルシステム、シェル、エディター、インデックス、メモリのレイヤーを追加することなく、そのセマンティック機能を公開します。

警告

Deixis はプレアルファ版です。セマンティックツールとガード付きの名前変更ワークフローは動作しますが、現時点では安定性を保証できません。

機能

設定済みの Deixis セッションでは、デフォルトで 15 個の読み取り専用 MCP ツールを利用できます。--allow-mutation を指定して起動すると、16 個目のツールとして apply_rename が追加されます。

Tool	目的
deixis_server_status	接続中のサーバーを一覧表示するか、1 つのサーバーの詳細を確認します。
hover	ゼロベースの UTF-8 位置にあるホバーマークアップを返します。
signature_help	呼び出しシグネチャと構造化されたパラメーターの詳細を返します。
definition	定義を検索します。
declaration	宣言を検索します。
type_definition	型定義を検索します。
implementation	実装を検索します。
references	宣言を含めるかどうかを明示して、参照を検索します。
incoming_calls	呼び出し元とその呼び出し箇所を検索します。
outgoing_calls	呼び出し先とその呼び出し箇所を検索します。
diagnostics	プル診断を要求するか、キャッシュされたプッシュ診断を返します。
document_symbols	シンボル構造が必要な場合に、ファイルのアウトラインを確認します。
workspace_symbols	接続中のサーバー全体、または明示的に指定した 1 つのサーバーを検索します。
prepare_rename	ある位置のシンボルを名前変更できるか確認します。
preview_rename	編集内容を検証し、差分と一度だけ使用できるプレビュー ID を返します。
apply_rename	1 つのプレビューをそのまま適用します（--allow-mutation が必要です）。

Deixis は UTF-8、UTF-16、UTF-32 の位置形式をネゴシエートし、ファイル単位のリクエストの前にディスク上のドキュメントを同期し、すべての操作を言語サーバーが通知する機能に基づいて制御し、結果に元のサーバーの情報を保持します。複数の言語サーバーで、変更されない 1 つのプロジェクトルートを扱えます。

復旧可能な LSP キャンセルは、制限時間付きの準備完了待機の後に最大 3 回再試行されます。再試行では元のリクエストのタイムアウトを共有し、MCP 呼び出し元がキャンセルすると停止します。再試行を使い切った場合、エラーには試行回数が記載され、言語サーバーのエラー詳細が保持されます。

ナビゲーション、ホバー、シグネチャヘルプ、参照、シンボル、呼び出し階層の準備でも、インデックス作成中に空の結果が返された場合や ContentModified エラーが発生した場合に、同じタイムアウトと最大 3 回の再試行の範囲内で再試行します。空の結果が返された場合、インデックス作成が続く間に再試行を消費するのではなく、Deixis はリクエストの期限まで準備完了を待ちます。サーバーがビジー状態のままの場合は、request_timeout エラーが発生します（デフォルトは 30 秒です）。 ContentModified エラーでは、再試行ごとに最大 5 秒間、準備完了を待ちます。ファイル単位の再試行では、位置を再利用する前に、同期済みのドキュメントとディスク上の内容の両方が変更されていないことを確認します。リクエスト中を通して準備完了または状態不明であるサーバーから、結果が返された場合や空の結果が返された場合は、ただちに返します。 対象のシンボルへ移動するには、definition、type_definition、implementation、referencesを直接使用してください。ファイル内の型、関数、ネストされたメンバーなどの概要が必要な場合にのみ、document_symbolsを使用してください。これはデフォルトのナビゲーション手順でも、ほかのクエリの前提条件でもありません。このガイダンスは、MCP の初期化手順とツールの説明にも記載されています。

引数を指定せずにdeixis_server_statusを呼び出すと、接続済みサーバーが辞書順に一覧表示され、残りの設定済みサーバー数が表示されます。

attached: python, rust
not attached: 3

空のリストはattached: noneと表示され、カウントはゼロの場合も含めて表示されます。構造化出力には、設定済みの名前の配列であるattachedと、カウントであるnotAttachedが含まれます。Deixis が現在のプロセスと少なくとも1つのドキュメントを同期すると、サーバーは接続済みになります。起動していないサーバーや、ドキュメントを同期せずに起動したサーバーは、未接続としてカウントされます。詳細なライフサイクルと機能のスナップショットを取得するにはserverを指定してください。start: trueを指定する場合も、サーバー名を明示する必要があります。

references、incoming_calls、outgoing_calls、document_symbols、workspace_symbolsでは、オプションのlimit（デフォルトは100、最大は500）とoffset（デフォルトは0）を指定できます。各ページでは、コンパクトな JSON の結果配列も64 KiBまでに制限されます。構造化されたpaginationオブジェクトには、returned、total、truncatedと、結果が残っている場合はnextOffsetが含まれます。そのオフセットと同じクエリ引数を使って続行してください。各呼び出しでクエリが再実行されるため、ファイルの編集、インデックス作成の進行状況、接続済みサーバーの変更によって、ページ間で結果が変わることがあります。テキスト応答にはページの概要が表示されます。

ネストされたドキュメントシンボルもすべて上限数に含まれます。シンボルはページ内で階層構造を保ちます。indexとparentIndexはページをまたぐ関係を示し、childCountは直接の子の総数を示します。ページに収まらない個々の項目は省略され、そのインデックスはpagination.omittedに一覧表示され、truncated: trueが設定されます。ページネーションはこれらの項目を飛ばして進みます。件数とバイト数の上限は、Deixis が返す正規化済みの結果に適用されます。言語サーバーは引き続き完全な応答を計算します。

プロトコルとアーキテクチャについてはDESIGN.mdを、計画中の作業についてはTODO.mdを参照してください。

インストール

言語サーバーは別のプログラムです。設定する言語サーバーをインストールし、MCP ホストの環境から参照できるようにしてください。

ビルド済みバイナリ

最新の GitHub リリースでは、x86-64 および ARM64 の Linux、Intel および Apple silicon の macOS、x86-64 の Windows 向けアーカイブを提供しています。Linux リリースには、glibc ビルドと静的 musl ビルドの両方が含まれています。

Linux または macOS では、次のコマンドで適切なリリースを自動的にインストールできます。

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/jolars/deixis/releases/latest/download/deixis-installer.sh | sh

または、Windows の PowerShell から実行します。

powershell -ExecutionPolicy Bypass -c "irm https://github.com/jolars/deixis/releases/latest/download/deixis-installer.ps1 | iex"

インストーラーはdeixisを Cargo のバイナリディレクトリに配置します。各リリースには、SHA-256 チェックサムと GitHub のビルド証明も含まれています。ダウンロードしたアーカイブは、次のコマンドで検証できます。

gh attestation verify deixis-aarch64-apple-darwin.tar.xz --repo jolars/deixis

Nix

デフォルトの flake パッケージをインストールします。

nix profile install github:jolars/deixis

または、インストールせずに実行します。

nix run github:jolars/deixis -- --root /path/to/project --config /path/to/config.toml

Cargo

Rust 1.98.0 以降が必要です。

cargo install deixis --locked

crates.io パッケージは、MCP Registry の ID mcp-name: io.github.jolars/deixisに属します。

チェックアウトしたソースからビルドするには、次のコマンドを実行します。

git clone https://github.com/jolars/deixis.git
cd deixis
cargo build --release --locked

生成されるバイナリはtarget/release/deixisです（Windows ではdeixis.exe）。

言語サーバーを設定する

動作確認済みの設定例から始めるか、単一のサーバーを定義します。

[servers.rust]
command = "rust-analyzer"
file_extensions = { ".rs" = "rust" }

--config を指定してファイルを渡すか、ユーザー設定としてインストールします。

プラットフォーム	XDG_CONFIG_HOME が未設定の場合のデフォルトパス
Linux およびその他の Unix	~/.config/deixis/config.toml
macOS	~/Library/Application Support/deixis/config.toml
Windows	%APPDATA%\deixis\config.toml

$XDG_CONFIG_HOME/deixis/config.toml は、この変数が設定されている場合、すべてのプラットフォームで優先されます。明示的に指定した --config は、ユーザー設定より優先されます。Deixis はプロジェクトツリー内の設定を検出しません。

設定は厳格に検証されます。不明なフィールド、空のコマンド、無効なルート、値がゼロの上限がある場合、エラーで起動が中止されます。設定リファレンスでは、すべてのフィールド、デフォルト値、ルーティングルール、プロセスの制限について説明しています。

MCP クライアントに接続する

Deixis はローカルの stdio サーバーです。MCP ホストはバイナリを直接起動する必要があり、シェルコマンドでラップしないでください。--root を指定するか、Deixis をプロジェクトディレクトリで起動して、プロジェクトを設定します。ルートはデフォルトで現在の作業ディレクトリとなり、起動時に一度だけ正規化されます。

Codex

コマンドラインから Deixis を追加します。

codex mcp add deixis --env RUST_LOG=deixis=info -- /absolute/path/to/deixis --root /absolute/path/to/project --config /absolute/path/to/config.toml

または、プロジェクトスコープの .codex/config.toml を追加します。

[mcp_servers.deixis]
command = "/absolute/path/to/deixis"
args = [
  "--root",
  "/absolute/path/to/project",
  "--config",
  "/absolute/path/to/config.toml",
]
tool_timeout_sec = 70

[mcp_servers.deixis.env]
RUST_LOG = "deixis=info"

ホストのツールタイムアウトを70秒に設定すると、最初のツール呼び出しでサーバーが遅延起動される場合に、デフォルトの30秒の LSP 起動時間とリクエスト上限に対応できます。Codex の startup_timeout_sec は Deixis との MCP ハンドシェイクに適用され、下流の言語サーバーには適用されません。ホスト側のすべてのオプションについては、最新のCodex MCP ドキュメントを参照してください。

JSON ベースの MCP ホスト

mcpServers JSON オブジェクトを使用するホストでは、同等の stdio エントリを使用します。設定ファイルの場所については、ホストのドキュメントを確認してください。

{
  "mcpServers": {
    "deixis": {
      "command": "/absolute/path/to/deixis",
      "args": [
        "--root",
        "/absolute/path/to/project",
        "--config",
        "/absolute/path/to/config.toml"
      ],
      "env": {
        "RUST_LOG": "deixis=info"
      }
    }
  }
}

ホストが対話型シェルの PATH を継承しない場合は、絶対パスを使用します。設定された言語サーバーのコマンドも、ホストの環境で解決できる必要があります。

Home Manager

この flake は homeManagerModules.default を提供します。空でない型付きサーバーカタログを指定すると、Deixis をインストールし、ユーザー設定を書き込み、ルートに依存しないコマンドを programs.mcp.servers に登録します。

flake の入力を追加します。

inputs.deixis = {
  url = "github:jolars/deixis";
  inputs.nixpkgs.follows = "nixpkgs";
};

次に、Home Manager モジュールをインポートして設定します。

{ inputs, ... }:

{
  imports = [ inputs.deixis.homeManagerModules.default ];

  programs.deixis = {
    enable = true;
    servers = {
      rust = {
        command = "rust-analyzer";
        fileExtensions.".rs" = "rust";
      };
      typescript = {
        command = "typescript-language-server";
        args = [ "--stdio" ];
        fileExtensions.".ts" = "typescript";
      };
    };
  };
}

生成されたコマンドには固定ルートがないため、各 MCP プロセスは作業ディレクトリにバインドされます。既存の TOML ファイルをインストールするには、servers の代わりに programs.deixis.configFile を設定します。この2つのオプションは同時に指定できません。

操作

言語サーバーは、ツール呼び出しで選択された場合にのみ起動します。ファイル単位のツールでは、プロジェクト相対パスまたはルート配下の絶対パスである path と、任意の設定済み server 名を指定できます。位置を指定するツールでは、次の値も指定できます。

{ "line": 12, "character": 8 }

どちらの値もゼロ始まりです。character は UTF-8 バイトオフセットです。複数のサーバーがファイルに該当する場合は、server を指定するか、設定ルートが一意になるようにしてください。 signature_help は、各サーバーが提供するすべてのシグネチャと、構造化されたパラメーターラベルおよびドキュメントを返します。テキスト形式のフォールバックには、エージェントのコンテキストを簡潔に保つため、アクティブなシグネチャのみ（サーバーが選択していない場合は最初のシグネチャのみ）が含まれます。

incoming_calls と outgoing_calls は、path、UTF-8 の position、および任意の server を受け取ります。これらは内部で呼び出し階層を準備した後、その位置に対して返されたすべてのシンボルを展開します。calls 内の各エントリには、from（呼び出し元）、to（呼び出し先）、fromRanges（from.uri 内の呼び出し箇所。from.positionEncoding を使用）が含まれます。両方のシンボルには、名前、種類、URI、範囲、サーバー、位置エンコーディングのほか、サーバーが提供する詳細情報や不透明なデータが含まれます。読み取り可能なプロジェクトファイルには UTF-8 が使用され、それ以外の対象にはサーバーのエンコーディングが維持されます。これらのツールを使用するには、ネゴシエートされた呼び出し階層のサポートが必要です。準備、展開、再試行では、同じリクエストタイムアウトが適用されます。ページネーションは返されたすべての呼び出しに適用され、呼び出し元と呼び出し先のペアを 1 項目として数えます。

server を指定しない場合、workspace_symbols は、接続済みで対応可能なサーバーにリクエストを分散し、ほかのサーバーは起動せずに、サーバー名の安定した順序で結果を統合します。特定のサーバーだけに問い合わせるには server を指定します。そのサーバーが必要に応じて起動します。

成功した呼び出しは、構造化 JSON と簡潔なテキスト形式のフォールバックを返します。ツールの失敗時は、安定した構造化エラーコードとともに isError: true を返します。セマンティックな結果が null または空の場合、readiness と resultStability が報告されることもあります。transient の結果は、言語サーバーが処理中であることを示しています。

シンボルの名前変更は、意図的に 2 段階の変更操作になっています。デフォルトでは、読み取り専用の確認に prepare_rename と preview_rename を使用できますが、apply_rename は公開も呼び出しもできません。MCP ホストの設定時に Deixis コマンドへ --allow-mutation を追加すると、変更の適用を許可できます。その後、ファイル、UTF-8 の位置、newName を指定して preview_rename を呼び出し、ファイルごとの構造化された編集内容と unified diff を確認してから、その不透明な previewId を apply_rename に渡します。プレビューではファイルは変更されません。この ID が許可するのは、そのプレビューと完全に一致する操作のみです。ID は 10 分後に期限切れとなり、最初の適用試行（失敗した場合も含む）で消費されます。2 回目の適用には、新しいプレビューが必要です。

名前変更では、変更不可能なプロジェクトルート配下にある既存の UTF-8 ファイルへのテキスト編集のみ受け付けます。ファイルの作成、削除、名前変更操作、変更アノテーション、外部パス、重複する編集、古くなったファイル内容は拒否されます。適用時には、コミット前にすべての置換をステージングし、コミットに失敗した場合は元の状態への復元を試みます。これはプロセス内のトランザクションであり、電源喪失時の保証ではありません。Deixis は、プロセスやマシンのクラッシュ後の復旧を保証しません。サーバーから開始された workspace/applyEdit リクエストは、明示的なプレビュー承認を伴わないため、引き続き拒否されます。

ログ

Deixis は stdout を MCP フレーム専用として確保します。Deixis のログとすべての子プロセスの stderr は stderr に出力されます。ログのデフォルト設定は deixis=info です。フィルターを変更するには、MCP ホストの環境で RUST_LOG を設定します。

RUST_LOG=deixis=debug

子プロセスと LSP のログイベントには、サーバー名が付加されます。通常の info ログには、ソースの内容やプロトコル本文は含まれません。起動、ルーティング、タイムアウト、診断、シャットダウンの失敗については、トラブルシューティングを参照してください。

開発

このリポジトリでは Rust 1.98.0 を固定しています。devenv シェルに入ると、完全なツールチェーンが提供され、pre-commit フックがインストールされます：

devenv shell
task check

オプトイン形式の互換性テストスイートでは、flake.lock で固定されたバージョンを使用して、TypeScript Language Server、Pyright、gopls、clangd、Deno をテストします：

task compatibility

Nix を使用しない場合は、これら5つのサーバーをインストールして、次を実行します：

cargo test --test real_language_servers -- --ignored --test-threads=1

実行ファイルのパスは、DEIXIS_TYPESCRIPT_LANGUAGE_SERVER、DEIXIS_PYRIGHT_LANGSERVER、DEIXIS_GOPLS、DEIXIS_CLANGD、DEIXIS_DENO で上書きできます。

エージェントベンチマークでは、Deixis が利用可能な場合と利用できない場合、また中立的な指示と LSP に誘導された指示を使う場合の Codex の試行をペアで実施します。タスクの成功率、モデルのトークン数、所要時間、MCP 呼び出し数、パッチ、未加工のイベントストリームを、分離された Git ワークツリーに記録します。

開発ゲートの詳細は、CONTRIBUTING.md を参照してください。

ライセンス

お好みに応じて、Apache License, Version 2.0 または MIT License のいずれかのライセンスの下で利用できます。