Type Server プロトコル（TSP）仕様書

Type Server プロトコル（TSP）は、型サーバーに対して Python の分析データを照会するための JSON-RPC プロトコル です。

概要とアーキテクチャ

型サーバーはワークスペースの型分析状態を保持し、以下の情報をクライアントに返答します。

• プロトコルのバージョン情報
• スナップショット（分析状態の識別子）
• Python の検索パス
• インポート解決結果
• 型クエリ結果（計算された型、宣言された型、想定される型）

データ形状と慣習

• Position

  や

  Range

  などは、**言語サーバープロトコル（LSP）**のデータ形状と慣習を採用します。
• URI は文字列として表現し、LSP と同等の形式を使用します。
• メソッド名はすべて

  typeServer/

  プレフィックスで始まります。

プロトコルアティファクト

以下のファイルが権限のある定義です。

• typeServerProtocol.ts

  : TypeScript インターフェースとリクエストタイプを定義。

• tsp.json

  : 機械可読なプロトコルモデル。

• tsp.schema.json

  : プロトコルモデルの JSON スキーマ。

バージョン履歴

クライアントとサーバー間の互換性チェックには、**セマンティックバージョニング（SemVer）**文字列を使用します。

• 0.x ライン: マイナー版の変更でも破壊的変更が生じる可能性があります。
• パッチ版: 同じマイナーライン内で後方互換性を維持します。

バージョン一覧

0.1.0

0.2.0

0.3.0

0.4.0

0.4.1

typeServer/connection

接続モデル

クライアントは型サーバーを起動し、以下のトランспортを通じてメイン JSON-RPC 接続で通信します。

• stdio

  （出力標準をプロトコルメッセージに予約）
• Node IPC

状態の同期フロー

型サーバーには十分なワークスペースおよびドキュメント状態を受け取る必要があります。通常は以下のような手順で行われます。

1. 通常の LSP 初期化とドキュメント同期を行う。
2. 同じ JSON-RPC 接続上で

   typeServer/*

   リクエストを送信する。

オプション：追加読み取り専用接続

TSP は、メイン接続（初期化・状態管理など）とは別に、追加の読み取り専用接続をサポートします。

• 両者がネゴシエーションした場合のみ開かれます。
• メイン接続が変更可能な状態を管理し続け、追加接続で読み取り専用クエリを実行できます。

起動シーケンス

典型的なセッションは以下の順序で進みます。

1. クライアントが型サーバーを起動または接続します。
2. LSP の

   initialize

   /

   initialized

   メッセージで共有ワークスペース状態を初期化します。
3. クライアントは

   typeServer/getSupportedProtocolVersion

   を呼び出し、互換性を検証します。
4. クライアントは

   typeServer/getSnapshot

   を呼び出して、最初のスナップショット識別子を入手します。
5. 現在のスナップショットを添えて、型クエリなどを送信します。
6. 型結果が無効になった場合（ファイル変更など）、サーバーは

   typeServer/snapshotChanged

   を送信します。

マルチ接続モード

大量の型クエリやバックグラウンドワーカーなどの同時実行を最適化するためのオプション機能です。

• メイン接続：ワークスペース状態の変更を管理（書可能）。
• 追加接続：読み取り専用の TSP リクエストを実行。
• 注意: マルチ接続サポートはプロトコルの必須条件ではありませんが、大量処理時に推奨されます。

キャパビリティハンドシェイク

マルチ接続サポートは LSP

initialize

クライアント側の広告（Advertisement）

実験機能領域に以下の構造を返します：

{
  "capabilities": {
    "experimental": {
      "typeServerMultiConnection": {
        "supportedTransports": ["ipc"]
      }
    }
  }
}

サーバー側の広告

サーバーも同様の構造を

initialize

有効になる条件:

• 両側が

  typeServerMultiConnection

  を広告すること。
• 共有するトランспорт（例：

  ipc

  ）が少なくとも 1 つ存在すること。
• どちらかが能力を省略したり、共通するトランспортがなければ、セッションは単一接続のままになります。

現在標準的にサポートされている追加接続トランポート種別は

ipc

追加接続の開通と閉鎖

ネゴシエーション後、メイン接続上で

typeServer/connection

チャンネル開通（Open）

クライアントが送信するリクエスト：

{
  "type": "open",
  "kind": "ipc",
  "args": ["<ipc-endpoint>"]
}

• 成功時:

  success: true

  を含む結果を返す。
• 失敗時:

  success: false

  とエラーメッセージを返す。

IPC エンドポイント引数

プラットフォーム依存の形式があります。

フルダプлекс（双方向）ストリームの場合:

{
  "type": "open",
  "kind": "ipc",
  "args": ["<full-duplex-ipc-endpoint>"]
}

片方向エンドポイントのみ公開する場合（入力/出力ペア）:

{
  "type": "open",
  "kind": "ipc",
  "args": ["<input-ipc-endpoint>", "<output-ipc-endpoint>"]
}

チャンネル閉鎖（Close）

クライアントが送信するリクエスト：

{
  "type": "close",
  "kind": "ipc",
  "args": ["<ipc-endpoint>"]
}

• args

  は開通時の形式と同じです（双方向なら 1 つ、片方向なら 2 つ）。
• サーバーは対応するチャンネルの提供を停止し、トランポートを閉じます。

許可されたトラフィック

メイン接続

すべての状態変更トラフィックを管理します。以下のメッセージのみ許されます：

• LSP の初期化およびライフサイクルメッセージ。
• ワークスペース、設定、ファイルウォッチャー、ドキュメント同期通知。
• サーバーからクライアントへのスナップショット通知。

• typeServer/connection

  コントロールリクエスト。

追加接続（読み取り専用）

TSP 専用です。以下の制限があります。

• サーバーの状態を変更しません。
• クライアントが提供したスナップショットの結果が無効になっているようなリクエストにのみ使用できます。
• ネゴシエされた TSP バージョンに基づき、特定のリクエストのみ許可されます（後述の表参照）。

サーバー側の拒否処理: 追加接続で受け取った場合、以下のいずれかを拒否すべきです：

• LSP のトラフィック
• 状態変更通知

• typeServer/connection

  リクエスト
• ネゴシエされたバージョンに許可されていないあらゆる TSP メッセージ

バージョン別の追加接続メッセージ（TSP 0.4.1）

typeServer/getSupportedProtocolVersion

typeServer/getSnapshot

typeServer/getPythonSearchPaths

typeServer/resolveImport

typeServer/getComputedType

typeServer/getDeclaredType

typeServer/getExpectedType

スナップショット

スナップショットは、型サーバーの分析状態の時点ごとのビューを識別するための非負整数です。

• 型ハンドルやオブジェクトは、明示的に別のことを述べない限り、そのスナップショットで有効です。
• 分析結果が無効化されるたびに（ファイル変更、設定変更など）、サーバーはスナップショットを進める必要があります。

スナップショットルール

typeServer/getSnapshot

typeServer/snapshotChanged

-32802 (ServerCancelled)

位置と範囲

TSP は LSP の位置慣習に従います。

• ライン番号: 0 ベース
• 文字オフセット: 0 ベースの UTF-16 コードユニット
• 範囲: 開始位置と終了位置を使用してソーススパンを識別

型サーバーが異なるエンコーディング（例：Byte Offset）で位置を保持する場合、プロトコル境界で LSP 形式への変換が必要です。不適切な変換は構文ノード情報の誤りを引き起こします。

ノード、宣言、およびハンドル

型クエリリクエスト（

getComputedType

• ノード: URI + ソース範囲
• 宣言: シンボル定義場所と方法（AST ノードを持つ通常のもの、または合成宣言）。

特殊値

InvalidHandle

• 値: -1
• 意味: 無効または利用できないハンドル。
• 扱い: クライアントとサーバーはこれを有効なオブジェクト ID ではなく、Sentinel 値として扱う必要があります。

型結果（Type Objects）

型結果は JSON シリアライズ可能なタグ付きオブジェクトです。

Discriminator

種別一覧

0

1

2

3

4

int | str

5

import os

6

7

@overload

8

9

型 ID とスナップショットの関係

• 返される型オブジェクトは、そのリクエストで使用されたスナップショットのみ有効です。
• 型 ID はシリアライズされたグラフ内で

  TypeReference

  を介して参照されますが、別のレスポンス間で比較してはなりません（グローバル ID でありません）。
• 大きなまたは再帰的なグラフを避けるために

  TypeReference

  を使用します。

プロトコル表面：メッセージ一覧

現在のプロトコルは意図的に小さく設定されています。下表にすべての TSP メッセージ、方向、パラメータ形状を示します。

getSupportedProtocolVersion

getSnapshot

snapshotChanged

{ old, new }

connection

{ type, kind, args? }

{ success, message? }

getPythonSearchPaths

{ fromUri, snapshot }

resolveImport

{ sourceUri, moduleDescriptor, snapshot }

getComputedType

{ arg: Node|Decl, snapshot }

getDeclaredType

{ arg: Node|Decl, snapshot }

getExpectedType

{ arg: Node|Decl, snapshot }

• サーバーは統合するクライアントによって要求されるメッセージを実装し、結果形状で許可されている場所のみ

  undefined

  を返すべきです。

型クエリの違い

3 つの型クエリリクエストは、報告される型の種類が異なります。

1. getComputedType

   : コードフローから推測された型
   • 例:

     a: int

     を絞り込み

     b = a + 1

     とすると、

     b

     は

     int

     。

2. getDeclaredType

   : ソースに明示的に記述された型
   • 例:

     def foo(a: int \| str)

     の場合、

     a

     は

     int \| str

     。

3. getExpectedType

   : 周囲のコンテキストが期待する型
   • 例:

     foo(4)

     の呼び出しにおける引数の想定型は

     int \| str

     。

エラー処理

標準的な JSON-RPC エラーレスポンスを使用します。

-32802

-32602

-32603

メッセージ詳細の注意点: エラーには失敗したリクエストを特定するのに十分な情報を含める必要がありますが、ローカルシークレットや実装固有の状態を暴露してはなりません。

互換性チェックリスト

型サーバーは以下の振る舞いを検証すべきです。

• getSupportedProtocolVersion

  はクライアントの SemVer と互換性を保つ文字列を返す。
• すべてのペイロードはプロトコルアティファクトに従ってシリアライズされる。

• getSnapshot

  は減少しない非負整数を返す。
• ファイルや設定の変更がスナップショット無効化を適切に引き起こす。
• 古いスナップショットへの要求は再試行可能なエラー（-32802）で失敗する。
• 位置・範囲の変換に LSP 規格（0 ベース UTF-16）を使用する。
• インポート解決はドキュメント URI または結果なしを返す。
• 型クエリは適切な Type オブジェクトまたは

  undefined

  を返す。
• マルチ接続はネゴシエ可能なトランポートのみ広告する。
• 追加接続は許可された TSP メッセージのみ受け入れ、その他を拒否する。

最終更新情報: この仕様の最後のコンテンツ更新は Pylance 2026.4.1 と一致しています。