Completion

Documentation Index

完全なドキュメント索引は modelcontextprotocol.io/llms.txt で取得してください。さらに調べる前に、このファイルを使って利用可能なすべてのページを見つけてください。

Model Context Protocol (MCP) は、server が prompt や resource template の引数に対する autocompletion suggestion を提供するための標準化された方法を提供します。ユーザーが特定の prompt（name で識別される）または resource template（URI で識別される）の引数値を入力しているとき、server は文脈に応じた suggestion を提供できます。

User Interaction Model

MCP における completion は、IDE の code completion に似た対話的ユーザー体験を支援するよう設計されています。

たとえば、application はユーザーの入力中に completion suggestion をドロップダウンやポップアップメニューに表示し、利用可能な候補を絞り込んだり選択したりできるようにしてもよいです。

ただし、実装は completion を任意のインターフェイスパターンで公開してかまいません。プロトコル自体は特定のユーザー操作モデルを義務付けません。

Capabilities

completion をサポートする server は、completions capability を宣言しなければなりません (MUST)。

{
  "capabilities": {
    "completions": {}
  }
}

Protocol Messages

Requesting Completions

completion suggestion を取得するために、client は何を補完対象にしているかを reference type で指定した completion/complete request を送信します。

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",
      "name": "code_review"
    },
    "argument": {
      "name": "language",
      "value": "py"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "completion": {
      "values": ["python", "pytorch", "pyside"],
      "total": 10,
      "hasMore": true
    }
  }
}

複数の引数を持つ prompt または URI template については、client は後続 request に文脈を与えるために、以前に確定した補完結果を context.arguments オブジェクトに含めるべきです (SHOULD)。

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",
      "name": "code_review"
    },
    "argument": {
      "name": "framework",
      "value": "fla"
    },
    "context": {
      "arguments": {
        "language": "python"
      }
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "completion": {
      "values": ["flask"],
      "total": 1,
      "hasMore": false
    }
  }
}

Reference Types

このプロトコルは 2 種類の completion reference をサポートします。

Type	Description	Example
`ref/prompt`	name によって prompt を参照する	`{"type": "ref/prompt", "name": "code_review"}`
`ref/resource`	resource URI を参照する	`{"type": "ref/resource", "uri": "file:///{path}"}`

Completion Results

server は、関連度で順位付けされた completion value の配列を返します。これには次が含まれます。

1 response あたり最大 100 件
利用可能な一致件数の省略可能な合計値
追加結果が存在するかを示す boolean 値

Message Flow

sequenceDiagram participant Client participant Server Note over Client: User types argument Client->>Server: completion/complete Server-->>Client: Completion suggestions Note over Client: User continues typing Client->>Server: completion/complete Server-->>Client: Refined suggestions

Data Types

CompleteRequest

ref: PromptReference または ResourceReference
argument: 次を含むオブジェクト
- name: 引数名
- value: 現在の値
context: 次を含むオブジェクト
- arguments: すでに解決済みの引数名とその値の対応付け

CompleteResult

completion: 次を含むオブジェクト
- values: suggestion の配列（最大 100 件）
- total: 省略可能な総一致件数
- hasMore: 追加結果の有無を示すフラグ

Error Handling

server は、一般的な失敗ケースに対して標準 JSON-RPC error を返すべきです (SHOULD)。

Method not found: -32601（capability がサポートされていない）
無効な prompt name: -32602（Invalid params）
必須引数の欠落: -32602（Invalid params）
Internal error: -32603（Internal error）

Implementation Considerations

server は次を行うべきです (SHOULD)。
- suggestion を関連度順で返す
- 適切な場合は fuzzy matching を実装する
- completion request に rate limiting を適用する
- すべての入力を検証する
client は次を行うべきです (SHOULD)。
- 急速に連続する completion request を debounce する
- 適切な場合は completion result をキャッシュする
- 欠落または部分的な結果を適切に扱う

Security

実装は次を満たさなければなりません (MUST)。

すべての completion 入力を検証する
適切な rate limiting を実装する
機微な suggestion への access を制御する
completion ベースの情報漏えいを防ぐ