-
Notifications
You must be signed in to change notification settings - Fork 4k
docs: refresh translations for recent English changes #3636
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+2,996
−510
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| --- | ||
| translation: | ||
| sections: [81862a209b483d27, b76e8073487afa03, bc214b2fc2bcdae4, d5835477c0b60163, a5d9786f902ad8e1] | ||
| tool: 1 | ||
| --- | ||
| # Header-Parameter {#header-parameters} | ||
|
|
||
| Die meisten Server brauchen das nie. | ||
|
|
||
| Ein Gateway oder Load Balancer vor deinem Server kann nur anhand dessen routen, was er lesen kann, ohne den Body zu parsen. Markiere ein Tool-Argument mit `x-mcp-header`, und Clients mit der **[Protokollversion](../protocol-versions.md)** `2026-07-28` senden seinen Wert zusätzlich als HTTP-Header. | ||
|
|
||
| ## Ein Argument markieren {#mark-an-argument} | ||
|
|
||
| Die Markierung ist ein zusätzlicher Schlüssel im JSON Schema des Arguments. Bei `MCPServer` setzt `Field` ihn dort: | ||
|
|
||
| ```python title="server.py" hl_lines="13" | ||
| --8<-- "docs_src/header_parameters/tutorial001.py" | ||
| ``` | ||
|
|
||
| * Über Streamable HTTP mit `2026-07-28` sendet ein Client `Mcp-Param-Region` zusätzlich zum Body, und der Server lehnt einen Aufruf ab, bei dem beide nicht übereinstimmen. | ||
| * Ein Client, der das Tool nicht aufgelistet hat, hat die Markierung nie gesehen: Er sendet keinen Header, und der Aufruf wird abgelehnt. Der `Client` dieses SDK listet dann die Tools auf und sendet den Aufruf einmal erneut. Vorher aufzulisten spart also nur einen Roundtrip. | ||
| * Jede andere Verbindung ignoriert die Annotation. | ||
|
|
||
| Deine Funktion ändert sich nicht: `region` kommt weiterhin als Argument an. | ||
|
|
||
| ## Was sich markieren lässt {#what-can-be-marked} | ||
|
|
||
| Argumente vom Typ `str`, `int` und `bool`. Alles andere wird beim Registrieren des Tools mit `InvalidSignature` abgewiesen. | ||
|
|
||
| Das gilt auch für `str | None`, das keinen einzelnen Typ hat. Ein optionales Argument braucht ein ausgeschriebenes Schema, mit `WithJsonSchema` von Pydantic: | ||
|
|
||
| ```python | ||
| region: Annotated[str | None, WithJsonSchema({"type": "string", "x-mcp-header": "Region"})] = None | ||
| ``` | ||
|
|
||
| ## Beim Low-Level-`Server` {#on-the-low-level-server} | ||
|
|
||
| Dort schreibst du `input_schema` von Hand, der Schlüssel kommt also direkt hinein: | ||
|
|
||
| ```python title="server.py" hl_lines="18" | ||
| --8<-- "docs_src/header_parameters/tutorial002.py" | ||
| ``` | ||
|
|
||
| * Nichts prüft die Annotation für dich: Eine ungültige wird ausgeliefert, und `2026-07-28`-Clients lassen das Tool aus ihrer Auflistung weg. | ||
|
|
||
| ### Schemas nach Namen {#schemas-by-name} | ||
|
|
||
| Um den Header zu prüfen, braucht das SDK das Eingabeschema des Tools, bevor es den Aufruf weiterleitet. Ohne `get_tool_input_schema` holt es sich das Schema, indem es bei jedem Aufruf mit Argumenten deinen `on_list_tools`-Handler ausführt – egal, ob überhaupt ein Tool markiert ist. | ||
|
|
||
| ```python title="server.py" hl_lines="26 39-41 48" | ||
| --8<-- "docs_src/header_parameters/tutorial003.py" | ||
| ``` | ||
|
|
||
| * Übergib die Funktion, um aus dem zu antworten, was du schon hast. | ||
| * Gib `None` für ein Tool zurück, bei dem es nichts zu prüfen gibt. | ||
|
|
||
| ## Zusammenfassung {#recap} | ||
|
|
||
| * `x-mcp-header` an einem Tool-Argument sorgt dafür, dass `2026-07-28`-Clients es als HTTP-Header `Mcp-Param-*` wiederholen. | ||
| * Der Server lehnt einen Aufruf ab, bei dem Header und Body nicht übereinstimmen. | ||
| * Nur Argumente vom Typ `str`, `int` und `bool` lassen sich markieren. Bei allem anderen löst `MCPServer` `InvalidSignature` aus. | ||
| * Der Low-Level-`Server` prüft nichts, und Clients verwerfen ein Tool mit ungültiger Annotation. | ||
| * `get_tool_input_schema` verhindert, dass der Low-Level-`Server` bei jedem Aufruf `on_list_tools` ausführt. | ||
|
|
||
| Der Rest der handgeschriebenen `Server`-API steht in **[Der Low-Level-Server](low-level-server.md)**. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,6 +1,6 @@ | ||||||
| --- | ||||||
| translation: | ||||||
| sections: [9cac816674181eb0, 7c157764133fea1f, 40b4916d82eaf1d4, 10d151f2cc75317f, 3d0832f39b0d7059, 92742ba36533633d, 0aeca6145e7bd302] | ||||||
| sections: [9cac816674181eb0, 5619e950d206e6c8, 40b4916d82eaf1d4, 10d151f2cc75317f, 3d0832f39b0d7059, 92742ba36533633d, 991c10e47fda2636] | ||||||
| tool: 1 | ||||||
| --- | ||||||
| # Client-Transporte {#client-transports} | ||||||
|
|
@@ -44,23 +44,41 @@ Zwei Dinge fallen auf: | |||||
| * Der `httpx2.AsyncClient` gehört dir, also betrittst und verlässt **du** ihn. Das SDK schließt nie einen Client, den es nicht selbst erzeugt hat. | ||||||
| * `streamable_http_client(url, http_client=...)` gibt einen Transport zurück, und `Client(transport)` nimmt ihn an wie alles andere auch. | ||||||
|
|
||||||
| Behalte das `timeout=` bei. Es ist dasselbe, das der SDK-eigene Client verwendet (30 Sekunden, 300 für Lesevorgänge); ein `httpx2.AsyncClient`, der ohne gebaut wird, bekommt den 5-Sekunden-Standardwert von `httpx2`, und ein Tool-Aufruf, der länger läuft, schlägt mit einem Read-Timeout fehl. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. P3: „ein Prompt for AI agents
Suggested change
|
||||||
|
|
||||||
| Eine Anmerkung zu TLS: `httpx2` prüft Zertifikate gegen den Trust Store des Betriebssystems (über | ||||||
| [`truststore`](https://pypi.org/project/truststore/)), nicht gegen eine mitgelieferte CA-Liste. In einer Umgebung ohne | ||||||
| nutzbaren System-CA-Store (manche minimalen Container) setzt du die Standard-Umgebungsvariablen `SSL_CERT_FILE`/`SSL_CERT_DIR` | ||||||
| oder übergibst deinem `httpx2.AsyncClient` ein explizites `verify=ssl_context` | ||||||
| (Hintergrund in | ||||||
| [`httpx` und `httpx-sse` durch `httpx2` ersetzt](../migration.md#httpx-and-httpx-sse-replaced-by-httpx2)). | ||||||
|
|
||||||
| ### Größere SSE-Events {#larger-sse-events} | ||||||
|
|
||||||
| Übergib `max_sse_event_size`, wenn ein Server ein großes Tool-Ergebnis oder eine große Benachrichtigung in einem einzigen SSE-Event sendet: | ||||||
|
|
||||||
| ```python title="client.py" hl_lines="6-9" | ||||||
| --8<-- "docs_src/client_transports/tutorial005.py" | ||||||
| ``` | ||||||
|
|
||||||
| Der Standardwert ist 1 MiB pro Event, gemessen in Bytes, bevor das Event geparst wird. Das Limit gilt für | ||||||
| POST-Responses, den GET-Stream und wiederaufgenommene Streams. Ein zu großes Event in einer POST-Response oder einem | ||||||
| wiederaufgenommenen Stream lässt diesen Request mit einem SSE-Fehler fehlschlagen. Beim GET-Stream im Hintergrund loggt | ||||||
| der Client den Fehler und startet den Stream neu. Setze `max_sse_event_size=None`, um die Obergrenze abzuschalten, wenn du dem | ||||||
| Server vertraust und größere Events brauchst. JSON-Responses sind nicht betroffen. Wenn du `ClientSessionGroup` verwendest, setze | ||||||
| dieselbe Option an `StreamableHttpParameters`. | ||||||
|
|
||||||
| !!! warning | ||||||
| `streamable_http_client` nahm früher `headers=` und `timeout=` direkt entgegen. Das tut er nicht mehr: | ||||||
| seine einzigen Parameter sind `url`, `http_client` und `terminate_on_close`. Greifst du aus | ||||||
| Seine Parameter sind `url`, `http_client`, `terminate_on_close` und `max_sse_event_size`. Greifst du aus | ||||||
| Gewohnheit zu `headers=`, bekommst du: | ||||||
|
|
||||||
| ```text | ||||||
| TypeError: streamable_http_client() got an unexpected keyword argument 'headers' | ||||||
| ``` | ||||||
|
|
||||||
| Alles, was mit HTTP zu tun hat, lebt jetzt auf dem einen `httpx2.AsyncClient`, den du übergibst. | ||||||
| Header, Authentifizierung, Proxys und Timeouts leben auf dem einen `httpx2.AsyncClient`, den du übergibst. | ||||||
| `max_sse_event_size` gilt dagegen für die SSE-Reader des MCP-Transports. | ||||||
|
|
||||||
| !!! info | ||||||
| `httpx2` behält die vertraute `httpx`-API bei. Wenn du `httpx` kennst, weißt du hier also bereits, wie Auth, | ||||||
|
|
@@ -137,6 +155,7 @@ Ein **Transport** ist ein beliebiger asynchroner Kontextmanager, der ein `(read, | |||||
|
|
||||||
| * `Client("http://.../mcp")` (eine URL) verbindet über Streamable HTTP, den Produktions-Transport. | ||||||
| * Header, Auth, Proxys und Timeouts gehören auf einen `httpx2.AsyncClient`, den du an `streamable_http_client(url, http_client=...)` übergibst. Es gibt kein Keyword `headers=`. | ||||||
| * Verwende `streamable_http_client(url, max_sse_event_size=...)`, um das Byte-Limit für jedes SSE-Event zu ändern. | ||||||
| * Redirects wird nur innerhalb des eigenen Origins der URL gefolgt (ein Trailing-Slash-`307`/`308`), plus `http`→`https` auf demselben Host. Alles andere schlägt mit `Redirect to … not followed` fehl; konfiguriere die endgültige URL. | ||||||
| * stdio ist `Client(StdioServerParameters(...))`. Pack es nur dann selbst in `stdio_client(...)` ein, wenn du die stderr des Kindprozesses umleiten willst. | ||||||
| * Der Subprozess bekommt eine Umgebung per Allow-List, nicht deine; `env=` ergänzt sie. | ||||||
|
|
||||||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P2:
um aus dem zu antwortenis not idiomatic German and makes this instruction unclear. Usedie auf Grundlage dessen antwortet, was du schon hastinstead.Prompt for AI agents