docs: publish translated docs in twelve languages and the tool that maintains them (#3280)
This commit is contained in:
Max
GitHub
parent
14aa889992
commit
52ad0a8876
1 changed files with 89737 additions and 54 deletions
139
i18n/ja/pages/get-started/first-steps.md
Normal file
139
i18n/ja/pages/get-started/first-steps.md
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
---
|
||||
translation:
|
||||
sections: [0d6c05bcbf836bf3, 59a7b14eeefc68c1, 7114d8d6daba203f, e8bbb56a98ba7bc9, 5138010f6159901c, f78da7c7c363d4c6, 220a939cab348686]
|
||||
tool: 1
|
||||
---
|
||||
# 最初のステップ {#first-steps}
|
||||
|
||||
**[トップページ](../index.md)** は駆け足です。サーバーを書き、実行し、ツールを呼び出します。
|
||||
|
||||
このページではじっくり進めます。サーバーが公開できる 3 種類のものをすべて取り上げ、途中で出てくるものすべてに名前を付けていきます。
|
||||
|
||||
## ホスト、クライアント、サーバー {#host-client-and-server}
|
||||
|
||||
ここから先、どのページにも登場する言葉が 3 つあります。
|
||||
|
||||
* **ホスト**は LLM アプリケーションです。Claude、IDE、エージェントランタイムなどがこれにあたります。ユーザーが対話している相手です。
|
||||
* **クライアント**はホストの中にあり、MCP を話します。ホストは、接続するサーバーごとにクライアントを 1 つずつ動かします。
|
||||
* **サーバー**は、この SDK で作るものです。クライアントに対して何かを公開します。モデルと直接やり取りすることは決してありません。
|
||||
|
||||
自分で書くのはサーバーです。ホストは別の誰かが作る製品です。SDK には `Client` も用意されています。サーバーのテストに使うもので、このページの後半にも登場します。
|
||||
|
||||
## 3 つのプリミティブ {#the-three-primitives}
|
||||
|
||||
サーバーが公開するものは、ちょうど 3 種類です。それらを分けるのは、**誰が使うと決めるのか**という点です。
|
||||
|
||||
| プリミティブ | 制御する主体 | どんなものか | 例 |
|
||||
|---------------|-----------------|-----------------------------------------------------|------------------------------------|
|
||||
| **ツール** | モデル | アクションを起こすためにモデルが呼び出す関数 | API 呼び出し、データベースへの書き込み |
|
||||
| **リソース** | アプリケーション | ホストがモデルのコンテキストに読み込むデータ | ファイルの内容、API のレスポンス |
|
||||
| **プロンプト** | ユーザー | ユーザーが名前で呼び出す、再利用可能なメッセージテンプレート | スラッシュコマンド、メニュー項目 |
|
||||
|
||||
「制御する主体」こそが、この区分の核心です。ツールが実行されるのは、**モデル**が呼び出すと決めたからです。リソースが添付されるのは、**アプリケーション**がモデルに必要だと判断したからです。プロンプトが実行されるのは、**ユーザー**が選んだからです。
|
||||
|
||||
!!! info
|
||||
Web API を作ったことがあれば、勘どころはもうほとんどつかめています。**リソース**は `GET`（データを読み込み、何も変更しない）で、**ツール**は `POST`（処理を行い、副作用を持つことがある）です。**プロンプト**に HTTP の対応物はありません。ユーザーが名前を指定して実行する、保存済みのクエリに近いものです。
|
||||
|
||||
## 1 つのサーバーで 3 つすべて {#one-server-all-three}
|
||||
|
||||
```python title="server.py" hl_lines="6 12 18"
|
||||
--8<-- "docs_src/first_steps/tutorial001.py"
|
||||
```
|
||||
|
||||
ごく普通の関数が 3 つ、デコレーターが 3 つです。どのデコレーターも、それだけで登録が完結します。
|
||||
|
||||
* `@mcp.tool()` は `add` を**ツール**にします。
|
||||
* `@mcp.resource("greeting://{name}")` は `greeting` を**リソーステンプレート**にします。URI の中の `{name}` が関数のパラメーターです。
|
||||
* `@mcp.prompt()` は `summarize` を**プロンプト**にします。返した文字列がユーザーメッセージになります。
|
||||
|
||||
それ以外のもの（名前、説明、引数のスキーマ）は、SDK が関数そのものから読み取ります。関数名、docstring、型ヒントからです。どれも別途宣言してはいません。
|
||||
|
||||
!!! tip
|
||||
SDK の 2 つの半分には、インポートパスも 2 つあります。`from mcp import Client` と `from mcp.server import MCPServer` です。`from mcp import MCPServer` はありません。
|
||||
|
||||
### 試してみる {#try-it}
|
||||
|
||||
MCP Inspector で実行してください。
|
||||
|
||||
```console
|
||||
uv run mcp dev server.py
|
||||
```
|
||||
|
||||
出力された URL を開いてください。Inspector にはプリミティブごとにタブが 1 つずつあります。順に見ていきましょう。
|
||||
|
||||
**Tools** タブには項目が 1 つあります。`add` で、説明は *Add two numbers.* です。フォームには必須の整数フィールドが 2 つあり、1 つは `a` 用、もう 1 つは `b` 用です。値を入力して呼び出すと、結果は `3` です。Inspector はこのフォームを `a: int, b: int` から組み立てました。ほかのどのクライアントも同じことをします。
|
||||
|
||||
**Resources** タブでは、*Resources* の一覧は空です。`greeting` は **Resource Templates** の下にあります。`greeting://{name}` にはパラメーターがあり、誰かが `name` を指定するまでは一覧に載せられる単体のリソースが存在しないからです。`World` を指定して読み取ると、こう返ってきます。
|
||||
|
||||
```text
|
||||
Hello, World!
|
||||
```
|
||||
|
||||
**Prompts** タブにも項目が 1 つあります。`summarize` で、必須の引数 `text` を 1 つだけ取ります。適当なテキストを渡して取得すると、`role: user` を持ち、レンダリングされた文字列を内容とするメッセージが 1 つ返ってきます。プロンプトとはそれだけのものです。メッセージを組み立てる関数にすぎません。
|
||||
|
||||
Inspector はサーバーを **stdio** で実行しました。MCP サーバーが話せるトランスポートの 1 つです。トランスポートを選ぶのはまだ先で、そのためのページが **[サーバーの実行](../run/index.md)** です。
|
||||
|
||||
## ケイパビリティ {#capabilities}
|
||||
|
||||
Inspector にはタブが 3 つありました。3 つあると、どうやってわかったのでしょうか。
|
||||
|
||||
クライアントが接続すると、サーバーは自身の**ケイパビリティ**を宣言します。どの系統のリクエストに応答するか、ということです。クライアントはこの宣言をもとに、そもそも何を要求するかを決めます。この宣言を自分で書いてはいません。`MCPServer` が代わりに宣言します。
|
||||
|
||||
自分の目で確かめてみましょう。SDK の `Client` はサーバーオブジェクトをそのまま受け取り、**インメモリ**で接続します（サブプロセスもポートも使いません）。
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
from mcp import Client
|
||||
|
||||
from server import mcp
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
async with Client(mcp) as client:
|
||||
print(client.server_capabilities.model_dump(exclude_none=True))
|
||||
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
```text
|
||||
{'prompts': {'list_changed': True}, 'resources': {'subscribe': True, 'list_changed': True}, 'tools': {'list_changed': True}}
|
||||
```
|
||||
|
||||
この辞書が、サーバーが宣言した**ケイパビリティ**です。接続してくるどのクライアントも、最初にこれを知ります。
|
||||
|
||||
| ケイパビリティ | クライアントが呼び出せるようになるもの |
|
||||
|-------------|------------------------------------------------------------|
|
||||
| `tools` | `tools/list`, `tools/call` |
|
||||
| `resources` | `resources/list`, `resources/templates/list`, `resources/read` |
|
||||
| `prompts` | `prompts/list`, `prompts/get` |
|
||||
|
||||
`MCPServer` は 3 つのプリミティブすべてを提供するので、3 つとも常に宣言されます。
|
||||
|
||||
ここにないものにも注目してください。`completions`（リソーステンプレートとプロンプトの引数の自動補完）には自分で書くハンドラーが必要ですが、このサーバーにはありません。そのためこのケイパビリティは宣言されず、行儀のよいクライアントなら要求もしません。オプションのものはすべてこのルールに従います。登録すればケイパビリティが現れます。**[補完](../servers/completions.md)** のページがそれを実証しています。
|
||||
|
||||
!!! info
|
||||
`Client(mcp)` は、このドキュメントのすべてのサンプルをテストしているのと同じインメモリクライアントで、自分のサーバーをテストするときにもこれを使います。まるごと 1 ページを割いています。**[テスト](testing.md)** です。
|
||||
|
||||
## 書かなかったもの {#what-you-did-not-write}
|
||||
|
||||
このページを振り返ってみてください。書いたのは小さな Python 関数 3 つです。次のものは書いて**いません**。
|
||||
|
||||
* JSON Schema。`a: int, b: int` がそのまま `add` のスキーマです。
|
||||
* リクエストハンドラー。`tools/list`、`resources/read`、`prompts/get` は、すべて代わりに処理されます。
|
||||
* ケイパビリティの宣言。`MCPServer` が代わりに作りました。
|
||||
* プロトコルのコードを 1 行も。バージョンのネゴシエーション、JSON-RPC のフレーミング、ケイパビリティの交換は、すべて `mcp dev` と `Client(mcp)` の内部で行われ、目にすることはありませんでした。
|
||||
|
||||
この比率こそが、この SDK の存在意義です。
|
||||
|
||||
## まとめ {#recap}
|
||||
|
||||
* **ホスト**は LLM アプリ、**クライアント**はそのうち MCP を話す部分、**サーバー**は自分で作るものです。
|
||||
* ツールは**モデル**が、リソースは**アプリケーション**が、プロンプトは**ユーザー**が制御します。
|
||||
* デコレーターはプリミティブごとに 1 つです。`@mcp.tool()`、`@mcp.resource(uri)`、`@mcp.prompt()`。名前、説明、スキーマは関数から取られます。
|
||||
* `{param}` を含む URI はリソース**テンプレート**を作り、具体的なリソースとは別に一覧表示されます。
|
||||
* サーバーの**ケイパビリティ**は代わりに宣言され、クライアントはサーバーが宣言したものだけを要求します。
|
||||
* `Client(mcp)` はサーバーオブジェクトにインメモリで接続します。初日から使えるテストハーネスです。
|
||||
|
||||
次は **[実際のホストに接続する](real-host.md)** です。このサーバーを Claude Desktop や IDE の中で、本当に動かします。その次は **[テスト](testing.md)** です。1 ページ、インメモリクライアント 1 つで、動くかどうかを当て推量することはもうありません。そのあとは各プリミティブに専用のページがあり、まずはモデルが動かすもの、**[ツール](../servers/tools.md)** から始まります。
|
||||
Loading…
Reference in a new issue