Microsoft's Type Server Protocol (TSP) lets tools request Python analysis data through JSON-RPC. Its specification in the Pylance repository describes a shared workspace model: the main connection controls changes, while optional extra connections handle read-only queries.
This explanation is for Python tool authors evaluating that interface. The supplied specification lists protocol version 0.4.1, which adds multi-connection negotiation and the typeServer/connection control request. It does not establish an announcement date or demonstrate interoperability between implementations. The examples below come from the documentation; no implementation tests were run for this article.
Choose the right type query
TSP uses Language Server Protocol (LSP) data shapes and conventions where useful, including positions and ranges. Its methods use the typeServer/ prefix. The specification separates three questions:
typeServer/getComputedTypereturns the type inferred from code flow. In the documentation example, after narrowingatoint, the computed type ofbinb = a + 1isint.typeServer/getDeclaredTypereturns the type explicitly written in the source. Fordef foo(a: int | str), the declared type ofaisint | str.typeServer/getExpectedTypereturns the type the surrounding context expects. For the callfoo(4), the documentation givesint | stras the expected type of the argument.
Choose the request according to whether your tool needs an annotation, a flow-derived type or the surrounding context's requirement. Treating these as interchangeable would lose a distinction the interface exposes.
TSP also defines requests for import resolution and Python search paths. The supplied specification does not establish which independent tools implement them.
Keep changes on the main connection
The main connection owns initialization, workspace state, document synchronization, state-changing notifications and connection control. Optional extra connections accept read-only TSP requests after client and server negotiate support. A server must still work correctly with a single connection.
Both sides must advertise multi-connection support and share a supported transport kind. Otherwise, the session remains single-connection and the client must not send typeServer/connection. An extra channel does not take ownership of document updates or make an earlier analysis result current.
Recover when a snapshot becomes stale
A snapshot identifies a point-in-time view of the server's analysis state. Returned type objects belong to the snapshot used by their request. The server must advance the snapshot whenever a previously returned analysis result may be invalid.
typeServer/snapshotChanged reports the previous and new snapshot identifiers. Requests containing a stale snapshot should fail with a JSON-RPC error that lets the client retry. The preferred error is LSP's ServerCancelled code, -32802. A client can request the current snapshot with typeServer/getSnapshot, then retry using that snapshot.
Snapshot validity is only one part of interpreting a response. Type IDs connect references within a single serialized response graph; they are not stable identities across separate responses, even within the same snapshot. A client should not use matching type IDs from different responses as proof that the types are the same.
A proposed compatibility check is to request analysis, make a document edit that can change the result, then check that a request using the old snapshot fails and a fresh request succeeds. This is an unexecuted test proposal, not an observed result.
Tool authors should check protocol compatibility and snapshot recovery before adding extra connections. The specification says minor-version changes in the 0.x line may be breaking, while patch changes remain backward compatible within the same minor line. TSP is worth evaluating when a tool needs workspace analysis through these requests. Developers choosing an integration on the strength of demonstrated editor compatibility will need implementation evidence beyond this specification.