docs: refresh translations for recent English changes (#3379)
This commit is contained in:
Max
GitHub
parent
d8b638304e
commit
c5d7d0b6d0
6 changed files with 3149 additions and 1047 deletions
|
|
@ -1,25 +1,25 @@
|
|||
---
|
||||
translation:
|
||||
sections: [e33d441f12d50535, 7099694c603e0f5f, c1df4cf9673433e6, c9cd294541422e6e, 6cec073617bfd037, efa92b8f99e908c8, 6a22a29e27fb4601]
|
||||
sections: [7be05607887e6853, e7375894888d9750, c36f73fc7e3af13b, 2fec2d7e129e62fe, 809b0e0a7c27295a, b4395a04d2a5d906, 1a436007f5f54779, c6b2078ed1e63ba5]
|
||||
tool: 1
|
||||
---
|
||||
# エラーの処理 {#handling-errors}
|
||||
|
||||
ツールの失敗には 2 通りあり、SDK はそれぞれをまったく違う形で扱います。
|
||||
ツールの失敗には 3 通りあり、SDK はそれぞれを違う形で扱います。
|
||||
|
||||
通常の例外を送出すると、**モデル**がそれを目にします。`MCPError` を送出すると、**プロトコル**がそれを目にします。
|
||||
`ToolError` を送出すると、**モデル**がメッセージを目にします。`MCPError` を送出すると、**プロトコル**がそれを目にします。それ以外を送出するとクラッシュです。モデルには呼び出しが失敗したことだけが伝わり、トレースバックはログに記録されます。
|
||||
|
||||
このページは、そのどちらを選ぶかについてです。
|
||||
このページは、そのどれを選ぶかについてです。
|
||||
|
||||
## モデルが直せるエラー {#an-error-the-model-can-fix}
|
||||
|
||||
何かを検索するツールを用意し、その検索を空振りさせてみます。
|
||||
|
||||
```python title="server.py" hl_lines="11-12"
|
||||
```python title="server.py" hl_lines="2 12-13"
|
||||
--8<-- "docs_src/handling_errors/tutorial001.py"
|
||||
```
|
||||
|
||||
この 2 行に MCP らしいところは何もありません。`get_author` は、どんな Python 関数でもそうするように、ただの `ValueError` を送出しているだけです。
|
||||
`mcp.server.mcpserver.exceptions` にある `ToolError` は、何かがうまくいかなかったことをツールがモデルに伝える手段です。
|
||||
|
||||
カタログにないタイトルで呼び出して、結果を見てみましょう。
|
||||
|
||||
|
|
@ -30,19 +30,21 @@ result.structured_content # None
|
|||
```
|
||||
|
||||
* リクエストは**成功**しています。結果が返っており、呼び出し側では何も送出されていません。
|
||||
* `is_error` は `True` で、例外のメッセージ（ツール名が前に付きます）が `content` に入っています。まさにモデルが読む場所です。
|
||||
* `is_error` は `True` で、メッセージ（ツール名が前に付きます）が `content` に入っています。まさにモデルが読む場所です。
|
||||
* `structured_content` は `None` です。失敗した呼び出しには、構造化すべき戻り値がありません。
|
||||
|
||||
これが**ツールエラー**で、ツールが送出する「あらゆる」例外のデフォルトの扱いです。そして、ほとんどの場合これこそが望む挙動です。
|
||||
これが**ツールエラー**で、ほとんどの場合これこそが望む挙動です。
|
||||
|
||||
ツールを呼び出しているのはモデルです。引数を選んだのもモデルです。つまりツールエラーは会話の 1 ターンになります。モデルは「No book titled 'Nothing' in the catalog.」を読み、タイトルを推測し損ねたことに気づき、もっと良いタイトルで呼び直します。`raise` を 1 つ書いただけで、自己修正するエージェントが手に入りました。
|
||||
|
||||
サーバー側では、`ToolError` はログに `INFO` が 1 行出るだけで、トレースバックはありません。想定していた失敗なので、調べることは何もありません。
|
||||
|
||||
!!! tip
|
||||
ツールからエラーメッセージを `return` しないでください。返された文字列は `is_error=False` なので、モデルにとっても（そしてあらゆるクライアント UI にとっても）ツールは正常に動作し、その文字列が答えだったように見えます。`raise` してください。シグナルはこのフラグです。
|
||||
|
||||
## モデルが直せないエラー {#an-error-the-model-cannot-fix}
|
||||
|
||||
今度は `ValueError` を `MCPError` に置き換えます。
|
||||
今度は `ToolError` を `MCPError` に置き換えます。
|
||||
|
||||
```python title="server.py" hl_lines="1 3 14"
|
||||
--8<-- "docs_src/handling_errors/tutorial002.py"
|
||||
|
|
@ -74,16 +76,35 @@ result.structured_content # None
|
|||
|
||||
2 つの経路は、2 つの異なる問いに答えるものです。
|
||||
|
||||
* 「実行」の失敗、つまりツールがやろうとしたことがうまくいかなかった場合は、**任意の例外を送出**します。呼び出しを選んだのはモデルなので、モデルがその結果を目にし、立て直す機会を得るべきです。綴りの間違ったタイトル、タイムアウトした上流の API、存在しない行。どれもツールエラーです。
|
||||
* 「実行」の失敗、つまりツールがやろうとしたことがうまくいかなかった場合は、**`ToolError` を送出**します。呼び出しを選んだのはモデルなので、モデルがその結果を目にし、立て直す機会を得るべきです。綴りの間違ったタイトル、タイムアウトした上流の API、存在しない行。どれもツールエラーです。
|
||||
* 「リクエストそのもの」を拒否すべきときは **`MCPError` を送出**します。ツールが依存するケイパビリティをクライアントが持っていない、サーバーが誰にも応答できる状態にない、呼び出し側が必要な手順を飛ばした。どれもモデルが再試行しても直らないので、メッセージを渡しても得るものはありません。
|
||||
|
||||
決め手になる問いは 1 つです。**もっと賢いモデルならこれを避けられたか**。はい → 通常の例外。いいえ → `MCPError`。
|
||||
決め手になる問いは 1 つです。**もっと賢いモデルならこれを避けられたか**。はい → `ToolError`。いいえ → `MCPError`。
|
||||
|
||||
この基準で見ると、`get_author` の 2 番目のバージョンは選択を誤っています。より良いタイトルで直るのですから、モデルはメッセージを見るべきでした。あれは仕組みを見せるためのもので、推奨するためのものではありません。
|
||||
|
||||
!!! info
|
||||
`MCPError` は `from mcp import MCPError` でインポートでき、`code`、`message`、省略可能な `data` ペイロードを受け取ります。そこに入れた内容がそのままクライアントに届きます。SDK は送出された `MCPError` をサニタイズせず、そのまま転送します。
|
||||
|
||||
## その他の例外 {#any-other-exception}
|
||||
|
||||
今度はチェックを外し、辞書の検索がそれ自体で失敗するのに任せます。
|
||||
|
||||
```python title="server.py" hl_lines="11"
|
||||
--8<-- "docs_src/handling_errors/tutorial004.py"
|
||||
```
|
||||
|
||||
`CATALOG[title]` は `KeyError` を送出します。想定していなかった例外なので、SDK はクラッシュとして扱います。
|
||||
|
||||
```python
|
||||
result.is_error # True
|
||||
result.content # [TextContent(text="Error executing tool get_author")]
|
||||
```
|
||||
|
||||
呼び出しは依然として `is_error=True` を返すので、モデルは失敗したことを知り、先へ進めます。受け取らないのは例外のテキストです。コードから出た `KeyError` や、3 つ下の層のライブラリのドライバーが吐いた SQL の山は、サーバーの内部を説明してしまうかもしれません。そのため、サーバーの外には決して出ません。
|
||||
|
||||
それを受け取るのはサーバー側です。サーバーはクラッシュを `ERROR` レベルで完全なトレースバック付きで記録し、`Tool 'get_author' raised an unexpected exception` と出力します。したがって、`WARNING` レベルの本番ログはどの `ToolError` でも静かなままで、本当に何かが壊れた瞬間に声を上げます。
|
||||
|
||||
## 存在しないリソース {#a-resource-that-doesnt-exist}
|
||||
|
||||
リソースも同じ線引きをします。そして、よくあるケースのために名前付きの例外を 1 つ用意しています。
|
||||
|
|
@ -104,7 +125,7 @@ result.structured_content # None
|
|||
}
|
||||
```
|
||||
|
||||
ここには `is_error=True` のような中間的な結果がないことに注目してください。リソースの読み取りは、内容を返すか失敗するかのどちらかです。リソースにはプロトコルの経路しかありません。テンプレートをはじめ、リソースに関するその他すべては **[リソース](resources.md)** にあります。
|
||||
ここには `is_error=True` のような中間的な結果がないことに注目してください。リソースの読み取りは、内容を返すか失敗するかのどちらかです。リソースにはプロトコルの経路しかありません。`ResourceError` は「見つからない」以外の失敗のための同じ仕組みで（`-32603` とメッセージ）、どちらもログには `INFO` が 1 行出るだけです。`MCPError` を除くその他の例外はクラッシュです。クライアントには URI だけを示す `-32603` が届き、トレースバックは `ERROR` レベルでログに記録されます。テンプレートをはじめ、リソースに関するその他すべては **[リソース](resources.md)** にあります。
|
||||
|
||||
## 送出する必要のないエラー {#errors-you-never-raise}
|
||||
|
||||
|
|
@ -115,16 +136,17 @@ result.structured_content # None
|
|||
つまり、書かなくてよい `raise` 文がまるごと一群あるということです。自分の型ヒントを改めて検証しないでください。
|
||||
|
||||
!!! info
|
||||
このページの内容はすべて**クライアント**から見えるものです。テストを書くときに使うインメモリの `Client` にも、まったく同じものが見えます。`raise_exceptions=True` でもツールエラーがトレースバックに戻ることはありません。このフラグが作用できる時点では、例外はすでに `is_error=True` の結果になっています。結果に対してアサートしてください。このパターンは **[テスト](../get-started/testing.md)** で扱っています。
|
||||
このページで**クライアント**から見えるものはすべて、テストを書くときに使うインメモリの `Client` からも見えます。`raise_exceptions=True` でも、失敗したツールの例外が呼び出し側に返されることはありません。このフラグが作用できる時点では、例外はすでに `is_error=True` の結果になっています。結果に対してアサートしてください。クラッシュのトレースバックが必要なら、それはサーバーのログにあり、pytest の `caplog` で捕捉できます。このパターンは **[テスト](../get-started/testing.md)** で扱っています。
|
||||
|
||||
## まとめ {#recap}
|
||||
|
||||
* ツールの中で**任意の例外**を送出する → 呼び出しは `is_error=True` を返し、メッセージが `content` に入ります。モデルはそれを読み、再試行できます。これがデフォルトです。
|
||||
* ツールの中で **`ToolError`** を送出する → 呼び出しは `is_error=True` を返し、メッセージが `content` に入ります。モデルはそれを読み、再試行できます。
|
||||
* **`MCPError`** を送出する → 呼び出しそのものが JSON-RPC エラーで失敗します。モデルには何も見えず、ホストが対処します。`code`、`message`、`data` はそのまま残ります。
|
||||
* 決め手の問い：「もっと賢いモデルならこれを避けられたか」。はい → 例外。いいえ → `MCPError`。
|
||||
* 決め手の問い：「もっと賢いモデルならこれを避けられたか」。はい → `ToolError`。いいえ → `MCPError`。
|
||||
* **その他の例外**はクラッシュ → モデルには `Error executing tool <name>` とだけ書かれた `is_error=True`、サーバー側にはトレースバック付きの `ERROR` レコードが残ります。
|
||||
* リソースのハンドラーから `ResourceNotFoundError` を送出する → プロトコルの `-32602` になり、URI が `data` に入ります。
|
||||
* 不正な引数は関数が実行される前にスキーマと照合して拒否されます。そのために `raise` する必要はありません。
|
||||
* `from mcp import MCPError` でインポートします。エラーコードの定数は `mcp.types` から取得します。
|
||||
* インポート：`from mcp import MCPError`、`from mcp.server.mcpserver.exceptions import ToolError, ResourceError, ResourceNotFoundError`、そしてエラーコードの定数は `mcp.types` から取得します。
|
||||
|
||||
エラーの処理はここまでです。サーバーが「公開する」ものはこれですべてです。すべてのハンドラーが実行中に読み取れるもの、そして実行中にクライアントに対して行えることは、次のセクション **[ハンドラーの中で](../handlers/index.md)** で扱います。
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [496394d24d221bf1, 4ceb4591180dc6c3, 0fd63e4682d02e0c, 969ede0bd3686a16, 043f526230dd243d, 6ee3e9bcfd24047a]
|
||||
sections: [496394d24d221bf1, 4ceb4591180dc6c3, 0fd63e4682d02e0c, 969ede0bd3686a16, 864137b5e9c61e91, 043f526230dd243d, db1ef91db7d6b3f3]
|
||||
tool: 1
|
||||
---
|
||||
# メディア {#media}
|
||||
|
|
@ -81,6 +81,24 @@ result.structured_content # None
|
|||
!!! check
|
||||
`data=` の場合はファイル名がないので、推測する材料がありません。`format=` を忘れると、SDK はデフォルトにフォールバックします。画像なら `image/png`、音声なら `audio/wav` です。この方法で MP3 のバイト列から `Audio` を作ると、クライアントには `mime_type="audio/wav"` と伝えられ、それを忠実に信じてデコードに失敗します。`data=` を渡すときは `format=` も渡してください。
|
||||
|
||||
## リソースを埋め込む {#embedding-a-resource}
|
||||
|
||||
ツールはドキュメントを返すこともできます。テキストまたはバイト列に、それが置かれている URI と MIME タイプを添えたものです。これが **`EmbeddedResource`** で、コンテンツブロックのもう 1 つの種類です。単純な `str` と違い、コンテンツが何であるかをクライアントに伝えるので、クライアントはそれを添付ファイルとして表示したり、すでに知っているリソースだと認識したりできます。
|
||||
|
||||
```python title="server.py" hl_lines="7 14 16-18"
|
||||
--8<-- "docs_src/media/tutorial005.py"
|
||||
```
|
||||
|
||||
* `brand://guidelines` は普通のリソースです（リソースについては **[リソース](resources.md)** で扱います）。このツールはリクエストに応じて同じドキュメントをモデルに渡します。`guidelines()` を直接呼び出すことで、情報源を 1 つに保っています。
|
||||
* `EmbeddedResource` と `TextResourceContents` は `mcp.types` にあります。画像のようなヘルパーはありません。組み立てたブロックはそのまま結果に入り、`structured_content` はありません。
|
||||
* リソースを登録したときの URI を使ってください。そうすれば、添付ファイルと `brand://guidelines` が同じドキュメントだとクライアントが判断できます。登録されているかどうかにかかわらず、どんな URI でも有効です。
|
||||
|
||||
```python
|
||||
result.content # [EmbeddedResource(type="resource", resource=TextResourceContents(uri="brand://guidelines", mime_type="text/markdown", text="# Brand guidelines\n\n..."))]
|
||||
```
|
||||
|
||||
バイナリのコンテンツには、`TextResourceContents` の代わりに `BlobResourceContents(uri=..., mime_type=..., blob=...)` を使い、バイト列を base64 エンコードして `blob` に入れます。クライアントが後で `resources/read` できるポインターだけを送りたい場合は、代わりに `ResourceLink(name=..., uri=...)` を返してください。これもコンテンツブロックです。
|
||||
|
||||
## アイコン {#icons}
|
||||
|
||||
`Icon` はメタデータであって、コンテンツではありません。画像そのものは運ばず、URI で画像を指し示します。クライアントはそれを取得して、サーバーの名前やツール、リソース、プロンプトの横に表示することがあります。
|
||||
|
|
@ -110,6 +128,7 @@ client.server_info.icons # [Icon(src="https://example.com/brand-kit.png", mime_
|
|||
|
||||
* ツールから `Image` または `Audio` を返すと、クライアントは `ImageContent` / `AudioContent` ブロックを受け取ります。バイト列が base64 エンコードされ、MIME タイプが付きます。
|
||||
* `path=` から作って拡張子に MIME タイプを決めさせるか、メモリ上の `data=` に明示的な `format=` を添えて作ります。
|
||||
* `EmbeddedResource` を返すとドキュメント（テキストまたは base64 の blob に、その URI と MIME タイプを添えたもの）を結果に入れられ、`ResourceLink` を返すとポインターだけを送れます。
|
||||
* メディアの結果には `structured_content` も出力スキーマもありません。
|
||||
* `Icon` はポインターです。`src` URI に、省略可能な `mime_type`、`sizes`、`theme` を加えたものです。
|
||||
* `icons=[...]` はサーバー、ツール、リソース、プロンプトのどれにも使え、クライアントは対応するオブジェクト上でそれらを見つけます。
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [d65c098f37f5b6c3, dd0c2724d6f2877e, 6835bb3570c6714c, ffe823cb0fedd488, f33651add1b59094]
|
||||
sections: [d65c098f37f5b6c3, dd0c2724d6f2877e, 6835bb3570c6714c, d30d3c20168b88b2, f5ef38dad59d6f76, 6e38a699ba57fbdf, 2b984a3bf37a0ddd]
|
||||
tool: 1
|
||||
---
|
||||
# プロンプト {#prompts}
|
||||
|
|
@ -137,7 +137,52 @@ uv run mcp dev server.py
|
|||
```
|
||||
|
||||
!!! info
|
||||
**[ツール](tools.md)** を読んでいれば、このページの内容はもうすべて知っています。同じデコレーター、同じく docstring が説明になる仕組み、同じ `Annotated`/`Field` です。変わるのは、誰が起動するか（ユーザー）と、結果がどこへ行くか（会話の中）だけです。
|
||||
**[ツール](tools.md)** を読んでいれば、ここまでの内容はもうすべて知っています。同じデコレーター、同じく docstring が説明になる仕組み、同じ `Annotated`/`Field` です。変わるのは、誰が起動するか（ユーザー）と、結果がどこへ行くか（会話の中）だけです。
|
||||
|
||||
## テキスト以外のコンテンツ {#more-than-text}
|
||||
|
||||
`UserMessage` と `AssistantMessage` は、`str` を受け取れる場所ならどこでも、コンテンツブロックや `Image` / `Audio` ヘルパーも受け取れます。プロンプトでよく出てくるケースは 2 つ、ドキュメントの添付と画像の添付です。
|
||||
|
||||
### ファイルを埋め込む {#embedding-a-file}
|
||||
|
||||
```python title="server.py" hl_lines="5 12 21 23"
|
||||
--8<-- "docs_src/prompts/tutorial004.py"
|
||||
```
|
||||
|
||||
* スタイルガイドは `style://python` にあるリソースで（リソースについては **[リソース](resources.md)** で扱います）、`server.py` の隣にある `style-guide.md` から読み込まれます。そこに任意の Markdown ファイルを置いてください。
|
||||
* `EmbeddedResource(resource=TextResourceContents(...))`（どちらも `mcp.types` にあります）は、URI と MIME タイプ付きのファイルを最初のメッセージとして運びます。そのファイルに言及するリクエストは、プレーンテキストとして後に続きます。
|
||||
* ガイドを f-string に貼り付けるのではなく埋め込むことで、クライアントはそれを添付ファイルとして表示でき、後から `style://python` を開き直せます。モデルはファイルをそのままの形で受け取ります。バイナリファイルの場合は、base64 の `blob` を持つ `BlobResourceContents` を使ってください。
|
||||
|
||||
レンダリングすると、最初のメッセージの `content` は `resource` ブロックです。
|
||||
|
||||
```json
|
||||
{"type": "resource", "resource": {"uri": "style://python", "mimeType": "text/markdown", "text": "* Prefer early returns.\n..."}}
|
||||
```
|
||||
|
||||
### 画像を添付する {#attaching-an-image}
|
||||
|
||||
```python title="server.py" hl_lines="4 15"
|
||||
--8<-- "docs_src/prompts/tutorial005.py"
|
||||
```
|
||||
|
||||
* `Image` は **[画像、音声、アイコン](media.md)** で紹介するヘルパーです。プロンプトがレンダリングされるとき、`UserMessage` はこれを `ImageContent` ブロック（ファイルは base64 エンコードされ、MIME タイプは `.png` から推測されます）に変換します。`Audio` も同じように `AudioContent` になります。
|
||||
* `server.py` の隣に `architecture.png` という名前の PNG を何か置いてください。プロンプトの引数は文字列なので、画像は常にサーバー側から来ます。`component` が与えるのは言葉だけです。
|
||||
|
||||
```json
|
||||
{"type": "image", "data": "iVBORw0KGgoAAAANSUhEUg...", "mimeType": "image/png"}
|
||||
```
|
||||
|
||||
## 実行時にリストを変更する {#changing-the-list-at-runtime}
|
||||
|
||||
プロンプトは、クライアントが接続している間にも追加できます。たとえば、ユーザーが指示を自分専用のメニュー項目として保存できるようにする場合です。プロンプトを登録してから、通知します。
|
||||
|
||||
```python title="server.py" hl_lines="5 23-27"
|
||||
--8<-- "docs_src/prompts/tutorial006.py"
|
||||
```
|
||||
|
||||
* `mcp.add_prompt(Prompt.from_function(fn, name=..., description=...))` は `@mcp.prompt()` とまったく同じように関数を登録し、`mcp.remove_prompt(name)` はその逆です。`add_prompt` は同名の既存エントリを上書きせずそのまま残すので、このツールは保存が置き換えになるよう、先に古いエントリを削除しています。`prompts/list` には変更がすぐに反映されます。
|
||||
* `await ctx.notify_prompts_changed()` は、`subscriptions/listen` ストリームで待ち受けているすべての `2026-07-28` クライアントに `notifications/prompts/list_changed` を送ります（**[サブスクリプション](../handlers/subscriptions.md)**）。`await ctx.session.send_prompt_list_changed()` は、呼び出し元のクライアントが 2026 年より前の世代のときに、そのクライアントへ送ります（**[レガシークライアントへの対応](../run/legacy-clients.md)**）。両方を呼んでください。どちらも、伝える相手がいなければ何もしません。
|
||||
* 通知を受け取ったクライアントは、もう一度 `prompts/list` を呼びます。Python の `Client` では `async with client.listen(prompts_list_changed=True) as sub:` がそれにあたり、`PromptsListChanged` イベントが届きます。
|
||||
|
||||
## まとめ {#recap}
|
||||
|
||||
|
|
@ -147,5 +192,7 @@ uv run mcp dev server.py
|
|||
* `str` を返すと 1 つのユーザーメッセージになります。`UserMessage` / `AssistantMessage` のリストを返すと、複数ターンの会話の出発点を用意できます。
|
||||
* `title=` と `Field(description=...)` は、クライアントが UI に表示するものです。
|
||||
* 必須の引数が欠けていると、リクエスト全体が失敗します。プロンプト単位のエラー結果はありません。
|
||||
* `EmbeddedResource` や `Image` を `UserMessage` でラップすると、ドキュメントや画像を添付できます。
|
||||
* 実行時にプロンプトを追加・削除するには `mcp.add_prompt(...)` / `mcp.remove_prompt(...)` を使い、その後 `await ctx.notify_prompts_changed()` と `await ctx.session.send_prompt_list_changed()` を呼びます。
|
||||
|
||||
プロンプト（やリソーステンプレート）の引数をサーバー側でオートコンプリートする機能については、**[補完](completions.md)** を参照してください。
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [a838d57f003aed44, 857d03886a0137ed, 42d9efcb9f542867, 2290ff08435b5573, e866c192e11d1c14, 6cdbad079f7b47f0, d4b607372fb28b51, 18dbf726ac45e0b7, c6f7d2a148aa49f4, c851964bb3301907, d715db6f8dccc9cc, ef86634aa70498a7]
|
||||
sections: [a838d57f003aed44, 857d03886a0137ed, 42d9efcb9f542867, 2290ff08435b5573, 91be9b73602abcf1, 6cdbad079f7b47f0, d4b607372fb28b51, 18dbf726ac45e0b7, c7eff2a5698225fa, c851964bb3301907, 8f296f1f09e4c400, d715db6f8dccc9cc, a0c344a48450dbe4]
|
||||
tool: 1
|
||||
---
|
||||
# 構造化出力 {#structured-output}
|
||||
|
|
@ -103,7 +103,7 @@ result.structured_content # {"temperature": 16.2, "humidity": 0.83, "conditions
|
|||
--8<-- "docs_src/structured_output/tutorial003.py"
|
||||
```
|
||||
|
||||
`TypedDict` は実行時にはただの `dict` なので、組み立てて返すのもそれです。スキーマもバリデーションも `structured_content` も、`BaseModel` 版と同一です（説明だけは付きません。`TypedDict` には説明を書く場所がないからです）。
|
||||
`TypedDict` は実行時にはただの `dict` なので、組み立てて返すのもそれです。スキーマもバリデーションも `structured_content` も、`BaseModel` 版と同じルールに従います。クラスの docstring や `Annotated[..., Field(description=...)]` を足せばそれが説明になり、dict に入れなかった `NotRequired` のキーは `structured_content` にも入りません。
|
||||
|
||||
## データクラス {#a-dataclass}
|
||||
|
||||
|
|
@ -185,16 +185,16 @@ result.structured_content # {"London": 16.2, "Reykjavik": 4.4}
|
|||
アノテーションは `WeatherData` を約束しています。ところが、上流のレスポンスが `humidity` を送ってこなくなりました。
|
||||
|
||||
!!! check
|
||||
`get_weather` を呼び出しても、中身が半分欠けたオブジェクトがこっそりクライアントに渡ることはありません。呼び出しは失敗し、エラーの冒頭の数行にそのフィールド名が示されます。
|
||||
`get_weather` を呼び出しても、中身が半分欠けたオブジェクトがこっそりクライアントに渡ることはありません。呼び出しは失敗します。クライアントは `Error executing tool get_weather` とともに `is_error=True` を受け取るので、モデルは、ありもしない天気を自信満々に読み上げる代わりに、呼び出しが失敗したと分かります。フィールド名は開発者向けに、サーバーログの `ERROR` レベルに出力されます。
|
||||
|
||||
```text
|
||||
Error executing tool get_weather: 1 validation error for WeatherData
|
||||
Tool 'get_weather' raised an unexpected exception
|
||||
...
|
||||
pydantic_core._pydantic_core.ValidationError: 1 validation error for WeatherData
|
||||
humidity
|
||||
Field required [type=missing, input_value={'temperature': 16.2, 'conditions': 'Overcast'}, input_type=dict]
|
||||
```
|
||||
|
||||
このテキストは `is_error=True` の付いたツール結果として返ってくるので、モデルは、ありもしない天気を自信満々に読み上げる代わりに、呼び出しが失敗したと分かります。
|
||||
|
||||
ちなみに、`-> WeatherData` のツールから単なる `dict` を返してもかまいません。`json.loads` が返したのはまさにそれです。バリデーションの対象は Python の型ではなく、値です。
|
||||
|
||||
## オプトアウト {#opting-out}
|
||||
|
|
@ -209,6 +209,10 @@ result.structured_content # {"London": 16.2, "Reykjavik": 4.4}
|
|||
|
||||
その逆の `structured_output=True` は、自動検出を必須要件に変えます。戻り値の型からスキーマを作れないツールは、テキストにフォールバックするのではなく、インポート時に例外を送出します。
|
||||
|
||||
## コンテンツブロックとメディア {#content-blocks-and-media}
|
||||
|
||||
コンテンツブロックとメディア（`TextContent`、`EmbeddedResource`、`Image`、`Audio` など）は、何もしなくてもオプトアウトされます。単体で返しても、`list`、`tuple`、`Sequence` の要素にしても、ユニオンの一方にしても同じです。これらはモデルが読むためのものなので、自動検出はそこからスキーマを導き出しません（`Image` と `Audio` については **[画像、音声、アイコン](media.md)** で扱っています）。それでも `structured_output=True` を渡せば、コンテンツブロックのクラスにはスキーマが強制されます。
|
||||
|
||||
## 型ヒントのないクラス {#a-class-without-type-hints}
|
||||
|
||||
頼んでもいないのに非構造化になってしまう道が 1 つだけあります。**本体にアノテーションが 1 つもない**クラスを返すことです。
|
||||
|
|
@ -237,6 +241,6 @@ result.structured_content # {"London": 16.2, "Reykjavik": 4.4}
|
|||
* スカラー、リスト、タプル、ユニオンは `{"result": ...}` でラップされます。モデル、`TypedDict`、データクラス、アノテーション付きクラス、`dict[str, ...]` はもともとオブジェクトなので、そのままです。
|
||||
* どの結果も `content`（モデル向けのテキスト）**と** `structured_content`（アプリケーション向けのデータ）の両方を持ちます。
|
||||
* 返したものはスキーマに照らして検証されます。食い違いは壊れた結果ではなく、ツールエラーになります。
|
||||
* `structured_output=False` を渡すと、そのツールはオプトアウトします。型ヒントのないクラスは黙ってオプトアウトするので、気をつけてください。
|
||||
* `structured_output=False` を渡すと、そのツールはオプトアウトします。コンテンツブロック、`Image`、`Audio` はデフォルトでオプトアウトします。型ヒントのないクラスは黙ってオプトアウトするので、気をつけてください。
|
||||
|
||||
これで、ツールが返せるものはすべて押さえました。次は 2 つ目のプリミティブ、**[リソース](resources.md)** です。
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [e4cc390d56573409, 8566e2b68594e9ad, 2c97b9f888398951, 048e5471dfa71aea, 3076b1e16ad95950, edbedf2a16e71311, 3d8ef8da89fa87c1, f6c0e02e6ea5a363]
|
||||
sections: [e4cc390d56573409, f30cf8103a6e918c, 2c97b9f888398951, 048e5471dfa71aea, 3076b1e16ad95950, edbedf2a16e71311, 3d8ef8da89fa87c1, f6c0e02e6ea5a363]
|
||||
tool: 1
|
||||
---
|
||||
# ツール {#tools}
|
||||
|
|
@ -39,6 +39,8 @@ SDK はこれらの型ヒントから JSON Schema を生成し、`tools/list`
|
|||
|
||||
どちらの引数にもデフォルト値がないため、両方とも `required` に入っています。これはすぐ後で直します。（`title` キーは Pydantic が生成した付随物です。契約にあたるのは、プロパティとその型、そして `required` です。）
|
||||
|
||||
`$schema` キーもありません。MCP はこのキーのないスキーマを **JSON Schema 2020-12** として扱い、Pydantic が生成するのもまさにこの形式です。そのため、**[低レベル Server](../advanced/low-level-server.md#the-dialect-is-json-schema-2020-12)** でスキーマを手書きするようになるまで、選ぶべきものは何もありません。
|
||||
|
||||
!!! tip
|
||||
ここでの型ヒントはドキュメントではありません。**契約そのもの**です。クライアントが `"limit": "ten"` を送ってきても、関数が実行される前に SDK が拒否します。
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [4a7033e1ed8ad602, 55dcbfff0c6271bf, 101ef9d14bf4ec46, 4b6c4a845438abc7, f98b46bafbee4acd]
|
||||
sections: [4a7033e1ed8ad602, 55dcbfff0c6271bf, 317f4256a650cab6, 4b6c4a845438abc7, f98b46bafbee4acd]
|
||||
tool: 1
|
||||
---
|
||||
# URI テンプレートとパスの安全性 {#uri-templates-and-path-safety}
|
||||
|
|
@ -98,7 +98,7 @@ SDK はハンドラーの実行前に、次のいずれかに当てはまるパ
|
|||
|
||||
組み込みのチェックはよくあるケースを止めますが、サンドボックスの境界までは知りようがありません。ファイルシステムにアクセスする場合は、`safe_join` を使ってパスを解決し、ベースディレクトリの内側に収まっていることを検証してください。
|
||||
|
||||
```python title="server.py" hl_lines="4 14"
|
||||
```python title="server.py" hl_lines="5 15"
|
||||
--8<-- "docs_src/uri_templates/tutorial002.py"
|
||||
```
|
||||
|
||||
|
|
@ -127,7 +127,7 @@ SDK はハンドラーの実行前に、次のいずれかに当てはまるパ
|
|||
これらのチェックはヒューリスティックな事前フィルターです。ファイルシステムへのアクセスでは、依然として `safe_join` が封じ込めの境界です。
|
||||
|
||||
!!! tip
|
||||
ハンドラーがリクエストに応えられない場合（ファイルが存在しない、ID が不明など）は、例外を送出してください。SDK がそれをエラーレスポンスに変換します。プロトコルエラーとツールエラーの違いについては、**[エラーの処理](handling-errors.md)** を参照してください。
|
||||
ハンドラーがリクエストに応えられない場合（ファイルが存在しない、ID が不明など）は、上の `read_manual` と同じように `ResourceNotFoundError` を送出してください。クライアントには、指定したメッセージと URI を含む `-32602` が返ります。想定外の例外は、代わりに汎用の `-32603` になります。**[エラーの処理](handling-errors.md#a-resource-that-doesnt-exist)** を参照してください。
|
||||
|
||||
## 低レベル Server でのリソース {#resources-on-the-low-level-server}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue