Microsoft's Type Server Protocol extends LSP with JSON-RPC type queries for Python

What Microsoft published

Microsoft has published the specification for a Type Server Protocol (TSP), a JSON-RPC protocol that lets a client ask a "type server" for Python analysis data. The document sits in the company's pylance-release repository on GitHub and reached the Hacker News front page. According to the specification, a type server maintains the type-analysis state for a whole workspace and answers requests covering the protocol version, snapshots, Python search paths, import resolution, and type queries — computed, declared and expected types.

The design leans on Language Server Protocol conventions wherever they are useful: TSP reuses LSP's Position and Range data shapes and represents URIs as strings exactly as LSP does, while all of its own methods are prefixed with typeServer/. Three artifacts are declared authoritative: a TypeScript file defining the interfaces and request types, a machine-readable JSON model of the protocol, and a JSON schema for validating that model.

How a session runs

A client starts or connects to a type server over a transport the server supports, such as stdio or Node IPC; when stdio is used, stdout is reserved for JSON-RPC messages. Clients are expected to supply enough workspace and document state for the server to answer requests, and the specification describes the common pattern: run ordinary LSP initialization and document synchronization first, then send typeServer/* requests over the same JSON-RPC connection.

A typical session proceeds in order. The client initializes shared state through the LSP initialize and initialized messages, calls typeServer/getSupportedProtocolVersion and verifies the returned semver string is compatible, then calls typeServer/getSnapshot to obtain the first snapshot identifier. After that it can issue type-query, import-resolution or search-path requests that carry the current snapshot where the request shape requires it. When earlier type results stop being valid, the server pushes a typeServer/snapshotChanged notification. Snapshots are non-negative integers that identify a given analysis state.

Multi-connection mode

Since version 0.4.1, TSP also supports optional extra read-only connections. The main connection keeps ownership of everything stateful — LSP lifecycle messages, workspace and configuration notifications, document synchronization, snapshot notifications and the typeServer/connection control request — while extra channels carry only read-only TSP requests whose results are valid for the snapshot the client supplies.

The specification frames this purely as a performance option, aimed at high-volume type queries or background workers that should not block the main connection. Support is negotiated during the normal LSP initialize handshake under capabilities.experimental.typeServerMultiConnection, and the mode activates only when both sides advertise the capability and their transport lists overlap; the one built-in extra-connection transport is IPC. Servers must still work correctly in single-connection mode, and multi-connection support must not be required for protocol correctness. Channels are opened and closed with a typeServer/connection request whose arguments carry either a single full-duplex IPC endpoint or an input/output pair on platforms that expose only one-way endpoints. Servers are told to reject LSP traffic, state-changing notifications and any TSP message not allowed for the negotiated version when they arrive on an extra connection.

Versioning and maturity

TSP uses semantic version strings for client and server compatibility checks, with an explicit caveat: while the protocol is in the 0.x line, minor version changes may be breaking. The history runs from an initial 0.1.0 through 0.2.0, which added request types and fields; 0.3.0, which switched to more complex type shapes; 0.4.0, which moved to a Type union and stub-based type payloads; and 0.4.1, which introduced multi-connection negotiation and the connection control request.

Why it matters

LSP standardized how editors consume diagnostics, completions and other language features, but the deeper machinery of type analysis has mostly stayed private to individual implementations such as Pylance. TSP proposes a wire-level standard for that layer: any editor or tool that speaks JSON-RPC could ask a conforming server for the computed type of an expression, the declared type of a symbol, or how an import resolves, instead of depending on implementation-specific APIs. The Python-only scope and the 0.x versioning make clear this is early work, and breaking changes are explicitly on the table. Still, because the protocol already borrows LSP's shapes and lifecycle, it is positioned as a natural extension of the LSP ecosystem — and if other language servers adopt the same pattern, type analysis could become as portable as the features LSP already covers.