Skip to content

Commit 534d867

Browse files
silverhand-botxiaoyijun
silverhand-bot
and
xiaoyijun
authored
chore: update translations and generated content (#46)
Co-authored-by: xiaoyijun <10806653+xiaoyijun@users.noreply.github.com>
1 parent bcd1230 commit 534d867

File tree

416 files changed

+43683
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

416 files changed

+43683
-0
lines changed

‎i18n/de/docusaurus-plugin-content-docs/current/README.mdx

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
sidebar_position: 1
3+
sidebar_label: Erste Schritte
4+
---
5+
6+
import TabItem from '@theme/TabItem';
7+
import Tabs from '@theme/Tabs';
8+
9+
# Erste Schritte
10+
11+
## Wähle einen kompatiblen OAuth 2.1- oder OpenID Connect-Anbieter \{#choose-a-compatible-oauth-2-1-or-openid-connect-provider}
12+
13+
Die MCP-Spezifikation hat einige [spezifische Anforderungen](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#1-3-standards-compliance) für die Autorisierung:
14+
15+
- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)
16+
- OAuth 2.0 Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414))
17+
- OAuth 2.0 Dynamic Client Registration Protocol ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591))
18+
19+
Während die letzten beiden nicht zwingend erforderlich sind, ist die erste notwendig, um eine sichere und konforme Implementierung zu gewährleisten.
20+
21+
:::note
22+
Im neuen MCP-Entwurf wird RFC 8414 für Autorisierungsserver (Anbieter) verpflichtend sein. Wir werden die Dokumentation aktualisieren, sobald der neue Entwurf finalisiert ist.
23+
:::
24+
25+
Du kannst die [Liste der MCP-kompatiblen Anbieter](./provider-list.mdx) prüfen, um zu sehen, ob dein Anbieter unterstützt wird.
26+
27+
## Installiere MCP Auth SDK \{#install-mcp-auth-sdk}
28+
29+
MCP Auth ist sowohl für Python als auch für TypeScript verfügbar. Lass uns wissen, wenn du Unterstützung für eine andere Sprache oder ein anderes Framework benötigst!
30+
31+
<Tabs groupId="sdk">
32+
<TabItem value="python" label="Python">
33+
34+
```bash
35+
pip install mcpauth
36+
```
37+
38+
Oder ein anderer Paketmanager deiner Wahl, wie pipenv oder poetry.
39+
40+
</TabItem>
41+
<TabItem value="node" label="Node.js">
42+
43+
```bash
44+
npm install mcp-auth
45+
```
46+
47+
Oder ein anderer Paketmanager deiner Wahl, wie pnpm oder yarn.
48+
49+
</TabItem>
50+
</Tabs>
51+
52+
## Initialisiere MCP Auth \{#init-mcp-auth}
53+
54+
Der erste Schritt ist die Initialisierung der MCP Auth-Instanz mit den Metadaten deines Anbieter-Autorisierungsservers. Wenn dein Anbieter eine der folgenden Spezifikationen unterstützt:
55+
56+
- [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414)
57+
- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)
58+
59+
kannst du die eingebaute Funktion verwenden, um die Metadaten abzurufen und die MCP Auth-Instanz zu initialisieren:
60+
61+
<Tabs groupId="sdk">
62+
<TabItem value="python" label="Python">
63+
64+
```python
65+
from mcpauth import MCPAuth
66+
from mcpauth.config import AuthServerType
67+
from mcpauth.utils import fetch_server_config
68+
69+
mcp_auth = MCPAuth(
70+
server=fetch_server_config(
71+
'<auth-server-url>',
72+
type=AuthServerType.OIDC # oder AuthServerType.OAUTH
73+
)
74+
)
75+
```
76+
77+
</TabItem>
78+
<TabItem value="node" label="Node.js">
79+
80+
```ts
81+
import { MCPAuth, fetchServerConfig } from 'mcp-auth';
82+
83+
const mcpAuth = new MCPAuth({
84+
server: await fetchServerConfig('<auth-server-issuer>', { type: 'oidc' }), // oder 'oauth'
85+
});
86+
```
87+
88+
</TabItem>
89+
</Tabs>
90+
91+
Wenn du die Metadaten-URL oder Endpunkte manuell angeben musst, siehe [Weitere Möglichkeiten zur Initialisierung von MCP Auth](./configure-server/mcp-auth.mdx#other-ways).
92+
93+
## Binde den Metadaten-Endpunkt ein \{#mount-the-metadata-endpoint}
94+
95+
Um der aktuellen MCP-Spezifikation zu entsprechen, bindet MCP Auth den OAuth 2.0 Authorization Server Metadata-Endpunkt (`/.well-known/oauth-authorization-server`) in deinen MCP-Server ein:
96+
97+
<Tabs groupId="sdk">
98+
<TabItem value="python" label="Python">
99+
100+
```python
101+
from starlette.applications import Starlette
102+
103+
app = Starlette(routes=[
104+
mcp_auth.metadata_route(),
105+
])
106+
```
107+
108+
</TabItem>
109+
<TabItem value="node" label="Node.js">
110+
111+
```ts
112+
import express from 'express';
113+
114+
const app = express();
115+
app.use(mcpAuth.delegatedRouter());
116+
```
117+
118+
</TabItem>
119+
</Tabs>
120+
121+
Die URLs in den Metadaten bleiben unverändert, sodass die Rolle des Autorisierungsservers vollständig an den Anbieter delegiert wird. Du kannst den Metadaten-Endpunkt testen, indem du `/.well-known/oauth-authorization-server` in deinem MCP-Server aufrufst.
122+
123+
### Warum nur der Metadaten-Endpunkt? \{#why-only-the-metadata-endpoint}
124+
125+
Du wirst vielleicht sehen, dass die offiziellen SDKs einen Auth-Router bereitstellen, der Autorisierungsendpunkte wie `/authorize`, `/token` usw. einbindet. Hier ist der Grund, warum wir das nicht tun:
126+
127+
1. Nur den Metadaten-Endpunkt einzubinden, ermöglicht es dir, die vollen Fähigkeiten deines Anbieters zu nutzen, ohne das Rad neu zu erfinden und unnötige Komplexität in deinen MCP-Server zu bringen.
128+
2. Es gibt außerdem Bestrebungen, die [Rolle des MCP-Servers zu einem Ressourcenserver zu verschieben](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205) und OAuth 2.0 Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)) zu verlangen. Das bedeutet, dass der MCP-Server **keine Autorisierungslogik mehr übernimmt** (einschließlich des Metadaten-Endpunkts), sondern nur noch als Ressourcenserver dient, der sich für Authentifizierung und Autorisierung auf den Anbieter verlässt.
129+
130+
:::note
131+
Wir werden MCP Auth aktualisieren, um die neue MCP-Spezifikation zu unterstützen, sobald sie finalisiert ist. In der Zwischenzeit kannst du die aktuelle Version verwenden, die mit der aktuellen Spezifikation kompatibel ist.
132+
:::
133+
134+
## Verwende das Bearer-Auth-Middleware \{#use-the-bearer-auth-middleware}
135+
136+
Sobald die MCP Auth-Instanz initialisiert ist, kannst du das Bearer-Auth-Middleware anwenden, um deine MCP-Routen zu schützen:
137+
138+
<Tabs groupId="sdk">
139+
<TabItem value="python" label="Python">
140+
141+
```python
142+
from starlette.applications import Starlette
143+
from starlette.middleware import Middleware
144+
from starlette.routing import Mount
145+
from mcpauth import MCPAuth
146+
from mcp.server.fastmcp import FastMCP
147+
148+
mcp = FastMCP()
149+
mcp_auth = MCPAuth(
150+
# Initialisiere mit deiner Auth-Server-Konfiguration
151+
)
152+
bearer_auth = mcp_auth.bearer_auth_middleware(
153+
"jwt", required_scopes=["read", "write"]
154+
)
155+
156+
app = Starlette(routes=[
157+
mcp_auth.metadata_route(),
158+
Mount(
159+
"/",
160+
app=mcp.sse_app(),
161+
middleware=[Middleware(bearer_auth)],
162+
),
163+
])
164+
```
165+
166+
</TabItem>
167+
<TabItem value="node" label="Node.js">
168+
169+
```ts
170+
import express from 'express';
171+
import { MCPAuth } from 'mcp-auth';
172+
173+
const app = express();
174+
const server = new McpServer(/* ... */);
175+
const mcpAuth = new MCPAuth({
176+
/* ... */
177+
});
178+
179+
app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));
180+
```
181+
182+
</TabItem>
183+
</Tabs>
184+
185+
Im obigen Beispiel haben wir den Token-Typ `jwt` angegeben und die Berechtigungen `read` und `write` gefordert. Es wird automatisch das JWT (JSON Web Token) validieren und ein Objekt mit den Informationen des authentifizierten Benutzers befüllen.
186+
187+
:::info
188+
Noch nie von JWT (JSON Web Token) gehört? Keine Sorge, du kannst die Dokumentation einfach weiterlesen – wir erklären es, wenn es nötig ist. Du kannst auch das [Auth Wiki](https://auth.wiki/jwt) für eine kurze Einführung besuchen.
189+
:::
190+
191+
Weitere Informationen zur Bearer-Auth-Konfiguration findest du unter [Bearer-Auth konfigurieren](./configure-server/bearer-auth.mdx).
192+
193+
## Auth-Informationen in deiner MCP-Implementierung abrufen \{#retrieve-the-auth-info-in-your-mcp-implementation}
194+
195+
Sobald das Bearer-Auth-Middleware angewendet ist, kannst du auf die Informationen des authentifizierten Benutzers (oder der Identität) in deiner MCP-Implementierung zugreifen:
196+
197+
<Tabs groupId="sdk">
198+
<TabItem value="python" label="Python">
199+
200+
MCP Auth speichert die Informationen des authentifizierten Benutzers nach erfolgreicher Authentifizierung in einer Kontextvariablen, sobald das Bearer-Auth-Middleware angewendet wurde. Du kannst darauf in deinen MCP-Tool-Handlern wie folgt zugreifen:
201+
202+
```python
203+
from mcp.server.fastmcp import FastMCP
204+
205+
mcp = FastMCP()
206+
mcp_auth = MCPAuth(
207+
# Initialisiere mit deiner Auth-Server-Konfiguration
208+
)
209+
210+
@mcp.tool()
211+
def add(a: int, b: int):
212+
"""
213+
Ein Tool, das zwei Zahlen addiert.
214+
Die Informationen des authentifizierten Benutzers sind im Kontext verfügbar.
215+
"""
216+
auth_info = mcp_auth.auth_info # Zugriff auf die Auth-Informationen im aktuellen Kontext
217+
if auth_info:
218+
print(f"Authentifizierter Benutzer: {auth_info.claims}")
219+
return a + b
220+
```
221+
222+
</TabItem>
223+
<TabItem value="node" label="Node.js">
224+
225+
Das zweite Argument des Tool-Handlers enthält das `authInfo`-Objekt, das die Informationen des authentifizierten Benutzers enthält:
226+
227+
```ts
228+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
229+
import { z } from 'zod';
230+
231+
const server = new McpServer(/* ... */);
232+
server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => {
233+
// Jetzt kannst du das `authInfo`-Objekt verwenden, um auf die authentifizierten Informationen zuzugreifen
234+
});
235+
```
236+
237+
</TabItem>
238+
</Tabs>
239+
240+
## Nächste Schritte \{#next-steps}
241+
242+
Lies weiter, um ein End-to-End-Beispiel zu erfahren, wie du MCP Auth mit deinem MCP-Server integrierst und wie du den Auth-Flow in MCP-Clients handhabst.

‎i18n/de/docusaurus-plugin-content-docs/current/comparison.mdx

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
sidebar_position: 101
3+
sidebar_label: Vergleich
4+
---
5+
6+
# Entscheidung zwischen MCP Auth und anderen Lösungen
7+
8+
Das MCP-Ökosystem entwickelt sich weiter. Während sich die Model Context Protocol (MCP) Spezifikation vom „Autorisierungsserver“-Ansatz hin zum neuen Modell „Ressourcenserver + Drittanbieter-IdP“ bewegt, ist es wichtig zu verstehen, wie verschiedene Integrationslösungen jetzt und in Zukunft passen.
9+
10+
Diese Seite zeigt die wichtigsten Unterschiede zwischen mcp-auth und anderen beliebten Lösungen auf, um dir bei der Wahl des besten Ansatzes für dein Projekt zu helfen.
11+
12+
## Hintergrund: Proxy-Ansatz vs. IdP-Integration \{#background-proxy-approach-vs-idp-integration}
13+
14+
Die meisten bestehenden MCP Auth-Lösungen verwenden einen „Proxy-Ansatz“. In diesem Modell leitet der MCP-Server Autorisierungsanfragen an einen Drittanbieter-Identitätsanbieter (IdP) weiter und fungiert damit effektiv als Vermittler zwischen dem Client und dem IdP.
15+
16+
**Proxy-Ansatz ([03-26 Spezifikation](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization))**
17+
18+
```mermaid
19+
sequenceDiagram
20+
participant Client
21+
participant MCP_Server as MCP-Server
22+
participant ThirdParty_IdP as Drittanbieter-IdP
23+
24+
Client->>MCP_Server: Autorisierungsanfrage
25+
MCP_Server->>ThirdParty_IdP: Leitet Anfrage weiter
26+
ThirdParty_IdP->>MCP_Server: Antwort
27+
MCP_Server->>Client: Antwort
28+
Client->>MCP_Server: Zugriff auf Ressource
29+
alt Remote-Validierung
30+
MCP_Server->>ThirdParty_IdP: Token validieren
31+
ThirdParty_IdP->>MCP_Server: Token gültig
32+
else Lokale Validierung
33+
MCP_Server->>MCP_Server: Token lokal validieren (z. B. zwischengespeicherter JWK)
34+
end
35+
MCP_Server->>Client: Ressourcendaten
36+
```
37+
38+
Obwohl dies mit der aktuellen (2025-03-26) MCP-Spezifikation funktioniert, ist es im Grunde ein Workaround. Es wird davon ausgegangen, dass der MCP-Server auch als Autorisierungsserver fungiert, was jedoch nicht der Richtung der neuesten Entwurfsspezifikation entspricht.
39+
40+
**MCP Auth / zukünftige Spezifikation (Ressourcenserver + Drittanbieter-IdP)**
41+
42+
```mermaid
43+
sequenceDiagram
44+
participant Client
45+
participant MCP_Server as MCP-Server
46+
participant ThirdParty_IdP as Drittanbieter-IdP
47+
48+
Client->>ThirdParty_IdP: Autorisierungsanfrage
49+
ThirdParty_IdP->>Client: Token
50+
Client->>MCP_Server: Zugriff auf Ressource (mit Token)
51+
alt Remote-Validierung
52+
MCP_Server->>ThirdParty_IdP: Token validieren
53+
ThirdParty_IdP->>MCP_Server: Token gültig
54+
else Lokale Validierung
55+
MCP_Server->>MCP_Server: Token lokal validieren (z. B. zwischengespeicherter JWK)
56+
end
57+
MCP_Server->>Client: Ressourcendaten
58+
```
59+
60+
Die kommende MCP-Spezifikation [verlagert die Verantwortung für die Autorisierung auf einen dedizierten Drittanbieter-IdP](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205). In diesem Modell dient der MCP-Server nur noch als Ressourcenserver, und alle Autorisierungsendpunkte kommen direkt vom Drittanbieter-IdP.
61+
62+
## Warum MCP Auth wählen? \{#why-choose-mcp-auth}
63+
64+
- Spezifikationskonformität: MCP Auth folgt direkt der Richtung des neuesten Entwurfs und ist damit die einzige Lösung, die sowohl mit der 03-26-Spezifikation als auch mit der kommenden Spezifikation kompatibel ist.
65+
- Keine Workarounds mehr: Anstatt als Proxy für den Autorisierungsserver zu agieren, überlässt MCP Auth dem Drittanbieter-IdP die gesamte Autorisierung, wie in der neuen Spezifikation vorgesehen.
66+
- Anbieterunabhängig: MCP Auth funktioniert mit jedem standardkonformen OAuth 2.0 / OIDC-Anbieter.
67+
- Reibungsloser Übergang: MCP Auth gibt alle Drittanbieter-Endpunkte unverändert über OAuth 2.0 Authorization Server Metadata zurück. Das hält die Integration jetzt einfach und macht sie bereit für zukünftige Änderungen.
68+
- Entwicklererfahrung: Bietet Tutorials, Hilfsprogramme und kommende Funktionen wie [OAuth 2.0 Protected Resource Metadata](https://auth.wiki/protected-resource-metadata), um das Leben für MCP-Server-Entwickler zu erleichtern.
69+
70+
| Funktion | Proxy-Lösungen | MCP Auth |
71+
| ---------------------------------- | -------------------- | -------- |
72+
| Funktioniert mit 03-26-Spezifikation | ✅ | ✅ |
73+
| Funktioniert mit zukünftiger Spezifikation | ❌ | ✅ |
74+
| Unterstützt Drittanbieter-IdPs direkt | ❌ (nur Workaround) | ✅ |
75+
| Anbieterunabhängig | Eingeschränkt[^1] | Ja |
76+
| Übergangsbereit | ❌ | ✅ |
77+
78+
Wenn du jetzt Drittanbieter-IdPs unterstützen musst und für die kommende Spezifikation bereit sein willst, ist MCP Auth die empfohlene Lösung. Proxy-basierte Ansätze könnten bald veraltet sein oder eine umfassende Überarbeitung erfordern.
79+
80+
[^1]: Einige Proxy-Lösungen können bestimmte Parameter oder Endpunkte fest einprogrammieren, was die Flexibilität einschränkt.

0 commit comments

Comments
 (0)