From 7bc369a12809459a186a84e227c621b6b9e96514 Mon Sep 17 00:00:00 2001 From: Kazuhiro Sera Date: Thu, 12 Jun 2025 09:51:20 +0900 Subject: [PATCH] Give more clarity to MCP docs and improve ja translation --- docs/src/content/docs/guides/mcp.mdx | 6 +-- docs/src/content/docs/ja/guides/mcp.mdx | 56 ++++++++++++------------- docs/src/scripts/translate.ts | 1 + 3 files changed, 32 insertions(+), 31 deletions(-) diff --git a/docs/src/content/docs/guides/mcp.mdx b/docs/src/content/docs/guides/mcp.mdx index 73ce7131..f55e9c71 100644 --- a/docs/src/content/docs/guides/mcp.mdx +++ b/docs/src/content/docs/guides/mcp.mdx @@ -17,7 +17,7 @@ The [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) is an op There are three types of MCP servers this SDK supports: -1. **Hosted MCP‑server tools** – remote MCP servers used as tools by the [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) +1. **Hosted MCP server tools** – remote MCP servers used as tools by the [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) 2. **Streamable HTTP MCP servers** – local or remote servers that implement the [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) 3. **Stdio MCP servers** – servers accessed via standard input/output (the simplest option) @@ -28,7 +28,7 @@ Choose a server type based on your use‑case: | Call publicly accessible remote servers with default OpenAI responses models | **1. Hosted MCP tools** | | Use publicly accessible remote servers but have the tool calls triggered locally | **2. Streamable HTTP** | | Use locally running Streamable HTTP servers | **2. Streamable HTTP** | -| Use any Streamable HTTP servers with non-OpenAI Responses models | **2. Streamable HTTP** | +| Use any Streamable HTTP servers with non-OpenAI-Responses models | **2. Streamable HTTP** | | Work with local MCP servers that only support the standard-I/O protocol | **3. Stdio** | ## 1. Hosted MCP server tools @@ -67,7 +67,7 @@ If you can programatically determine whether a tool call is safe, you can use th title="Human in the loop with hosted MCP tools" /> -Fully working samples (streaming, approval, HITL) are [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) in our GitHub repository. +Fully working samples (Hosted tools/Streamable HTTP/stdio + Streaming, HITL, onApproval) are [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) in our GitHub repository. ## 2. Streamable HTTP MCP servers diff --git a/docs/src/content/docs/ja/guides/mcp.mdx b/docs/src/content/docs/ja/guides/mcp.mdx index ee87145b..6c4699c0 100644 --- a/docs/src/content/docs/ja/guides/mcp.mdx +++ b/docs/src/content/docs/ja/guides/mcp.mdx @@ -11,35 +11,35 @@ import hostedHITLExample from '../../../../../../examples/docs/mcp/hostedHITL.ts import streamableHttpExample from '../../../../../../examples/docs/mcp/streamableHttp.ts?raw'; import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw'; -[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP ドキュメントより引用します。 +[** Model Context Protocol ( MCP ) **](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP ドキュメントでは次のように説明されています。 -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーション向けの USB-C ポートのようなものと考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリーに接続するための標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続するための標準化された方法を提供します。 +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP を AI アプリケーション向けの USB-C ポートと考えてください。USB-C がデバイスをさまざまな周辺機器に接続するための標準化された方法を提供するのと同様に、MCP は AI モデルを複数のデータソースやツールに接続するための標準化された方法を提供します。 -この SDK がサポートする MCP サーバーには次の 3 種類があります。 +この SDK がサポートする MCP サーバーは次の 3 種類です。 -1. **Hosted MCP-server tools** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) によりツールとして呼び出されるリモート MCP サーバー -2. **Streamable HTTP MCP サーバー** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装したローカルまたはリモートサーバー -3. **Stdio MCP サーバー** – 標準入力/出力経由でアクセスするサーバー（もっともシンプル） +1. **リモート MCP サーバーツール（Hosted）** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) がツールとして利用するリモート MCP サーバー +2. **Streamable HTTP MCP サーバー** – [Streamable HTTP トランスポート](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装したローカルまたはリモートサーバー +3. **Stdio MCP サーバー** – 標準入力 / 出力経由でアクセスするサーバー（最もシンプルなオプション） ユースケースに応じてサーバータイプを選択してください。 -| 必要なこと | 推奨オプション | -| ---------------------------------------------------------------------------------------- | ----------------------- | -| 公開アクセス可能なリモートサーバーを、デフォルトの OpenAI Responses モデルで呼び出したい | **1. Hosted MCP tools** | -| 公開アクセス可能なリモートサーバーを使用しつつ、ツール呼び出しをローカルでトリガーしたい | **2. Streamable HTTP** | -| ローカルで動作する Streamable HTTP サーバーを使用したい | **2. Streamable HTTP** | -| OpenAI 以外の Responses モデルと組み合わせて任意の Streamable HTTP サーバーを使いたい | **2. Streamable HTTP** | -| 標準 I/O プロトコルのみをサポートするローカル MCP サーバーと連携したい | **3. Stdio** | +| 必要なもの | 推奨オプション | +| -------------------------------------------------------------------------------------------- | -------------------------------------------- | +| 公開アクセス可能なリモートサーバーを既定の OpenAI Responses モデルで呼び出したい | **1. リモート MCP サーバーツール（Hosted）** | +| 公開アクセス可能なリモートサーバーを利用するが、ツール呼び出し自体はローカルでトリガーしたい | **2. Streamable HTTP** | +| ローカルで動作する Streamable HTTP サーバーを利用したい | **2. Streamable HTTP** | +| OpenAI Responses 以外のモデルで任意の Streamable HTTP サーバーを利用したい | **2. Streamable HTTP** | +| 標準 I/O プロトコルのみをサポートするローカル MCP サーバーを利用したい | **3. Stdio** | -## 1. Hosted MCP サーバーツール +## 1. リモート MCP サーバーツール（Hosted） -Hosted tool では、往復すべてがモデル内部で完結します。あなたのコードが MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートツールのエンドポイントを呼び出し、その結果をストリームでモデルに返します。 +Hosted ツールでは、往復処理をすべてモデル内部で完結させます。コードから MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートツールのエンドポイントを呼び出し、その結果をストリーミングでモデルに返します。 -Hosted MCP サーバーツールを使うもっともシンプルな例を示します。`hostedMcpTool` ユーティリティ関数にリモート MCP サーバーのラベルと URL を渡すだけで作成できます。 +Hosted MCP ツールを利用する最も簡単な例を以下に示します。`hostedMcpTool` ユーティリティ関数にリモート MCP サーバーのラベルと URL を渡して、Hosted MCP サーバーツールを作成します。 -続いて、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）でエージェントを実行します。 +次に、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）でエージェントを実行します。 -MCP の増分結果をストリーミングする場合は、`Agent` を実行するときに `stream: true` を渡してください。 +増分的な MCP 実行結果をストリームで受け取りたい場合は、`Agent` を実行するときに `stream: true` を渡します。 -ストリーミング、承認、HITL を含む完全な動作例は GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 +完全な動作例（Hosted ツール / Streamable HTTP / stdio + Streaming, HITL, onApproval）は GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 ## 2. Streamable HTTP MCP サーバー -エージェントがローカルまたはリモートの Streamable HTTP MCP サーバーと直接通信する場合は、サーバーの `url`、`name`、オプション設定を指定して `MCPServerStreamableHttp` を生成します。 +エージェントがローカルまたはリモートの Streamable HTTP MCP サーバーに直接接続する場合は、サーバーの `url`、`name` と任意の設定を渡して `MCPServerStreamableHttp` をインスタンス化します。 -コンストラクターでは `authProvider`, `requestInit`, `reconnectionOptions`, `sessionId` など、MCP TypeScript SDK の追加オプションも指定できます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントをご覧ください。 +コンストラクタは `authProvider`、`requestInit`、`reconnectionOptions`、`sessionId` などの MCP TypeScript-SDK 追加オプションも受け取ります。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) のドキュメントを参照してください。 ## 3. Stdio MCP サーバー -標準 I/O のみを公開するサーバーには、`fullCommand` を指定して `MCPServerStdio` を生成します。 +標準 I/O だけを公開しているサーバーには、`fullCommand` を渡して `MCPServerStdio` をインスタンス化します。 -## 知っておくべきその他のポイント +## その他のポイント -**Streamable HTTP** および **Stdio** サーバーの場合、`Agent` は実行のたびに利用可能なツールを確認するため `list_tools()` を呼び出すことがあります。この往復は、特にリモートサーバーではレイテンシーを増やす可能性があります。ツールリストが変わらないと確信できる場合は、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡して結果をメモリにキャッシュできます。 +**Streamable HTTP** および **Stdio** サーバーの場合、`Agent` が実行されるたびに使用可能なツールを確認するために `list_tools()` を呼び出すことがあります。この往復処理は、特にリモートサーバーではレイテンシーを増加させるため、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡すことで結果をメモリにキャッシュできます。 -後からキャッシュを無効化したい場合は、サーバーインスタンスの `invalidateToolsCache()` を呼び出してください。 +ツール一覧が変更されないと確信できる場合にのみ有効化してください。後でキャッシュを無効化するには、サーバーインスタンスの `invalidateToolsCache()` を呼び出します。 -## 参考文献 +## さらに学ぶ - [Model Context Protocol](https://modelcontextprotocol.io/) – 公式仕様 - [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) – 上記で参照した実行可能デモ diff --git a/docs/src/scripts/translate.ts b/docs/src/scripts/translate.ts index 261ce60d..24f7f75b 100644 --- a/docs/src/scripts/translate.ts +++ b/docs/src/scripts/translate.ts @@ -168,6 +168,7 @@ const engToNonEngMapping: Record> = { 'TypeScript-first': 'TypeScript ファースト', 'Human in the loop': 'Human in the loop (人間の介入)', 'Hosted tool': '組み込みツール（Hosted）', + 'Hosted MCP server tools': 'リモート MCP サーバーツール（Hosted）', raw: '元', }, };