Deixis

Deixis

Deixis is a Model Context Protocol (MCP) server that gives coding agents typed access to Language Server Protocol (LSP) operations. It manages explicitly configured language servers for one project and exposes their semantic capabilities without adding another filesystem, shell, editor, index, or memory layer.

[!WARNING]

Deixis is pre-alpha. Its semantic tools and guarded rename workflow work, but

no stability guarantees are available yet.

Capabilities

A configured Deixis session exposes fifteen read-only MCP tools by default. Starting it with --allow-mutation adds apply_rename as a sixteenth tool.

Deixis negotiates UTF-8, UTF-16, and UTF-32 positions, synchronizes documents from disk before file-scoped requests, gates every operation on the language server's advertised capabilities, and preserves source-server provenance in results. Several language servers may serve one immutable project root.

Recoverable LSP cancellations are retried up to three times after a bounded readiness wait. Retries share the original request timeout and stop when the MCP caller cancels. If retries are exhausted, the error reports the attempt count and preserves the language server's error details.

Navigation, hover, signature help, references, symbols, and call-hierarchy preparation also retry empty results observed during indexing and ContentModified errors within the same timeout and three-retry limit. After an empty result, Deixis waits for readiness up to the request deadline instead of spending retries while indexing continues. A server that remains busy produces a request_timeout error (30 seconds by default). ContentModified errors wait up to five seconds for readiness per retry. File-scoped retries verify that both the synchronized document and its contents on disk are unchanged before reusing a position. Nonempty results and empty results from servers with ready or unknown status throughout the request return immediately.

Use definition, type_definition, implementation, and references directly for targeted symbol navigation. Use document_symbols only when you need a file outline, such as a view of its types, functions, and nested members. It is not a default navigation step or a prerequisite for other queries. This guidance is also included in the MCP initialization instructions and tool description.

Calling deixis_server_status without arguments lists attached servers in lexical order and counts the remaining configured servers:

attached: python, rust

not attached: 3

An empty list is shown as attached: none; the count is included even when zero. Structured output contains attached (an array of configured names) and notAttached (a count). A server is attached after Deixis has synchronized at least one document with its current process. Servers that have not started or have started without a synchronized document count as not attached. Pass server for its detailed lifecycle and capability snapshot; start: true also requires an explicit server name.

references, incoming_calls, outgoing_calls, document_symbols, and workspace_symbols accept an optional limit (default 100, maximum 500) and offset (default 0). Each page also caps the compact JSON result array at 64 KiB. The structured pagination object reports returned, total, truncated, and, when more results remain, nextOffset. Continue with that offset and the same query arguments. Each call reruns the query, so file edits, indexing progress, or changes to attached servers can shift results between pages. Text responses summarize the page.

Every nested document symbol counts toward the limit. Symbols retain their hierarchy within a page; index and parentIndex identify relationships across pages, and childCount reports the full number of direct children. Individual items too large for a page are omitted, with their indexes listed in pagination.omitted and truncated: true. Pagination advances past these items. Counts and byte limits apply to the normalized results returned by Deixis; language servers still compute their full responses.

See DESIGN.md for the protocol and architecture and TODO.md for planned work.

Installation

Language servers are separate programs; install the ones you configure and make them visible in the environment of the MCP host.

Prebuilt binaries

The [latest GitHub release] provides archives for x86-64 and ARM64 Linux, Intel and Apple silicon macOS, and x86-64 Windows. Linux releases include both glibc and static musl builds.

Install the appropriate release automatically on Linux or macOS:

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

Or from PowerShell on Windows:

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

The installers place deixis in Cargo's binary directory. Each release also includes SHA-256 checksums and GitHub build attestations. Verify a downloaded archive with:

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

Nix

Install the default flake package:

nix profile install github:jolars/deixis

Or run it without installing:

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

Cargo

Rust 1.98.0 or newer is required:

cargo install deixis --locked

The crates.io package belongs to the MCP Registry identity mcp-name: io.github.jolars/deixis.

To build a checkout instead:

git clone https://github.com/jolars/deixis.git

cd deixis cargo build --release --locked

The resulting binary is target/release/deixis (deixis.exe on Windows).

Configure language servers

Start with the tested example configuration, or define a single server:

[servers.rust]

command = "rust-analyzer" file_extensions = { ".rs" = "rust" }

Pass the file explicitly with --config, or install it as the user configuration:

$XDG_CONFIG_HOME/deixis/config.toml takes precedence on every platform when that variable is set. An explicit --config takes precedence over the user configuration. Deixis never discovers configuration in the project tree.

The configuration is strict: unknown fields, empty commands, invalid routes, and zero-valued bounds stop startup with an error. The configuration reference documents every field, default, routing rule, and process limit.

Connect an MCP client

Deixis is a local stdio server. The MCP host must launch the binary directly; do not wrap it in a shell command. Set the project either with --root or by starting Deixis in the project directory. The root defaults to the current working directory and is canonicalized once at startup.

Codex

Add Deixis from the command line:

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

Or add a project-scoped .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"

The 70-second host tool timeout accommodates the default 30-second LSP startup and request bounds when the first tool call starts a server lazily. Codex's startup_timeout_sec applies to the Deixis MCP handshake, not to a downstream language server. See the current [Codex MCP documentation] for all host-side options.

JSON-based MCP hosts

For a host that uses an mcpServers JSON object, use the equivalent stdio entry. Consult the host's documentation for its configuration file location.

{

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

Use absolute paths when the host does not inherit your interactive shell's PATH. The configured language-server commands must also resolve in the host's environment.

Home Manager

The flake provides homeManagerModules.default. A nonempty typed server catalog installs Deixis, writes its user configuration, and registers one root-agnostic command in programs.mcp.servers:

Add the flake input:

inputs.deixis = {

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

Then import and configure the Home Manager module:

{ 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"; }; }; }; }

The generated command has no fixed root, so each MCP process binds to its working directory. Set programs.deixis.configFile instead of servers to install an existing TOML file. The two options are mutually exclusive.

Operation

Language servers start only when selected by a tool call. File-scoped tools accept a project-relative or root-contained absolute path and an optional configured server name. Position-based tools also accept:

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

Both values are zero-based; character is a UTF-8 byte