diff --git a/i18n/de/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigError.md b/i18n/de/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigError.md index 23fbbdd..9cf5cbd 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigError.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigError.md @@ -12,7 +12,7 @@ type AuthServerConfigError = { }; ``` -Repräsentiert einen Fehler, der während der Validierung der Metadaten des Autorisierungsservers auftritt. +Repräsentiert einen Fehler, der während der Validierung der Metadaten des Autorisierungsservers (authorization server) auftritt. ## Eigenschaften {#properties} diff --git a/i18n/de/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index 574aaad..2402859 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -3,6 +3,7 @@ sidebar_position: 2 sidebar_label: 'Tutorial: Baue einen Todo-Manager' --- +import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -17,19 +18,20 @@ In diesem Tutorial bauen wir einen Todo-Manager-MCP-Server mit Benutzer-Authenti Nach Abschluss dieses Tutorials hast du: - ✅ Ein grundlegendes Verständnis, wie du rollenbasierte Zugangskontrolle (RBAC) in deinem MCP-Server einrichtest. -- ✅ Einen MCP-Server, der als Ressourcenserver fungiert und Zugangstokens akzeptiert, die von einem Autorisierungsserver ausgestellt wurden. +- ✅ Einen MCP-Server, der als Ressourcenserver agiert und Zugangstokens akzeptiert, die von einem Autorisierungsserver ausgestellt wurden. - ✅ Eine funktionierende Implementierung der durch Berechtigungen gesteuerten Zugriffskontrolle für Todo-Operationen. ## Überblick \{#overview} Das Tutorial umfasst folgende Komponenten: -- **MCP-Client (MCP Inspector)**: Ein visuelles Test-Tool für MCP-Server, das als OAuth 2.0/OIDC-Client agiert. Es startet den Autorisierungs-Flow mit dem Autorisierungsserver und erhält Zugangstokens, um Anfragen an den MCP-Server zu authentifizieren. +- **MCP-Client (VS Code)**: Ein Code-Editor mit eingebauter MCP-Unterstützung, der als OAuth 2.0/OIDC-Client agiert. Er initiiert den Autorisierungs-Flow mit dem Autorisierungsserver und erhält Zugangstokens, um Anfragen an den MCP-Server zu authentifizieren. - **Autorisierungsserver**: Ein OAuth 2.1- oder OpenID Connect-Anbieter, der Benutzeridentitäten verwaltet, Benutzer authentifiziert und Zugangstokens mit passenden Berechtigungen an autorisierte Clients ausstellt. -- **MCP-Server (Ressourcenserver)**: Nach der neuesten MCP-Spezifikation agiert der MCP-Server als Ressourcenserver im OAuth 2.0-Framework. Er validiert Zugangstokens, die vom Autorisierungsserver ausgestellt wurden, und setzt berechtigungsbasierte Berechtigungen für Todo-Operationen durch. +- **MCP-Server (Ressourcenserver)**: Nach der neuesten MCP-Spezifikation agiert der MCP-Server als Ressourcenserver im OAuth 2.0-Framework. Er validiert Zugangstokens, die vom Autorisierungsserver ausgestellt wurden, und erzwingt berechtigungsbasierte Berechtigungen für Todo-Operationen. Diese Architektur folgt dem Standard-OAuth 2.0-Flow, bei dem: -- Der **MCP Inspector** geschützte Ressourcen im Namen des Benutzers anfordert + +- **VS Code** geschützte Ressourcen im Namen des Benutzers anfordert - Der **Autorisierungsserver** den Benutzer authentifiziert und Zugangstokens ausstellt - Der **MCP-Server** Tokens validiert und geschützte Ressourcen basierend auf gewährten Berechtigungen bereitstellt @@ -38,16 +40,16 @@ Hier ist ein Überblicksdiagramm der Interaktion zwischen diesen Komponenten: ```mermaid sequenceDiagram autonumber - participant Client as MCP Inspector
(OAuth-Client) + participant Client as VS Code
(OAuth-Client) participant RS as MCP-Server
(Ressourcenserver) participant AS as Autorisierungsserver Client->>RS: MCP-Anfrage (kein Token) RS-->>Client: 401 Nicht autorisiert (WWW-Authenticate) - Note over Client: Ressourcen-Metadaten-URL extrahieren
aus WWW-Authenticate-Header + Note over Client: Extrahiere resource_metadata-URL
aus WWW-Authenticate-Header Client->>RS: GET /.well-known/oauth-protected-resource (resource_metadata) - RS-->>Client: Geschützte Ressourcen-Metadaten
(inkl. Autorisierungsserver-URL) + RS-->>Client: Geschützte Ressourcen-Metadaten
(enthält Autorisierungsserver-URL) Client->>AS: GET /.well-known/oauth-authorization-server AS-->>Client: Autorisierungsserver-Metadaten @@ -55,7 +57,7 @@ sequenceDiagram AS-->>Client: Zugangstoken Client->>RS: MCP-Anfrage (Authorization: Bearer ) - RS->>RS: Zugangstoken validieren und autorisieren + RS->>RS: Validiert Zugangstoken ist gültig und autorisiert RS-->>Client: MCP-Antwort ``` @@ -63,23 +65,23 @@ sequenceDiagram ### Zugangstokens mit Berechtigungen (Scopes) \{#access-tokens-with-scopes} -Um [rollenbasierte Zugangskontrolle (RBAC)](https://auth.wiki/rbac) in deinem MCP-Server zu implementieren, muss dein Autorisierungsserver das Ausstellen von Zugangstokens mit Berechtigungen unterstützen. Berechtigungen (Scopes) repräsentieren die Berechtigungen, die einem Benutzer gewährt wurden. +Um [rollenbasierte Zugangskontrolle (RBAC)](https://auth.wiki/rbac) in deinem MCP-Server zu implementieren, muss dein Autorisierungsserver Zugangstokens mit Berechtigungen (Scopes) ausstellen können. Berechtigungen repräsentieren die Rechte, die einem Benutzer gewährt wurden. -[Logto](https://logto.io) bietet RBAC-Unterstützung durch seine API-Ressourcen (konform zu [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) und Rollenfunktionen. So richtest du es ein: +[Logto](https://logto.io) bietet RBAC-Unterstützung durch seine API-Ressourcen (gemäß [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) und Rollenfunktionen. So richtest du es ein: 1. Melde dich bei der [Logto Console](https://cloud.logto.io) (oder deiner selbst gehosteten Logto Console) an. -2. Erstelle eine API-Ressource und Berechtigungen: +2. Erstelle API-Ressource und Berechtigungen: - Gehe zu "API-Ressourcen" - - Erstelle eine neue API-Ressource mit dem Namen "Todo Manager" + - Erstelle eine neue API-Ressource namens "Todo Manager" - Füge folgende Berechtigungen hinzu: - - `create:todos`: "Neue Todo-Elemente erstellen" - - `read:todos`: "Alle Todo-Elemente lesen" - - `delete:todos`: "Beliebiges Todo-Element löschen" + - `create:todos`: "Neue Todo-Einträge erstellen" + - `read:todos`: "Alle Todo-Einträge lesen" + - `delete:todos`: "Beliebigen Todo-Eintrag löschen" 3. Erstelle Rollen (empfohlen für einfachere Verwaltung): @@ -92,7 +94,7 @@ Um [rollenbasierte Zugangskontrolle (RBAC)](https://auth.wiki/rbac) in deinem MC - Wähle einen Benutzer aus - Du kannst entweder: - Rollen im Tab "Rollen" zuweisen (empfohlen) - - Oder direkt Berechtigungen im Tab "Berechtigungen" zuweisen + - Oder Berechtigungen direkt im Tab "Berechtigungen" zuweisen Die Berechtigungen werden im `scope`-Anspruch des JWT-Zugangstokens als durch Leerzeichen getrennte Zeichenkette enthalten sein. @@ -102,15 +104,15 @@ Die Berechtigungen werden im `scope`-Anspruch des JWT-Zugangstokens als durch Le OAuth 2.0 / OIDC-Anbieter unterstützen in der Regel berechtigungsbasierte Zugangskontrolle. Bei der Implementierung von RBAC: 1. Definiere die benötigten Berechtigungen in deinem Autorisierungsserver -2. Konfiguriere deinen Client so, dass diese Berechtigungen während des Autorisierungs-Flow angefordert werden -3. Stelle sicher, dass dein Autorisierungsserver die gewährten Berechtigungen im Zugangstoken einfügt +2. Konfiguriere deinen Client so, dass er diese Berechtigungen während des Autorisierungs-Flow anfordert +3. Stelle sicher, dass dein Autorisierungsserver die gewährten Berechtigungen im Zugangstoken einträgt 4. Die Berechtigungen sind üblicherweise im `scope`-Anspruch des JWT-Zugangstokens enthalten -Sieh in der Dokumentation deines Anbieters nach, wie: +Siehe die Dokumentation deines Anbieters für Details zu: -- Berechtigungen definiert und verwaltet werden -- Berechtigungen im Zugangstoken enthalten sind -- Zusätzliche RBAC-Funktionen wie Rollenverwaltung verfügbar sind +- Wie du Berechtigungen definierst und verwaltest +- Wie Berechtigungen im Zugangstoken enthalten sind +- Zusätzliche RBAC-Funktionen wie Rollenverwaltung @@ -119,18 +121,18 @@ Sieh in der Dokumentation deines Anbieters nach, wie: Nach der neuesten MCP-Spezifikation agiert der MCP-Server als **Ressourcenserver (Resource Server)** im OAuth 2.0-Framework. Als Ressourcenserver hat der MCP-Server folgende Aufgaben: -1. **Token-Validierung**: Überprüfe die Echtheit und Integrität der von MCP-Clients empfangenen Zugangstokens -2. **Berechtigungsdurchsetzung**: Extrahiere und prüfe die Berechtigungen aus dem Zugangstoken, um festzustellen, welche Operationen der Client ausführen darf -3. **Ressourcenschutz**: Geschützte Ressourcen (Tools ausführen) nur bereitstellen, wenn der Client gültige Tokens mit ausreichenden Berechtigungen vorlegt +1. **Token-Validierung**: Überprüfe die Echtheit und Integrität der von MCP-Clients erhaltenen Zugangstokens +2. **Berechtigungsdurchsetzung**: Extrahiere und prüfe die Berechtigungen aus dem Zugangstoken, um zu bestimmen, welche Operationen der Client ausführen darf +3. **Ressourcenschutz**: Gebe geschützte Ressourcen (Tools ausführen) nur frei, wenn der Client gültige Tokens mit ausreichenden Berechtigungen vorlegt -Wenn dein MCP-Server eine Anfrage erhält, läuft folgender Validierungsprozess ab: +Wenn dein MCP-Server eine Anfrage erhält, führt er folgenden Validierungsprozess durch: 1. Extrahiere das Zugangstoken aus dem `Authorization`-Header (Bearer-Token-Format) 2. Validierung der Signatur und Ablaufzeit des Zugangstokens 3. Extrahiere die Berechtigungen und Benutzerinformationen aus dem validierten Token 4. Prüfe, ob das Token die erforderlichen Berechtigungen für die angeforderte Operation enthält -Beispiel: Wenn ein Benutzer ein neues Todo-Element erstellen möchte, muss sein Zugangstoken die Berechtigung `create:todos` enthalten. So funktioniert der Validierungs-Flow des Ressourcenservers: +Beispiel: Wenn ein Benutzer einen neuen Todo-Eintrag erstellen möchte, muss sein Zugangstoken die Berechtigung `create:todos` enthalten. So funktioniert der Validierungs-Flow des Ressourcenservers: ```mermaid sequenceDiagram @@ -143,7 +145,7 @@ sequenceDiagram alt JWT-Validierung (bevorzugt) Server->>Auth: JWKS abrufen (falls nicht im Cache) Auth-->>Server: JWKS zurückgeben - Server->>Server: JWT-Signatur & Claims lokal validieren + Server->>Server: JWT-Signatur & Ansprüche lokal validieren else Token-Introspektion (Fallback) Server->>Auth: POST /introspect
(token=access_token) Auth-->>Server: Token-Info zurückgeben
(active, scope, user_id, etc.) @@ -155,7 +157,7 @@ sequenceDiagram Server->>Server: Angeforderte Operation ausführen Server->>Client: Operationsergebnis zurückgeben else Fehlende Berechtigungen - Server->>Client: 403 Verboten
(insufficient_scope error) + Server->>Client: 403 Verboten zurückgeben
(insufficient_scope error) end ``` @@ -165,25 +167,25 @@ Dynamische Client-Registrierung ist für dieses Tutorial nicht erforderlich, kan ## Verstehe RBAC im Todo-Manager \{#understand-rbac-in-todo-manager} -Zu Demonstrationszwecken implementieren wir ein einfaches rollenbasiertes Zugangskontrollsystem (RBAC) in unserem Todo-Manager-MCP-Server. Dies zeigt dir die Grundprinzipien von RBAC bei überschaubarer Implementierung. +Zu Demonstrationszwecken implementieren wir ein einfaches rollenbasiertes Zugangskontrollsystem (RBAC) in unserem Todo-Manager-MCP-Server. Das zeigt dir die Grundprinzipien von RBAC bei überschaubarer Implementierung. :::note -Obwohl dieses Tutorial RBAC-basierte Berechtigungsverwaltung demonstriert, ist es wichtig zu beachten, dass nicht alle Authentifizierungsanbieter die Berechtigungsverwaltung über Rollen implementieren. Manche Anbieter haben eigene Mechanismen zur Verwaltung von Zugangskontrolle und Berechtigungen. +Auch wenn dieses Tutorial RBAC-basierte Berechtigungsverwaltung demonstriert, ist es wichtig zu beachten, dass nicht alle Authentifizierungsanbieter die Berechtigungsverwaltung über Rollen implementieren. Manche Anbieter haben eigene Mechanismen zur Verwaltung von Zugangskontrolle und Berechtigungen. ::: ### Tools und Berechtigungen \{#tools-and-scopes} Unser Todo-Manager-MCP-Server stellt drei Haupttools bereit: -- `create-todo`: Ein neues Todo-Element erstellen -- `get-todos`: Alle Todos auflisten -- `delete-todo`: Ein Todo anhand der ID löschen +- `create-todo`: Erstelle einen neuen Todo-Eintrag +- `get-todos`: Liste alle Todos auf +- `delete-todo`: Lösche ein Todo anhand der ID -Um den Zugriff auf diese Tools zu steuern, definieren wir folgende Berechtigungen: +Zur Zugriffskontrolle auf diese Tools definieren wir folgende Berechtigungen: -- `create:todos`: Erlaubt das Erstellen neuer Todo-Elemente -- `delete:todos`: Erlaubt das Löschen bestehender Todo-Elemente -- `read:todos`: Erlaubt das Abfragen und Abrufen aller Todo-Elemente +- `create:todos`: Erlaubt das Erstellen neuer Todo-Einträge +- `delete:todos`: Erlaubt das Löschen bestehender Todo-Einträge +- `read:todos`: Erlaubt das Abfragen und Abrufen aller Todo-Einträge ### Rollen und Berechtigungen \{#roles-and-permissions} @@ -194,29 +196,29 @@ Wir definieren zwei Rollen mit unterschiedlichen Zugriffsrechten: | Admin | ✅ | ✅ | ✅ | | User | ✅ | | | -- **User**: Ein normaler Benutzer, der Todo-Elemente erstellen und nur seine eigenen Todos ansehen oder löschen kann -- **Admin**: Ein Administrator, der alle Todo-Elemente erstellen, ansehen und löschen kann, unabhängig vom Eigentümer +- **User**: Ein normaler Benutzer, der Todo-Einträge erstellen und nur seine eigenen Todos ansehen oder löschen kann +- **Admin**: Ein Administrator, der alle Todo-Einträge erstellen, ansehen und löschen kann, unabhängig vom Eigentümer ### Ressourcenbesitz \{#resource-ownership} Obwohl die obige Berechtigungstabelle die expliziten Berechtigungen jeder Rolle zeigt, gibt es ein wichtiges Prinzip des Ressourcenbesitzes zu beachten: - **Benutzer** haben nicht die Berechtigungen `read:todos` oder `delete:todos`, können aber trotzdem: - - Ihre eigenen Todo-Elemente lesen - - Ihre eigenen Todo-Elemente löschen -- **Admins** haben volle Berechtigungen (`read:todos` und `delete:todos`), wodurch sie: - - Alle Todo-Elemente im System sehen können - - Jedes Todo-Element löschen können, unabhängig vom Eigentümer + - Ihre eigenen Todo-Einträge lesen + - Ihre eigenen Todo-Einträge löschen +- **Admins** haben volle Berechtigungen (`read:todos` und `delete:todos`) und können daher: + - Alle Todo-Einträge im System ansehen + - Jeden Todo-Eintrag löschen, unabhängig vom Eigentümer -Dies zeigt ein häufiges Muster in RBAC-Systemen, bei dem der Besitz einer Ressource implizite Berechtigungen für eigene Ressourcen gewährt, während administrative Rollen explizite Berechtigungen für alle Ressourcen erhalten. +Das demonstriert ein häufiges Muster in RBAC-Systemen, bei dem der Besitz einer Ressource implizite Berechtigungen für eigene Ressourcen gewährt, während administrative Rollen explizite Berechtigungen für alle Ressourcen erhalten. :::tip Mehr erfahren -Um tiefer in RBAC-Konzepte und Best Practices einzutauchen, sieh dir [Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac) an. +Um tiefer in RBAC-Konzepte und Best Practices einzutauchen, siehe [Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac). ::: ## Autorisierung in deinem Anbieter konfigurieren \{#configure-authorization-in-your-provider} -Um das oben beschriebene Zugangskontrollsystem zu implementieren, musst du deinen Autorisierungsserver so konfigurieren, dass er die erforderlichen Berechtigungen unterstützt. So geht es bei verschiedenen Anbietern: +Um das oben beschriebene Zugangskontrollsystem zu implementieren, musst du deinen Autorisierungsserver so konfigurieren, dass er die erforderlichen Berechtigungen unterstützt. So geht es mit verschiedenen Anbietern: @@ -225,15 +227,15 @@ Um das oben beschriebene Zugangskontrollsystem zu implementieren, musst du deine 1. Melde dich bei der [Logto Console](https://cloud.logto.io) (oder deiner selbst gehosteten Logto Console) an. -2. Erstelle eine API-Ressource und Berechtigungen: +2. Erstelle API-Ressource und Berechtigungen: - Gehe zu "API-Ressourcen" - - Erstelle eine neue API-Ressource mit dem Namen "Todo Manager" und verwende `http://localhost:3001` als Ressourcenindikator. - - **Wichtig**: Der Ressourcenindikator muss mit der URL deines MCP-Servers übereinstimmen. Für dieses Tutorial verwenden wir `http://localhost:3001`, da unser MCP-Server auf Port 3001 läuft. In Produktion verwende deine tatsächliche MCP-Server-URL (z. B. `https://your-mcp-server.example.com`). + - Erstelle eine neue API-Ressource namens "Todo Manager" und verwende `http://localhost:3001/` als Ressourcenindikator. + - **Wichtig**: Der Ressourcenindikator muss mit der URL deines MCP-Servers übereinstimmen. Für dieses Tutorial verwenden wir `http://localhost:3001/`, da unser MCP-Server auf Port 3001 läuft. In Produktion verwende deine tatsächliche MCP-Server-URL (z. B. `https://your-mcp-server.example.com/`). - Erstelle folgende Berechtigungen: - - `create:todos`: "Neue Todo-Elemente erstellen" - - `read:todos`: "Alle Todo-Elemente lesen" - - `delete:todos`: "Beliebiges Todo-Element löschen" + - `create:todos`: "Neue Todo-Einträge erstellen" + - `read:todos`: "Alle Todo-Einträge lesen" + - `delete:todos`: "Beliebigen Todo-Eintrag löschen" 3. Erstelle Rollen (empfohlen für einfachere Verwaltung): @@ -248,18 +250,18 @@ Um das oben beschriebene Zugangskontrollsystem zu implementieren, musst du deine - Für bestehende Benutzer: - Gehe zu "Benutzerverwaltung" - Wähle einen Benutzer aus - - Weisen dem Benutzer Rollen im Tab "Rollen" zu + - Weise dem Benutzer Rollen im Tab "Rollen" zu :::tip Programmatische Rollenverwaltung -Du kannst auch die [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) von Logto verwenden, um Benutzerrollen programmatisch zu verwalten. Das ist besonders nützlich für automatisierte Benutzerverwaltung oder beim Aufbau von Admin-Panels. +Du kannst auch die [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) von Logto verwenden, um Benutzerrollen programmatisch zu verwalten. Das ist besonders nützlich für automatisiertes Benutzer-Management oder beim Bau von Admin-Panels. ::: -Beim Anfordern eines Zugangstokens wird Logto die Berechtigungen im `scope`-Anspruch des Tokens basierend auf den Rollenzuweisungen des Benutzers einfügen. +Beim Anfordern eines Zugangstokens wird Logto die Berechtigungen im `scope`-Anspruch des Tokens basierend auf den Rollenberechtigungen des Benutzers eintragen. -Für OAuth 2.0- oder OpenID Connect-Anbieter musst du die Berechtigungen konfigurieren, die verschiedene Zugriffsrechte repräsentieren. Die genauen Schritte hängen von deinem Anbieter ab, aber im Allgemeinen: +Für OAuth 2.0- oder OpenID Connect-Anbieter musst du die Berechtigungen konfigurieren, die verschiedene Rechte repräsentieren. Die genauen Schritte hängen von deinem Anbieter ab, aber im Allgemeinen: 1. Berechtigungen definieren: @@ -270,30 +272,34 @@ Für OAuth 2.0- oder OpenID Connect-Anbieter musst du die Berechtigungen konfigu 2. Client konfigurieren: - - Registriere oder aktualisiere deinen Client, um diese Berechtigungen anzufordern + - Registriere oder aktualisiere deinen Client, damit er diese Berechtigungen anfordert - Stelle sicher, dass die Berechtigungen im Zugangstoken enthalten sind 3. Berechtigungen zuweisen: - - Verwende die Oberfläche deines Anbieters, um Benutzern passende Berechtigungen zuzuweisen - - Manche Anbieter unterstützen rollenbasierte Verwaltung, andere nutzen direkte Berechtigungszuweisungen - - Sieh in der Dokumentation deines Anbieters nach, was empfohlen wird + - Verwende die Oberfläche deines Anbieters, um Benutzern die passenden Berechtigungen zuzuweisen + - Manche Anbieter unterstützen rollenbasierte Verwaltung, andere direkte Berechtigungszuweisung + - Siehe die Dokumentation deines Anbieters für den empfohlenen Ansatz :::tip -Die meisten Anbieter fügen die gewährten Berechtigungen im `scope`-Anspruch des Zugangstokens ein. Das Format ist typischerweise eine durch Leerzeichen getrennte Zeichenkette von Berechtigungswerten. +Die meisten Anbieter werden die gewährten Berechtigungen im `scope`-Anspruch des Zugangstokens eintragen. Das Format ist typischerweise eine durch Leerzeichen getrennte Zeichenkette von Berechtigungswerten. ::: +:::note[Abschließender Schrägstrich im Ressourcenindikator] +Füge immer einen abschließenden Schrägstrich (`/`) im Ressourcenindikator hinzu. Aufgrund eines aktuellen Bugs im offiziellen MCP-SDK fügen Clients, die das SDK verwenden, beim Starten von Auth-Anfragen automatisch einen Schrägstrich an Ressourcenkennungen an. Wenn dein Ressourcenindikator keinen Schrägstrich enthält, schlägt die Ressourcenvalidierung für diese Clients fehl. (VS Code ist von diesem Bug nicht betroffen.) +::: + Nach der Konfiguration deines Autorisierungsservers erhalten Benutzer Zugangstokens mit ihren gewährten Berechtigungen. Der MCP-Server verwendet diese Berechtigungen, um zu bestimmen: - Ob ein Benutzer neue Todos erstellen darf (`create:todos`) -- Ob ein Benutzer alle Todos (`read:todos`) oder nur seine eigenen sehen darf +- Ob ein Benutzer alle Todos (`read:todos`) oder nur seine eigenen ansehen darf - Ob ein Benutzer beliebige Todos (`delete:todos`) oder nur seine eigenen löschen darf ## MCP-Server einrichten \{#set-up-the-mcp-server} -Wir verwenden die [offiziellen MCP SDKs](https://github.com/modelcontextprotocol), um unseren Todo-Manager-MCP-Server zu erstellen. +Wir verwenden die [offiziellen MCP-SDKs](https://github.com/modelcontextprotocol), um unseren Todo-Manager-MCP-Server zu erstellen. ### Neues Projekt erstellen \{#create-a-new-project} @@ -312,7 +318,7 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" Wir verwenden TypeScript in unseren Beispielen, da Node.js v22.6.0+ TypeScript nativ mit dem Flag `--experimental-strip-types` ausführen kann. Wenn du JavaScript verwendest, ist der Code ähnlich – stelle nur sicher, dass du Node.js v22.6.0 oder neuer nutzt. Siehe Node.js-Dokumentation für Details. ::: -### MCP SDK und Abhängigkeiten installieren \{#install-the-mcp-sdk-and-dependencies} +### MCP-SDK und Abhängigkeiten installieren \{#install-the-mcp-sdk-and-dependencies} ```bash npm install @modelcontextprotocol/sdk express zod @@ -332,44 +338,6 @@ Starte den Server mit: npm start ``` -## MCP-Server inspizieren \{#inspect-the-mcp-server} - -### MCP Inspector klonen und starten \{#clone-and-run-mcp-inspector} - -Jetzt, da der MCP-Server läuft, können wir den MCP Inspector verwenden, um zu prüfen, ob Tools verfügbar sind. - -Der offizielle MCP Inspector v0.16.2 hat einige Bugs, die die Authentifizierungsfunktionalität beeinträchtigen. Um diese Probleme zu beheben, haben wir eine [gepatchte Version des MCP Inspectors](https://github.com/mcp-auth/inspector/tree/patch/0.16.2-fixes) erstellt, die notwendige Fixes für OAuth/OIDC-Authentifizierungsflüsse enthält. Wir haben auch Pull Requests an das offizielle Repository eingereicht, um diese Fixes beizusteuern. - -Um den MCP Inspector zu starten, verwende folgenden Befehl (Node.js wird benötigt): - -```bash -git clone https://github.com/mcp-auth/inspector.git -b patch/0.16.2-fixes -cd inspector -npm install -npm run dev -``` - -Der MCP Inspector öffnet sich automatisch im Standardbrowser, oder du kannst ihn manuell über den Link aus der Terminalausgabe aufrufen (achte darauf, den Link mit dem Parameter `MCP_PROXY_AUTH_TOKEN` zu verwenden, z. B. `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=458ae4a4...acab1907`). - -### MCP Inspector mit dem MCP-Server verbinden \{#connect-mcp-inspector-to-the-mcp-server} - -Vor dem Fortfahren prüfe folgende Konfiguration im MCP Inspector: - -- **Transporttyp**: Setze auf `Streamable HTTP`. -- **URL**: Setze auf die URL deines MCP-Servers. In unserem Fall: `http://localhost:3001`. - -Jetzt kannst du auf den "Connect"-Button klicken, um zu sehen, ob der MCP Inspector eine Verbindung zum MCP-Server herstellen kann. Wenn alles in Ordnung ist, solltest du den Status "Connected" im MCP Inspector sehen. - -### Checkpoint: Todo-Manager-Tools ausführen \{#checkpoint-run-todo-manager-tools} - -1. Klicke im oberen Menü des MCP Inspectors auf den Tab "Tools". -2. Klicke auf den Button "List Tools". -3. Du solltest die Tools `create-todo`, `get-todos` und `delete-todo` auf der Seite sehen. Klicke darauf, um die Tool-Details zu öffnen. -4. Du solltest rechts den Button "Run Tool" sehen. Klicke darauf und gib die erforderlichen Parameter ein, um das Tool auszuführen. -5. Du solltest das Tool-Ergebnis mit der JSON-Antwort `{"error": "Not implemented"}` sehen. - -![MCP Inspector erster Start](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - ## Integration mit deinem Autorisierungsserver \{#integrate-with-your-authorization-server} Für diesen Abschnitt gibt es einige Überlegungen: @@ -390,26 +358,26 @@ Dies ist normalerweise die Basis-URL deines Autorisierungsservers, z. B. `https:
-**Wie du den MCP Inspector als Client in deinem Autorisierungsserver registrierst** +**Wie du den MCP-Client in deinem Autorisierungsserver registrierst** -- Wenn dein Autorisierungsserver [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) unterstützt, kannst du diesen Schritt überspringen, da sich der MCP Inspector automatisch als Client registriert. -- Wenn dein Autorisierungsserver Dynamic Client Registration nicht unterstützt, musst du den MCP Inspector manuell als Client in deinem Autorisierungsserver registrieren. +- Wenn dein Autorisierungsserver [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) unterstützt, kannst du diesen Schritt überspringen, da sich der MCP-Client automatisch registriert. +- Wenn dein Autorisierungsserver Dynamic Client Registration nicht unterstützt, musst du den MCP-Client manuell registrieren.
-**Verstehe die Token-Anfrageparameter** +**Verstehe Token-Request-Parameter** -Beim Anfordern von Zugangstokens von verschiedenen Autorisierungsservern gibt es verschiedene Ansätze, um die Zielressource und Berechtigungen anzugeben. Hier die Hauptmuster: +Beim Anfordern von Zugangstokens von verschiedenen Autorisierungsservern gibt es verschiedene Ansätze, um die Zielressource und Berechtigungen anzugeben. Hier die wichtigsten Muster: - **Ressourcenindikator-basiert**: - - Verwendet den Parameter `resource`, um die Ziel-API anzugeben (siehe [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) + - Verwendet den `resource`-Parameter, um die Ziel-API anzugeben (siehe [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) - Häufig in modernen OAuth 2.0-Implementierungen - Beispielanfrage: ```json { - "resource": "http://localhost:3001", + "resource": "http://localhost:3001/", "scope": "create:todos read:todos" } ``` @@ -417,7 +385,7 @@ Beim Anfordern von Zugangstokens von verschiedenen Autorisierungsservern gibt es - **Audience-basiert**: - - Verwendet den Parameter `audience`, um den beabsichtigten Token-Empfänger anzugeben + - Verwendet den `audience`-Parameter, um den beabsichtigten Token-Empfänger anzugeben - Ähnlich wie Ressourcenindikatoren, aber mit anderen Semantiken - Beispielanfrage: ```json @@ -443,33 +411,37 @@ Beim Anfordern von Zugangstokens von verschiedenen Autorisierungsservern gibt es - Prüfe die Dokumentation deines Anbieters auf unterstützte Parameter - Manche Anbieter unterstützen mehrere Ansätze gleichzeitig -- Ressourcenindikatoren bieten bessere Sicherheit durch Audience-Beschränkung +- Ressourcenindikatoren bieten bessere Sicherheit durch Audience-Restriktion - Verwende Ressourcenindikatoren, wenn verfügbar, für bessere Zugangskontrolle :::
-Jeder Anbieter hat eigene Anforderungen, aber die folgenden Schritte führen dich durch die Integration des MCP Inspectors und MCP Servers mit anbieter-spezifischen Konfigurationen. +Auch wenn jeder Anbieter eigene Anforderungen hat, führen dich die folgenden Schritte durch die Integration von VS Code und MCP-Server mit anbieter-spezifischen Konfigurationen. -### MCP Inspector als Client registrieren \{#register-mcp-inspector-as-a-client} +### MCP-Client als Drittanbieter-App registrieren \{#register-mcp-client-as-a-third-party-app} -Die Integration des Todo-Managers mit [Logto](https://logto.io) ist einfach, da es ein OpenID Connect-Anbieter ist, der Ressourcenindikatoren und Berechtigungen unterstützt. So kannst du deine Todo-API mit `http://localhost:3001` als Ressourcenindikator absichern. +Die Integration des Todo-Managers mit [Logto](https://logto.io) ist unkompliziert, da es ein OpenID Connect-Anbieter ist, der Ressourcenindikatoren und Berechtigungen unterstützt. So kannst du deine Todo-API mit `http://localhost:3001/` als Ressourcenindikator absichern. -Da Logto noch keine Dynamic Client Registration unterstützt, musst du den MCP Inspector manuell als Client in deinem Logto-Tenant registrieren: +Da Logto Dynamic Client Registration noch nicht unterstützt, musst du deinen MCP-Client (VS Code) manuell als Drittanbieter-App in deinem Logto-Tenant registrieren: -1. Öffne deinen MCP Inspector, gehe zur Authentifizierungskonfiguration und klicke auf die "OAuth2.0 Flow"-Konfiguration. Kopiere den **Redirect URI**-Wert, z. B. `http://localhost:6274/oauth/callback`. -2. Melde dich bei der [Logto Console](https://cloud.logto.io) (oder deiner selbst gehosteten Logto Console) an. -3. Navigiere zum Tab "Anwendungen", klicke auf "Anwendung erstellen". Klicke unten auf der Seite auf "App ohne Framework erstellen". -4. Fülle die Anwendungsdetails aus und klicke auf "Anwendung erstellen": - - **Anwendungstyp auswählen**: Wähle "Single-page application". - - **Anwendungsname**: Gib einen Namen ein, z. B. "MCP Inspector". -5. Im Abschnitt "Einstellungen / Redirect URIs" füge den kopierten **Redirect URI**-Wert ein. Klicke dann unten auf "Änderungen speichern". -6. Im oberen Bereich siehst du den Wert "App ID". Kopiere ihn. -7. Gehe zurück zum MCP Inspector und füge den "App ID"-Wert in der Authentifizierungskonfiguration unter "OAuth2.0 Flow" im Feld "Client ID" ein. -8. Gib im Feld "Scope" ein: `create:todos read:todos delete:todos`. Dadurch enthält das von Logto zurückgegebene Zugangstoken die notwendigen Berechtigungen für den Zugriff auf den Todo-Manager. +1. Melde dich bei der [Logto Console](https://cloud.logto.io) (oder deiner selbst gehosteten Logto Console) an. +2. Navigiere zu **Anwendungen > Drittanbieter-Apps** und klicke auf "Anwendung erstellen". +3. Wähle **Native App** als Anwendungstyp. +4. Fülle die Anwendungsdetails aus: + - **Anwendungsname**: Gib einen Namen für deine Anwendung ein, z. B. "MCP Client". + - **Beschreibung**: Gib eine Beschreibung ein, z. B. "MCP-Client für VS Code". +5. Setze folgende **Redirect-URIs** für VS Code: + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` +6. Klicke auf "Änderungen speichern". +7. Gehe zum Tab **Berechtigungen** der App, füge unter **Benutzer** die Berechtigungen `create:todos`, `read:todos` und `delete:todos` aus der zuvor erstellten **Todo Manager**-API-Ressource hinzu. +8. Im oberen Bereich siehst du den Wert "App ID". Kopiere ihn für später. @@ -478,27 +450,28 @@ Da Logto noch keine Dynamic Client Registration unterstützt, musst du den MCP I Dies ist eine generische Anleitung zur Integration eines OAuth 2.0 / OpenID Connect-Anbieters. Beide folgen ähnlichen Schritten, da OIDC auf OAuth 2.0 aufbaut. Prüfe die Dokumentation deines Anbieters für Details. ::: -Wenn dein Anbieter Dynamic Client Registration unterstützt, kannst du direkt zu Schritt 8 unten gehen; andernfalls musst du den MCP Inspector manuell als Client registrieren: +Wenn dein Anbieter Dynamic Client Registration unterstützt, kannst du die manuelle Registrierung überspringen; andernfalls musst du den MCP-Client manuell registrieren: -1. Öffne deinen MCP Inspector, gehe zur Authentifizierungskonfiguration und klicke auf die "OAuth2.0 Flow"-Konfiguration. Kopiere den **Redirect URI**-Wert, z. B. `http://localhost:6274/oauth/callback`. +1. Melde dich in der Konsole deines Anbieters an. -2. Melde dich in der Konsole deines Anbieters an. +2. Navigiere zum Bereich "Anwendungen" oder "Clients" und erstelle eine neue Anwendung oder einen neuen Client. -3. Navigiere zum Abschnitt "Anwendungen" oder "Clients" und erstelle eine neue Anwendung oder einen neuen Client. +3. Falls dein Anbieter einen Client-Typ verlangt, wähle "Native App" oder "Public client". -4. Falls erforderlich, wähle als Client-Typ "Single-page application" oder "Public client". +4. Nach dem Erstellen der Anwendung konfiguriere die Redirect-URIs. Für VS Code füge hinzu: -5. Nach dem Erstellen der Anwendung musst du den Redirect URI konfigurieren. Füge den kopierten **Redirect URI**-Wert ein. + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` -6. Finde die "Client ID" oder "Application ID" der neu erstellten Anwendung und kopiere sie. +5. Konfiguriere die benötigten Berechtigungen für die Anwendung: -7. Gehe zurück zum MCP Inspector und füge den "Client ID"-Wert in der Authentifizierungskonfiguration unter "OAuth2.0 Flow" im Feld "Client ID" ein. + ```text + create:todos read:todos delete:todos + ``` -8. Gib im Feld "Scope" folgende Berechtigungen ein, um die notwendigen Rechte für Todo-Operationen anzufordern: - -```text -create:todos read:todos delete:todos -``` +6. Finde die "Client ID" oder "Application ID" der neu erstellten Anwendung und kopiere sie für später. @@ -507,16 +480,14 @@ create:todos read:todos delete:todos Installiere zuerst das MCP Auth SDK in deinem MCP-Server-Projekt. -import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; - -Jetzt müssen wir MCP Auth in deinem MCP-Server initialisieren. Im geschützten Ressourcenmodus musst du deine Ressourcenmetadaten einschließlich der Autorisierungsserver konfigurieren. +Jetzt müssen wir MCP Auth im MCP-Server initialisieren. Im geschützten Ressourcenmodus musst du deine Ressourcenmetadaten einschließlich der Autorisierungsserver konfigurieren. Es gibt zwei Möglichkeiten, Autorisierungsserver zu konfigurieren: - **Vorab abgerufen (empfohlen)**: Verwende `fetchServerConfig()`, um die Metadaten vor der Initialisierung von MCPAuth abzurufen. So wird die Konfiguration beim Start validiert. -- **On-Demand-Discovery**: Gib nur `issuer` und `type` an – die Metadaten werden bei Bedarf abgerufen. Das ist nützlich für Edge-Runtimes (wie Cloudflare Workers), bei denen asynchrone Top-Level-Fetches nicht erlaubt sind. +- **On-Demand-Discovery**: Gib nur `issuer` und `type` an – Metadaten werden bei Bedarf abgerufen. Das ist nützlich für Edge-Runtimes (wie Cloudflare Workers), bei denen asynchrone Top-Level-Fetches nicht erlaubt sind. #### Geschützte Ressourcenmetadaten konfigurieren \{#configure-protected-resource-metadata} @@ -526,7 +497,7 @@ Zuerst benötigst du die Issuer-URL deines Autorisierungsservers: -In Logto findest du die Issuer-URL auf der Anwendungsdetailseite in der Logto Console unter "Endpoints & Credentials / Issuer endpoint". Sie sieht aus wie `https://my-project.logto.app/oidc`. +In Logto findest du die Issuer-URL auf der Anwendungsdetailseite in der Logto Console unter "Endpoints & Credentials / Issuer endpoint". Sie sollte etwa so aussehen: `https://my-project.logto.app/oidc`. @@ -535,8 +506,8 @@ In Logto findest du die Issuer-URL auf der Anwendungsdetailseite in der Logto Co Für OAuth 2.0-Anbieter musst du: 1. Die Dokumentation deines Anbieters nach der Autorisierungsserver-URL (oft Issuer-URL oder Basis-URL genannt) durchsuchen -2. Manche Anbieter stellen dies unter `https://{deine-domain}/.well-known/oauth-authorization-server` bereit -3. Im Admin-Panel deines Anbieters unter OAuth/API-Einstellungen nachsehen +2. Manche Anbieter stellen dies unter `https://{your-domain}/.well-known/oauth-authorization-server` bereit +3. Im Admin-Bereich deines Anbieters unter OAuth/API-Einstellungen nachsehen @@ -548,13 +519,13 @@ Jetzt konfiguriere die Protected Resource Metadata beim Erstellen der MCP Auth-I ### MCP-Server aktualisieren \{#update-mcp-server} -Wir sind fast fertig! Jetzt aktualisieren wir den MCP-Server, um die MCP Auth-Route und Middleware-Funktion anzuwenden und die berechtigungsbasierte Zugangskontrolle für die Todo-Manager-Tools basierend auf den Benutzerberechtigungen zu implementieren. +Fast geschafft! Jetzt aktualisieren wir den MCP-Server, um die MCP Auth-Route und Middleware-Funktion anzuwenden und die berechtigungsbasierte Zugriffskontrolle für die Todo-Manager-Tools basierend auf den Benutzerberechtigungen zu implementieren. Jetzt Protected Resource Metadata-Routen anwenden, damit MCP-Clients die erwarteten Ressourcenmetadaten vom MCP-Server abrufen können. [Der Code bleibt unverändert, siehe oben.] -Als Nächstes wenden wir die MCP Auth-Middleware auf den MCP-Server an. Diese Middleware übernimmt Authentifizierung und Autorisierung für eingehende Anfragen und stellt sicher, dass nur autorisierte Benutzer Zugriff auf die Todo-Manager-Tools haben. +Jetzt wenden wir die MCP Auth-Middleware auf den MCP-Server an. Diese Middleware übernimmt Authentifizierung und Autorisierung für eingehende Anfragen und stellt sicher, dass nur autorisierte Benutzer Zugriff auf die Todo-Manager-Tools haben. [Der Code bleibt unverändert, siehe oben.] @@ -562,21 +533,31 @@ Jetzt können wir die Implementierung der Tools aktualisieren. [Der Code bleibt unverändert, siehe oben.] -Erstelle nun den "Todo-Service", der im obigen Code verwendet wird, um die zugehörige Funktionalität zu implementieren: +Jetzt erstelle den "Todo-Service", der im obigen Code verwendet wird, um die zugehörige Funktionalität zu implementieren: + +Erstelle die Datei `todo-service.ts` für den Todo-Service: [Der Code bleibt unverändert, siehe oben.] Herzlichen Glückwunsch! Wir haben erfolgreich einen vollständigen MCP-Server mit Authentifizierung (Authentifizierung) und Autorisierung (Autorisierung) implementiert! :::info -Sieh dir das [MCP Auth Node.js SDK Repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) für den vollständigen Code des MCP-Servers (OIDC-Version) an. +Siehe das [MCP Auth Node.js SDK Repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) für den vollständigen Code des MCP-Servers (OIDC-Version). ::: ## Checkpoint: Die `todo-manager`-Tools ausführen \{#checkpoint-run-the-todo-manager-tools} -Starte deinen MCP-Server neu und öffne den MCP Inspector im Browser. Wenn du auf den "Connect"-Button klickst, solltest du zur Anmeldeseite deines Autorisierungsservers weitergeleitet werden. +Starte deinen MCP-Server neu und verbinde VS Code damit. So verbindest du dich mit Authentifizierung: + +1. Drücke in VS Code `Command + Shift + P` (macOS) oder `Ctrl + Shift + P` (Windows/Linux), um die Befehlspalette zu öffnen. +2. Tippe `MCP: Add Server...` und wähle es aus. +3. Wähle `HTTP` als Servertyp. +4. Gib die MCP-Server-URL ein: `http://localhost:3001` +5. Nach dem Start einer OAuth-Anfrage fordert dich VS Code auf, die **App ID** einzugeben. Gib die App ID ein, die du von deinem Autorisierungsserver kopiert hast. +6. Da wir kein **App Secret** haben (es ist ein Public Client), drücke einfach Enter, um zu überspringen. +7. Schließe den Anmeldeprozess im Browser ab. -Nach der Anmeldung und Rückkehr zum MCP Inspector wiederhole die Aktionen aus dem vorherigen Checkpoint, um die Todo-Manager-Tools auszuführen. Dieses Mal kannst du die Tools mit deiner authentifizierten Benutzeridentität verwenden. Das Verhalten der Tools hängt von den Rollen und Berechtigungen ab, die deinem Benutzer zugewiesen sind: +Sobald du dich angemeldet hast und zu VS Code zurückkehrst, wiederhole die Aktionen aus dem vorherigen Checkpoint, um die Todo-Manager-Tools auszuführen. Diesmal kannst du die Tools mit deiner authentifizierten Benutzeridentität verwenden. Das Verhalten der Tools hängt von den Rollen und Berechtigungen ab, die deinem Benutzer zugewiesen sind: - Wenn du als **User** (nur mit `create:todos`-Berechtigung) angemeldet bist: @@ -591,25 +572,23 @@ Nach der Anmeldung und Rückkehr zum MCP Inspector wiederhole die Aktionen aus d Du kannst diese unterschiedlichen Berechtigungsstufen testen, indem du: -1. Die aktuelle Sitzung abmeldest (klicke auf "Disconnect" im MCP Inspector) +1. Die Verbindung zum MCP-Server trennst (Serverkonfiguration in VS Code entfernen) 2. Dich mit einem anderen Benutzerkonto anmeldest, das andere Rollen/Berechtigungen hat 3. Die gleichen Tools erneut ausprobierst, um zu sehen, wie sich das Verhalten je nach Benutzerberechtigungen ändert -Dies zeigt, wie rollenbasierte Zugangskontrolle (RBAC) in der Praxis funktioniert, wobei verschiedene Benutzer unterschiedliche Zugriffsrechte auf die Funktionen des Systems haben. - -![MCP Inspector Todo-Manager-Tool-Ergebnis](/docs-assets/images/tutorials/todo-manager/result.png) +Das zeigt, wie rollenbasierte Zugangskontrolle (RBAC) in der Praxis funktioniert, wobei verschiedene Benutzer unterschiedliche Zugriffsrechte auf die Funktionen des Systems haben. :::info -Sieh dir das [MCP Auth Node.js SDK Repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) für den vollständigen Code des MCP-Servers (OIDC-Version) an. +Siehe das [MCP Auth Node.js SDK Repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) für den vollständigen Code des MCP-Servers (OIDC-Version). ::: ## Abschließende Hinweise \{#closing-notes} -Herzlichen Glückwunsch! Du hast das Tutorial erfolgreich abgeschlossen. Fassen wir zusammen, was wir gemacht haben: +Herzlichen Glückwunsch! Du hast das Tutorial erfolgreich abgeschlossen. Lass uns zusammenfassen, was wir gemacht haben: - Einen grundlegenden MCP-Server mit Todo-Management-Tools (`create-todo`, `get-todos`, `delete-todo`) eingerichtet - Rollenbasierte Zugangskontrolle (RBAC) mit unterschiedlichen Berechtigungsstufen für Benutzer und Admins implementiert - Den MCP-Server mit einem Autorisierungsserver über MCP Auth integriert -- Den MCP Inspector so konfiguriert, dass Benutzer authentifiziert werden und Zugangstokens mit Berechtigungen zum Aufrufen der Tools verwendet werden +- VS Code so konfiguriert, dass Benutzer authentifiziert werden und Zugangstokens mit Berechtigungen zum Aufrufen der Tools verwenden Sieh dir weitere Tutorials und die Dokumentation an, um das Beste aus MCP Auth herauszuholen. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/references/js/type-aliases/ValidateIssuerFunction.md b/i18n/es/docusaurus-plugin-content-docs/current/references/js/type-aliases/ValidateIssuerFunction.md index ffab10f..0b59d23 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/references/js/type-aliases/ValidateIssuerFunction.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/references/js/type-aliases/ValidateIssuerFunction.md @@ -10,7 +10,8 @@ type ValidateIssuerFunction = (tokenIssuer: string) => void; Tipo de función para validar el emisor (Issuer) del token de acceso (Access token). -Esta función debe lanzar un [MCPAuthBearerAuthError](/references/js/classes/MCPAuthBearerAuthError.md) con el código 'invalid_issuer' si el emisor no es válido. El emisor debe validarse contra: +Esta función debe lanzar un [MCPAuthBearerAuthError](/references/js/classes/MCPAuthBearerAuthError.md) con el código 'invalid_issuer' si el emisor +no es válido. El emisor debe validarse contra: 1. Los servidores de autorización configurados en los metadatos del servidor de autenticación de MCP-Auth 2. Los servidores de autorización listados en los metadatos del recurso protegido @@ -27,4 +28,4 @@ Esta función debe lanzar un [MCPAuthBearerAuthError](/references/js/classes/MCP ## Lanza {#throws} -Cuando el emisor no es reconocido o es inválido. \ No newline at end of file +Cuando el emisor (Issuer) no es reconocido o es inválido. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index ca405a6..c616da2 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -3,6 +3,7 @@ sidebar_position: 2 sidebar_label: 'Tutorial: Construye un gestor de tareas' --- +import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -17,37 +18,38 @@ En este tutorial, construiremos un servidor MCP gestor de tareas con Autenticaci Al completar este tutorial, tendrás: - ✅ Una comprensión básica de cómo configurar el control de acceso basado en roles (RBAC) en tu servidor MCP. -- ✅ Un servidor MCP que actúa como Servidor de Recursos, consumiendo tokens de acceso emitidos por un Servidor de Autorización. +- ✅ Un servidor MCP que actúa como Servidor de Recursos, consumiendo tokens de acceso emitidos por un Servidor de Autorización (Authorization Server). - ✅ Una implementación funcional de la aplicación de permisos basados en Alcances (Scopes) para operaciones de tareas. ## Visión general \{#overview} El tutorial involucrará los siguientes componentes: -- **Cliente MCP (MCP Inspector)**: Una herramienta visual de pruebas para servidores MCP que actúa como cliente OAuth 2.0/OIDC. Inicia el flujo de autorización con el servidor de autorización y obtiene tokens de acceso para autenticar solicitudes al servidor MCP. -- **Servidor de Autorización**: Un proveedor OAuth 2.1 u OpenID Connect que gestiona identidades de usuario, autentica usuarios y emite tokens de acceso con los Alcances (Scopes) apropiados a los clientes autorizados. -- **Servidor MCP (Servidor de Recursos)**: Según la última especificación de MCP, el servidor MCP actúa como un Servidor de Recursos en el marco OAuth 2.0. Valida tokens de acceso emitidos por el servidor de autorización y aplica permisos basados en Alcances (Scopes) para operaciones de tareas. +- **Cliente MCP (VS Code)**: Un editor de código con soporte MCP integrado que actúa como cliente OAuth 2.0/OIDC. Inicia el flujo de autorización con el servidor de autorización y obtiene tokens de acceso para autenticar solicitudes al servidor MCP. +- **Servidor de Autorización (Authorization Server)**: Un proveedor OAuth 2.1 o OpenID Connect que gestiona identidades de usuario, autentica usuarios y emite tokens de acceso con los Alcances (Scopes) apropiados a los clientes autorizados. +- **Servidor MCP (Servidor de Recursos)**: Según la última especificación MCP, el servidor MCP actúa como Servidor de Recursos en el marco OAuth 2.0. Valida tokens de acceso emitidos por el servidor de autorización y aplica permisos basados en Alcances (Scopes) para operaciones de tareas. Esta arquitectura sigue el flujo estándar de OAuth 2.0 donde: -- El **MCP Inspector** solicita recursos protegidos en nombre del usuario -- El **Servidor de Autorización** autentica al usuario y emite tokens de acceso -- El **Servidor MCP** valida los tokens y sirve recursos protegidos según los permisos otorgados + +- **VS Code** solicita recursos protegidos en nombre del usuario +- El **Servidor de Autorización (Authorization Server)** autentica al usuario y emite tokens de acceso +- El **Servidor MCP** valida los tokens y sirve recursos protegidos según los permisos concedidos Aquí tienes un diagrama de alto nivel de la interacción entre estos componentes: ```mermaid sequenceDiagram autonumber - participant Client as MCP Inspector
(Cliente OAuth) + participant Client as VS Code
(Cliente OAuth) participant RS as Servidor MCP
(Servidor de Recursos) participant AS as Servidor de Autorización Client->>RS: Solicitud MCP (sin token) RS-->>Client: 401 No autorizado (WWW-Authenticate) - Note over Client: Extraer URL de resource_metadata
del encabezado WWW-Authenticate + Note over Client: Extrae la URL de resource_metadata
del encabezado WWW-Authenticate Client->>RS: GET /.well-known/oauth-protected-resource (resource_metadata) - RS-->>Client: Metadatos del recurso protegido
(incluye URL del servidor de autorización) + RS-->>Client: Metadatos del recurso protegido
(incluye la URL del servidor de autorización) Client->>AS: GET /.well-known/oauth-authorization-server AS-->>Client: Metadatos del servidor de autorización @@ -55,7 +57,7 @@ sequenceDiagram AS-->>Client: Token de acceso Client->>RS: Solicitud MCP (Authorization: Bearer ) - RS->>RS: Validar que el token de acceso es válido y autorizado + RS->>RS: Valida que el token de acceso sea válido y autorizado RS-->>Client: Respuesta MCP ``` @@ -63,38 +65,38 @@ sequenceDiagram ### Tokens de acceso con Alcances (Scopes) \{#access-tokens-with-scopes} -Para implementar el [control de acceso basado en roles (RBAC)](https://auth.wiki/rbac) en tu servidor MCP, tu servidor de autorización debe admitir la emisión de tokens de acceso con Alcances (Scopes). Los Alcances (Scopes) representan los permisos que se han otorgado a un usuario. +Para implementar el [control de acceso basado en roles (RBAC)](https://auth.wiki/rbac) en tu servidor MCP, tu servidor de autorización debe admitir la emisión de tokens de acceso con Alcances (Scopes). Los Alcances (Scopes) representan los Permisos (Permissions) que se han concedido a un usuario. -[Logto](https://logto.io) proporciona soporte para RBAC a través de sus recursos de API (conforme a [RFC 8707: Indicadores de recurso para OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) y funciones de roles. Así es como se configura: +[Logto](https://logto.io) proporciona soporte RBAC a través de sus Recursos de API (API resources) (conforme a [RFC 8707: Indicadores de recurso para OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) y funciones de Roles (Roles). Así es como se configura: -1. Inicia sesión en [Logto Console](https://cloud.logto.io) (o tu Logto Console autoalojado) +1. Inicia sesión en [Logto Console](https://cloud.logto.io) (o en tu instancia Logto autogestionada) -2. Crea recurso de API y Alcances (Scopes): +2. Crea un recurso de API y Alcances (Scopes): - - Ve a "Recursos de API" + - Ve a "Recursos de API (API Resources)" - Crea un nuevo recurso de API llamado "Gestor de tareas" - Añade los siguientes Alcances (Scopes): - `create:todos`: "Crear nuevas tareas" - `read:todos`: "Leer todas las tareas" - `delete:todos`: "Eliminar cualquier tarea" -3. Crea roles (recomendado para una gestión más sencilla): +3. Crea Roles (Roles) (recomendado para una gestión más sencilla): - Ve a "Roles" - Crea un rol "Admin" y asigna todos los Alcances (Scopes) (`create:todos`, `read:todos`, `delete:todos`) - Crea un rol "User" y asigna solo el Alcance (Scope) `create:todos` -4. Asigna permisos: - - Ve a "Usuarios" +4. Asigna Permisos (Permissions): + - Ve a "Usuarios (Users)" - Selecciona un usuario - Puedes: - - Asignar roles en la pestaña "Roles" (recomendado) - - O asignar Alcances (Scopes) directamente en la pestaña "Permisos" + - Asignar Roles (Roles) en la pestaña "Roles" (recomendado) + - O asignar Alcances (Scopes) directamente en la pestaña "Permisos (Permissions)" -Los Alcances (Scopes) se incluirán en el reclamo `scope` del token de acceso JWT como una cadena separada por espacios. +Los Alcances (Scopes) se incluirán en el Reclamo (Claim) `scope` del token de acceso JWT como una cadena separada por espacios. @@ -103,24 +105,24 @@ Los proveedores OAuth 2.0 / OIDC suelen admitir el control de acceso basado en A 1. Define los Alcances (Scopes) requeridos en tu servidor de autorización 2. Configura tu cliente para solicitar estos Alcances (Scopes) durante el flujo de autorización -3. Asegúrate de que tu servidor de autorización incluya los Alcances (Scopes) otorgados en el token de acceso -4. Los Alcances (Scopes) suelen incluirse en el reclamo `scope` del token de acceso JWT +3. Asegúrate de que tu servidor de autorización incluya los Alcances (Scopes) concedidos en el token de acceso +4. Los Alcances (Scopes) suelen incluirse en el Reclamo (Claim) `scope` del token de acceso JWT Consulta la documentación de tu proveedor para detalles específicos sobre: - Cómo definir y gestionar Alcances (Scopes) - Cómo se incluyen los Alcances (Scopes) en el token de acceso -- Cualquier característica adicional de RBAC como la gestión de roles +- Cualquier característica adicional de RBAC como la gestión de Roles (Roles) ### Validación de tokens y comprobación de permisos \{#validating-tokens-and-checking-permissions} -Según la última especificación de MCP, el servidor MCP actúa como un **Servidor de Recursos (Resource Server)** en el marco OAuth 2.0. Como Servidor de Recursos, el servidor MCP tiene las siguientes responsabilidades: +Según la última especificación MCP, el servidor MCP actúa como **Servidor de Recursos (Resource Server)** en el marco OAuth 2.0. Como Servidor de Recursos, el servidor MCP tiene las siguientes responsabilidades: 1. **Validación de tokens**: Verificar la autenticidad e integridad de los tokens de acceso recibidos de los clientes MCP -2. **Aplicación de Alcances (Scopes)**: Extraer y validar los Alcances (Scopes) del token de acceso para determinar qué operaciones está autorizado a realizar el cliente +2. **Aplicación de Alcances (Scope Enforcement)**: Extraer y validar los Alcances (Scopes) del token de acceso para determinar qué operaciones está autorizado a realizar el cliente 3. **Protección de recursos**: Solo servir recursos protegidos (ejecutar herramientas) cuando el cliente presente tokens válidos con permisos suficientes Cuando tu servidor MCP recibe una solicitud, realiza el siguiente proceso de validación: @@ -130,7 +132,7 @@ Cuando tu servidor MCP recibe una solicitud, realiza el siguiente proceso de val 3. Extrae los Alcances (Scopes) e información del usuario del token validado 4. Comprueba si el token tiene los Alcances (Scopes) requeridos para la operación solicitada -Por ejemplo, si un usuario quiere crear una nueva tarea, su token de acceso debe incluir el Alcance (Scope) `create:todos`. Así es como funciona el flujo de validación del Servidor de Recursos: +Por ejemplo, si un usuario quiere crear una nueva tarea, su token de acceso debe incluir el Alcance (Scope) `create:todos`. Así es como funciona el flujo de validación en el Servidor de Recursos: ```mermaid sequenceDiagram @@ -142,20 +144,20 @@ sequenceDiagram alt Validación JWT (Preferido) Server->>Auth: Obtener JWKS (si no está en caché) - Auth-->>Server: Retornar JWKS - Server->>Server: Validar firma y reclamos del JWT localmente + Auth-->>Server: Devuelve JWKS + Server->>Server: Valida localmente la firma y los reclamos del JWT else Introspección de token (Alternativa) Server->>Auth: POST /introspect
(token=access_token) - Auth-->>Server: Retornar información del token
(activo, scope, user_id, etc.) + Auth-->>Server: Devuelve información del token
(active, scope, user_id, etc.) end - Server->>Server: Extraer Alcances (Scopes) y contexto de usuario
del token validado + Server->>Server: Extrae Alcances (Scopes) y contexto de usuario
del token validado alt Tiene los Alcances (Scopes) requeridos - Server->>Server: Ejecutar operación solicitada - Server->>Client: Retornar resultado de la operación + Server->>Server: Ejecuta la operación solicitada + Server->>Client: Devuelve el resultado de la operación else Faltan Alcances (Scopes) requeridos - Server->>Client: Retornar 403 Prohibido
(error insufficient_scope) + Server->>Client: Devuelve 403 Prohibido
(error insufficient_scope) end ``` @@ -168,7 +170,7 @@ El registro dinámico de clientes no es necesario para este tutorial, pero puede Para fines demostrativos, implementaremos un sistema simple de control de acceso basado en roles (RBAC) en nuestro servidor MCP gestor de tareas. Esto te mostrará los principios básicos de RBAC manteniendo la implementación sencilla. :::note -Aunque este tutorial demuestra la gestión de Alcances (Scopes) basada en RBAC, es importante señalar que no todos los proveedores de autenticación implementan la gestión de Alcances (Scopes) a través de roles. Algunos proveedores pueden tener implementaciones y mecanismos únicos para gestionar el control de acceso y los permisos. +Aunque este tutorial demuestra la gestión de Alcances (Scopes) basada en RBAC, es importante señalar que no todos los proveedores de autenticación implementan la gestión de Alcances (Scopes) a través de Roles (Roles). Algunos proveedores pueden tener implementaciones y mecanismos propios para gestionar el control de acceso y los Permisos (Permissions). ::: ### Herramientas y Alcances (Scopes) \{#tools-and-scopes} @@ -185,9 +187,9 @@ Para controlar el acceso a estas herramientas, definimos los siguientes Alcances - `delete:todos`: Permite eliminar tareas existentes - `read:todos`: Permite consultar y recuperar la lista de todas las tareas -### Roles y permisos \{#roles-and-permissions} +### Roles y Permisos (Permissions) \{#roles-and-permissions} -Definiremos dos roles con diferentes niveles de acceso: +Definiremos dos Roles (Roles) con diferentes niveles de acceso: | Rol | create:todos | read:todos | delete:todos | | ----- | ------------ | ---------- | ------------ | @@ -199,9 +201,9 @@ Definiremos dos roles con diferentes niveles de acceso: ### Propiedad de recursos \{#resource-ownership} -Aunque la tabla de permisos anterior muestra los Alcances (Scopes) explícitos asignados a cada rol, hay un principio importante de propiedad de recursos a considerar: +Aunque la tabla de permisos anterior muestra los Alcances (Scopes) explícitos asignados a cada Rol (Role), hay un principio importante de propiedad de recursos a considerar: -- **Usuarios** no tienen los Alcances (Scopes) `read:todos` o `delete:todos`, pero aún pueden: +- **Usuarios (Users)** no tienen los Alcances (Scopes) `read:todos` o `delete:todos`, pero aún pueden: - Leer sus propias tareas - Eliminar sus propias tareas - **Admins** tienen todos los permisos (`read:todos` y `delete:todos`), lo que les permite: @@ -221,21 +223,21 @@ Para implementar el sistema de control de acceso que describimos antes, deberás -[Logto](https://logto.io) proporciona soporte para RBAC a través de sus recursos de API y funciones de roles. Así es como se configura: +[Logto](https://logto.io) proporciona soporte RBAC a través de sus Recursos de API (API resources) y funciones de Roles (Roles). Así es como se configura: -1. Inicia sesión en [Logto Console](https://cloud.logto.io) (o tu Logto Console autoalojado) +1. Inicia sesión en [Logto Console](https://cloud.logto.io) (o en tu instancia Logto autogestionada) -2. Crea recurso de API y Alcances (Scopes): +2. Crea un recurso de API y Alcances (Scopes): - - Ve a "Recursos de API" - - Crea un nuevo recurso de API llamado "Gestor de tareas" y usa `http://localhost:3001` como el indicador de recurso. - - **Importante**: El indicador de recurso debe coincidir con la URL de tu servidor MCP. Para este tutorial, usamos `http://localhost:3001` ya que nuestro servidor MCP se ejecuta en el puerto 3001. En producción, usa la URL real de tu servidor MCP (por ejemplo, `https://tu-servidor-mcp.ejemplo.com`). + - Ve a "Recursos de API (API Resources)" + - Crea un nuevo recurso de API llamado "Gestor de tareas" y usa `http://localhost:3001/` como el indicador de recurso. + - **Importante**: El indicador de recurso debe coincidir con la URL de tu servidor MCP. Para este tutorial, usamos `http://localhost:3001/` ya que nuestro servidor MCP se ejecuta en el puerto 3001. En producción, usa la URL real de tu servidor MCP (por ejemplo, `https://tu-servidor-mcp.ejemplo.com/`). - Crea los siguientes Alcances (Scopes): - `create:todos`: "Crear nuevas tareas" - `read:todos`: "Leer todas las tareas" - `delete:todos`: "Eliminar cualquier tarea" -3. Crea roles (recomendado para una gestión más sencilla): +3. Crea Roles (Roles) (recomendado para una gestión más sencilla): - Ve a "Roles" - Crea un rol "Admin" y asigna todos los Alcances (Scopes) (`create:todos`, `read:todos`, `delete:todos`) @@ -244,7 +246,7 @@ Para implementar el sistema de control de acceso que describimos antes, deberás 4. Gestiona roles y permisos de usuario: - Para nuevos usuarios: - - Obtendrán automáticamente el rol "User" ya que lo establecimos como rol predeterminado + - Obtendrán automáticamente el rol "User" ya que lo establecimos como el rol predeterminado - Para usuarios existentes: - Ve a "Gestión de usuarios" - Selecciona un usuario @@ -254,12 +256,12 @@ Para implementar el sistema de control de acceso que describimos antes, deberás También puedes usar la [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) de Logto para gestionar roles de usuario de forma programática. Esto es especialmente útil para la gestión automatizada de usuarios o al construir paneles de administración. ::: -Al solicitar un token de acceso, Logto incluirá los Alcances (Scopes) en el reclamo `scope` del token según los permisos de rol del usuario. +Al solicitar un token de acceso, Logto incluirá los Alcances (Scopes) en el Reclamo (Claim) `scope` del token según los permisos de rol del usuario. -Para proveedores OAuth 2.0 u OpenID Connect, deberás configurar los Alcances (Scopes) que representan diferentes permisos. Los pasos exactos dependerán de tu proveedor, pero generalmente: +Para proveedores OAuth 2.0 o OpenID Connect, deberás configurar los Alcances (Scopes) que representan diferentes Permisos (Permissions). Los pasos exactos dependerán de tu proveedor, pero generalmente: 1. Define Alcances (Scopes): @@ -273,19 +275,23 @@ Para proveedores OAuth 2.0 u OpenID Connect, deberás configurar los Alcances (S - Registra o actualiza tu cliente para solicitar estos Alcances (Scopes) - Asegúrate de que los Alcances (Scopes) estén incluidos en el token de acceso -3. Asigna permisos: - - Usa la interfaz de tu proveedor para otorgar los Alcances (Scopes) apropiados a los usuarios - - Algunos proveedores pueden admitir la gestión basada en roles, mientras que otros pueden usar asignaciones directas de Alcances (Scopes) +3. Asigna Permisos (Permissions): + - Usa la interfaz de tu proveedor para conceder los Alcances (Scopes) apropiados a los usuarios + - Algunos proveedores pueden admitir la gestión basada en Roles (Roles), mientras que otros pueden usar asignaciones directas de Alcances (Scopes) - Consulta la documentación de tu proveedor para el enfoque recomendado :::tip -La mayoría de los proveedores incluirán los Alcances (Scopes) otorgados en el reclamo `scope` del token de acceso. El formato suele ser una cadena de valores de Alcances (Scopes) separados por espacios. +La mayoría de los proveedores incluirán los Alcances (Scopes) concedidos en el Reclamo (Claim) `scope` del token de acceso. El formato suele ser una cadena de valores de Alcance (Scope) separados por espacios. ::: -Después de configurar tu servidor de autorización, los usuarios recibirán tokens de acceso que contienen los Alcances (Scopes) otorgados. El servidor MCP usará estos Alcances (Scopes) para determinar: +:::note[Barra final en el indicador de recurso] +Incluye siempre una barra final (`/`) en el indicador de recurso. Debido a un error actual en el SDK oficial de MCP, los clientes que usan el SDK añadirán automáticamente una barra final a los identificadores de recurso al iniciar solicitudes de autenticación. Si tu indicador de recurso no incluye la barra final, la validación del recurso fallará para esos clientes. (VS Code no se ve afectado por este error.) +::: + +Después de configurar tu servidor de autorización, los usuarios recibirán tokens de acceso que contienen sus Alcances (Scopes) concedidos. El servidor MCP usará estos Alcances (Scopes) para determinar: - Si un usuario puede crear nuevas tareas (`create:todos`) - Si un usuario puede ver todas las tareas (`read:todos`) o solo las suyas @@ -309,7 +315,7 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -Usamos TypeScript en nuestros ejemplos ya que Node.js v22.6.0+ admite la ejecución de TypeScript de forma nativa usando la opción `--experimental-strip-types`. Si usas JavaScript, el código será similar; solo asegúrate de usar Node.js v22.6.0 o posterior. Consulta la documentación de Node.js para más detalles. +Usamos TypeScript en nuestros ejemplos ya que Node.js v22.6.0+ admite la ejecución nativa de TypeScript usando la bandera `--experimental-strip-types`. Si usas JavaScript, el código será similar; solo asegúrate de usar Node.js v22.6.0 o posterior. Consulta la documentación de Node.js para más detalles. ::: ### Instala el SDK de MCP y dependencias \{#install-the-mcp-sdk-and-dependencies} @@ -324,7 +330,126 @@ O cualquier otro gestor de paquetes que prefieras, como `pnpm` o `yarn`. Crea un archivo llamado `todo-manager.ts` y añade el siguiente código: -[El bloque de código se mantiene igual que el original.] +```ts +// todo-manager.ts + +import { z } from 'zod'; +import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; +import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; +import express, { type Request, type Response } from 'express'; + +// Crea un servidor MCP +const server = new McpServer({ + name: 'Todo Manager', + version: '0.0.0', +}); + +server.registerTool( + 'create-todo', + { + description: 'Crear una nueva tarea', + inputSchema: { content: z.string() }, + }, + async ({ content }) => { + return { + content: [{ type: 'text', text: JSON.stringify({ error: 'No implementado' }) }], + }; + } +); + +server.registerTool( + 'get-todos', + { + description: 'Listar todas las tareas', + inputSchema: {}, + }, + async () => { + return { + content: [{ type: 'text', text: JSON.stringify({ error: 'No implementado' }) }], + }; + } +); + +server.registerTool( + 'delete-todo', + { + description: 'Eliminar una tarea por id', + inputSchema: { id: z.string() }, + }, + async ({ id }) => { + return { + content: [{ type: 'text', text: JSON.stringify({ error: 'No implementado' }) }], + }; + } +); + +// A continuación el código base de la documentación del SDK de MCP +const PORT = 3001; +const app = express(); + +app.post('/', async (request: Request, response: Response) => { + // En modo sin estado, crea una nueva instancia de transporte y servidor para cada solicitud + // para asegurar el aislamiento completo. Una sola instancia causaría colisiones de ID de solicitud + // cuando varios clientes se conectan simultáneamente. + + try { + const transport: StreamableHTTPServerTransport = new StreamableHTTPServerTransport({ + sessionIdGenerator: undefined, + }); + response.on('close', async () => { + console.log('Solicitud cerrada'); + await transport.close(); + await server.close(); + }); + await server.connect(transport); + await transport.handleRequest(request, response, request.body); + } catch (error) { + console.error('Error al manejar la solicitud MCP:', error); + if (!response.headersSent) { + response.status(500).json({ + jsonrpc: '2.0', + error: { + code: -32_603, + message: 'Error interno del servidor', + }, + id: null, + }); + } + } +}); + +// Notificaciones SSE no soportadas en modo sin estado +app.get('/', async (request: Request, response: Response) => { + console.log('Solicitud GET MCP recibida'); + response.writeHead(405).end( + JSON.stringify({ + jsonrpc: '2.0', + error: { + code: -32_000, + message: 'Método no permitido.', + }, + id: null, + }) + ); +}); + +// Terminación de sesión no necesaria en modo sin estado +app.delete('/', async (request: Request, response: Response) => { + console.log('Solicitud DELETE MCP recibida'); + response.writeHead(405).end( + JSON.stringify({ + jsonrpc: '2.0', + error: { + code: -32_000, + message: 'Método no permitido.', + }, + id: null, + }) + ); +}); + +app.listen(PORT); +``` Ejecuta el servidor con: @@ -332,50 +457,12 @@ Ejecuta el servidor con: npm start ``` -## Inspecciona el servidor MCP \{#inspect-the-mcp-server} - -### Clona y ejecuta MCP inspector \{#clone-and-run-mcp-inspector} - -Ahora que tenemos el servidor MCP en funcionamiento, podemos usar el MCP inspector para ver si las herramientas están disponibles. - -La versión oficial del MCP inspector v0.16.2 tiene algunos errores que afectan la funcionalidad de autenticación. Para solucionar estos problemas, hemos creado una [versión parcheada del MCP inspector](https://github.com/mcp-auth/inspector/tree/patch/0.16.2-fixes) que incluye las correcciones necesarias para los flujos de autenticación OAuth/OIDC. También hemos enviado pull requests al repositorio oficial para contribuir con estas correcciones. - -Para ejecutar el MCP inspector, puedes usar el siguiente comando (se requiere Node.js): - -```bash -git clone https://github.com/mcp-auth/inspector.git -b patch/0.16.2-fixes -cd inspector -npm install -npm run dev -``` - -El MCP inspector se abrirá automáticamente en tu navegador predeterminado, o puedes acceder manualmente haciendo clic en el enlace de la salida de la terminal (asegúrate de hacer clic en el enlace que incluye el parámetro `MCP_PROXY_AUTH_TOKEN`, como `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=458ae4a4...acab1907`). - -### Conecta MCP inspector al servidor MCP \{#connect-mcp-inspector-to-the-mcp-server} - -Antes de continuar, revisa la siguiente configuración en MCP inspector: - -- **Tipo de transporte**: Establece en `Streamable HTTP`. -- **URL**: Establece la URL de tu servidor MCP. En nuestro caso, debe ser `http://localhost:3001`. - -Ahora puedes hacer clic en el botón "Connect" para ver si el MCP inspector puede conectarse al servidor MCP. Si todo está bien, deberías ver el estado "Connected" en el MCP inspector. - -### Punto de control: Ejecuta las herramientas del gestor de tareas \{#checkpoint-run-todo-manager-tools} - -1. En el menú superior del MCP inspector, haz clic en la pestaña "Tools". -2. Haz clic en el botón "List Tools". -3. Deberías ver las herramientas `create-todo`, `get-todos` y `delete-todo` listadas en la página. Haz clic en ellas para ver los detalles. -4. Deberías ver el botón "Run Tool" en el lado derecho. Haz clic en él e ingresa los parámetros requeridos para ejecutar la herramienta. -5. Deberías ver el resultado de la herramienta con la respuesta JSON `{"error": "Not implemented"}`. - -![Primer uso de MCP inspector](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - ## Integra con tu servidor de autorización \{#integrate-with-your-authorization-server} Para completar esta sección, hay varias consideraciones a tener en cuenta:
-**La URL del emisor de tu servidor de autorización** +**La URL del emisor (Issuer) de tu servidor de autorización** Normalmente es la URL base de tu servidor de autorización, como `https://auth.example.com`. Algunos proveedores pueden tener una ruta como `https://example.logto.app/oidc`, así que asegúrate de consultar la documentación de tu proveedor. @@ -390,26 +477,26 @@ Normalmente es la URL base de tu servidor de autorización, como `https://auth.e
-**Cómo registrar el MCP inspector como cliente en tu servidor de autorización** +**Cómo registrar el cliente MCP en tu servidor de autorización** -- Si tu servidor de autorización admite [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591), puedes omitir este paso ya que el MCP inspector se registrará automáticamente como cliente. -- Si tu servidor de autorización no admite Dynamic Client Registration, deberás registrar manualmente el MCP inspector como cliente en tu servidor de autorización. +- Si tu servidor de autorización admite [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591), puedes omitir este paso ya que el cliente MCP se registrará automáticamente. +- Si tu servidor de autorización no admite Dynamic Client Registration, deberás registrar manualmente el cliente MCP en tu servidor de autorización.
**Comprende los parámetros de solicitud de token** -Al solicitar tokens de acceso de diferentes servidores de autorización, encontrarás varios enfoques para especificar el recurso objetivo y los permisos. Aquí están los principales patrones: +Al solicitar tokens de acceso de diferentes servidores de autorización, encontrarás varios enfoques para especificar el recurso objetivo y los permisos. Aquí los principales patrones: - **Basado en indicador de recurso**: - - Usa el parámetro `resource` para especificar la API objetivo (ver [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) + - Usa el parámetro `resource` para especificar la API objetivo (ver [RFC 8707: Indicadores de recurso para OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) - Común en implementaciones modernas de OAuth 2.0 - Ejemplo de solicitud: ```json { - "resource": "http://localhost:3001", + "resource": "http://localhost:3001/", "scope": "create:todos read:todos" } ``` @@ -441,7 +528,7 @@ Al solicitar tokens de acceso de diferentes servidores de autorización, encontr :::tip Mejores prácticas -- Consulta la documentación de tu proveedor para los parámetros admitidos +- Consulta la documentación de tu proveedor para los parámetros soportados - Algunos proveedores admiten varios enfoques simultáneamente - Los indicadores de recurso proporcionan mejor seguridad mediante restricción de audiencia - Considera usar indicadores de recurso cuando estén disponibles para un mejor control de acceso @@ -449,56 +536,61 @@ Al solicitar tokens de acceso de diferentes servidores de autorización, encontr
-Aunque cada proveedor puede tener requisitos específicos, los siguientes pasos te guiarán en el proceso de integración del MCP inspector y el servidor MCP con configuraciones específicas del proveedor. +Aunque cada proveedor puede tener requisitos específicos, los siguientes pasos te guiarán en el proceso de integración de VS Code y el servidor MCP con configuraciones específicas del proveedor. -### Registra MCP inspector como cliente \{#register-mcp-inspector-as-a-client} +### Registra el cliente MCP como una app de terceros \{#register-mcp-client-as-a-third-party-app} -Integrar el gestor de tareas con [Logto](https://logto.io) es sencillo ya que es un proveedor OpenID Connect que admite indicadores de recurso y Alcances (Scopes), permitiéndote proteger tu API de tareas con `http://localhost:3001` como indicador de recurso. - -Como Logto aún no admite Dynamic Client Registration, deberás registrar manualmente el MCP inspector como cliente en tu tenant de Logto: - -1. Abre tu MCP inspector, ve a la configuración de Autenticación (Authentication) y haz clic en la configuración "OAuth2.0 Flow". Copia el valor de **Redirect URI**, que debería ser algo como `http://localhost:6274/oauth/callback`. -2. Inicia sesión en [Logto Console](https://cloud.logto.io) (o tu Logto Console autoalojado). -3. Navega a la pestaña "Aplicaciones", haz clic en "Crear aplicación". Al final de la página, haz clic en "Crear app sin framework". -4. Rellena los detalles de la aplicación y haz clic en "Crear aplicación": - - **Selecciona un tipo de aplicación**: Elige "Aplicación de una sola página". - - **Nombre de la aplicación**: Ingresa un nombre para tu aplicación, por ejemplo, "MCP Inspector". -5. En la sección "Configuración / Redirect URIs", pega el valor de **Redirect URI** que copiaste del MCP inspector. Luego haz clic en "Guardar cambios" en la barra inferior. -6. En la tarjeta superior, verás el valor "App ID". Cópialo. -7. Vuelve al MCP inspector y pega el valor "App ID" en la configuración de Autenticación (Authentication) bajo "OAuth2.0 Flow" en el campo "Client ID". -8. En el campo "Scope", ingresa: `create:todos read:todos delete:todos`. Esto asegurará que el token de acceso devuelto por Logto contenga los Alcances (Scopes) necesarios para acceder al gestor de tareas. +Integrar el gestor de tareas con [Logto](https://logto.io) es sencillo ya que es un proveedor OpenID Connect que admite indicadores de recurso y Alcances (Scopes), permitiéndote asegurar tu API de tareas con `http://localhost:3001/` como indicador de recurso. + +Como Logto aún no admite Dynamic Client Registration, deberás registrar manualmente tu cliente MCP (VS Code) como una app de terceros en tu tenant de Logto: + +1. Inicia sesión en [Logto Console](https://cloud.logto.io) (o en tu instancia Logto autogestionada). +2. Navega a **Aplicaciones > Apps de terceros** y haz clic en "Crear aplicación". +3. Selecciona **App nativa** como tipo de aplicación. +4. Rellena los detalles de la aplicación: + - **Nombre de la aplicación**: Ingresa un nombre, por ejemplo, "MCP Client". + - **Descripción**: Ingresa una descripción, por ejemplo, "Cliente MCP para VS Code". +5. Establece las siguientes **URIs de redirección** para VS Code: + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` +6. Haz clic en "Guardar cambios". +7. Ve a la pestaña **Permisos (Permissions)** de la app, en la sección **Usuario (User)**, añade los permisos `create:todos`, `read:todos` y `delete:todos` del recurso de API **Todo Manager** que creaste antes. +8. En la tarjeta superior, verás el valor "App ID". Cópialo para usarlo más adelante. :::note -Esta es una guía genérica de integración para proveedores OAuth 2.0 / OpenID Connect. Ambos siguen pasos similares ya que OIDC se basa en OAuth 2.0. Consulta la documentación de tu proveedor para detalles específicos. +Esta es una guía genérica de integración con proveedores OAuth 2.0 / OpenID Connect. Ambos siguen pasos similares ya que OIDC se basa en OAuth 2.0. Consulta la documentación de tu proveedor para detalles específicos. ::: -Si tu proveedor admite Dynamic Client Registration, puedes ir directamente al paso 8 para configurar el MCP inspector; de lo contrario, deberás registrar manualmente el MCP inspector como cliente: +Si tu proveedor admite Dynamic Client Registration, puedes omitir el registro manual; de lo contrario, deberás registrar manualmente el cliente MCP: -1. Abre tu MCP inspector, ve a la configuración de Autenticación (Authentication) y haz clic en la configuración "OAuth2.0 Flow". Copia el valor de **Redirect URI**, que debería ser algo como `http://localhost:6274/oauth/callback`. +1. Inicia sesión en la consola de tu proveedor. -2. Inicia sesión en la consola de tu proveedor. +2. Navega a la sección "Aplicaciones" o "Clientes", luego crea una nueva aplicación o cliente. -3. Navega a la sección "Aplicaciones" o "Clientes", luego crea una nueva aplicación o cliente. +3. Si tu proveedor requiere un tipo de cliente, selecciona "App nativa" o "Cliente público". -4. Si tu proveedor requiere un tipo de cliente, selecciona "Aplicación de una sola página" o "Cliente público". +4. Después de crear la aplicación, configura las URIs de redirección. Para VS Code, añade lo siguiente: -5. Después de crear la aplicación, deberás configurar el redirect URI. Pega el valor de **Redirect URI** que copiaste del MCP inspector. + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` -6. Busca el "Client ID" o "Application ID" de la nueva aplicación y cópialo. +5. Configura los Alcances (Scopes)/Permisos (Permissions) requeridos para la aplicación: -7. Vuelve al MCP inspector y pega el valor "Client ID" en la configuración de Autenticación (Authentication) bajo "OAuth2.0 Flow" en el campo "Client ID". + ```text + create:todos read:todos delete:todos + ``` -8. En el campo "Scope", ingresa los siguientes Alcances (Scopes) para solicitar los permisos necesarios para las operaciones de tareas: - -```text -create:todos read:todos delete:todos -``` +6. Busca el "Client ID" o "Application ID" de la aplicación recién creada y cópialo para usarlo más adelante. @@ -507,20 +599,18 @@ create:todos read:todos delete:todos Primero, instala el SDK de MCP Auth en tu proyecto de servidor MCP. -import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; - -Ahora necesitamos inicializar MCP Auth en tu servidor MCP. Con el modo de recurso protegido, necesitas configurar tus metadatos de recurso incluyendo los servidores de autorización. +Ahora necesitamos inicializar MCP Auth en tu servidor MCP. Con el modo de recurso protegido, debes configurar tus metadatos de recurso incluyendo los servidores de autorización. Hay dos formas de configurar los servidores de autorización: -- **Pre-obtenido (Recomendado)**: Usa `fetchServerConfig()` para obtener los metadatos antes de inicializar MCPAuth. Esto asegura que la configuración se valide al inicio. -- **Descubrimiento bajo demanda**: Solo proporciona `issuer` y `type` - los metadatos se obtendrán bajo demanda cuando se necesiten por primera vez. Esto es útil para entornos edge (como Cloudflare Workers) donde no se permite fetch asíncrono a nivel superior. +- **Pre-obtenido (Recomendado)**: Usa `fetchServerConfig()` para obtener los metadatos antes de inicializar MCPAuth. Esto asegura que la configuración se valide al iniciar. +- **Descubrimiento bajo demanda**: Solo proporciona `issuer` y `type` - los metadatos se obtendrán bajo demanda la primera vez que se necesiten. Esto es útil para entornos edge (como Cloudflare Workers) donde no se permite fetch asíncrono a nivel superior. #### Configura los metadatos del recurso protegido \{#configure-protected-resource-metadata} -Primero, obtén la URL del emisor de tu servidor de autorización: +Primero, obtén la URL del emisor (Issuer) de tu servidor de autorización: @@ -535,7 +625,7 @@ En Logto, puedes encontrar la URL del emisor en la página de detalles de tu apl Para proveedores OAuth 2.0, deberás: 1. Consultar la documentación de tu proveedor para la URL del servidor de autorización (a menudo llamada issuer URL o base URL) -2. Algunos proveedores pueden exponer esto en `https://{tu-dominio}/.well-known/oauth-authorization-server` +2. Algunos proveedores la exponen en `https://{tu-dominio}/.well-known/oauth-authorization-server` 3. Busca en la consola de administración de tu proveedor bajo la configuración OAuth/API @@ -544,31 +634,249 @@ Para proveedores OAuth 2.0, deberás: Ahora, configura los metadatos del recurso protegido al construir la instancia de MCP Auth: -[El bloque de código se mantiene igual que el original.] +```js +// todo-manager.ts + +import { MCPAuth, fetchServerConfig } from 'mcp-auth'; + +const issuerUrl = ''; // Reemplaza con la URL del emisor de tu servidor de autorización + +// Define el identificador de recurso para este servidor MCP +const resourceId = 'http://localhost:3001/'; + +// Pre-obtén la configuración del servidor de autorización (recomendado) +const authServerConfig = await fetchServerConfig(issuerUrl, { type: 'oidc' }); + +// Configura MCP Auth con los metadatos del recurso protegido +const mcpAuth = new MCPAuth({ + protectedResources: { + metadata: { + resource: resourceId, + authorizationServers: [authServerConfig], + // Alcances (Scopes) que este servidor MCP entiende + scopesSupported: ['create:todos', 'read:todos', 'delete:todos'], + }, + }, +}); +``` ### Actualiza el servidor MCP \{#update-mcp-server} ¡Ya casi terminamos! Es momento de actualizar el servidor MCP para aplicar la ruta y función middleware de MCP Auth, luego implementar el control de acceso basado en permisos para las herramientas del gestor de tareas según los Alcances (Scopes) del usuario. -Ahora, aplica las rutas de metadatos de recurso protegido para que los clientes MCP puedan recuperar los metadatos esperados del recurso desde el servidor MCP. +Ahora, aplica las rutas de metadatos de recurso protegido para que los clientes MCP puedan obtener los metadatos esperados del recurso desde el servidor MCP. -[El bloque de código se mantiene igual que el original.] +```ts +// todo-manager.ts -A continuación, aplicaremos el middleware de MCP Auth al servidor MCP. Este middleware gestionará la Autenticación (Authentication) y Autorización (Authorization) para las solicitudes entrantes, asegurando que solo los usuarios autorizados puedan acceder a las herramientas del gestor de tareas. +// Configura las rutas de metadatos de recurso protegido +// Esto expone metadatos sobre este servidor de recursos para clientes OAuth +app.use(mcpAuth.protectedResourceMetadataRouter()); +``` + +A continuación, aplicaremos el middleware de MCP Auth al servidor MCP. Este middleware manejará la Autenticación (Authentication) y Autorización (Authorization) para las solicitudes entrantes, asegurando que solo los usuarios autorizados puedan acceder a las herramientas del gestor de tareas. + +```ts +// todo-manager.ts -[El bloque de código se mantiene igual que el original.] +app.use(mcpAuth.protectedResourceMetadataRouter()); + +// Aplica el middleware de MCP Auth +app.use( + mcpAuth.bearerAuth('jwt', { + resource: resourceId, + audience: resourceId, + }) +); +``` En este punto, podemos actualizar las herramientas del gestor de tareas para aprovechar el middleware de MCP Auth para Autenticación (Authentication) y Autorización (Authorization). Actualicemos la implementación de las herramientas. -[El bloque de código se mantiene igual que el original.] +```js +// todo-manager.ts + +// otros imports... +import assert from 'node:assert'; +import { fetchServerConfig, MCPAuth, MCPAuthBearerAuthError } from 'mcp-auth'; +import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'; + +// Se mencionará en la siguiente sección +import { TodoService } from './todo-service.js'; + +const assertUserId = (authInfo?: AuthInfo) => { + const { subject } = authInfo ?? {}; + assert(subject, 'Información de autenticación inválida'); + return subject; +}; + +const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { + return requiredScopes.every((scope) => userScopes.includes(scope)); +}; + +const todoService = new TodoService(); + +server.registerTool( + 'create-todo', + { + description: 'Crear una nueva tarea', + inputSchema: { content: z.string() }, + }, + ({ content }, { authInfo }) => { + const userId = assertUserId(authInfo); + + /** + * Solo los usuarios con el Alcance (Scope) 'create:todos' pueden crear tareas + */ + if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { + throw new MCPAuthBearerAuthError('missing_required_scopes'); + } + + const createdTodo = todoService.createTodo({ content, ownerId: userId }); + + return { + content: [{ type: 'text', text: JSON.stringify(createdTodo) }], + }; + } +); + +server.registerTool( + 'get-todos', + { + description: 'Listar todas las tareas', + inputSchema: {}, + }, + (_params, { authInfo }) => { + const userId = assertUserId(authInfo); + + /** + * Si el usuario tiene el Alcance (Scope) 'read:todos', puede acceder a todas las tareas (todoOwnerId = undefined) + * Si el usuario no tiene el Alcance (Scope) 'read:todos', solo puede acceder a sus propias tareas (todoOwnerId = userId) + */ + const todoOwnerId = hasRequiredScopes(authInfo?.scopes ?? [], ['read:todos']) + ? undefined + : userId; + + const todos = todoService.getAllTodos(todoOwnerId); + + return { + content: [{ type: 'text', text: JSON.stringify(todos) }], + }; + } +); + +server.registerTool( + 'delete-todo', + { + description: 'Eliminar una tarea por id', + inputSchema: { id: z.string() }, + }, + ({ id }, { authInfo }) => { + const userId = assertUserId(authInfo); + + const todo = todoService.getTodoById(id); + + if (!todo) { + return { + content: [{ type: 'text', text: JSON.stringify({ error: 'No se pudo eliminar la tarea' }) }], + }; + } + + /** + * Los usuarios solo pueden eliminar sus propias tareas + * Los usuarios con el Alcance (Scope) 'delete:todos' pueden eliminar cualquier tarea + */ + if (todo.ownerId !== userId && !hasRequiredScopes(authInfo?.scopes ?? [], ['delete:todos'])) { + return { + content: [ + { + type: 'text', + text: JSON.stringify({ error: 'No se pudo eliminar la tarea' }), + }, + ], + }; + } + + const deletedTodo = todoService.deleteTodo(id); + + return { + content: [ + { + type: 'text', + text: JSON.stringify({ + message: `Tarea ${id} eliminada`, + details: deletedTodo, + }), + }, + ], + }; + } +); +``` Ahora, crea el "Servicio de tareas" usado en el código anterior para implementar la funcionalidad relacionada: Crea el archivo `todo-service.ts` para el servicio de tareas: -[El bloque de código se mantiene igual que el original.] +```ts +// todo-service.ts + +type Todo = { + id: string; + content: string; + ownerId: string; + createdAt: string; +}; + +/** + * Un servicio de tareas simple para fines demostrativos. + * Usa un array en memoria para almacenar tareas + */ +export class TodoService { + private readonly todos: Todo[] = []; + + getAllTodos(ownerId?: string): Todo[] { + if (ownerId) { + return this.todos.filter((todo) => todo.ownerId === ownerId); + } + return this.todos; + } + + getTodoById(id: string): Todo | undefined { + return this.todos.find((todo) => todo.id === id); + } + + createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo { + const todo: Todo = { + id: this.genId(), + content, + ownerId, + createdAt: new Date().toISOString(), + }; + + // eslint-disable-next-line @silverhand/fp/no-mutating-methods + this.todos.push(todo); + return todo; + } + + deleteTodo(id: string): Todo | undefined { + const index = this.todos.findIndex((todo) => todo.id === id); + + if (index === -1) { + return undefined; + } + + // eslint-disable-next-line @silverhand/fp/no-mutating-methods + const [deleted] = this.todos.splice(index, 1); + return deleted; + } + + private genId(): string { + return Math.random().toString(36).slice(2, 10); + } +} +``` ¡Felicidades! ¡Hemos implementado con éxito un servidor MCP completo con Autenticación (Authentication) y Autorización (Authorization)! @@ -578,9 +886,17 @@ Consulta el [repositorio del SDK de MCP Auth para Node.js](https://github.com/mc ## Punto de control: Ejecuta las herramientas `todo-manager` \{#checkpoint-run-the-todo-manager-tools} -Reinicia tu servidor MCP y abre el MCP inspector en tu navegador. Cuando hagas clic en el botón "Connect", deberías ser redirigido a la página de inicio de sesión de tu servidor de autorización. +Reinicia tu servidor MCP y conecta VS Code a él. Así es como puedes conectarte con autenticación: + +1. En VS Code, presiona `Command + Shift + P` (macOS) o `Ctrl + Shift + P` (Windows/Linux) para abrir la paleta de comandos. +2. Escribe `MCP: Add Server...` y selecciónalo. +3. Elige `HTTP` como tipo de servidor. +4. Ingresa la URL del servidor MCP: `http://localhost:3001` +5. Después de que se inicie una solicitud OAuth, VS Code te pedirá que ingreses el **App ID**. Ingresa el App ID que copiaste de tu servidor de autorización. +6. Como no tenemos un **App Secret** (es un cliente público), simplemente presiona Enter para omitir. +7. Completa el flujo de inicio de sesión en tu navegador. -Una vez que inicies sesión y regreses al MCP inspector, repite las acciones que hicimos en el punto de control anterior para ejecutar las herramientas del gestor de tareas. Esta vez, puedes usar estas herramientas con tu identidad de usuario autenticada. El comportamiento de las herramientas dependerá de los roles y permisos asignados a tu usuario: +Una vez que inicies sesión y regreses a VS Code, repite las acciones que hicimos en el punto de control anterior para ejecutar las herramientas del gestor de tareas. Esta vez, puedes usar estas herramientas con tu identidad de usuario autenticada. El comportamiento de las herramientas dependerá de los Roles (Roles) y Permisos (Permissions) asignados a tu usuario: - Si has iniciado sesión como **User** (con solo el Alcance (Scope) `create:todos`): @@ -595,14 +911,12 @@ Una vez que inicies sesión y regreses al MCP inspector, repite las acciones que Puedes probar estos diferentes niveles de permisos: -1. Cerrando la sesión actual (haz clic en el botón "Disconnect" en MCP inspector) -2. Iniciando sesión con otra cuenta de usuario que tenga diferentes roles/permisos +1. Desconectándote del servidor MCP (elimina la configuración del servidor en VS Code) +2. Iniciando sesión con una cuenta de usuario diferente que tenga diferentes Roles (Roles)/Permisos (Permissions) 3. Probando las mismas herramientas nuevamente para observar cómo cambia el comportamiento según los permisos del usuario Esto demuestra cómo funciona el control de acceso basado en roles (RBAC) en la práctica, donde diferentes usuarios tienen diferentes niveles de acceso a la funcionalidad del sistema. -![Resultado de la herramienta gestor de tareas en MCP inspector](/docs-assets/images/tutorials/todo-manager/result.png) - :::info Consulta el [repositorio del SDK de MCP Auth para Node.js](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) para ver el código completo del servidor MCP (versión OIDC). ::: @@ -614,6 +928,6 @@ Consulta el [repositorio del SDK de MCP Auth para Node.js](https://github.com/mc - Configuración de un servidor MCP básico con herramientas de gestión de tareas (`create-todo`, `get-todos`, `delete-todo`) - Implementación de control de acceso basado en roles (RBAC) con diferentes niveles de permisos para usuarios y administradores - Integración del servidor MCP con un servidor de autorización usando MCP Auth -- Configuración del MCP Inspector para autenticar usuarios y usar tokens de acceso con Alcances (Scopes) para llamar a herramientas +- Configuración de VS Code para autenticar usuarios y usar tokens de acceso con Alcances (Scopes) para llamar a herramientas Asegúrate de consultar otros tutoriales y documentación para aprovechar al máximo MCP Auth. \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md b/i18n/fr/docusaurus-plugin-content-docs/current/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md index 80c12da..74bb257 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md @@ -16,7 +16,7 @@ type MCPAuthBearerAuthErrorDetails = { ## Propriétés {#properties} -### actual ? {#actual} +### actual? {#actual} ```ts optional actual: unknown; @@ -24,7 +24,7 @@ optional actual: unknown; *** -### cause ? {#cause} +### cause? {#cause} ```ts optional cause: unknown; @@ -32,7 +32,7 @@ optional cause: unknown; *** -### expected ? {#expected} +### expected? {#expected} ```ts optional expected: unknown; @@ -40,7 +40,7 @@ optional expected: unknown; *** -### missingScopes ? {#missingscopes} +### missingScopes? {#missingscopes} ```ts optional missingScopes: string[]; @@ -48,7 +48,7 @@ optional missingScopes: string[]; *** -### uri ? {#uri} +### uri? {#uri} ```ts optional uri: URL; diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/references/js/type-aliases/ResourceServerModeConfig.md b/i18n/fr/docusaurus-plugin-content-docs/current/references/js/type-aliases/ResourceServerModeConfig.md index 69361eb..b059862 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/references/js/type-aliases/ResourceServerModeConfig.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/references/js/type-aliases/ResourceServerModeConfig.md @@ -20,4 +20,4 @@ Configuration pour le serveur MCP en mode serveur de ressources. protectedResources: ResourceServerConfig | ResourceServerConfig[]; ``` -Une configuration unique de serveur de ressources ou un tableau de celles-ci. \ No newline at end of file +Une configuration unique de serveur de ressources ou un tableau de celles-ci. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/references/js/type-aliases/VerifyAccessTokenFunction.md b/i18n/fr/docusaurus-plugin-content-docs/current/references/js/type-aliases/VerifyAccessTokenFunction.md index 4a43c15..9dcc1f7 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/references/js/type-aliases/VerifyAccessTokenFunction.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/references/js/type-aliases/VerifyAccessTokenFunction.md @@ -19,9 +19,9 @@ valider son expiration et extraire les revendications (Claims) nécessaires pour **Remarque :** Il n'est pas nécessaire de vérifier les champs suivants dans le jeton, car ils seront contrôlés par le gestionnaire : -- `iss` (Émetteur / Issuer) +- `iss` (Émetteur (Issuer)) - `aud` (Audience) -- `scope` (Portées / Scopes) +- `scope` (Portées (Scopes)) ## Paramètres {#parameters} diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index e36b64c..ce46eed 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -3,6 +3,7 @@ sidebar_position: 2 sidebar_label: 'Tutoriel : Créer un gestionnaire de tâches' --- +import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -12,24 +13,25 @@ import Tabs from '@theme/Tabs'; MCP Auth est également disponible pour Python ! Consultez le [dépôt SDK Python](https://github.com/mcp-auth/python) pour l'installation et l'utilisation. ::: -Dans ce tutoriel, nous allons construire un serveur MCP gestionnaire de tâches avec authentification et autorisation des utilisateurs. En suivant la dernière spécification MCP, notre serveur MCP agira comme un **Serveur de ressources** OAuth 2.0 qui valide les jetons d’accès et applique les permissions basées sur la portée (scope). +Dans ce tutoriel, nous allons construire un serveur MCP gestionnaire de tâches avec authentification et autorisation des utilisateurs. En suivant la dernière spécification MCP, notre serveur MCP agira en tant que **Serveur de ressources** OAuth 2.0 qui valide les jetons d’accès et applique les permissions basées sur la portée (scope). Après avoir terminé ce tutoriel, vous aurez : - ✅ Une compréhension de base de la mise en place du contrôle d’accès basé sur les rôles (RBAC) dans votre serveur MCP. -- ✅ Un serveur MCP qui agit comme Serveur de ressources, consommant des jetons d’accès émis par un Serveur d’autorisation. -- ✅ Une implémentation fonctionnelle de l’application des permissions basées sur la portée pour les opérations de gestion des tâches. +- ✅ Un serveur MCP qui agit comme un Serveur de ressources, consommant des jetons d’accès émis par un Serveur d’autorisation. +- ✅ Une implémentation fonctionnelle de l’application des permissions basées sur la portée pour les opérations sur les tâches. ## Vue d’ensemble \{#overview} Le tutoriel impliquera les composants suivants : -- **Client MCP (MCP Inspector)** : Un outil de test visuel pour les serveurs MCP qui agit comme un client OAuth 2.0 / OIDC. Il initie le flux d’autorisation avec le serveur d’autorisation et obtient des jetons d’accès pour authentifier les requêtes vers le serveur MCP. +- **Client MCP (VS Code)** : Un éditeur de code avec prise en charge MCP intégrée qui agit comme un client OAuth 2.0 / OIDC. Il initie le flux d’autorisation avec le serveur d’autorisation et obtient des jetons d’accès pour authentifier les requêtes vers le serveur MCP. - **Serveur d’autorisation** : Un fournisseur OAuth 2.1 ou OpenID Connect qui gère les identités des utilisateurs, authentifie les utilisateurs et émet des jetons d’accès avec les portées appropriées aux clients autorisés. - **Serveur MCP (Serveur de ressources)** : Selon la dernière spécification MCP, le serveur MCP agit comme un Serveur de ressources dans le cadre OAuth 2.0. Il valide les jetons d’accès émis par le serveur d’autorisation et applique les permissions basées sur la portée pour les opérations sur les tâches. Cette architecture suit le flux standard OAuth 2.0 où : -- Le **MCP Inspector** demande des ressources protégées au nom de l’utilisateur + +- **VS Code** demande des ressources protégées au nom de l’utilisateur - Le **Serveur d’autorisation** authentifie l’utilisateur et émet des jetons d’accès - Le **Serveur MCP** valide les jetons et sert les ressources protégées selon les permissions accordées @@ -38,7 +40,7 @@ Voici un schéma de haut niveau de l’interaction entre ces composants : ```mermaid sequenceDiagram autonumber - participant Client as MCP Inspector
(Client OAuth) + participant Client as VS Code
(Client OAuth) participant RS as Serveur MCP
(Serveur de ressources) participant AS as Serveur d’autorisation @@ -75,13 +77,13 @@ Pour mettre en œuvre le [contrôle d’accès basé sur les rôles (RBAC)](http 2. Créez une ressource API et des portées : - Allez dans "Ressources API" - - Créez une nouvelle ressource API nommée "Gestionnaire de tâches" + - Créez une nouvelle ressource API nommée "Todo Manager" - Ajoutez les portées suivantes : - - `create:todos` : "Créer de nouvelles tâches" - - `read:todos` : "Lire toutes les tâches" - - `delete:todos` : "Supprimer n’importe quelle tâche" + - `create:todos` : "Créer de nouveaux éléments de tâches" + - `read:todos` : "Lire tous les éléments de tâches" + - `delete:todos` : "Supprimer n’importe quel élément de tâche" -3. Créez des rôles (recommandé pour une gestion plus simple) : +3. Créez des rôles (recommandé pour une gestion plus facile) : - Allez dans "Rôles" - Créez un rôle "Admin" et assignez toutes les portées (`create:todos`, `read:todos`, `delete:todos`) @@ -91,8 +93,8 @@ Pour mettre en œuvre le [contrôle d’accès basé sur les rôles (RBAC)](http - Allez dans "Utilisateurs" - Sélectionnez un utilisateur - Vous pouvez soit : - - Assigner des rôles dans l’onglet "Rôles" (recommandé) - - Ou assigner directement des portées dans l’onglet "Permissions" + - Attribuer des rôles dans l’onglet "Rôles" (recommandé) + - Ou attribuer directement des portées dans l’onglet "Permissions" Les portées seront incluses dans la revendication `scope` du jeton d’accès JWT sous forme de chaîne séparée par des espaces. @@ -106,11 +108,11 @@ Les fournisseurs OAuth 2.0 / OIDC prennent généralement en charge le contrôle 3. Assurez-vous que votre serveur d’autorisation inclut les portées accordées dans le jeton d’accès 4. Les portées sont généralement incluses dans la revendication `scope` du jeton d’accès JWT -Consultez la documentation de votre fournisseur pour les détails spécifiques sur : +Consultez la documentation de votre fournisseur pour plus de détails sur : - Comment définir et gérer les portées - Comment les portées sont incluses dans le jeton d’accès -- D’éventuelles fonctionnalités RBAC supplémentaires comme la gestion des rôles +- Toutes fonctionnalités RBAC supplémentaires comme la gestion des rôles @@ -120,8 +122,8 @@ Consultez la documentation de votre fournisseur pour les détails spécifiques s Selon la dernière spécification MCP, le serveur MCP agit comme un **Serveur de ressources** dans le cadre OAuth 2.0. En tant que Serveur de ressources, le serveur MCP a les responsabilités suivantes : 1. **Validation du jeton** : Vérifier l’authenticité et l’intégrité des jetons d’accès reçus des clients MCP -2. **Application des portées** : Extraire et valider les portées du jeton d’accès pour déterminer les opérations autorisées pour le client -3. **Protection des ressources** : Ne servir les ressources protégées (exécuter des outils) que lorsque le client présente des jetons valides avec des permissions suffisantes +2. **Application des portées** : Extraire et valider les portées du jeton d’accès pour déterminer quelles opérations le client est autorisé à effectuer +3. **Protection des ressources** : Ne servir les ressources protégées (exécuter les outils) que lorsque le client présente des jetons valides avec des permissions suffisantes Lorsque votre serveur MCP reçoit une requête, il effectue le processus de validation suivant : @@ -140,13 +142,13 @@ sequenceDiagram Client->>Server: Requête avec jeton d’accès
(Authorization: Bearer ) - alt Validation JWT (Préféré) + alt Validation JWT (Préférée) Server->>Auth: Récupérer JWKS (si non en cache) - Auth-->>Server: Retourner JWKS - Server->>Server: Valider localement la signature & les revendications du JWT + Auth-->>Server: Retourne JWKS + Server->>Server: Valider la signature JWT & les revendications localement else Introspection du jeton (Fallback) Server->>Auth: POST /introspect
(token=access_token) - Auth-->>Server: Retourner infos du jeton
(active, scope, user_id, etc.) + Auth-->>Server: Retourne infos du jeton
(active, scope, user_id, etc.) end Server->>Server: Extraire portées & contexte utilisateur
du jeton validé @@ -159,9 +161,9 @@ sequenceDiagram end ``` -### Enregistrement dynamique de client \{#dynamic-client-registration} +### Enregistrement dynamique du client \{#dynamic-client-registration} -L’enregistrement dynamique de client n’est pas requis pour ce tutoriel, mais il peut être utile si vous souhaitez automatiser le processus d’enregistrement du client MCP auprès de votre serveur d’autorisation. Consultez [L’enregistrement dynamique de client est-il requis ?](/provider-list#is-dcr-required) pour plus de détails. +L’enregistrement dynamique du client n’est pas requis pour ce tutoriel, mais il peut être utile si vous souhaitez automatiser le processus d’enregistrement du client MCP auprès de votre serveur d’autorisation. Consultez [L’enregistrement dynamique du client est-il requis ?](/provider-list#is-dcr-required) pour plus de détails. ## Comprendre le RBAC dans le gestionnaire de tâches \{#understand-rbac-in-todo-manager} @@ -173,7 +175,7 @@ Bien que ce tutoriel démontre la gestion des portées basée sur le RBAC, il es ### Outils et portées \{#tools-and-scopes} -Notre serveur MCP gestionnaire de tâches propose trois outils principaux : +Notre serveur MCP gestionnaire de tâches fournit trois outils principaux : - `create-todo` : Créer une nouvelle tâche - `get-todos` : Lister toutes les tâches @@ -194,8 +196,8 @@ Nous allons définir deux rôles avec différents niveaux d’accès : | Admin | ✅ | ✅ | ✅ | | User | ✅ | | | -- **User** : Un utilisateur classique qui peut créer des tâches et voir ou supprimer uniquement ses propres tâches -- **Admin** : Un administrateur qui peut créer, voir et supprimer toutes les tâches, quelle que soit leur propriété +- **User** : Un utilisateur régulier qui peut créer des tâches et voir ou supprimer uniquement ses propres tâches +- **Admin** : Un administrateur qui peut créer, voir et supprimer toutes les tâches, quel que soit le propriétaire ### Propriété des ressources \{#resource-ownership} @@ -206,43 +208,43 @@ Bien que le tableau des permissions ci-dessus montre les portées explicites att - Supprimer leurs propres tâches - **Les admins** ont toutes les permissions (`read:todos` et `delete:todos`), ce qui leur permet de : - Voir toutes les tâches du système - - Supprimer n’importe quelle tâche, quelle que soit la propriété + - Supprimer n’importe quelle tâche, quel que soit le propriétaire -Cela illustre un schéma courant dans les systèmes RBAC où la propriété d’une ressource accorde des permissions implicites à l’utilisateur pour ses propres ressources, tandis que les rôles administratifs reçoivent des permissions explicites pour toutes les ressources. +Cela illustre un schéma courant dans les systèmes RBAC où la propriété d’une ressource accorde des permissions implicites aux utilisateurs pour leurs propres ressources, tandis que les rôles administratifs reçoivent des permissions explicites pour toutes les ressources. :::tip En savoir plus -Pour approfondir les concepts et bonnes pratiques RBAC, consultez [Maîtriser le RBAC : Un exemple complet et réel](https://blog.logto.io/mastering-rbac). +Pour approfondir les concepts et bonnes pratiques du RBAC, consultez [Maîtriser le RBAC : Un exemple complet et concret](https://blog.logto.io/mastering-rbac). ::: ## Configurer l’autorisation dans votre fournisseur \{#configure-authorization-in-your-provider} -Pour mettre en œuvre le système de contrôle d’accès décrit précédemment, vous devrez configurer votre serveur d’autorisation pour prendre en charge les portées requises. Voici comment faire selon les fournisseurs : +Pour mettre en œuvre le système de contrôle d’accès décrit précédemment, vous devrez configurer votre serveur d’autorisation pour prendre en charge les portées requises. Voici comment faire avec différents fournisseurs : -[Logto](https://logto.io) propose la gestion RBAC via ses ressources API et ses fonctionnalités de rôles. Voici comment le configurer : +[Logto](https://logto.io) propose la prise en charge du RBAC via ses ressources API et ses fonctionnalités de rôles. Voici comment le configurer : 1. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre propre instance Logto Console) 2. Créez une ressource API et des portées : - Allez dans "Ressources API" - - Créez une nouvelle ressource API nommée "Gestionnaire de tâches" et utilisez `http://localhost:3001` comme indicateur de ressource. - - **Important** : L’indicateur de ressource doit correspondre à l’URL de votre serveur MCP. Pour ce tutoriel, nous utilisons `http://localhost:3001` car notre serveur MCP tourne sur le port 3001. En production, utilisez l’URL réelle de votre serveur MCP (par exemple, `https://votre-mcp-server.example.com`). + - Créez une nouvelle ressource API nommée "Todo Manager" en utilisant `http://localhost:3001/` comme indicateur de ressource. + - **Important** : L’indicateur de ressource doit correspondre à l’URL de votre serveur MCP. Pour ce tutoriel, nous utilisons `http://localhost:3001/` puisque notre serveur MCP tourne sur le port 3001. En production, utilisez l’URL réelle de votre serveur MCP (par exemple, `https://your-mcp-server.example.com/`). - Créez les portées suivantes : - - `create:todos` : "Créer de nouvelles tâches" - - `read:todos` : "Lire toutes les tâches" - - `delete:todos` : "Supprimer n’importe quelle tâche" + - `create:todos` : "Créer de nouveaux éléments de tâches" + - `read:todos` : "Lire tous les éléments de tâches" + - `delete:todos` : "Supprimer n’importe quel élément de tâche" -3. Créez des rôles (recommandé pour une gestion plus simple) : +3. Créez des rôles (recommandé pour une gestion plus facile) : - Allez dans "Rôles" - Créez un rôle "Admin" et assignez toutes les portées (`create:todos`, `read:todos`, `delete:todos`) - Créez un rôle "User" et assignez uniquement la portée `create:todos` - Dans la page de détails du rôle "User", passez à l’onglet "Général" et définissez le rôle "User" comme "Rôle par défaut". -4. Gérez les rôles et permissions des utilisateurs : +4. Gérer les rôles et permissions des utilisateurs : - Pour les nouveaux utilisateurs : - Ils recevront automatiquement le rôle "User" puisque nous l’avons défini comme rôle par défaut - Pour les utilisateurs existants : @@ -250,16 +252,16 @@ Pour mettre en œuvre le système de contrôle d’accès décrit précédemment - Sélectionnez un utilisateur - Attribuez des rôles à l’utilisateur dans l’onglet "Rôles" -:::tip Gestion programmatique des rôles -Vous pouvez également utiliser la [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) de Logto pour gérer les rôles des utilisateurs de manière programmatique. C’est particulièrement utile pour la gestion automatisée des utilisateurs ou lors de la création de panneaux d’administration. +:::tip Gestion des rôles par API +Vous pouvez également utiliser la [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) de Logto pour gérer les rôles des utilisateurs de manière programmatique. Ceci est particulièrement utile pour la gestion automatisée des utilisateurs ou lors de la création de panneaux d’administration. ::: -Lors de la demande d’un jeton d’accès, Logto inclura les portées dans la revendication `scope` du jeton selon les permissions du rôle de l’utilisateur. +Lors de la demande d’un jeton d’accès, Logto inclura les portées dans la revendication `scope` du jeton en fonction des permissions de rôle de l’utilisateur. -Pour les fournisseurs OAuth 2.0 ou OpenID Connect, vous devrez configurer les portées qui représentent les différentes permissions. Les étapes exactes dépendront de votre fournisseur, mais généralement : +Pour les fournisseurs OAuth 2.0 ou OpenID Connect, vous devrez configurer les portées qui représentent différentes permissions. Les étapes exactes dépendront de votre fournisseur, mais en général : 1. Définir les portées : @@ -275,7 +277,7 @@ Pour les fournisseurs OAuth 2.0 ou OpenID Connect, vous devrez configurer les po 3. Attribuer les permissions : - Utilisez l’interface de votre fournisseur pour accorder les portées appropriées aux utilisateurs - - Certains fournisseurs prennent en charge la gestion basée sur les rôles, d’autres utilisent l’attribution directe de portées + - Certains fournisseurs peuvent prendre en charge la gestion basée sur les rôles, tandis que d’autres utilisent des attributions de portées directes - Consultez la documentation de votre fournisseur pour la méthode recommandée :::tip @@ -285,11 +287,15 @@ La plupart des fournisseurs incluront les portées accordées dans la revendicat +:::note[Barre oblique finale dans l’indicateur de ressource] +Incluez toujours une barre oblique finale (`/`) dans l’indicateur de ressource. En raison d’un bug actuel dans le SDK officiel MCP, les clients utilisant le SDK ajouteront automatiquement une barre oblique finale aux identifiants de ressource lors de l’initiation des requêtes d’authentification. Si votre indicateur de ressource n’inclut pas la barre oblique, la validation de la ressource échouera pour ces clients. (VS Code n’est pas affecté par ce bug.) +::: + Après avoir configuré votre serveur d’autorisation, les utilisateurs recevront des jetons d’accès contenant leurs portées accordées. Le serveur MCP utilisera ces portées pour déterminer : - Si un utilisateur peut créer de nouvelles tâches (`create:todos`) -- S’il peut voir toutes les tâches (`read:todos`) ou seulement les siennes -- S’il peut supprimer n’importe quelle tâche (`delete:todos`) ou seulement les siennes +- Si un utilisateur peut voir toutes les tâches (`read:todos`) ou seulement les siennes +- Si un utilisateur peut supprimer n’importe quelle tâche (`delete:todos`) ou seulement les siennes ## Mettre en place le serveur MCP \{#set-up-the-mcp-server} @@ -309,7 +315,7 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -Nous utilisons TypeScript dans nos exemples car Node.js v22.6.0+ prend en charge l’exécution native de TypeScript avec l’option `--experimental-strip-types`. Si vous utilisez JavaScript, le code sera similaire – assurez-vous simplement d’utiliser Node.js v22.6.0 ou plus récent. Voir la documentation Node.js pour plus de détails. +Nous utilisons TypeScript dans nos exemples car Node.js v22.6.0+ prend en charge l’exécution native de TypeScript avec l’option `--experimental-strip-types`. Si vous utilisez JavaScript, le code sera similaire – assurez-vous simplement d’utiliser Node.js v22.6.0 ou ultérieur. Voir la documentation Node.js pour plus de détails. ::: ### Installer le SDK MCP et les dépendances \{#install-the-mcp-sdk-and-dependencies} @@ -324,7 +330,126 @@ Ou tout autre gestionnaire de paquets que vous préférez, comme `pnpm` ou `yarn Créez un fichier nommé `todo-manager.ts` et ajoutez le code suivant : -[Le code TypeScript reste inchangé, conformément aux instructions.] +```ts +// todo-manager.ts + +import { z } from 'zod'; +import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; +import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; +import express, { type Request, type Response } from 'express'; + +// Créer un serveur MCP +const server = new McpServer({ + name: 'Todo Manager', + version: '0.0.0', +}); + +server.registerTool( + 'create-todo', + { + description: 'Créer une nouvelle tâche', + inputSchema: { content: z.string() }, + }, + async ({ content }) => { + return { + content: [{ type: 'text', text: JSON.stringify({ error: 'Non implémenté' }) }], + }; + } +); + +server.registerTool( + 'get-todos', + { + description: 'Lister toutes les tâches', + inputSchema: {}, + }, + async () => { + return { + content: [{ type: 'text', text: JSON.stringify({ error: 'Non implémenté' }) }], + }; + } +); + +server.registerTool( + 'delete-todo', + { + description: 'Supprimer une tâche par id', + inputSchema: { id: z.string() }, + }, + async ({ id }) => { + return { + content: [{ type: 'text', text: JSON.stringify({ error: 'Non implémenté' }) }], + }; + } +); + +// Ci-dessous le code standard issu de la documentation du SDK MCP +const PORT = 3001; +const app = express(); + +app.post('/', async (request: Request, response: Response) => { + // En mode stateless, créez une nouvelle instance de transport et de serveur pour chaque requête + // afin d’assurer une isolation complète. Une seule instance causerait des collisions d’ID de requête + // lorsque plusieurs clients se connectent simultanément. + + try { + const transport: StreamableHTTPServerTransport = new StreamableHTTPServerTransport({ + sessionIdGenerator: undefined, + }); + response.on('close', async () => { + console.log('Requête fermée'); + await transport.close(); + await server.close(); + }); + await server.connect(transport); + await transport.handleRequest(request, response, request.body); + } catch (error) { + console.error('Erreur lors du traitement de la requête MCP :', error); + if (!response.headersSent) { + response.status(500).json({ + jsonrpc: '2.0', + error: { + code: -32_603, + message: 'Erreur interne du serveur', + }, + id: null, + }); + } + } +}); + +// Les notifications SSE ne sont pas prises en charge en mode stateless +app.get('/', async (request: Request, response: Response) => { + console.log('Reçu une requête GET MCP'); + response.writeHead(405).end( + JSON.stringify({ + jsonrpc: '2.0', + error: { + code: -32_000, + message: 'Méthode non autorisée.', + }, + id: null, + }) + ); +}); + +// La terminaison de session n’est pas nécessaire en mode stateless +app.delete('/', async (request: Request, response: Response) => { + console.log('Reçu une requête DELETE MCP'); + response.writeHead(405).end( + JSON.stringify({ + jsonrpc: '2.0', + error: { + code: -32_000, + message: 'Méthode non autorisée.', + }, + id: null, + }) + ); +}); + +app.listen(PORT); +``` Lancez le serveur avec : @@ -332,52 +457,14 @@ Lancez le serveur avec : npm start ``` -## Inspecter le serveur MCP \{#inspect-the-mcp-server} - -### Cloner et lancer MCP inspector \{#clone-and-run-mcp-inspector} - -Maintenant que nous avons le serveur MCP en fonctionnement, nous pouvons utiliser le MCP inspector pour vérifier si les outils sont disponibles. - -La version officielle MCP inspector v0.16.2 présente quelques bugs affectant la fonctionnalité d’authentification. Pour y remédier, nous avons créé une [version corrigée du MCP inspector](https://github.com/mcp-auth/inspector/tree/patch/0.16.2-fixes) incluant les correctifs nécessaires pour les flux d’authentification OAuth / OIDC. Nous avons également soumis des pull requests au dépôt officiel pour contribuer ces correctifs en amont. - -Pour lancer le MCP inspector, utilisez la commande suivante (Node.js requis) : - -```bash -git clone https://github.com/mcp-auth/inspector.git -b patch/0.16.2-fixes -cd inspector -npm install -npm run dev -``` - -Le MCP inspector s’ouvrira automatiquement dans votre navigateur par défaut, ou vous pouvez y accéder manuellement en cliquant sur le lien affiché dans le terminal (assurez-vous de cliquer sur le lien contenant le paramètre `MCP_PROXY_AUTH_TOKEN`, tel que `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=458ae4a4...acab1907`). - -### Connecter MCP inspector au serveur MCP \{#connect-mcp-inspector-to-the-mcp-server} - -Avant de continuer, vérifiez la configuration suivante dans MCP inspector : - -- **Type de transport** : Réglez sur `Streamable HTTP`. -- **URL** : Réglez sur l’URL de votre serveur MCP. Dans notre cas, ce sera `http://localhost:3001`. - -Vous pouvez maintenant cliquer sur le bouton "Connect" pour voir si le MCP inspector peut se connecter au serveur MCP. Si tout est correct, vous devriez voir le statut "Connected" dans MCP inspector. - -### Point de contrôle : Exécuter les outils du gestionnaire de tâches \{#checkpoint-run-todo-manager-tools} - -1. Dans le menu supérieur du MCP inspector, cliquez sur l’onglet "Tools". -2. Cliquez sur le bouton "List Tools". -3. Vous devriez voir les outils `create-todo`, `get-todos` et `delete-todo` listés sur la page. Cliquez dessus pour ouvrir les détails de l’outil. -4. Vous devriez voir le bouton "Run Tool" à droite. Cliquez dessus et saisissez les paramètres requis pour exécuter l’outil. -5. Vous devriez voir le résultat de l’outil avec la réponse JSON `{"error": "Not implemented"}`. - -![Premier lancement du MCP inspector](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - ## Intégrer avec votre serveur d’autorisation \{#integrate-with-your-authorization-server} -Pour compléter cette section, plusieurs points sont à prendre en compte : +Pour compléter cette section, plusieurs considérations sont à prendre en compte :
-**L’URL de l’émetteur (issuer) de votre serveur d’autorisation** +**L’URL de l’émetteur de votre serveur d’autorisation** -C’est généralement l’URL de base de votre serveur d’autorisation, comme `https://auth.example.com`. Certains fournisseurs peuvent avoir un chemin comme `https://example.logto.app/oidc`, vérifiez donc la documentation de votre fournisseur. +Il s’agit généralement de l’URL de base de votre serveur d’autorisation, comme `https://auth.example.com`. Certains fournisseurs peuvent avoir un chemin comme `https://example.logto.app/oidc`, alors vérifiez la documentation de votre fournisseur.
@@ -390,17 +477,17 @@ C’est généralement l’URL de base de votre serveur d’autorisation, comme
-**Comment enregistrer MCP inspector comme client dans votre serveur d’autorisation** +**Comment enregistrer le client MCP dans votre serveur d’autorisation** -- Si votre serveur d’autorisation prend en charge [l’enregistrement dynamique de client](https://datatracker.ietf.org/doc/html/rfc7591), vous pouvez ignorer cette étape car MCP inspector s’enregistrera automatiquement comme client. -- Si votre serveur d’autorisation ne prend pas en charge l’enregistrement dynamique, vous devrez enregistrer manuellement MCP inspector comme client dans votre serveur d’autorisation. +- Si votre serveur d’autorisation prend en charge [l’enregistrement dynamique du client](https://datatracker.ietf.org/doc/html/rfc7591), vous pouvez ignorer cette étape car le client MCP s’enregistrera automatiquement. +- Si votre serveur d’autorisation ne prend pas en charge l’enregistrement dynamique du client, vous devrez enregistrer manuellement le client MCP dans votre serveur d’autorisation.
-**Comprendre les paramètres de la requête de jeton** +**Comprendre les paramètres de requête de jeton** -Lors de la demande de jetons d’accès auprès de différents serveurs d’autorisation, vous rencontrerez diverses approches pour spécifier la ressource cible et les permissions. Voici les principaux schémas : +Lorsque vous demandez des jetons d’accès à différents serveurs d’autorisation, vous rencontrerez diverses approches pour spécifier la ressource cible et les permissions. Voici les principaux schémas : - **Basé sur l’indicateur de ressource** : @@ -409,7 +496,7 @@ Lors de la demande de jetons d’accès auprès de différents serveurs d’auto - Exemple de requête : ```json { - "resource": "http://localhost:3001", + "resource": "http://localhost:3001/", "scope": "create:todos read:todos" } ``` @@ -418,7 +505,7 @@ Lors de la demande de jetons d’accès auprès de différents serveurs d’auto - **Basé sur l’audience** : - Utilise le paramètre `audience` pour spécifier le destinataire prévu du jeton - - Semblable aux indicateurs de ressource mais avec des sémantiques différentes + - Semblable aux indicateurs de ressource mais avec une sémantique différente - Exemple de requête : ```json { @@ -444,32 +531,36 @@ Lors de la demande de jetons d’accès auprès de différents serveurs d’auto - Consultez la documentation de votre fournisseur pour les paramètres pris en charge - Certains fournisseurs prennent en charge plusieurs approches simultanément - Les indicateurs de ressource offrent une meilleure sécurité via la restriction d’audience -- Privilégiez les indicateurs de ressource lorsque disponibles pour un meilleur contrôle d’accès +- Envisagez d’utiliser les indicateurs de ressource lorsque c’est possible pour un meilleur contrôle d’accès :::
-Bien que chaque fournisseur puisse avoir ses propres exigences spécifiques, les étapes suivantes vous guideront pour intégrer MCP inspector et le serveur MCP avec des configurations spécifiques au fournisseur. +Bien que chaque fournisseur puisse avoir ses propres exigences spécifiques, les étapes suivantes vous guideront dans l’intégration de VS Code et du serveur MCP avec des configurations spécifiques au fournisseur. -### Enregistrer MCP inspector comme client \{#register-mcp-inspector-as-a-client} +### Enregistrer le client MCP comme application tierce \{#register-mcp-client-as-a-third-party-app} -L’intégration du gestionnaire de tâches avec [Logto](https://logto.io) est simple car il s’agit d’un fournisseur OpenID Connect qui prend en charge les indicateurs de ressource et les portées, vous permettant de sécuriser votre API de tâches avec `http://localhost:3001` comme indicateur de ressource. - -Comme Logto ne prend pas encore en charge l’enregistrement dynamique de client, vous devrez enregistrer manuellement MCP inspector comme client dans votre tenant Logto : - -1. Ouvrez votre MCP inspector, allez dans la configuration Authentification et cliquez sur la configuration "OAuth2.0 Flow". Copiez la valeur **Redirect URI**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. -2. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre propre instance Logto Console). -3. Accédez à l’onglet "Applications", cliquez sur "Créer une application". En bas de la page, cliquez sur "Créer une application sans framework". -4. Remplissez les détails de l’application, puis cliquez sur "Créer l’application" : - - **Sélectionnez un type d’application** : Choisissez "Application monopage". - - **Nom de l’application** : Saisissez un nom, par exemple "MCP Inspector". -5. Dans la section "Paramètres / URI de redirection", collez la valeur **Redirect URI** copiée depuis MCP inspector. Cliquez ensuite sur "Enregistrer les modifications" dans la barre du bas. -6. Dans la carte du haut, vous verrez la valeur "App ID". Copiez-la. -7. Retournez dans MCP inspector et collez la valeur "App ID" dans la configuration Authentification sous "OAuth2.0 Flow" dans le champ "Client ID". -8. Dans le champ "Scope", saisissez : `create:todos read:todos delete:todos`. Cela garantira que le jeton d’accès retourné par Logto contient les portées nécessaires pour accéder au gestionnaire de tâches. +L’intégration du gestionnaire de tâches avec [Logto](https://logto.io) est simple puisqu’il s’agit d’un fournisseur OpenID Connect qui prend en charge les indicateurs de ressource et les portées, vous permettant de sécuriser votre API de tâches avec `http://localhost:3001/` comme indicateur de ressource. + +Comme Logto ne prend pas encore en charge l’enregistrement dynamique du client, vous devrez enregistrer manuellement votre client MCP (VS Code) comme application tierce dans votre tenant Logto : + +1. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre propre instance Logto Console). +2. Naviguez vers **Applications > Applications tierces** et cliquez sur "Créer une application". +3. Sélectionnez **Application native** comme type d’application. +4. Renseignez les détails de l’application : + - **Nom de l’application** : Entrez un nom, par exemple "MCP Client". + - **Description** : Entrez une description, par exemple "Client MCP pour VS Code". +5. Définissez les **URI de redirection** suivants pour VS Code : + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` +6. Cliquez sur "Enregistrer les modifications". +7. Allez dans l’onglet **Permissions** de l’application, sous la section **Utilisateur**, ajoutez les permissions `create:todos`, `read:todos` et `delete:todos` de la ressource API **Todo Manager** que vous avez créée précédemment. +8. Dans la carte supérieure, vous verrez la valeur "App ID". Copiez-la pour une utilisation ultérieure. @@ -478,27 +569,28 @@ Comme Logto ne prend pas encore en charge l’enregistrement dynamique de client Ceci est un guide générique d’intégration OAuth 2.0 / OpenID Connect. Les deux suivent des étapes similaires car OIDC est construit sur OAuth 2.0. Consultez la documentation de votre fournisseur pour les détails spécifiques. ::: -Si votre fournisseur prend en charge l’enregistrement dynamique de client, vous pouvez passer directement à l’étape 8 ci-dessous pour configurer MCP inspector ; sinon, vous devrez enregistrer manuellement MCP inspector comme client : +Si votre fournisseur prend en charge l’enregistrement dynamique du client, vous pouvez ignorer l’enregistrement manuel ; sinon, vous devrez enregistrer manuellement le client MCP : -1. Ouvrez votre MCP inspector, allez dans la configuration Authentification et cliquez sur la configuration "OAuth2.0 Flow". Copiez la valeur **Redirect URI**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. +1. Connectez-vous à la console de votre fournisseur. -2. Connectez-vous à la console de votre fournisseur. +2. Naviguez vers la section "Applications" ou "Clients", puis créez une nouvelle application ou client. -3. Accédez à la section "Applications" ou "Clients", puis créez une nouvelle application ou un nouveau client. +3. Si votre fournisseur demande un type de client, sélectionnez "Application native" ou "Client public". -4. Si votre fournisseur demande un type de client, sélectionnez "Application monopage" ou "Client public". +4. Après avoir créé l’application, configurez les URI de redirection. Pour VS Code, ajoutez les suivants : -5. Après avoir créé l’application, vous devrez configurer l’URI de redirection. Collez la valeur **Redirect URI** copiée depuis MCP inspector. + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` -6. Trouvez l’"ID client" ou "ID d’application" de la nouvelle application et copiez-le. +5. Configurez les portées / permissions requises pour l’application : -7. Retournez dans MCP inspector et collez la valeur "Client ID" dans la configuration Authentification sous "OAuth2.0 Flow" dans le champ "Client ID". + ```text + create:todos read:todos delete:todos + ``` -8. Dans le champ "Scope", saisissez les portées suivantes pour demander les permissions nécessaires aux opérations sur les tâches : - -```text -create:todos read:todos delete:todos -``` +6. Trouvez l’"ID client" ou "ID d’application" de la nouvelle application et copiez-le pour une utilisation ultérieure. @@ -507,20 +599,18 @@ create:todos read:todos delete:todos Commencez par installer le SDK MCP Auth dans votre projet serveur MCP. -import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; - Nous devons maintenant initialiser MCP Auth dans votre serveur MCP. En mode ressource protégée, vous devez configurer vos métadonnées de ressource, y compris les serveurs d’autorisation. Il existe deux façons de configurer les serveurs d’autorisation : -- **Pré-récupéré (recommandé)** : Utilisez `fetchServerConfig()` pour récupérer les métadonnées avant d’initialiser MCPAuth. Cela garantit que la configuration est validée au démarrage. +- **Pré-récupéré (Recommandé)** : Utilisez `fetchServerConfig()` pour récupérer les métadonnées avant d’initialiser MCPAuth. Cela garantit que la configuration est validée au démarrage. - **Découverte à la demande** : Fournissez uniquement `issuer` et `type` – les métadonnées seront récupérées à la demande lors du premier besoin. Ceci est utile pour les environnements edge (comme Cloudflare Workers) où l’appel asynchrone de haut niveau n’est pas autorisé. #### Configurer les métadonnées de ressource protégée \{#configure-protected-resource-metadata} -Commencez par obtenir l’URL de l’émetteur (issuer) de votre serveur d’autorisation : +Commencez par obtenir l’URL de l’émetteur de votre serveur d’autorisation : @@ -535,8 +625,8 @@ Dans Logto, vous pouvez trouver l’URL de l’émetteur sur la page de détails Pour les fournisseurs OAuth 2.0, vous devrez : 1. Consulter la documentation de votre fournisseur pour l’URL du serveur d’autorisation (souvent appelée issuer URL ou base URL) -2. Certains fournisseurs exposent cela à `https://{votre-domaine}/.well-known/oauth-authorization-server` -3. Chercher dans la console d’administration de votre fournisseur sous les paramètres OAuth / API +2. Certains fournisseurs exposent cela à `https://{your-domain}/.well-known/oauth-authorization-server` +3. Cherchez dans la console d’administration de votre fournisseur sous les paramètres OAuth / API @@ -544,7 +634,31 @@ Pour les fournisseurs OAuth 2.0, vous devrez : Configurez maintenant les métadonnées de ressource protégée lors de la création de l’instance MCP Auth : -[Le code JavaScript reste inchangé, conformément aux instructions.] +```js +// todo-manager.ts + +import { MCPAuth, fetchServerConfig } from 'mcp-auth'; + +const issuerUrl = ''; // Remplacez par l’URL de l’émetteur de votre serveur d’autorisation + +// Définir l’identifiant de ressource pour ce serveur MCP +const resourceId = 'http://localhost:3001/'; + +// Pré-récupérer la configuration du serveur d’autorisation (recommandé) +const authServerConfig = await fetchServerConfig(issuerUrl, { type: 'oidc' }); + +// Configurer MCP Auth avec les métadonnées de ressource protégée +const mcpAuth = new MCPAuth({ + protectedResources: { + metadata: { + resource: resourceId, + authorizationServers: [authServerConfig], + // Portées prises en charge par ce serveur MCP + scopesSupported: ['create:todos', 'read:todos', 'delete:todos'], + }, + }, +}); +``` ### Mettre à jour le serveur MCP \{#update-mcp-server} @@ -552,35 +666,237 @@ Nous y sommes presque ! Il est temps de mettre à jour le serveur MCP pour appli Appliquez maintenant les routes de métadonnées de ressource protégée afin que les clients MCP puissent récupérer les métadonnées attendues depuis le serveur MCP. -[Le code TypeScript reste inchangé, conformément aux instructions.] +```ts +// todo-manager.ts + +// Mettre en place les routes de métadonnées de ressource protégée +// Cela expose les métadonnées de ce serveur de ressources pour les clients OAuth +app.use(mcpAuth.protectedResourceMetadataRouter()); +``` Ensuite, appliquez le middleware MCP Auth au serveur MCP. Ce middleware gérera l’authentification et l’autorisation des requêtes entrantes, garantissant que seuls les utilisateurs autorisés peuvent accéder aux outils du gestionnaire de tâches. -[Le code TypeScript reste inchangé, conformément aux instructions.] +```ts +// todo-manager.ts + +app.use(mcpAuth.protectedResourceMetadataRouter()); + +// Appliquer le middleware MCP Auth +app.use( + mcpAuth.bearerAuth('jwt', { + resource: resourceId, + audience: resourceId, + }) +); +``` À ce stade, nous pouvons mettre à jour les outils du gestionnaire de tâches pour exploiter le middleware MCP Auth pour l’authentification et l’autorisation. Mettons à jour l’implémentation des outils. -[Le code TypeScript reste inchangé, conformément aux instructions.] +```js +// todo-manager.ts + +// autres imports... +import assert from 'node:assert'; +import { fetchServerConfig, MCPAuth, MCPAuthBearerAuthError } from 'mcp-auth'; +import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'; + +// Nous en parlerons dans la section suivante +import { TodoService } from './todo-service.js'; + +const assertUserId = (authInfo?: AuthInfo) => { + const { subject } = authInfo ?? {}; + assert(subject, 'Informations d’authentification invalides'); + return subject; +}; + +const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { + return requiredScopes.every((scope) => userScopes.includes(scope)); +}; + +const todoService = new TodoService(); + +server.registerTool( + 'create-todo', + { + description: 'Créer une nouvelle tâche', + inputSchema: { content: z.string() }, + }, + ({ content }, { authInfo }) => { + const userId = assertUserId(authInfo); + + /** + * Seuls les utilisateurs avec la portée 'create:todos' peuvent créer des tâches + */ + if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { + throw new MCPAuthBearerAuthError('missing_required_scopes'); + } + + const createdTodo = todoService.createTodo({ content, ownerId: userId }); + + return { + content: [{ type: 'text', text: JSON.stringify(createdTodo) }], + }; + } +); + +server.registerTool( + 'get-todos', + { + description: 'Lister toutes les tâches', + inputSchema: {}, + }, + (_params, { authInfo }) => { + const userId = assertUserId(authInfo); + + /** + * Si l’utilisateur a la portée 'read:todos', il peut accéder à toutes les tâches (todoOwnerId = undefined) + * Sinon, il ne peut accéder qu’à ses propres tâches (todoOwnerId = userId) + */ + const todoOwnerId = hasRequiredScopes(authInfo?.scopes ?? [], ['read:todos']) + ? undefined + : userId; + + const todos = todoService.getAllTodos(todoOwnerId); + + return { + content: [{ type: 'text', text: JSON.stringify(todos) }], + }; + } +); + +server.registerTool( + 'delete-todo', + { + description: 'Supprimer une tâche par id', + inputSchema: { id: z.string() }, + }, + ({ id }, { authInfo }) => { + const userId = assertUserId(authInfo); + + const todo = todoService.getTodoById(id); + + if (!todo) { + return { + content: [{ type: 'text', text: JSON.stringify({ error: 'Échec de la suppression de la tâche' }) }], + }; + } + + /** + * Les utilisateurs ne peuvent supprimer que leurs propres tâches + * Les utilisateurs avec la portée 'delete:todos' peuvent supprimer n’importe quelle tâche + */ + if (todo.ownerId !== userId && !hasRequiredScopes(authInfo?.scopes ?? [], ['delete:todos'])) { + return { + content: [ + { + type: 'text', + text: JSON.stringify({ error: 'Échec de la suppression de la tâche' }), + }, + ], + }; + } + + const deletedTodo = todoService.deleteTodo(id); + + return { + content: [ + { + type: 'text', + text: JSON.stringify({ + message: `Tâche ${id} supprimée`, + details: deletedTodo, + }), + }, + ], + }; + } +); +``` Créez maintenant le "service Todo" utilisé dans le code ci-dessus pour implémenter la fonctionnalité associée : Créez le fichier `todo-service.ts` pour le service Todo : -[Le code TypeScript reste inchangé, conformément aux instructions.] +```ts +// todo-service.ts + +type Todo = { + id: string; + content: string; + ownerId: string; + createdAt: string; +}; + +/** + * Un service Todo simple à des fins de démonstration. + * Utilise un tableau en mémoire pour stocker les tâches + */ +export class TodoService { + private readonly todos: Todo[] = []; + + getAllTodos(ownerId?: string): Todo[] { + if (ownerId) { + return this.todos.filter((todo) => todo.ownerId === ownerId); + } + return this.todos; + } + + getTodoById(id: string): Todo | undefined { + return this.todos.find((todo) => todo.id === id); + } + + createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo { + const todo: Todo = { + id: this.genId(), + content, + ownerId, + createdAt: new Date().toISOString(), + }; + + // eslint-disable-next-line @silverhand/fp/no-mutating-methods + this.todos.push(todo); + return todo; + } + + deleteTodo(id: string): Todo | undefined { + const index = this.todos.findIndex((todo) => todo.id === id); + + if (index === -1) { + return undefined; + } + + // eslint-disable-next-line @silverhand/fp/no-mutating-methods + const [deleted] = this.todos.splice(index, 1); + return deleted; + } + + private genId(): string { + return Math.random().toString(36).slice(2, 10); + } +} +``` Félicitations ! Nous avons implémenté avec succès un serveur MCP complet avec authentification et autorisation ! :::info -Consultez le [dépôt SDK Node.js MCP Auth](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) pour le code complet du serveur MCP (version OIDC). +Consultez le [dépôt SDK MCP Auth Node.js](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) pour le code complet du serveur MCP (version OIDC). ::: ## Point de contrôle : Exécuter les outils `todo-manager` \{#checkpoint-run-the-todo-manager-tools} -Redémarrez votre serveur MCP et ouvrez MCP inspector dans votre navigateur. Lorsque vous cliquez sur le bouton "Connect", vous devriez être redirigé vers la page de connexion de votre serveur d’autorisation. +Redémarrez votre serveur MCP et connectez VS Code à celui-ci. Voici comment se connecter avec authentification : + +1. Dans VS Code, appuyez sur `Commande + Maj + P` (macOS) ou `Ctrl + Maj + P` (Windows / Linux) pour ouvrir la palette de commandes. +2. Tapez `MCP: Add Server...` et sélectionnez-le. +3. Choisissez `HTTP` comme type de serveur. +4. Entrez l’URL du serveur MCP : `http://localhost:3001` +5. Après l’initiation d’une requête OAuth, VS Code vous demandera de saisir l’**App ID**. Entrez l’App ID que vous avez copié depuis votre serveur d’autorisation. +6. Comme nous n’avons pas de **App Secret** (c’est un client public), appuyez simplement sur Entrée pour passer. +7. Terminez le flux de connexion dans votre navigateur. -Une fois connecté et de retour dans MCP inspector, répétez les actions du point de contrôle précédent pour exécuter les outils du gestionnaire de tâches. Cette fois, vous pouvez utiliser ces outils avec votre identité utilisateur authentifiée. Le comportement des outils dépendra des rôles et permissions attribués à votre utilisateur : +Une fois connecté et de retour dans VS Code, répétez les actions du point de contrôle précédent pour exécuter les outils du gestionnaire de tâches. Cette fois, vous pouvez utiliser ces outils avec votre identité utilisateur authentifiée. Le comportement des outils dépendra des rôles et permissions attribués à votre utilisateur : - Si vous êtes connecté en tant que **User** (avec uniquement la portée `create:todos`) : @@ -591,29 +907,27 @@ Une fois connecté et de retour dans MCP inspector, répétez les actions du poi - Si vous êtes connecté en tant qu’**Admin** (avec toutes les portées : `create:todos`, `read:todos`, `delete:todos`) : - Vous pouvez créer de nouvelles tâches - Vous pouvez voir toutes les tâches du système avec l’outil `get-todos` - - Vous pouvez supprimer n’importe quelle tâche avec l’outil `delete-todo`, quel que soit son créateur + - Vous pouvez supprimer n’importe quelle tâche avec l’outil `delete-todo`, quel que soit le créateur Vous pouvez tester ces différents niveaux de permission en : -1. Vous déconnectant de la session en cours (cliquez sur le bouton "Disconnect" dans MCP inspector) +1. Vous déconnectant du serveur MCP (supprimez la configuration du serveur dans VS Code) 2. Vous connectant avec un autre compte utilisateur ayant des rôles / permissions différents 3. Essayant à nouveau les mêmes outils pour observer comment le comportement change selon les permissions de l’utilisateur Cela démontre comment le contrôle d’accès basé sur les rôles (RBAC) fonctionne en pratique, où différents utilisateurs ont différents niveaux d’accès aux fonctionnalités du système. -![Résultat de l’outil gestionnaire de tâches dans MCP inspector](/docs-assets/images/tutorials/todo-manager/result.png) - :::info -Consultez le [dépôt SDK Node.js MCP Auth](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) pour le code complet du serveur MCP (version OIDC). +Consultez le [dépôt SDK MCP Auth Node.js](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) pour le code complet du serveur MCP (version OIDC). ::: ## Notes de clôture \{#closing-notes} Félicitations ! Vous avez terminé avec succès le tutoriel. Récapitulons ce que nous avons fait : -- Mise en place d’un serveur MCP de base avec des outils de gestion des tâches (`create-todo`, `get-todos`, `delete-todo`) +- Mise en place d’un serveur MCP de base avec des outils de gestion de tâches (`create-todo`, `get-todos`, `delete-todo`) - Implémentation du contrôle d’accès basé sur les rôles (RBAC) avec différents niveaux de permissions pour les utilisateurs et les admins - Intégration du serveur MCP avec un serveur d’autorisation via MCP Auth -- Configuration de MCP Inspector pour authentifier les utilisateurs et utiliser des jetons d’accès avec portées pour appeler les outils +- Configuration de VS Code pour authentifier les utilisateurs et utiliser des jetons d’accès avec des portées pour appeler les outils N’hésitez pas à consulter d’autres tutoriels et la documentation pour tirer le meilleur parti de MCP Auth. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigError.md b/i18n/ja/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigError.md index 2e8e8e5..5c5b68d 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigError.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigError.md @@ -22,7 +22,7 @@ type AuthServerConfigError = { optional cause: Error; ``` -エラーの任意の原因。通常は、より詳細なコンテキストを提供する `Error` のインスタンスです。 +エラーのオプションの原因です。通常は、より多くのコンテキストを提供する `Error` のインスタンスです。 *** diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index 8747b6d..97d84e0 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -3,6 +3,7 @@ sidebar_position: 2 sidebar_label: 'チュートリアル: Todo マネージャーを構築する' --- +import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -12,25 +13,25 @@ import Tabs from '@theme/Tabs'; MCP Auth は Python でも利用可能です！インストール方法や使い方は [Python SDK リポジトリ](https://github.com/mcp-auth/python) をご覧ください。 ::: -このチュートリアルでは、ユーザー認証 (Authentication) と認可 (Authorization) を備えた todo マネージャー MCP サーバーを構築します。最新の MCP 仕様に従い、MCP サーバーは OAuth 2.0 **リソースサーバー (Resource Server)** として動作し、アクセス トークンを検証し、スコープベースの権限を強制します。 +このチュートリアルでは、ユーザー認証 (Authentication) と認可 (Authorization) を備えた todo マネージャー MCP サーバーを構築します。最新の MCP 仕様に従い、MCP サーバーは OAuth 2.0 **リソースサーバー (Resource Server)** として動作し、アクセス トークンの検証とスコープベースの権限管理を行います。 このチュートリアルを完了すると、次のことができるようになります： - ✅ MCP サーバーでロールベースのアクセス制御 (RBAC) を設定する基本的な理解 -- ✅ 認可サーバーが発行したアクセス トークンを受け取り、リソースサーバーとして動作する MCP サーバー -- ✅ Todo 操作に対するスコープベースの権限強制の実装 +- ✅ 認可サーバーが発行したアクセス トークンを利用するリソースサーバーとしての MCP サーバー +- ✅ Todo 操作に対するスコープベースの権限管理の実装 ## 概要 \{#overview} -このチュートリアルでは、以下のコンポーネントが登場します： +このチュートリアルでは、以下のコンポーネントを扱います： -- **MCP クライアント (MCP Inspector)**：OAuth 2.0 / OIDC クライアントとして動作する MCP サーバーのビジュアルテストツール。認可サーバーと認可フローを開始し、MCP サーバーへのリクエスト認証にアクセス トークンを取得します。 -- **認可サーバー (Authorization Server)**：OAuth 2.1 または OpenID Connect プロバイダー。ユーザーアイデンティティの管理、ユーザー認証 (Authentication)、適切なスコープを持つアクセス トークンの発行を行います。 -- **MCP サーバー (リソースサーバー Resource Server)**：最新の MCP 仕様に従い、OAuth 2.0 フレームワークのリソースサーバーとして動作します。認可サーバーが発行したアクセス トークンを検証し、todo 操作に対してスコープベースの権限を強制します。 +- **MCP クライアント (VS Code)**：MCP サポートを内蔵したコードエディタで、OAuth 2.0/OIDC クライアントとして動作します。認可サーバーと認可フローを開始し、MCP サーバーへのリクエスト認証のためにアクセス トークンを取得します。 +- **認可サーバー (Authorization Server)**：OAuth 2.1 または OpenID Connect プロバイダーで、ユーザーのアイデンティティ管理、認証 (Authentication)、および認可されたクライアントへの適切なスコープ付きアクセス トークンの発行を行います。 +- **MCP サーバー (リソースサーバー)**：最新の MCP 仕様に基づき、OAuth 2.0 フレームワークのリソースサーバー (Resource Server) として動作します。認可サーバーが発行したアクセス トークンの検証と、todo 操作に対するスコープベースの権限管理を行います。 このアーキテクチャは標準的な OAuth 2.0 フローに従います： -- **MCP Inspector** がユーザーの代理で保護されたリソースをリクエスト +- **VS Code** がユーザーに代わって保護されたリソースをリクエスト - **認可サーバー (Authorization Server)** がユーザーを認証 (Authentication) し、アクセス トークンを発行 - **MCP サーバー** がトークンを検証し、付与された権限に基づいて保護されたリソースを提供 @@ -39,7 +40,7 @@ MCP Auth は Python でも利用可能です！インストール方法や使い ```mermaid sequenceDiagram autonumber - participant Client as MCP Inspector
(OAuth クライアント) + participant Client as VS Code
(OAuth クライアント) participant RS as MCP サーバー
(リソースサーバー) participant AS as 認可サーバー @@ -48,10 +49,10 @@ sequenceDiagram Note over Client: WWW-Authenticate ヘッダーから
resource_metadata URL を抽出 Client->>RS: GET /.well-known/oauth-protected-resource (resource_metadata) - RS-->>Client: 保護リソースメタデータ
(認可サーバー URL を含む) + RS-->>Client: 保護リソースのメタデータ
(認可サーバー URL を含む) Client->>AS: GET /.well-known/oauth-authorization-server - AS-->>Client: 認可サーバーメタデータ + AS-->>Client: 認可サーバーのメタデータ Client->>AS: OAuth 認可 (ログイン & 同意) AS-->>Client: アクセス トークン @@ -64,23 +65,23 @@ sequenceDiagram ### スコープ付きアクセス トークン \{#access-tokens-with-scopes} -[ロールベースのアクセス制御 (RBAC)](https://auth.wiki/rbac) を MCP サーバーで実装するには、認可サーバーがスコープ付きのアクセス トークンを発行できる必要があります。スコープはユーザーに付与された権限を表します。 +MCP サーバーで [ロールベースのアクセス制御 (RBAC)](https://auth.wiki/rbac) を実装するには、認可サーバーがスコープ付きのアクセス トークンを発行できる必要があります。スコープはユーザーに付与された権限を表します。 [Logto](https://logto.io) は、API リソース（[RFC 8707: OAuth 2.0 のリソースインジケーター](https://datatracker.ietf.org/doc/html/rfc8707) に準拠）とロール機能を通じて RBAC をサポートしています。設定方法は以下の通りです： -1. [Logto Console](https://cloud.logto.io)（またはセルフホスト版 Logto Console）にサインイン +1. [Logto コンソール](https://cloud.logto.io)（またはセルフホスト Logto コンソール）にサインイン 2. API リソースとスコープを作成： - 「API リソース」へ移動 - 「Todo Manager」という新しい API リソースを作成 - - 以下のスコープを追加： - - `create:todos`: "新しい todo アイテムの作成" - - `read:todos`: "すべての todo アイテムの閲覧" - - `delete:todos`: "任意の todo アイテムの削除" + - 以下のスコープを追加 + - `create:todos`: 「新しい todo アイテムの作成」 + - `read:todos`: 「すべての todo アイテムの閲覧」 + - `delete:todos`: 「任意の todo アイテムの削除」 3. ロールを作成（管理を簡単にするため推奨）： @@ -91,47 +92,42 @@ sequenceDiagram 4. 権限を割り当てる： - 「ユーザー」へ移動 - ユーザーを選択 - - 以下のいずれかを実施： - - 「ロール」タブでロールを割り当て（推奨） - - または「権限」タブで直接スコープを割り当て + - 「ロール」タブでロールを割り当てる（推奨） + - または「権限」タブで直接スコープを割り当てる スコープは JWT アクセス トークンの `scope` クレームにスペース区切りの文字列として含まれます。 -OAuth 2.0 / OIDC プロバイダーは通常、スコープベースのアクセス制御をサポートしています。RBAC を実装する場合： +OAuth 2.0 / OIDC プロバイダーは通常、スコープベースのアクセス制御をサポートしています。RBAC を実装する際は： 1. 認可サーバーで必要なスコープを定義 2. クライアントが認可フロー中にこれらのスコープをリクエストするよう設定 3. 認可サーバーが付与したスコープをアクセス トークンに含めることを確認 4. スコープは通常、JWT アクセス トークンの `scope` クレームに含まれます -詳細はプロバイダーのドキュメントを参照してください： - -- スコープの定義・管理方法 -- アクセス トークンへのスコープの含め方 -- ロール管理など追加の RBAC 機能 +スコープの定義・管理方法や、アクセス トークンへのスコープの含め方、ロール管理などの追加 RBAC 機能については、プロバイダーのドキュメントを参照してください。 ### トークンの検証と権限チェック \{#validating-tokens-and-checking-permissions} -最新の MCP 仕様に従い、MCP サーバーは OAuth 2.0 フレームワークの **リソースサーバー (Resource Server)** として動作します。リソースサーバーとして、MCP サーバーは以下の責任を持ちます： +最新の MCP 仕様によると、MCP サーバーは OAuth 2.0 フレームワークの **リソースサーバー (Resource Server)** として動作します。リソースサーバーとしての MCP サーバーの責務は以下の通りです： 1. **トークン検証**：MCP クライアントから受け取ったアクセス トークンの真正性と完全性を検証 -2. **スコープ強制**：アクセス トークンからスコープを抽出・検証し、クライアントが実行できる操作を決定 +2. **スコープの強制**：アクセス トークンからスコープを抽出し、クライアントが実行できる操作を判定 3. **リソース保護**：有効なトークンと十分な権限がある場合のみ保護リソース（ツールの実行）を提供 -MCP サーバーがリクエストを受け取った際の検証プロセスは以下の通りです： +MCP サーバーがリクエストを受け取った際の検証プロセスは次の通りです： -1. `Authorization` ヘッダー（Bearer トークン形式）からアクセス トークンを抽出 +1. `Authorization` ヘッダーからアクセス トークンを抽出（Bearer トークン形式） 2. アクセス トークンの署名と有効期限を検証 3. 検証済みトークンからスコープとユーザー情報を抽出 4. リクエストされた操作に必要なスコープがトークンに含まれているか確認 -例えば、ユーザーが新しい todo アイテムを作成したい場合、アクセス トークンに `create:todos` スコープが含まれている必要があります。リソースサーバーの検証フローは以下の通りです： +例えば、ユーザーが新しい todo アイテムを作成したい場合、そのアクセス トークンには `create:todos` スコープが含まれている必要があります。リソースサーバーの検証フローは以下の通りです： ```mermaid sequenceDiagram @@ -145,7 +141,7 @@ sequenceDiagram Server->>Auth: JWKS を取得（キャッシュされていない場合） Auth-->>Server: JWKS を返す Server->>Server: JWT 署名とクレームをローカルで検証 - else トークンインスペクション（フォールバック） + else トークンイントロスペクション（フォールバック） Server->>Auth: POST /introspect
(token=access_token) Auth-->>Server: トークン情報を返す
(active, scope, user_id など) end @@ -153,7 +149,7 @@ sequenceDiagram Server->>Server: 検証済みトークンからスコープとユーザー情報を抽出 alt 必要なスコープあり - Server->>Server: 要求された操作を実行 + Server->>Server: リクエストされた操作を実行 Server->>Client: 操作結果を返す else 必要なスコープなし Server->>Client: 403 Forbidden
(insufficient_scope エラー) @@ -166,10 +162,10 @@ sequenceDiagram ## Todo マネージャーにおける RBAC を理解する \{#understand-rbac-in-todo-manager} -デモ目的で、todo マネージャー MCP サーバーにシンプルなロールベースのアクセス制御 (RBAC) システムを実装します。これにより、RBAC の基本原則をシンプルな実装で体験できます。 +デモ目的として、todo マネージャー MCP サーバーにシンプルなロールベースのアクセス制御 (RBAC) システムを実装します。これにより、RBAC の基本原則をシンプルな実装で体験できます。 :::note -このチュートリアルは RBAC ベースのスコープ管理を例示していますが、すべての認証 (Authentication) プロバイダーがロールによるスコープ管理を実装しているわけではありません。プロバイダーによっては独自のアクセス制御や権限管理の仕組みを持つ場合があります。 +このチュートリアルでは RBAC ベースのスコープ管理を紹介していますが、すべての認証 (Authentication) プロバイダーがロールによるスコープ管理を実装しているわけではありません。プロバイダーによっては独自のアクセス制御や権限管理の仕組みを持つ場合があります。 ::: ### ツールとスコープ \{#tools-and-scopes} @@ -177,14 +173,14 @@ sequenceDiagram Todo マネージャー MCP サーバーは、主に次の 3 つのツールを提供します： - `create-todo`: 新しい todo アイテムの作成 -- `get-todos`: すべての todo の一覧表示 -- `delete-todo`: ID で todo を削除 +- `get-todos`: すべての todo の一覧取得 +- `delete-todo`: ID 指定で todo を削除 これらのツールへのアクセスを制御するため、以下のスコープを定義します： - `create:todos`: 新しい todo アイテムの作成を許可 - `delete:todos`: 既存の todo アイテムの削除を許可 -- `read:todos`: すべての todo アイテムの取得・一覧表示を許可 +- `read:todos`: すべての todo アイテムの一覧取得を許可 ### ロールと権限 \{#roles-and-permissions} @@ -200,19 +196,19 @@ Todo マネージャー MCP サーバーは、主に次の 3 つのツールを ### リソース所有権 \{#resource-ownership} -上記の権限テーブルは各ロールに明示的に割り当てられたスコープを示していますが、リソース所有権の重要な原則も考慮します： +上記の権限テーブルは各ロールに明示的に割り当てられたスコープを示していますが、リソース所有権の重要な原則も考慮する必要があります： -- **User** は `read:todos` や `delete:todos` スコープを持ちませんが、次のことが可能です： +- **User** は `read:todos` や `delete:todos` スコープを持っていませんが、次のことが可能です： - 自分の todo アイテムの閲覧 - 自分の todo アイテムの削除 -- **Admin** はすべての権限（`read:todos` および `delete:todos`）を持ち、次のことが可能です： +- **Admin** は `read:todos` および `delete:todos` を持つため： - システム内のすべての todo アイテムの閲覧 - 所有者に関係なく任意の todo アイテムの削除 これは、RBAC システムでよく見られるパターンで、リソース所有者には自分のリソースに対する暗黙的な権限が与えられ、管理者ロールにはすべてのリソースに対する明示的な権限が付与されることを示しています。 :::tip 詳しく学ぶ -RBAC の概念やベストプラクティスについてさらに学ぶには、[Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac) をご覧ください。 +RBAC の概念やベストプラクティスをさらに深く学びたい場合は、[Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac) をご覧ください。 ::: ## プロバイダーで認可を設定する \{#configure-authorization-in-your-provider} @@ -222,19 +218,19 @@ RBAC の概念やベストプラクティスについてさらに学ぶには、 -[Logto](https://logto.io) は、API リソースとロール機能を通じて RBAC をサポートしています。設定方法は以下の通りです： +[Logto](https://logto.io) は API リソースとロール機能を通じて RBAC をサポートしています。設定方法は以下の通りです： -1. [Logto Console](https://cloud.logto.io)（またはセルフホスト版 Logto Console）にサインイン +1. [Logto コンソール](https://cloud.logto.io)（またはセルフホスト Logto コンソール）にサインイン 2. API リソースとスコープを作成： - 「API リソース」へ移動 - - 「Todo Manager」という新しい API リソースを作成し、リソースインジケーターに `http://localhost:3001` を指定 - - **重要**：リソースインジケーターは MCP サーバーの URL と一致する必要があります。このチュートリアルでは MCP サーバーがポート 3001 で動作するため `http://localhost:3001` を使用します。本番環境では実際の MCP サーバー URL（例：`https://your-mcp-server.example.com`）を使用してください。 - - 以下のスコープを作成： - - `create:todos`: "新しい todo アイテムの作成" - - `read:todos`: "すべての todo アイテムの閲覧" - - `delete:todos`: "任意の todo アイテムの削除" + - 「Todo Manager」という新しい API リソースを作成し、リソースインジケーターに `http://localhost:3001/` を使用 + - **重要**：リソースインジケーターは MCP サーバーの URL と一致する必要があります。このチュートリアルでは MCP サーバーがポート 3001 で動作するため `http://localhost:3001/` を使用します。本番環境では実際の MCP サーバー URL（例：`https://your-mcp-server.example.com/`）を使用してください。 + - 以下のスコープを作成 + - `create:todos`: 「新しい todo アイテムの作成」 + - `read:todos`: 「すべての todo アイテムの閲覧」 + - `delete:todos`: 「任意の todo アイテムの削除」 3. ロールを作成（管理を簡単にするため推奨）： @@ -243,7 +239,7 @@ RBAC の概念やベストプラクティスについてさらに学ぶには、 - 「User」ロールを作成し、`create:todos` スコープのみ割り当て - 「User」ロールの詳細ページで「一般」タブに切り替え、「User」ロールを「デフォルトロール」に設定 -4. ユーザーロールと権限を管理： +4. ユーザーのロールと権限を管理： - 新規ユーザーの場合： - デフォルトロールを設定したため自動的に「User」ロールが付与されます - 既存ユーザーの場合： @@ -252,49 +248,53 @@ RBAC の概念やベストプラクティスについてさらに学ぶには、 - 「ロール」タブでロールを割り当て :::tip プログラムによるロール管理 -Logto の [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) を使ってユーザーロールをプログラムで管理することも可能です。自動ユーザー管理や管理画面構築時に便利です。 +Logto の [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) を利用して、ユーザーロールをプログラムで管理することも可能です。自動化や管理画面構築時に便利です。 ::: -アクセス トークンをリクエストする際、Logto はユーザーのロール権限に基づいてスコープをトークンの `scope` クレームに含めます。 +アクセス トークンをリクエストすると、Logto はユーザーのロール権限に基づきスコープをトークンの `scope` クレームに含めます。 OAuth 2.0 または OpenID Connect プロバイダーの場合、異なる権限を表すスコープを設定する必要があります。具体的な手順はプロバイダーによって異なりますが、一般的には： -1. スコープを定義： +1. スコープの定義： - - 認可サーバーで以下をサポートするよう設定： + - 認可サーバーで以下をサポートするよう設定 - `create:todos` - `read:todos` - `delete:todos` -2. クライアントを設定： +2. クライアントの設定： - - クライアントを登録または更新し、これらのスコープをリクエストするように設定 + - クライアントを登録または更新し、これらのスコープをリクエストするよう設定 - スコープがアクセス トークンに含まれることを確認 -3. 権限を割り当てる： +3. 権限の割り当て： - プロバイダーの管理画面でユーザーに適切なスコープを付与 - - 一部のプロバイダーはロールベース管理をサポートし、他は直接スコープ割り当てを使用 + - 一部プロバイダーはロールベース管理をサポートし、他は直接スコープ割り当てを採用 - 推奨方法はプロバイダーのドキュメントを参照 :::tip -ほとんどのプロバイダーは付与されたスコープをアクセス トークンの `scope` クレームに含めます。形式は通常スペース区切りのスコープ値です。 +ほとんどのプロバイダーは付与したスコープをアクセス トークンの `scope` クレームに含めます。形式は通常スペース区切りのスコープ値です。 ::: -認可サーバーの設定後、ユーザーは付与されたスコープを含むアクセス トークンを受け取ります。MCP サーバーはこれらのスコープを使って次の判断を行います： +:::note[リソースインジケーターの末尾スラッシュ] +リソースインジケーターには必ず末尾スラッシュ（`/`）を含めてください。現在の MCP 公式 SDK のバグにより、SDK を利用するクライアントは認証リクエスト時にリソース識別子へ自動的にスラッシュを付加します。リソースインジケーターにスラッシュが含まれていない場合、これらのクライアントでリソース検証が失敗します（VS Code はこのバグの影響を受けません）。 +::: + +認可サーバーの設定後、ユーザーは付与されたスコープを含むアクセス トークンを受け取ります。MCP サーバーはこれらのスコープを利用して次の判定を行います： -- 新しい todo を作成できるか（`create:todos`） -- すべての todo を閲覧できるか（`read:todos`）または自分のものだけか -- 任意の todo を削除できるか（`delete:todos`）または自分のものだけか +- 新しい todo の作成が可能か（`create:todos`） +- すべての todo の閲覧（`read:todos`）または自分の todo のみ閲覧可能か +- 任意の todo の削除（`delete:todos`）または自分の todo のみ削除可能か ## MCP サーバーをセットアップする \{#set-up-the-mcp-server} -[MCP 公式 SDK](https://github.com/modelcontextprotocol) を使って todo マネージャー MCP サーバーを作成します。 +[公式 MCP SDK](https://github.com/modelcontextprotocol) を利用して todo マネージャー MCP サーバーを作成します。 ### 新しいプロジェクトを作成 \{#create-a-new-project} @@ -303,14 +303,14 @@ OAuth 2.0 または OpenID Connect プロバイダーの場合、異なる権限 ```bash mkdir mcp-server cd mcp-server -npm init -y # または `pnpm init` +npm init -y # または `pnpm init` を使用 npm pkg set type="module" npm pkg set main="todo-manager.ts" npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -例では TypeScript を使用しています。Node.js v22.6.0 以降は `--experimental-strip-types` フラグで TypeScript をネイティブ実行できます。JavaScript を使う場合もほぼ同様ですが、Node.js v22.6.0 以降を使用してください。詳細は Node.js ドキュメントを参照してください。 +サンプルでは TypeScript を使用しています。Node.js v22.6.0 以降では `--experimental-strip-types` フラグで TypeScript をネイティブ実行できます。JavaScript を使う場合もほぼ同様ですが、Node.js v22.6.0 以降を利用してください。詳細は Node.js ドキュメントを参照してください。 ::: ### MCP SDK と依存パッケージをインストール \{#install-the-mcp-sdk-and-dependencies} @@ -333,75 +333,37 @@ npm install @modelcontextprotocol/sdk express zod npm start ``` -## MCP サーバーを検証する \{#inspect-the-mcp-server} - -### MCP inspector をクローンして実行 \{#clone-and-run-mcp-inspector} - -MCP サーバーが起動したら、MCP inspector を使ってツールが利用可能か確認できます。 - -公式 MCP inspector v0.16.2 には認証 (Authentication) 機能に影響するバグがあります。これを解決するため、OAuth / OIDC 認証フローの修正を含む [パッチ版 MCP inspector](https://github.com/mcp-auth/inspector/tree/patch/0.16.2-fixes) を作成しました。修正内容は公式リポジトリにもプルリクエスト済みです。 - -MCP inspector を実行するには（Node.js が必要です）： - -```bash -git clone https://github.com/mcp-auth/inspector.git -b patch/0.16.2-fixes -cd inspector -npm install -npm run dev -``` - -MCP inspector は自動的にデフォルトブラウザで開きます。もしくはターミナル出力のリンク（`MCP_PROXY_AUTH_TOKEN` パラメータ付き、例：`http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=458ae4a4...acab1907`）を手動で開いてください。 - -### MCP inspector を MCP サーバーに接続 \{#connect-mcp-inspector-to-the-mcp-server} - -進む前に MCP inspector の設定を確認してください： - -- **Transport Type**：`Streamable HTTP` を選択 -- **URL**：MCP サーバーの URL を指定（本例では `http://localhost:3001`） - -「Connect」ボタンをクリックして MCP inspector が MCP サーバーに接続できるか確認します。正常なら MCP inspector に「Connected」ステータスが表示されます。 - -### チェックポイント: Todo マネージャーツールを実行 \{#checkpoint-run-todo-manager-tools} - -1. MCP inspector の上部メニューで「Tools」タブをクリック -2. 「List Tools」ボタンをクリック -3. `create-todo`, `get-todos`, `delete-todo` ツールが一覧表示されます。クリックして詳細を開きます -4. 右側に「Run Tool」ボタンが表示されるので、必要なパラメータを入力して実行 -5. JSON レスポンス `{"error": "Not implemented"}` が表示されれば成功です - -![MCP inspector 初回実行](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - ## 認可サーバーと連携する \{#integrate-with-your-authorization-server} -このセクションを完了するには、いくつかの考慮事項があります： +このセクションを完了するには、いくつかのポイントを考慮する必要があります：
**認可サーバーの発行者 (Issuer) URL** -通常は認可サーバーのベース URL です（例：`https://auth.example.com`）。プロバイダーによっては `https://example.logto.app/oidc` のようなパスが付く場合もあるので、ドキュメントを確認してください。 +通常は `https://auth.example.com` のような認可サーバーのベース URL です。プロバイダーによっては `https://example.logto.app/oidc` のようなパスが付く場合もあるので、ドキュメントを確認してください。
-**認可サーバーメタデータの取得方法** +**認可サーバーのメタデータ取得方法** -- 認可サーバーが [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) に準拠していれば、MCP Auth の組み込みユーティリティで自動取得できます -- 準拠していない場合は、MCP サーバー設定でメタデータ URL やエンドポイントを手動指定してください。詳細はプロバイダーのドキュメントを参照 +- 認可サーバーが [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) に準拠していれば、MCP Auth の組み込みユーティリティで自動取得できます。 +- 準拠していない場合は、MCP サーバー設定でメタデータ URL やエンドポイントを手動指定する必要があります。詳細はプロバイダーのドキュメントを参照してください。
-**MCP inspector を認可サーバーのクライアントとして登録する方法** +**MCP クライアントの認可サーバーへの登録方法** -- 認可サーバーが [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) をサポートしていれば、この手順は不要です。MCP inspector が自動登録します -- サポートしていない場合は、MCP inspector を手動でクライアント登録してください +- 認可サーバーが [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) をサポートしていれば、この手順は不要です。MCP クライアントが自動登録されます。 +- サポートしていない場合は、MCP クライアントを手動で認可サーバーに登録する必要があります。
**トークンリクエストパラメータの理解** -認可サーバーごとにターゲットリソースや権限指定の方法が異なります。主なパターンは以下の通りです： +認可サーバーごとに、ターゲットリソースや権限指定の方法が異なります。主なパターンは次の通りです： - **リソースインジケーター方式**： @@ -410,15 +372,15 @@ MCP inspector は自動的にデフォルトブラウザで開きます。もし - 例： ```json { - "resource": "http://localhost:3001", + "resource": "http://localhost:3001/", "scope": "create:todos read:todos" } ``` - - サーバーはリクエストされたリソース専用のトークンを発行 + - サーバーはリソースごとにバインドされたトークンを発行 - **オーディエンス方式**： - - `audience` パラメータでトークンの受信者を指定 + - `audience` パラメータでトークンの宛先を指定 - リソースインジケーターと似ているが意味が異なる - 例： ```json @@ -429,7 +391,7 @@ MCP inspector は自動的にデフォルトブラウザで開きます。もし ``` - **純粋なスコープ方式**： - - resource / audience パラメータなしでスコープのみを利用 + - resource/audience パラメータなしでスコープのみ利用 - 従来の OAuth 2.0 アプローチ - 例： ```json @@ -443,63 +405,68 @@ MCP inspector は自動的にデフォルトブラウザで開きます。もし :::tip ベストプラクティス - プロバイダーのドキュメントでサポートされているパラメータを確認 -- 複数の方式を同時にサポートするプロバイダーもある +- 複数方式を同時サポートするプロバイダーも存在 - リソースインジケーターはオーディエンス制限によるセキュリティ向上に有効 -- 利用可能ならリソースインジケーター方式を推奨 +- 利用可能な場合はリソースインジケーター方式を推奨 :::
-プロバイダーごとに要件は異なりますが、以下の手順で MCP inspector と MCP サーバーをプロバイダー固有の設定で統合できます。 +プロバイダーごとに細かな要件は異なりますが、以下の手順で VS Code と MCP サーバーをプロバイダー固有の設定で連携できます。 -### MCP inspector をクライアントとして登録 \{#register-mcp-inspector-as-a-client} +### MCP クライアントをサードパーティアプリとして登録 \{#register-mcp-client-as-a-third-party-app} -[Logto](https://logto.io) との統合は簡単です。OpenID Connect プロバイダーであり、リソースインジケーターとスコープをサポートしているため、`http://localhost:3001` をリソースインジケーターとして todo API を安全に保護できます。 - -Logto は Dynamic Client Registration をまだサポートしていないため、MCP inspector を Logto テナントのクライアントとして手動登録する必要があります： - -1. MCP inspector を開き、Authentication 設定で「OAuth2.0 Flow」設定をクリック。**Redirect URI** の値（例：`http://localhost:6274/oauth/callback`）をコピー -2. [Logto Console](https://cloud.logto.io)（またはセルフホスト版 Logto Console）にサインイン -3. 「アプリケーション」タブで「アプリケーションを作成」をクリック。ページ下部で「フレームワークなしでアプリを作成」をクリック -4. アプリケーション詳細を入力し、「アプリケーションを作成」をクリック： - - **アプリケーションタイプ**：「シングルページアプリケーション」を選択 - - **アプリケーション名**：例「MCP Inspector」 -5. 「設定 / Redirect URI」セクションで、先ほどコピーした **Redirect URI** を貼り付け、下部バーの「変更を保存」をクリック -6. 上部カードに「App ID」が表示されるのでコピー -7. MCP inspector に戻り、「OAuth2.0 Flow」設定の「Client ID」欄に「App ID」を貼り付け -8. 「Scope」欄に `create:todos read:todos delete:todos` を入力。これで Logto から返されるアクセス トークンに必要なスコープが含まれます +[Logto](https://logto.io) との連携は簡単です。OpenID Connect プロバイダーであり、リソースインジケーターとスコープをサポートしているため、`http://localhost:3001/` をリソースインジケーターとして todo API を保護できます。 + +Logto は現時点で Dynamic Client Registration をサポートしていないため、MCP クライアント（VS Code）を Logto テナントのサードパーティアプリとして手動登録する必要があります： + +1. [Logto コンソール](https://cloud.logto.io)（またはセルフホスト Logto コンソール）にサインイン +2. **アプリケーション > サードパーティアプリ** へ移動し、「アプリケーションを作成」をクリック +3. **ネイティブアプリ** をアプリケーションタイプとして選択 +4. アプリケーション情報を入力： + - **アプリケーション名**：例「MCP Client」 + - **説明**：例「VS Code 用 MCP クライアント」 +5. VS Code 用の **リダイレクト URI** を設定： + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` +6. 「変更を保存」をクリック +7. アプリの **権限** タブで、**User** セクションにて、先ほど作成した **Todo Manager** API リソースから `create:todos`, `read:todos`, `delete:todos` 権限を追加 +8. 上部カードに「App ID」が表示されるので、後で使用するためコピー :::note -これは一般的な OAuth 2.0 / OpenID Connect プロバイダー統合ガイドです。OIDC は OAuth 2.0 上に構築されているため手順はほぼ同じです。詳細はプロバイダーのドキュメントを参照してください。 +これは一般的な OAuth 2.0 / OpenID Connect プロバイダー連携ガイドです。OIDC は OAuth 2.0 上に構築されているため、手順はほぼ同じです。詳細はプロバイダーのドキュメントを参照してください。 ::: -Dynamic Client Registration をサポートしている場合は、下記手順 8 から MCP inspector の設定が可能です。サポートしていない場合は MCP inspector を手動でクライアント登録してください： +Dynamic Client Registration をサポートしていれば手動登録は不要ですが、サポートしていない場合は MCP クライアントを手動登録してください： -1. MCP inspector を開き、Authentication 設定で「OAuth2.0 Flow」設定をクリック。**Redirect URI** の値（例：`http://localhost:6274/oauth/callback`）をコピー +1. プロバイダーのコンソールにサインイン -2. プロバイダーのコンソールにサインイン +2. 「アプリケーション」または「クライアント」セクションで新規アプリケーションまたはクライアントを作成 -3. 「アプリケーション」または「クライアント」セクションで新規アプリケーションまたはクライアントを作成 +3. クライアントタイプが必要な場合は「ネイティブアプリ」または「パブリッククライアント」を選択 -4. クライアントタイプが必要な場合は「シングルページアプリケーション」または「パブリッククライアント」を選択 +4. アプリ作成後、リダイレクト URI を設定。VS Code 用には以下を追加： -5. アプリケーション作成後、リダイレクト URI を設定。コピーした **Redirect URI** を貼り付け + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` -6. 新規アプリケーションの「Client ID」または「Application ID」をコピー +5. 必要なスコープ/権限をアプリケーションに設定： -7. MCP inspector に戻り、「OAuth2.0 Flow」設定の「Client ID」欄に貼り付け + ```text + create:todos read:todos delete:todos + ``` -8. 「Scope」欄に todo 操作用の必要なスコープを入力： - -```text -create:todos read:todos delete:todos -``` +6. 新規アプリケーションの「Client ID」または「Application ID」を控えておく @@ -508,26 +475,24 @@ create:todos read:todos delete:todos まず、MCP サーバープロジェクトに MCP Auth SDK をインストールします。 -import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; - -次に MCP サーバーで MCP Auth を初期化します。保護リソースモードでは、認可サーバーを含むリソースメタデータを設定する必要があります。 +次に、MCP サーバーで MCP Auth を初期化します。保護リソースモードでは、認可サーバーを含むリソースメタデータを設定する必要があります。 認可サーバーの設定方法は 2 通りあります： -- **事前取得（推奨）**：`fetchServerConfig()` でメタデータを取得してから MCPAuth を初期化。起動時に設定が検証されます -- **オンデマンドディスカバリー**：`issuer` と `type` のみ指定し、初回利用時にメタデータを取得。Cloudflare Workers などトップレベル async fetch が許可されない環境で便利 +- **事前取得（推奨）**：`fetchServerConfig()` でメタデータを事前取得し、MCPAuth 初期化時に設定。起動時に設定が検証されます。 +- **オンデマンドディスカバリー**：`issuer` と `type` のみ指定し、初回利用時にメタデータを取得。Cloudflare Workers などトップレベル async fetch が許可されない環境で便利です。 -#### 保護リソースメタデータを設定 \{#configure-protected-resource-metadata} +#### 保護リソースメタデータの設定 \{#configure-protected-resource-metadata} -まず認可サーバーの issuer URL を取得します： +まず、認可サーバーの発行者 (issuer) URL を取得します： -Logto では、Logto Console のアプリケーション詳細ページ「Endpoints & Credentials / Issuer endpoint」セクションで issuer URL を確認できます。例：`https://my-project.logto.app/oidc` +Logto では、Logto コンソールのアプリケーション詳細ページ「エンドポイント & 資格情報 / Issuer endpoint」セクションで issuer URL を確認できます。例：`https://my-project.logto.app/oidc` @@ -535,51 +500,57 @@ Logto では、Logto Console のアプリケーション詳細ページ「Endpoi OAuth 2.0 プロバイダーの場合： -1. プロバイダーのドキュメントで認可サーバー URL（issuer URL または base URL と呼ばれることが多い）を確認 +1. 認可サーバー URL（issuer URL または base URL と呼ばれる）をドキュメントで確認 2. 多くの場合 `https://{your-domain}/.well-known/oauth-authorization-server` で公開 -3. 管理コンソールの OAuth / API 設定を確認 +3. 管理コンソールの OAuth/API 設定を確認 -次に、MCP Auth インスタンス作成時に Protected Resource Metadata を設定します： +次に、MCP Auth インスタンス構築時に Protected Resource Metadata を設定します： （※ ここはコードなので翻訳不要、省略） ### MCP サーバーを更新 \{#update-mcp-server} -あと少しです！MCP Auth のルートとミドルウェア関数を適用し、ユーザーのスコープに基づく権限制御を todo マネージャーツールに実装します。 +あと少しです！MCP Auth ルートとミドルウェア関数を適用し、ユーザーのスコープに基づく権限管理を実装します。 -まず、MCP クライアントが MCP サーバーからリソースメタデータを取得できるよう、保護リソースメタデタルートを適用します。 +まず、MCP クライアントが MCP サーバーからリソースメタデータを取得できるよう、保護リソースメタデータルートを適用します。 （※ ここはコードなので翻訳不要、省略） -次に、MCP Auth ミドルウェアを MCP サーバーに適用します。このミドルウェアはリクエストの認証 (Authentication) と認可 (Authorization) を処理し、認可されたユーザーのみが todo マネージャーツールにアクセスできるようにします。 +次に、MCP サーバーに MCP Auth ミドルウェアを適用します。このミドルウェアはリクエストの認証 (Authentication) と認可 (Authorization) を処理し、認可されたユーザーのみが todo マネージャーツールにアクセスできるようにします。 （※ ここはコードなので翻訳不要、省略） -この時点で、todo マネージャーツールの実装を MCP Auth ミドルウェアを活用する形に更新できます。 +ここまでで、todo マネージャーツールの実装を MCP Auth ミドルウェアを利用した認証 (Authentication)・認可 (Authorization) 対応に更新できます。 （※ ここはコードなので翻訳不要、省略） 次に、上記コードで利用している「Todo サービス」を作成します： -`todo-service.ts` ファイルを作成し、Todo サービスの機能を実装します： - （※ ここはコードなので翻訳不要、省略） -おめでとうございます！認証 (Authentication) と認可 (Authorization) を備えた MCP サーバーの実装が完了しました！ +おめでとうございます！これで認証 (Authentication) と認可 (Authorization) を備えた MCP サーバーが完成しました。 :::info -[MCP Auth Node.js SDK リポジトリ](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) で MCP サーバー（OIDC バージョン）の完全なコードを確認できます。 +[MCP Auth Node.js SDK リポジトリ](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) で MCP サーバー（OIDC 版）の完全なコードを確認できます。 ::: -## チェックポイント: `todo-manager` ツールを実行 \{#checkpoint-run-the-todo-manager-tools} +## チェックポイント: `todo-manager` ツールを実行する \{#checkpoint-run-the-todo-manager-tools} + +MCP サーバーを再起動し、VS Code から接続します。認証付きで接続する手順は以下の通りです： -MCP サーバーを再起動し、ブラウザで MCP inspector を開きます。「Connect」ボタンをクリックすると、認可サーバーのサインインページにリダイレクトされます。 +1. VS Code で `Command + Shift + P`（macOS）または `Ctrl + Shift + P`（Windows/Linux）を押してコマンドパレットを開く +2. `MCP: Add Server...` と入力し選択 +3. サーバータイプに `HTTP` を選択 +4. MCP サーバーの URL を入力：`http://localhost:3001` +5. OAuth リクエストが開始されると、VS Code から **App ID** の入力を求められます。認可サーバーからコピーした App ID を入力 +6. **App Secret** は不要（パブリッククライアントのため）なので Enter でスキップ +7. ブラウザでサインインフローを完了 -サインイン後 MCP inspector に戻り、前回のチェックポイントと同じ操作で todo マネージャーツールを実行します。今回は認証 (Authentication) 済みユーザーアイデンティティでツールを利用できます。ツールの動作はユーザーに割り当てられたロールと権限によって異なります： +サインイン後 VS Code に戻り、前回のチェックポイントと同様に todo マネージャーツールを実行できます。今回は認証済みユーザーとしてツールを利用でき、ユーザーに割り当てられたロールと権限によって動作が変わります： - **User**（`create:todos` スコープのみ）の場合： @@ -589,30 +560,28 @@ MCP サーバーを再起動し、ブラウザで MCP inspector を開きます - **Admin**（すべてのスコープ：`create:todos`, `read:todos`, `delete:todos`）の場合： - 新しい todo の作成が可能 - - `get-todos` ツールですべての todo を閲覧可能 - - `delete-todo` ツールで誰が作成したものでも削除可能 + - `get-todos` ツールでシステム内のすべての todo を閲覧可能 + - `delete-todo` ツールで所有者に関係なく任意の todo を削除可能 異なる権限レベルをテストするには： -1. 現在のセッションからサインアウト（MCP inspector の「Disconnect」ボタンをクリック） -2. 別のロール / 権限を持つユーザーアカウントでサインイン +1. MCP サーバーから切断（VS Code のサーバー設定を削除） +2. 別のロール/権限を持つユーザーアカウントでサインイン 3. 同じツールを再度試し、ユーザーの権限による動作の違いを確認 これにより、ロールベースのアクセス制御 (RBAC) が実際にどのように機能するかを体験できます。 -![MCP inspector todo manager tool result](/docs-assets/images/tutorials/todo-manager/result.png) - :::info -[MCP Auth Node.js SDK リポジトリ](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) で MCP サーバー（OIDC バージョン）の完全なコードを確認できます。 +[MCP Auth Node.js SDK リポジトリ](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) で MCP サーバー（OIDC 版）の完全なコードを確認できます。 ::: ## 締めくくり \{#closing-notes} おめでとうございます！チュートリアルを無事完了しました。ここまでで実施した内容を振り返ります： -- Todo 管理ツール（`create-todo`, `get-todos`, `delete-todo`）を備えた基本的な MCP サーバーのセットアップ -- ユーザーと管理者で異なる権限レベルを持つロールベースのアクセス制御 (RBAC) の実装 -- MCP Auth を使った MCP サーバーと認可サーバーの統合 -- MCP Inspector でユーザー認証 (Authentication) とスコープ付きアクセス トークンによるツール呼び出しの設定 +- Todo 管理ツール（`create-todo`, `get-todos`, `delete-todo`）付きの基本的な MCP サーバーのセットアップ +- ユーザーと管理者向けに異なる権限レベルを持つロールベースのアクセス制御 (RBAC) の実装 +- MCP サーバーと認可サーバーの連携（MCP Auth 利用） +- VS Code でユーザー認証 (Authentication)・スコープ付きアクセス トークンによるツール利用の設定 -他のチュートリアルやドキュメントもぜひご覧いただき、MCP Auth を最大限に活用してください。 \ No newline at end of file +他のチュートリアルやドキュメントもぜひご覧いただき、MCP Auth を最大限活用してください。 \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index cfaddbd..ea28a14 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -3,6 +3,7 @@ sidebar_position: 2 sidebar_label: '튜토리얼: Todo 매니저 만들기' --- +import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -12,33 +13,34 @@ import Tabs from '@theme/Tabs'; MCP Auth는 Python에서도 사용할 수 있습니다! 설치 및 사용법은 [Python SDK 저장소](https://github.com/mcp-auth/python)를 확인하세요. ::: -이 튜토리얼에서는 사용자 인증 (인증 (Authentication)) 및 인가 (Authorization)가 적용된 todo 매니저 MCP 서버를 구축합니다. 최신 MCP 명세를 따라, 우리의 MCP 서버는 액세스 토큰 (액세스 토큰 (Access token))을 검증하고 스코프 기반 권한을 적용하는 OAuth 2.0 **리소스 서버 (Resource Server)** 역할을 하게 됩니다. +이 튜토리얼에서는 사용자 인증 (Authentication) 및 인가 (Authorization)가 적용된 todo 매니저 MCP 서버를 구축합니다. 최신 MCP 명세를 따라, 우리의 MCP 서버는 액세스 토큰 (Access token)을 검증하고 스코프 (Scope) 기반 권한을 적용하는 OAuth 2.0 **리소스 서버 (Resource Server)** 역할을 하게 됩니다. 이 튜토리얼을 완료하면 다음을 얻게 됩니다: -- ✅ MCP 서버에서 역할 기반 접근 제어 (RBAC)에 대한 기본 이해 -- ✅ 인가 서버가 발급한 액세스 토큰을 사용하는 리소스 서버 역할의 MCP 서버 -- ✅ todo 작업에 대한 스코프 기반 권한 적용의 실제 구현 +- ✅ MCP 서버에서 역할 기반 접근 제어 (RBAC)를 설정하는 방법에 대한 기본 이해 +- ✅ 인가 서버 (Authorization Server)가 발급한 액세스 토큰을 사용하는 리소스 서버 역할의 MCP 서버 +- ✅ todo 작업에 대한 스코프 (Scope) 기반 권한 적용의 실제 구현 ## 개요 (Overview) \{#overview} 이 튜토리얼에는 다음과 같은 구성 요소가 포함됩니다: -- **MCP 클라이언트 (MCP Inspector)**: OAuth 2.0/OIDC 클라이언트 역할을 하는 MCP 서버용 시각적 테스트 도구입니다. 인가 서버와 인가 플로우를 시작하고, MCP 서버에 요청을 인증하기 위한 액세스 토큰을 획득합니다. -- **인가 서버 (Authorization Server)**: 사용자 아이덴티티를 관리하고, 사용자를 인증하며, 인가된 클라이언트에 적절한 스코프가 포함된 액세스 토큰을 발급하는 OAuth 2.1 또는 OpenID Connect 제공자입니다. -- **MCP 서버 (Resource Server)**: 최신 MCP 명세에 따라, MCP 서버는 OAuth 2.0 프레임워크에서 리소스 서버 역할을 합니다. 인가 서버가 발급한 액세스 토큰을 검증하고, todo 작업에 대해 스코프 기반 권한을 적용합니다. +- **MCP 클라이언트 (VS Code)**: 내장 MCP 지원이 있는 코드 에디터로, OAuth 2.0/OIDC 클라이언트 역할을 합니다. 인가 서버와 인가 플로우를 시작하고, MCP 서버에 인증된 요청을 보내기 위해 액세스 토큰을 획득합니다. +- **인가 서버 (Authorization Server)**: 사용자 아이덴티티를 관리하고, 사용자를 인증 (Authentication)하며, 인가된 클라이언트에 적절한 스코프 (Scope)가 포함된 액세스 토큰을 발급하는 OAuth 2.1 또는 OpenID Connect 제공자입니다. +- **MCP 서버 (Resource Server)**: 최신 MCP 명세에 따라, MCP 서버는 OAuth 2.0 프레임워크에서 리소스 서버 역할을 합니다. 인가 서버가 발급한 액세스 토큰을 검증하고, todo 작업에 대해 스코프 (Scope) 기반 권한을 적용합니다. 이 아키텍처는 표준 OAuth 2.0 플로우를 따릅니다: -- **MCP Inspector**가 사용자를 대신하여 보호된 리소스를 요청합니다 -- **인가 서버**가 사용자를 인증하고 액세스 토큰을 발급합니다 + +- **VS Code**가 사용자를 대신하여 보호된 리소스를 요청합니다 +- **인가 서버 (Authorization Server)**가 사용자를 인증하고 액세스 토큰을 발급합니다 - **MCP 서버**가 토큰을 검증하고, 부여된 권한에 따라 보호된 리소스를 제공합니다 -다음은 이 구성 요소들 간 상호작용의 상위 다이어그램입니다: +아래는 이 구성 요소들 간의 상호작용을 나타낸 고수준 다이어그램입니다: ```mermaid sequenceDiagram autonumber - participant Client as MCP Inspector
(OAuth 클라이언트) + participant Client as VS Code
(OAuth 클라이언트) participant RS as MCP 서버
(리소스 서버) participant AS as 인가 서버 @@ -63,12 +65,12 @@ sequenceDiagram ### 스코프가 포함된 액세스 토큰 (Access tokens with scopes) \{#access-tokens-with-scopes} -MCP 서버에서 [역할 기반 접근 제어 (RBAC)](https://auth.wiki/rbac)를 구현하려면, 인가 서버가 스코프가 포함된 액세스 토큰을 발급할 수 있어야 합니다. 스코프는 사용자가 부여받은 권한을 나타냅니다. +[MCP 서버에서 역할 기반 접근 제어 (RBAC)](https://auth.wiki/rbac)를 구현하려면, 인가 서버가 스코프 (Scope)가 포함된 액세스 토큰을 발급할 수 있어야 합니다. 스코프는 사용자가 부여받은 권한 (Permission)을 나타냅니다. -[Logto](https://logto.io)는 API 리소스([RFC 8707: OAuth 2.0을 위한 리소스 지표](https://datatracker.ietf.org/doc/html/rfc8707)) 및 역할 기능을 통해 RBAC를 지원합니다. 설정 방법은 다음과 같습니다: +[Logto](https://logto.io)는 API 리소스 (API resource) ([RFC 8707: OAuth 2.0을 위한 리소스 지표](https://datatracker.ietf.org/doc/html/rfc8707)) 및 역할 (Role) 기능을 통해 RBAC를 지원합니다. 설정 방법은 다음과 같습니다: 1. [Logto Console](https://cloud.logto.io) (또는 자체 호스팅 Logto Console)에 로그인하세요. @@ -81,35 +83,31 @@ MCP 서버에서 [역할 기반 접근 제어 (RBAC)](https://auth.wiki/rbac)를 - `read:todos`: "모든 todo 항목 읽기" - `delete:todos`: "모든 todo 항목 삭제" -3. 역할 생성(관리를 쉽게 하기 위해 권장): +3. 역할 생성 (관리가 쉬우므로 권장): - "역할"로 이동 - - "Admin" 역할을 생성하고 모든 스코프(`create:todos`, `read:todos`, `delete:todos`) 할당 + - "Admin" 역할을 생성하고 모든 스코프 (`create:todos`, `read:todos`, `delete:todos`) 할당 - "User" 역할을 생성하고 `create:todos` 스코프만 할당 4. 권한 할당: - "사용자"로 이동 - 사용자를 선택 - - "Roles" 탭에서 역할 할당(권장) - - 또는 "Permissions" 탭에서 스코프 직접 할당 + - "Roles" 탭에서 역할을 할당하거나 (권장) + - 또는 "Permissions" 탭에서 직접 스코프를 할당할 수 있습니다 스코프는 JWT 액세스 토큰의 `scope` 클레임에 공백으로 구분된 문자열로 포함됩니다. -OAuth 2.0 / OIDC 제공자는 일반적으로 스코프 기반 접근 제어를 지원합니다. RBAC 구현 시: +OAuth 2.0 / OIDC 제공자는 일반적으로 스코프 기반 접근 제어를 지원합니다. RBAC을 구현할 때: -1. 인가 서버에서 필요한 스코프 정의 -2. 클라이언트가 인가 플로우 중 이 스코프를 요청하도록 구성 -3. 인가 서버가 부여된 스코프를 액세스 토큰에 포함하는지 확인 -4. 스코프는 보통 JWT 액세스 토큰의 `scope` 클레임에 포함됨 +1. 인가 서버에서 필요한 스코프를 정의하세요 +2. 클라이언트가 인가 플로우 중에 이 스코프를 요청하도록 구성하세요 +3. 인가 서버가 부여된 스코프를 액세스 토큰에 포함하는지 확인하세요 +4. 스코프는 보통 JWT 액세스 토큰의 `scope` 클레임에 포함됩니다 -자세한 내용은 제공자 문서를 확인하세요: - -- 스코프 정의 및 관리 방법 -- 액세스 토큰에 스코프가 어떻게 포함되는지 -- 역할 관리 등 추가 RBAC 기능 +스코프 정의 및 관리 방법, 액세스 토큰에 스코프가 포함되는 방식, 역할 관리 등 추가 RBAC 기능은 제공자 문서를 참고하세요. @@ -120,11 +118,11 @@ OAuth 2.0 / OIDC 제공자는 일반적으로 스코프 기반 접근 제어를 1. **토큰 검증**: MCP 클라이언트로부터 받은 액세스 토큰의 진위 및 무결성 확인 2. **스코프 적용**: 액세스 토큰에서 스코프를 추출 및 검증하여 클라이언트가 수행할 수 있는 작업 결정 -3. **리소스 보호**: 유효한 토큰과 충분한 권한이 있는 경우에만 보호된 리소스(도구 실행) 제공 +3. **리소스 보호**: 클라이언트가 유효한 토큰과 충분한 권한을 제시할 때만 보호된 리소스(도구 실행) 제공 MCP 서버가 요청을 받으면 다음과 같은 검증 과정을 거칩니다: -1. `Authorization` 헤더에서 액세스 토큰 추출(Bearer 토큰 형식) +1. `Authorization` 헤더에서 액세스 토큰 추출 (Bearer 토큰 형식) 2. 액세스 토큰의 서명 및 만료 검증 3. 검증된 토큰에서 스코프 및 사용자 정보 추출 4. 요청된 작업에 필요한 스코프가 토큰에 포함되어 있는지 확인 @@ -139,18 +137,18 @@ sequenceDiagram Client->>Server: 액세스 토큰과 함께 요청
(Authorization: Bearer ) - alt JWT 검증(권장) - Server->>Auth: JWKS 가져오기(캐시되지 않은 경우) + alt JWT 검증 (권장) + Server->>Auth: JWKS 가져오기 (캐시 안 된 경우) Auth-->>Server: JWKS 반환 Server->>Server: JWT 서명 및 클레임 로컬 검증 - else 토큰 인트로스펙션(대체) + else 토큰 인트로스펙션 (대체) Server->>Auth: POST /introspect
(token=access_token) Auth-->>Server: 토큰 정보 반환
(active, scope, user_id 등) end Server->>Server: 검증된 토큰에서 스코프 및 사용자 컨텍스트 추출 - alt 필요한 스코프 있음 + alt 필요한 스코프 보유 Server->>Server: 요청된 작업 실행 Server->>Client: 작업 결과 반환 else 필요한 스코프 없음 @@ -160,14 +158,14 @@ sequenceDiagram ### 동적 클라이언트 등록 (Dynamic Client Registration) \{#dynamic-client-registration} -이 튜토리얼에서는 필수는 아니지만, 인가 서버와 MCP 클라이언트 등록을 자동화하고 싶다면 유용할 수 있습니다. 자세한 내용은 [동적 클라이언트 등록이 필요한가요?](/provider-list#is-dcr-required)를 참고하세요. +이 튜토리얼에서는 필수는 아니지만, 인가 서버에 MCP 클라이언트 등록을 자동화하고 싶다면 유용할 수 있습니다. 자세한 내용은 [동적 클라이언트 등록이 필요한가요?](/provider-list#is-dcr-required)를 참고하세요. ## Todo 매니저에서 RBAC 이해하기 (Understand RBAC in todo manager) \{#understand-rbac-in-todo-manager} -데모 목적상, todo 매니저 MCP 서버에 간단한 역할 기반 접근 제어 (RBAC) 시스템을 구현합니다. 이를 통해 RBAC의 기본 원리를 쉽게 이해할 수 있습니다. +데모 목적으로, todo 매니저 MCP 서버에 간단한 역할 기반 접근 제어 (RBAC) 시스템을 구현합니다. 이를 통해 RBAC의 기본 원리를 쉽게 이해할 수 있습니다. :::note -이 튜토리얼은 RBAC 기반 스코프 관리를 시연하지만, 모든 인증 (Authentication) 제공자가 역할을 통한 스코프 관리를 구현하는 것은 아닙니다. 일부 제공자는 자체적인 접근 제어 및 권한 관리 방식을 가질 수 있습니다. +이 튜토리얼은 RBAC 기반 스코프 관리를 시연하지만, 모든 인증 (Authentication) 제공자가 역할을 통한 스코프 관리를 구현하는 것은 아닙니다. 일부 제공자는 자체적인 접근 제어 및 권한 (Permission) 관리 메커니즘을 가질 수 있습니다. ::: ### 도구와 스코프 (Tools and scopes) \{#tools-and-scopes} @@ -188,26 +186,26 @@ sequenceDiagram 다음과 같이 서로 다른 접근 수준을 가진 두 가지 역할을 정의합니다: -| 역할 | create:todos | read:todos | delete:todos | -| ----- | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | +| 역할 (Role) | create:todos | read:todos | delete:todos | +| ----------- | ------------ | ---------- | ------------ | +| Admin | ✅ | ✅ | ✅ | +| User | ✅ | | | - **User**: 자신의 todo만 생성, 조회, 삭제할 수 있는 일반 사용자 - **Admin**: 소유자와 상관없이 모든 todo를 생성, 조회, 삭제할 수 있는 관리자 ### 리소스 소유권 (Resource ownership) \{#resource-ownership} -위 권한 테이블은 각 역할에 명시적으로 할당된 스코프를 보여주지만, 리소스 소유권이라는 중요한 원칙이 있습니다: +위 권한 테이블은 각 역할에 명시적으로 할당된 스코프를 보여주지만, 리소스 소유권의 중요한 원칙이 있습니다: - **User**는 `read:todos` 또는 `delete:todos` 스코프가 없지만, 여전히: - - 자신의 todo 항목을 읽을 수 있음 - - 자신의 todo 항목을 삭제할 수 있음 -- **Admin**은 전체 권한(`read:todos`, `delete:todos`)을 가지며: - - 시스템의 모든 todo 항목을 볼 수 있음 - - 소유자와 상관없이 모든 todo 항목을 삭제할 수 있음 + - 자신의 todo 항목을 조회할 수 있습니다 + - 자신의 todo 항목을 삭제할 수 있습니다 +- **Admin**은 전체 권한 (`read:todos`, `delete:todos`)을 가지므로: + - 시스템의 모든 todo 항목을 볼 수 있습니다 + - 소유자와 상관없이 모든 todo 항목을 삭제할 수 있습니다 -이는 RBAC 시스템에서 리소스 소유권이 사용자의 자체 리소스에 대한 암묵적 권한을 부여하고, 관리 역할은 모든 리소스에 대한 명시적 권한을 받는 일반적인 패턴을 보여줍니다. +이는 RBAC 시스템에서 리소스 소유권이 사용자의 자신의 리소스에 대한 암묵적 권한을 부여하고, 관리 역할은 모든 리소스에 대한 명시적 권한을 받는 일반적인 패턴을 보여줍니다. :::tip 더 알아보기 RBAC 개념과 모범 사례를 더 깊이 이해하려면 [Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac)을 참고하세요. @@ -220,37 +218,37 @@ RBAC 개념과 모범 사례를 더 깊이 이해하려면 [Mastering RBAC: A Co -[Logto](https://logto.io)는 API 리소스와 역할 기능을 통해 RBAC를 지원합니다. 설정 방법은 다음과 같습니다: +[Logto](https://logto.io)는 API 리소스 및 역할 기능을 통해 RBAC를 지원합니다. 설정 방법은 다음과 같습니다: 1. [Logto Console](https://cloud.logto.io) (또는 자체 호스팅 Logto Console)에 로그인하세요. 2. API 리소스 및 스코프 생성: - "API 리소스"로 이동 - - "Todo Manager"라는 새 API 리소스를 생성하고, 리소스 지표로 `http://localhost:3001`을 사용합니다. - - **중요**: 리소스 지표는 MCP 서버의 URL과 일치해야 합니다. 이 튜토리얼에서는 MCP 서버가 3001 포트에서 실행되므로 `http://localhost:3001`을 사용합니다. 운영 환경에서는 실제 MCP 서버 URL(예: `https://your-mcp-server.example.com`)을 사용하세요. + - "Todo Manager"라는 새 API 리소스를 생성하고, 리소스 지표 (Resource indicator)로 `http://localhost:3001/`을 사용하세요. + - **중요**: 리소스 지표는 MCP 서버의 URL과 일치해야 합니다. 이 튜토리얼에서는 MCP 서버가 3001 포트에서 실행되므로 `http://localhost:3001/`을 사용합니다. 운영 환경에서는 실제 MCP 서버 URL (예: `https://your-mcp-server.example.com/`)을 사용하세요. - 다음 스코프 생성: - `create:todos`: "새 todo 항목 생성" - `read:todos`: "모든 todo 항목 읽기" - `delete:todos`: "모든 todo 항목 삭제" -3. 역할 생성(관리를 쉽게 하기 위해 권장): +3. 역할 생성 (관리가 쉬우므로 권장): - "Roles"로 이동 - - "Admin" 역할을 생성하고 모든 스코프(`create:todos`, `read:todos`, `delete:todos`) 할당 + - "Admin" 역할을 생성하고 모든 스코프 (`create:todos`, `read:todos`, `delete:todos`) 할당 - "User" 역할을 생성하고 `create:todos` 스코프만 할당 - - "User" 역할 상세 페이지에서 "General" 탭으로 이동하여 "User" 역할을 "기본 역할"로 설정 + - "User" 역할 상세 페이지에서 "General" 탭으로 이동하여 "User" 역할을 "기본 역할 (Default role)"로 설정 4. 사용자 역할 및 권한 관리: - 신규 사용자: - - 기본 역할로 "User" 역할이 자동 할당됨 + - 기본 역할로 "User" 역할이 자동 할당됩니다 - 기존 사용자: - "사용자 관리"로 이동 - 사용자를 선택 - "Roles" 탭에서 역할 할당 :::tip 프로그래밍 방식의 역할 관리 -Logto의 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api)를 사용하여 프로그래밍 방식으로 사용자 역할을 관리할 수 있습니다. 자동화된 사용자 관리나 관리자 패널 구축 시 유용합니다. +Logto의 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api)를 사용하여 프로그래밍 방식으로 사용자 역할을 관리할 수도 있습니다. 자동화된 사용자 관리나 관리자 패널 구축 시 유용합니다. ::: 액세스 토큰을 요청할 때, Logto는 사용자 역할 권한에 따라 토큰의 `scope` 클레임에 스코프를 포함합니다. @@ -258,7 +256,7 @@ Logto의 [Management API](https://docs.logto.io/integrate-logto/interact-with-ma -OAuth 2.0 또는 OpenID Connect 제공자의 경우, 서로 다른 권한을 나타내는 스코프를 구성해야 합니다. 구체적인 단계는 제공자에 따라 다르지만, 일반적으로: +OAuth 2.0 또는 OpenID Connect 제공자의 경우, 서로 다른 권한을 나타내는 스코프를 구성해야 합니다. 구체적인 단계는 제공자마다 다르지만, 일반적으로: 1. 스코프 정의: @@ -273,9 +271,9 @@ OAuth 2.0 또는 OpenID Connect 제공자의 경우, 서로 다른 권한을 나 - 액세스 토큰에 스코프가 포함되는지 확인 3. 권한 할당: - - 제공자 인터페이스를 사용하여 사용자에게 적절한 스코프 부여 + - 제공자 인터페이스를 사용하여 사용자에게 적절한 스코프를 부여 - 일부 제공자는 역할 기반 관리, 일부는 직접 스코프 할당을 지원 - - 권장 접근 방식은 제공자 문서를 확인 + - 권장 방식은 제공자 문서를 참고 :::tip 대부분의 제공자는 부여된 스코프를 액세스 토큰의 `scope` 클레임에 포함합니다. 형식은 일반적으로 공백으로 구분된 스코프 값 문자열입니다. @@ -284,11 +282,15 @@ OAuth 2.0 또는 OpenID Connect 제공자의 경우, 서로 다른 권한을 나 -인가 서버를 구성한 후, 사용자는 부여받은 스코프가 포함된 액세스 토큰을 받게 됩니다. MCP 서버는 이 스코프를 사용하여 다음을 결정합니다: +:::note[리소스 지표의 슬래시] +리소스 지표에는 항상 끝에 슬래시(`/`)를 포함하세요. MCP 공식 SDK의 현재 버그로 인해, SDK를 사용하는 클라이언트는 인증 요청 시 리소스 식별자에 자동으로 슬래시를 추가합니다. 리소스 지표에 슬래시가 없으면 해당 클라이언트에서 리소스 검증이 실패합니다. (VS Code는 이 버그의 영향을 받지 않습니다.) +::: + +인가 서버를 구성한 후, 사용자는 부여된 스코프가 포함된 액세스 토큰을 받게 됩니다. MCP 서버는 이 스코프를 사용하여 다음을 결정합니다: - 사용자가 새 todo를 생성할 수 있는지 (`create:todos`) -- 사용자가 모든 todo를 볼 수 있는지 (`read:todos`) 또는 자신의 것만 볼 수 있는지 -- 사용자가 모든 todo를 삭제할 수 있는지 (`delete:todos`) 또는 자신의 것만 삭제할 수 있는지 +- 사용자가 모든 todo를 볼 수 있는지 (`read:todos`) 또는 자신의 todo만 볼 수 있는지 +- 사용자가 모든 todo를 삭제할 수 있는지 (`delete:todos`) 또는 자신의 todo만 삭제할 수 있는지 ## MCP 서버 설정하기 (Set up the MCP server) \{#set-up-the-mcp-server} @@ -308,7 +310,7 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -예제에서는 Node.js v22.6.0+에서 `--experimental-strip-types` 플래그로 TypeScript를 네이티브로 실행할 수 있으므로 TypeScript를 사용합니다. JavaScript를 사용하는 경우 코드가 유사하며, Node.js v22.6.0 이상을 사용해야 합니다. 자세한 내용은 Node.js 문서를 참고하세요. +예제에서는 Node.js v22.6.0+에서 `--experimental-strip-types` 플래그로 TypeScript를 네이티브로 실행합니다. JavaScript를 사용하는 경우 코드가 거의 동일하며, Node.js v22.6.0 이상을 사용해야 합니다. 자세한 내용은 Node.js 문서를 참고하세요. ::: ### MCP SDK 및 의존성 설치 (Install the MCP SDK and dependencies) \{#install-the-mcp-sdk-and-dependencies} @@ -323,7 +325,7 @@ npm install @modelcontextprotocol/sdk express zod `todo-manager.ts` 파일을 만들고 다음 코드를 추가하세요: -(코드는 번역하지 않습니다. 그대로 사용하세요.) +[코드 블록은 번역하지 않습니다.] 서버 실행: @@ -331,93 +333,55 @@ npm install @modelcontextprotocol/sdk express zod npm start ``` -## MCP 서버 검사하기 (Inspect the MCP server) \{#inspect-the-mcp-server} - -### MCP inspector 클론 및 실행 (Clone and run MCP inspector) \{#clone-and-run-mcp-inspector} - -이제 MCP 서버가 실행 중이므로, MCP inspector를 사용해 도구가 노출되는지 확인할 수 있습니다. - -공식 MCP inspector v0.16.2에는 인증 (Authentication) 기능에 영향을 주는 버그가 있습니다. 이를 해결하기 위해 OAuth/OIDC 인증 플로우에 필요한 수정이 포함된 [패치 버전 MCP inspector](https://github.com/mcp-auth/inspector/tree/patch/0.16.2-fixes)를 만들었습니다. 공식 저장소에도 PR을 제출했습니다. - -MCP inspector를 실행하려면(Node.js 필요): - -```bash -git clone https://github.com/mcp-auth/inspector.git -b patch/0.16.2-fixes -cd inspector -npm install -npm run dev -``` - -MCP inspector는 기본 브라우저에서 자동으로 열리거나, 터미널 출력의 링크(예: `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=458ae4a4...acab1907`)를 클릭해 수동으로 접근할 수 있습니다. - -### MCP inspector를 MCP 서버에 연결 (Connect MCP inspector to the MCP server) \{#connect-mcp-inspector-to-the-mcp-server} - -진행 전, MCP inspector에서 다음 설정을 확인하세요: - -- **Transport Type**: `Streamable HTTP`로 설정 -- **URL**: MCP 서버의 URL로 설정(예시: `http://localhost:3001`) - -이제 "Connect" 버튼을 클릭해 MCP inspector가 MCP 서버에 연결되는지 확인하세요. 정상적으로 연결되면 MCP inspector에서 "Connected" 상태를 볼 수 있습니다. - -### 체크포인트: Todo 매니저 도구 실행 (Checkpoint: Run todo manager tools) \{#checkpoint-run-todo-manager-tools} - -1. MCP inspector 상단 메뉴에서 "Tools" 탭 클릭 -2. "List Tools" 버튼 클릭 -3. `create-todo`, `get-todos`, `delete-todo` 도구가 페이지에 표시됩니다. 클릭해 도구 상세 보기 -4. 우측에 "Run Tool" 버튼이 보입니다. 클릭 후 필요한 파라미터 입력해 도구 실행 -5. JSON 응답 `{"error": "Not implemented"}`가 표시됩니다. - -![MCP inspector 첫 실행](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## 인가 서버와 통합 (Integrate with your authorization server) \{#integrate-with-your-authorization-server} +## 인가 서버와 통합하기 (Integrate with your authorization server) \{#integrate-with-your-authorization-server} 이 섹션을 완료하려면 다음 사항을 고려해야 합니다:
-**인가 서버의 발급자(issuer) URL** +**인가 서버의 발급자 (Issuer) URL** -일반적으로 인가 서버의 기본 URL(예: `https://auth.example.com`)입니다. 일부 제공자는 `https://example.logto.app/oidc`와 같은 경로를 가질 수 있으니, 제공자 문서를 확인하세요. +일반적으로 인가 서버의 기본 URL입니다. 예: `https://auth.example.com`. 일부 제공자는 `https://example.logto.app/oidc`와 같은 경로를 가질 수 있으니, 제공자 문서를 확인하세요.
**인가 서버 메타데이터 조회 방법** -- 인가 서버가 [OAuth 2.0 인가 서버 메타데이터](https://datatracker.ietf.org/doc/html/rfc8414) 또는 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)를 준수한다면, MCP Auth 내장 유틸리티로 자동 조회할 수 있습니다. -- 준수하지 않는 경우, MCP 서버 설정에서 메타데이터 URL 또는 엔드포인트를 수동으로 지정해야 합니다. 제공자 문서를 참고하세요. +- 인가 서버가 [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)를 준수한다면, MCP Auth 내장 유틸리티로 메타데이터를 자동으로 가져올 수 있습니다. +- 준수하지 않는 경우, MCP 서버 설정에서 메타데이터 URL 또는 엔드포인트를 수동으로 지정해야 합니다. 제공자 문서에서 엔드포인트를 확인하세요.
-**MCP inspector를 인가 서버에 클라이언트로 등록하는 방법** +**인가 서버에 MCP 클라이언트 등록 방법** -- 인가 서버가 [동적 클라이언트 등록](https://datatracker.ietf.org/doc/html/rfc7591)을 지원한다면, MCP inspector가 자동으로 클라이언트로 등록됩니다. -- 지원하지 않는 경우, MCP inspector를 인가 서버에 수동으로 클라이언트로 등록해야 합니다. +- 인가 서버가 [동적 클라이언트 등록 (Dynamic Client Registration)](https://datatracker.ietf.org/doc/html/rfc7591)을 지원한다면, MCP 클라이언트가 자동으로 등록됩니다. +- 지원하지 않는 경우, MCP 클라이언트를 인가 서버에 수동으로 등록해야 합니다.
**토큰 요청 파라미터 이해하기** -인가 서버마다 대상 리소스 및 권한 지정 방식이 다를 수 있습니다. 주요 패턴은 다음과 같습니다: +인가 서버에서 액세스 토큰을 요청할 때, 대상 리소스 및 권한을 지정하는 다양한 방식이 있습니다. 주요 패턴은 다음과 같습니다: - **리소스 지표 기반**: - - `resource` 파라미터로 대상 API 지정([RFC 8707: OAuth 2.0을 위한 리소스 지표](https://datatracker.ietf.org/doc/html/rfc8707) 참고) + - `resource` 파라미터로 대상 API 지정 ([RFC 8707: OAuth 2.0을 위한 리소스 지표](https://datatracker.ietf.org/doc/html/rfc8707) 참고) - 최신 OAuth 2.0 구현에서 일반적 - 예시 요청: ```json { - "resource": "http://localhost:3001", + "resource": "http://localhost:3001/", "scope": "create:todos read:todos" } ``` - - 서버가 요청된 리소스에 바인딩된 토큰 발급 + - 서버는 요청된 리소스에 바인딩된 토큰을 발급 -- **대상(audience) 기반**: +- **대상 (Audience) 기반**: - `audience` 파라미터로 토큰 수신자 지정 - - 리소스 지표와 유사하나 의미가 다름 + - 리소스 지표와 유사하지만 의미가 다름 - 예시 요청: ```json { @@ -435,91 +399,94 @@ MCP inspector는 기본 브라우저에서 자동으로 열리거나, 터미널 "scope": "todo-api:create todo-api:read openid profile" } ``` - - 네임스페이스를 위해 접두사 스코프 사용 + - 권한 네임스페이스를 위해 접두사 스코프 사용 - 간단한 OAuth 2.0 구현에서 일반적 :::tip 모범 사례 -- 제공자 문서에서 지원 파라미터 확인 +- 제공자 문서에서 지원되는 파라미터 확인 - 일부 제공자는 여러 방식을 동시에 지원 -- 리소스 지표는 대상 제한을 통해 더 나은 보안 제공 -- 가능하다면 리소스 지표 사용 권장 +- 리소스 지표는 대상 제한을 통해 더 나은 보안을 제공 +- 가능하다면 리소스 지표 사용을 고려하여 더 나은 접근 제어 구현 :::
-제공자마다 구체적인 요구사항이 다를 수 있지만, 아래 단계에 따라 MCP inspector와 MCP 서버를 제공자별 설정과 통합할 수 있습니다. +각 제공자마다 구체적인 요구 사항이 다를 수 있지만, 아래 단계는 VS Code와 MCP 서버를 제공자별 설정과 통합하는 과정을 안내합니다. -### MCP inspector를 클라이언트로 등록 (Register MCP inspector as a client) \{#register-mcp-inspector-as-a-client} +### MCP 클라이언트를 서드파티 앱으로 등록하기 (Register MCP client as a third-party app) \{#register-mcp-client-as-a-third-party-app} -[Logto](https://logto.io)는 OpenID Connect 제공자로, 리소스 지표와 스코프를 지원하므로 `http://localhost:3001` 리소스 지표로 todo API를 안전하게 보호할 수 있습니다. - -Logto는 아직 동적 클라이언트 등록을 지원하지 않으므로, MCP inspector를 Logto 테넌트에 수동으로 클라이언트로 등록해야 합니다: - -1. MCP inspector를 열고, Authentication 설정에서 "OAuth2.0 Flow" 설정을 클릭합니다. **Redirect URI** 값을 복사하세요(예: `http://localhost:6274/oauth/callback`). -2. [Logto Console](https://cloud.logto.io) (또는 자체 호스팅 Logto Console)에 로그인하세요. -3. "Applications" 탭으로 이동, "Create application" 클릭. 페이지 하단에서 "Create app without framework" 클릭. -4. 애플리케이션 세부 정보 입력 후 "Create application" 클릭: - - **애플리케이션 유형 선택**: "Single-page application" 선택 - - **애플리케이션 이름**: 예시로 "MCP Inspector" 입력 -5. "Settings / Redirect URIs" 섹션에서, 복사한 **Redirect URI** 값을 붙여넣고 하단 바에서 "Save changes" 클릭 -6. 상단 카드에서 "App ID" 값을 복사 -7. MCP inspector로 돌아가 "OAuth2.0 Flow"의 "Client ID" 필드에 "App ID" 값을 붙여넣기 -8. "Scope" 필드에 `create:todos read:todos delete:todos` 입력. Logto가 todo 매니저에 필요한 스코프가 포함된 액세스 토큰을 반환하도록 합니다. +[Logto](https://logto.io)는 OpenID Connect 제공자로, 리소스 지표와 스코프를 지원하므로 `http://localhost:3001/`을 리소스 지표로 사용하여 todo API를 안전하게 보호할 수 있습니다. + +Logto는 아직 동적 클라이언트 등록을 지원하지 않으므로, MCP 클라이언트(VS Code)를 Logto 테넌트의 서드파티 앱으로 수동 등록해야 합니다: + +1. [Logto Console](https://cloud.logto.io) (또는 자체 호스팅 Logto Console)에 로그인 +2. **Applications > Third-party apps**로 이동 후 "Create application" 클릭 +3. **Native App**을 애플리케이션 유형으로 선택 +4. 애플리케이션 정보 입력: + - **Application name**: 예) "MCP Client" + - **Description**: 예) "MCP client for VS Code" +5. VS Code용 **Redirect URI** 설정: + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` +6. "Save changes" 클릭 +7. 앱의 **Permissions** 탭에서 **User** 섹션 아래, 앞서 생성한 **Todo Manager** API 리소스의 `create:todos`, `read:todos`, `delete:todos` 권한 추가 +8. 상단 카드에서 "App ID" 값을 확인하고 복사해둡니다 :::note -이 가이드는 일반적인 OAuth 2.0 / OpenID Connect 제공자 통합 안내입니다. OIDC는 OAuth 2.0 위에 구축되어 있으므로, 두 프로토콜 모두 유사한 단계를 따릅니다. 구체적인 내용은 제공자 문서를 참고하세요. +이 가이드는 일반적인 OAuth 2.0 / OpenID Connect 제공자 통합 가이드입니다. OIDC는 OAuth 2.0 위에 구축되어 있으므로 단계가 유사합니다. 구체적인 내용은 제공자 문서를 참고하세요. ::: -제공자가 동적 클라이언트 등록을 지원한다면, 아래 8번 단계로 바로 이동해 MCP inspector를 설정할 수 있습니다. 그렇지 않으면 MCP inspector를 수동으로 클라이언트로 등록해야 합니다: - -1. MCP inspector를 열고, Authentication 설정에서 "OAuth2.0 Flow" 설정을 클릭합니다. **Redirect URI** 값을 복사하세요(예: `http://localhost:6274/oauth/callback`). +제공자가 동적 클라이언트 등록을 지원한다면 수동 등록을 건너뛸 수 있습니다. 그렇지 않으면 MCP 클라이언트를 수동으로 등록해야 합니다: -2. 제공자 콘솔에 로그인하세요. +1. 제공자 콘솔에 로그인 -3. "Applications" 또는 "Clients" 섹션으로 이동, 새 애플리케이션 또는 클라이언트 생성 +2. "Applications" 또는 "Clients" 섹션에서 새 애플리케이션/클라이언트 생성 -4. 클라이언트 유형을 요구하는 경우 "Single-page application" 또는 "Public client" 선택 +3. 클라이언트 유형을 요구한다면 "Native App" 또는 "Public client" 선택 -5. 애플리케이션 생성 후, Redirect URI를 구성해야 합니다. 복사한 **Redirect URI** 값을 붙여넣으세요. +4. 애플리케이션 생성 후, 리디렉션 URI를 설정합니다. VS Code의 경우 다음을 추가: -6. 새로 생성된 애플리케이션의 "Client ID" 또는 "Application ID"를 찾아 복사 + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` -7. MCP inspector로 돌아가 "OAuth2.0 Flow"의 "Client ID" 필드에 "Client ID" 값을 붙여넣기 +5. 애플리케이션에 필요한 스코프/권한 구성: -8. "Scope" 필드에 todo 작업에 필요한 다음 스코프 입력: + ```text + create:todos read:todos delete:todos + ``` -```text -create:todos read:todos delete:todos -``` +6. 새로 생성된 애플리케이션의 "Client ID" 또는 "Application ID"를 찾아 복사해둡니다 ### MCP Auth 설정 (Set up MCP Auth) \{#set-up-mcp-auth} -먼저, MCP 서버 프로젝트에 MCP Auth SDK를 설치하세요. - -import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; +먼저 MCP 서버 프로젝트에 MCP Auth SDK를 설치하세요. 이제 MCP 서버에서 MCP Auth를 초기화해야 합니다. 보호된 리소스 모드에서는 인가 서버를 포함한 리소스 메타데이터를 구성해야 합니다. -인가 서버를 구성하는 방법은 두 가지입니다: +인가 서버를 구성하는 방법은 두 가지가 있습니다: -- **사전 페치(권장)**: `fetchServerConfig()`로 메타데이터를 미리 가져와 MCPAuth 초기화 전에 검증합니다. +- **사전 패치(권장)**: `fetchServerConfig()`로 메타데이터를 미리 가져와 MCPAuth를 초기화합니다. 시작 시 구성이 검증됩니다. - **온디맨드 디스커버리**: `issuer`와 `type`만 제공하면, 최초 필요 시 메타데이터를 가져옵니다. (Cloudflare Workers 등 top-level async fetch가 불가한 환경에 유용) #### 보호된 리소스 메타데이터 구성 (Configure protected resource metadata) \{#configure-protected-resource-metadata} -먼저, 인가 서버의 발급자(issuer) URL을 확인하세요: +먼저 인가 서버의 발급자(issuer) URL을 확인하세요: @@ -533,7 +500,7 @@ Logto에서는 Logto Console의 애플리케이션 상세 페이지 "Endpoints & OAuth 2.0 제공자의 경우: -1. 제공자 문서에서 인가 서버 URL(issuer URL 또는 base URL) 확인 +1. 제공자 문서에서 인가 서버 URL(issuer URL 또는 base URL)을 확인 2. 일부 제공자는 `https://{your-domain}/.well-known/oauth-authorization-server`에서 노출 3. 제공자 관리 콘솔의 OAuth/API 설정에서 확인 @@ -541,75 +508,81 @@ OAuth 2.0 제공자의 경우: -이제 MCP Auth 인스턴스 생성 시 보호된 리소스 메타데이터를 구성하세요: +이제 MCP Auth 인스턴스를 만들 때 보호된 리소스 메타데이터를 구성하세요: -(코드는 번역하지 않습니다. 그대로 사용하세요.) +[코드 블록은 번역하지 않습니다.] ### MCP 서버 업데이트 (Update MCP server) \{#update-mcp-server} 거의 다 왔습니다! 이제 MCP Auth 라우트와 미들웨어를 적용하고, 사용자의 스코프에 따라 todo 매니저 도구에 권한 기반 접근 제어를 구현합니다. -먼저, MCP 클라이언트가 MCP 서버에서 기대하는 리소스 메타데이터를 조회할 수 있도록 보호된 리소스 메타데이터 라우트를 적용하세요. +먼저, 보호된 리소스 메타데이터 라우트를 적용하여 MCP 클라이언트가 MCP 서버에서 예상 리소스 메타데이터를 가져올 수 있도록 합니다. -(코드는 번역하지 않습니다. 그대로 사용하세요.) +[코드 블록은 번역하지 않습니다.] -다음으로, MCP 서버에 MCP Auth 미들웨어를 적용합니다. 이 미들웨어는 인증 (Authentication) 및 인가 (Authorization)를 처리하여, 권한이 있는 사용자만 todo 매니저 도구에 접근할 수 있도록 합니다. +다음으로, MCP Auth 미들웨어를 MCP 서버에 적용합니다. 이 미들웨어는 인증 (Authentication) 및 인가 (Authorization)를 처리하여, 인가된 사용자만 todo 매니저 도구에 접근할 수 있도록 합니다. -(코드는 번역하지 않습니다. 그대로 사용하세요.) +[코드 블록은 번역하지 않습니다.] -이제 todo 매니저 도구의 구현을 업데이트하여 MCP Auth 미들웨어를 통한 인증 (Authentication) 및 인가 (Authorization)를 활용할 수 있습니다. +이제 todo 매니저 도구의 구현을 업데이트하여 MCP Auth 미들웨어를 통한 인증 및 인가를 활용할 수 있습니다. -(코드는 번역하지 않습니다. 그대로 사용하세요.) +[코드 블록은 번역하지 않습니다.] -이제 위 코드에서 사용된 "Todo 서비스"를 구현하세요: +위 코드에서 사용된 "Todo 서비스"를 구현하세요: `todo-service.ts` 파일을 생성하여 Todo 서비스를 구현합니다: -(코드는 번역하지 않습니다. 그대로 사용하세요.) +[코드 블록은 번역하지 않습니다.] 축하합니다! 인증 (Authentication) 및 인가 (Authorization)가 적용된 완전한 MCP 서버를 성공적으로 구현했습니다! :::info -MCP 서버( OIDC 버전 )의 전체 코드는 [MCP Auth Node.js SDK 저장소](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)에서 확인할 수 있습니다. +MCP 서버(OIDC 버전)의 전체 코드는 [MCP Auth Node.js SDK 저장소](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)에서 확인할 수 있습니다. ::: ## 체크포인트: `todo-manager` 도구 실행 (Checkpoint: Run the `todo-manager` tools) \{#checkpoint-run-the-todo-manager-tools} -MCP 서버를 재시작하고 MCP inspector를 브라우저에서 엽니다. "Connect" 버튼을 클릭하면 인가 서버의 로그인 페이지로 리디렉션됩니다. +MCP 서버를 재시작하고 VS Code에서 연결하세요. 인증과 함께 연결하는 방법은 다음과 같습니다: + +1. VS Code에서 `Command + Shift + P`(macOS) 또는 `Ctrl + Shift + P`(Windows/Linux)를 눌러 커맨드 팔레트 열기 +2. `MCP: Add Server...` 입력 후 선택 +3. 서버 유형으로 `HTTP` 선택 +4. MCP 서버 URL 입력: `http://localhost:3001` +5. OAuth 요청이 시작되면, VS Code가 **App ID** 입력을 요청합니다. 인가 서버에서 복사한 App ID를 입력하세요. +6. **App Secret**은 없으므로(공개 클라이언트), Enter를 눌러 건너뜁니다. +7. 브라우저에서 로그인 플로우를 완료하세요. -로그인 후 MCP inspector로 돌아오면, 이전 체크포인트에서 했던 것처럼 todo 매니저 도구를 실행하세요. 이번에는 인증된 사용자 아이덴티티로 도구를 사용할 수 있습니다. 도구의 동작은 사용자에게 할당된 역할과 권한에 따라 달라집니다: +로그인 후 VS Code로 돌아와, 이전 체크포인트에서 했던 것처럼 todo 매니저 도구를 실행하세요. 이번에는 인증된 사용자 아이덴티티로 도구를 사용할 수 있습니다. 도구의 동작은 사용자에게 할당된 역할과 권한에 따라 달라집니다: -- **User**(오직 `create:todos` 스코프만 가진 사용자)로 로그인한 경우: +- **User**(오직 `create:todos` 스코프만 보유)로 로그인한 경우: - `create-todo` 도구로 새 todo 생성 가능 - 자신의 todo만 조회 및 삭제 가능 - 다른 사용자의 todo는 볼 수 없고 삭제도 불가 -- **Admin**(모든 스코프: `create:todos`, `read:todos`, `delete:todos` 보유)로 로그인한 경우: +- **Admin**(모든 스코프: `create:todos`, `read:todos`, `delete:todos`)로 로그인한 경우: - 새 todo 생성 가능 - `get-todos` 도구로 시스템의 모든 todo 조회 가능 - `delete-todo` 도구로 소유자와 상관없이 모든 todo 삭제 가능 다른 권한 수준을 테스트하려면: -1. 현재 세션에서 로그아웃(MCP inspector에서 "Disconnect" 클릭) +1. MCP 서버 연결 해제(VS Code에서 서버 구성 제거) 2. 다른 역할/권한을 가진 사용자 계정으로 로그인 3. 동일한 도구를 다시 실행하여 권한에 따라 동작이 어떻게 달라지는지 확인 -이로써 역할 기반 접근 제어 (RBAC)가 실제로 어떻게 동작하는지 확인할 수 있습니다. - -![MCP inspector todo 매니저 도구 결과](/docs-assets/images/tutorials/todo-manager/result.png) +이렇게 하면 역할 기반 접근 제어 (RBAC)가 실제로 어떻게 동작하는지, 서로 다른 사용자가 시스템 기능에 대해 서로 다른 접근 권한을 가지는지 확인할 수 있습니다. :::info -MCP 서버( OIDC 버전 )의 전체 코드는 [MCP Auth Node.js SDK 저장소](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)에서 확인할 수 있습니다. +MCP 서버(OIDC 버전)의 전체 코드는 [MCP Auth Node.js SDK 저장소](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)에서 확인할 수 있습니다. ::: ## 마무리 (Closing notes) \{#closing-notes} -축하합니다! 튜토리얼을 성공적으로 완료했습니다. 지금까지 한 일을 요약하면: +축하합니다! 튜토리얼을 성공적으로 완료했습니다. 지금까지 한 내용을 정리해봅시다: - todo 관리 도구(`create-todo`, `get-todos`, `delete-todo`)가 포함된 기본 MCP 서버 설정 -- 사용자와 관리자를 위한 다양한 권한 수준의 역할 기반 접근 제어 (RBAC) 구현 -- MCP Auth를 사용해 MCP 서버를 인가 서버와 통합 -- MCP Inspector를 구성하여 사용자를 인증하고, 스코프가 포함된 액세스 토큰으로 도구 호출 +- 사용자와 관리자를 위한 서로 다른 권한 수준의 역할 기반 접근 제어 (RBAC) 구현 +- MCP Auth를 사용하여 MCP 서버를 인가 서버와 통합 +- VS Code에서 사용자 인증 및 스코프가 포함된 액세스 토큰으로 도구 호출 구성 -MCP Auth를 최대한 활용하려면 다른 튜토리얼과 문서도 꼭 확인해 보세요. \ No newline at end of file +MCP Auth를 최대한 활용하려면 다른 튜토리얼과 문서도 꼭 확인해보세요. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/references/js/functions/createVerifyJwt.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/references/js/functions/createVerifyJwt.md index da4553d..4cb911d 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/references/js/functions/createVerifyJwt.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/references/js/functions/createVerifyJwt.md @@ -20,7 +20,7 @@ A função para recuperar a chave usada para verificar o JWT. **Veja também** -JWTVerifyGetKey para a definição do tipo da função de recuperação de chave. +JWTVerifyGetKey para a definição de tipo da função de recuperação de chave. ### options? {#options} @@ -30,7 +30,7 @@ Opções opcionais de verificação do JWT. **Veja também** -JWTVerifyOptions para a definição do tipo das opções. +JWTVerifyOptions para a definição de tipo das opções. ## Retorno {#returns} @@ -40,4 +40,4 @@ Uma função que verifica tokens de acesso JWT (Access tokens) e retorna um obje ## Veja também {#see} -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) para a definição do tipo da função retornada. \ No newline at end of file +[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) para a definição de tipo da função retornada. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigError.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigError.md index bce4d15..665d98e 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigError.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigError.md @@ -12,7 +12,7 @@ type AuthServerConfigError = { }; ``` -Representa um erro que ocorre durante a validação dos metadados do servidor de autorização (authorization server). +Representa um erro que ocorre durante a validação dos metadados do servidor de autorização. ## Propriedades {#properties} diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerModeConfig.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerModeConfig.md index 5719fd8..9cdde09 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerModeConfig.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerModeConfig.md @@ -10,7 +10,7 @@ type AuthServerModeConfig = { }; ``` -Configuração para o modo legado de servidor MCP como servidor de autorização (authorization server). +Configuração para o modo legado de servidor MCP como servidor de autorização. ## Obsoleto {#deprecated} @@ -24,7 +24,7 @@ Use a configuração `ResourceServerModeConfig` em vez disso. server: AuthServerConfig; ``` -A configuração do único servidor de autorização (authorization server). +A configuração do único servidor de autorização. #### Obsoleto {#deprecated} diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index a2567ef..658b6c5 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -3,6 +3,7 @@ sidebar_position: 2 sidebar_label: 'Tutorial: Construa um gerenciador de tarefas' --- +import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -12,25 +13,26 @@ import Tabs from '@theme/Tabs'; MCP Auth também está disponível para Python! Confira o [repositório do SDK Python](https://github.com/mcp-auth/python) para instalação e uso. ::: -Neste tutorial, vamos construir um servidor MCP de gerenciador de tarefas com Autenticação (Authentication) e Autorização (Authorization) de usuários. Seguindo a especificação mais recente do MCP, nosso servidor MCP atuará como um **Servidor de Recursos (Resource Server)** OAuth 2.0 que valida tokens de acesso e aplica permissões baseadas em escopo. +Neste tutorial, vamos construir um servidor MCP de gerenciador de tarefas com autenticação e autorização de usuários. Seguindo a especificação MCP mais recente, nosso servidor MCP atuará como um **Resource Server** OAuth 2.0 que valida tokens de acesso e aplica permissões baseadas em escopo. Após concluir este tutorial, você terá: -- ✅ Uma compreensão básica de como configurar Controle de acesso baseado em papel (RBAC) no seu servidor MCP. -- ✅ Um servidor MCP que atua como um Servidor de Recursos, consumindo tokens de acesso emitidos por um Servidor de Autorização. +- ✅ Uma compreensão básica de como configurar controle de acesso baseado em papel (RBAC) em seu servidor MCP. +- ✅ Um servidor MCP que atua como Resource Server, consumindo tokens de acesso emitidos por um Authorization Server. - ✅ Uma implementação funcional de aplicação de permissões baseadas em escopo para operações de tarefas. ## Visão geral \{#overview} O tutorial envolverá os seguintes componentes: -- **Cliente MCP (MCP Inspector)**: Uma ferramenta visual de testes para servidores MCP que atua como um cliente OAuth 2.0/OIDC. Ele inicia o fluxo de autorização com o servidor de autorização e obtém tokens de acesso para autenticar solicitações ao servidor MCP. -- **Servidor de Autorização**: Um provedor OAuth 2.1 ou OpenID Connect que gerencia identidades de usuários, autentica usuários e emite tokens de acesso com os escopos apropriados para clientes autorizados. -- **Servidor MCP (Servidor de Recursos)**: De acordo com a especificação mais recente do MCP, o servidor MCP atua como um Servidor de Recursos no framework OAuth 2.0. Ele valida tokens de acesso emitidos pelo servidor de autorização e aplica permissões baseadas em escopo para operações de tarefas. +- **Cliente MCP (VS Code)**: Um editor de código com suporte MCP integrado que atua como cliente OAuth 2.0/OIDC. Ele inicia o fluxo de autorização com o authorization server e obtém tokens de acesso para autenticar requisições ao servidor MCP. +- **Authorization Server**: Um provedor OAuth 2.1 ou OpenID Connect que gerencia identidades de usuários, autentica usuários e emite tokens de acesso com escopos apropriados para clientes autorizados. +- **Servidor MCP (Resource Server)**: De acordo com a especificação MCP mais recente, o servidor MCP atua como Resource Server no framework OAuth 2.0. Ele valida tokens de acesso emitidos pelo authorization server e aplica permissões baseadas em escopo para operações de tarefas. Esta arquitetura segue o fluxo padrão do OAuth 2.0 onde: -- O **MCP Inspector** solicita recursos protegidos em nome do usuário -- O **Servidor de Autorização** autentica o usuário e emite tokens de acesso + +- O **VS Code** solicita recursos protegidos em nome do usuário +- O **Authorization Server** autentica o usuário e emite tokens de acesso - O **Servidor MCP** valida tokens e serve recursos protegidos com base nas permissões concedidas Aqui está um diagrama de alto nível da interação entre esses componentes: @@ -38,43 +40,43 @@ Aqui está um diagrama de alto nível da interação entre esses componentes: ```mermaid sequenceDiagram autonumber - participant Client as MCP Inspector
(Cliente OAuth) - participant RS as Servidor MCP
(Servidor de Recursos) - participant AS as Servidor de Autorização + participant Client as VS Code
(OAuth Client) + participant RS as Servidor MCP
(Resource Server) + participant AS as Authorization Server - Client->>RS: Solicitação MCP (sem token) + Client->>RS: Requisição MCP (sem token) RS-->>Client: 401 Não autorizado (WWW-Authenticate) Note over Client: Extrair URL resource_metadata
do cabeçalho WWW-Authenticate Client->>RS: GET /.well-known/oauth-protected-resource (resource_metadata) - RS-->>Client: Metadados do recurso protegido
(inclui URL do servidor de autorização) + RS-->>Client: Metadados do recurso protegido
(inclui URL do authorization server) Client->>AS: GET /.well-known/oauth-authorization-server - AS-->>Client: Metadados do servidor de autorização + AS-->>Client: Metadados do authorization server Client->>AS: Autorização OAuth (login & consentimento) AS-->>Client: Token de acesso - Client->>RS: Solicitação MCP (Authorization: Bearer ) + Client->>RS: Requisição MCP (Authorization: Bearer ) RS->>RS: Validar se o token de acesso é válido e autorizado RS-->>Client: Resposta MCP ``` -## Entenda seu servidor de autorização \{#understand-your-authorization-server} +## Entenda seu authorization server \{#understand-your-authorization-server} ### Tokens de acesso com escopos \{#access-tokens-with-scopes} -Para implementar [Controle de acesso baseado em papel (RBAC)](https://auth.wiki/rbac) no seu servidor MCP, seu servidor de autorização precisa suportar a emissão de tokens de acesso com escopos. Escopos representam as permissões que um usuário recebeu. +Para implementar [controle de acesso baseado em papel (RBAC)](https://auth.wiki/rbac) em seu servidor MCP, seu authorization server precisa suportar a emissão de tokens de acesso com escopos. Escopos representam as permissões que um usuário recebeu. -[Logto](https://logto.io) oferece suporte a RBAC por meio de seus Recursos de API (API resources) (conforme [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) e recursos de papéis. Veja como configurar: +[Logto](https://logto.io) oferece suporte a RBAC por meio de seus recursos de API (conforme [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) e funcionalidades de papéis. Veja como configurar: -1. Faça login no [Logto Console](https://cloud.logto.io) (ou no seu Logto Console auto-hospedado) +1. Faça login no [Logto Console](https://cloud.logto.io) (ou em seu Logto Console auto-hospedado) 2. Crie recurso de API e escopos: - - Vá em "Recursos de API" + - Vá em "API Resources" - Crie um novo recurso de API chamado "Todo Manager" - Adicione os seguintes escopos: - `create:todos`: "Criar novas tarefas" @@ -83,16 +85,16 @@ Para implementar [Controle de acesso baseado em papel (RBAC)](https://auth.wiki/ 3. Crie papéis (recomendado para facilitar o gerenciamento): - - Vá em "Papéis" + - Vá em "Roles" - Crie um papel "Admin" e atribua todos os escopos (`create:todos`, `read:todos`, `delete:todos`) - Crie um papel "User" e atribua apenas o escopo `create:todos` 4. Atribua permissões: - - Vá em "Usuários" + - Vá em "Users" - Selecione um usuário - Você pode: - - Atribuir papéis na aba "Papéis" (recomendado) - - Ou atribuir escopos diretamente na aba "Permissões" + - Atribuir papéis na aba "Roles" (recomendado) + - Ou atribuir escopos diretamente na aba "Permissions" Os escopos serão incluídos na reivindicação `scope` do token de acesso JWT como uma string separada por espaços. @@ -101,50 +103,50 @@ Os escopos serão incluídos na reivindicação `scope` do token de acesso JWT c Provedores OAuth 2.0 / OIDC normalmente suportam controle de acesso baseado em escopo. Ao implementar RBAC: -1. Defina os escopos necessários no seu servidor de autorização +1. Defina os escopos necessários em seu authorization server 2. Configure seu cliente para solicitar esses escopos durante o fluxo de autorização -3. Certifique-se de que seu servidor de autorização inclua os escopos concedidos no token de acesso +3. Certifique-se de que seu authorization server inclua os escopos concedidos no token de acesso 4. Os escopos geralmente são incluídos na reivindicação `scope` do token de acesso JWT Consulte a documentação do seu provedor para detalhes específicos sobre: - Como definir e gerenciar escopos - Como os escopos são incluídos no token de acesso -- Quaisquer recursos adicionais de RBAC, como gerenciamento de papéis +- Quaisquer recursos adicionais de RBAC como gerenciamento de papéis ### Validando tokens e verificando permissões \{#validating-tokens-and-checking-permissions} -De acordo com a especificação mais recente do MCP, o servidor MCP atua como um **Servidor de Recursos (Resource Server)** no framework OAuth 2.0. Como Servidor de Recursos, o servidor MCP tem as seguintes responsabilidades: +De acordo com a especificação MCP mais recente, o servidor MCP atua como **Resource Server** no framework OAuth 2.0. Como Resource Server, o servidor MCP tem as seguintes responsabilidades: -1. **Validação de Token**: Verificar a autenticidade e integridade dos tokens de acesso recebidos dos clientes MCP -2. **Aplicação de Escopo**: Extrair e validar os escopos do token de acesso para determinar quais operações o cliente está autorizado a executar -3. **Proteção de Recursos**: Servir apenas recursos protegidos (executar ferramentas) quando o cliente apresentar tokens válidos com permissões suficientes +1. **Validação de token**: Verificar a autenticidade e integridade dos tokens de acesso recebidos dos clientes MCP +2. **Aplicação de escopos**: Extrair e validar os escopos do token de acesso para determinar quais operações o cliente está autorizado a executar +3. **Proteção de recursos**: Servir apenas recursos protegidos (executar ferramentas) quando o cliente apresentar tokens válidos com permissões suficientes -Quando seu servidor MCP recebe uma solicitação, ele executa o seguinte processo de validação: +Quando seu servidor MCP recebe uma requisição, ele executa o seguinte processo de validação: 1. Extrai o token de acesso do cabeçalho `Authorization` (formato Bearer token) 2. Valida a assinatura e expiração do token de acesso 3. Extrai os escopos e informações do usuário do token validado 4. Verifica se o token possui os escopos necessários para a operação solicitada -Por exemplo, se um usuário quiser criar uma nova tarefa, seu token de acesso deve incluir o escopo `create:todos`. Veja como funciona o fluxo de validação do Servidor de Recursos: +Por exemplo, se um usuário quiser criar uma nova tarefa, seu token de acesso deve incluir o escopo `create:todos`. Veja como funciona o fluxo de validação do Resource Server: ```mermaid sequenceDiagram participant Client as Cliente MCP - participant Server as Servidor MCP
(Servidor de Recursos) - participant Auth as Servidor de Autorização + participant Server as Servidor MCP
(Resource Server) + participant Auth as Authorization Server - Client->>Server: Solicitação com token de acesso
(Authorization: Bearer ) + Client->>Server: Requisição com token de acesso
(Authorization: Bearer ) alt Validação JWT (Preferencial) Server->>Auth: Buscar JWKS (se não estiver em cache) Auth-->>Server: Retornar JWKS - Server->>Server: Validar assinatura e reivindicações do JWT localmente - else Introspecção de Token (Alternativa) + Server->>Server: Validar assinatura e claims do JWT localmente + else Introspecção de token (Alternativa) Server->>Auth: POST /introspect
(token=access_token) Auth-->>Server: Retornar informações do token
(active, scope, user_id, etc.) end @@ -161,14 +163,14 @@ sequenceDiagram ### Registro dinâmico de cliente \{#dynamic-client-registration} -O Registro Dinâmico de Cliente não é necessário para este tutorial, mas pode ser útil se você quiser automatizar o processo de registro do cliente MCP com seu servidor de autorização. Veja [O Registro Dinâmico de Cliente é necessário?](/provider-list#is-dcr-required) para mais detalhes. +O Registro Dinâmico de Cliente não é necessário para este tutorial, mas pode ser útil se você quiser automatizar o processo de registro do cliente MCP com seu authorization server. Veja [Is Dynamic Client Registration required?](/provider-list#is-dcr-required) para mais detalhes. -## Entenda o RBAC no gerenciador de tarefas \{#understand-rbac-in-todo-manager} +## Entenda RBAC no gerenciador de tarefas \{#understand-rbac-in-todo-manager} -Para fins de demonstração, implementaremos um sistema simples de Controle de acesso baseado em papel (RBAC) em nosso servidor MCP de gerenciador de tarefas. Isso mostrará os princípios básicos do RBAC mantendo a implementação direta. +Para fins de demonstração, implementaremos um sistema simples de controle de acesso baseado em papel (RBAC) em nosso servidor MCP de gerenciador de tarefas. Isso mostrará os princípios básicos do RBAC mantendo a implementação simples. :::note -Embora este tutorial demonstre o gerenciamento de escopos baseado em RBAC, é importante observar que nem todos os provedores de autenticação implementam o gerenciamento de escopos por meio de papéis. Alguns provedores podem ter suas próprias implementações e mecanismos exclusivos para gerenciar controle de acesso e permissões. +Embora este tutorial demonstre gerenciamento de escopos baseado em RBAC, é importante notar que nem todos os provedores de autenticação implementam gerenciamento de escopos por meio de papéis. Alguns provedores podem ter suas próprias implementações e mecanismos exclusivos para gerenciar controle de acesso e permissões. ::: ### Ferramentas e escopos \{#tools-and-scopes} @@ -199,37 +201,37 @@ Definiremos dois papéis com diferentes níveis de acesso: ### Propriedade do recurso \{#resource-ownership} -Embora a tabela de permissões acima mostre os escopos explícitos atribuídos a cada papel, há um princípio importante de propriedade de recurso a considerar: +Embora a tabela de permissões acima mostre os escopos explícitos atribuídos a cada papel, há um princípio importante de propriedade do recurso a considerar: - **Usuários** não possuem os escopos `read:todos` ou `delete:todos`, mas ainda podem: - Ler suas próprias tarefas - Excluir suas próprias tarefas -- **Admins** possuem permissões totais (`read:todos` e `delete:todos`), permitindo que eles: - - Visualizem todas as tarefas do sistema - - Excluam qualquer tarefa, independentemente da propriedade +- **Admins** possuem permissões completas (`read:todos` e `delete:todos`), permitindo: + - Visualizar todas as tarefas do sistema + - Excluir qualquer tarefa, independentemente da propriedade Isso demonstra um padrão comum em sistemas RBAC onde a propriedade do recurso concede permissões implícitas aos usuários para seus próprios recursos, enquanto papéis administrativos recebem permissões explícitas para todos os recursos. :::tip Saiba mais -Para se aprofundar nos conceitos e melhores práticas de RBAC, confira [Dominando RBAC: Um exemplo real e abrangente](https://blog.logto.io/mastering-rbac). +Para se aprofundar em conceitos e boas práticas de RBAC, confira [Dominando RBAC: Um exemplo abrangente do mundo real](https://blog.logto.io/mastering-rbac). ::: -## Configure a autorização no seu provedor \{#configure-authorization-in-your-provider} +## Configure a autorização em seu provedor \{#configure-authorization-in-your-provider} -Para implementar o sistema de controle de acesso que descrevemos anteriormente, você precisará configurar seu servidor de autorização para suportar os escopos necessários. Veja como fazer isso com diferentes provedores: +Para implementar o sistema de controle de acesso que descrevemos anteriormente, você precisará configurar seu authorization server para suportar os escopos necessários. Veja como fazer isso em diferentes provedores: -[Logto](https://logto.io) oferece suporte a RBAC por meio de seus Recursos de API (API resources) e recursos de papéis. Veja como configurar: +[Logto](https://logto.io) oferece suporte a RBAC por meio de recursos de API e funcionalidades de papéis. Veja como configurar: -1. Faça login no [Logto Console](https://cloud.logto.io) (ou no seu Logto Console auto-hospedado) +1. Faça login no [Logto Console](https://cloud.logto.io) (ou em seu Logto Console auto-hospedado) 2. Crie recurso de API e escopos: - - Vá em "Recursos de API" - - Crie um novo recurso de API chamado "Todo Manager" usando `http://localhost:3001` como indicador de recurso. - - **Importante**: O indicador de recurso deve corresponder à URL do seu servidor MCP. Para este tutorial, usamos `http://localhost:3001` pois nosso servidor MCP roda na porta 3001. Em produção, use a URL real do seu servidor MCP (ex: `https://seu-servidor-mcp.exemplo.com`). + - Vá em "API Resources" + - Crie um novo recurso de API chamado "Todo Manager" usando `http://localhost:3001/` como indicador de recurso. + - **Importante**: O indicador de recurso deve corresponder à URL do seu servidor MCP. Para este tutorial, usamos `http://localhost:3001/` pois nosso servidor MCP roda na porta 3001. Em produção, use a URL real do seu servidor MCP (ex: `https://seu-mcp-server.exemplo.com/`). - Crie os seguintes escopos: - `create:todos`: "Criar novas tarefas" - `read:todos`: "Ler todas as tarefas" @@ -237,20 +239,20 @@ Para implementar o sistema de controle de acesso que descrevemos anteriormente, 3. Crie papéis (recomendado para facilitar o gerenciamento): - - Vá em "Papéis" + - Vá em "Roles" - Crie um papel "Admin" e atribua todos os escopos (`create:todos`, `read:todos`, `delete:todos`) - Crie um papel "User" e atribua apenas o escopo `create:todos` - - Na página de detalhes do papel "User", vá para a aba "Geral" e defina o papel "User" como o "Papel padrão". + - Na página de detalhes do papel "User", vá para a aba "General" e defina o papel "User" como o "Default role". 4. Gerencie papéis e permissões dos usuários: - Para novos usuários: - - Eles receberão automaticamente o papel "User" já que o definimos como padrão + - Eles receberão automaticamente o papel "User" pois o definimos como padrão - Para usuários existentes: - - Vá em "Gerenciamento de usuários" + - Vá em "User management" - Selecione um usuário - - Atribua papéis para o usuário na aba "Papéis" + - Atribua papéis ao usuário na aba "Roles" -:::tip Gerenciamento programático de papéis +:::tip Gerenciamento de papéis programático Você também pode usar a [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) do Logto para gerenciar papéis de usuários programaticamente. Isso é especialmente útil para automação ou ao construir painéis administrativos. ::: @@ -259,11 +261,11 @@ Ao solicitar um token de acesso, o Logto incluirá os escopos na reivindicação -Para provedores OAuth 2.0 ou OpenID Connect, você precisará configurar os escopos que representam diferentes permissões. Os passos exatos dependerão do seu provedor, mas geralmente: +Para provedores OAuth 2.0 ou OpenID Connect, você precisará configurar os escopos que representam diferentes permissões. Os passos exatos dependem do seu provedor, mas geralmente: 1. Defina escopos: - - Configure seu servidor de autorização para suportar: + - Configure seu authorization server para suportar: - `create:todos` - `read:todos` - `delete:todos` @@ -274,7 +276,7 @@ Para provedores OAuth 2.0 ou OpenID Connect, você precisará configurar os esco - Certifique-se de que os escopos estejam incluídos no token de acesso 3. Atribua permissões: - - Use a interface do seu provedor para conceder os escopos apropriados aos usuários + - Use a interface do seu provedor para conceder escopos apropriados aos usuários - Alguns provedores podem suportar gerenciamento baseado em papéis, enquanto outros podem usar atribuições diretas de escopos - Consulte a documentação do seu provedor para a abordagem recomendada @@ -285,7 +287,11 @@ A maioria dos provedores incluirá os escopos concedidos na reivindicação `sco -Após configurar seu servidor de autorização, os usuários receberão tokens de acesso contendo seus escopos concedidos. O servidor MCP usará esses escopos para determinar: +:::note[Barra no final do indicador de recurso] +Sempre inclua uma barra (`/`) no final do indicador de recurso. Devido a um bug atual no SDK oficial MCP, clientes usando o SDK adicionarão automaticamente uma barra ao final dos identificadores de recurso ao iniciar requisições de autenticação. Se seu indicador de recurso não incluir a barra, a validação do recurso falhará para esses clientes. (O VS Code não é afetado por esse bug.) +::: + +Após configurar seu authorization server, os usuários receberão tokens de acesso contendo seus escopos concedidos. O servidor MCP usará esses escopos para determinar: - Se um usuário pode criar novas tarefas (`create:todos`) - Se um usuário pode visualizar todas as tarefas (`read:todos`) ou apenas as suas @@ -293,7 +299,7 @@ Após configurar seu servidor de autorização, os usuários receberão tokens d ## Configure o servidor MCP \{#set-up-the-mcp-server} -Usaremos os [SDKs oficiais do MCP](https://github.com/modelcontextprotocol) para criar nosso servidor MCP de gerenciador de tarefas. +Usaremos os [SDKs oficiais MCP](https://github.com/modelcontextprotocol) para criar nosso servidor MCP de gerenciador de tarefas. ### Crie um novo projeto \{#create-a-new-project} @@ -309,10 +315,10 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -Estamos usando TypeScript em nossos exemplos pois o Node.js v22.6.0+ suporta rodar TypeScript nativamente usando a flag `--experimental-strip-types`. Se você estiver usando JavaScript, o código será semelhante - apenas certifique-se de estar usando Node.js v22.6.0 ou superior. Veja a documentação do Node.js para detalhes. +Estamos usando TypeScript em nossos exemplos pois o Node.js v22.6.0+ suporta rodar TypeScript nativamente usando a flag `--experimental-strip-types`. Se você estiver usando JavaScript, o código será semelhante - apenas certifique-se de usar Node.js v22.6.0 ou superior. Veja a documentação do Node.js para detalhes. ::: -### Instale o SDK MCP e dependências \{#install-the-mcp-sdk-and-dependencies} +### Instale o MCP SDK e dependências \{#install-the-mcp-sdk-and-dependencies} ```bash npm install @modelcontextprotocol/sdk express zod @@ -377,12 +383,12 @@ server.registerTool( } ); -// Abaixo está o código boilerplate da documentação do SDK MCP +// Abaixo está o código boilerplate da documentação do MCP SDK const PORT = 3001; const app = express(); app.post('/', async (request: Request, response: Response) => { - // No modo stateless, crie uma nova instância de transporte e servidor para cada requisição + // No modo stateless, crie uma nova instância de transport e server para cada requisição // para garantir isolamento completo. Uma única instância causaria colisão de IDs de requisição // quando múltiplos clientes conectam simultaneamente. @@ -398,13 +404,13 @@ app.post('/', async (request: Request, response: Response) => { await server.connect(transport); await transport.handleRequest(request, response, request.body); } catch (error) { - console.error('Erro ao lidar com a solicitação MCP:', error); + console.error('Erro ao lidar com requisição MCP:', error); if (!response.headersSent) { response.status(500).json({ jsonrpc: '2.0', error: { code: -32_603, - message: 'Erro interno do servidor', + message: 'Internal server error', }, id: null, }); @@ -414,13 +420,13 @@ app.post('/', async (request: Request, response: Response) => { // Notificações SSE não suportadas no modo stateless app.get('/', async (request: Request, response: Response) => { - console.log('Recebida solicitação GET MCP'); + console.log('Recebida requisição GET MCP'); response.writeHead(405).end( JSON.stringify({ jsonrpc: '2.0', error: { code: -32_000, - message: 'Método não permitido.', + message: 'Method not allowed.', }, id: null, }) @@ -429,13 +435,13 @@ app.get('/', async (request: Request, response: Response) => { // Encerramento de sessão não é necessário no modo stateless app.delete('/', async (request: Request, response: Response) => { - console.log('Recebida solicitação DELETE MCP'); + console.log('Recebida requisição DELETE MCP'); response.writeHead(405).end( JSON.stringify({ jsonrpc: '2.0', error: { code: -32_000, - message: 'Método não permitido.', + message: 'Method not allowed.', }, id: null, }) @@ -451,94 +457,56 @@ Execute o servidor com: npm start ``` -## Inspecione o servidor MCP \{#inspect-the-mcp-server} - -### Clone e execute o MCP inspector \{#clone-and-run-mcp-inspector} - -Agora que temos o servidor MCP rodando, podemos usar o MCP inspector para ver se as ferramentas estão disponíveis. - -O MCP inspector oficial v0.16.2 possui alguns bugs que afetam a funcionalidade de autenticação. Para resolver esses problemas, criamos uma [versão corrigida do MCP inspector](https://github.com/mcp-auth/inspector/tree/patch/0.16.2-fixes) que inclui as correções necessárias para os fluxos de autenticação OAuth/OIDC. Também enviamos pull requests para o repositório oficial para contribuir com essas correções. - -Para rodar o MCP inspector, use o seguinte comando (Node.js é necessário): - -```bash -git clone https://github.com/mcp-auth/inspector.git -b patch/0.16.2-fixes -cd inspector -npm install -npm run dev -``` - -O MCP inspector abrirá automaticamente em seu navegador padrão, ou você pode acessá-lo manualmente clicando no link exibido no terminal (certifique-se de clicar no link que inclui o parâmetro `MCP_PROXY_AUTH_TOKEN`, como `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=458ae4a4...acab1907`). - -### Conecte o MCP inspector ao servidor MCP \{#connect-mcp-inspector-to-the-mcp-server} - -Antes de prosseguir, verifique a seguinte configuração no MCP inspector: - -- **Tipo de transporte**: Defina como `Streamable HTTP`. -- **URL**: Defina para a URL do seu servidor MCP. No nosso caso, deve ser `http://localhost:3001`. - -Agora você pode clicar no botão "Connect" para ver se o MCP inspector consegue se conectar ao servidor MCP. Se tudo estiver certo, você verá o status "Connected" no MCP inspector. - -### Checkpoint: Execute as ferramentas do gerenciador de tarefas \{#checkpoint-run-todo-manager-tools} - -1. No menu superior do MCP inspector, clique na aba "Tools". -2. Clique no botão "List Tools". -3. Você deve ver as ferramentas `create-todo`, `get-todos` e `delete-todo` listadas na página. Clique para abrir os detalhes da ferramenta. -4. Você verá o botão "Run Tool" no lado direito. Clique nele e insira os parâmetros necessários para executar a ferramenta. -5. Você verá o resultado da ferramenta com a resposta JSON `{"error": "Not implemented"}`. - -![Primeira execução do MCP inspector](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## Integre com seu servidor de autorização \{#integrate-with-your-authorization-server} +## Integre com seu authorization server \{#integrate-with-your-authorization-server} Para completar esta seção, há várias considerações a serem feitas:
-**A URL do emissor do seu servidor de autorização** +**A URL do issuer do seu authorization server** -Normalmente é a URL base do seu servidor de autorização, como `https://auth.exemplo.com`. Alguns provedores podem ter um caminho como `https://example.logto.app/oidc`, então verifique a documentação do seu provedor. +Normalmente é a URL base do seu authorization server, como `https://auth.example.com`. Alguns provedores podem ter um caminho como `https://example.logto.app/oidc`, então verifique a documentação do seu provedor.
-**Como recuperar os metadados do servidor de autorização** +**Como obter os metadados do authorization server** -- Se seu servidor de autorização estiver em conformidade com o [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) ou [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), você pode usar as utilidades integradas do MCP Auth para buscar os metadados automaticamente. -- Se seu servidor de autorização não estiver em conformidade com esses padrões, você precisará especificar manualmente a URL dos metadados ou endpoints na configuração do servidor MCP. Consulte a documentação do seu provedor para os endpoints específicos. +- Se seu authorization server estiver em conformidade com [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) ou [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), você pode usar as utilidades integradas do MCP Auth para buscar os metadados automaticamente. +- Se seu authorization server não for compatível com esses padrões, você precisará especificar manualmente a URL dos metadados ou endpoints na configuração do servidor MCP. Consulte a documentação do seu provedor para os endpoints específicos.
-**Como registrar o MCP inspector como cliente no seu servidor de autorização** +**Como registrar o cliente MCP em seu authorization server** -- Se seu servidor de autorização suporta [Registro Dinâmico de Cliente](https://datatracker.ietf.org/doc/html/rfc7591), você pode pular esta etapa, pois o MCP inspector se registrará automaticamente como cliente. -- Se seu servidor de autorização não suporta Registro Dinâmico de Cliente, você precisará registrar manualmente o MCP inspector como cliente no seu servidor de autorização. +- Se seu authorization server suporta [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591), você pode pular esta etapa pois o cliente MCP se registrará automaticamente. +- Se seu authorization server não suporta Dynamic Client Registration, você precisará registrar manualmente o cliente MCP em seu authorization server.
-**Entenda os parâmetros de solicitação de token** +**Entenda os parâmetros de requisição de token** -Ao solicitar tokens de acesso de diferentes servidores de autorização, você encontrará várias abordagens para especificar o recurso alvo e permissões. Aqui estão os principais padrões: +Ao solicitar tokens de acesso de diferentes authorization servers, você encontrará várias abordagens para especificar o recurso alvo e permissões. Aqui estão os principais padrões: - **Baseado em indicador de recurso**: - Usa o parâmetro `resource` para especificar a API alvo (veja [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) - Comum em implementações modernas de OAuth 2.0 - - Exemplo de solicitação: + - Exemplo de requisição: ```json { - "resource": "http://localhost:3001", + "resource": "http://localhost:3001/", "scope": "create:todos read:todos" } ``` - O servidor emite tokens vinculados especificamente ao recurso solicitado -- **Baseado em audiência**: +- **Baseado em audience**: - Usa o parâmetro `audience` para especificar o destinatário pretendido do token - - Semelhante aos indicadores de recurso, mas com semânticas diferentes - - Exemplo de solicitação: + - Semelhante a indicadores de recurso, mas com semânticas diferentes + - Exemplo de requisição: ```json { "audience": "todo-api", @@ -547,9 +515,9 @@ Ao solicitar tokens de acesso de diferentes servidores de autorização, você e ``` - **Baseado apenas em escopo**: - - Depende apenas de escopos sem parâmetros de recurso/audiência + - Depende apenas de escopos sem parâmetros de recurso/audience - Abordagem tradicional do OAuth 2.0 - - Exemplo de solicitação: + - Exemplo de requisição: ```json { "scope": "todo-api:create todo-api:read openid profile" @@ -558,37 +526,41 @@ Ao solicitar tokens de acesso de diferentes servidores de autorização, você e - Frequentemente usa escopos prefixados para namespacing de permissões - Comum em implementações OAuth 2.0 mais simples -:::tip Melhores práticas +:::tip Boas práticas - Verifique a documentação do seu provedor para os parâmetros suportados - Alguns provedores suportam múltiplas abordagens simultaneamente -- Indicadores de recurso fornecem melhor segurança por restrição de audiência +- Indicadores de recurso fornecem melhor segurança por restrição de audience - Considere usar indicadores de recurso quando disponíveis para melhor controle de acesso :::
-Embora cada provedor possa ter seus próprios requisitos específicos, os passos a seguir irão guiá-lo no processo de integração do MCP inspector e do servidor MCP com configurações específicas do provedor. +Embora cada provedor possa ter requisitos específicos, os passos a seguir irão guiá-lo pelo processo de integração do VS Code e do servidor MCP com configurações específicas do provedor. -### Registre o MCP inspector como cliente \{#register-mcp-inspector-as-a-client} +### Registre o cliente MCP como um app de terceiros \{#register-mcp-client-as-a-third-party-app} -Integrar o gerenciador de tarefas com o [Logto](https://logto.io) é simples, pois é um provedor OpenID Connect que suporta indicadores de recurso e escopos, permitindo proteger sua API de tarefas com `http://localhost:3001` como indicador de recurso. - -Como o Logto ainda não suporta Registro Dinâmico de Cliente, você precisará registrar manualmente o MCP inspector como cliente em seu tenant Logto: - -1. Abra seu MCP inspector, vá para a configuração de Autenticação e clique em "OAuth2.0 Flow". Copie o valor do **Redirect URI**, que deve ser algo como `http://localhost:6274/oauth/callback`. -2. Faça login no [Logto Console](https://cloud.logto.io) (ou no seu Logto Console auto-hospedado). -3. Navegue até a aba "Aplicações", clique em "Criar aplicação". No final da página, clique em "Criar app sem framework". -4. Preencha os detalhes da aplicação e clique em "Criar aplicação": - - **Selecione um tipo de aplicação**: Escolha "Aplicação de página única". - - **Nome da aplicação**: Insira um nome para sua aplicação, ex: "MCP Inspector". -5. Na seção "Configurações / Redirect URIs", cole o valor do **Redirect URI** copiado do MCP inspector. Clique em "Salvar alterações" na barra inferior. -6. No cartão superior, você verá o valor "App ID". Copie-o. -7. Volte ao MCP inspector e cole o valor "App ID" na configuração de Autenticação em "OAuth2.0 Flow" no campo "Client ID". -8. No campo "Scope", insira: `create:todos read:todos delete:todos`. Isso garantirá que o token de acesso retornado pelo Logto contenha os escopos necessários para acessar o gerenciador de tarefas. +Integrar o gerenciador de tarefas com o [Logto](https://logto.io) é simples, pois é um provedor OpenID Connect que suporta indicadores de recurso e escopos, permitindo proteger sua API de tarefas com `http://localhost:3001/` como indicador de recurso. + +Como o Logto ainda não suporta Dynamic Client Registration, você precisará registrar manualmente seu cliente MCP (VS Code) como um app de terceiros em seu tenant Logto: + +1. Faça login no [Logto Console](https://cloud.logto.io) (ou em seu Logto Console auto-hospedado). +2. Navegue até **Applications > Third-party apps** e clique em "Create application". +3. Selecione **Native App** como tipo de aplicação. +4. Preencha os detalhes da aplicação: + - **Application name**: Insira um nome para sua aplicação, ex: "MCP Client". + - **Description**: Insira uma descrição, ex: "MCP client for VS Code". +5. Defina os seguintes **Redirect URIs** para o VS Code: + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` +6. Clique em "Save changes". +7. Vá até a aba **Permissions** do app, na seção **User**, adicione as permissões `create:todos`, `read:todos` e `delete:todos` do recurso de API **Todo Manager** que você criou anteriormente. +8. No cartão superior, você verá o valor "App ID". Copie-o para uso posterior. @@ -597,55 +569,54 @@ Como o Logto ainda não suporta Registro Dinâmico de Cliente, você precisará Este é um guia genérico de integração com provedores OAuth 2.0 / OpenID Connect. Ambos seguem passos semelhantes, pois OIDC é construído sobre OAuth 2.0. Consulte a documentação do seu provedor para detalhes específicos. ::: -Se seu provedor suporta Registro Dinâmico de Cliente, você pode ir direto ao passo 8 abaixo para configurar o MCP inspector; caso contrário, será necessário registrar manualmente o MCP inspector como cliente: +Se seu provedor suporta Dynamic Client Registration, você pode pular o registro manual; caso contrário, será necessário registrar manualmente o cliente MCP: -1. Abra seu MCP inspector, vá para a configuração de Autenticação e clique em "OAuth2.0 Flow". Copie o valor do **Redirect URI**, que deve ser algo como `http://localhost:6274/oauth/callback`. +1. Faça login no console do seu provedor. -2. Faça login no console do seu provedor. +2. Navegue até a seção "Applications" ou "Clients" e crie uma nova aplicação ou cliente. -3. Navegue até a seção "Aplicações" ou "Clientes" e crie uma nova aplicação ou cliente. +3. Se seu provedor exigir um tipo de cliente, selecione "Native App" ou "Public client". -4. Se seu provedor exigir um tipo de cliente, selecione "Aplicação de página única" ou "Cliente público". +4. Após criar a aplicação, configure os redirect URIs. Para o VS Code, adicione: -5. Após criar a aplicação, será necessário configurar o redirect URI. Cole o valor do **Redirect URI** copiado do MCP inspector. + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` -6. Encontre o "Client ID" ou "Application ID" da aplicação recém-criada e copie-o. +5. Configure os escopos/permissões necessários para a aplicação: -7. Volte ao MCP inspector e cole o valor "Client ID" na configuração de Autenticação em "OAuth2.0 Flow" no campo "Client ID". + ```text + create:todos read:todos delete:todos + ``` -8. No campo "Scope", insira os seguintes escopos para solicitar as permissões necessárias para operações de tarefas: - -```text -create:todos read:todos delete:todos -``` +6. Encontre o "Client ID" ou "Application ID" da aplicação recém-criada e copie para uso posterior. ### Configure o MCP Auth \{#set-up-mcp-auth} -Primeiro, instale o SDK MCP Auth no seu projeto do servidor MCP. - -import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; +Primeiro, instale o SDK MCP Auth em seu projeto do servidor MCP. -Agora precisamos inicializar o MCP Auth no seu servidor MCP. Com o modo de recurso protegido, você precisa configurar seus metadados de recurso incluindo os servidores de autorização. +Agora precisamos inicializar o MCP Auth em seu servidor MCP. No modo de recurso protegido, você precisa configurar seus metadados de recurso incluindo os authorization servers. -Existem duas formas de configurar servidores de autorização: +Existem duas formas de configurar authorization servers: - **Pré-busca (Recomendado)**: Use `fetchServerConfig()` para buscar os metadados antes de inicializar o MCPAuth. Isso garante que a configuração seja validada na inicialização. -- **Descoberta sob demanda**: Forneça apenas `issuer` e `type` - os metadados serão buscados sob demanda quando necessário. Isso é útil para runtimes edge (como Cloudflare Workers) onde fetch assíncrono no topo do arquivo não é permitido. +- **Descoberta sob demanda**: Forneça apenas `issuer` e `type` - os metadados serão buscados sob demanda quando necessário. Isso é útil para runtimes edge (como Cloudflare Workers) onde não é permitido fetch assíncrono no topo do código. #### Configure os metadados do recurso protegido \{#configure-protected-resource-metadata} -Primeiro, obtenha a URL do emissor do seu servidor de autorização: +Primeiro, obtenha a URL do issuer do seu authorization server: -No Logto, você pode encontrar a URL do emissor na página de detalhes da sua aplicação dentro do Logto Console, na seção "Endpoints & Credentials / Issuer endpoint". Deve ser algo como `https://meu-projeto.logto.app/oidc`. +No Logto, você pode encontrar a URL do issuer na página de detalhes da sua aplicação dentro do Logto Console, na seção "Endpoints & Credentials / Issuer endpoint". Deve ser algo como `https://meu-projeto.logto.app/oidc`. @@ -653,9 +624,9 @@ No Logto, você pode encontrar a URL do emissor na página de detalhes da sua ap Para provedores OAuth 2.0, você precisará: -1. Verificar a documentação do seu provedor para a URL do servidor de autorização (geralmente chamada de issuer URL ou base URL) -2. Alguns provedores podem expor isso em `https://{seu-dominio}/.well-known/oauth-authorization-server` -3. Procurar no console administrativo do seu provedor em configurações OAuth/API +1. Verificar a documentação do seu provedor para a URL do authorization server (geralmente chamada de issuer URL ou base URL) +2. Alguns provedores expõem isso em `https://{seu-dominio}/.well-known/oauth-authorization-server` +3. Procure no console administrativo do seu provedor em configurações OAuth/API @@ -668,12 +639,12 @@ Agora, configure os Metadados do Recurso Protegido ao construir a instância do import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const issuerUrl = ''; // Substitua pela URL do emissor do seu servidor de autorização +const issuerUrl = ''; // Substitua pela URL do issuer do seu authorization server // Defina o identificador do recurso para este servidor MCP -const resourceId = 'http://localhost:3001'; +const resourceId = 'http://localhost:3001/'; -// Pré-busca da configuração do servidor de autorização (recomendado) +// Pré-busque a configuração do authorization server (recomendado) const authServerConfig = await fetchServerConfig(issuerUrl, { type: 'oidc' }); // Configure o MCP Auth com os metadados do recurso protegido @@ -683,32 +654,27 @@ const mcpAuth = new MCPAuth({ resource: resourceId, authorizationServers: [authServerConfig], // Escopos que este servidor MCP entende - scopesSupported: [ - "create:todos", - "read:todos", - "delete:todos" - ] - } - } + scopesSupported: ['create:todos', 'read:todos', 'delete:todos'], + }, + }, }); ``` ### Atualize o servidor MCP \{#update-mcp-server} -Estamos quase lá! É hora de atualizar o servidor MCP para aplicar a rota e o middleware do MCP Auth, depois implementar o controle de acesso baseado em permissões para as ferramentas do gerenciador de tarefas com base nos escopos do usuário. +Estamos quase lá! É hora de atualizar o servidor MCP para aplicar a rota e o middleware do MCP Auth, e então implementar o controle de acesso baseado em permissões para as ferramentas do gerenciador de tarefas com base nos escopos do usuário. -Agora, aplique as rotas de metadados do recurso protegido para que clientes MCP possam recuperar os metadados esperados do recurso a partir do servidor MCP. +Agora, aplique as rotas de metadados de recurso protegido para que clientes MCP possam recuperar os metadados esperados do recurso a partir do servidor MCP. ```ts // todo-manager.ts // Configure as rotas de Metadados do Recurso Protegido -// Isso expõe metadados sobre este servidor de recursos para clientes OAuth +// Isso expõe metadados sobre este resource server para clientes OAuth app.use(mcpAuth.protectedResourceMetadataRouter()); - ``` -Em seguida, aplicaremos o middleware MCP Auth ao servidor MCP. Este middleware irá lidar com a autenticação e autorização das requisições recebidas, garantindo que apenas usuários autorizados possam acessar as ferramentas do gerenciador de tarefas. +Em seguida, aplicaremos o middleware MCP Auth ao servidor MCP. Esse middleware irá lidar com autenticação e autorização das requisições recebidas, garantindo que apenas usuários autorizados possam acessar as ferramentas do gerenciador de tarefas. ```ts // todo-manager.ts @@ -741,7 +707,7 @@ import { TodoService } from './todo-service.js'; const assertUserId = (authInfo?: AuthInfo) => { const { subject } = authInfo ?? {}; - assert(subject, 'Informação de autenticação inválida'); + assert(subject, 'Invalid auth info'); return subject; }; @@ -785,8 +751,8 @@ server.registerTool( const userId = assertUserId(authInfo); /** - * Se o usuário possui o escopo 'read:todos', pode acessar todas as tarefas (todoOwnerId = undefined) - * Se não possui, pode acessar apenas suas próprias tarefas (todoOwnerId = userId) + * Se o usuário tem o escopo 'read:todos', pode acessar todas as tarefas (todoOwnerId = undefined) + * Se não tem, pode acessar apenas suas próprias tarefas (todoOwnerId = userId) */ const todoOwnerId = hasRequiredScopes(authInfo?.scopes ?? [], ['read:todos']) ? undefined @@ -813,7 +779,7 @@ server.registerTool( if (!todo) { return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Falha ao excluir tarefa' }) }], + content: [{ type: 'text', text: JSON.stringify({ error: 'Failed to delete todo' }) }], }; } @@ -826,7 +792,7 @@ server.registerTool( content: [ { type: 'text', - text: JSON.stringify({ error: 'Falha ao excluir tarefa' }), + text: JSON.stringify({ error: 'Failed to delete todo' }), }, ], }; @@ -839,7 +805,7 @@ server.registerTool( { type: 'text', text: JSON.stringify({ - message: `Tarefa ${id} excluída`, + message: `Todo ${id} deleted`, details: deletedTodo, }), }, @@ -865,7 +831,7 @@ type Todo = { /** * Um serviço simples de tarefas para fins de demonstração. - * Usa um array em memória para armazenar as tarefas + * Usa um array em memória para armazenar tarefas */ export class TodoService { private readonly todos: Todo[] = []; @@ -912,7 +878,7 @@ export class TodoService { } ``` -Parabéns! Implementamos com sucesso um servidor MCP completo com Autenticação (Authentication) e Autorização (Authorization)! +Parabéns! Implementamos com sucesso um servidor MCP completo com autenticação e autorização! :::info Confira o [repositório do SDK MCP Auth Node.js](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) para o código completo do servidor MCP (versão OIDC). @@ -920,30 +886,36 @@ Confira o [repositório do SDK MCP Auth Node.js](https://github.com/mcp-auth/js/ ## Checkpoint: Execute as ferramentas `todo-manager` \{#checkpoint-run-the-todo-manager-tools} -Reinicie seu servidor MCP e abra o MCP inspector no navegador. Ao clicar no botão "Connect", você será redirecionado para a página de login do seu servidor de autorização. +Reinicie seu servidor MCP e conecte o VS Code a ele. Veja como conectar com autenticação: -Depois de fazer login e retornar ao MCP inspector, repita as ações do checkpoint anterior para executar as ferramentas do gerenciador de tarefas. Desta vez, você poderá usar essas ferramentas com sua identidade de usuário autenticada. O comportamento das ferramentas dependerá dos papéis e permissões atribuídos ao seu usuário: +1. No VS Code, pressione `Command + Shift + P` (macOS) ou `Ctrl + Shift + P` (Windows/Linux) para abrir a Command Palette. +2. Digite `MCP: Add Server...` e selecione. +3. Escolha `HTTP` como tipo de servidor. +4. Insira a URL do servidor MCP: `http://localhost:3001` +5. Após uma requisição OAuth ser iniciada, o VS Code solicitará que você insira o **App ID**. Insira o App ID copiado do seu authorization server. +6. Como não temos um **App Secret** (é um cliente público), apenas pressione Enter para pular. +7. Complete o fluxo de login no seu navegador. + +Depois de fazer login e retornar ao VS Code, repita as ações do checkpoint anterior para executar as ferramentas do gerenciador de tarefas. Desta vez, você pode usar essas ferramentas com sua identidade de usuário autenticada. O comportamento das ferramentas dependerá dos papéis e permissões atribuídos ao seu usuário: - Se você estiver logado como **User** (com apenas o escopo `create:todos`): - - Você pode criar novas tarefas usando a ferramenta `create-todo` - - Você só pode visualizar e excluir suas próprias tarefas - - Você não poderá ver ou excluir tarefas de outros usuários + - Pode criar novas tarefas usando a ferramenta `create-todo` + - Só pode visualizar e excluir suas próprias tarefas + - Não poderá ver ou excluir tarefas de outros usuários - Se estiver logado como **Admin** (com todos os escopos: `create:todos`, `read:todos`, `delete:todos`): - - Você pode criar novas tarefas + - Pode criar novas tarefas - Pode visualizar todas as tarefas do sistema usando a ferramenta `get-todos` - Pode excluir qualquer tarefa usando a ferramenta `delete-todo`, independentemente de quem a criou Você pode testar esses diferentes níveis de permissão: -1. Saindo da sessão atual (clique no botão "Disconnect" no MCP inspector) +1. Desconectando do servidor MCP (remova a configuração do servidor no VS Code) 2. Fazendo login com outra conta de usuário que tenha papéis/permissões diferentes -3. Tentando as mesmas ferramentas novamente para observar como o comportamento muda de acordo com as permissões do usuário - -Isso demonstra como o Controle de acesso baseado em papel (RBAC) funciona na prática, onde diferentes usuários têm diferentes níveis de acesso à funcionalidade do sistema. +3. Testando as mesmas ferramentas novamente para observar como o comportamento muda de acordo com as permissões do usuário -![Resultado da ferramenta do gerenciador de tarefas no MCP inspector](/docs-assets/images/tutorials/todo-manager/result.png) +Isso demonstra como o controle de acesso baseado em papel (RBAC) funciona na prática, onde diferentes usuários têm diferentes níveis de acesso à funcionalidade do sistema. :::info Confira o [repositório do SDK MCP Auth Node.js](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) para o código completo do servidor MCP (versão OIDC). @@ -953,9 +925,9 @@ Confira o [repositório do SDK MCP Auth Node.js](https://github.com/mcp-auth/js/ Parabéns! Você concluiu com sucesso o tutorial. Vamos recapitular o que fizemos: -- Configuração de um servidor MCP básico com ferramentas de gerenciamento de tarefas (`create-todo`, `get-todos`, `delete-todo`) -- Implementação de Controle de acesso baseado em papel (RBAC) com diferentes níveis de permissão para usuários e administradores -- Integração do servidor MCP com um servidor de autorização usando MCP Auth -- Configuração do MCP Inspector para autenticar usuários e usar tokens de acesso com escopos para chamar ferramentas +- Configuramos um servidor MCP básico com ferramentas de gerenciamento de tarefas (`create-todo`, `get-todos`, `delete-todo`) +- Implementamos controle de acesso baseado em papel (RBAC) com diferentes níveis de permissão para usuários e admins +- Integramos o servidor MCP com um authorization server usando MCP Auth +- Configuramos o VS Code para autenticar usuários e usar tokens de acesso com escopos para chamar ferramentas Não deixe de conferir outros tutoriais e a documentação para aproveitar ao máximo o MCP Auth. \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerModeConfig.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerModeConfig.md index aa8fd5c..95c24f3 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerModeConfig.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerModeConfig.md @@ -12,7 +12,7 @@ type AuthServerModeConfig = { 用于传统 MCP 服务器作为授权服务器模式的配置。 -## 已废弃 {#deprecated} +## 已弃用 {#deprecated} 请改用 `ResourceServerModeConfig` 配置。 @@ -26,6 +26,6 @@ server: AuthServerConfig; 单一授权服务器配置。 -#### 已废弃 {#deprecated} +#### 已弃用 {#deprecated} 请改用 `protectedResources` 配置。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index a902592..c6a1d96 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -3,43 +3,44 @@ sidebar_position: 2 sidebar_label: '教程：构建一个待办事项管理器' --- +import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; # 教程：构建一个待办事项管理器 :::tip Python SDK 可用 -MCP Auth 也支持 Python！请查看 [Python SDK 仓库](https://github.com/mcp-auth/python) 以获取安装和使用方法。 +MCP Auth 也支持 Python！请查看 [Python SDK 仓库](https://github.com/mcp-auth/python) 了解安装和用法。 ::: -在本教程中，我们将构建一个带有用户认证 (Authentication) 和授权 (Authorization) 的待办事项管理器 MCP 服务器。遵循最新的 MCP 规范，我们的 MCP 服务器将作为 OAuth 2.0 **资源服务器 (Resource Server)**，用于验证访问令牌 (Access token) 并强制执行基于权限 (Scope) 的权限控制。 +在本教程中，我们将构建一个带有用户认证 (Authentication) 和授权 (Authorization) 的待办事项管理器 MCP 服务器。按照最新的 MCP 规范，我们的 MCP 服务器将作为 OAuth 2.0 **资源服务器 (Resource Server)**，用于验证访问令牌 (Access token) 并强制执行基于权限 (Scope) 的权限控制。 完成本教程后，你将获得： - ✅ 对如何在 MCP 服务器中设置基于角色的访问控制 (RBAC) 有基本了解 - ✅ 一个作为资源服务器 (Resource Server) 的 MCP 服务器，能够消费由授权服务器 (Authorization Server) 签发的访问令牌 (Access token) -- ✅ 一个基于权限 (Scope) 的待办事项操作权限控制的实际实现 +- ✅ 一个基于权限 (Scope) 强制执行待办事项操作权限的工作实现 ## 概览 \{#overview} 本教程涉及以下组件： -- **MCP 客户端（MCP Inspector）**：一个用于测试 MCP 服务器的可视化工具，作为 OAuth 2.0/OIDC 客户端。它与授权服务器 (Authorization Server) 发起授权流程并获取访问令牌 (Access token) 以认证 (Authentication) 对 MCP 服务器的请求。 -- **授权服务器 (Authorization Server)**：一个 OAuth 2.1 或 OpenID Connect 提供商，负责管理用户身份、认证 (Authentication) 用户，并向已授权客户端签发带有相应权限 (Scope) 的访问令牌 (Access token)。 -- **MCP 服务器（资源服务器 Resource Server）**：根据最新的 MCP 规范，MCP 服务器在 OAuth 2.0 框架中作为资源服务器 (Resource Server)。它验证授权服务器 (Authorization Server) 签发的访问令牌 (Access token)，并对待办事项操作强制执行基于权限 (Scope) 的权限控制。 +- **MCP 客户端（VS Code）**：一个内置 MCP 支持的代码编辑器，作为 OAuth 2.0/OIDC 客户端。它发起与授权服务器的授权流程，并获取访问令牌 (Access token) 以认证 (Authentication) 对 MCP 服务器的请求。 +- **授权服务器 (Authorization Server)**：一个 OAuth 2.1 或 OpenID Connect 提供商，负责管理用户身份、认证 (Authentication) 用户，并向授权客户端签发带有相应权限 (Scope) 的访问令牌 (Access token)。 +- **MCP 服务器（资源服务器 Resource Server）**：根据最新的 MCP 规范，MCP 服务器在 OAuth 2.0 框架中作为资源服务器 (Resource Server)。它验证授权服务器签发的访问令牌 (Access token)，并对待办事项操作强制执行基于权限 (Scope) 的权限控制。 该架构遵循标准的 OAuth 2.0 流程： -- **MCP Inspector** 代表用户请求受保护资源 +- **VS Code** 代表用户请求受保护资源 - **授权服务器 (Authorization Server)** 认证 (Authentication) 用户并签发访问令牌 (Access token) -- **MCP 服务器** 验证令牌并根据已授予的权限 (Permission) 提供受保护资源 +- **MCP 服务器** 验证令牌并根据授予的权限 (Scope) 提供受保护资源 以下是这些组件之间交互的高级流程图： ```mermaid sequenceDiagram autonumber - participant Client as MCP Inspector
(OAuth 客户端) + participant Client as VS Code
(OAuth 客户端) participant RS as MCP 服务器
(资源服务器 Resource Server) participant AS as 授权服务器 (Authorization Server) @@ -62,16 +63,16 @@ sequenceDiagram ## 了解你的授权服务器 \{#understand-your-authorization-server} -### 带有权限 (Scope) 的访问令牌 (Access token) \{#access-tokens-with-scopes} +### 带权限 (Scope) 的访问令牌 (Access token) \{#access-tokens-with-scopes} -要在 MCP 服务器中实现[基于角色的访问控制 (RBAC)](https://auth.wiki/rbac)，你的授权服务器 (Authorization Server) 需要支持签发带有权限 (Scope) 的访问令牌 (Access token)。权限 (Scope) 代表用户被授予的权限 (Permission)。 +要在 MCP 服务器中实现[基于角色的访问控制 (RBAC)](https://auth.wiki/rbac)，你的授权服务器需要支持签发带有权限 (Scope) 的访问令牌 (Access token)。权限 (Scope) 代表用户被授予的权限。 [Logto](https://logto.io) 通过其 API 资源（符合 [RFC 8707: OAuth 2.0 的资源指示器 Resource Indicators](https://datatracker.ietf.org/doc/html/rfc8707)）和角色 (Role) 功能提供 RBAC 支持。设置方法如下： -1. 登录 [Logto Console](https://cloud.logto.io)（或你的自托管 Logto Console） +1. 登录 [Logto 控制台](https://cloud.logto.io)（或你的自托管 Logto 控制台） 2. 创建 API 资源和权限 (Scope)： @@ -85,17 +86,17 @@ sequenceDiagram 3. 创建角色 (Role)（推荐，便于管理）： - 进入“角色 (Roles)” - - 创建一个“Admin”角色，并分配所有权限 (Scope)（`create:todos`、`read:todos`、`delete:todos`） - - 创建一个“User”角色，仅分配 `create:todos` 权限 (Scope) + - 创建一个“Admin”角色，并分配所有权限 (`create:todos`, `read:todos`, `delete:todos`) + - 创建一个“User”角色，仅分配 `create:todos` 权限 -4. 分配权限 (Permission)： +4. 分配权限： - 进入“用户” - 选择一个用户 - 你可以： - - 在“角色 (Roles)”标签页分配角色 (推荐) + - 在“角色 (Roles)”标签页分配角色（推荐） - 或在“权限 (Permissions)”标签页直接分配权限 (Scope) -这些权限 (Scope) 会作为空格分隔的字符串包含在 JWT 访问令牌 (Access token) 的 `scope` 声明 (Claim) 中。 +这些权限 (Scope) 会以空格分隔字符串的形式包含在 JWT 访问令牌 (Access token) 的 `scope` 声明 (Claim) 中。 @@ -104,10 +105,10 @@ OAuth 2.0 / OIDC 提供商通常支持基于权限 (Scope) 的访问控制。实 1. 在授权服务器中定义所需的权限 (Scope) 2. 配置客户端在授权流程中请求这些权限 (Scope) -3. 确保授权服务器在访问令牌 (Access token) 中包含已授予的权限 (Scope) +3. 确保授权服务器在访问令牌 (Access token) 中包含授予的权限 (Scope) 4. 权限 (Scope) 通常包含在 JWT 访问令牌 (Access token) 的 `scope` 声明 (Claim) 中 -请查阅你的提供商文档，了解： +请查阅你的提供商文档，了解以下内容： - 如何定义和管理权限 (Scope) - 权限 (Scope) 如何包含在访问令牌 (Access token) 中 @@ -116,20 +117,20 @@ OAuth 2.0 / OIDC 提供商通常支持基于权限 (Scope) 的访问控制。实 -### 验证令牌并检查权限 (Permission) \{#validating-tokens-and-checking-permissions} +### 验证令牌并检查权限 \{#validating-tokens-and-checking-permissions} 根据最新的 MCP 规范，MCP 服务器在 OAuth 2.0 框架中作为**资源服务器 (Resource Server)**。作为资源服务器 (Resource Server)，MCP 服务器有以下职责： 1. **令牌验证**：验证从 MCP 客户端收到的访问令牌 (Access token) 的真实性和完整性 -2. **权限 (Scope) 强制**：从访问令牌 (Access token) 中提取并验证权限 (Scope)，以确定客户端被授权执行哪些操作 -3. **资源保护**：仅在客户端提供有效且权限 (Permission) 充足的令牌时，才提供受保护资源（执行工具） +2. **权限 (Scope) 强制执行**：从访问令牌 (Access token) 中提取并验证权限 (Scope)，以确定客户端被授权执行哪些操作 +3. **资源保护**：仅在客户端提供有效且权限 (Scope) 足够的令牌时，才提供受保护资源（执行工具） -当 MCP 服务器收到请求时，会执行如下验证流程： +当你的 MCP 服务器收到请求时，会执行如下验证流程： 1. 从 `Authorization` 头中提取访问令牌 (Access token)（Bearer token 格式） 2. 验证访问令牌 (Access token) 的签名和过期时间 3. 从已验证的令牌中提取权限 (Scope) 和用户信息 -4. 检查令牌是否包含所需的权限 (Scope) 以执行请求的操作 +4. 检查令牌是否包含请求操作所需的权限 (Scope) 例如，如果用户想创建新的待办事项，其访问令牌 (Access token) 必须包含 `create:todos` 权限 (Scope)。以下是资源服务器 (Resource Server) 验证流程： @@ -160,16 +161,16 @@ sequenceDiagram end ``` -### 动态客户端注册（Dynamic Client Registration）\{#dynamic-client-registration} +### 动态客户端注册 \{#dynamic-client-registration} -本教程不要求动态客户端注册，但如果你想自动化 MCP 客户端在授权服务器 (Authorization Server) 的注册流程，可以参考 [是否需要动态客户端注册？](/provider-list#is-dcr-required) 了解详情。 +本教程不要求动态客户端注册，但如果你希望自动化 MCP 客户端与授权服务器的注册流程，可以参考 [是否需要动态客户端注册？](/provider-list#is-dcr-required) 了解详情。 ## 了解待办事项管理器中的 RBAC \{#understand-rbac-in-todo-manager} 为了演示，我们将在待办事项管理器 MCP 服务器中实现一个简单的基于角色的访问控制 (RBAC) 系统。这将向你展示 RBAC 的基本原理，同时保持实现简洁。 :::note -虽然本教程演示了基于 RBAC 的权限 (Scope) 管理，但需要注意，并非所有认证 (Authentication) 提供商都通过角色 (Role) 实现权限 (Scope) 管理。有些提供商可能有自己独特的访问控制和权限 (Permission) 管理机制。 +虽然本教程演示了基于 RBAC 的权限 (Scope) 管理，但需要注意，并非所有认证 (Authentication) 提供商都通过角色 (Role) 实现权限 (Scope) 管理。有些提供商可能有自己独特的访问控制和权限管理机制。 ::: ### 工具与权限 (Scope) \{#tools-and-scopes} @@ -178,9 +179,9 @@ sequenceDiagram - `create-todo`：创建新的待办事项 - `get-todos`：列出所有待办事项 -- `delete-todo`：根据 ID 删除待办事项 +- `delete-todo`：按 ID 删除待办事项 -为控制对这些工具的访问，我们定义如下权限 (Scope)： +为了控制对这些工具的访问，我们定义了以下权限 (Scope)： - `create:todos`：允许创建新的待办事项 - `delete:todos`：允许删除现有待办事项 @@ -195,21 +196,21 @@ sequenceDiagram | Admin | ✅ | ✅ | ✅ | | User | ✅ | | | -- **User**：普通用户，可以创建待办事项，仅能查看或删除自己的待办事项 -- **Admin**：管理员，可以创建、查看和删除所有待办事项，无论归属 +- **User**：普通用户，可以创建待办事项，并仅查看或删除自己的待办事项 +- **Admin**：管理员，可以创建、查看和删除所有待办事项，无论归属谁 -### 资源归属 (Resource Ownership) \{#resource-ownership} +### 资源归属 \{#resource-ownership} -虽然上表展示了每个角色 (Role) 明确分配的权限 (Scope)，但还有一个重要的资源归属原则： +虽然上表显示了每个角色 (Role) 明确分配的权限 (Scope)，但还有一个重要的资源归属原则： -- **User** 没有 `read:todos` 或 `delete:todos` 权限 (Scope)，但仍然可以： +- **User** 没有 `read:todos` 或 `delete:todos` 权限 (Scope)，但他们仍然可以： - 查看自己的待办事项 - 删除自己的待办事项 - **Admin** 拥有全部权限 (`read:todos` 和 `delete:todos`)，可以： - 查看系统中所有待办事项 - - 删除任意待办事项，无论归属 + - 删除任意待办事项，无论归属谁 -这体现了 RBAC 系统中的常见模式：资源归属为用户自己的资源隐式授予权限 (Permission)，而管理员角色 (Role) 则获得所有资源的显式权限 (Permission)。 +这体现了 RBAC 系统中的常见模式：资源归属为用户自己的资源隐式授予权限，而管理员角色 (Role) 则对所有资源拥有显式权限。 :::tip 了解更多 想深入了解 RBAC 概念和最佳实践，请查看 [精通 RBAC：一个全面的真实案例](https://blog.logto.io/mastering-rbac)。 @@ -217,20 +218,20 @@ sequenceDiagram ## 在你的提供商中配置授权 (Authorization) \{#configure-authorization-in-your-provider} -要实现前述访问控制系统，你需要在授权服务器 (Authorization Server) 中配置所需的权限 (Scope)。不同提供商的配置方法如下： +要实现我们前述的访问控制系统，你需要在授权服务器中配置所需的权限 (Scope)。不同提供商的配置方法如下： [Logto](https://logto.io) 通过其 API 资源和角色 (Role) 功能提供 RBAC 支持。设置方法如下： -1. 登录 [Logto Console](https://cloud.logto.io)（或你的自托管 Logto Console） +1. 登录 [Logto 控制台](https://cloud.logto.io)（或你的自托管 Logto 控制台） 2. 创建 API 资源和权限 (Scope)： - 进入“API 资源” - - 创建一个名为“Todo Manager”的新 API 资源，并使用 `http://localhost:3001` 作为资源指示器 (Resource indicator)。 - - **重要**：资源指示器 (Resource indicator) 必须与你的 MCP 服务器 URL 匹配。本教程使用 `http://localhost:3001`，因为 MCP 服务器运行在 3001 端口。生产环境请使用实际 MCP 服务器 URL（如 `https://your-mcp-server.example.com`）。 + - 创建一个名为“Todo Manager”的新 API 资源，并使用 `http://localhost:3001/` 作为资源指示器 (Resource indicator)。 + - **重要**：资源指示器 (Resource indicator) 必须与你的 MCP 服务器 URL 完全一致。本教程使用 `http://localhost:3001/`，因为 MCP 服务器运行在 3001 端口。生产环境请使用实际 MCP 服务器 URL（如 `https://your-mcp-server.example.com/`）。 - 创建以下权限 (Scope)： - `create:todos`：“创建新的待办事项” - `read:todos`：“读取所有待办事项” @@ -239,28 +240,28 @@ sequenceDiagram 3. 创建角色 (Role)（推荐，便于管理）： - 进入“角色 (Roles)” - - 创建一个“Admin”角色，并分配所有权限 (Scope)（`create:todos`、`read:todos`、`delete:todos`） - - 创建一个“User”角色，仅分配 `create:todos` 权限 (Scope) + - 创建一个“Admin”角色，并分配所有权限 (`create:todos`, `read:todos`, `delete:todos`) + - 创建一个“User”角色，仅分配 `create:todos` 权限 - 在“User”角色详情页，切换到“常规”标签，并将“User”角色设置为“默认角色 (Default role)”。 4. 管理用户角色 (Role) 和权限 (Permission)： - 新用户： - - 因为我们设置了默认角色 (Default role)，新用户会自动获得“User”角色 + - 因为设置了默认角色，注册后会自动获得“User”角色 - 已有用户： - 进入“用户管理” - 选择一个用户 - 在“角色 (Roles)”标签页为用户分配角色 :::tip 编程方式管理角色 (Role) -你也可以使用 Logto 的 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) 以编程方式管理用户角色 (Role)。这对于自动化用户管理或构建管理后台非常有用。 +你也可以使用 Logto 的 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) 以编程方式管理用户角色 (Role)。这对于自动化用户管理或构建管理后台特别有用。 ::: -请求访问令牌 (Access token) 时，Logto 会根据用户角色 (Role) 权限 (Permission) 在令牌的 `scope` 声明 (Claim) 中包含相应权限 (Scope)。 +请求访问令牌 (Access token) 时，Logto 会根据用户角色 (Role) 权限将权限 (Scope) 包含在令牌的 `scope` 声明 (Claim) 中。 -对于 OAuth 2.0 或 OpenID Connect 提供商，你需要配置代表不同权限 (Permission) 的权限 (Scope)。具体步骤视提供商而定，但一般包括： +对于 OAuth 2.0 或 OpenID Connect 提供商，你需要配置代表不同权限的权限 (Scope)。具体步骤视你的提供商而定，但通常包括： 1. 定义权限 (Scope)： @@ -275,18 +276,22 @@ sequenceDiagram - 确保权限 (Scope) 被包含在访问令牌 (Access token) 中 3. 分配权限 (Permission)： - - 使用提供商界面为用户分配合适的权限 (Scope) - - 有些提供商支持基于角色 (Role) 的管理，另一些则直接分配权限 (Scope) - - 查阅提供商文档获取推荐做法 + - 使用你的提供商界面为用户授予相应权限 (Scope) + - 有些提供商支持基于角色 (Role) 的管理，有些则直接分配权限 (Scope) + - 查阅你的提供商文档，了解推荐做法 :::tip -大多数提供商会在访问令牌 (Access token) 的 `scope` 声明 (Claim) 中包含已授予的权限 (Scope)。格式通常为空格分隔的权限 (Scope) 字符串。 +大多数提供商会将授予的权限 (Scope) 以空格分隔字符串的形式包含在访问令牌 (Access token) 的 `scope` 声明 (Claim) 中。 ::: -配置好授权服务器 (Authorization Server) 后，用户将获得包含其权限 (Scope) 的访问令牌 (Access token)。MCP 服务器将使用这些权限 (Scope) 判断： +:::note[资源指示器 (Resource indicator) 末尾斜杠] +资源指示器 (Resource indicator) 一定要带上末尾斜杠（`/`）。由于 MCP 官方 SDK 当前存在一个 bug，使用该 SDK 的客户端在发起认证 (Authentication) 请求时会自动在资源标识符后追加斜杠。如果你的资源指示器没有斜杠，这些客户端的资源验证会失败。（VS Code 不受此 bug 影响。） +::: + +配置好授权服务器后，用户将获得包含其权限 (Scope) 的访问令牌 (Access token)。MCP 服务器将使用这些权限 (Scope) 判断： - 用户是否可以创建新的待办事项（`create:todos`） - 用户是否可以查看所有待办事项（`read:todos`）或仅能查看自己的 @@ -298,7 +303,7 @@ sequenceDiagram ### 创建新项目 \{#create-a-new-project} -搭建一个新的 Node.js 项目： +创建一个新的 Node.js 项目： ```bash mkdir mcp-server @@ -310,7 +315,7 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -我们的示例使用 TypeScript，因为 Node.js v22.6.0+ 原生支持通过 `--experimental-strip-types` 运行 TypeScript。如果你使用 JavaScript，代码类似——只需确保 Node.js 版本为 v22.6.0 或更高。详情见 Node.js 官方文档。 +我们的示例使用 TypeScript，因为 Node.js v22.6.0+ 原生支持通过 `--experimental-strip-types` 运行 TypeScript。如果你使用 JavaScript，代码类似——只需确保 Node.js 版本为 v22.6.0 或更高。详见 Node.js 官方文档。 ::: ### 安装 MCP SDK 及依赖 \{#install-the-mcp-sdk-and-dependencies} @@ -325,7 +330,7 @@ npm install @modelcontextprotocol/sdk express zod 创建名为 `todo-manager.ts` 的文件，并添加如下代码： -（代码内容保持原样，不翻译） +（代码部分保持原样，不翻译） 运行服务器： @@ -333,84 +338,46 @@ npm install @modelcontextprotocol/sdk express zod npm start ``` -## 检查 MCP 服务器 \{#inspect-the-mcp-server} - -### 克隆并运行 MCP inspector \{#clone-and-run-mcp-inspector} - -现在 MCP 服务器已运行，我们可以使用 MCP inspector 检查工具是否可用。 - -官方 MCP inspector v0.16.2 存在一些影响认证 (Authentication) 功能的 bug。为了解决这些问题，我们制作了一个[修补版 MCP inspector](https://github.com/mcp-auth/inspector/tree/patch/0.16.2-fixes)，包含了 OAuth/OIDC 认证 (Authentication) 流程所需的修复。我们也已向官方仓库提交了 PR。 - -运行 MCP inspector： - -```bash -git clone https://github.com/mcp-auth/inspector.git -b patch/0.16.2-fixes -cd inspector -npm install -npm run dev -``` - -MCP inspector 会自动在默认浏览器中打开，或你也可以手动点击终端输出中的链接（确保点击带有 `MCP_PROXY_AUTH_TOKEN` 参数的链接，如 `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=458ae4a4...acab1907`）。 - -### 连接 MCP inspector 到 MCP 服务器 \{#connect-mcp-inspector-to-the-mcp-server} - -在继续之前，请检查 MCP inspector 的以下配置： - -- **Transport Type**：设置为 `Streamable HTTP` -- **URL**：设置为你的 MCP 服务器 URL，本例为 `http://localhost:3001` +## 与授权服务器集成 \{#integrate-with-your-authorization-server} -现在点击“Connect”按钮，查看 MCP inspector 是否能连接到 MCP 服务器。如果一切正常，你会在 MCP inspector 中看到“Connected”状态。 - -### 检查点：运行待办事项管理工具 \{#checkpoint-run-todo-manager-tools} - -1. 在 MCP inspector 顶部菜单点击“Tools”标签 -2. 点击“List Tools”按钮 -3. 你应该能看到 `create-todo`、`get-todos` 和 `delete-todo` 工具被列出。点击可查看工具详情 -4. 右侧会有“Run Tool”按钮。点击并输入所需参数运行工具 -5. 你会看到工具返回的 JSON 响应 `{"error": "Not implemented"}` - -![MCP inspector 首次运行](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## 集成你的授权服务器 \{#integrate-with-your-authorization-server} - -完成本节前，有几个注意事项： +完成本节前，你需要考虑以下事项：
**你的授权服务器的发行者 (Issuer) URL** -通常是你的授权服务器的基础 URL，如 `https://auth.example.com`。有些提供商可能是 `https://example.logto.app/oidc`，请查阅提供商文档。 +通常是你的授权服务器的基础 URL，如 `https://auth.example.com`。有些提供商可能是 `https://example.logto.app/oidc`，请查阅你的提供商文档。
**如何获取授权服务器元数据** -- 如果你的授权服务器符合 [OAuth 2.0 授权服务器元数据](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，可以用 MCP Auth 内置工具自动获取元数据 -- 如果不符合这些标准，你需要在 MCP 服务器配置中手动指定元数据 URL 或端点。查阅提供商文档获取具体端点 +- 如果你的授权服务器符合 [OAuth 2.0 授权服务器元数据](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect 发现](https://openid.net/specs/openid-connect-discovery-1_0.html)，你可以使用 MCP Auth 内置工具自动获取元数据。 +- 如果不符合这些标准，你需要在 MCP 服务器配置中手动指定元数据 URL 或端点。请查阅你的提供商文档。
-**如何将 MCP inspector 注册为授权服务器客户端** +**如何在授权服务器注册 MCP 客户端** -- 如果你的授权服务器支持 [动态客户端注册 (Dynamic Client Registration)](https://datatracker.ietf.org/doc/html/rfc7591)，可以跳过此步，MCP inspector 会自动注册 -- 如果不支持动态客户端注册，需要手动在授权服务器中注册 MCP inspector 为客户端 +- 如果你的授权服务器支持 [动态客户端注册](https://datatracker.ietf.org/doc/html/rfc7591)，可以跳过此步骤，MCP 客户端会自动注册。 +- 如果不支持动态客户端注册，你需要手动在授权服务器注册 MCP 客户端。
**了解令牌请求参数** -向不同授权服务器请求访问令牌 (Access token) 时，指定目标资源和权限 (Scope) 的方式各异，主要有： +向不同授权服务器请求访问令牌 (Access token) 时，指定目标资源和权限 (Scope) 的方式各有不同。主要模式如下： - **基于资源指示器 (Resource indicator)**： - 使用 `resource` 参数指定目标 API（见 [RFC 8707: OAuth 2.0 的资源指示器](https://datatracker.ietf.org/doc/html/rfc8707)） - - 现代 OAuth 2.0 实现常用 + - 现代 OAuth 2.0 实现常见 - 示例请求： ```json { - "resource": "http://localhost:3001", + "resource": "http://localhost:3001/", "scope": "create:todos read:todos" } ``` @@ -419,7 +386,7 @@ MCP inspector 会自动在默认浏览器中打开，或你也可以手动点击 - **基于受众 (Audience)**： - 使用 `audience` 参数指定令牌接收方 - - 与资源指示器类似但语义不同 + - 与资源指示器类似，但语义不同 - 示例请求： ```json { @@ -437,69 +404,74 @@ MCP inspector 会自动在默认浏览器中打开，或你也可以手动点击 "scope": "todo-api:create todo-api:read openid profile" } ``` - - 常用前缀权限 (Scope) 进行命名空间隔离 - - 适用于较简单的 OAuth 2.0 实现 + - 通常用前缀权限 (Scope) 进行命名空间隔离 + - 简单 OAuth 2.0 实现常见 :::tip 最佳实践 - 查阅你的提供商文档，了解支持哪些参数 - 有些提供商同时支持多种方式 - 资源指示器 (Resource indicator) 通过受众限制提升安全性 -- 如可用，建议优先使用资源指示器 (Resource indicator) 以获得更好的访问控制 +- 如可用，优先使用资源指示器 (Resource indicator) 以获得更好的访问控制 :::
-每个提供商可能有自己的具体要求，以下步骤将指导你如何结合 MCP inspector 和 MCP 服务器进行针对性配置。 +每个提供商可能有自己的具体要求，以下步骤将指导你如何结合 VS Code 和 MCP 服务器进行集成，并进行针对性配置。 -### 注册 MCP inspector 为客户端 \{#register-mcp-inspector-as-a-client} +### 注册 MCP 客户端为第三方应用 \{#register-mcp-client-as-a-third-party-app} -将待办事项管理器集成到 [Logto](https://logto.io) 非常简单，因为它是支持资源指示器 (Resource indicator) 和权限 (Scope) 的 OpenID Connect 提供商，可以用 `http://localhost:3001` 作为资源指示器保护你的 todo API。 - -由于 Logto 目前尚不支持动态客户端注册 (Dynamic Client Registration)，你需要手动在 Logto 租户中注册 MCP inspector 为客户端： - -1. 打开 MCP inspector，进入认证 (Authentication) 配置，点击 "OAuth2.0 Flow" 配置。复制 **Redirect URI**，如 `http://localhost:6274/oauth/callback` -2. 登录 [Logto Console](https://cloud.logto.io)（或你的自托管 Logto Console） -3. 进入“应用程序”标签，点击“创建应用程序”。页面底部点击“无框架创建应用” -4. 填写应用详情，点击“创建应用程序”： - - **选择应用类型**：选择“单页应用” - - **应用名称**：如 "MCP Inspector" -5. 在“设置 / Redirect URIs”部分，粘贴刚才复制的 **Redirect URI**，然后点击底部栏“保存更改” -6. 顶部卡片会显示 "App ID"，复制它 -7. 回到 MCP inspector，在认证 (Authentication) 配置的 "OAuth2.0 Flow" 下的 "Client ID" 字段粘贴 "App ID" -8. 在 "Scope" 字段输入：`create:todos read:todos delete:todos`，确保 Logto 返回的访问令牌 (Access token) 包含访问 todo manager 所需的权限 (Scope) +将待办事项管理器与 [Logto](https://logto.io) 集成非常简单，因为它是支持资源指示器 (Resource indicator) 和权限 (Scope) 的 OpenID Connect 提供商，可以用 `http://localhost:3001/` 作为资源指示器保护你的 todo API。 + +由于 Logto 目前尚不支持动态客户端注册，你需要手动将 MCP 客户端（VS Code）注册为 Logto 租户的第三方应用： + +1. 登录 [Logto 控制台](https://cloud.logto.io)（或你的自托管 Logto 控制台）。 +2. 进入 **应用程序 > 第三方应用**，点击“创建应用”。 +3. 选择 **原生应用 (Native App)** 作为应用类型。 +4. 填写应用信息： + - **应用名称**：如“MCP Client” + - **描述**：如“VS Code 的 MCP 客户端” +5. 为 VS Code 设置以下 **重定向 URI**： + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` +6. 点击“保存更改”。 +7. 进入应用的 **权限 (Permissions)** 标签页，在 **用户** 部分，添加你之前创建的 **Todo Manager** API 资源下的 `create:todos`、`read:todos` 和 `delete:todos` 权限。 +8. 在顶部卡片中，你会看到“App ID”值。复制备用。 :::note -这是通用的 OAuth 2.0 / OpenID Connect 提供商集成指南。OIDC 基于 OAuth 2.0，流程类似。具体细节请查阅你的提供商文档。 +这是通用的 OAuth 2.0 / OpenID Connect 提供商集成指南。OAuth 2.0 和 OIDC 步骤类似，因为 OIDC 构建在 OAuth 2.0 之上。具体细节请查阅你的提供商文档。 ::: -如果你的提供商支持动态客户端注册 (Dynamic Client Registration)，可直接跳到第 8 步配置 MCP inspector；否则需手动注册 MCP inspector 为客户端： +如果你的提供商支持动态客户端注册，可以跳过手动注册；否则需要手动注册 MCP 客户端： -1. 打开 MCP inspector，进入认证 (Authentication) 配置，点击 "OAuth2.0 Flow" 配置。复制 **Redirect URI**，如 `http://localhost:6274/oauth/callback` +1. 登录你的提供商控制台。 -2. 登录你的提供商控制台 +2. 进入“应用程序”或“客户端”部分，创建新应用或客户端。 -3. 进入“应用程序”或“客户端”部分，创建新应用或客户端 +3. 如需选择客户端类型，选择“原生应用 (Native App)”或“公共客户端 (Public client)”。 -4. 如需选择客户端类型，选“单页应用”或“公有客户端” +4. 创建应用后，配置重定向 URI。对于 VS Code，添加如下： -5. 创建应用后，需配置重定向 URI，粘贴刚才复制的 **Redirect URI** + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` -6. 找到新建应用的 "Client ID" 或 "Application ID"，复制 +5. 为应用配置所需权限 (Scope)： -7. 回到 MCP inspector，在认证 (Authentication) 配置的 "OAuth2.0 Flow" 下的 "Client ID" 字段粘贴 + ```text + create:todos read:todos delete:todos + ``` -8. 在 "Scope" 字段输入以下权限 (Scope) 以请求待办事项操作所需权限： - -```text -create:todos read:todos delete:todos -``` +6. 找到新建应用的“Client ID”或“Application ID”，复制备用。 @@ -508,35 +480,33 @@ create:todos read:todos delete:todos 首先，在 MCP 服务器项目中安装 MCP Auth SDK。 -import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; - -现在需要在 MCP 服务器中初始化 MCP Auth。在受保护资源模式下，你需要配置资源元数据，包括授权服务器 (Authorization Server)。 +现在需要在 MCP 服务器中初始化 MCP Auth。在受保护资源模式下，你需要配置资源元数据，包括授权服务器信息。 -有两种方式配置授权服务器 (Authorization Server)： +配置授权服务器有两种方式： -- **预获取（推荐）**：使用 `fetchServerConfig()` 在初始化 MCPAuth 前获取元数据，确保配置在启动时已验证 -- **按需发现**：只提供 `issuer` 和 `type`，首次需要时再获取元数据。适用于如 Cloudflare Workers 等不允许顶层异步 fetch 的边缘运行时 +- **预获取（推荐）**：使用 `fetchServerConfig()` 在初始化 MCPAuth 前获取元数据，确保启动时配置已验证。 +- **按需发现**：只提供 `issuer` 和 `type`，首次需要时再获取元数据。适用于如 Cloudflare Workers 等不允许顶层异步 fetch 的边缘运行时。 #### 配置受保护资源元数据 \{#configure-protected-resource-metadata} -首先获取你的授权服务器 (Authorization Server) 的发行者 (Issuer) URL： +首先，获取你的授权服务器发行者 (Issuer) URL： -在 Logto 中，你可以在 Logto Console 的应用详情页 "Endpoints & Credentials / Issuer endpoint" 部分找到发行者 (Issuer) URL，格式如 `https://my-project.logto.app/oidc`。 +在 Logto 中，你可以在 Logto 控制台的应用详情页“端点与凭据 / 发行者端点 (Issuer endpoint)”部分找到发行者 (Issuer) URL，格式类似 `https://my-project.logto.app/oidc`。 -对于 OAuth 2.0 提供商： +对于 OAuth 2.0 提供商，你需要： -1. 查阅提供商文档获取授权服务器 (Authorization Server) URL（通常称为发行者 (Issuer) URL 或基础 URL） -2. 有些提供商会暴露在 `https://{your-domain}/.well-known/oauth-authorization-server` +1. 查阅你的提供商文档，获取授权服务器 URL（通常称为发行者 (Issuer) URL 或基础 URL） +2. 有些提供商会在 `https://{your-domain}/.well-known/oauth-authorization-server` 暴露此信息 3. 在提供商管理后台的 OAuth/API 设置中查找 @@ -545,43 +515,51 @@ import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; 现在，在构建 MCP Auth 实例时配置受保护资源元数据： -（代码内容保持原样，不翻译） +（代码部分保持原样，不翻译） ### 更新 MCP 服务器 \{#update-mcp-server} -快完成了！现在需要更新 MCP 服务器，应用 MCP Auth 路由和中间件函数，并基于用户权限 (Scope) 实现待办事项工具的权限控制。 +我们快完成了！现在需要更新 MCP 服务器，应用 MCP Auth 路由和中间件，并基于用户权限 (Scope) 实现待办事项工具的权限控制。 首先，应用受保护资源元数据路由，让 MCP 客户端可以从 MCP 服务器获取资源元数据。 -（代码内容保持原样，不翻译） +（代码部分保持原样，不翻译） -接下来，应用 MCP Auth 中间件到 MCP 服务器。该中间件将处理所有请求的认证 (Authentication) 和授权 (Authorization)，确保只有被授权用户才能访问待办事项工具。 +接下来，应用 MCP Auth 中间件到 MCP 服务器。该中间件会处理所有请求的认证 (Authentication) 和授权 (Authorization)，确保只有被授权的用户才能访问待办事项工具。 -（代码内容保持原样，不翻译） +（代码部分保持原样，不翻译） -现在可以更新待办事项工具的实现，利用 MCP Auth 中间件进行认证 (Authentication) 和授权 (Authorization)。 +现在，我们可以更新待办事项工具的实现，利用 MCP Auth 中间件进行认证 (Authentication) 和授权 (Authorization)。 -（代码内容保持原样，不翻译） +（代码部分保持原样，不翻译） -接下来，创建上述代码用到的 "Todo service"： +接下来，创建上面代码中用到的“Todo service”： -创建 `todo-service.ts` 文件： +创建 `todo-service.ts` 文件，实现相关功能： -（代码内容保持原样，不翻译） +（代码部分保持原样，不翻译） 恭喜！我们已经成功实现了一个带有认证 (Authentication) 和授权 (Authorization) 的完整 MCP 服务器！ :::info -完整 MCP 服务器（OIDC 版本）代码请参考 [MCP Auth Node.js SDK 仓库](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。 +查看 [MCP Auth Node.js SDK 仓库](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) 获取 MCP 服务器（OIDC 版本）的完整代码。 ::: ## 检查点：运行 `todo-manager` 工具 \{#checkpoint-run-the-todo-manager-tools} -重启 MCP 服务器，并在浏览器中打开 MCP inspector。点击“Connect”按钮后，你会被重定向到授权服务器 (Authorization Server) 的登录页面。 +重启你的 MCP 服务器，并用 VS Code 连接它。以下是带认证 (Authentication) 的连接方法： + +1. 在 VS Code 中，按下 `Command + Shift + P`（macOS）或 `Ctrl + Shift + P`（Windows/Linux）打开命令面板。 +2. 输入 `MCP: Add Server...` 并选择它。 +3. 选择 `HTTP` 作为服务器类型。 +4. 输入 MCP 服务器 URL：`http://localhost:3001` +5. OAuth 请求发起后，VS Code 会提示你输入 **App ID**。输入你从授权服务器复制的 App ID。 +6. 因为我们没有 **App Secret**（这是公共客户端），直接回车跳过。 +7. 在浏览器中完成登录流程。 -登录后返回 MCP inspector，重复上一个检查点的操作运行待办事项工具。这一次，你可以用已认证 (Authentication) 的用户身份使用这些工具。工具的行为将根据分配给你的角色 (Role) 和权限 (Permission) 而变化： +登录并返回 VS Code 后，重复上一个检查点的操作，运行待办事项管理器工具。这一次，你可以用已认证 (Authentication) 的用户身份使用这些工具。工具的行为将取决于你用户的角色 (Role) 和权限 (Permission)： -- 如果你以 **User**（仅有 `create:todos` 权限 (Scope)）身份登录： +- 如果你以 **User**（仅有 `create:todos` 权限）身份登录： - 可以用 `create-todo` 工具创建新待办事项 - 只能查看和删除自己的待办事项 @@ -590,29 +568,27 @@ import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; - 如果你以 **Admin**（拥有全部权限：`create:todos`、`read:todos`、`delete:todos`）身份登录： - 可以创建新待办事项 - 可以用 `get-todos` 工具查看系统中所有待办事项 - - 可以用 `delete-todo` 工具删除任意待办事项，无论归属 + - 可以用 `delete-todo` 工具删除任意待办事项，无论归属谁 你可以通过以下方式测试不同权限级别： -1. 退出当前会话（在 MCP inspector 点击“Disconnect”按钮） -2. 用另一个拥有不同角色 (Role)/权限 (Permission) 的用户账号登录 -3. 再次尝试相同工具，观察根据用户权限 (Permission) 行为的变化 +1. 断开 MCP 服务器连接（在 VS Code 中移除服务器配置） +2. 用拥有不同角色 (Role)/权限 (Permission) 的其他用户账号登录 +3. 再次尝试相同工具，观察因用户权限不同而产生的行为变化 这展示了基于角色的访问控制 (RBAC) 在实际中的工作方式，不同用户对系统功能有不同访问级别。 -![MCP inspector 待办事项工具结果](/docs-assets/images/tutorials/todo-manager/result.png) - :::info -完整 MCP 服务器（OIDC 版本）代码请参考 [MCP Auth Node.js SDK 仓库](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。 +查看 [MCP Auth Node.js SDK 仓库](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) 获取 MCP 服务器（OIDC 版本）的完整代码。 ::: ## 结语 \{#closing-notes} 恭喜！你已成功完成本教程。让我们回顾一下所做的内容： -- 搭建了一个基础 MCP 服务器并实现了待办事项管理工具（`create-todo`、`get-todos`、`delete-todo`） +- 搭建了一个基础的 MCP 服务器，包含待办事项管理工具（`create-todo`、`get-todos`、`delete-todo`） - 实现了基于角色的访问控制 (RBAC)，为用户和管理员设置了不同权限级别 -- 使用 MCP Auth 将 MCP 服务器与授权服务器 (Authorization Server) 集成 -- 配置 MCP Inspector 认证 (Authentication) 用户，并用带有权限 (Scope) 的访问令牌 (Access token) 调用工具 +- 使用 MCP Auth 将 MCP 服务器与授权服务器集成 +- 配置 VS Code 认证 (Authentication) 用户，并用带权限 (Scope) 的访问令牌 (Access token) 调用工具 -欢迎查阅其他教程和文档，充分发挥 MCP Auth 的强大功能。 \ No newline at end of file +欢迎查阅其他教程和文档，充分发挥 MCP Auth 的强大能力。 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigWarning.md b/i18n/zh-TW/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigWarning.md index 2cd45b3..37c2826 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigWarning.md +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/references/js/type-aliases/AuthServerConfigWarning.md @@ -2,7 +2,7 @@ sidebar_label: AuthServerConfigWarning --- -# 型別別名：AuthServerConfigWarning +# 型別別名：AuthServerConfigWarning (Type Alias: AuthServerConfigWarning) ```ts type AuthServerConfigWarning = { @@ -13,7 +13,7 @@ type AuthServerConfigWarning = { 表示在驗證授權伺服器中繼資料時發生的警告。 -## 屬性 {#properties} +## 屬性 (Properties) {#properties} ### code {#code} @@ -31,4 +31,4 @@ code: AuthServerConfigWarningCode; description: string; ``` -對警告的人類可讀描述。 +對警告的人類可讀描述。 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index 48e467d..2fdb3c1 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -1,45 +1,46 @@ --- sidebar_position: 2 -sidebar_label: '教學：打造待辦事項管理器' +sidebar_label: '教學：打造待辦事項管理器 (Tutorial: Build a todo manager)' --- +import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; -# 教學：打造待辦事項管理器 +# 教學：打造待辦事項管理器 (Tutorial: Build a todo manager) :::tip Python SDK available MCP Auth 也支援 Python！請參考 [Python SDK repository](https://github.com/mcp-auth/python) 以取得安裝與使用方式。 ::: -在本教學中，我們將建立一個具備使用者驗證 (Authentication) 與授權 (Authorization) 的待辦事項管理器 MCP 伺服器。根據最新的 MCP 規範，我們的 MCP 伺服器將作為 OAuth 2.0 **資源伺服器 (Resource Server)**，負責驗證存取權杖 (Access token) 並執行基於權限範圍 (Scope) 的權限控管。 +在本教學中，我們將建立一個具備使用者驗證 (Authentication) 與授權 (Authorization) 的待辦事項管理器 MCP 伺服器。根據最新 MCP 規範，我們的 MCP 伺服器將作為 OAuth 2.0 **資源伺服器 (Resource Server)**，負責驗證存取權杖 (Access token) 並執行基於權限範圍 (Scope) 的權限控管。 完成本教學後，你將會： -- ✅ 基本瞭解如何在 MCP 伺服器中設定角色型存取控制 (RBAC, Role-based Access Control) +- ✅ 基本瞭解如何在 MCP 伺服器中設置角色型存取控制 (RBAC, Role-based access control) - ✅ 擁有一個作為資源伺服器 (Resource Server) 的 MCP 伺服器，能消耗由授權伺服器 (Authorization Server) 發出的存取權杖 (Access token) - ✅ 實作基於權限範圍 (Scope) 的待辦事項操作權限控管 -## 概覽 \{#overview} +## 概覽 (Overview) \{#overview} 本教學將包含以下元件： -- **MCP 用戶端（MCP Inspector）**：一個用於測試 MCP 伺服器的視覺化工具，作為 OAuth 2.0 / OIDC 用戶端。它會與授權伺服器啟動授權流程並取得存取權杖 (Access token) 來驗證對 MCP 伺服器的請求。 -- **授權伺服器 (Authorization Server)**：一個 OAuth 2.1 或 OpenID Connect 簽發者 (Issuer)，負責管理使用者身分、驗證使用者並向授權用戶端發出具備適當權限範圍 (Scope) 的存取權杖 (Access token)。 -- **MCP 伺服器（資源伺服器 Resource Server）**：根據最新 MCP 規範，MCP 伺服器在 OAuth 2.0 架構中作為資源伺服器 (Resource Server)。它負責驗證授權伺服器發出的存取權杖 (Access token)，並根據權限範圍 (Scope) 控管待辦事項操作。 +- **MCP 用戶端 (VS Code)**：一個內建 MCP 支援的程式碼編輯器，作為 OAuth 2.0 / OIDC 用戶端。它會與授權伺服器啟動授權流程並取得存取權杖 (Access token) 以驗證對 MCP 伺服器的請求。 +- **授權伺服器 (Authorization Server)**：一個 OAuth 2.1 或 OpenID Connect 提供者，負責管理使用者身分、驗證使用者並向授權用戶端發放帶有適當權限範圍 (Scope) 的存取權杖 (Access token)。 +- **MCP 伺服器 (資源伺服器, Resource Server)**：根據最新 MCP 規範，MCP 伺服器在 OAuth 2.0 架構中作為資源伺服器 (Resource Server)。它驗證授權伺服器發出的存取權杖 (Access token)，並針對待辦事項操作執行基於權限範圍 (Scope) 的權限控管。 此架構遵循標準 OAuth 2.0 流程： -- **MCP Inspector** 代表使用者請求受保護資源 -- **授權伺服器 (Authorization Server)** 驗證使用者並發出存取權杖 (Access token) +- **VS Code** 代表使用者請求受保護資源 +- **授權伺服器 (Authorization Server)** 驗證使用者並發放存取權杖 (Access token) - **MCP 伺服器 (Resource Server)** 驗證權杖並根據授權權限提供受保護資源 -以下是這些元件互動的高階流程圖： +以下是這些元件互動的高階圖示： ```mermaid sequenceDiagram autonumber - participant Client as MCP Inspector
(OAuth 用戶端) + participant Client as VS Code
(OAuth 用戶端) participant RS as MCP 伺服器
(資源伺服器) participant AS as 授權伺服器 (Authorization Server) @@ -60,24 +61,24 @@ sequenceDiagram RS-->>Client: MCP 回應 ``` -## 瞭解你的授權伺服器 \{#understand-your-authorization-server} +## 瞭解你的授權伺服器 (Understand your authorization server) \{#understand-your-authorization-server} ### 具備權限範圍 (Scope) 的存取權杖 (Access tokens) \{#access-tokens-with-scopes} -要在 MCP 伺服器中實作 [角色型存取控制 (RBAC)](https://auth.wiki/rbac)，你的授權伺服器需支援發出具備權限範圍 (Scope) 的存取權杖 (Access token)。權限範圍 (Scope) 代表使用者被授予的權限。 +若要在 MCP 伺服器中實作 [角色型存取控制 (RBAC)](https://auth.wiki/rbac)，你的授權伺服器需支援發放帶有權限範圍 (Scope) 的存取權杖 (Access token)。權限範圍 (Scope) 代表使用者被授予的權限。 -[Logto](https://logto.io) 透過 API 資源 (API resources)（符合 [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)）與角色 (Roles) 功能支援 RBAC。設定方式如下： +[Logto](https://logto.io) 透過 API 資源（符合 [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)）與角色 (Roles) 功能支援 RBAC。設定方式如下： 1. 登入 [Logto Console](https://cloud.logto.io)（或你的自架 Logto Console） -2. 建立 API 資源與權限範圍 (Scope)： +2. 建立 API 資源與權限範圍 (Scopes)： - 前往「API 資源」 - 建立名為「Todo Manager」的新 API 資源 - - 新增以下權限範圍 (Scope)： + - 新增以下權限範圍 (Scopes)： - `create:todos`：「建立新待辦事項」 - `read:todos`：「讀取所有待辦事項」 - `delete:todos`：「刪除任一待辦事項」 @@ -95,33 +96,33 @@ sequenceDiagram - 在「角色」分頁指派角色（建議） - 或直接在「權限」分頁指派權限範圍 -這些權限範圍 (Scope) 會以空格分隔字串的形式包含在 JWT 存取權杖 (Access token) 的 `scope` 宣告 (Claim) 中。 +這些權限範圍 (Scopes) 會以空格分隔字串的形式包含在 JWT 存取權杖 (Access token) 的 `scope` 宣告 (Claim) 中。 -OAuth 2.0 / OIDC 簽發者 (Issuer) 通常支援基於權限範圍 (Scope) 的存取控制。實作 RBAC 時： +OAuth 2.0 / OIDC 提供者通常支援基於權限範圍 (Scope) 的存取控制。實作 RBAC 時： -1. 在授權伺服器中定義所需權限範圍 (Scope) -2. 設定用戶端於授權流程中請求這些權限範圍 +1. 在授權伺服器中定義所需的權限範圍 (Scopes) +2. 設定用戶端在授權流程中請求這些權限範圍 3. 確保授權伺服器將授予的權限範圍包含在存取權杖 (Access token) 中 4. 權限範圍通常會包含在 JWT 存取權杖的 `scope` 宣告 (Claim) 中 -請查閱你的簽發者 (Issuer) 文件以瞭解： +請參閱你的提供者文件以瞭解： -- 如何定義與管理權限範圍 (Scope) -- 權限範圍如何包含於存取權杖 (Access token) +- 如何定義與管理權限範圍 (Scopes) +- 權限範圍如何包含在存取權杖中 - 是否有額外的 RBAC 功能如角色管理 -### 權杖驗證與權限檢查 \{#validating-tokens-and-checking-permissions} +### 權杖驗證與權限檢查 (Validating tokens and checking permissions) \{#validating-tokens-and-checking-permissions} 根據最新 MCP 規範，MCP 伺服器在 OAuth 2.0 架構中作為 **資源伺服器 (Resource Server)**。作為資源伺服器，MCP 伺服器有以下職責： 1. **權杖驗證**：驗證從 MCP 用戶端收到的存取權杖 (Access token) 的真實性與完整性 -2. **權限範圍 (Scope) 強制執行**：從存取權杖中擷取並驗證權限範圍，以判斷用戶端被授權執行哪些操作 +2. **權限範圍執行**：從存取權杖中擷取並驗證權限範圍 (Scope)，以判斷用戶端被授權執行哪些操作 3. **資源保護**：僅在用戶端提供有效且具備足夠權限的權杖時，才提供受保護資源（執行工具） 當 MCP 伺服器收到請求時，會執行以下驗證流程： @@ -129,9 +130,9 @@ OAuth 2.0 / OIDC 簽發者 (Issuer) 通常支援基於權限範圍 (Scope) 的 1. 從 `Authorization` 標頭擷取存取權杖（Bearer 權杖格式） 2. 驗證存取權杖的簽章與有效期限 3. 從已驗證的權杖中擷取權限範圍與使用者資訊 -4. 檢查權杖是否具備執行該操作所需的權限範圍 +4. 檢查權杖是否具備執行請求操作所需的權限範圍 -例如，若使用者要建立新待辦事項，其存取權杖必須包含 `create:todos` 權限範圍。以下為資源伺服器驗證流程： +例如，若使用者要建立新待辦事項，其存取權杖必須包含 `create:todos` 權限範圍。以下為資源伺服器驗證流程圖： ```mermaid sequenceDiagram @@ -141,7 +142,7 @@ sequenceDiagram Client->>Server: 夾帶存取權杖的請求
(Authorization: Bearer ) - alt JWT 驗證（推薦） + alt JWT 驗證（建議） Server->>Auth: 取得 JWKS（若未快取） Auth-->>Server: 回傳 JWKS Server->>Server: 本地驗證 JWT 簽章與宣告 @@ -156,23 +157,23 @@ sequenceDiagram Server->>Server: 執行請求操作 Server->>Client: 回傳操作結果 else 欠缺所需權限範圍 - Server->>Client: 回傳 403 禁止
(insufficient_scope error) + Server->>Client: 回傳 403 禁止存取
(insufficient_scope error) end ``` ### 動態用戶端註冊 (Dynamic Client Registration) \{#dynamic-client-registration} -本教學不強制使用動態用戶端註冊，但若你想自動化 MCP 用戶端註冊流程，這會很有幫助。詳情請參閱 [動態用戶端註冊是否必要？](/provider-list#is-dcr-required)。 +本教學不需動態用戶端註冊，但若你想自動化 MCP 用戶端在授權伺服器的註冊流程，可參考 [動態用戶端註冊是否必要？](/provider-list#is-dcr-required) 以取得更多資訊。 -## 瞭解待辦事項管理器中的 RBAC \{#understand-rbac-in-todo-manager} +## 瞭解待辦事項管理器中的 RBAC (Understand RBAC in todo manager) \{#understand-rbac-in-todo-manager} -為了示範，我們會在待辦事項管理器 MCP 伺服器中實作一個簡單的角色型存取控制 (RBAC) 系統。這將讓你瞭解 RBAC 的基本原理，同時保持實作簡潔。 +為了示範，我們會在待辦事項管理器 MCP 伺服器中實作一個簡單的角色型存取控制 (RBAC) 系統。這將讓你瞭解 RBAC 的基本原理，同時保持實作簡單明瞭。 :::note -雖然本教學以 RBAC 為例說明權限範圍 (Scope) 管理，但並非所有驗證 (Authentication) 簽發者 (Issuer) 都透過角色來管理權限範圍。有些簽發者可能有自己獨特的存取控制與權限管理機制。 +雖然本教學以 RBAC 為例進行權限範圍管理，但並非所有驗證 (Authentication) 提供者都透過角色 (Role) 來管理權限範圍 (Scope)。有些提供者可能有自己獨特的存取控制與權限管理機制。 ::: -### 工具與權限範圍 (Scope) \{#tools-and-scopes} +### 工具與權限範圍 (Tools and scopes) \{#tools-and-scopes} 我們的待辦事項管理器 MCP 伺服器提供三個主要工具： @@ -180,27 +181,27 @@ sequenceDiagram - `get-todos`：列出所有待辦事項 - `delete-todo`：依 ID 刪除待辦事項 -為控管這些工具的存取，我們定義以下權限範圍 (Scope)： +為控管這些工具的存取，我們定義以下權限範圍 (Scopes)： - `create:todos`：允許建立新待辦事項 - `delete:todos`：允許刪除現有待辦事項 -- `read:todos`：允許查詢並取得所有待辦事項清單 +- `read:todos`：允許查詢並取得所有待辦事項列表 -### 角色與權限 \{#roles-and-permissions} +### 角色與權限 (Roles and permissions) \{#roles-and-permissions} -我們將定義兩個不同存取層級的角色： +我們將定義兩種不同存取層級的角色： -| 角色 | create:todos | read:todos | delete:todos | -| ------ | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | +| 角色 (Role) | create:todos | read:todos | delete:todos | +| ----------- | ------------ | ---------- | ------------ | +| Admin | ✅ | ✅ | ✅ | +| User | ✅ | | | -- **User**：一般使用者，可建立待辦事項，且僅能檢視或刪除自己的待辦事項 +- **User**：一般使用者，可建立待辦事項，僅能檢視或刪除自己的待辦事項 - **Admin**：管理員，可建立、檢視並刪除所有待辦事項，不論擁有者為誰 -### 資源擁有權 \{#resource-ownership} +### 資源擁有權 (Resource ownership) \{#resource-ownership} -雖然上表明確列出每個角色被指派的權限範圍 (Scope)，但還有一個重要的資源擁有權原則： +雖然上表明確列出每個角色被指派的權限範圍 (Scopes)，但還有一個重要的資源擁有權原則： - **User** 沒有 `read:todos` 或 `delete:todos` 權限範圍，但仍可： - 讀取自己的待辦事項 @@ -209,29 +210,29 @@ sequenceDiagram - 檢視系統中所有待辦事項 - 刪除任何待辦事項，不論擁有者 -這展現了 RBAC 系統中常見的模式：資源擁有權會隱含授予使用者對自己資源的權限，而管理角色則獲得對所有資源的明確權限。 +這展現了 RBAC 系統中常見的模式：資源擁有權會隱含授予使用者對自己資源的操作權限，而管理員角色則獲得對所有資源的明確權限。 -:::tip 進一步瞭解 -想深入瞭解 RBAC 概念與最佳實踐，請參閱 [精通 RBAC：完整實務範例](https://blog.logto.io/mastering-rbac)。 +:::tip 深入學習 +想更深入瞭解 RBAC 概念與最佳實踐，請參閱 [Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac)。 ::: -## 在你的簽發者 (Issuer) 中設定授權 (Authorization) \{#configure-authorization-in-your-provider} +## 在你的提供者中設定授權 (Configure authorization in your provider) \{#configure-authorization-in-your-provider} -要實作上述存取控制系統，你需要在授權伺服器中設定所需的權限範圍 (Scope)。以下說明不同簽發者的設定方式： +要實作上述存取控制系統，你需要在授權伺服器中設定所需的權限範圍 (Scopes)。以下為不同提供者的設定方式： -[Logto](https://logto.io) 透過 API 資源 (API resources) 與角色 (Roles) 功能支援 RBAC。設定方式如下： +[Logto](https://logto.io) 透過 API 資源與角色 (Roles) 功能支援 RBAC。設定方式如下： 1. 登入 [Logto Console](https://cloud.logto.io)（或你的自架 Logto Console） -2. 建立 API 資源與權限範圍 (Scope)： +2. 建立 API 資源與權限範圍 (Scopes)： - 前往「API 資源」 - - 建立名為「Todo Manager」的新 API 資源，並將 `http://localhost:3001` 設為資源標示符 (Resource indicator)。 - - **重要**：資源標示符必須與你的 MCP 伺服器 URL 相符。本教學使用 `http://localhost:3001`，因 MCP 伺服器運行於 3001 埠。正式環境請使用實際 MCP 伺服器 URL（如 `https://your-mcp-server.example.com`）。 - - 建立以下權限範圍 (Scope)： + - 建立名為「Todo Manager」的新 API 資源，並將 `http://localhost:3001/` 設為資源標示符 (Resource indicator)。 + - **重要**：資源標示符必須與你的 MCP 伺服器 URL 相符。本教學使用 `http://localhost:3001/`，因 MCP 伺服器運行於 3001 埠。正式環境請使用實際 MCP 伺服器 URL（如 `https://your-mcp-server.example.com/`）。 + - 建立以下權限範圍 (Scopes)： - `create:todos`：「建立新待辦事項」 - `read:todos`：「讀取所有待辦事項」 - `delete:todos`：「刪除任一待辦事項」 @@ -241,11 +242,11 @@ sequenceDiagram - 前往「角色」 - 建立「Admin」角色並指派所有權限範圍（`create:todos`、`read:todos`、`delete:todos`） - 建立「User」角色並僅指派 `create:todos` 權限範圍 - - 在「User」角色詳細頁切換到「一般」分頁，將「User」設為「預設角色」 + - 在「User」角色詳細頁切換到「一般」分頁，將「User」設為「預設角色 (Default role)」 4. 管理使用者角色與權限： - 新使用者： - - 由於已設為預設角色，將自動獲得「User」角色 + - 會自動取得「User」角色（因已設為預設角色） - 現有使用者： - 前往「使用者管理」 - 選擇一位使用者 @@ -255,14 +256,14 @@ sequenceDiagram 你也可以使用 Logto 的 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) 以程式方式管理使用者角色。這對自動化使用者管理或建立管理後台特別有用。 ::: -請求存取權杖時，Logto 會根據使用者角色權限將權限範圍 (Scope) 包含於權杖的 `scope` 宣告 (Claim) 中。 +請求存取權杖時，Logto 會根據使用者角色權限將權限範圍 (Scopes) 包含於權杖的 `scope` 宣告中。 -對於 OAuth 2.0 或 OpenID Connect 簽發者 (Issuer)，你需要設定代表不同權限的權限範圍 (Scope)。具體步驟依簽發者而異，但一般流程如下： +對於 OAuth 2.0 或 OpenID Connect 提供者，你需設定代表不同權限的權限範圍 (Scopes)。具體步驟依提供者而異，但一般流程如下： -1. 定義權限範圍 (Scope)： +1. 定義權限範圍 (Scopes)： - 設定授權伺服器支援： - `create:todos` @@ -272,31 +273,35 @@ sequenceDiagram 2. 設定用戶端： - 註冊或更新用戶端以請求這些權限範圍 - - 確保權限範圍包含於存取權杖 + - 確保權限範圍包含於存取權杖中 3. 指派權限： - - 透過簽發者介面將適當權限範圍指派給使用者 - - 有些簽發者支援基於角色的管理，有些則直接指派權限範圍 - - 請查閱簽發者文件以瞭解建議做法 + - 透過提供者介面將適當權限範圍指派給使用者 + - 有些提供者支援基於角色的管理，有些則直接指派權限範圍 + - 請參閱提供者文件以取得建議做法 :::tip -大多數簽發者會將授予的權限範圍包含於存取權杖的 `scope` 宣告 (Claim) 中，格式通常為空格分隔的權限範圍字串。 +大多數提供者會將授予的權限範圍包含於存取權杖的 `scope` 宣告中，格式通常為空格分隔的字串。 ::: -設定好授權伺服器後，使用者將取得包含其授權權限範圍的存取權杖。MCP 伺服器會根據這些權限範圍判斷： +:::note[資源標示符結尾斜線] +資源標示符 (Resource indicator) 請務必加上結尾斜線（`/`）。由於 MCP 官方 SDK 目前有個 bug，使用該 SDK 的用戶端在發起驗證請求時會自動於資源標示符後加上斜線。若你的資源標示符未包含斜線，這些用戶端的資源驗證將失敗。（VS Code 不受此 bug 影響。） +::: + +設定好授權伺服器後，使用者將取得包含其權限範圍的存取權杖。MCP 伺服器會根據這些權限範圍判斷： - 使用者是否能建立新待辦事項（`create:todos`） -- 使用者是否能檢視所有待辦事項（`read:todos`）或僅能檢視自己的 -- 使用者是否能刪除任一待辦事項（`delete:todos`）或僅能刪除自己的 +- 使用者能否檢視所有待辦事項（`read:todos`）或僅能檢視自己的 +- 使用者能否刪除任一待辦事項（`delete:todos`）或僅能刪除自己的 -## 建立 MCP 伺服器 \{#set-up-the-mcp-server} +## 建立 MCP 伺服器 (Set up the MCP server) \{#set-up-the-mcp-server} 我們將使用 [MCP 官方 SDK](https://github.com/modelcontextprotocol) 來建立待辦事項管理器 MCP 伺服器。 -### 建立新專案 \{#create-a-new-project} +### 建立新專案 (Create a new project) \{#create-a-new-project} 建立新的 Node.js 專案： @@ -310,10 +315,10 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -我們的範例使用 TypeScript，因為 Node.js v22.6.0+ 原生支援 `--experimental-strip-types` 直接執行 TypeScript。若你使用 JavaScript，程式碼大致相同，只需確保 Node.js 版本為 v22.6.0 或以上。詳情請參閱 Node.js 官方文件。 +我們範例中使用 TypeScript，因 Node.js v22.6.0+ 原生支援 `--experimental-strip-types` 執行 TypeScript。若你使用 JavaScript，程式碼大致相同，只需確保 Node.js 版本為 v22.6.0 或以上。詳情請參閱 Node.js 文件。 ::: -### 安裝 MCP SDK 與相依套件 \{#install-the-mcp-sdk-and-dependencies} +### 安裝 MCP SDK 與相依套件 (Install the MCP SDK and dependencies) \{#install-the-mcp-sdk-and-dependencies} ```bash npm install @modelcontextprotocol/sdk express zod @@ -321,11 +326,11 @@ npm install @modelcontextprotocol/sdk express zod 或使用你偏好的套件管理工具，如 `pnpm` 或 `yarn`。 -### 建立 MCP 伺服器 \{#create-the-mcp-server} +### 建立 MCP 伺服器 (Create the MCP server) \{#create-the-mcp-server} 建立名為 `todo-manager.ts` 的檔案並加入以下程式碼： -（原始程式碼略，請參考英文內容） +（原始程式碼略，請參考原文） 啟動伺服器： @@ -333,68 +338,30 @@ npm install @modelcontextprotocol/sdk express zod npm start ``` -## 檢查 MCP 伺服器 \{#inspect-the-mcp-server} - -### 下載並執行 MCP inspector \{#clone-and-run-mcp-inspector} - -現在 MCP 伺服器已啟動，我們可以使用 MCP inspector 檢查工具是否可用。 - -官方 MCP inspector v0.16.2 有些 bug 會影響驗證 (Authentication) 功能。為解決這些問題，我們建立了 [修正版 MCP inspector](https://github.com/mcp-auth/inspector/tree/patch/0.16.2-fixes)，已包含 OAuth / OIDC 驗證流程所需修正。我們也已向官方 repo 提交 PR。 - -執行 MCP inspector： - -```bash -git clone https://github.com/mcp-auth/inspector.git -b patch/0.16.2-fixes -cd inspector -npm install -npm run dev -``` - -MCP inspector 會自動在預設瀏覽器開啟，或你也可以手動點擊終端機輸出的連結（請點帶有 `MCP_PROXY_AUTH_TOKEN` 參數的連結，如 `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=458ae4a4...acab1907`）。 - -### 連接 MCP inspector 至 MCP 伺服器 \{#connect-mcp-inspector-to-the-mcp-server} - -請先確認 MCP inspector 的以下設定： - -- **Transport Type**：設為 `Streamable HTTP` -- **URL**：設為你的 MCP 伺服器 URL，本例為 `http://localhost:3001` - -現在你可以點擊「Connect」按鈕，檢查 MCP inspector 是否能連線至 MCP 伺服器。若一切正常，MCP inspector 會顯示「Connected」狀態。 - -### 檢查點：執行待辦事項管理工具 \{#checkpoint-run-todo-manager-tools} - -1. 在 MCP inspector 上方選單點選「Tools」分頁 -2. 點擊「List Tools」按鈕 -3. 你應該會看到 `create-todo`、`get-todos`、`delete-todo` 工具列在頁面上，點擊可檢視工具詳情 -4. 右側會有「Run Tool」按鈕，點擊並輸入必要參數執行工具 -5. 你會看到工具回傳的 JSON 結果 `{"error": "Not implemented"}` - -![MCP inspector 首次執行畫面](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## 與授權伺服器整合 \{#integrate-with-your-authorization-server} +## 與授權伺服器整合 (Integrate with your authorization server) \{#integrate-with-your-authorization-server} 完成本節需考慮以下幾點：
-**你的授權伺服器簽發者 (Issuer) URL** +**你的授權伺服器的簽發者 (Issuer) URL** -通常是你的授權伺服器基底 URL，如 `https://auth.example.com`。有些服務商可能是 `https://example.logto.app/oidc`，請查閱你的簽發者 (Issuer) 文件。 +通常是授權伺服器的基礎 URL，例如 `https://auth.example.com`。有些提供者可能為 `https://example.logto.app/oidc`，請參閱提供者文件確認。
**如何取得授權伺服器中繼資料** -- 若你的授權伺服器符合 [OAuth 2.0 授權伺服器中繼資料](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，可用 MCP Auth 內建工具自動取得中繼資料 -- 若不符合，需手動指定中繼資料 URL 或端點於 MCP 伺服器設定，詳情請查閱簽發者 (Issuer) 文件 +- 若授權伺服器符合 [OAuth 2.0 授權伺服器中繼資料](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，可用 MCP Auth 內建工具自動取得中繼資料。 +- 若不符合上述標準，需手動於 MCP 伺服器設定中指定中繼資料 URL 或端點。請參閱提供者文件。
-**如何將 MCP inspector 註冊為用戶端** +**如何在授權伺服器註冊 MCP 用戶端** -- 若你的授權伺服器支援 [動態用戶端註冊 (Dynamic Client Registration)](https://datatracker.ietf.org/doc/html/rfc7591)，MCP inspector 會自動註冊為用戶端 -- 若不支援，需手動將 MCP inspector 註冊為用戶端 +- 若授權伺服器支援 [動態用戶端註冊 (Dynamic Client Registration)](https://datatracker.ietf.org/doc/html/rfc7591)，可略過此步驟，MCP 用戶端會自動註冊。 +- 若不支援，需手動在授權伺服器註冊 MCP 用戶端。
@@ -403,22 +370,22 @@ MCP inspector 會自動在預設瀏覽器開啟，或你也可以手動點擊終 向不同授權伺服器請求存取權杖時，指定目標資源與權限的方式可能不同，主要有： -- **基於資源標示符 (Resource indicator)**： +- **基於資源標示符 (Resource indicator based)**： - 使用 `resource` 參數指定目標 API（參見 [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)） - 現代 OAuth 2.0 常見 - 範例請求： ```json { - "resource": "http://localhost:3001", + "resource": "http://localhost:3001/", "scope": "create:todos read:todos" } ``` - 伺服器會發出專屬於該資源的權杖 -- **基於受眾 (Audience)**： +- **基於受眾 (Audience based)**： - - 使用 `audience` 參數指定權杖預期接收者 + - 使用 `audience` 參數指定權杖接收者 - 與資源標示符類似但語意不同 - 範例請求： ```json @@ -428,8 +395,8 @@ MCP inspector 會自動在預設瀏覽器開啟，或你也可以手動點擊終 } ``` -- **純權限範圍 (Scope) 型**： - - 僅依權限範圍，不帶 resource / audience 參數 +- **純權限範圍 (Pure scope based)**： + - 僅依賴權限範圍，不帶 resource/audience 參數 - 傳統 OAuth 2.0 作法 - 範例請求： ```json @@ -437,107 +404,110 @@ MCP inspector 會自動在預設瀏覽器開啟，或你也可以手動點擊終 "scope": "todo-api:create todo-api:read openid profile" } ``` - - 常以前綴命名空間權限範圍 - - 簡單 OAuth 2.0 實作常見 + - 常見於簡單 OAuth 2.0 實作，會用前綴命名空間 + - ... :::tip 最佳實踐 -- 查閱你的簽發者 (Issuer) 文件以確認支援哪些參數 -- 有些服務同時支援多種方式 -- 資源標示符有助於提升安全性與存取控管 -- 建議優先使用資源標示符 +- 請參閱提供者文件以確認支援哪些參數 +- 有些提供者同時支援多種方式 +- 資源標示符可提升安全性（限制受眾） +- 若可用，建議優先使用資源標示符以加強存取控管 ::: -雖然每個簽發者 (Issuer) 可能有不同要求，以下步驟可協助你整合 MCP inspector 與 MCP 伺服器，並進行服務商專屬設定。 +每個提供者可能有不同需求，以下步驟將指引你如何依提供者設定 VS Code 與 MCP 伺服器。 -### 註冊 MCP inspector 為用戶端 \{#register-mcp-inspector-as-a-client} +### 註冊 MCP 用戶端為第三方應用 (Register MCP client as a third-party app) \{#register-mcp-client-as-a-third-party-app} -將待辦事項管理器整合至 [Logto](https://logto.io) 很簡單，因為它是支援資源標示符與權限範圍的 OpenID Connect 簽發者 (Issuer)，可用 `http://localhost:3001` 作為資源標示符保護你的 todo API。 - -由於 Logto 尚未支援動態用戶端註冊，你需手動將 MCP inspector 註冊為用戶端： - -1. 開啟 MCP inspector，進入驗證 (Authentication) 設定，點選「OAuth2.0 Flow」設定，複製 **Redirect URI**，如 `http://localhost:6274/oauth/callback` -2. 登入 [Logto Console](https://cloud.logto.io)（或你的自架 Logto Console） -3. 前往「應用程式」分頁，點選「建立應用程式」，頁面底部點「不選框架建立應用程式」 -4. 填寫應用程式資訊後點「建立應用程式」： - - **選擇應用程式類型**：選「單頁應用程式」 - - **應用程式名稱**：如「MCP Inspector」 -5. 在「設定 / Redirect URIs」區塊貼上剛才複製的 **Redirect URI**，然後點底部「儲存變更」 -6. 頁面上方會看到「App ID」，請複製 -7. 回到 MCP inspector，將「App ID」貼到驗證 (Authentication) 設定的「OAuth2.0 Flow」下的「Client ID」欄位 -8. 在「Scope」欄位輸入：`create:todos read:todos delete:todos`，確保 Logto 回傳的存取權杖包含操作 todo manager 所需權限範圍 +將待辦事項管理器整合至 [Logto](https://logto.io) 非常簡單，因其為支援資源標示符與權限範圍的 OpenID Connect 提供者，可用 `http://localhost:3001/` 作為資源標示符保護你的 todo API。 + +由於 Logto 尚未支援動態用戶端註冊，你需手動將 MCP 用戶端（VS Code）註冊為 Logto 租戶的第三方應用： + +1. 登入 [Logto Console](https://cloud.logto.io)（或你的自架 Logto Console）。 +2. 前往 **應用程式 > 第三方應用** 並點擊「建立應用程式」。 +3. 選擇 **原生應用 (Native App)** 作為應用程式類型。 +4. 填寫應用程式資訊： + - **應用程式名稱**：如 "MCP Client" + - **描述**：如 "MCP client for VS Code" +5. 為 VS Code 設定以下 **Redirect URI**： + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` +6. 點擊「儲存變更」。 +7. 前往應用程式的 **權限** 分頁，在 **User** 區段，新增你先前建立的 **Todo Manager** API 資源中的 `create:todos`、`read:todos`、`delete:todos` 權限。 +8. 在頂部卡片可看到「App ID」，請複製以備後用。 :::note -這是通用 OAuth 2.0 / OpenID Connect 簽發者 (Issuer) 整合指引。兩者步驟類似，因 OIDC 建立於 OAuth 2.0 之上。請查閱你的簽發者 (Issuer) 文件以獲得細節。 +這是通用的 OAuth 2.0 / OpenID Connect 提供者整合指引。兩者步驟類似，因 OIDC 建立於 OAuth 2.0 之上。請參閱你的提供者文件以取得細節。 ::: -若你的服務支援動態用戶端註冊，可直接跳至第 8 步設定 MCP inspector；否則需手動註冊： +若你的提供者支援動態用戶端註冊，可略過手動註冊；否則需手動註冊 MCP 用戶端： -1. 開啟 MCP inspector，進入驗證 (Authentication) 設定，點選「OAuth2.0 Flow」設定，複製 **Redirect URI**，如 `http://localhost:6274/oauth/callback` +1. 登入提供者管理後台。 -2. 登入你的服務商管理後台 +2. 前往「應用程式」或「用戶端」區，建立新應用程式或用戶端。 -3. 前往「應用程式」或「用戶端」區塊，建立新應用程式或用戶端 +3. 若需選擇用戶端類型，請選「原生應用 (Native App)」或「公開用戶端 (Public client)」。 -4. 若需選擇用戶端類型，請選「單頁應用程式」或「公開用戶端」 +4. 建立應用程式後，設定 Redirect URI。對 VS Code，請新增： -5. 建立應用程式後，需設定 redirect URI，貼上剛才複製的 **Redirect URI** + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` -6. 找到新應用程式的「Client ID」或「Application ID」並複製 +5. 設定應用程式所需權限範圍： -7. 回到 MCP inspector，將「Client ID」貼到驗證 (Authentication) 設定的「OAuth2.0 Flow」下的「Client ID」欄位 + ```text + create:todos read:todos delete:todos + ``` -8. 在「Scope」欄位輸入以下權限範圍以請求 todo 操作所需權限： - -```text -create:todos read:todos delete:todos -``` +6. 找到新應用程式的「Client ID」或「Application ID」並複製備用。 -### 設定 MCP Auth \{#set-up-mcp-auth} +### 設定 MCP Auth (Set up MCP Auth) \{#set-up-mcp-auth} 首先，在 MCP 伺服器專案中安裝 MCP Auth SDK。 -import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; - -接著初始化 MCP Auth。以受保護資源模式，你需設定資源中繼資料（包含授權伺服器）。 +接著初始化 MCP Auth。以受保護資源模式，你需設定資源中繼資料 (Resource metadata)，包含授權伺服器資訊。 -有兩種設定方式： +有兩種設定授權伺服器的方式： -- **預先取得（推薦）**：用 `fetchServerConfig()` 於啟動時預先取得中繼資料，確保設定有效 -- **隨需探索**：僅提供 `issuer` 與 `type`，首次需要時才取得中繼資料，適合不允許頂層 async fetch 的 edge runtime（如 Cloudflare Workers） +- **預先取得（建議）**：用 `fetchServerConfig()` 於初始化前取得中繼資料，確保啟動時即驗證設定。 +- **隨需探索**：僅提供 `issuer` 與 `type`，首次需要時才取得中繼資料。適用於無法在頂層 async fetch 的環境（如 Cloudflare Workers）。 -#### 設定受保護資源中繼資料 \{#configure-protected-resource-metadata} +#### 設定受保護資源中繼資料 (Configure protected resource metadata) \{#configure-protected-resource-metadata} -首先取得你的授權伺服器簽發者 (Issuer) URL： +首先，取得授權伺服器的簽發者 (Issuer) URL： -在 Logto，可於 Logto Console 應用程式詳情頁「Endpoints & Credentials / Issuer endpoint」區塊找到簽發者 (Issuer) URL，格式如 `https://my-project.logto.app/oidc`。 +在 Logto，可於 Logto Console 的應用程式詳細頁「端點與憑證 / Issuer endpoint」區找到 issuer URL，格式如 `https://my-project.logto.app/oidc`。 -對於 OAuth 2.0 簽發者 (Issuer)： +對於 OAuth 2.0 提供者： -1. 查閱服務商文件取得授權伺服器 URL（常稱 issuer URL 或 base URL） -2. 有些服務會在 `https://{your-domain}/.well-known/oauth-authorization-server` 提供 -3. 也可於管理後台 OAuth / API 設定區查找 +1. 請參閱提供者文件取得授權伺服器 URL（常稱 issuer URL 或 base URL） +2. 有些提供者會在 `https://{your-domain}/.well-known/oauth-authorization-server` 提供 +3. 也可於管理後台 OAuth / API 設定中查找 @@ -545,29 +515,27 @@ import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; 現在，於建立 MCP Auth 實例時設定受保護資源中繼資料： -（原始程式碼略，請參考英文內容） +（原始程式碼略，請參考原文） -### 更新 MCP 伺服器 \{#update-mcp-server} +### 更新 MCP 伺服器 (Update MCP server) \{#update-mcp-server} -快完成了！現在要將 MCP Auth 路由與中介軟體 (middleware) 套用到 MCP 伺服器，並根據使用者權限範圍 (Scope) 實作待辦事項工具的權限控管。 +快完成了！現在要將 MCP Auth 路由與中介軟體 (middleware) 套用到 MCP 伺服器，並根據使用者權限範圍實作待辦事項工具的權限控管。 -首先，套用受保護資源中繼資料路由，讓 MCP 用戶端可從 MCP 伺服器取得預期的資源中繼資料。 +首先，套用受保護資源中繼資料路由，讓 MCP 用戶端能從 MCP 伺服器取得資源中繼資料。 -（原始程式碼略，請參考英文內容） +（原始程式碼略，請參考原文） -接著，套用 MCP Auth 中介軟體。這個中介軟體會處理進入請求的驗證 (Authentication) 與授權 (Authorization)，確保只有授權使用者能存取待辦事項工具。 +接著，套用 MCP Auth 中介軟體，處理進入請求的驗證 (Authentication) 與授權 (Authorization)，確保只有授權使用者能存取待辦事項工具。 -（原始程式碼略，請參考英文內容） +（原始程式碼略，請參考原文） -現在可以更新待辦事項工具的實作，讓其利用 MCP Auth 中介軟體進行驗證 (Authentication) 與授權 (Authorization)。 +現在可以更新待辦事項工具的實作，讓其利用 MCP Auth 中介軟體進行驗證與授權。 -（原始程式碼略，請參考英文內容） +（原始程式碼略，請參考原文） 最後，建立上述程式碼中用到的「Todo service」： -建立 `todo-service.ts` 檔案： - -（原始程式碼略，請參考英文內容） +（原始程式碼略，請參考原文） 恭喜！你已成功實作一個具備驗證 (Authentication) 與授權 (Authorization) 的完整 MCP 伺服器！ @@ -575,11 +543,19 @@ import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; 完整 MCP 伺服器（OIDC 版本）程式碼請參考 [MCP Auth Node.js SDK repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。 ::: -## 檢查點：執行 `todo-manager` 工具 \{#checkpoint-run-the-todo-manager-tools} +## 檢查點：執行 `todo-manager` 工具 (Checkpoint: Run the `todo-manager` tools) \{#checkpoint-run-the-todo-manager-tools} + +重啟 MCP 伺服器並用 VS Code 連線。連線並驗證的步驟如下： -重啟 MCP 伺服器並於瀏覽器開啟 MCP inspector。點擊「Connect」後，應會被導向授權伺服器登入頁。 +1. 在 VS Code 按下 `Command + Shift + P`（macOS）或 `Ctrl + Shift + P`（Windows / Linux）開啟命令面板 +2. 輸入 `MCP: Add Server...` 並選擇 +3. 選擇 `HTTP` 作為伺服器類型 +4. 輸入 MCP 伺服器 URL：`http://localhost:3001` +5. 啟動 OAuth 請求後，VS Code 會提示你輸入 **App ID**，請輸入你從授權伺服器複製的 App ID +6. 因為沒有 **App Secret**（屬於公開用戶端），直接按 Enter 跳過 +7. 在瀏覽器完成登入流程 -登入並返回 MCP inspector 後，重複前述步驟執行待辦事項工具。這次你將以已驗證的使用者身分操作，工具行為會依你被指派的角色與權限而異： +登入並返回 VS Code 後，重複前一檢查點的操作以執行待辦事項工具。這次你將以已驗證的使用者身分使用這些工具，工具行為將依你被指派的角色與權限而異： - 若以 **User**（僅有 `create:todos` 權限範圍）登入： @@ -594,25 +570,23 @@ import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; 你可以這樣測試不同權限層級： -1. 登出當前帳號（點 MCP inspector 的「Disconnect」） -2. 以不同角色／權限的帳號登入 -3. 重複操作觀察工具行為如何隨使用者權限改變 - -這展現了角色型存取控制 (RBAC) 的實際運作，不同使用者可存取系統不同功能。 +1. 斷開 MCP 伺服器連線（於 VS Code 移除伺服器設定） +2. 以不同角色 / 權限的帳號重新登入 +3. 再次嘗試相同工具，觀察行為如何隨使用者權限變化 -![MCP inspector todo manager 工具結果](/docs-assets/images/tutorials/todo-manager/result.png) +這展現了角色型存取控制 (RBAC) 的實際運作，不同使用者對系統功能有不同存取層級。 :::info 完整 MCP 伺服器（OIDC 版本）程式碼請參考 [MCP Auth Node.js SDK repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。 ::: -## 結語 \{#closing-notes} +## 結語 (Closing notes) \{#closing-notes} 恭喜！你已順利完成本教學。讓我們回顧一下： -- 建立具備待辦事項管理工具（`create-todo`、`get-todos`、`delete-todo`）的基本 MCP 伺服器 +- 建立具備待辦事項工具（`create-todo`、`get-todos`、`delete-todo`）的基本 MCP 伺服器 - 實作使用者與管理員不同權限層級的角色型存取控制 (RBAC) - 透過 MCP Auth 將 MCP 伺服器與授權伺服器整合 -- 設定 MCP Inspector 以驗證使用者並用帶有權限範圍的存取權杖呼叫工具 +- 設定 VS Code 以驗證使用者並用帶有權限範圍的存取權杖呼叫工具 -歡迎參閱其他教學與文件，充分發揮 MCP Auth 的強大功能。 +歡迎參閱其他教學與文件，充分發揮 MCP Auth 的強大功能。 \ No newline at end of file