mcp-auth · xiaoyijun · Jun 3, 2025 · Jun 3, 2025
diff --git a/i18n/de/docusaurus-plugin-content-docs/current/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/README.mdx
@@ -0,0 +1,242 @@
+---
+sidebar_position: 1
+sidebar_label: Erste Schritte
+---
+
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+# Erste Schritte
+
+## Wähle einen kompatiblen OAuth 2.1- oder OpenID Connect-Anbieter \{#choose-a-compatible-oauth-2-1-or-openid-connect-provider}
+
+Die MCP-Spezifikation hat einige [spezifische Anforderungen](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#1-3-standards-compliance) für die Autorisierung:
+
+- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)
+- OAuth 2.0 Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414))
+- OAuth 2.0 Dynamic Client Registration Protocol ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591))
+
+Während die letzten beiden nicht zwingend erforderlich sind, ist die erste notwendig, um eine sichere und konforme Implementierung zu gewährleisten.
+
+:::note
+Im neuen MCP-Entwurf wird RFC 8414 für Autorisierungsserver (Anbieter) verpflichtend sein. Wir werden die Dokumentation aktualisieren, sobald der neue Entwurf finalisiert ist.
+:::
+
+Du kannst die [Liste der MCP-kompatiblen Anbieter](./provider-list.mdx) prüfen, um zu sehen, ob dein Anbieter unterstützt wird.
+
+## Installiere MCP Auth SDK \{#install-mcp-auth-sdk}
+
+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!
+
+<Tabs groupId="sdk">
+<TabItem value="python" label="Python">
+
+```bash
+pip install mcpauth
+```
+
+Oder ein anderer Paketmanager deiner Wahl, wie pipenv oder poetry.
+
+</TabItem>
+<TabItem value="node" label="Node.js">
+
+```bash
+npm install mcp-auth
+```
+
+Oder ein anderer Paketmanager deiner Wahl, wie pnpm oder yarn.
+
+</TabItem>
+</Tabs>
+
+## Initialisiere MCP Auth \{#init-mcp-auth}
+
+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:
+
+- [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414)
+- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)
+
+kannst du die eingebaute Funktion verwenden, um die Metadaten abzurufen und die MCP Auth-Instanz zu initialisieren:
+
+<Tabs groupId="sdk">
+<TabItem value="python" label="Python">
+
+```python
+from mcpauth import MCPAuth
+from mcpauth.config import AuthServerType
+from mcpauth.utils import fetch_server_config
+
+mcp_auth = MCPAuth(
+    server=fetch_server_config(
+      '<auth-server-url>',
+      type=AuthServerType.OIDC # oder AuthServerType.OAUTH
+    )
+)
+```
+
+</TabItem>
+<TabItem value="node" label="Node.js">
+
+```ts
+import { MCPAuth, fetchServerConfig } from 'mcp-auth';
+
+const mcpAuth = new MCPAuth({
+  server: await fetchServerConfig('<auth-server-issuer>', { type: 'oidc' }), // oder 'oauth'
+});
+```
+
+</TabItem>
+</Tabs>
+
+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).
+
+## Binde den Metadaten-Endpunkt ein \{#mount-the-metadata-endpoint}
+
+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:
+
+<Tabs groupId="sdk">
+<TabItem value="python" label="Python">
+
+```python
+from starlette.applications import Starlette
+
+app = Starlette(routes=[
+    mcp_auth.metadata_route(),
+])
+```
+
+</TabItem>
+<TabItem value="node" label="Node.js">
+
+```ts
+import express from 'express';
+
+const app = express();
+app.use(mcpAuth.delegatedRouter());
+```
+
+</TabItem>
+</Tabs>
+
+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.
+
+### Warum nur der Metadaten-Endpunkt? \{#why-only-the-metadata-endpoint}
+
+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:
+
+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.
+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.
+
+:::note
+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.
+:::
+
+## Verwende das Bearer-Auth-Middleware \{#use-the-bearer-auth-middleware}
+
+Sobald die MCP Auth-Instanz initialisiert ist, kannst du das Bearer-Auth-Middleware anwenden, um deine MCP-Routen zu schützen:
+
+<Tabs groupId="sdk">
+<TabItem value="python" label="Python">
+
+```python
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.routing import Mount
+from mcpauth import MCPAuth
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP()
+mcp_auth = MCPAuth(
+  # Initialisiere mit deiner Auth-Server-Konfiguration
+)
+bearer_auth = mcp_auth.bearer_auth_middleware(
+    "jwt", required_scopes=["read", "write"]
+)
+
+app = Starlette(routes=[
+    mcp_auth.metadata_route(),
+    Mount(
+        "/",
+        app=mcp.sse_app(),
+        middleware=[Middleware(bearer_auth)],
+    ),
+])
+```
+
+</TabItem>
+<TabItem value="node" label="Node.js">
+
+```ts
+import express from 'express';
+import { MCPAuth } from 'mcp-auth';
+
+const app = express();
+const server = new McpServer(/* ... */);
+const mcpAuth = new MCPAuth({
+  /* ... */
+});
+
+app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));
+```
+
+</TabItem>
+</Tabs>
+
+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.
+
+:::info
+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.
+:::
+
+Weitere Informationen zur Bearer-Auth-Konfiguration findest du unter [Bearer-Auth konfigurieren](./configure-server/bearer-auth.mdx).
+
+## Auth-Informationen in deiner MCP-Implementierung abrufen \{#retrieve-the-auth-info-in-your-mcp-implementation}
+
+Sobald das Bearer-Auth-Middleware angewendet ist, kannst du auf die Informationen des authentifizierten Benutzers (oder der Identität) in deiner MCP-Implementierung zugreifen:
+
+<Tabs groupId="sdk">
+<TabItem value="python" label="Python">
+
+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:
+
+```python
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP()
+mcp_auth = MCPAuth(
+  # Initialisiere mit deiner Auth-Server-Konfiguration
+)
+
+@mcp.tool()
+def add(a: int, b: int):
+    """
+    Ein Tool, das zwei Zahlen addiert.
+    Die Informationen des authentifizierten Benutzers sind im Kontext verfügbar.
+    """
+    auth_info = mcp_auth.auth_info # Zugriff auf die Auth-Informationen im aktuellen Kontext
+    if auth_info:
+        print(f"Authentifizierter Benutzer: {auth_info.claims}")
+    return a + b
+```
+
+</TabItem>
+<TabItem value="node" label="Node.js">
+
+Das zweite Argument des Tool-Handlers enthält das `authInfo`-Objekt, das die Informationen des authentifizierten Benutzers enthält:
+
+```ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+const server = new McpServer(/* ... */);
+server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => {
+  // Jetzt kannst du das `authInfo`-Objekt verwenden, um auf die authentifizierten Informationen zuzugreifen
+});
+```
+
+</TabItem>
+</Tabs>
+
+## Nächste Schritte \{#next-steps}
+
+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.
diff --git a/i18n/de/docusaurus-plugin-content-docs/current/comparison.mdx b/i18n/de/docusaurus-plugin-content-docs/current/comparison.mdx
@@ -0,0 +1,80 @@
+---
+sidebar_position: 101
+sidebar_label: Vergleich
+---
+
+# Entscheidung zwischen MCP Auth und anderen Lösungen
+
+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.
+
+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.
+
+## Hintergrund: Proxy-Ansatz vs. IdP-Integration \{#background-proxy-approach-vs-idp-integration}
+
+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.
+
+**Proxy-Ansatz ([03-26 Spezifikation](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization))**
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant MCP_Server as MCP-Server
+    participant ThirdParty_IdP as Drittanbieter-IdP
+
+    Client->>MCP_Server: Autorisierungsanfrage
+    MCP_Server->>ThirdParty_IdP: Leitet Anfrage weiter
+    ThirdParty_IdP->>MCP_Server: Antwort
+    MCP_Server->>Client: Antwort
+    Client->>MCP_Server: Zugriff auf Ressource
+    alt Remote-Validierung
+        MCP_Server->>ThirdParty_IdP: Token validieren
+        ThirdParty_IdP->>MCP_Server: Token gültig
+    else Lokale Validierung
+        MCP_Server->>MCP_Server: Token lokal validieren (z. B. zwischengespeicherter JWK)
+    end
+    MCP_Server->>Client: Ressourcendaten
+```
+
+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.
+
+**MCP Auth / zukünftige Spezifikation (Ressourcenserver + Drittanbieter-IdP)**
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant MCP_Server as MCP-Server
+    participant ThirdParty_IdP as Drittanbieter-IdP
+
+    Client->>ThirdParty_IdP: Autorisierungsanfrage
+    ThirdParty_IdP->>Client: Token
+    Client->>MCP_Server: Zugriff auf Ressource (mit Token)
+    alt Remote-Validierung
+        MCP_Server->>ThirdParty_IdP: Token validieren
+        ThirdParty_IdP->>MCP_Server: Token gültig
+    else Lokale Validierung
+        MCP_Server->>MCP_Server: Token lokal validieren (z. B. zwischengespeicherter JWK)
+    end
+    MCP_Server->>Client: Ressourcendaten
+```
+
+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.
+
+## Warum MCP Auth wählen? \{#why-choose-mcp-auth}
+
+- 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.
+- 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.
+- Anbieterunabhängig: MCP Auth funktioniert mit jedem standardkonformen OAuth 2.0 / OIDC-Anbieter.
+- 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.
+- 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.
+
+| Funktion                           | Proxy-Lösungen       | MCP Auth |
+| ---------------------------------- | -------------------- | -------- |
+| Funktioniert mit 03-26-Spezifikation | ✅                   | ✅       |
+| Funktioniert mit zukünftiger Spezifikation | ❌                   | ✅       |
+| Unterstützt Drittanbieter-IdPs direkt | ❌ (nur Workaround)  | ✅       |
+| Anbieterunabhängig                 | Eingeschränkt[^1]    | Ja       |
+| Übergangsbereit                    | ❌                   | ✅       |
+
+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.
+
+[^1]: Einige Proxy-Lösungen können bestimmte Parameter oder Endpunkte fest einprogrammieren, was die Flexibilität einschränkt.